return concrete types of Claims, using generics

[muhlemmer]

This change proposes the use of concrete struct types for Claims and descendant types, instead of interfaces. By usage of generics, we can let callers replace the standard types with custom type that carry additional properties. This would be a breaking change for the next branch.

rp package

In the rp package the following function will change their signature:

func VerifyTokens[C oidc.AccessTokenHashGetter](ctx context.Context, accessToken, idTokenString string, v IDTokenVerifier) (claims C, err error)
func VerifyIDToken[C oidc.Claims](ctx context.Context, token string, v IDTokenVerifier) (claims C, err error)

op package

In the op package the following functions will change their signature:

func VerifyIDTokenHint[C oidc.Claims](ctx context.Context, token string, v IDTokenHintVerifier) (claims C, err error)
func VerifyAccessToken[C oidc.Claims](ctx context.Context, token string, v AccessTokenVerifier) (claims C, err error)

oidc package

Above type parameters between square brackets ([]) define the minimum set of methods required to check validity of token claims. Aka, constraints. The existing Claims interfaces will be reused and supplemented with 2 methods:

1. GetSignatureAlgorithm() jose.SignatureAlgorithm migrated from IDTokenClaims
2. SetSignatureAlgorithm(jose.SignatureAlgorithm) migrated from ClaimsSignature

Although both methods are not required in all use-cases of Claims all the current existing implementations of Claims currently carry the signatureAlg field.

A new interface AccessTokenHashClaims with the GetAccessTokenHash() string method migrated from IDTokenClaims . Finally oidc will carry the following interface definitions, used as constraints:

type Claims interface {
	GetIssuer() string
	GetSubject() string
	GetAudience() []string
	GetExpiration() time.Time
	GetIssuedAt() time.Time
	GetNonce() string
	GetAuthenticationContextClassReference() string
	GetAuthTime() time.Time
	GetAuthorizedParty() string

	// new methods
	GetSignatureAlgorithm() jose.SignatureAlgorithm
	SetSignatureAlgorithm(jose.SignatureAlgorithm)
}

type AccessTokenHashClaims interface {
	Claims
	GetAccessTokenHash() string
}

The following interfaces can now be removed (their names will be reused):

• AccessTokenClaims
• IDTokenClaims
• UserInfo
• UserInfoProfile
• UserInfoEmail
• UserInfoPhone
• UserInfoAddress
• UserInfoSetter
• UserInfoProfileSetter

In place, we will export the currently private struct types by taking the above names.

Example usage

If users want VerifyIDToken to return the predefined IDTokenClaims struct type:

claims, err := VerifyIDToken[*oidc.IDTokenClaims](ctx, token, v)

Or if their token caries additional claims, they can extend the type by struct embedding to gain direct access to those claims:

type customClaims struct {
	oidc.AccessTokenClaims
	Foo string `json:"foo"`
	Bar string `json:"bar"`
}

claims, err := VerifyIDToken[*customClaims](ctx, token, v)

[hifabienne]

@muhlemmer are you working on this? If yes can you please put it into progress?