ai-chat/docs/OIDC_AUDIENCE.md

OIDC Audience (aud) — explanation and guidance

Why aud matters

• The aud (audience) claim in a JWT indicates the intended recipient(s) of the token.
• Your API should verify aud to ensure the token was issued for this service, preventing tokens meant for other services from being used against your backend.

How this project handles aud

• OIDC_AUDIENCE is optional in this scaffold.
• If OIDC_AUDIENCE is set in the environment, the backend will validate that the token's aud claim matches that value.
• If OIDC_AUDIENCE is not set, the backend will skip audience validation (the token still must be valid and optionally matched to iss).

Security guidance

• Production: set OIDC_AUDIENCE to the identifier your provider includes in access tokens for this API. This is typically:

  • The API identifier or Resource URI you configured in Auth0
  • The client ID (or api://<client-id>) in Azure AD when you configured an app registration
  • The audience or client for Keycloak realm resources

• Local dev: it can be convenient to omit OIDC_AUDIENCE when using non-standard tokens or test setups, but avoid this in production.

Provider-specific notes

• Auth0: configure an API and use its Identifier as the audience when requesting tokens. The access token will contain that audience.
• Keycloak: check the client/realm settings; the aud may be the client id or an array of client ids.
• Azure AD: access tokens may use aud = api://<client-id> or your Application (client) ID URI.

How to discover the correct value

1. Request a token from your provider (or use the issuer's test token).
2. Decode the JWT (jwt.io or python-jose) and inspect the aud claim.
3. Set OIDC_AUDIENCE to that value in your .env.

If you want, paste an example decoded token (redact sensitive fields) and I can tell you the exact value to use for OIDC_AUDIENCE.