oicd_audience removal

docs/OIDC_AUDIENCE.md

@@ -0,0 +1,35 @@
+# 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`.