OAuth2 Access Token Claims Explained

JWTs are commonly used as access tokens in OAuth2, containing claims that define identity, security, and permissions. However, many developers misuse or fail to validate these claims properly, leading to security risks.

Let's break down the most important JWT claims and how to use them correctly.

What Are JWT Claims?

JWTs contain claims, which are key-value pairs that store information about the token and the authenticated user.

Claims fall into three categories:

  • Registered claims → Standard claims defined in the JWT specification.
  • Public claims → Custom claims that follow a namespace convention.
  • Private claims → App-specific claims that aren't standardized.

Common Registered Claims in OAuth2 Access Tokens

Here are some of the most common claims in OAuth2 access tokens:

  • iss (Issuer) → Identifies who issued the token.
  • sub (Subject) → Represents the user ID the token is issued for.
  • aud (Audience) → Defines the intended recipient of the token.
  • exp (Expiration) → Specifies when the token expires.
  • iat (Issued At) → Indicates when the token was created.
  • nbf (Not Before) → Defines when the token starts being valid.

These claims play a crucial role in authentication and security.

Using the sub (Subject) Claim Correctly

The sub claim uniquely identifies the user the token is for.

  • ✅ Best practice: Store a unique, immutable identifier like a UUID or database ID.
  • ❌ Bad practice: Using mutable values like usernames or emails, which can change over time.

Why the aud (Audience) Claim Matters for Security

The aud claim ensures that a token is used by the correct API.

  • ✅ APIs must reject tokens if aud does not match the expected value.
  • ✅ Avoid using multi-audience tokens unless absolutely necessary.

If an access token is leaked, aud prevents it from being used on an unintended API. Proper audience validation is a key security measure in OAuth2, as explained in OAuth2 Audience Explained.

Handling Expiration with exp, iat, and nbf

  • exp (Expiration) → The token must not be accepted after this timestamp.
  • iat (Issued At) → Helps prevent replay attacks.
  • nbf (Not Before) → The token cannot be used before this timestamp.

APIs should always validate the expiration time before processing a request.

Using scope to Define Permissions

OAuth2 scopes limit what an access token can do.

For example:

  • read:contacts → Can view contacts.
  • write:contacts → Can modify contacts.

The API should check the scope claim before allowing an operation. Scopes play a crucial role in access control, defining which actions a token is authorized for, as detailed in OAuth2 Scopes Explained.

Other Common Claims in OAuth2 Access Tokens

In addition to the standard claims, some OAuth2 providers add extra claims for more security and context:

  • azp (Authorized Party) → Identifies the client that requested the token.
  • auth_time (Authentication Time) → When the user authenticated.
  • tenant_id → Used in multi-tenant authentication systems.
  • amr (Authentication Methods Reference) → How the user authenticated (mfa, password).
  • email_verified → Indicates whether the user’s email is verified.

These claims can enhance security but must be validated properly.

Common Mistakes When Handling JWT Claims

  • ❌ Not validating aud → Accepting tokens meant for another API.
  • ❌ Ignoring exp → Letting expired tokens be used.
  • ❌ Using mutable values in sub → Can cause identity conflicts.
  • ❌ Trusting custom claims blindly → Always validate claims at the API level.

A common debate in OAuth2 is whether to use JWTs or opaque tokens as access tokens. Each has its own advantages and trade-offs, which are discussed in depth in JWT vs. Opaque Tokens.

Learn More About OAuth2 in Remix & React Router

If you're building OAuth2 authentication in a React Router or Remix application, using JWTs as access tokens can be beneficial, but it's often better to handle tokens securely in a Backend-for-Frontend (BFF). This approach centralizes authentication, improves security, and avoids exposing tokens in the frontend, as explained in OAuth2 for Backend-for-Frontend.

I'm currently writing a book called React Router OAuth2 Handbook, focused on implementing secure OAuth2 authentication in Remix and React Router apps—using patterns you can apply to any web app.

The landing page is live (book coming soon) at books.sergiodxa.com