Support for ID tokens in token exchange

[kpur-sbab]

Expected Behavior
An ID token issued by a trusted identity provider (e.g., GitLab, Google, GitHub) can be used for token exchange with Spring Authorization Server to obtain an access token.

Current Behavior
Spring Authorization Server does not currently support token exchange using ID tokens.

Context
I am revisiting this topic following a previously closed issue, as we believe there is a valid use case worth reconsidering.

In our setup:

• We expose APIs through Spring Authorization Server to provision OAuth2 clients.
• To maintain consistency across environments (test and production), we use GitLab pipelines to automate client provisioning.
• At present, GitLab authenticates using the client credentials grant to invoke these APIs.

While functional, this approach limits auditability, as all actions are attributed to a shared client rather than the individual who triggered the pipeline.

GitLab provides OIDC support via the GITLAB_OIDC_TOKEN, which represents the identity of the user who initiated the pipeline. Our proposed approach is:

1. Register GitLab as a token exchange client in Spring Authorization Server.
2. Allow GitLab to present its ID token.
3. Exchange this ID token for an access token representing the triggering user.

This would allow us to maintain a proper audit trail of who performed client provisioning actions.

GitLab also exposes a JWKS endpoint (https://gitlab.com/oauth/discovery/keys) for validating ID tokens, making this integration technically feasible. We explored extending or replicating OAuth2TokenExchangeAuthenticationProvider to support this flow; however, since the class is final, customization is not straightforward.

We believe this could be a useful enhancement for Spring Authorization Server and would appreciate your guidance on whether this approach aligns with the intended design, or if there are recommended alternatives.

Thank you very much for your time and consideration.
Tagging @jgrandja @jzheaux

Regards,
Kishore

[jgrandja]

@kpur-sbab This issue was transferred from spring-projects/spring-authorization-server (see spring-authorization-server#2195)

[bkoragan]

@jgrandja I'd like to propose an approach for this enhancement and would appreciate feedback before opening a PR.

Some of Use Cases

1. CI/CD Pipeline Identity (Primary — from this issue)
GitLab, GitHub Actions, and other CI platforms issue OIDC ID tokens representing the user who triggered the pipeline. Organizations want to exchange these ID tokens for access tokens to maintain per-user audit trails, replacing shared client_credentials that obscure who performed an action.

Example flow:

1. Developer triggers GitLab pipeline
2. Pipeline receives GITLAB_OIDC_TOKEN (ID token with sub = triggering user)
3. Pipeline sends token exchange request with subject_token_type=urn:ietf:params:oauth:token-type:id_token
4. Spring Authorization Server validates the ID token via GitLab's JWKS endpoint and issues an access token attributed to the user.
   @kpur-sbab - please confirm if this aligns your case.

2. Federated Identity
An organization trusts multiple external IdPs (Google, Azure AD, Okta). Services present ID tokens from these IdPs and exchange them for local access tokens scoped to the authorization servers' resource modell.

3. Backend-to-Backend with User Context
A backend service receives a user's ID token from a frontend and needs to exchange it for an access token to call downstream services on behalf of that user, without requiring a full authorization code flow.

RFC Basis

RFC 8693 Section 3 explicitly defines urn:ietf:params:oauth:token-type:id_token as a valid token type idntifier. The current implementation only supportsaccess_token and jwt types.

Here is proposed approach

Since OAuth2TokenExchangeAuthenticationProvider is final, I think of a pluggable resolver strategy rather than opening the class for extension:

1. OAuth2TokenExchangeSubjectTokenResolver — keeping the @FunctionalInterface strategy that resolves a subject token + type into a principal context. Returns null if it cannot handle the token type (chain-of-responsibility).

2. OidcIdTokenSubjectTokenResolver — default implementation that uses JwtDecoderFactory<RegisteredClient> to decode and validate externally-issued ID tokens. This follows the same pattern asJwtClientAssertionDecoderFactory in the same module.

3. Provider modification — Add a setSubjectTokenResolver() setter on OAuth2TokenExchangeAuthenticationProvider. When set, the resolver is tried first; if it returns null, the existing authorizationService.findByToken() path is used. Full backward compatibility is preserved.

4. Converter modification — Add id_token to SUPPORTED_TOKEN_TYPES in OAuth2TokenExchangeAuthenticationConverter.

5. Auto-wiring — OAuth2TokenEndpointConfigurer picks up aOAuth2TokenExchangeSubjectTokenResolver bean via getOptionalBean(same pattern as OAuth2AuthorizationService, OAuth2TokenGenerator, etc.).

Notes:

• No breaking changes — Existing behavior is untouched when no resolver is configured
• Follows existing patterns — @FunctionalInterface strategy,JwtDecoderFactory, getOptionalBean auto-wiring
• Keeps final — The provider class stays final; only the token resolution strategy is pluggable
• Extensible — Users can implement their own resolver for non-OIDC external tokens (e.g., custom JWT formats)

Configuration Example

@Bean
OidcIdTokenSubjectTokenResolver subjectTokenResolver() {
    return new OidcIdTokenSubjectTokenResolver((registeredClient) -> {
        // create an JwtDecoder per client pointing to the trusted
        // IDP's JWKS endpoint 
        String jwkSetUri = registeredClient.getClientSettings()
            .getSetting("id-token-jwk-set-uri");
        return NimbusJwtDecoder.withJwkSetUri(jwkSetUri).build();
    });
}

Happy to adjust the approach based on your feedback..

[kpur-sbab]

@bkoragan The example flow perfectly aligns to our requirement.

[kpur-sbab]

@bkoragan One more I forgot to mention. Not all the users can trigger the pipeline so the id token will carry some additional claims(say oauth2.admin.client:write) which has to be mapped as a custom claim in the exchanged token so that the request to OAuth2 client provisioning API is authorized correctly