JWT Claims Deep Dive: Registered, Public, and Private Claims

JWT claims are the payload of a JSON Web Token - the actual data being transmitted. Understanding the different types of claims and how to use them effectively is key to building secure and functional JWT-based systems.

Registered Claims (RFC 7519)

These are predefined claims that provide interoperability between JWT implementations:

• iss (Issuer): Identifies the principal that issued the JWT (e.g., "https://auth.example.com")
• sub (Subject): Identifies the principal (usually the user ID)
• aud (Audience): Identifies the recipients the JWT is intended for
• exp (Expiration Time): The time after which the JWT MUST NOT be accepted
• nbf (Not Before): The time before which the JWT MUST NOT be accepted
• iat (Issued At): The time at which the JWT was issued
• jti (JWT ID): A unique identifier for the JWT, useful for revocation

Public Claims

Public claims are defined in the IANA JSON Web Token Claims Registry or in other specifications. They use collision-resistant names (e.g., namespaced as URI). Examples include:

• name: Human-readable name of the subject
• email: Email address of the subject
• role: Role or permission level
• scope: OAuth 2.0 scope granted to the token

Private Claims

Private claims are custom claims agreed upon between producers and consumers. They can carry application-specific data like user preferences, feature flags, or tenant identifiers. Use names that are unlikely to collide with other applications.

Best Practices for Claims

• Keep the payload small - large tokens increase request size and bandwidth usage
• Never include sensitive data - the payload is Base64-encoded, not encrypted
• Always validate the exp, nbf, and aud claims
• Use the jti claim for token tracking and revocation
• Include the iss claim to prevent token confusion attacks

Claims in OpenID Connect

OpenID Connect ID Tokens use standardized claims defined by OpenID Connect Core specification, including auth_time, nonce, acr, amr, and at_hash. These provide additional security guarantees for authentication flows.

Conclusion

JWT claims form the backbone of token-based identity and authorization. Using them correctly with proper validation ensures both security and functionality in your applications.