JWT Claims Explained

Claims are statements about an entity (typically, the user) and additional metadata that are included in a JWT payload. This guide explains the different types of claims, their purposes, and best practices for using them effectively.

Types of JWT Claims

JWT claims are categorized into three types:

Registered Claims

Predefined claims recommended by the JWT specification (RFC 7519) to provide a set of useful, interoperable claims.

Public Claims

Claims defined by those using JWTs, but registered in the IANA JSON Web Token Registry or defined as a URI to avoid collisions.

Private Claims

Custom claims created to share information between parties that agree on using them and are neither registered nor public claims.

Registered Claims

Registered claims are a set of predefined claims that are not mandatory but recommended to provide a set of useful, interoperable claims. Here are the most important registered claims:

Claim	Name	Description	Example
`iss`	Issuer	Identifies the principal that issued the JWT	`"iss": "https://auth.example.com"`
`sub`	Subject	Identifies the principal that is the subject of the JWT	`"sub": "1234567890"`
`aud`	Audience	Identifies the recipients that the JWT is intended for	`"aud": "https://api.example.com"`
`exp`	Expiration Time	Identifies the expiration time on or after which the JWT must not be accepted for processing	`"exp": 1516239022`
`nbf`	Not Before	Identifies the time before which the JWT must not be accepted for processing	`"nbf": 1516239022`
`iat`	Issued At	Identifies the time at which the JWT was issued	`"iat": 1516239022`
`jti`	JWT ID	Provides a unique identifier for the JWT	`"jti": "a-123"`

Time-Based Claims

The time-based claims (exp, nbf, iat) use the NumericDate format, which is a JSON numeric value representing the number of seconds from 1970-01-01T00:00:00Z UTC until the specified UTC date/time.

Note: Time-based claims are represented as Unix timestamps (seconds since the epoch). Make sure to handle timezone differences correctly in your application.

Public Claims

Public claims are claims that are defined by those using JWTs but should be registered in the IANA JSON Web Token Registry or be defined as a URI that contains a collision-resistant namespace.

Examples of public claims include:

name: Full name
given_name: Given name
family_name: Family name
email: Email address
picture: Profile picture URL

The full list of registered public claims can be found in the IANA JSON Web Token Registry.

Private Claims

Private claims are custom claims created to share information between parties that agree on using them. These claims are neither registered nor public claims.

Examples of private claims might include:

{
  "user_id": "B12345",
  "role": "admin",
  "permissions": ["read", "write", "delete"],
  "organization": "acme_corp",
  "plan": "premium"
}

Warning: Be careful with naming private claims to avoid collisions with registered or public claims. Consider using a namespace prefix for your private claims (e.g., https://example.com/claims/role or example_role).

Best Practices for JWT Claims

Security Considerations

Always Include Expiration: Always include an exp claim to limit the lifetime of tokens.
Keep Tokens Small: Include only necessary claims to keep tokens small and efficient.
No Sensitive Data: Never include sensitive information in JWT claims as they are easily decoded.
Validate All Claims: Always validate all claims on the server side, especially time-based claims.
Use Audience: Include the aud claim to specify the intended recipient of the token.

Implementation Tips

Short Expiration Times: Use short expiration times (minutes to hours, not days) for access tokens.
Use Refresh Tokens: Implement refresh tokens for obtaining new access tokens without re-authentication.
Include Issuer: Always include the iss claim to identify the token issuer.
Use JWT ID: Include a jti claim for token revocation capabilities.
Consistent Time Handling: Ensure consistent handling of time-based claims across different systems.

Example JWT Payload with Claims

Here's an example of a JWT payload with various types of claims:

{
  // Registered claims
  "iss": "https://auth.example.com",
  "sub": "1234567890",
  "aud": "https://api.example.com",
  "exp": 1516239022,
  "nbf": 1516238022,
  "iat": 1516238022,
  "jti": "id123456",
  
  // Public claims
  "name": "John Doe",
  "email": "john@example.com",
  
  // Private claims
  "user_id": "U12345",
  "role": "admin",
  "permissions": ["read", "write", "delete"],
  "organization": "acme_corp"
}

Conclusion

Understanding JWT claims is essential for implementing secure and effective authentication and authorization systems. By following best practices and using claims appropriately, you can create tokens that are both secure and functional.

Next Steps

Explore JWT Vulnerabilities Learn Secure Implementation