Customize token exchange endpoint to issue ID-JAG - #49998

services/src/main/java/org/keycloak/protocol/oidc/tokenexchange/IDJWTTokenExchangeProvider.java:150

• This applies revocation policy to the authenticated requester rather than the client that issued the ID token (token.getIssuedFor()). Since inherited audience validation permits a different requester when it is listed in a multi-audience token, an ID token from a disabled, deleted, or revoke-before issuing client can still mint an ID-JAG; resolve and validate the token-holder client (or require it to equal client) first.

        if (client.getNotBefore() > notBefore) {
            notBefore = client.getNotBefore();
        }

services/src/main/java/org/keycloak/protocol/oidc/tokenexchange/IDJWTTokenExchangeProvider.java:228

• A client can trigger this WARN on every otherwise successful exchange by appending an unpermitted scope, allowing routine input to flood operational logs. Log filtered client input at debug level instead.

                logger.warn("Requested scope [" + requested + "] is not permitted and was filtered out.");

services/src/main/java/org/keycloak/protocol/oidc/tokenexchange/IDJWTTokenExchangeProvider.java:66

• The public ID-JAG guide still states that issuer support is not implemented and that issuer configuration is unavailable (docs/guides/securing-apps/identity-assertion-jwt-authorization-grant.adoc:31-35,52-70). Update it to document this provider and its three required client attributes; otherwise administrators cannot reliably configure the new feature.

    // client attribute used to find the resource authorization server client by the audience parameter
    private static final String RESOURCE_AUTHORIZATION_SERVER_IDENTIFIER = "idjag.resource.authorization.server.identifier";

    // client attribute prefix for the client's client_id in resource authorization server
    private static final String CLIENTID_IN_RESOURCE_AUTHORIZATION_SERVER = "idjag.clientid.at.";

    // client attribute prefix for the permitted scopes in the resource authorization server
    private static final String PERMITTED_SCOPES_IN_RESOURCE_AUTHORIZATION_SERVER = "idjag.permitted.scopes.at.";

services/src/main/java/org/keycloak/protocol/oidc/tokenexchange/IDJWTTokenExchangeProvider.java:387

• The new repeated-audience rejection branch is not exercised by the added integration tests; the wrong-audience test sends only one value. Add a request with two .audience(...) calls and assert invalid_request so multiple audiences cannot regress to silent truncation.

            } else if (audienceParams.size() > 1) {
                event.detail(Details.REASON, "Multiple audiences are not supported");
                event.error(Errors.INVALID_REQUEST);

                throw new CorsErrorResponseException(cors, OAuthErrorException.INVALID_REQUEST, 
                    "The ID-JAG token exchange provider does not support multiple audiences. Please request one audience at a time.", 
                    Response.Status.BAD_REQUEST);

services/src/main/java/org/keycloak/protocol/oidc/tokenexchange/IDJWTTokenExchangeProvider.java:174

• This validates the requester’s client session, not the client identified by the signed ID token’s azp (token.getIssuedFor()). For a cross-client token whose audience includes the requester, the token can remain exchangeable after its issuing client is disabled, revoked, or removed; resolve the issuing client and apply its enabled/not-before/client-session checks, while keeping the separate requester-audience validation.

        AuthenticatedClientSessionModel clientSession = userSession.getAuthenticatedClientSessionByClient(client.getId());
        if (clientSession == null || !AuthenticationManager.isClientSessionValid(realm, client, userSession, clientSession)) {
            event.detail(Details.REASON, "Client session not found or revoked");
            event.error(Errors.INVALID_TOKEN);
            throw new CorsErrorResponseException(cors, OAuthErrorException.INVALID_TOKEN, "Client session not found or revoked", Response.Status.BAD_REQUEST);

services/src/main/java/org/keycloak/protocol/oidc/TokenManager.java:1351

• The mapper context here belongs to the requesting client, so AbstractPairwiseSubMapper derives sub from that client’s sector rather than the ID-JAG audience. A requester exchanging for multiple authorization servers will therefore disclose the same pairwise subject to each; subject derivation needs an audience-specific mapper context or sector.

            idjag = transformIDJag(session, idjag, userSession, clientSessionCtx);

services/src/main/java/org/keycloak/protocol/oidc/tokenexchange/IDJWTTokenExchangeProvider.java:236

• A client can generate one WARN entry per unpermitted scope while the request is otherwise valid, allowing routine input to flood operational logs. Keep the event/error response for auditing and log filtered user input at debug level.

                logger.warn("Requested scope [" + requested + "] is not permitted and was filtered out.");

services/src/main/java/org/keycloak/protocol/oidc/tokenexchange/IDJWTTokenExchangeProvider.java:150

• This applies the requesting client's revocation policy to the subject ID token instead of the client in token.getIssuedFor(). Since the inherited audience check permits a different token holder when the requester is in aud, an ID token whose issuing client was disabled, revoked, or detached from the session can still be exchanged; resolve and validate the subject-token client and use it for both not-before and client-session checks.

        if (client.getNotBefore() > notBefore) {
            notBefore = client.getNotBefore();
        }

services/src/main/java/org/keycloak/protocol/oidc/tokenexchange/IDJWTTokenExchangeProvider.java:80

• For an ID-JAG request from a client without standard token exchange enabled, returning false lets lower-priority providers overwrite this reason (the standard provider will report that the ID-token subject is unsupported). Once the ID-JAG token type selects this provider, claim the request and reject the disabled setting from tokenExchange() so clients receive the actual configuration error.

        if(!OIDCAdvancedConfigWrapper.fromClientModel(context.getClient()).isStandardTokenExchangeEnabled()) {
            context.setUnsupportedReason("Standard token exchange is not enabled for the requested client");
            return false;
        }

services/src/main/java/org/keycloak/protocol/oidc/tokenexchange/IDJWTTokenExchangeProvider.java:55

• This adds the issuer implementation, but the existing ID-JAG guide still states that issuer support and issuer configuration are unavailable (docs/guides/securing-apps/identity-assertion-jwt-authorization-grant.adoc:31-65). Update that guide with the feature flag, token-exchange request, and the three required client attributes; otherwise users cannot configure this new provider from the product documentation.

public class IDJWTTokenExchangeProvider extends StandardTokenExchangeProvider {

services/src/main/java/org/keycloak/protocol/oidc/tokenexchange/IDJWTTokenExchangeProvider.java:150

• The revocation checks are applied to the requesting client, not to the client that issued the subject ID token (token.getIssuedFor()). If both clients share an SSO session and the ID token includes the requester in aud, disabling/revoking the token-holder client still leaves that token exchangeable; resolve the token-holder client and apply its enabled/not-before/client-session checks before proceeding.

        if (client.getNotBefore() > notBefore) {
            notBefore = client.getNotBefore();

services/src/main/java/org/keycloak/protocol/oidc/tokenexchange/IDJWTTokenExchangeProvider.java:123

• A syntactically valid JWT with a missing alg header makes getAlgorithm() return null, so .name() throws an uncaught NullPointerException and returns a 500 instead of invalid_token. Validate the header algorithm before dereferencing it so malformed client input follows the existing verification-error path.

            String kid = verifier.getHeader().getKeyId();
            String algorithm = verifier.getHeader().getAlgorithm().name();
            SignatureProvider signatureProvider = session.getProvider(SignatureProvider.class, algorithm);

services/src/main/java/org/keycloak/protocol/oidc/tokenexchange/IDJWTTokenExchangeProvider.java:179

• This validates the requesting client's session, not the client identified by the ID token's azp. Because inherited validateAudience also permits a different requester that appears in the token audience, such a requester can still exchange the token after the token-holder client is disabled, removed, revoked, or restarted; resolve token.getIssuedFor() and apply enabled, not-before, client-session, and session-start checks to that client/session.

        AuthenticatedClientSessionModel clientSession = userSession.getAuthenticatedClientSessionByClient(client.getId());
        if (clientSession == null || !AuthenticationManager.isClientSessionValid(realm, client, userSession, clientSession)) {

services/src/main/java/org/keycloak/protocol/oidc/tokenexchange/IDJWTTokenExchangeProvider.java:244

• An authenticated client can generate a WARN entry for every unpermitted scope while the exchange still succeeds if any requested scope is valid. Invalid request input should not flood operational logs; log this at debug level or reject the request once with invalid_scope.

                logger.warn("Requested scope [" + requested + "] is not permitted and was filtered out.");

services/src/main/java/org/keycloak/protocol/oidc/tokenexchange/IDJWTTokenExchangeProvider.java:118

• Checking only actor_token still accepts actor_token_type by itself and silently ignores it. Since this provider does not support delegation, either actor parameter must make the ID-JAG request fail.

        if (context.getParams().getActorToken() != null) {
            event.detail(Details.REASON, "Actor tokens are not supported for ID-JAG token exchange");
            event.error(Errors.INVALID_REQUEST);
            throw new CorsErrorResponseException(cors, OAuthErrorException.INVALID_REQUEST,
                "Actor tokens are not supported for ID-JAG token exchange", Response.Status.BAD_REQUEST);

services/src/main/java/org/keycloak/protocol/oidc/tokenexchange/IDJWTTokenExchangeProvider.java:164

• The revocation and session checks are applied to the authenticated requester client, not to the client identified by the subject ID token's issuedFor. Inherited audience validation permits cross-client exchange when the requester is in aud, so disabling/revoking or setting not-before on the token-holder client does not invalidate that ID token; resolve and validate the token-holder client/session separately.

        int notBefore = realm.getNotBefore();

        if (client.getNotBefore() > notBefore) {
            notBefore = client.getNotBefore();
        }

services/src/main/java/org/keycloak/protocol/oidc/TokenManager.java:1351

• This mapper context belongs to the requesting application, so AbstractPairwiseSubMapper derives sub from the requester's sector rather than the resource authorization server that is placed in aud. The same target server can therefore receive different subjects for one user depending on which requesting app obtained the ID-JAG; generate the subject using the resolved audience client's sector/context.

            idjag = transformIDJag(session, idjag, userSession, clientSessionCtx);

services/src/main/java/org/keycloak/protocol/oidc/tokenexchange/IDJWTTokenExchangeProvider.java:75

• Overriding StandardTokenExchangeProvider.supports() drops its guards for requested_subject, requested_issuer, and subject_issuer. An ID-JAG request containing any of those parameters is therefore accepted and the requested impersonation/issuer semantics are silently ignored; reject these unsupported parameters before claiming the request.

This issue also appears on line 114 of the same file.

        String requestedTokenType = context.getFormParams().getFirst(OAuth2Constants.REQUESTED_TOKEN_TYPE);
        if (!OAuth2Constants.IDENTITY_ASSERTION_JWT_TOKEN_TYPE.equals(requestedTokenType)) {
            context.setUnsupportedReason("Parameter 'requested_token_type' should be 'urn:ietf:params:oauth:token-type:id-jag' for IDJWT token exchange");
            return false;

services/src/main/java/org/keycloak/protocol/oidc/TokenManager.java:1363

• OIDCIDTokenMapper is allowed to return an IDToken, so a custom mapper that returns a replacement token causes this cast to throw ClassCastException and turns ID-JAG issuance into a 500. Avoid relying on the mapper preserving the IDJAG runtime subtype, or introduce an ID-JAG-specific mapping contract.

                        return (IDJAG) ((OIDCIDTokenMapper) mapper.getValue()).transformIDToken(token, mapper.getKey(), session, userSession, clientSessionCtx);

services/src/main/java/org/keycloak/protocol/oidc/tokenexchange/IDJWTTokenExchangeProvider.java:250

• Each client-controlled, unpermitted scope is logged at WARN even though the request can still succeed with the remaining scopes. An authenticated client can submit many such values per request and flood operational logs; keep this at debug level or aggregate it once.

                logger.warn("Requested scope [" + requested + "] is not permitted and was filtered out.");