Hi. Can you please clarify as how you worked around the issue with roles?

I've added a default client scope roles to the client that requests the token exchange. That fixed the issue for me.

My entire setup consists of:

• 1+ public OAuth2 clients:
  • At least one OAuth2 grant enabled (typically the Authorization Code grant)
  • Full scope allowed (option inside of the dedicated scopes of the client)
  • Optional client scope: roles
  • Created by Dynamic Client Registration
• 1 confidential OAuth2 client:
  • Standard Token Exchange enabled
  • Default client scope: roles
  • A client role impersonator (It can be any name you want)
• Users mapped to the impersonator client role (directly or via group membership), as well as other roles from other resource server clients

The flow:

1. Users delegate power to the public OAuth2 clients.
2. The confidential client that will request the token exchange later on is added among the audiences in the access token, as well as the other clients the user has access to.
3. The confidential client sends the token exchange request, specifying one of those other clients in the audience parameter of the request.
4. The new access token contains the only the requested audience (i.e., single string value in the aud claim instead of a list), and the azp claim set to the name of the token exchange requestor client.

I use it to reduce the scope of the initial token, before handling consecutive requests.

The audience parameter is optional in token exchange V2 and it's totally different to V1 client-to-client exchange. This parameter is now used only to restrict the returned token to the audience(s) specified in the param. We are returning an error if you say that audience should be restricted to clientb but that audience is not even generated. This parameter does not add any special audience. We tried to explain this behavior here.

So, in general, in token exchange V2 if you plan to perform a token exchange using clienta to generate a token for clientb the steps are the following:

• In clienta you need to configure the scopes (default or optional) you need to create a token in clienta that is valid for clientb. Here you configure mappers and so on and so forth. Those scopes can be used to add audiences to the aud claim needed by endpoints that clientb uses or, in general, anything you need for clientb.
• Allow token exchange capability in clienta.
• When you perform the token exchange you specify the scopes you want to use. Normal processing in keycloak is performed.
• The audience param can be used to restrict the access of the returned token. If the resulting token has several scopes and you just want some of them, you can restrict the audience.

Why does token exchange work when the audience is omitted?

Because V2 is different to V1. The audience is not necessary now. It's just used to restrict the generated token. Only normal scope processing is used in clienta to generate the token (scopes are the meaningful part now).

Why am I unable to exchange the token for a specific audience (App B)?

Because the token generated in clienta does not generate an audience for clientb. Therefore you cannot restrict the audience for that client.

Why does Keycloak claim that the requested audience is “not available”, even though App B is a valid confidential client?

Because when processing the request for clienta, the final token's audience does not contain clientb, so you cannot restrict the audience to clientb.

Could you elaborate on the linked docs, which are saying:

By default, token exchange can be used to request extra scopes and audiences that are not present in the initial subject_token. If, for security reasons, you want to ensure that scopes are limited to the ones already granted to the subject_token, the downscope-assertion-grant-enforcer policy executor can be applied to the client. This executor enforces that only downscoping is allowed for token exchange. See Downscoping and Client Policies chapters in the Server Administration Guide for more information.

If adding audiences is not possible, the incoming token would have to have quite an escalated set of privileges, just to be stripped down again later. This means, we need to add audiences somewhere in the middle (to hide from the public client) and strip them later.

What would be the flow to add an audience to an incoming token?
My setup right now is planned like this:

sequenceDiagram
    actor B as Browser
    participant PC as Public Client<br/>(Web Page)
    participant AG as API Gateway<br/>(api-gw-client-id)
    participant BC as Backend API<br/>(backend-client-id)
    participant KC as Keycloak

    rect rgb(230, 240, 255)
        Note over B,KC: Phase 1: Initial Authentication
        B->>+KC: Initiate OAuth2 Authorization Code Flow
        PC-->>PC: Handle redirects & callbacks
        Note over KC: Token (1) audience (static mapper):<br/>web page audience<br/>api-gw-client-id
        KC-->>-B: Return Access Token (1)
    end
    
    B->>+PC: User interaction
    PC->>+AG: GET /api/xyz<br/>Authorization: Bearer Token (1)
    
    rect rgb(255, 250, 230)
        Note over AG,KC: Phase 2: Token Exchange
        Note over AG: API Gateway has static audience<br/>mapper in KC for backend-client-id
        AG->>+KC: Token Exchange Request<br/>audience=backend-client-id
        KC-->>-AG: Return Exchanged Token (2)
    end
    
    AG->>+BC: Forward request with Token (2)<br/>Authorization: Bearer Token (2)
    Note over BC: Token (2) audience:<br/>backend-client-id only<br/>(restricted scope)
    BC-->>-AG: API Response (Data)
    AG-->>-PC: API Response (Data)
    PC-->>-B: Render UI with data

The reason for asking is that the decidsion which audiences to add or not is driven by other mechanisms in the api gateway, not static config in KC. We would like to look at the claims in the public client token and decide on that.

@k1th The audiences in keycloak are managed via mappers, so usually you configure client scopes to add audiences. The paragraph you are pasting is just mentioning that token exchange can request new scopes (and possibly new audiences granted by those scopes). It's just a warning to say that, by default new scopes and audiences is allowed in TE. You can limit that using the downscoping client policy.

In general the way to add a new audience in keycloak is mapping the audience mapper (with the wanted audience or audiences) to a client scope. And then request that extra scope (or scopes) in the Token Exchange request.

Thank you, @rmartinc
That works well, but was hard to understand from the docs:

• the token exchange audience param restricts audiences, but cannot add them directly
• the token exchange scope param is able to extend the token (including audience).

It is even possible to only use the scope to add the audience, but "hide" the scope from the access token.
Is this a useful practice?
In our case the backend system will not rely on the scope itself.

You can hide the client scope if you set the Include in token scope to false (like for example in the basicscope). In general, this is the way how keycloak works for all the grants, previously the TE v1 was a weird exception.