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.

Standard Claims

• Issuer (iss): The iss claim specifies the issuer of the access token. It represents the authorization server that issued the token.
• Subject (sub): The sub claim 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 aud claim 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
• Scope (scope): The scope claim specifies the permissions granted to the access token. It defines the actions and resources that the token can access. For example, a token with the read scope may only be able to read data, while a token with the write scope may be able to write data. Some scopes are defined by the OAuth 2.0 specification, while others can be custom scopes defined by the authorization server.
• Expiration Time (exp): The exp claim 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 iat claim 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 nbf claim 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 jti claim provides a unique identifier for the access token. It can be used for tracking or revoking tokens in certain scenarios.

Here is an example of an access token payload containing those standard claims:

{
  "iss": "https://auth.example.com",
  "sub": "1234567890",
  "aud": "https://api.example.com",
  "scope": "read write",
  "exp": 1635200000,
  "iat": 1635196400,
  "nbf": 1635196400,
  "jti": "abc123"
}

Custom Claims

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 tokens 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.