36 lines
1.8 KiB
Markdown
36 lines
1.8 KiB
Markdown
# 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`.
|