andrea-chiarelli

I have over 20 years of experience as a software engineer and technical author. Throughout my career, I've used several programming languages and technologies for the projects I was involved in, ranging from C# to JavaScript, ASP.NET to Node.js, Angular to React, SOAP to REST APIs, etc.

In the last few years, I've been focusing on simplifying the developer experience with Identity and related topics, especially in the .NET ecosystem.

Principal Developer Advocate

Andrea Chiarelli

Dive deep into the common myths surrounding JSON Web Tokens (JWTs), from their security to their role as access tokens, and why they aren't a one-size-fits-all solution for session management.

JSON Web Tokens, or JWTs, are a cornerstone of modern application security and API protection. You've likely encountered them when implementing login flows, securing microservice communication, or working with standards like OAuth 2.0 and OpenID Connect. Their popularity, however, has given rise to a series of persistent myths and dangerous anti-patterns.

Many developers treat JWTs as a magical black box, leading to implementations that are either insecure or overly complex. Believing these myths can expose your application to significant vulnerabilities.

In this article, we will dissect and debunk five of the most common misconceptions about JWTs. By understanding what a JWT is&mdash;and what it isn't&mdash;you can leverage its power correctly and build more secure and robust systems.

## Myth 1: A JWT Is Just Another Name for a Token

One of the most fundamental misunderstandings is that "token" and "JWT" are synonymous. While a JWT is a type of token, not all tokens are JWTs.

A "token" in the general sense is simply a piece of data that represents a fact, usually an authorization grant. Historically, many of these tokens have been **opaque strings**. An opaque token is a random, meaningless string from the client's perspective. It acts as a reference, like a ticket stub. To get any information from it (like who the user is or what permissions they have), the receiving server must make a call back to the issuing server. Here is an example of an opaque token:

```shell
w3VzBypV4S1zaYd1-390AFda9d1t3-A4fWsdr23as
```

In contrast, a JSON Web Token (JWT) is a **structured token**. As defined in [RFC 7519](https://tools.ietf.org/html/rfc7519), a JWT is a compact, URL-safe means of representing claims to be transferred between two parties. It's not opaque; it's a self-contained JSON object that is digitally signed or encrypted.

> To learn more about JWTs, check out the [JWT Handbook](https://auth0.com/resources/ebooks/jwt-handbook) and use [jwt.io](http://jwt.io) to decode them.

Because it's self-contained, a service that trusts the issuer can validate a JWT and use its claims without needing to contact the issuer. **This is the core benefit of JWTs: stateless, decentralized validation**.

## Myth 2: JWT and Access Token Are Interchangeable Terms

This myth often follows the first. In OAuth 2.0 terminology, an **access token** is a credential used by a client to access protected resources. The crucial detail is that the OAuth 2.0 specification *does not mandate a specific format* for access tokens. They can be opaque tokens, or they can be JWTs.

So, why the confusion? JWTs have become a very popular format for access tokens. The benefits are clear:

* A resource server (e.g., a web API application) can validate a JWT-based access token without calling the authorization server on every request. It just needs the issuer's public key to check the signature.  
* The token itself can carry essential data, such as the user ID and [permissions (scopes)](https://auth0.com/blog/permissions-privileges-and-scopes/), reducing the need for extra database lookups.

However, an authorization server could just as easily issue an opaque access token and require resource servers to validate it via an [introspection endpoint](https://datatracker.ietf.org/doc/html/rfc7662). This stateful approach offers a major benefit: the token can be revoked instantly.

As a takeaway, remember that an access token is a *concept*&mdash;a key that unlocks a door. A JWT is a *format* for that key. You can have an access token that is not a JWT, but you can't say a JWT is always an access token, as it could be an [ID token](https://auth0.com/blog/id-token-access-token-what-is-the-difference/) or used for other purposes.

## Myth 3: JWTs Are Vulnerable Because Their Payload Is Readable

As mentioned before, you can decode a JWT by using [jwt.io](http://jwt.io). The following screenshot shows the content of a test JWT:

![The jwt.io debugger showing the decoded header and payload of a sample JSON Web Token, demonstrating that the payload data is visible by default.](https://images.ctfassets.net/23aumh6u8s0i/m0lLoapwO9AvmrYuLOdi9/aabdf7590adc697c787b1d3aa433bbe5/jwt-decoder-online.png)

A common reaction upon seeing a JWT for the first time is alarm. "I can decode this\! The data is exposed\! JWT is an insecure format\!"

A standard JWT is normally signed. Its payload is simply Base64Url encoded, not encrypted. You can easily paste the payload into any Base64 decoder and read its contents.

This visibility is by design. The purpose of the signature on a JWT is to guarantee **integrity** and **authenticity**, not **confidentiality**. The signature ensures that:

1. The data has not been tampered with since it was signed.  
2. The token was genuinely created by the party holding the signing key.

You should **never** put sensitive or secret information in the payload of a JWT. If you need confidentiality, you must use [JWE (JSON Web Encryption)](https://auth0.com/docs/secure/tokens/access-tokens/json-web-encryption), which encrypts the payload.

## Myth 4: A Signature Makes a JWT Inherently Secure

The signature is the most critical security feature of a JWT, but it's not a silver bullet. A signature is only as strong as the processes around it. Believing that "it's signed, so it's safe" is a dangerous oversimplification.

For a signed JWT to be truly secure, you must:

- **Use a strong algorithm:** Always use strong signing algorithms like [`RS256` or `ES256`](https://auth0.com/blog/rs256-vs-hs256-whats-the-difference/). Critically, your validation library **must** prevent the "none" algorithm attack, where an attacker strips the signature and changes the `alg` header to `"none"`.  
- **Validate all relevant claims:** A valid signature only proves the token hasn't been modified. It doesn't mean the token is still usable. You must always validate the standard claims:  
   * `exp`: Is the token expired?  
   * `nbf`: Is the token being used before it's valid?  
   * `iss`: Was the token issued by the authority you trust?  
   * `aud`: Was this token intended for your service (the audience)?  
- **Protect your signing keys:** If an attacker steals your symmetric secret (`HS256`) or your private key (`RS256`), they can forge valid tokens for any user. Key management is paramount.  
- **Transmit securely:** Always transmit JWTs over a secure channel (HTTPS) to prevent man-in-the-middle attacks from stealing the token in transit.

A signature doesn't protect against token theft via [Cross-Site Scripting (XSS)](https://auth0.com/blog/cross-site-request-forgery-csrf/) or compromised client devices. It's one piece of a larger security puzzle.

## Myth 5: JWTs Are a Modern Replacement for Sessions

This is perhaps the most contentious and widely debated myth. Many tutorials present JWTs as the "modern" way to handle user sessions, replacing old-fashioned server-side sessions. This is a misleading and often harmful narrative.

Traditional server-side sessions store session data on the server and give the client a simple, opaque session ID (usually in an `HttpOnly` cookie). JWTs, when used for sessions, move this state to the client inside the token.

This "stateless" approach has a massive drawback for user sessions: **revocation is extremely difficult**.

* **You can't easily log a user out:** If a user clicks "log out," how do you invalidate their JWT? It remains valid until its expiration time.  
* **A compromised token is a lasting threat:** If a JWT is stolen, the attacker can use it until it expires. You have no immediate way to kill that session.

Workarounds like blocklisting tokens exist, but they reintroduce server-side state, defeating the primary purpose of using JWTs for statelessness in the first place. At that point, you've just built a more complicated version of traditional sessions.

JWTs excel for short-lived, transactional scenarios where statelessness is a key architectural driver (e.g., authorizing a request in a microservices mesh). For managing user login state, the ability to centrally manage and instantly revoke sessions often makes the "old-fashioned" server-side session model a safer and simpler choice.

<include src="ebook-ads/JwtHandbook" />

## Myths at a Glance

When applied correctly, JSON Web Tokens are a powerful and useful specification. They provide a standard for creating self-contained, verifiable tokens ideal for stateless systems and inter-service communication.

However, understanding their limitations is just as important as knowing their benefits. Here is a quick recap of the myths analyzed in this article:

![A summary table debunking five common JWT myths, covering topics like JWT security, access tokens vs. JWTs, payload visibility, signature security, and session management.](https://images.ctfassets.net/23aumh6u8s0i/P4pyLFEAKbhF9OKDX4Ss3/74a24471de857f1b8465b79aa31ce9d7/jwt-myths-vs-reality.png)

By moving past these common myths, you can make more informed architectural decisions. Don't treat JWTs as a generic solution for all things authentication and session-related. Instead, see them as a specialized tool in your developer toolkit—one that is incredibly effective when used for the right job.

Five Myths About JWTs Debunked

A deep dive into OAuth 2.0 access tokens and the principle of least privilege to enhance your application's security by correctly scoping tokens and implementing robust validation strategies.

In the context of modern application security, access tokens play a prominent role in authorization. They are the digital keys that grant applications access to protected resources on behalf of a user. However, with great power comes great responsibility. A compromised access token can be a significant security liability. This is where the [principle of least privilege](https://csrc.nist.gov/glossary/term/least_privilege) (PoLP) becomes not just a best practice, but a critical defense mechanism.

This article takes a deep dive into the intersection of access tokens and the principle of least privilege, with a focus on leveraging the capabilities of [OAuth 2.0](https://auth0.com/intro-to-iam/what-is-oauth-2) to build more secure and resilient systems. We'll explore the foundational concepts, advanced techniques, and provide a practical checklist for your security reviews.

## What is the Principle of Least Privilege?

The **principle of least privilege** is a core concept in computer security. It states that users, programs, or processes should only be granted the minimum permissions necessary to perform their function. In other words, every component within a system should operate with the lowest possible level of access, or 'privilege', required for its tasks.

Think of it like giving keys to a building. Instead of giving every employee a master key that opens every door (*high privilege*), you give each person only the keys to the specific rooms they actually need to access (*least privilege*). For example, a receptionist gets a key to the front desk area, a developer gets a key to their office, but neither has access to the executive offices unless explicitly required.

This approach enhances security by **limiting the potential damage from an accident, error, or security breach**. If an account with limited privileges is compromised, the attacker's access is confined to a small controlled area, preventing them from gaining control over the entire system. Therefore, applying this principle means ensuring that applications and users can only access the specific data and perform the exact actions they are explicitly authorized to do, and nothing more.

## OAuth 2.0 and its Role in Access Control

At its core, OAuth 2.0 is an authorization framework, not an authentication protocol. This distinction is crucial. While authentication is about verifying identity, authorization is about granting permission to access specific resources. OAuth 2.0 provides a standardized way for a client application to obtain an access token from an authorization server, with the user's consent, to access resources hosted by a resource server.

A solid grasp of the OAuth 2.0 components is essential for implementing the principle of least privilege. Let’s quickly recap them:

* **Roles:**  
  * **Resource Owner:** The user who owns the data and grants permission to the application.  
  * **Client:** The application requesting access to the user's data.  
  * **Authorization Server:** The server that authenticates the resource owner and issues access tokens after obtaining their consent, e.g., Auth0.  
  * **Resource Server:** The server that hosts the protected resources and accepts access tokens for authorization, typically implemented as an API.  
* **Tokens:**  
  * **Access Token:** A credential used by the client to access protected resources. It represents the authorization of a specific client to access specific resources.  
  * **Refresh Token:** A long-lived credential used to obtain a new access token when the current one expires.  
* **Scopes:** The mechanism within OAuth 2.0 that allows us to define the granular permissions a client can request.

With this basic knowledge, let's delve deeper into how to implement the LP principle in a system protected by access tokens.

> For a deeper understanding of OAuth 2.0, consider reading [OAuth 2.0 and OpenID Connect: The Professional Guide](https://auth0.com/resources/ebooks/oauth-openid-connect-professional-guide).

## Scopes: The Heart of Least Privilege in OAuth 2.0

The true power of OAuth 2.0 in enforcing the principle of least privilege lies in the effective use of [scopes](https://auth0.com/blog/permissions-privileges-and-scopes/). Scopes are strings that define the specific permissions a client application is requesting. Unlike [OpenID Connect](https://auth0.com/docs/get-started/apis/scopes/openid-connect-scopes), OAuth 2.0 does not define standard scopes. The scopes used in an application scenario depend on the specific business case. Specifically, they are defined by the resource server (API) implementer and must be known to the client application. When designing the scopes for your API, follow a few best practices.

### No scopes, No party!

While the OAuth 2.0 specification does not explicitly forbid a client from [requesting an access token without a `scope` parameter](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1), doing so represents a significant security anti-pattern and a direct violation of the principle of least privilege.

When a client initiates an authorization request without specifying any scopes, [the authorization server's behavior can be ambiguous](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3). Since the OAuth 2.0 specifications do not define a standard behavior to handle this case, your application can receive an error message or a subset of predefined scopes, possibly empty.

Moreover, if API implementations do not accurately check scopes, you may find yourself in a scenario where the issued access token essentially grants the full permissions of the user.

This practice carries substantial risk. If a scopeless access token is compromised—leaked from a client-side application, intercepted in transit, or exfiltrated from a backend system—the attacker gains broad, unrestricted access to the user's resources. They could potentially read sensitive data, modify information, and perform actions on behalf of the user, all because the token's power was not constrained.

As a result, avoid scopeless access tokens. Always include the `scope` parameter in your application's authorization requests, and make your APIs always check for the expected scopes.

### Designing granular scopes

Vague or overly broad scopes defeat the purpose of least privilege. Consider an e-commerce API. You may think of scopes like `orders` or `profile` to allow access to the user’s orders and profile. However, these scopes are not explicit on the type of access they grant. Probably the `orders` scope says that your application can manage orders, i.e., it can read, create, update, print, for example. A more granular approach would be:

* `orders:read`: Allows the client to read a user's order.  
* `orders:write`: Allows the client to create new orders.  
* `profile:read`: Allows the client to read the user's profile information.  
* `profile:write`: Allows the client to update the user's profile.

This granularity ensures that a third-party analytics dashboard, for example, would only ever request and be granted the `orders:read` scope, mitigating the potential damage if its access token were to be compromised.

The following picture visually summarizes the application of the principle of least privilege using granular scopes:

<picture>
<img src="https://images.ctfassets.net/23aumh6u8s0i/4qzpht7LRcPnUerDwZXs07/6e09324185fd2afd7aa3488d1655b671/access-tokens-with-and-without-least-privilege.png" alt="A diagram comparing API access with and without the principle of least privilege, showing how OAuth 2.0 access tokens can provide granular, limited access for better API security." style="width:75%; margin: 0px auto;">
</picture>

### Leveraging hierarchical scopes

OAuth 2.0 does not strictly specify the format of scopes. They are generic strings whose meaning depends on the API context. As illustrated in the examples above, a common approach is to use the format `resource:action`. Some use the dot (`.`) as a separator instead of the colon (`:`). It really does not matter.

While you are free to use the format you prefer, consider taking advantage of the hierarchical structure of the format suggested above. For example, if you want to grant access only to the status of an order for informational purposes, but not at the details of the order, you can define a scope like `orders:status:read`. This allows you to have more granular control over a protected resource.

For more advanced scenarios, you may consider using [OAuth 2.0 Rich Authorization Requests](https://datatracker.ietf.org/doc/html/rfc9396), which allows you to specify detailed authorization requests.

### Using dynamic scopes

Modern applications often require different levels of access at different times. Instead of requesting all possible permissions upfront, a better user experience and security practice is to request scopes dynamically as needed. For instance, an application could initially request `profile:read` on user sign-up. Later, when the user wants to perform an action that requires more permissions, such as updating their profile, the application can initiate a new OAuth 2.0 flow to request the `profile:write` scope. This adheres to the principle of just-in-time access.

### Ensuring user consent

[User consent](https://auth0.com/docs/get-started/applications/confidential-and-public-applications/user-consent-and-third-party-applications) is a critical component in OAuth 2.0 authorization requests, directly supporting the principle of least privilege.

The authorization server must obtain explicit approval from the user, ensuring they understand and consent to the specific access an application client is requesting on their behalf. This consent should be freely given, with adequate information provided to the user.

In this context, a user-friendly description of the scopes a client application is requesting is key. The user should be aware of the permissions they are delegating to the application.

> A key aspect is that scopes do not create new permissions; they merely represent **a subset of the permissions the user already possesses** and delegated to the client application.

## Beyond Scopes: Advanced Token Security and Validation

While scopes are the primary tool for defining what an application can do on behalf of the user, a comprehensive strategy for least privilege involves more than just well-designed scopes. You must also consider the entire lifecycle of an access token.

### Token validation best practices

At the resource server, every incoming access token must be rigorously validated before granting access. This validation should go beyond simply checking the token's signature and expiration. Here are the fundamental steps to validate an access token before granting the application access to the resource:

1. **Signature Verification:** Always verify the token's signature against the authorization server's public key. This ensures the token was issued by a trusted source and has not been tampered with.  
2. **Expiration Check:** Check the `exp` claim to ensure the token has not expired.  
3. **Issuer and Audience Validation:** Verify the `iss` (issuer) and `aud` (audience) claims. The `iss` should match the expected authorization server, and the `aud` should match your resource server. This prevents tokens issued for one application from being used to access another.  
4. **Scope Enforcement:** This is the critical step for least privilege. The resource server must check the `scope` claim in the access token and ensure that the requested action is permitted by the granted scopes.  
5. **User Permissions Check**: Last but not least, make sure that the resource your application is requesting to access is actually accessible by the user with the permissions matching the scopes. Read [this article](https://auth0.com/blog/on-the-nature-of-oauth2-scopes/) to learn more about this.

### Short-lived access tokens and refresh tokens

In addition to a correct design and use of scopes, the management of access tokens is a critical security component adhering to the principle of least privilege. A key strategy to bolster security is the implementation of short-lived access tokens. The rationale behind this approach is to drastically reduce the "*window of opportunity*" for a potential attacker. If an access token, which grants an application permission to access specific resources, were to be compromised, its utility would be severely limited by its short lifespan.

Typically, these short-lived access tokens are issued with a validity period ranging from a few minutes to a few hours, depending on the business case and the security level required.This brevity is a deliberate security measure connected to the principle of least privilege: not only your application must have the minimum permissions it needs, but it must have them for the minimum amount of time necessary. However, to ensure a seamless user experience without requiring re-authentication every few minutes, a complementary mechanism is employed: [refresh tokens](https://auth0.com/docs/secure/tokens/refresh-tokens).

When an access token expires, the client application can use the refresh token to request a new, valid access token from the authorization server. This process is transparent to the user, maintaining a continuous session.

Given their power to grant new access tokens, refresh tokens themselves must be securely managed to prevent security issues. Learn more [about refresh tokens by reading this article](https://auth0.com/blog/refresh-tokens-what-are-they-and-when-to-use-them/).

<include src="ebook-ads/Oauth2OidcGuide" />

## Security Review Checklist for Access Token-Based Systems

To assist in your development and review process, here is a checklist to help ensure you are adhering to the principle of least privilege and other access token security best practices.

**Scope and Permissions**

* Are scopes granular and well-defined, following the principle of least privilege?  
* Does the application request only the necessary scopes at any given time?  
* Is there a process for users to review and consent to the requested scopes?  
* Are there different levels of scopes for read vs. write vs. administrative actions?

**Token Issuance and Lifecycle**

* Are access tokens short-lived?  
* Are refresh tokens used to obtain new access tokens?  
* Are refresh tokens stored securely on the client?  
* Is there a mechanism to revoke refresh tokens and access tokens?

**Token Validation at the Resource Server**

* Is the token's signature verified on every request?  
* Is the token's expiration (`exp` claim) checked?  
* Is the issuer (`iss` claim) validated against a trusted value?  
* Is the audience (`aud` claim) validated to ensure the token is intended for this API?  
* Is the `scope` claim inspected, and are the permissions enforced for the requested operation?

## Conclusion

Building secure applications is not an afterthought but a core responsibility. The principle of least privilege is a powerful paradigm for mitigating the risks associated with access tokens. By meticulously designing granular scopes, implementing robust token validation, and managing the token lifecycle effectively, you can significantly enhance the security posture of your applications.

The OAuth 2.0 framework provides the tools necessary to implement a least privilege model, but it is your responsibility as developers to use them correctly and diligently. By following the best practices and using the checklist provided, you can be more confident in the security and resilience of your access token-based systems.

OAuth 2.0 Access Tokens and the Principle of Least Privilege

Sam4-square

I'm an Identity nerd with many years of experience as a developer and advocate. I love explaining complex topics clearly and understandably. You can find me on stage at developer events worldwide or simply having great conversations in the hallway. Google has recognized me as a Google Developer Expert (GDE) in the domains of Web Technologies, Security, Privacy, Payments, and Identity.

Sam Bellen

Supercharge your Auth0-issued access tokens with information, like organizations a user belongs to, from your Auth0 FGA decision engine.

Auth0 supports Roles and Permissions and allows you to add users' permissions to your access tokens with a convenient toggle in the dashboard. But what if you’re using a more fine-grained solution to make access control decisions, like [Auth0 FGA](https://a0.to/auth0-fga-content) or its open-source counterpart, [OpenFGA](https://a0.to/fga-content)?

Actions are our way of offering developers flexibility. There are many different use cases for Auth0 Actions, and enriching an access or ID token is one of them. In this blog post, we’ll explore how we can add some relevant user data from our Auth0 FGA decision engine to the access tokens issued by our Auth0 tenant so that we can use that data in our application logic.

## Prerequisites

For this blog post, we assume you are familiar with either Auth0 FGA or OpenFGA and have an instance up and running. If you’d like to follow along, you can use the following model and tuples to set up a test store, or you could adapt the code for our Auth0 action later to reflect your use case.

> If you are unfamiliar with Auth0 FGA, OpenFGA, or how to get started, read [this blog](https://auth0.com/blog/fine-grained-access-control-with-okta-fga-nextjs/) post to learn more.

## The OpenFGA Authorization Model

Our [model](https://openfga.dev/docs/getting-started/configure-model) will contain a “user,” an “organization,” and a “document” type. An organization can have admins who are defined users and members who are either directly defined users or any user who’s already an admin for the organization. One or more organizations can own documents, and access rights are determined by the “doc_creator” and “doc_admin” relations from these organizations.

```
model
schema 1.1

type user

type organization
relations
    define admin: [user]
    define member: [user] or admin
    define doc_creator: [user] or member
    define doc_admin: [user] or admin

type document
relations
    define owner: [organization]
    define can_create: doc_creator from owner
    define can_delete: doc_admin from owner
```

### OpenFGA Test Tuples

These are [the tuples](https://openfga.dev/docs/getting-started/update-tuples) I’ve added to our Auth0 FGA Store. The ``auth0|62...7f`` is a user identifier within Auth0 and will be part of the Access Token as the `sub` claim. We’ll use these user IDs in our action code to look up all organizations belonging to the current user.

```js
[
    {
      "object":"organization:devrel",
      "relation":"admin",
      "user":"user:auth0|62...7f"
    },
    {
      "object":"organization:openfga",
      "relation":"member",
      "user":"user:auth0|62...7f"
    }  
]
```

## Let’s Write Our Auth0 Action

We can create our [Action](https://auth0.com/features/actions) from the Library page under the Actions menu item. Once we’ve navigated to this page, click the “Create Action” button in the top-right corner. This will allow us to install an action from the marketplace, start from an existing template, or write one from scratch. We’ll choose “Choose a template”, as there’s a template available that can serve as a solid basis from which to start.

![Let’s Write Our Auth0 Action](https://images.ctfassets.net/23aumh6u8s0i/6MUa1wOTUXVfJjelvLvUNT/d006cd1500a5dd4531ba4b6f0e9190a5/enrich-auth0-access-tokens-with-auth0-fga-data_01.png)

On the next page, select the “Enrich profile” use case and click on the “Add Email to Access Token” template. This template will add an email address to your access tokens, but we’ll adapt it to add organizations from Auth0 FGA instead.

![Template for Actions](https://images.ctfassets.net/23aumh6u8s0i/4NDnN6YTO3fMSBNBGUfYXh/ff765bc5ef61b437d2b8862cda074bc3/enrich-auth0-access-tokens-with-auth0-fga-data_02.png)

You can now preview the code from the template and click on the “Use This Template” button to install it. The following popup will ask you to give a name to the new action. We will leave the “post-login” trigger and node runtime as is and click “Create”.

![Add Email to Access Token](https://images.ctfassets.net/23aumh6u8s0i/3UhXvF3kmvyW5JuqLILbHn/4f2c28ffb2af2d164ba3bdc5ed2bf9a9/enrich-auth0-access-tokens-with-auth0-fga-data_03.png)

![Create Action](https://images.ctfassets.net/23aumh6u8s0i/6JWXbwZJVcgnltt0oI7JXM/c1a7905d5d73d68f6964bc7798493d17/enrich-auth0-access-tokens-with-auth0-fga-data_04.png)

### Namespace our custom claim

The [OpenID Connect specification](https://openid.net/specs/openid-connect-core-1_0.html#AdditionalClaims) recommends adding a namespace to [custom claim](https://auth0.com/docs/secure/tokens/json-web-tokens/create-custom-claims#namespaced-guidelines) names. The first few lines of code in our `onExecutePostLogin` function do just that. They check for a secret called `namespace` and ensure that it ends with a trailing slash.

We can add the namespace to the secrets by clicking on the Key icon in the left-side menu of the Action editor and clicking on the “Add Secret” button. Namespaces are usually a URI, so we will add `https://example.com` as a `NAMESPACE` secret. Feel free to change this to a more appropriate namespace.

### Install and configure the OpenFGA SDK

The Actions editor also conveniently allows us to install packages from NPM. We can add the OpenFGA SDK by clicking on the box icon on the left side and clicking on the “Add dependency” button. The package name will be `@openfga/sdk`, and the version can remain “latest”. This will install the [`@openfga/sdk`](https://www.npmjs.com/package/@openfga/sdk) package so we can import and use it in the Action codebase.

Add the following line to the top of the Action’s codebase:

```js
const { OpenFgaClient, CredentialsMethod } = require('@openfga/sdk');
```

Now that we’ve imported the OpenFGA client, let’s create a new instance and configure the credentials. 

```js
const fgaClient = new OpenFgaClient({
    apiUrl: event.secrets.FGA_API_URL,
    storeId: event.secrets.FGA_STORE_ID,
    authorizationModelId: event.secrets.FGA_MODEL_ID,  // Optional, by default it will use the latest model
    credentials: {
        method: CredentialsMethod.ClientCredentials,
        config: {
            apiTokenIssuer: event.secrets.FGA_API_TOKEN_ISSUER,
            apiAudience: event.secrets.FGA_API_AUDIENCE,
            clientId: event.secrets.FGA_CLIENT_ID,
            clientSecret: event.secrets.FGA_CLIENT_SECRET,
        }
    }
});
```

It is a good idea to create a new authorized client through the [Auth0 FGA dashboard’s](https://dashboard.fga.dev/) settings page for us to use in the Actions editor. Once you’ve created this new client, you can add its Client ID and secret to the Actions editor’s secrets, together with all other necessary configuration parameters. 

Here’s a quick overview of what they should look like. Be sure to change the `eu1` region in the API URL and Audience to `us1` or `au1` depending on which jurisdiction you choose when creating your store.

```
FGA_API_URL=https://api.eu1.fga.dev
FGA_API_AUDIENCE=https://api.eu1.fga.dev/
FGA_API_TOKEN_ISSUER=auth.fga.dev
FGA_CLIENT_ID=0U...4q
FGA_CLIENT_SECRET=pB...kf
FGA_STORE_ID=01...1M
FGA_MODEL_ID=01...9C
```

### List all assigned organizations from Auth0 FGA

Auth0 FGA exposes a `list-objects` endpoint that can return a set of objects of a particular type assigned to a user, such as all organizations for which a user is a member. This will also consider all indirect relationships, such as when a user is a member because they are an admin for a specific organization.

To use this endpoint, the OpenFGA client we just created exposes a `listObjects` method where we can pass a user, relation, and object type. Notice that we pass along the `user_id` from `event.user`. This is the actual ID of the user who is currently trying to log in.

Add the following snippet below the OpenFGA client initialization code in our Action.

```js
const {objects} = await fgaClient.listObjects({
    user: `user:${event.user.user_id}`,
    relation: "member",
    type: "organization",
})
```

### Add the Assigned Organizations to the Access Token

The last thing left to do is to add the returned organization to our access token. We can re-purpose the last existing line from the template by adding the email to add our organizations instead. With some minimal changes, that code will look something like this.

```js
api.accessToken.setCustomClaim(
  namespace + 'organizations', 
  objects.map(organization => organization?.replace('organization:', ''))
);
```

The `list-objects` endpoint returns the object type together with the actual objects, so in our case, we can strip `organization:` from each returned organization. This will keep the organization names, which we can add to the custom claim.

### Putting it All Together

If we add some error handling, we’ll end up with an action that should look like this. 

```js
const { OpenFgaClient, CredentialsMethod } = require("@openfga/sdk");

exports.onExecutePostLogin = async (event, api) => {
  let namespace = event.secrets.NAMESPACE || "";
  if (namespace && !namespace.endsWith("/")) {
    namespace += "/";
  }

  try {
    const fgaClient = new OpenFgaClient({
      apiUrl: event.secrets.FGA_API_URL,
      storeId: event.secrets.FGA_STORE_ID,
      authorizationModelId: event.secrets.FGA_MODEL_ID,
      credentials: {
        method: CredentialsMethod.ClientCredentials,
        config: {
          apiTokenIssuer: event.secrets.FGA_API_TOKEN_ISSUER,
          apiAudience: event.secrets.FGA_API_AUDIENCE,
          clientId: event.secrets.FGA_CLIENT_ID,
          clientSecret: event.secrets.FGA_CLIENT_SECRET,
        },
      },
    });

    const { objects } = await fgaClient.listObjects({
      user: `user:${event.user.user_id}`,
      relation: "member",
      type: "organization",
    });

    api.accessToken.setCustomClaim(
      namespace + "organizations",
      objects.map((organization) => organization?.replace("organization:", ""))
    );
  } catch (error) {
    api.access.deny("Could not list organizations");
  }
};
```

The issued access token will now have a custom `https://example.com/organizations` claim, and when decoded, it can look something like the following:

```js
{
  "iss": "https://<your-tenant>.eu.auth0.com/",
  "sub": "auth0|62...7f",
  "aud": [
    "https://example.com",
    "https://<your-tenant>.auth0.com/userinfo"
  ],
  "iat": 1740579493,
  "exp": 1740665893,
  "scope": "openid profile email address phone",
  "jti": "rDk6D9GigyYTfi2WN492AB",
  "client_id": "T1...aW",
  "https://example.com/organizations": [
    "devrel",
    "openfga"
  ],
}
```

## Wrapping Up

In this article, we’ve gone through the steps to create a new Auth0 Action. This action will run every time a user logs into our application and adds all organizations that the user is a member of to the Access Token. We can use this information in our backend systems by decoding the Access Token, which will be a JSON Web Token, and looking for our custom claim `https://example.com/organizations`.

The action does the following steps to accomplish this:

* Import the [OpenFGA Node.js SDK](https://github.com/openfga/js-sdk).
* Make sure we have a namespace configured and that it ends with a slash.
* Create a new instance of the imported OpenFGA client.
* Use this client to list all organizations assigned to the user by using the exposed `listObjects()` method.
* Return the list of organizations as a custom claim prepended by our namespace in our Access Tokens.


Enrich Auth0 Access Tokens with Auth0 FGA Data

Madhuri

Madhuri is a Senior Engineer at Okta CIC, working in the IAM-Protocols team. The team focuses on building the core identity for the Auth0 product and keeping up to date with the latest industry standards.

Sr Software Engineer

Madhuri Ravindra Mohan

Abbie Carlson

As a Product Marketing Manager, I'm responsible for communicating the value of Identity for consumer apps as well as focusing on the developer experience. I'm forever curious about how Identity plays a role in our everyday lives as consumers and how a great Customer Identity solution can make or break a business through patron loyalty and retention. 

Outside of work can catch me watching Seattle sports, going to as many concerts as I can or listening to true crime podcasts.

Senior Product Marketing Manager

Auth0 now offers the option to choose between two access token profiles: the Auth0 token profile, which remains the default, and RFC 9068.

Imagine if you could charge every single one of your devices with one, single charger.

Your smartphone, the family printer, your kiddo’s tablet, and your work computer. How great would this be? You’d no longer be searching your junk drawer for that one, specific cord.

Similarly, access tokens are the lifeblood of an IAM (Identity and Access Management) infrastructure, impacting gateways, microservices and teams. Consequently, changing access token formats can be costly, time-consuming, and a pain.

This issue led to the IETF standards community brainstorming and then publishing a new standard detailing how to encode and validate an OAuth 2.0 JWT access token. The standardization process, led by Vittorio Bertocci, has been captured in [this insightful blog](https://auth0.com/blog/how-the-jwt-profile-for-oauth-20-access-tokens-became-rfc9068/).

We’re happy to announce that [RFC 9068](https://datatracker.ietf.org/doc/html/rfc9068) is now Generally Available on Auth0 for all customers. We continue to focus on enabling everyone to safely use any technology, and we hope that RFC 9068 supports you and your team’s Identity solutions. Let’s talk about how to use it.

## Access Token Profiles in Auth0

Auth0 now offers the option to choose, on a per-API basis, between two access token profiles: the Auth0 token profile, which remains the default, and RFC 9068. 

Based on the selected access token profile for an API, the format of the generated JWT access token changes. The main differences are:

* The RFC 9068 profile incorporates the jti claim, providing a unique identifier for the JWT.
* The Auth0 profile uses the azp claim to represent the client ID, whereas the RFC 9068 profile uses the client_id claim.
* The RFC 9068 profile does not use the gty claim, which is an Auth0-specific claim that represents the authentication flow.

![Auth0 Access Tokens Documentation](https://images.ctfassets.net/23aumh6u8s0i/6pPIMde7wHJ2Qld3EnJpWk/cb0136c98aae0449623a92abed71ec77/Uploaded_from_JWT_Access_Token_Profile_-_Community_blog)
_Image snapshot of how tokens of two different profiles look, highlighting the difference. To learn more, please refer to [Auth0 Access Tokens Documentation](https://auth0.com/docs/secure/tokens/access-tokens/access-token-profiles)._

Adopting the RFC 9068 profile offers several advantages. Your Auth0 access tokens will be directly interoperable with API gateways and servers that follow the standard, eliminating the need for custom token validation. This flexibility facilitates changing Identity Providers if you need to at some point. Additionally, you can leverage SDKs and tools that support RFC 9068, aligning with well-vetted Identity standards and evolving best practices.

## Generate a RFC 9068-Compliant Access Token

The RFC 9068 token profile is Generally Available and supported across all tenants and plans.
You can generate an RFC 9068-compliant access token using the same process as obtaining any access token: create a client, configure an API, and request a token.

To create a client, you can simply follow the normal process as explained in our [Get Started guide](https://auth0.com/docs/get-started/auth0-overview/create-applications). The RFC 9068 profile works for all application types and grant-types.

### Configure an API

Go to [Dashboard > Applications > APIs](https://manage.auth0.com/#/apis), and select **+ Create API**.

The **JSON Web Token (JWT) Profile** field determines the format of the API access tokens issued. The available values are Auth0 and RFC 9068.

![API creation](https://images.ctfassets.net/23aumh6u8s0i/2gT2erLX8IsL6kQkBpw4Br/153a7c9e338603a7fce90c9900a37899/Uploaded_from_JWT_Access_Token_Profile_-_Community_blog)  
_Image snapshot of the API creation page where the user can configure an access token profile. To learn more, refer to [Register APIs](https://auth0.com/docs/get-started/auth0-overview/set-up-apis)_

### Get an access token

As an example, let's see how you can request an access token with client_credentials grant via cURL:

```
curl --request POST \
     --url https://YOUR_AUTH0_DOMAIN/oauth/token \
     --header 'content-type: application/json' \
     --data '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","audience":"https://your-api-endpoint","grant_type":"client_credentials"}'
```

Replace the placeholders `YOUR_AUTH0_DOMAIN`, `YOUR_CLIENT_ID`, and `YOUR_CLIENT_SECRET` with the respective values from your client configuration.

This request generates a response as the following:

```
{ 
   "access_token":"eyJhbGciOiJSUzI1NiIsInR5cCI6Im...",
   "scope":"read:blogs",
   "expires_in":86400,
   "token_type":"Bearer"
}
```

The generated access_token will be RFC 9068 compatible. 

This works for all grant-types for the API. Simply follow the normal flow of a grant-type and you will get RFC 9068 compliant access tokens. Easy!

![RFC 9068-compatible access token](https://images.ctfassets.net/23aumh6u8s0i/3A1b8A9PPlJMP7DU5TDwRp/c6d7282fc62b5ec56ba8f29149e235ec/Uploaded_from_JWT_Access_Token_Profile_-_Community_blog)
_Image snapshot of a RFC 9068-compatible access token generated using a `client_credentials` grant type_

## An Ode to the Great...

Now, this post wouldn’t be complete without taking some time to acknowledge the brains behind RFC 9068, Vittorio Bertocci. 

Vittorio was and will continue to be a titan of the Identity industry. Not only was Vittorio a luminary genius in his own right, but he was a funny, witty and authentic human being. His legacy will forever be woven into the work we, and our fellow Identity friends, create for the next years, decades, and beyond. (To read a bit more about our beloved Vittorio, take a look at our celebratory blog about his life [here](https://auth0.com/blog/in-celebration-of-vittorio-bertocci/)). 

![Vittorio’s](https://images.ctfassets.net/23aumh6u8s0i/3kJu2VorZXI0DBWP7kzRPC/60c662efc764cd30c069639bf6748af4/Uploaded_from_JWT_Access_Token_Profile_-_Community_blog)

To continue Vittorio’s legacy and his passion for giving back to the community, we’d love to share two causes that were incredibly important to Vittorio:

- [Questbridge](https://www.questbridge.org/donate): providing higher education to lower income students.
- [Pancan](https://pancan.org/ways-to-give/): pancreatic cancer research.

JWT Access Tokens Profiles, Now in GA

Learn the best practices for securing ID, access, and refresh tokens in your .NET MAUI applications and keeping a consistent user experience.

Managing Tokens in .NET MAUI

Learn the right way to call a protected API using an access token in ASP.NET Core applications.

Call Protected APIs in ASP.NET Core

Vittorio

Vittorio Bertocci is a Principal Architect for Auth0. Before Auth0, he had a lengthy career with Microsoft, where Vittorio worked with Fortune 100 and Global 100 companies, including working on Microsoft’s Azure Active Directory team as principal program manager focusing on the developer experience. He contributed to the inception and launch of Microsoft's claims-based platform components (Windows Identity Foundation and ADFS, ADAL and MSAL SDKs, ASP.NET middleware). Vittorio is a well known speaker, educator and published author.

Principal Architect

Vittorio Bertocci

A first-person account of how modern open identity standards are made

From Idea to Standard: How the JWT Profile for OAuth 2.0 Access Tokens Became RFC9068

Learn what ID and access tokens are and how to correctly use them in the OpenID Connect and OAuth context.

"Let’s use a token to secure this API call. Should I use the ID token or the access token? ​🤔 The ID token looks nicer to me. After all, if I know who the user is, I can make better authorization decisions, right?"

Have you ever found yourself making similar arguments? Choices based on your intuition may sound good, but what looks intuitive is not always correct. In the case of ID and access tokens, they have clear and well-defined purposes, so you should use them based on that. Using the wrong token can result in your solution being insecure.

"What changes after all? They are just tokens. I can use them as I see fit. What’s the worst that could happen?"

Let’s take a closer look at these two types of tokens to better understand their role in authentication and authorization processes.

If you prefer, you can also watch this video on the same topic:

<AmpContent>
<amp-youtube
    data-videoid="M4JIvUIE17c"
    layout="responsive"
    width="480" height="270">
</amp-youtube>
</AmpContent>

<NonAmpContent>
<div
  class='embed-container'
  style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%;margin-bottom:40px;">
    <iframe
      style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"
      src='https://www.youtube.com/embed/M4JIvUIE17c'
      frameborder='0' allowfullscreen>
    </iframe>
</div>
</NonAmpContent>


## What Is an ID Token?

An ID token is an artifact that proves that **the user has been authenticated**. It was introduced by [OpenID Connect](https://openid.net/connect/) (OIDC), an open standard for authentication used by many identity providers such as Google, Facebook, and, of course, Auth0. Check out [this document for more details on OpenID Connect](https://auth0.com/docs/protocols/openid-connect-protocol). Let's take a quick look at the problem OIDC wants to resolve.

Consider the following diagram:

![ID token scenario](https://images.ctfassets.net/23aumh6u8s0i/QAHEJgeyGWL3otdWNnWNT/2f3dcdfb6ef72ae91c48d9cd180028dd/id-token-scenario.jpg)


Here, a user with their browser authenticates against an OpenID provider and gets access to a web application. The result of that authentication process based on OpenID Connect is the ID token, which is passed to the application as proof that the user has been authenticated.

This provides a very basic idea of what an ID token is: proof of the user's authentication. Let’s see some other details.

An ID token is **encoded as a JSON Web Token** (JWT), a standard format that allows your application to easily inspect its content, and make sure it comes from the expected issuer and that no one else changed it. If you want to learn more about JWTs, check out [The JWT Handbook](https://auth0.com/resources/ebooks/jwt-handbook).

To put it simply, an example of ID token looks like this:

```
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwOi8vbXktZG9tYWluLmF1dGgwLmNvbSIsInN1YiI6ImF1dGgwfDEyMzQ1NiIsImF1ZCI6IjEyMzRhYmNkZWYiLCJleHAiOjEzMTEyODE5NzAsImlhdCI6MTMxMTI4MDk3MCwibmFtZSI6IkphbmUgRG9lIiwiZ2l2ZW5fbmFtZSI6IkphbmUiLCJmYW1pbHlfbmFtZSI6IkRvZSJ9.bql-jxlG9B_bielkqOnjTY9Di9FillFb6IMQINXoYsw
```

Of course, this isn't readable to the human eye, so you have to decode it to see what content the JWT holds.  By the way, the ID token is not encrypted but just [Base 64](https://en.wikipedia.org/wiki/Base64) encoded. You can use one of the [many available libraries](https://jwt.io/#libraries-io) to decode it, or you can examine it yourself with the [jwt.io](https://jwt.io/?id_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwOi8vbXktZG9tYWluLmF1dGgwLmNvbSIsInN1YiI6ImF1dGgwfDEyMzQ1NiIsImF1ZCI6IjEyMzRhYmNkZWYiLCJleHAiOjEzMTEyODE5NzAsImlhdCI6MTMxMTI4MDk3MCwibmFtZSI6IkphbmUgRG9lIiwiZ2l2ZW5fbmFtZSI6IkphbmUiLCJmYW1pbHlfbmFtZSI6IkRvZSJ9.bql-jxlG9B_bielkqOnjTY9Di9FillFb6IMQINXoYsw) debugger.

Without going deeper into the details, the relevant information carried by the ID token above looks like the following:

```json
{ 
  "iss": "http://my-domain.auth0.com", 
  "sub": "auth0|123456", 
  "aud": "1234abcdef", 
  "exp": 1311281970, 
  "iat": 1311280970, 
  "name": "Jane Doe", 
  "given_name": "Jane", 
  "family_name": "Doe"
}
```

These JSON properties are called **claims**, and they are **declarations about the user** and the token itself. The claims about the user define the user’s identity.

> Actually, the OpenID Connect specifications don't require the ID token to have user's claims. In its minimal structure, it has no data about the user; just info about the authentication operation.

One important claim is the `aud` claim. This claim defines the **audience** of the token, i.e., the web application that is meant to be **the final recipient of the token**. In the case of the ID token, its value is the client ID of the application that should consume the token.

> Remember this small detail about the audience claim because it will help you better understand what its correct use is later on.

The ID token may have additional information about the user, such as their email address, picture, birthday, and so on.

Finally, maybe the most important thing: the ID token is signed by the issuer with its private key. This guarantees you the origin of the token and ensures that it has not been tampered with. You can verify these things by [using the issuer's public key](https://auth0.com/blog/how-to-explain-public-key-cryptography-digital-signatures-to-anyone/).

Cool! Now you know what an ID token is. But what can you do with an ID token?

First, it demonstrates that the user has been authenticated by an entity you trust (the OpenID provider) and so **you can trust the claims about their identity**.

Also, your application can **personalize the user’s experience** by using the claims about the user that are included in the ID token. For example, you can show their name on the UI, or display a "best wishes" message on their birthday. The fun part is that you don’t need to make additional requests, so you may get **a little gain in performance** for your application.

## What Is an Access Token?

Now that you know what an ID token is, let’s try to understand what an access token is.

Let's start by depicting the scenario where the access token fits:

![Access token scenario](https://images.ctfassets.net/23aumh6u8s0i/5DLgYCLtVgxLPT0Nqco53r/ec4ccd3c9d33734a38ef85d01dfe6b0e/access-token-scenario.jpg)


In the diagram above, a **client application** wants to access a **resource**, e.g., an API or anything else which is protected from unauthorized access. The other two elements in that diagram are the user, which is the **owner** of the resource, and the **authorization server**. In this scenario, the access token is the  artifact that **allows the client application to access the user's resource**. It is issued by the authorization server after successfully authenticating the user and obtaining their consent.

In the [OAuth 2](https://auth0.com/docs/protocols/protocol-oauth2) context, the access token **allows a client application to access a specific resource to perform specific actions on behalf of the user**. That is what is known as a **delegated authorization scenario**: the user delegates a client application to access a resource on their behalf. That means, for example, that you can authorize your LinkedIn app to access Twitter’s API on your behalf to cross-post on both social platforms. Keep in mind that you only authorize LinkedIn to publish your posts on Twitter. You don't authorize it to delete them or change your profile’s data or do other things, too. This limitation is very important in a delegated authorization scenario and is achieved through scopes. **[Scopes](https://auth0.com/docs/scopes)** are a mechanism that allows the user to authorize a third-party application to **perform only specific operations**.

Of course, the API receiving the access token must be sure that it actually is a valid token issued by the authorization server that it trusts and make authorization decisions based on the information associated with it. In other words, the API needs to somehow use that token in order to authorize the client application to perform the desired operation on the resource.

How the access token should be used in order to make authorization decisions depends on many factors: the overall system architecture, the token format, etc. For example, an access token could be a key that allows the API to retrieve the needed information from a database shared with the authorization server, or it can directly contain the needed information in an encoded format. This means that **understanding how to retrieve the needed information to make authorization decisions is an agreement between the authorization server and the resource server**, i.e., the API.

[OAuth 2 core specifications](https://datatracker.ietf.org/doc/html/rfc6749) say nothing about the access token format. It **can be a string in any format**. A common format used for access tokens is JWT, and [a standard structure is available](https://datatracker.ietf.org/doc/html/rfc9068). However, this doesn’t mean that access tokens should be in that format.

Alright! Now you know what an ID token and an access token are. 🎉 So you are ready to use them without any fear of making mistakes. But, wait. I do not see you convinced. 🤔 Maybe you need some other information. Ok. So, let’s see what these tokens are _not_ suitable for.

## What Is an ID Token NOT Suitable For?

One of the most common mistakes developers make with an ID token is using it to call an API.

As said above, an ID token proves that a user has been authenticated. In a first-party scenario, i.e. in a scenario where the client and the API are both controlled by you, you may decide that your ID token is good to make authorization decisions: maybe all you need to know is the user identity.

However, even in this scenario, the security of your application, consisting of the client and the API, may be at risk. In fact, **there is no mechanism that ties the ID token to the client-API channel**. If an attacker manages to steal your ID token, they can use it to call your API like a legitimate client.

For the access token, on the other hand, there is [a set of techniques, collectively known as *sender constraint*](https://auth0.com/blog/identity-unlocked-explained-episode-1/), that allow you to bind an access token to a specific sender. This guarantees that even if an attacker steals an access token, they can’t use it to access your API since the token is bound to the client that originally requested it.

In a delegated authorization scenario where a third-party client wants to call your API, **you must not use an ID token to call the API**. In addition to the lack of mechanisms to bind it to the client, there are several other reasons not to do this.

If your API accepts an ID token as an authorization token, to begin with, you are ignoring the intended recipient stated by the audience claim. That claim says that it is meant for your client application, not for the resource server (i.e., the API).

You may think this is just a formality, but **there are security implications** here.

First of all, among other validation checks, your API shouldn’t accept a token that is not meant for it. If it does, its security is at risk. In fact, if your API doesn't care if a token is meant for it, an ID token stolen from any client application can be used to access your API. Of course, checking the audience is just one of [the checks that your API should do to prevent unauthorized access](https://auth0.com/docs/security/tokens/access-tokens/validate-access-tokens).

In addition, your ID token will not have granted [scopes](https://auth0.com/docs/scopes) (I know, this is another pain point). As said before, scopes allow the user to restrict the operations your client application can do on their behalf. Those scopes are associated with the access token so that your API knows what the client application can do and what it can't do. If your client application uses an ID token to call the API, you ignore this feature and potentially allow the application to perform actions that the user has not authorized.

## What Is an Access Token NOT Suitable For?

On the access token side, it was conceived to demonstrate that you are authorized to access a resource, e.g., to call an API.

Your client application should use it only for this reason. In other words, the access token **should not be inspected by the client application**. It is intended for the resource server, and your client application should treat access tokens as opaque strings, that is, strings with no specific meaning. Even if you know the access token format, you shouldn’t try to interpret its content in your client application. As said, the access token format is an agreement between the authorization server and the resource server, and the client application should not intrude. Think of what can happen if one day the access token format changes. If your client code was inspecting that access token, now it will break unexpectedly.

## A Quick Recap

The confusion over the use of ID and access tokens is very common, and it can be difficult to wrap your head around the differences. Maybe it mostly derives from not having a clear understanding of the different goals of each artifact as defined by the OAuth and OpenID Connect specifications. Also, understanding the scenarios where those artifacts were originally meant to operate has an important role in preventing confusion on their use. Nevertheless, I hope this topic is a little more clear now.

To recap, here is a quick summary of what you learned about what you can and can’t do with ID and access tokens:

![ID token vs access token](https://images.ctfassets.net/23aumh6u8s0i/2y2MCTq87UqQ1uzCJsl4M/c6f127f738f0d13017ff47544958d880/id-token-vs-access-token.jpg)

If you want to see ID and access tokens in action, <a href="https://a0.to/blog_signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">sign up for a free Auth0 account</a> and start to add authentication and authorization to your applications in minutes with [your preferred programming language and framework](https://auth0.com/docs/libraries).

ID Token and Access Token: What's the Difference?

JWT Profile for OAuth 2.0 Access Tokens with Vittorio Bertocci

## The Overview

In this episode of _Identity, Unlocked_, the CTO and co-founder of Auth0, Matias Woloski, appears as acting host and interviews Vittorio Bertocci, principal architect at Auth0 and the regular host of _Identity, Unlocked_, on the JWT profiles for OAuth2 access tokens specification. 

This spec describes how to encode OAuth2 access tokens in use JWT format in an interoperable way, by giving a minimal list of claims, how to emit a JWT depending on specific aspects of the request, and most importantly, describes how to validate an incoming token based on very specific rules. The document also features sections on security and privacy, highlighting common pitfalls and suggesting ways to prevent and minimize issues.

Vittorio walks Matias through the creation process of this spec, beginning with recognizing that, despite encoding access tokens in JWT was common practice across the industry, there was no guidance on how to do so in any existing standard. After gathering examples of JWT access tokens issued by several different identity products and services, Vittorio presented the general idea for this new spec at the [2019 OAuth Security Workshop](https://osw2019.sec.uni-stuttgart.de/). After receiving interest, he proceeded to produce and propose an internet draft at [IETF104](https://datatracker.ietf.org/meeting/104/materials/slides-104-oauth-sessa-jwt-profile-for-access-token-00).

Once the spec was adopted as an official working group item, the workgroup provided an overflow of feedback and the discussions went into much greater and productive detail. While not every interaction in the workgroup is going to be worthwhile or a game changer, Vittorio explains that the working group process is key for producing high quality, widely applicable documents that have been vetted for security and correctness by some of the best experts in the industry. The [specification document ](https://tools.ietf.org/html/draft-ietf-oauth-access-token-jwt-12)has now been approved and submitted for IESG publication, one step closer to reaching the status of the official standard.  

Matias and Vittorio speak further about how using this spec JWT profile tokens will make it possible to develop truly interoperable SDKs, allowing developers more time to devote on creating their apps, rather than focusing on low-level implementation differences. Vittorio also hopes this spec will stop the use of ID tokens in place of access tokens, streamline the code required to handle authorization, and help to keep privacy considerations into account when designing API solutions.

The episode closes with a call for action. The work of identity standards groups touches everyone in our industry, but not everyone is represented. Participation is easier than ever, and contributions are welcome - Vittorio encourages reaching out to him for help, extending an invitation to anyone who would like to take part in the process but don’t know where to start.

## Key Takeaways

What is the JWT profile spec, in a nutshell:

<iframe width="100%" height="230px" scrolling="no" style="border: none" src="https://identityunlocked.auth0.com/player/c4eb1494"></iframe>

How a spec evolves from an idea:

<iframe width="100%" height="230px" scrolling="no" style="border: none" src="https://identityunlocked.auth0.com/player/226f297c"></iframe>

The JWT profiles for OAuth2 access tokens spec through the workgroup process:

<iframe width="100%" height="230px" scrolling="no" style="border: none" src="https://identityunlocked.auth0.com/player/9a3722e2"></iframe>

Vittorio explains the potential advantages of this JWT spec:

<iframe width="100%" height="230px" scrolling="no" style="border: none" src="https://identityunlocked.auth0.com/player/f870c54e"></iframe>

Vittorio’s Call to Action: 

<iframe width="100%" height="230px" scrolling="no" style="border: none" src="https://identityunlocked.auth0.com/player/56147e11"></iframe>

### Links/Resources:

- Connect with Matias Woloski on [LinkedIn](https://www.linkedin.com/in/matiaswoloski/)
- Connect with Matias Woloski on [Twitter](https://twitter.com/woloski)

<br>

- Connect with Vittorio Bertocci on [LinkedIn](https://www.linkedin.com/in/vittoriobertocci/)
- Connect with Vittorio Bertocci on [Twitter](http://www.twitter.com/vibronet)

<br>

- Learn more about [Identity, Unlocked](https://identityunlocked.auth0.com/public/49/Identity%2C-Unlocked.--bed7fada/episodes)
- Learn more about [Auth0](https://auth0.com/)
- Learn more about the sponsor for this season, the [OpenID Foundation](https://openid.net/foundation/)

<include src="asides/IdentityUnlocked" />

<include src="asides/AboutAuth0" />

Identity, Unlocked... Explained: Season 2, Ep 8

332d7898dae6bc56031ac3507a0248ba

I'm a full-stack developer with a passion for technology and code. I love writing tutorials for developers to showcase a particular technology whilst building something useful at the same time. Right now  I can mostly be found developing for the front-end, playing around with Docker, or tinkering with Unreal Engine and electronics!

Developer Experience Engineer

Steve Hobbs

Learn how to build APIs with Scala and the Play Framework, and secure them using access tokens.

Build and Secure APIs with Scala and the Play Framework

diegopoza

System Engineer, geek, foodie, technology lover, speaker.

Sr Manager, Developer Advocacy

Diego Poza

Almost 90 millions Facebook users were affected by a breach that compromised access tokens to the platform.



On September 25th, 2018, Facebook learned from its engineering team that [a security vulnerability compromised around 50 million accounts](https://newsroom.fb.com/news/2018/09/security-update/). While the investigation is still in progress, Facebook already has defined the attack surface and vulnerabilities that led to the attack along with identity data that was compromised.

A feature that allows Facebook users to determine what their profile looks like to other people, known as ["View As"](https://www.facebook.com/help/288066747875915?helpref=faq_content), had a vulnerability that was exploited by attackers. 

![Facebook View As feature.](https://images.ctfassets.net/23aumh6u8s0i/2fEamNAYfwNcwaU1rOpoBy/ee3e16c5e6b6b4c7573882479ea46e6a/facebook-view-as-feature)

Through this vulnerability, attackers were able to steal Facebook access tokens. An [access token](https://auth0.com/docs/tokens/access-token) is a credential that can be used by an application to access an API. Its main purpose is to inform the API that the bearer of this token has been authorized to access the API and perform specific actions. In this case, an attacker could have used the Facebook access tokens to take over accounts.

One of the ways that Facebook uses access tokens is to persist login. As Facebook mentions on their [Security Update](https://newsroom.fb.com/news/2018/09/security-update/), these tokens are the "equivalent of digital keys that keep people logged in to Facebook so they don’t need to re-enter their password every time they use the app." Thus, for this type of data breach, changing the user's password doesn't provide risk mitigation. Instead, the digital keys need to be changed. Once Facebook understood the origin and nature of the attack, the engineering team carried out the following actions to mitigate any damage to the platform and to users:

- Facebook fixed the vulnerability in the "View As" feature.
- Facebook has informed law enforcement about the attack.
- Facebook has reset the access tokens of the almost 50 million accounts that were determined to be at risk in order to diminish any risk to the user data and to ensure their personal and digital security.
- As a precautionary step, Facebook has also reset the access tokens for another 40 million accounts. These accounts used the "View As" feature in the past year.

As a result of these security measures, about 90 million users will have to log back into the Facebook platform. Other applications that use Facebook login are also impacted and will require users to re-authenticate. Facebook wants to remain transparent and direct in the acknowledgment and communication of this security breach. Once affected users log back into their accounts, they will receive a notification at the top of their News Feed with an explanation of what has happened and what actions were taken.

![Facebook security breach user notification](https://images.ctfassets.net/23aumh6u8s0i/6dPmOhI9JO2lMpeVzhexwe/a74063a6782f8882ed81ef1ba0a972a9/facebook-data-breach-notification-access-tokens)

[Source](https://fbnewsroomus.files.wordpress.com/2018/09/42647794_340201783392972_4207828087510925312_n.png?w=960&h=551)

As a final precaution, Facebook has turned off the "View As" feature to run a security review as part of their investigation. As the security investigation is on its early stage, Facebook has yet to determine if any of the compromised accounts had their data accessed or misused. The identity or location of the attackers is also unknown at this time. Facebook vows to keep users updated on the evolution of the investigation. 

On a statement on his personal page, Mark Zuckerberg, Facebook CEO, issued a statement [summarizing the nature of the data breach](https://www.facebook.com/zuck/posts/10105274505136221). Part of his statement includes the assessment that new tools need to be developed to prevent attacks like this from being successful:

> "We face constant attacks from people who want to take over accounts or steal information around the world. While I'm glad we found this, fixed the vulnerability, and secured the accounts that may be at risk, the reality is we need to continue developing new tools to prevent this from happening in the first place. If you've forgotten your password or are having trouble logging in, you can access your account through the Help Center."

To stay tuned on this developing investigation, visit [Facebook Newsroom](https://newsroom.fb.com/) or follow [@facebook](https://twitter.com/facebook) on Twitter.


<include src="asides/AboutAuth0" />


Early Look at Facebook Access Token Security Breach

4ff2f1955778896cc06318b342dabf55?size=200 avatar

4ff2f1955778896cc06318b342dabf55?size=200

Former Auth0 Employee

Maria Paktiti

We explain the difference between access token and ID token and why the latter should never be used to secure an API.



**TL;DR:** There is much confusion on the Web about the differences between the OpenID Connect and OAuth 2.0 specifications, and their respective tokens. As a result many developers publish insecure applications, compromising their users security. The contradicting implementations between identity providers do not help either.

This article is an attempt to clear what is what and explain why you should always use an access token to secure an API, and never an ID token.

---

## Two complementary specifications

OAuth 2.0 is used to **grant authorization**. It enables you to authorize the Web App A to access your information from Web App B, without sharing your credentials. It was built with *only* authorization in mind and doesn't include any authentication mechanisms (in other words, it doesn't give the Authorization Server any way of verifying who the user is).

OpenID Connect builds on OAuth 2.0. It enables you, the user, to verify your identity and give some basic profile information, without sharing your credentials.

An example is a to-do application, that lets you log in using your Google account, and can push your to-do items as calendar entries, at your Google Calendar. The part where you authenticate your identity is implemented via OpenID Connect, while the part where you authorize the to-do application to modify your calendar by adding entries, is implemented via OAuth 2.0.

> OpenID Connect is about who someone is. OAuth 2.0 is about what they are allowed to do.

You may notice the *"without sharing your credentials"* part, at our definitions of the two specifications earlier. What you do share in both cases, is tokens.

OpenID Connect issues an identity token, known as `id_token`, while OAuth 2.0 issues an `access_token`. Learn more about OIDC with the free OpenID Connect Handbook:

<include src="ebook-ads/OidcHandbook" />

## How to use each token

The `id_token` is a [JWT](https://auth0.com/docs/jwt) and is meant for the client only. In the example we used earlier, when you authenticate using Google, an `id_token` is sent from Google to the to-do application, that says who you are. The to-do application can parse [the token's contents](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) and use this information, like your name and your profile picture, to customize the user experience.

**Note:** You must never use the info in an `id_token` unless you have validated it! For more information refer to: [How to validate an ID token](https://auth0.com/docs/tokens/id-token#how-to-validate-an-id-token). For a list of libraries you can use to verify a JWT refer to [JWT.io](https://jwt.io/).

The `access_token` can be any type of token (not necessarily a JWT) and is meant for the API. Its purpose is to inform the API that the bearer of this token has been authorized to access the API and perform specific actions (as specified by the `scope` that has been granted). In the example we used earlier, after you authenticate, and provide your consent that the to-do application can have read/write access to your calendar, an `access_token` is sent from Google to the to-do application. Each time the to-do application wants to access your Google Calendar it will make a request to the Google Calendar API, using this `access_token` in an HTTP `Authorization` header.

**Note:** Access Tokens should be treated as opaque strings by clients. They are only meant for the API. Your client should not attempt to decode them or depend on a particular `access_token` format.

## How NOT to use each token

Now that we saw what these tokens can be used for, let's see what they cannot be used for.

* **An `access_token` cannot be used for authentication.** It holds no information about the user. It cannot tell us if the user has authenticated and when.

* **An `id_token` cannot be used for API access.** Each token contains information on the intended audience (recipient). According to the OpenID Connect specification, the audience (claim `aud`) of each `id_token` must be the `client_id` of the client making the authentication request. If it isn't you shouldn't trust the token. An API, on the other hand, expects a token with the audience set to the API's unique identifier. So unless you are in control of both the client and the API, sending an `id_token` to an API will not work. Furthermore, the `id_token` is signed with a secret that is known to the client (since it is issued to a particular client). This means that if an API were to accept such token, it would have no way of knowing if the client has modified the token (to add more scopes) and then signed it again.

## Compare Tokens

To better understand what we just read, let's look at the contents of example tokens.

The (decoded) contents of an `id_token` look like the following:

```js

{
  "iss": "http://${account.namespace}/",
  "sub": "auth0|123456",
  "aud": "${account.clientId}",
  "exp": 1311281970,
  "iat": 1311280970,
  "name": "Jane Doe",
  "given_name": "Jane",
  "family_name": "Doe",
  "gender": "female",
  "birthdate": "0000-10-31",
  "email": "janedoe@example.com",
  "picture": "http://example.com/janedoe/me.jpg"
}

```

This token is meant for **authenticating the user to the client**. Note that the audience (`aud` claim) of the token is set to the client's identifier, which means that only this specific client should consume this token.

For comparison, let's look at the contents of an `access_token`:

```js

{
  "iss": "https://${account.namespace}/",
  "sub": "auth0|123456",
  "aud": [
    "my-api-identifier",
    "https://${account.namespace}/userinfo"
  ],
  "azp": "${account.clientId}",
  "exp": 1489179954,
  "iat": 1489143954,
  "scope": "openid profile email address phone read:appointments email"
}

```

This token is meant for **authorizing the user to the API**. As such, it is completely opaque to clients, meaning that a client should not care about the contents of this token, decode it or depend on a particular token format. Note that the token does not contain any information about the user itself besides their ID (`sub` claim), it only contains authorization information about which actions the client is allowed to perform at the API (`scope` claim).

Since in many cases it is desirable to retrieve additional user information at the API, this token is also valid for calling the `/userinfo` API, which will return the user's profile information. So the intended audience (`aud` claim) of the token is either the API (`my-api-identifier`) or the `/userinfo` endpoint (`https://${account.namespace}/userinfo`).

### Recommended resources for further reading

* [Access Token](https://auth0.com/docs/tokens/access-token)
* [ID Token](https://auth0.com/docs/tokens/id-token)
* [The problem with OAuth for Authentication](http://www.thread-safe.com/2012/01/problem-with-oauth-for-authentication.html)
* [The OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749)
* [OAuth 2.0 Overview](https://auth0.com/docs/protocols/oauth2)
* [OpenID Connect Overview](https://auth0.com/docs/protocols/oidc)

## Securing Applications with Auth0

Are you building a [B2C](https://auth0.com/b2c-customer-identity-management), [B2B](https://auth0.com/b2b-enterprise-identity-management), or [B2E](https://auth0.com/b2e-identity-management-for-employees) tool? Auth0, can help you focus on what matters the most to you, the special features of your product. [Auth0](https://auth0.com/) can improve your product's security with state-of-the-art features like [passwordless](https://auth0.com/passwordless), [breached password surveillance](https://auth0.com/breached-passwords), and [multifactor authentication](https://auth0.com/multifactor-authentication).

[We offer a generous **free tier**](https://auth0.com/pricing) so you can get started with modern authentication.
