feat(oidc): allow returning of parent errors to client (#8376)

# Which Problems Are Solved

Currently the OIDC API of ZITADEL only prints parent errors to the logs.
Where 4xx status are typically warn level and 5xx error level. This
makes it hard to debug certain errors for client in multi-instance
environments like ZITADEL cloud, where there is no direct access to
logs. In case of support requests we often can't correlate past
log-lines to the error that was reported.

This change adds the possibility to return the parent error in the
response to the OIDC client. For the moment this only applies to JSON
body responses, not error redirects to the RP.

# How the Problems Are Solved

- New instance-level feature flag: `debug_oidc_parent_error`
- Use the new `WithReturnParentToClient()` function from the oidc lib
introduced in https://github.com/zitadel/oidc/pull/629 for all cases
where `WithParent` was already used and the request context is
available.

# Additional Changes

none

# Additional Context

- Depends on: https://github.com/zitadel/oidc/pull/629
- Related to: https://github.com/zitadel/zitadel/issues/8362

---------

Co-authored-by: Livio Spring <livio.a@gmail.com>

internal/api/grpc/feature/v2/converter.go

@@ -43,6 +43,7 @@ func instanceFeaturesToCommand(req *feature_pb.SetInstanceFeaturesRequest) *comm
 		Actions:                         req.Actions,
 		ImprovedPerformance:             improvedPerformanceListToDomain(req.ImprovedPerformance),
 		WebKey:                          req.WebKey,
+		DebugOIDCParentError:            req.DebugOidcParentError,
 	}
 }
 
@@ -57,6 +58,7 @@ func instanceFeaturesToPb(f *query.InstanceFeatures) *feature_pb.GetInstanceFeat
 		Actions:                             featureSourceToFlagPb(&f.Actions),
 		ImprovedPerformance:                 featureSourceToImprovedPerformanceFlagPb(&f.ImprovedPerformance),
 		WebKey:                              featureSourceToFlagPb(&f.WebKey),
+		DebugOidcParentError:                featureSourceToFlagPb(&f.DebugOIDCParentError),
 	}
 }
 

internal/api/grpc/feature/v2/converter_test.go

@@ -217,6 +217,10 @@ func Test_instanceFeaturesToPb(t *testing.T) {
 			Enabled: true,
 			Source:  feature_pb.Source_SOURCE_INSTANCE,
 		},
+		DebugOidcParentError: &feature_pb.FeatureFlag{
+			Enabled: false,
+			Source:  feature_pb.Source_SOURCE_UNSPECIFIED,
+		},
 	}
 	got := instanceFeaturesToPb(arg)
 	assert.Equal(t, want, got)

internal/api/grpc/feature/v2beta/converter.go

@@ -43,6 +43,7 @@ func instanceFeaturesToCommand(req *feature_pb.SetInstanceFeaturesRequest) *comm
 		Actions:                         req.Actions,
 		ImprovedPerformance:             improvedPerformanceListToDomain(req.ImprovedPerformance),
 		WebKey:                          req.WebKey,
+		DebugOIDCParentError:            req.DebugOidcParentError,
 	}
 }
 
@@ -57,6 +58,7 @@ func instanceFeaturesToPb(f *query.InstanceFeatures) *feature_pb.GetInstanceFeat
 		Actions:                             featureSourceToFlagPb(&f.Actions),
 		ImprovedPerformance:                 featureSourceToImprovedPerformanceFlagPb(&f.ImprovedPerformance),
 		WebKey:                              featureSourceToFlagPb(&f.WebKey),
+		DebugOidcParentError:                featureSourceToFlagPb(&f.DebugOIDCParentError),
 	}
 }
 

internal/api/grpc/feature/v2beta/converter_test.go

@@ -217,6 +217,10 @@ func Test_instanceFeaturesToPb(t *testing.T) {
 			Enabled: true,
 			Source:  feature_pb.Source_SOURCE_INSTANCE,
 		},
+		DebugOidcParentError: &feature_pb.FeatureFlag{
+			Enabled: false,
+			Source:  feature_pb.Source_SOURCE_UNSPECIFIED,
+		},
 	}
 	got := instanceFeaturesToPb(arg)
 	assert.Equal(t, want, got)

internal/api/oidc/auth_request.go

@@ -277,7 +277,7 @@ func (o *OPStorage) RevokeToken(ctx context.Context, token, userID, clientID str
 		if zerrors.IsPreconditionFailed(err) {
 			return oidc.ErrInvalidClient().WithDescription("token was not issued for this client")
 		}
-		return oidc.ErrServerError().WithParent(err)
+		return oidc.ErrServerError().WithParent(err).WithReturnParentToClient(authz.GetFeatures(ctx).DebugOIDCParentError)
 	}
 
 	return o.revokeTokenV1(ctx, token, userID, clientID)
@@ -293,14 +293,14 @@ func (o *OPStorage) revokeTokenV1(ctx context.Context, token, userID, clientID s
 		if err == nil || zerrors.IsNotFound(err) {
 			return nil
 		}
-		return oidc.ErrServerError().WithParent(err)
+		return oidc.ErrServerError().WithParent(err).WithReturnParentToClient(authz.GetFeatures(ctx).DebugOIDCParentError)
 	}
 	accessToken, err := o.repo.TokenByIDs(ctx, userID, token)
 	if err != nil {
 		if zerrors.IsNotFound(err) {
 			return nil
 		}
-		return oidc.ErrServerError().WithParent(err)
+		return oidc.ErrServerError().WithParent(err).WithReturnParentToClient(authz.GetFeatures(ctx).DebugOIDCParentError)
 	}
 	if accessToken.ApplicationID != clientID {
 		return oidc.ErrInvalidClient().WithDescription("token was not issued for this client")
@@ -309,7 +309,7 @@ func (o *OPStorage) revokeTokenV1(ctx context.Context, token, userID, clientID s
 	if err == nil || zerrors.IsNotFound(err) {
 		return nil
 	}
-	return oidc.ErrServerError().WithParent(err)
+	return oidc.ErrServerError().WithParent(err).WithReturnParentToClient(authz.GetFeatures(ctx).DebugOIDCParentError)
 }
 
 func (o *OPStorage) GetRefreshTokenInfo(ctx context.Context, clientID string, token string) (userID string, tokenID string, err error) {

internal/api/oidc/client.go

@@ -975,13 +975,13 @@ func (s *Server) VerifyClient(ctx context.Context, r *op.Request[op.ClientCreden
 		return s.clientCredentialsAuth(ctx, r.Data.ClientID, r.Data.ClientSecret)
 	}
 
-	clientID, assertion, err := clientIDFromCredentials(r.Data)
+	clientID, assertion, err := clientIDFromCredentials(ctx, r.Data)
 	if err != nil {
 		return nil, err
 	}
 	client, err := s.query.GetOIDCClientByID(ctx, clientID, assertion)
 	if zerrors.IsNotFound(err) {
-		return nil, oidc.ErrInvalidClient().WithParent(err).WithDescription("client not found")
+		return nil, oidc.ErrInvalidClient().WithParent(err).WithReturnParentToClient(authz.GetFeatures(ctx).DebugOIDCParentError).WithDescription("client not found")
 	}
 	if err != nil {
 		return nil, err // defaults to server error
@@ -1019,7 +1019,7 @@ func (s *Server) verifyClientAssertion(ctx context.Context, client *query.OIDCCl
 	}
 	verifier := op.NewJWTProfileVerifierKeySet(keySetMap(client.PublicKeys), op.IssuerFromContext(ctx), time.Hour, client.ClockSkew)
 	if _, err := op.VerifyJWTAssertion(ctx, assertion, verifier); err != nil {
-		return oidc.ErrInvalidClient().WithParent(err).WithDescription("invalid assertion")
+		return oidc.ErrInvalidClient().WithParent(err).WithReturnParentToClient(authz.GetFeatures(ctx).DebugOIDCParentError).WithDescription("invalid assertion")
 	}
 	return nil
 }
@@ -1036,7 +1036,7 @@ func (s *Server) verifyClientSecret(ctx context.Context, client *query.OIDCClien
 	spanPasswordComparison.EndWithError(err)
 	if err != nil {
 		s.command.OIDCSecretCheckFailed(ctx, client.AppID, client.ProjectID, client.Settings.ResourceOwner)
-		return oidc.ErrInvalidClient().WithParent(err).WithDescription("invalid secret")
+		return oidc.ErrInvalidClient().WithParent(err).WithReturnParentToClient(authz.GetFeatures(ctx).DebugOIDCParentError).WithDescription("invalid secret")
 	}
 	s.command.OIDCSecretCheckSucceeded(ctx, client.AppID, client.ProjectID, client.Settings.ResourceOwner, updated)
 	return nil

internal/api/oidc/client_converter.go

@@ -1,6 +1,7 @@
 package oidc
 
 import (
+	"context"
 	"slices"
 	"strings"
 	"time"
@@ -8,6 +9,7 @@ import (
 	"github.com/zitadel/oidc/v3/pkg/oidc"
 	"github.com/zitadel/oidc/v3/pkg/op"
 
+	"github.com/zitadel/zitadel/internal/api/authz"
 	"github.com/zitadel/zitadel/internal/command"
 	"github.com/zitadel/zitadel/internal/domain"
 	"github.com/zitadel/zitadel/internal/query"
@@ -218,11 +220,11 @@ func removeScopeWithPrefix(scopes []string, scopePrefix ...string) []string {
 	return newScopeList
 }
 
-func clientIDFromCredentials(cc *op.ClientCredentials) (clientID string, assertion bool, err error) {
+func clientIDFromCredentials(ctx context.Context, cc *op.ClientCredentials) (clientID string, assertion bool, err error) {
 	if cc.ClientAssertion != "" {
 		claims := new(oidc.JWTTokenRequest)
 		if _, err := oidc.ParseToken(cc.ClientAssertion, claims); err != nil {
-			return "", false, oidc.ErrInvalidClient().WithParent(err)
+			return "", false, oidc.ErrInvalidClient().WithParent(err).WithReturnParentToClient(authz.GetFeatures(ctx).DebugOIDCParentError)
 		}
 		return claims.Issuer, true, nil
 	}

internal/api/oidc/client_credentials.go

@@ -8,6 +8,7 @@ import (
 	"github.com/zitadel/oidc/v3/pkg/oidc"
 	"github.com/zitadel/oidc/v3/pkg/op"
 
+	"github.com/zitadel/zitadel/internal/api/authz"
 	"github.com/zitadel/zitadel/internal/query"
 	"github.com/zitadel/zitadel/internal/telemetry/tracing"
 	"github.com/zitadel/zitadel/internal/zerrors"
@@ -37,7 +38,7 @@ func (c *clientCredentialsRequest) GetScopes() []string {
 func (s *Server) clientCredentialsAuth(ctx context.Context, clientID, clientSecret string) (op.Client, error) {
 	user, err := s.query.GetUserByLoginName(ctx, false, clientID)
 	if zerrors.IsNotFound(err) {
-		return nil, oidc.ErrInvalidClient().WithParent(err).WithDescription("client not found")
+		return nil, oidc.ErrInvalidClient().WithParent(err).WithReturnParentToClient(authz.GetFeatures(ctx).DebugOIDCParentError).WithDescription("client not found")
 	}
 	if err != nil {
 		return nil, err // defaults to server error

internal/api/oidc/introspect.go

@@ -156,18 +156,18 @@ func (s *Server) introspectionClientAuth(ctx context.Context, cc *op.ClientCrede
 		if cc.ClientAssertion != "" {
 			verifier := op.NewJWTProfileVerifierKeySet(keySetMap(client.PublicKeys), op.IssuerFromContext(ctx), time.Hour, time.Second)
 			if _, err := op.VerifyJWTAssertion(ctx, cc.ClientAssertion, verifier); err != nil {
-				return "", "", false, oidc.ErrUnauthorizedClient().WithParent(err)
+				return "", "", false, oidc.ErrUnauthorizedClient().WithParent(err).WithReturnParentToClient(authz.GetFeatures(ctx).DebugOIDCParentError)
 			}
 			return client.ClientID, client.ProjectID, client.ProjectRoleAssertion, nil
 
 		}
 		if client.HashedSecret != "" {
 			if err := s.introspectionClientSecretAuth(ctx, client, cc.ClientSecret); err != nil {
-				return "", "", false, oidc.ErrUnauthorizedClient().WithParent(err)
+				return "", "", false, oidc.ErrUnauthorizedClient().WithParent(err).WithReturnParentToClient(authz.GetFeatures(ctx).DebugOIDCParentError)
 			}
 			return client.ClientID, client.ProjectID, client.ProjectRoleAssertion, nil
 		}
-		return "", "", false, oidc.ErrUnauthorizedClient().WithParent(errNoClientSecret)
+		return "", "", false, oidc.ErrUnauthorizedClient().WithParent(errNoClientSecret).WithReturnParentToClient(authz.GetFeatures(ctx).DebugOIDCParentError)
 	}()
 
 	span.EndWithError(err)
@@ -212,13 +212,13 @@ func (s *Server) introspectionClientSecretAuth(ctx context.Context, client *quer
 // clientFromCredentials parses the client ID early,
 // and makes a single query for the client for either auth methods.
 func (s *Server) clientFromCredentials(ctx context.Context, cc *op.ClientCredentials) (client *query.IntrospectionClient, err error) {
-	clientID, assertion, err := clientIDFromCredentials(cc)
+	clientID, assertion, err := clientIDFromCredentials(ctx, cc)
 	if err != nil {
 		return nil, err
 	}
 	client, err = s.query.GetIntrospectionClientByID(ctx, clientID, assertion)
 	if errors.Is(err, sql.ErrNoRows) {
-		return nil, oidc.ErrUnauthorizedClient().WithParent(err)
+		return nil, oidc.ErrUnauthorizedClient().WithParent(err).WithReturnParentToClient(authz.GetFeatures(ctx).DebugOIDCParentError)
 	}
 	// any other error is regarded internal and should not be reported back to the client.
 	return client, err

internal/api/oidc/server.go

@@ -10,6 +10,7 @@ import (
 	"github.com/zitadel/oidc/v3/pkg/oidc"
 	"github.com/zitadel/oidc/v3/pkg/op"
 
+	"github.com/zitadel/zitadel/internal/api/authz"
 	"github.com/zitadel/zitadel/internal/auth/repository"
 	"github.com/zitadel/zitadel/internal/command"
 	"github.com/zitadel/zitadel/internal/crypto"
@@ -119,7 +120,7 @@ func (s *Server) Discovery(ctx context.Context, r *op.Request[struct{}]) (_ *op.
 	}()
 	restrictions, err := s.query.GetInstanceRestrictions(ctx)
 	if err != nil {
-		return nil, op.NewStatusError(oidc.ErrServerError().WithParent(err).WithDescription("internal server error"), http.StatusInternalServerError)
+		return nil, op.NewStatusError(oidc.ErrServerError().WithParent(err).WithReturnParentToClient(authz.GetFeatures(ctx).DebugOIDCParentError).WithDescription("internal server error"), http.StatusInternalServerError)
 	}
 	allowedLanguages := restrictions.AllowedLanguages
 	if len(allowedLanguages) == 0 {

internal/api/oidc/token_device.go

@@ -7,6 +7,7 @@ import (
 	"github.com/zitadel/oidc/v3/pkg/oidc"
 	"github.com/zitadel/oidc/v3/pkg/op"
 
+	"github.com/zitadel/zitadel/internal/api/authz"
 	"github.com/zitadel/zitadel/internal/command"
 	"github.com/zitadel/zitadel/internal/domain"
 	"github.com/zitadel/zitadel/internal/telemetry/tracing"
@@ -29,7 +30,7 @@ func (s *Server) DeviceToken(ctx context.Context, r *op.ClientRequest[oidc.Devic
 		return response(s.accessTokenResponseFromSession(ctx, client, session, "", client.client.ProjectID, client.client.ProjectRoleAssertion, client.client.AccessTokenRoleAssertion, client.client.IDTokenRoleAssertion, client.client.IDTokenUserinfoAssertion))
 	}
 	if errors.Is(err, context.DeadlineExceeded) {
-		return nil, oidc.ErrSlowDown().WithParent(err)
+		return nil, oidc.ErrSlowDown().WithParent(err).WithReturnParentToClient(authz.GetFeatures(ctx).DebugOIDCParentError)
 	}
 
 	var target command.DeviceAuthStateError
@@ -42,5 +43,5 @@ func (s *Server) DeviceToken(ctx context.Context, r *op.ClientRequest[oidc.Devic
 			return nil, oidc.ErrExpiredDeviceCode()
 		}
 	}
-	return nil, oidc.ErrAccessDenied().WithParent(err)
+	return nil, oidc.ErrAccessDenied().WithParent(err).WithReturnParentToClient(authz.GetFeatures(ctx).DebugOIDCParentError)
 }

internal/api/oidc/token_exchange.go

@@ -55,7 +55,7 @@ func (s *Server) tokenExchange(ctx context.Context, r *op.ClientRequest[oidc.Tok
 
 	subjectToken, err := s.verifyExchangeToken(ctx, client, r.Data.SubjectToken, r.Data.SubjectTokenType, oidc.AllTokenTypes...)
 	if err != nil {
-		return nil, oidc.ErrInvalidRequest().WithParent(err).WithDescription("subject_token invalid")
+		return nil, oidc.ErrInvalidRequest().WithParent(err).WithReturnParentToClient(authz.GetFeatures(ctx).DebugOIDCParentError).WithDescription("subject_token invalid")
 	}
 
 	actorToken := subjectToken // see [createExchangeTokens] comment.
@@ -65,7 +65,7 @@ func (s *Server) tokenExchange(ctx context.Context, r *op.ClientRequest[oidc.Tok
 		}
 		actorToken, err = s.verifyExchangeToken(ctx, client, r.Data.ActorToken, r.Data.ActorTokenType, oidc.AccessTokenType, oidc.IDTokenType, oidc.RefreshTokenType)
 		if err != nil {
-			return nil, oidc.ErrInvalidRequest().WithParent(err).WithDescription("actor_token invalid")
+			return nil, oidc.ErrInvalidRequest().WithParent(err).WithReturnParentToClient(authz.GetFeatures(ctx).DebugOIDCParentError).WithDescription("actor_token invalid")
 		}
 		ctx = authz.SetCtxData(ctx, authz.CtxData{
 			UserID: actorToken.userID,

internal/api/oidc/userinfo.go

@@ -42,7 +42,7 @@ func (s *Server) UserInfo(ctx context.Context, r *op.Request[oidc.UserInfoReques
 
 	token, err := s.verifyAccessToken(ctx, r.Data.AccessToken)
 	if err != nil {
-		return nil, op.NewStatusError(oidc.ErrAccessDenied().WithDescription("access token invalid").WithParent(err), http.StatusUnauthorized)
+		return nil, op.NewStatusError(oidc.ErrAccessDenied().WithDescription("access token invalid").WithParent(err).WithReturnParentToClient(authz.GetFeatures(ctx).DebugOIDCParentError), http.StatusUnauthorized)
 	}
 
 	var (