refactor: use struct types for claim related types (#283)

* oidc: add regression tests for token claim json

this helps to verify that the same JSON is produced,
after these types are refactored.

* refactor: use struct types for claim related types

BREAKING CHANGE:
The following types are changed from interface to struct type:

- AccessTokenClaims
- IDTokenClaims
- IntrospectionResponse
- UserInfo and related types.

The following methods of OPStorage now take a pointer to a struct type,
instead of an interface:

- SetUserinfoFromScopes
- SetUserinfoFromToken
- SetIntrospectionFromToken

The following functions are now generic, so that type-safe extension
of Claims is now possible:

- op.VerifyIDTokenHint
- op.VerifyAccessToken
- rp.VerifyTokens
- rp.VerifyIDToken

- Changed UserInfoAddress to pointer in UserInfo and
IntrospectionResponse.
This was needed to make omitempty work correctly.
- Copy or merge maps in IntrospectionResponse and SetUserInfo

* op: add example for VerifyAccessToken

* fix: rp: wrong assignment in WithIssuedAtMaxAge

WithIssuedAtMaxAge assigned its value to v.maxAge, which was wrong.
This change fixes that by assiging the duration to v.maxAgeIAT.

* rp: add VerifyTokens example

* oidc: add standard references to:

- IDTokenClaims
- IntrospectionResponse
- UserInfo

* only count coverage for `./pkg/...`

example/client/api/api.go

@@ -76,7 +76,7 @@ func main() {
 		params := mux.Vars(r)
 		requestedClaim := params["claim"]
 		requestedValue := params["value"]
-		value, ok := resp.GetClaim(requestedClaim).(string)
+		value, ok := resp.Claims[requestedClaim].(string)
 		if !ok || value == "" || value != requestedValue {
 			http.Error(w, "claim does not match", http.StatusForbidden)
 			return

example/client/app/app.go

@@ -60,7 +60,7 @@ func main() {
 	http.Handle("/login", rp.AuthURLHandler(state, provider))
 
 	// for demonstration purposes the returned userinfo response is written as JSON object onto response
-	marshalUserinfo := func(w http.ResponseWriter, r *http.Request, tokens *oidc.Tokens, state string, rp rp.RelyingParty, info oidc.UserInfo) {
+	marshalUserinfo := func(w http.ResponseWriter, r *http.Request, tokens *oidc.Tokens[*oidc.IDTokenClaims], state string, rp rp.RelyingParty, info *oidc.UserInfo) {
 		data, err := json.Marshal(info)
 		if err != nil {
 			http.Error(w, err.Error(), http.StatusInternalServerError)

example/client/github/github.go

@@ -13,6 +13,7 @@ import (
 	"github.com/zitadel/oidc/v2/pkg/client/rp"
 	"github.com/zitadel/oidc/v2/pkg/client/rp/cli"
 	"github.com/zitadel/oidc/v2/pkg/http"
+	"github.com/zitadel/oidc/v2/pkg/oidc"
 )
 
 var (
@@ -43,7 +44,7 @@ func main() {
 	state := func() string {
 		return uuid.New().String()
 	}
-	token := cli.CodeFlow(ctx, relyingParty, callbackPath, port, state)
+	token := cli.CodeFlow[*oidc.IDTokenClaims](ctx, relyingParty, callbackPath, port, state)
 
 	client := github.NewClient(relyingParty.OAuthConfig().Client(ctx, token.Token))
 

example/server/storage/storage.go

@@ -429,13 +429,13 @@ func (s *Storage) AuthorizeClientIDSecret(ctx context.Context, clientID, clientS
 
 // SetUserinfoFromScopes implements the op.Storage interface
 // it will be called for the creation of an id_token, so we'll just pass it to the private function without any further check
-func (s *Storage) SetUserinfoFromScopes(ctx context.Context, userinfo oidc.UserInfoSetter, userID, clientID string, scopes []string) error {
+func (s *Storage) SetUserinfoFromScopes(ctx context.Context, userinfo *oidc.UserInfo, userID, clientID string, scopes []string) error {
 	return s.setUserinfo(ctx, userinfo, userID, clientID, scopes)
 }
 
 // SetUserinfoFromToken implements the op.Storage interface
 // it will be called for the userinfo endpoint, so we read the token and pass the information from that to the private function
-func (s *Storage) SetUserinfoFromToken(ctx context.Context, userinfo oidc.UserInfoSetter, tokenID, subject, origin string) error {
+func (s *Storage) SetUserinfoFromToken(ctx context.Context, userinfo *oidc.UserInfo, tokenID, subject, origin string) error {
 	token, ok := func() (*Token, bool) {
 		s.lock.Lock()
 		defer s.lock.Unlock()
@@ -463,7 +463,7 @@ func (s *Storage) SetUserinfoFromToken(ctx context.Context, userinfo oidc.UserIn
 
 // SetIntrospectionFromToken implements the op.Storage interface
 // it will be called for the introspection endpoint, so we read the token and pass the information from that to the private function
-func (s *Storage) SetIntrospectionFromToken(ctx context.Context, introspection oidc.IntrospectionResponse, tokenID, subject, clientID string) error {
+func (s *Storage) SetIntrospectionFromToken(ctx context.Context, introspection *oidc.IntrospectionResponse, tokenID, subject, clientID string) error {
 	token, ok := func() (*Token, bool) {
 		s.lock.Lock()
 		defer s.lock.Unlock()
@@ -480,14 +480,17 @@ func (s *Storage) SetIntrospectionFromToken(ctx context.Context, introspection o
 			// this will automatically be done by the library if you don't return an error
 			// you can also return further information about the user / associated token
 			// e.g. the userinfo (equivalent to userinfo endpoint)
-			err := s.setUserinfo(ctx, introspection, subject, clientID, token.Scopes)
+
+			userInfo := new(oidc.UserInfo)
+			err := s.setUserinfo(ctx, userInfo, subject, clientID, token.Scopes)
 			if err != nil {
 				return err
 			}
+			introspection.SetUserInfo(userInfo)
 			//...and also the requested scopes...
-			introspection.SetScopes(token.Scopes)
+			introspection.Scope = token.Scopes
 			//...and the client the token was issued to
-			introspection.SetClientID(token.ApplicationID)
+			introspection.ClientID = token.ApplicationID
 			return nil
 		}
 	}
@@ -608,7 +611,7 @@ func (s *Storage) accessToken(applicationID, refreshTokenID, subject string, aud
 }
 
 // setUserinfo sets the info based on the user, scopes and if necessary the clientID
-func (s *Storage) setUserinfo(ctx context.Context, userInfo oidc.UserInfoSetter, userID, clientID string, scopes []string) (err error) {
+func (s *Storage) setUserinfo(ctx context.Context, userInfo *oidc.UserInfo, userID, clientID string, scopes []string) (err error) {
 	s.lock.Lock()
 	defer s.lock.Unlock()
 	user := s.userStore.GetUserByID(userID)
@@ -618,17 +621,19 @@ func (s *Storage) setUserinfo(ctx context.Context, userInfo oidc.UserInfoSetter,
 	for _, scope := range scopes {
 		switch scope {
 		case oidc.ScopeOpenID:
-			userInfo.SetSubject(user.ID)
+			userInfo.Subject = user.ID
 		case oidc.ScopeEmail:
-			userInfo.SetEmail(user.Email, user.EmailVerified)
+			userInfo.Email = user.Email
+			userInfo.EmailVerified = oidc.Bool(user.EmailVerified)
 		case oidc.ScopeProfile:
-			userInfo.SetPreferredUsername(user.Username)
-			userInfo.SetName(user.FirstName + " " + user.LastName)
-			userInfo.SetFamilyName(user.LastName)
-			userInfo.SetGivenName(user.FirstName)
-			userInfo.SetLocale(user.PreferredLanguage)
+			userInfo.PreferredUsername = user.Username
+			userInfo.Name = user.FirstName + " " + user.LastName
+			userInfo.FamilyName = user.LastName
+			userInfo.GivenName = user.FirstName
+			userInfo.Locale = oidc.NewLocale(user.PreferredLanguage)
 		case oidc.ScopePhone:
-			userInfo.SetPhone(user.Phone, user.PhoneVerified)
+			userInfo.PhoneNumber = user.Phone
+			userInfo.PhoneNumberVerified = user.PhoneVerified
 		case CustomScope:
 			// you can also have a custom scope and assert public or custom claims based on that
 			userInfo.AppendClaims(CustomClaim, customClaim(clientID))
@@ -698,7 +703,7 @@ func (s *Storage) GetPrivateClaimsFromTokenExchangeRequest(ctx context.Context,
 // SetUserinfoFromScopesForTokenExchange implements the op.TokenExchangeStorage interface
 // it will be called for the creation of an id_token - we are using the same private function as for other flows,
 // plus adding token exchange specific claims related to delegation or impersonation
-func (s *Storage) SetUserinfoFromTokenExchangeRequest(ctx context.Context, userinfo oidc.UserInfoSetter, request op.TokenExchangeRequest) error {
+func (s *Storage) SetUserinfoFromTokenExchangeRequest(ctx context.Context, userinfo *oidc.UserInfo, request op.TokenExchangeRequest) error {
 	err := s.setUserinfo(ctx, userinfo, request.GetSubject(), request.GetClientID(), request.GetScopes())
 	if err != nil {
 		return err

example/server/storage/storage_dynamic.go

@@ -198,7 +198,7 @@ func (s *multiStorage) AuthorizeClientIDSecret(ctx context.Context, clientID, cl
 
 // SetUserinfoFromScopes implements the op.Storage interface
 // it will be called for the creation of an id_token, so we'll just pass it to the private function without any further check
-func (s *multiStorage) SetUserinfoFromScopes(ctx context.Context, userinfo oidc.UserInfoSetter, userID, clientID string, scopes []string) error {
+func (s *multiStorage) SetUserinfoFromScopes(ctx context.Context, userinfo *oidc.UserInfo, userID, clientID string, scopes []string) error {
 	storage, err := s.storageFromContext(ctx)
 	if err != nil {
 		return err
@@ -208,7 +208,7 @@ func (s *multiStorage) SetUserinfoFromScopes(ctx context.Context, userinfo oidc.
 
 // SetUserinfoFromToken implements the op.Storage interface
 // it will be called for the userinfo endpoint, so we read the token and pass the information from that to the private function
-func (s *multiStorage) SetUserinfoFromToken(ctx context.Context, userinfo oidc.UserInfoSetter, tokenID, subject, origin string) error {
+func (s *multiStorage) SetUserinfoFromToken(ctx context.Context, userinfo *oidc.UserInfo, tokenID, subject, origin string) error {
 	storage, err := s.storageFromContext(ctx)
 	if err != nil {
 		return err
@@ -218,7 +218,7 @@ func (s *multiStorage) SetUserinfoFromToken(ctx context.Context, userinfo oidc.U
 
 // SetIntrospectionFromToken implements the op.Storage interface
 // it will be called for the introspection endpoint, so we read the token and pass the information from that to the private function
-func (s *multiStorage) SetIntrospectionFromToken(ctx context.Context, introspection oidc.IntrospectionResponse, tokenID, subject, clientID string) error {
+func (s *multiStorage) SetIntrospectionFromToken(ctx context.Context, introspection *oidc.IntrospectionResponse, tokenID, subject, clientID string) error {
 	storage, err := s.storageFromContext(ctx)
 	if err != nil {
 		return err