Description

This epic describes all necessary issues to make token-exchange fully supported.

Discussion

#26502

Issues

All issues in area/token-exchange should be reviewed and moved to corresponding tasks

Motivation

Keycloak has had the OAuth RFC 8693: Token Exchange feature for many years; however, since its inception, it has remained a technology preview feature. Following many requests from the community and customers, the Keycloak team is committed to getting token exchange out of preview.

Scope of the work

The initial scope is to have support for internal/internal token exchange. We might have follow-up epics for support other use-cases (like external to internal, internal to external, impersonation use-cases like direct naked impersonation etc).

Standard token exchange

These are tasks to make sure that Keycloak is compliant with the token exchange specification, which is in current Keycloak documentation referred as internal to internal token exchange. Also here are tasks to make sure that internal-internal token exchange could be supported by default. Which means:

• Good documentation and testing coverage
• Threat modeling and security (including the fine grained control over what is permitted or not)
• Fixing/implement some fundamental gaps in the current implementation.

Required for supported token-exchange

This tasklist contains tasks, which are minimum needed for supported standard token-exchange. So far, it is planned to implement them asap (ideally Keycloak 26.2). The "optional" tasks are not included here.

See this document for the discussions and context about the tasks for standard token-exchange for Keycloak 26.2

• Use correct error code in error response in token exchange #31547
• Add issued_token_type to token-exchange response #31548
• Revise client authentication requirement for token-exchange #31550
• Divide token-exchange to multiple features #35504
• Support for multiple values of some parameters in the grant SPI #35506
• Support for multiple values of audience #35505
• Reject request in case of unavailable audience requested #37104
• Consider making StandardTokenExchangeV2Test to be independent of StandardTokenExchangeV1Test #37105
• Remove FGAP dependency #37108
• Make sure token-exchange is allowed just if client is within token audience #37109
• Remove public-clients support from token-exchange #37111
• Filter scopes for token-exchange based on audience and client roles #37147
• Should we generate id-token from token exchange? #37113
• Consent handling of token-exchange #37112
• Doublecheck request and response parameters aligned with the token-exchange specification #37114
• Review token-exchange with SAML assertion requested #37121
• Add switch to enable token-exchange to requester clients #37110
• The token exchange grant type not available in well-known endpoint when token-exchange-standard feature enabled #37552
• Update default requested token-type and add switch for refresh token #37115
• Make token exchange grant type supported by OIDC client registration #37554
• Start encoding of access-tokens IDs #37118
• Add client-policies support to token-exchange #37122
• Improve ClientScopesCondition to make possible any scope type #37123
• Client scope condition for grant type ? #37124
• Polish token-exchange when refresh-token requested with the offline access #37116
• Can we avoid creating client-session for the case when access-token requested? #37117
• Revocation: document or figure revocation of access-token chain #37119
• Review and test events for token exchange #37693
• Handle supported standard-token-exchange together with use-cases for federated and subject impersonation #37367
• Revocation: Figure revocation of refresh-token chain #37120
• Avoid creating user sessions from the token exchange #37832
• Improve token-exchange documentation #37126
• Promote standard token-exchange V2 to supported by default #37368

Other issues related to standard token-exchange

This list contains tasks, enhancements and reported bugs, which are also related to standard token-exchange. ATM those are not considered "blockers" for supported standard token-exchange. After we finish the tasks from the list above, we may create follow-up epic and add the tasks from the list below to that epic. Before that, we may need to triage those again as:

• Some of those issues might be addressed by the other tasks from the list above. In this case, we can close them.
• Some of those issues might be addressed as a follow-ups (and hence should be moved to the new epic)
• Some of those issues might be addressed in a bit different way than described in the issue (due token-exchange refactoring). In this case, we can move them to the new epic with some updated description
• Some of those issues might be unsupported and hence we might close them as "won't do"

GH Issues:

• Improve control over audience and scope for token-exchange #31553
• aud claim is missing when doing token-exchange with the same 'audience' parameter as the client initiating token-exchange #36942
• Requested (additional) scopes get lost in token exchange since Kecyloak 24 #29614
• Token exchange does not apply mappers #17220
• Token exchange - permissions #35507
• Review and document how refresh tokens are issued when executing token exchanges #23144
• Exchange Token for clients within same Realm throws access_denied #17008
• Improved consent handling in token exchange (OIDC to OIDC Client) #31797
• Add claims to an exchanged token in Token Exchange #30358
• Exchange using an offline token, returns a token that does not pass introspection #33611
• Token Exchange in "Securing Applications and Services" should mention admin_fine_grained_authz #19148
• Empty ISS access token claim when offline token exchanged and scopes are not set correctly as well  #33321
• Token exchange with Token revocation #33252
• Token-Exchange programmatic permission setup #20075
• Make token-exchange feature usable without of Authorization Services #31552
• Can we support automatic migration from FGAP to RBAC for token exchange? #33239
• Add support for the resource parameter in token-exchange #36870
• Support for token-exchange delegation #38279

Federated token exchange

Tasks related to external-internal or internal-external token exchange where integration with some IDP is involved.

Dedicated epics created for the federated-token exchange support:

• External-to-internal token exchange: External to internal token exchange #38335
• Internal-to-external token exchange: Internal to external token exchange #40704

Impersonation

Dedicated epic created for the subject-impersonation support: #38336