Implementing Claims-Based Identity
1. Understanding Claims Concepts
| Term | Detail |
|---|---|
| Claim | Name/value assertion about subject |
| Issuer | Authority making the claim |
| Subject | Entity claim describes |
| Container | JWT, SAML Assertion, X.509 cert |
2. Creating Claims
Example: Claims in token
{
"sub": "user_42",
"email": "alice@example.com",
"email_verified": true,
"https://app.example/tenant": "acme",
"https://app.example/roles": ["admin", "billing"],
"iss": "https://auth.example",
"exp": 1715000000
}3. Using Standard Claim Types
| Spec | Examples |
|---|---|
| JWT (RFC 7519) | iss, sub, aud, exp, nbf, iat, jti |
| OIDC standard | name, email, picture, address, phone |
| SAML | NameID + attribute statements |
| SCIM (RFC 7643) | userName, emails, groups, active |
4. Implementing Custom Claims
| Practice | Detail |
|---|---|
| Namespace | URI prefix: https://app/tenant |
| Size | Keep tokens < 1KB |
| PII | Avoid sensitive data — JWT is signed not encrypted |
| Stability | Don't break consumers; version namespace |
5. Validating Claims
| Claim | Validation |
|---|---|
| iss | Matches expected issuer |
| aud | Includes this service |
| exp / nbf | Now within window (±60s skew) |
| scope | Required scope present |
| azp | Authorized client |
6. Transforming Claims
| Transformation | Example |
|---|---|
| Rename | upn → email |
| Filter | Drop sensitive claims for downstream services |
| Enrich | Add tenant, plan from DB lookup |
| Map values | IdP groups → app roles |
7. Using Claims for Authorization
Example: Claim-based check
@PreAuthorize("@auth.hasClaim('plan', 'premium')")
public Report generateAdvancedReport() { ... }8. Implementing Claims-Based Policies
| Policy Type | Detail |
|---|---|
| Required claim | Must have plan=premium |
| Claim value range | age > 18 |
| Combined | role=admin AND mfa_level=strong |
| Spring | .requiresClaim("plan", "premium") |
9. Handling Claims in JWT
| Consideration | Detail |
|---|---|
| Size | Minimize — affects every request |
| Freshness | Claims stale until token refresh |
| Visibility | Base64 — anyone with token can read |
| Arrays | Roles/groups as JSON arrays |
10. Implementing Claims Enrichment
| Hook Point | Detail |
|---|---|
| Token issuance | Add custom claims from DB/external (Auth0 Actions, Okta hooks) |
| Token exchange | RFC 8693 transform claims downstream |
| API gateway | Add claims at edge based on user lookup |
| Caveat | Hook latency adds to login time |