Understanding OAuth 2 Access Token Claims
OAuth 2.x is a widely adopted protocol for securing APIs and providing delegated access to user resources. Access tokens play a vital role in the OAuth flow, serving as credentials to authorize API requests. In this blog post, we will explore the various claims that can be found in OAuth access tokens, shedding light on their purpose and significance.
Introduction to Access Token Claims
Access tokens in OAuth 2.0 and OAuth 2.1 are typically encoded as JSON Web Tokens (JWTs), which consist of a set of claims. Claims are pieces of information contained within the access token payload, providing relevant details about the token, the user, and the authorized permissions.
Issuer (iss): The
issclaim specifies the issuer of the access token. It represents the authorization server that issued the token.
Subject (sub): The
subclaim identifies the subject of the access token, which can be a user or a client (for machine-to-machine). For user access tokens, this claim often contains a unique identifier for the authenticated user (user id).
Audience (aud): The
audclaim identifies the intended audience for the access token. It represents the resource server(s) or service(s) that the token is intended for. For example, if you have resource server(s) for file storage and other resource servers for video streaming, you may restraints access to only one
Expiration Time (exp): The
expclaim indicates the expiration time of the access token. After this time has passed, the token should no longer be considered valid.
Issued At (iat): The
iatclaim specifies the timestamp at which the access token was issued. It can be useful for determining token age and calculating validity periods.
Not Before (nbf): The
nbfclaim indicates the earliest time at which the access token can be considered valid. Tokens presented before this time should be rejected.
Token Identifier (jti): The
jticlaim provides a unique identifier for the access token. It can be used for tracking or revoking tokens in certain scenarios.
Besides the standard claims, OAuth allows for the inclusion of custom claims specific to the application or authorization server. These claims can provide additional context or information needed by the client or resource server.
Client-Specific Information: Custom claims may also include client-specific data, such as application-specific user identifiers or any other relevant information required by the client. Prefer using standard claims when they exist. If you are using OpenID Connect identity layer, you should use OpenID Connect standard claims.
User Roles: Whether custom claims can include information about the user's roles, you should not use OAuth custom claims to pass permission in the system. OAuth is an application authorization protocol firstly designed for handling application authorization, not user permission. For user permission, you should use a permission system like UMA and/or a model like Google Zanzibar.
Access Token Validation and Usage
To ensure the security and integrity of access tokens, it is essential to validate them before accepting and processing requests. The validation process typically involves verifying the signature of the token, checking its expiration time, and ensuring that the token was issued by a trusted authorization server.
Access tokens should be securely transmitted and stored, as they grant access to protected resources. They should only be used by authorized parties and protected from unauthorized access or tampering.