Description

Putting an additional claim to an exchanged token in Token Exchange.

Current protocol mappers are applied to an exchanged token (to internal) in Token Exchange.
However, these protocol mappers are applied not only an access token by Token Response in any kind of grant, but applied in Token Exchange.

Therefore, current protocol mappers are not applied to only an exchanged token in Token Exchange.

Discussion

No response

Motivation

This feature is beneficial for a use case where a keycloak user only put some specific claim to an exchanged token in only Token Exchange. For example, in micro-service architecture applied environment, a claim that can be meaningful for some workload inside microservices should be put onto only an exchanged token, not onto an access token outside microservices.

Details

AFAIK, there are two ways to realize it;

1. Enhance existing protocol mappers
2. Created new types of protocol mappers
3. Using client policies

As for 1, we add a switch to existing protocol mappers. If the switch is ON, it is applied to an exchanged token in Token Exchange. If OFF, it is not applied.

Advantage:

• We need not to modify existing Token Exchange source code.

Disadvantage:

• It needs some migration mechanism.
• We need to control UI to show the switch only if keycloak runs with Token Exchange feature.
• One additional switch is shown in Admin UI, which complicates operations by a keycloak's admin.
• The protocol mapper is applied to an exchanged token in every patterns of Token Exchange. For example, there are two patters of Token Exchange (A and B), then, the protocol mapper is applied to an exchanged token in Token Exchange pattern A, and Token Exchange pattern B.

As for 2, we add new type of a protocol mapper TokenExchangeMapper like OID4VCMapper in OID4VCI. This protocol mapper is only applied to an exchanged token in Token Exchange.

Advantage:

• It need not some migration mechanism.

Disadvantage:

• We need to modify existing Token Exchange source code.
• The protocol mapper is applied to an exchanged token in every patterns of Token Exchange. For example, there are two patters of Token Exchange (A and B), then, the protocol mapper is applied to an exchanged token in Token Exchange pattern A, and Token Exchange pattern B.

As for 3, we use client policies to add some claims to an exchanged token in Token Exchange

Advantage:

• It need not some migration mechanism.
• It can change which claims are put onto to an exchanged token in each patterns of Token Exchange. For example, there are two patters of Token Exchange (A and B), then, the client policy's executor put a claim X to an exchanged token in Token Exchange pattern A, while the other client policy's executor put a claim Y to an exchanged token in Token Exchange pattern B.

Disadvantage:

• We need not to modify existing Token Exchange source code for applying client policies in Token Exchange (current Keycloak does not apply client policies in Token Exchange)