Guide Updated

JWT aud Claim (Audience)

The JWT aud (audience) claim identifies which service should accept the token. Learn the aud validation rule, how multiple audiences work, and how to fix Spring Security's 'Audiences in jwt are not allowed' error.

The `aud` (audience) claim identifies the intended recipients of the JWT. Only the intended recipient should accept the token. It is defined in RFC 7519 §4.1.3 and is the most commonly skipped: and most dangerous to skip: registered claim.

Format and values

`aud` is either a single string or an array of strings. A single audience: `"aud": "https://api.example.com"`. Multiple audiences: `"aud": ["https://api.example.com", "https://dashboard.example.com"]`.

Validation rule

The verifier checks whether its own identifier appears in the `aud` value. If `aud` is a string, it must match exactly. If `aud` is an array, the expected audience must be present somewhere in the array. The check is case-sensitive. Always pass your expected audience explicitly to the verification call: most JWT libraries do not enforce `aud` unless you opt in.

Common mistakes

  • Skipping aud validation because you trust the issuer. The issuer may issue tokens for other services too: a token meant for your analytics service should not be accepted by your payments service even though the signature is valid.
  • Assuming your library validates aud by default. Many libraries make it opt-in. Test it: issue a token with the wrong audience, verify without specifying an expected audience, and confirm the library rejects it. If it accepts, configure the check explicitly.
  • Encoding tenant identity into aud in a multi-tenant system. Use a separate private claim (tenant_id) alongside aud; aud identifies the service, not the tenant.

Code examples

Validate aud (Node.js: jsonwebtoken)

          jwt.verify(token, secret, {
  algorithms: ["HS256"],
  audience: "https://api.example.com",   // rejects tokens for other services
});

Validate aud (Java: Spring Security)

          // application.yml (Spring Boot 3.1+)
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          jwk-set-uri: https://YOUR_DOMAIN.auth0.com/.well-known/jwks.json
          audiences:
            - https://api.example.com

Frequently asked questions

  • What is the aud claim in a JWT?

    aud (audience) is an RFC 7519 registered claim that identifies the intended recipient(s) of the JWT. It is either a single string or an array of strings. The verifier checks whether its own identifier appears in aud and rejects the token if it does not. aud prevents a token issued for one service from being replayed against another that shares the same signing key (the confused deputy attack).

  • Why is my JWT aud rejected with 'Audiences in jwt are not allowed'?

    This Spring Security error means the token's aud does not contain the audience Spring's decoder is configured to expect. The fix is to align the token's aud claim with the audience configured in application.yml (spring.security.oauth2.resourceserver.jwt.audiences) or in your custom OAuth2TokenValidator. Do not disable the audience validator to make the error go away: that opens a confused-deputy attack. See the /verify/java/ guide for the full troubleshooting walkthrough and code.

  • Can a JWT have multiple audiences?

    Yes. aud is defined as either a single string or an array of strings. A token with aud: ['https://api.example.com', 'https://dashboard.example.com'] is valid for either service; each verifier checks whether its own identifier appears anywhere in the array. Use multiple audiences when one token legitimately authorizes access to several related services owned by the same provider. Avoid putting unrelated audiences in the same token: each extra audience expands the attack surface if any service skips aud validation.

Related