Audience Mapper adds UUID of a Client rather than "Client ID"

[Florian Märkl]

Hello all,

I have the following use-case for a service:

- A publicly accessible API requiring user authentication

- A public frontend, accessing this API directly

The frontend should perform the typical OAuth2 access token flow with PKCE to obtain an access token with specific (minimal) rights to access only this one API.

The API should locally validate the access token sent by the frontend. So as part of the jwt validation, the API should also check that itself is specified in the "aud" claim. I am using generic jwt/oidc libraries for this, no Keycloak-specific one.

Since I currently do not use any role-based features, I am following the "Hardcoded audience" section here: https://www.keycloak.org/docs/latest/server_admin/#_audience_hardcoded
Specifically, my example keycloak setup now looks like this:

- Client with client id "my-frontend"

- Client with client id "my-api"

- Client Scope "use-my-api", with mapper "aud-my-api" of type "Audience" with "my-api" in "Included Client Audience" and "Add to access token" enabled

- Client Scope "use-my-api" attached to "my-frontend" as an optional scope

So far so good, I can now get access tokens issued for users logged in through the "my-frontend" client with "my-api" in the "aud" claim. The problem is that the string delivered in "aud" is not the actual Client ID of the API client (which would be "my-api"), but its UUID, for example "930858e4-dd42-467c-9890-f4fecc915dcc" here:

{
  "exp": 1719217653,
  "iat": 1719217593,
  "jti": "3e532635-bc1b-4644-9cc0-cb87db132cf0",
  "iss": "http://127.0.0.1:8080/realms/master",
  "aud": [
    "930858e4-dd42-467c-9890-f4fecc915dcc",
    "account"
  ],
  "sub": "c13f3734-1424-45d5-b176-d0edeb95bdf6",
  "typ": "Bearer",
  "azp": "my-frontend",
  "sid": "b89b0458-b378-4743-b2fb-283df82f2d18",
  "acr": "1",
  (...)
  "scope": "openid email use-my-api profile",
  "preferred_username": "tester"
}

Is this really  the intended behavior? The documentation above states that "A hardcoded audience is a protocol mapper, that will add the client ID of the specified service client as an audience to the token." but this is not the client ID as used for OAuth2, but rather the internal ID of the client in keycloak.

Interestingly, an external tutorial on https://dev.to/metacosmos/how-to-configure-audience-in-keycloak-kp4 also suggests that one should get the clear client id ("bob" and "charles" in their case) in "aud", so I am not sure if maybe my configuration is off.

Of course I could just enter whatever string I want in the "Included Custom Audience" field of the Audience mapper, but this seems wrong in this case where Keycloak already provides this feature of associating a registered client with the mapper.

I am attaching an export of my current test realm for reference.

Thanks in advance for any help!

Best Regards

Florian