A claim is a named statement or attribute carried in a security token. In a JWT, claims appear in the payload and describe the subject, such as its identity, API access, role, scope, issuer, audience, or expiration. Access-token claims support authorization; ID-token claims describe identity and must not be used to validate API access. section 7.2.1 section 7.2.2
Claims commonly serve these purposes:
- Identify the token’s issuer, subject, audience, issuance time, expiration, validity start, or unique identifier through registered claims such as iss, sub, aud, exp, nbf, iat, and jti. section 7.2.2
- Represent roles and permissions through custom claims, such as a permissions array containing an admin role. section 7.7 section 4.7
- Express granular access scopes when users need different operation-level permissions rather than membership in fixed role groups. section 7.7
- Describe authentication context and user identity in an OpenID Connect ID token, including optional claims such as auth_time, acr, and amr. section 7.6
Authorizing an admin endpoint
An API validates the access token, captures its claims, and checks whether the permissions claim contains admin. If the claim is absent, the endpoint rejects the request with 403 Forbidden because the caller has valid credentials but insufficient permissions. A sensitive endpoint may instead return 404 Not Found. section 4.8 section 8.6
Listing 4.11 Mitigating BFLA vulnerabilities
# file: ch04/bfla.py
@server.get("/admin")
def get_admin(user_claims: UserClaims = Depends(validate_token)):
if "admin" in user_claims.permissions: #1
return "success!" #2
raise HTTPException( #3
status_code=403, detail=f"Forbidden"
)
Shows the focused implementation pattern: validate the token, inspect user_claims.permissions, and reject callers without the admin role. section 4.8
Claims are useful only when the token is validated correctly. Validation checks the signature with an allowed algorithm and key, constrains issuer and audience, and verifies expiration. Authorization must then check the relevant role, permission, or scope on every protected request. Skipping that check can create broken function-level authorization, allowing ordinary users to reach administrative functionality. section 8.3 section 4.7
