# 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](https://sergiodxa.com/articles/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](https://sergiodxa.com/articles/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](https://sergiodxa.com/articles/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](https://sergiodxa.com/articles/oauth2-for-backend-for-frontend).

---

Want to master secure OAuth2 flows in React Router apps?

📘 My book *React Router OAuth2 Handbook* is now available!

It covers everything from the basics to advanced topics like PKCE, refresh tokens, and E2E auth testing.

→ [books.sergiodxa.com/release](https://go.sergiodxa.com/x6EE88z)