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

joey devilla headshot 900px

I’m a Senior Developer Advocate at Auth0, and I like to work on various technologies. I’ve developed software for all sorts of platforms, from CD-ROM and the PalmPilot to my current area of focus, mobile phones, IoT devices, and AI. When I’m not looking for strange new platforms to write software for, I’m playing a strange old instrument — the accordion!

Senior Developer Advocate

Joey deVilla

peterfernandez_360

As an Architect, Consultant, and Engineer, I have more than 30 years of experience designing and developing secure and robust software solutions. When not helping teams deal with the complexities of Customer Identity, you can usually find me working behind the scenes, acting in or directing a show at my local theatre.

Peter Fernandez

Add personalization to your iOS/SwiftUI app with user info from the ID token, a JWT (JSON Web Token) that you’ll read with the Swift JWTDecode library.

In Part 1 of this tutorial, you created a SwiftUI-based iOS app that uses Auth0 for basic login and logout functionality. In this part, you’ll enhance your app by giving it the ability to read the user’s profile to display their photo, name, and email address when they’re logged in.

<include 
    src="LinkCard" 
    title="Calling a Protected API from an iOS Swift App" 
    link="https://auth0.com/blog/calling-protected-apis-from-ios-swift/" 
    description="Looking for a step-by-step guide to leveraging OAuth 2.0 when accessing protected APIs via an iOS app built with Swift? If you're integrating with Auth0, then this is everything you need to know!"     img="https://images.ctfassets.net/23aumh6u8s0i/5PC3nu1F68m8S3BmJFv9SN/e83487c6d89d72fb6a49155722959b1d/ios_hero_2021_2.jpeg"
/>

Once again, you can follow the text in this article, or if you prefer learning by video, you can follow the steps in this article’s companion video:

<iframe width="600" height="338" src="https://www.youtube.com/embed/xOBoLegDmTw" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

> Look for the 🛠 emoji if you’d like to skim through the content while focusing on the build and execution steps.
> 
> The 📺 emoji highlights links to specific points in the video.


## Examine the ID Token

📺 [The _Examine the ID Token_ section of the video](https://www.youtube.com/watch?v=xOBoLegDmTw&t=2008s)
 
If you look at the `.success` case of the `switch` statement in `ContentView`’s `login()` method, you’ll see these `print()` functions:

```swift
print("Credentials: \(credentials)")
print("ID token: \(credentials.idToken)")
```

These functions’ output will appear in Xcode’s Debug area:

![Xcode screenshot highlighting the Debug area.](https://images.ctfassets.net/23aumh6u8s0i/2Odv2P2CeeMGBoKSHNl3ly/2ba5ae37dbc5afafb94e82f95f41a722/debug_area.png)

> If the Debug area isn’t visible, open the _View_ menu and select _Debug Area_ → _Show Debug Area_ or use the keyboard shortcut _command-Shift-Y_.

You’ll see the contents of the `credentials` object and its `idToken` property, which should look similar to this:

```
Credentials: Credentials(accessToken: "<REDACTED>", tokenType: "Bearer", idToken: "<REDACTED>", refreshToken: nil, expiresIn: 2022-03-20 04:38:25 +0000, scope: Optional("openid profile email"), recoveryCode: nil)
ID token: eyJhbGciOiJSUzI1NiIsInR5cC...
```

The `credentials` object is a package of information that Auth0 sends to your app after authenticating a user. This information includes:

- **ID token:** Data that proves that the user has been authenticated.
- **Access token:** Data that gives a client application permission to access a specific resource to perform specific actions on the user’s behalf.
- **Refresh token:** Applications use this to get additional access tokens when the original access token expires without requiring the user to re-authenticate.
- **Scopes:** A set of [OpenID Connect (OIDC) scopes](https://auth0.com/docs/get-started/apis/scopes/openid-connect-scopes) — authorizations for access to details about the user — that Auth0 has granted to the app. Unless you specify otherwise, *Auth0.swift* defaults to requesting the following scopes when logging in a user:
	- `openid`: Authorization to use OIDC to verify the user's identity
	- `profile`: Authorization to access the user’s name information
	- `email`:  Authorization to access the user’s email address

> Want to know more about ID tokens and access tokens? We explain all in our article, [_ID Token and Access Token: What's the Difference?_](https://auth0.com/blog/id-token-access-token-what-is-the-difference/)
> 
> Want to know more about refresh tokens? See our article, [_What Are Refresh Tokens and How to Use Them Securely_](https://auth0.com/blog/refresh-tokens-what-are-they-and-when-to-use-them/).

The piece of information that we’re most interested in (for this exercise) is the ID token.

When the `print()` function is used to output the contents of `credentials`, the values of the `idToken` and `accessToken` properties are replaced with the string `<REDACTED>` as a security measure. Malicious parties can use tools to capture the output of `print()` functions from production apps; this is why `Credentials` instances redact the values of their `idToken` and `accessToken` properties when printed.

Note that when we use the `print()` function to output `credentials.idToken` — the ID token itself — the value is _not_ redacted. That’s because this value is useful for debugging, which we’ll do in the next step.

> It’s fine to print the value of the ID token to the debug console while you’re learning about the authentication process or building the app. Make sure you remove `print()` statements — especially those that print sensitive information, such as the ID token — before putting them into production!


### What’s in the ID token?

📺 [The _What’s in the ID token?_ section of the video](https://www.youtube.com/watch?v=xOBoLegDmTw&t=2118s)

To see what’s in the ID token, copy its value from the Debug area, go to Auth0’s [JWT.io site](https://jwt.io/) and paste that value into the _Encoded_ text area on the left side of the page. JWT.io will decode the ID token from its JWT form and display its decoded contents in the _Decoded_ area on the page’s right side:

![JWT.io and the decoded ID token.](https://images.ctfassets.net/23aumh6u8s0i/4sg6VirydfCzVVenH6LWil/174552abed55b4fe3d8100493c1510db/jwt.io_screenshot.png)

In the _Decoded_ area’s _Payload_ section, you’ll see the decoded user information from the ID token, including the data that we want the app to display: the user’s name, email address, and picture.

In the next step, we’ll give the app the same ID token-decoding capability as JWT.io’s.

> Auth0 has plenty of information about JWTs. In addition to the main [JWT.io page](https://jwt.io/), you should visit JWT.io’s [_Introduction to JSON Web Tokens_](https://jwt.io/introduction) and download our [free JWT Handbook](https://auth0.com/resources/ebooks/jwt-handbook).


## Get the User’s Information

📺 [The _Get the User’s Information_ section of the video](https://www.youtube.com/watch?v=xOBoLegDmTw&t=2223s)

The app only “knows” whether the user is logged in or logged out in its current state. It also has information about the user’s identity encoded in the ID token. Let’s extract this user information — the *user profile* — and use it to display the user’s name, email address, and picture when the user is logged in. 

🛠 In `Profile`, add the following `import` statement before the `struct Profile` line:

```Swift
// [ 📄 Profile.swift ]

import JWTDecode

// [ More code here ]
```

🛠 In the `Profile` extension, replace the `// TODO: Implement the 'from()' method.` comment with this `from()` method. It uses a couple of methods from the newly-imported `JWTDecode` library:

```swift
// [ 📄 Profile.swift ]

// [ More code here ]

  static func from(_ idToken: String) -> Self {
    guard
      let jwt = try? decode(jwt: idToken),
      let id = jwt.subject,
      let name = jwt.claim(name: "name").string,
      let email = jwt.claim(name: "email").string,
      let emailVerified = jwt.claim(name: "email_verified").boolean,
      let picture = jwt.claim(name: "picture").string,
      let updatedAt = jwt.claim(name: "updated_at").string
    else {
      return .empty
    }

    return Profile(
      id: id,
      name: name,
      email: email,
      emailVerified: String(describing: emailVerified),
      picture: picture,
      updatedAt: updatedAt
    )
  }
  
// [ More code here ]
```

Given an ID token string, the `from()` function creates a `Profile` instance. If `from()` can extract claims — values about the user’s identity, which include their name, email address, and the URL for their picture — from the ID token, it returns a `Profile` instance with that information in its properties. Otherwise, it returns a `Profile` instance with empty properties.


## Display the User’s Information

📺 [The _Display the User’s Information_ section of the video](https://www.youtube.com/watch?v=xOBoLegDmTw&t=2424s)

Now that there’s a way to extract information from an ID token, let’s put it to use. 

Since `userProfile` is marked with the `@State` attribute, it defines the user interface’s state. Whenever `userProfile` or one of its properties changes, the app redraws the user interface to reflect the change.

We want to display the user’s information when they log in, so we’ll use `Profile`’s newly-created `from()` method in the `login()` method.

🛠 Open `ContentView` and update `login()` as shown below:

```swift
// [ 📄 ContentView.swift ]

// [ More code here ]

  func login() {
    Auth0 // 1
      .webAuth() // 2
      .start { result in // 3
        switch result {
          // 4
          case .failure(let error):
            print("Failed with: \(error)")
          // 5
          case .success(let credentials):
            self.isAuthenticated = true
            // 👇🏽👇🏽👇🏽 New line of code here!
            self.userProfile = Profile.from(credentials.idToken)
            // 👆🏽👆🏽👆🏽
            print("Credentials: \(credentials)")
            print("ID token: \(credentials.idToken)")
        }
      }
  }

// [ More code here ]
```

The newly-added line of code runs after the user logs in, and the app receives the ID token. It creates a new `Profile` instance from the data in the ID token and sets `ContentView`’s `userProfile` property to that instance.

When the user logs out, we should clean up the user profile just to be safe.

🛠 Update `logout()` as shown below:

```swift
// [ 📄 ContentView.swift ]

// [ More code here ]

  func logout() {
    Auth0
      .webAuth()
      .clearSession { result in
        switch result {
          case .success:
            self.isAuthenticated = false
            // 👇🏽👇🏽👇🏽 New line of code here!
            self.userProfile = Profile.empty
            // 👆🏽👆🏽👆🏽

          case .failure(let error):
            print("Failed with: \(error)")
        }
      }
  }

// [ More code here ]
```


## Run the App Again

📺 [The _Run the App Again_ section of the video](https://www.youtube.com/watch?v=xOBoLegDmTw&t=2566s)

Run the app and confirm that the changes work. When you log in, you should see the user’s name, email address, and picture:

![The app’s “logged in” screen, featuring the text “Logged in” and displaying the user’s picture, name, and email address.](https://images.ctfassets.net/23aumh6u8s0i/1zYLUYAU3fdbLLde9PmhCN/90854331950e7557fbcc52db5bcb7379/logged_in_screen.png)

Congratulations, and high-fives and handshakes all around! You’ve taken a SwiftUI app and given it the ability to authenticate users with Auth0.


## Next Steps

SwiftUI is an expansive topic; we only scratched its surface in this tutorial. For your next steps in exploring it, you might want to look at these valuable resources:

- [SwiftUI by Example](https://www.hackingwithswift.com/quick-start/swiftui)
- [Your First SwiftUI App](https://www.youtube.com/watch?v=VlhcNR7Qrno)
- [Stanford University’s “Developing Applications for iOS” course for Spring 2021](https://www.youtube.com/playlist?list=PLpGHT1n4-mAsxuRxVPv7kj4-dQYoC3VVu)

📺 Last but not least, the video ends with [closing remarks and a quick accordion number](https://www.youtube.com/watch?v=xOBoLegDmTw&t=2645s)!

Get Started with iOS Authentication using SwiftUI, Part 2: User Info, ID Tokens, and JWTs

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

Should you use cookie-based or token-based authentication in ASP.NET Core Identity? Or should you use JWT and OpenID Connect?

.NET 8 has been released and many new exciting features are available to developers. In particular, this release brings [new options for authentication and authorization for ASP.NET Core Identity](https://auth0.com/blog/whats-new-dotnet8-authentication-authorization/). While these features have been long awaited, it seems that not everyone is happy with Microsoft's implementation choices, and there is some confusion among developers about the proper approach to use in their ASP.NET Core Identity-based applications. Let's try to shed some light on this not-so-simple topic.

## ASP.NET Core Identity: What’s New

One of the most criticized features of ASP.NET Core Identity until .NET 7 has been [its lack of *modern* authentication support for Single Page Applications](https://github.com/dotnet/aspnetcore/issues/42158). Whatever *modern* means, [ASP.NET Core Identity](https://learn.microsoft.com/en-us/aspnet/core/security/authentication/identity) has provided support for cookie-based authentication since version 3.1. It has also provided a set of web pages that allow users to register, authenticate, recover passwords, etc.

However, the current trend in authentication for SPAs seems to be token-based rather than cookie-based, and ASP.NET Core Identity didn't support it. The only option provided with the built-in SPA templates was based on Identity Server, a third-party [OpenID Connect](https://openid.net/developers/how-connect-works/) server. This approach has been [deemed excessive for small projects](https://github.com/dotnet/aspnetcore/issues/42158#issuecomment-1153222403) by several developers, and in any case introduces a third-party dependency that not everyone may want.

To address this issue, .NET 8 introduces support for token-based authentication and a set of [Identity API endpoints](https://learn.microsoft.com/en-us/aspnet/core/security/authentication/identity-api-authorization) that let developers do through the API what they could already do through the old-style web pages.

> To learn more about [the new authentication and authorization features introduced by .NET 8, read this article](https://auth0.com/blog/whats-new-dotnet8-authentication-authorization).

Awesome! So the problem is fixed and we all live happily ever after.🎉

In fact, things are not quite like that. Some developers are not entirely happy. There are those who expected a different implementation, and those who are now confused about the correct use of the new options. Let's try to bring some order to all this confusion.

> Disclaimer: This article is not a step-by-step tutorial on how to add ASP.NET Core Identity to your application. Its purpose is to discuss the authentication modes that it supports as of .NET 8.0.

## Cookie or Token-based Authentication?

Now ASP.NET Core Identity provides you with two authentication options: cookie-based and token-based. But what is the actual difference between the two approaches?

### Cookie-based authentication

Cookie-based authentication is the typical approach used by the traditional server-side rendered web page model. This is the model used by ASP.NET Core MVC and Razor Pages, to put it bluntly. In this type of authentication, a server-generated cookie proves successful user authentication and represents the user session.

> To learn more about [the relationship between cookies and sessions, read this article](https://dev.to/andychiare/sessions-tokens-and-rocknroll-4pdc).

Roughly, the cookie-based authentication flow is as follows:

1. The user authenticates through a web page.
2. The server generates a cookie and sends it to the browser with the response page.
3. The browser sends the cookie with each new page request.
4. If the server finds the cookie in the incoming request, it can use it to get the relevant information to make its authorization decisions.

The fun fact is that the cookie's back and forth is automatically managed by the browser. Provided that the server applies all [the security best practices](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html#cookies) to protect its cookies, your application doesn't need to care about storing them and sending them back with each request.

### Token-based authentication

Token-based authentication doesn't rely on cookies to prove user authentication. It relies on a token, which is a unique string of characters that also represents the user's session.

> To learn more about [how tokens help build sessions, check out this article](https://dev.to/andychiare/sessions-tokens-and-rocknroll-4pdc).

Awesome! How does the token-based flow work? Here is a rough description:

1. The user authenticates via a client-side page that calls the login endpoint.
2. The server generates a token and sends it to the app in the login endpoint's response.
3. The app sends the token with each new HTTP request.
4. If the server finds the token in the incoming request, it can use it to get the relevant information to make its authorization decisions.

As you can see, this flow is basically the same as the cookie-based flow. The only difference is that this one mentions the token instead of the cookie. So what is the real difference between the two approaches?

<details>
  <summary>What does authentication mean in this context?</summary>

If you are an experienced developer, you should already know the difference between **authentication** and **authorization**. Very roughly, authentication verifies the identity of the user while authorization verifies what the user can do.

Cookie-based authentication and token-based authentication are somewhat ambiguous terms. In fact, in this context, the cookie and the token indicate that the user has been successfully authenticated. However, they are used to make authorization decisions. When the server receives a request from a client, it checks if a cookie or a token is included in it. If so, the cookie or the token allows the server to somehow retrieve information to determine whether or not the request can be fulfilled. This information may also include the user profile data, of course. The specific way used to retrieve this information does not really matter.

This means that there is no real user authentication when sending a request to the server. User authentication has already taken place at the beginning of the session.
</details>

### Cookies and tokens: a quick comparison

As you learned in the previous sections, cookie-based and token-based authentication are very similar. The main visible difference is the artifact they rely on to prove authentication and support session creation. However, there are significant differences. I will not go into a detailed comparison between cookies and tokens, but I can't help but mention at least the following:

- **Cookies** are *tied to a domain*, require *little storage*, and are *automatically managed by the browser*. However, without proper precautions, they are vulnerable to [CSRF](https://auth0.com/blog/cross-site-request-forgery-csrf/) and [XSS attacks](https://auth0.com/blog/cross-site-scripting-xss/), are *not suitable for multi-domain applications*, and have *scalability issues*.
- **Tokens** are *not tied to only web applications* and they *promote server scalability*. However, *their management and security is left to the developer*. Depending on the type of token, there may be an *invalidation problem*, i.e. a revoked token may still be used by the client, and a *data transfer overhead* if the token size becomes significant.

> It's worth noting that while cookies in general can lead to scalability issues when used as pointers to server-side data, this is not the case with the authentication cookie issued by ASP.NET Core Identity. By default, this cookie contains encrypted data that allows the server to retrieve the user's identity information without having to access a server-side store. However, you need to [properly configure your servers](https://learn.microsoft.com/en-us/aspnet/core/security/data-protection/configuration/overview) in order to share the same encryption/decryption key.

That said, when should you use one type of authentication over the other?

### Which authentication type to use?

There's a common belief that cookie-based authentication should be used for traditional server-side page-rendered applications, while token-based authentication is for SPAs and native applications.

Actually, the ASP.NET Core Identity framework uses the cookie-based authentication approach for ASP.NET Core MVC and Razor Pages applications. With these types of applications, each request triggers a complete reload of the entire web page in the browser. In previous versions of .NET, if you wanted to leverage the ASP.NET Core Identity built-in authentication pages in your SPA, the user experience would be disrupted. Users would pass from the partial page reload experience typical of a SPA to a full page reload experience. This is one of the reasons behind the request of token-based authentication from many developers. They feel that having a token and a set of authentication APIs, such as the Identity API, allows them to build a consistent user experience for SPAs. In addition, this API can also be used by native applications, i.e., desktop and mobile applications, which were excluded by the traditional cookie-based approach.

This criterion may seem reasonable, but...

## Wait! Identity API Endpoints Have Cookies Too?

So, in general, you might think that cookie-based authentication is meant for traditional server-rendered applications, while token-based authentication is meant for SPAs and native applications.

However, if you dig into [the currently sparse documentation](https://devblogs.microsoft.com/dotnet/whats-new-with-identity-in-dotnet-8/#securing-blazor-webassembly-apps), you will find that you can call the authentication endpoint (`/login`) with the `useCookies=true` parameter. In other words, you can call the following endpoint: `/login?useCookies=true`. What does this mean? What scenario does it cover?

Well, despite many developers thinking that SPA should use token-based authentication, this is not always the case. Think about this for a moment:

- Why should you use tokens and manage the back-and-forth and their security when you can use cookies to take advantage of the built-in capabilities of browsers?
- What can you do with a token that you can't do with a cookie?
- In other words, do you really need a token in your specific scenario?

As a general rule, you should use the right tool for your specific needs. Over-designing or following common sense can lead to extra work and possible risks because you have to worry about token security.

If the client of your Web API application is a native client, you are forced to use token-based authentication. Supporting cookies in native applications would be impractical. However, you can use cookies in your SPA. Provided that your application lives in a single domain, you can use cookies and their automatic management by browsers. Why not?

If your application consists of a SPA and a Web API, and you authenticate users locally using ASP.NET Core Identity, you should use cookie-based authentication. Technically, your application is a first-party application, and even [OAuth best practices](https://www.ietf.org/archive/id/draft-ietf-oauth-browser-based-apps-14.html#section-6.1) recommend using this approach.

## Why Are These Tokens Not JWTs?

Another common misconception is that *token* means *JSON Web Token* (JWT). I've seen many developers react as shown in the following picture when they learn that the token issued by the Identity API is not in JWT format:

![Why not JWT?](https://images.ctfassets.net/23aumh6u8s0i/4CaZUMohAdvA2AiEDtfGjx/6585793bf36b74b70f29610f448ceb97/why-not-jwt.png)

Actually, that token has a proprietary format, although you can partially decode it. Read [this article](https://nestenius.se/2023/08/29/bearertoken-the-new-authentication-handler-in-net-8/) if you want to learn more about what's inside the access and refresh tokens issued by the Identity API.

Again, why do developers think the JWT format would have been better in this context? If your application is a first-party application in the authentication context, why do you need JWT?

The JWT format was invented to share information between two trusted parties. In the authentication and authorization context, a typical example of JWT adoption is when a third-party entity authenticates or authorizes a user. In this case, the third-party entity (the Identity provider or authorization server) issues a JWT containing the information related to the authentication or authorization result.

The need for a JWT arises from the fact that the third-party entity and your application are independent; they do not share a common data source.

Your application receives the result of the requested operation in the form of a JWT and it can verify that this information was actually issued by that entity by validating the token's signature. To be precise, only OpenID Connect defines a [JWT-based format for ID tokens](https://openid.net/specs/openid-connect-core-1_0.html#IDToken). OAuth 2.0 doesn't recommend [a specific format for access tokens](https://datatracker.ietf.org/doc/html/rfc6749#section-1.4), although [one is available](https://datatracker.ietf.org/doc/html/rfc9068).

> To learn more about [ID token and access token differences, see this article](https://auth0.com/blog/id-token-access-token-what-is-the-difference).

The point is, does your application really need the JWT format for access tokens? If so, your scenario may be different from what the Identity API was designed for. In a first-party scenario, your server should have all the information it needs to make authorization decisions.

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

## When Do You Need OpenID Connect and OAuth 2.0?

Developer reactions to the new Identity API make me think that they have been waiting for a built-in OpenID Connect and OAuth 2.0 implementation. They would probably expect Microsoft to have replaced Identity Server with its own OpenID Connect server. However, this may sound somewhat contradictory, since many have complained about the complexity of Identity Server in simple authentication scenarios.

Leaving aside speculation about what some developers expected, .NET 8 and its version of ASP.NET Core Identity is now here with its new authentication options. When should you use it in your applications and when do you need OpenID Connect and OAuth 2.0?

ASP.NET Core Identity can be the right solution if you need to build an application with basic authentication needs. Your users are authenticated locally, you don't expect much traffic and therefore don't plan to scale anytime soon, you don't have complex custom authentication needs. You can also integrate with external identity providers. I recommend using cookie-based authentication for web applications (including SPAs) and token-based authentication only for native apps.

OpenID Connect comes into play when your needs go beyond a simple authentication. You should look for a standards-compliant Identity provider if you need [Single Sign-On](https://auth0.com/docs/authenticate/single-sign-on) (SSO), for example. If you expose your API to third parties, you can leverage the benefits of a standard authorization approach such as OAuth 2.0. In these cases, ASP.NET Core Identity is not a good fit.

Check [this document](https://learn.microsoft.com/en-us/aspnet/core/security/how-to-choose-identity-solution?view=aspnetcore-8.0) for some guidance on when ASP.NET Core Identity is sufficient or when you need an OpenID Connect server.

## Some Caveats About Identity API Endpoints

The discussion so far is intended to help you make the right choices for authentication in your .NET applications based on your specific application scenario. This will help you avoid overdesign and make an informed choice about the right approach.

If you have decided to use the Identity API for your SPA and native application, there are still a few caveats that you still need to be aware of.

The Identity API is a great addition that allows you to leverage the user authentication and management under the hood, while you can customize your own UI. However, there is currently no way to make its endpoints unavailable. All Identity API endpoints are exposed. For example, anyone can call the `/register` endpoint to create a new user, regardless your application's business logic expects self-registered users or not. Presumably this will be fixed in the future, but as for .NET 8, it's like this.

A second concern is that you can't customize the Identity API endpoints. In most cases, you may not need customization, but what can you do if you need to customize the data required in the `/registration` endpoint? Or even add an unsupported authentication method, such as [WebAuthn](https://webauthn.me/introduction)?

Include these questions in your ASP.NET Core Identity evaluation.

<include src="SignupCTA" />

## Recap

In summary, .NET 8 brings exciting new features to ASP.NET Core Identity: token-based authentication and the Identity API.

However, this does not mean that they are the right approach for your specific scenario. Take some time to analyze what you need right now and in the near future. Don't follow the trend without carefully analyzing your needs and what ASP.NET Core Identity can offer you. You probably don't need token-based authentication for your SPA. Perhaps the simple token format for the Identity API is enough for your needs.

Anyway, if your analysis leads you to use OpenID Connect, don't forget that [Auth0 can help you](https://a0.to/blog_signup)! 😎


Cookies, Tokens, or JWTs? The ASP.NET Core Identity Dilemma

jess-author

Jessica Temporal is a Senior Developer Advocate at Auth0 and co-founder of the first Brazilian data science podcast called <a target='_blank' href='https://pizzadedados.com'><strong>Pizza de Dados</strong></a>. She’s the author of <a target='_blank' href='https://www.amazon.com/dp/B0CDNX6NS7/ref=sr_1_1?&_encoding=UTF8&tag=jesstempora0e-20&linkCode=ur2&linkId=efc4229f6b816609dfce4f185781d99a&camp=1789&creative=9325' ><strong>The Big Git Microbook</strong></a>, creator of <a target='_blank' href='https://gitfichas.com/en'><strong>GitFichas.com</strong></a>, and a part of <a target='_blank' href='https://www.linkedin.com/learning/instructors/jessica-temporal'><strong>LinkedIn Learning</strong></a> instructors team. Jessica helped develop the AI that identifies possible unlawful expenses from Brazilian politicians. She is part of the PyLadies initiative that works to improve diversity and inclusion in technology. In her free time, she likes to knit, play video games, use her 3D printer, and is learning to create 3D models.

Sr. Developer Advocate

Jessica Temporal

Learn how to create a new custom action that will add a custom claim to your Auth0-issued ID Token

Did you know that you can use Actions to customize the user ID token? Well, if you need to add custom claims to your users' ID tokens, you came to the right place! With this tutorial, you'll learn how to use the power of Actions to include custom claims to users' ID tokens.

If you prefer, you can also watch the videos below with me explaining to add custom claims to your users' ID tokens using Actions 👇!

<AmpContent>
<amp-youtube
    data-videoid="DpGRU9mttDw"
    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/DpGRU9mttDw' frameborder='0' allowfullscreen></iframe></div>

</NonAmpContent>

## Auth0 Issued ID Tokens and Custom Claims

[ID Tokens](https://auth0.com/docs/secure/tokens/id-tokens) are commonly used in token-based authentication to pass user information to a client application. At Auth0, ID Tokens follow the [JSON Web Token (JWT)](https://auth0.com/docs/secure/tokens/json-web-tokens) standard; this means that all ID tokens Auth0 issues are JWTs.

Claims are pieces of information about a given subject. In the case of ID Tokens, claims will contain information about the user, such as the user's name. Using custom claims can give your ID token extra information that can improve your application, for example, storing a user ID from a third party or system.

In this example, you'll see how to use Actions to make a request to an external API and store back the obtained information as a custom claim to ID token payload to be used on the sample application.

## The Sample Application

Before you begin, you will need a sample code to customize.

>  For this blog post, you will use the React single-page application (SPA) sample. Keep in mind that <u>you can use what you'll learn here and apply it to your app no matter what language or framework it uses</u>.

You can clone the sample application from GitHub with the following command:

```bash
git clone https://github.com/auth0-blog/assign-random-dog.git
```

After the cloning finishes, follow the [README.md file](https://github.com/auth0-blog/assign-random-dog/blob/main/README.md) instructions to configure it to use Auth0. You'll need an Auth0 account, and if you don't have it, <a href="https://auth0.com/signup"  data-amp-replace="CLIENT_ID"  data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">you can get one for free here</a>.

After configuring the sample application, you can go into the app root folder and run it with the following command:

```bash
npm start
```

Open your browser and access [https://localhost:3000/](https://localhost:3000/). You should get the following page:

![Sample app home page](https://images.ctfassets.net/23aumh6u8s0i/1KGVVbq1ML8VZkXFhPgAWJ/205d7b2cac63ab7c718aa74d2c1d056a/starter-react-app)

## What Are Auth0 Actions?

If you are new to this neck of the woods, this might be your first time hearing about Actions, don't worry; I got you covered, but if you are familiar with Actions, feel free to jump to the next section.

As mentioned, you will use Actions to add a custom claim to your users' ID tokens, and Actions are the new way to extend Auth0 functionalities. They are JavaScript functions running in a Node.js environment executed when specific events happen in some internal Auth0 flows.

 For example, Actions can be triggered when a user authenticates or changes their password. Today, you'll build an Action that will run after a user logs into your application, and as a result, the ID token will have a new custom claim. You can imagine this process as shown in the image below:

![Post login registration Auth0 Action](https://images.ctfassets.net/23aumh6u8s0i/3bMftYmivpwjXYRrQCS1fo/575d293ccfe8dfdada67eea035f85084/login-flow-with-assign-random-dog-action.png)

The Action code itself is implemented inside the Auth0 Dashboard, with an in-browser editor that allows you to write the code and use a prepared test environment to test your code. Also, you can deploy the code and use the versioning tool, but you will see more of that later.

>  You can check out these blog posts for [a quick introduction to Auth0 Actions](https://auth0.com/blog/introducing-auth0-actions/) and how they [compare with the deprecated Rules and Hooks](https://auth0.com/blog/actions-now-generally-available/).

## Implementing The Assign Random Dog Action

Having fun while learning new things makes everybody's life easier! For your custom claim, you will call an external API to grab a random dog picture to be displayed every time the user navigates to their user profile. Right now, your profile page looks like this:

![image of the profile page for the react sample showing the id token](https://images.ctfassets.net/23aumh6u8s0i/6aJLZd3bQM1upkXkszdidq/bfe3e6c3b4d444c7e6caf93f81261668/profle-page-react-sample-spa-showing-id-token-of-the-user.png)

And you want to make it look like this:

![image of the profile page for the react sample showing the id token and a random dog picture](https://images.ctfassets.net/23aumh6u8s0i/75eMhiO9yzow8C9Z3b2hor/006aceb5662bb41d70f0e0f4e07a98a8/updated-profile-page-to-display-the-dog-picture.png)

The API you will use is the [Dog API](https://dog.ceo/dog-api), which claims to be _"the internet's biggest collection of open source dog pictures."_ This API has a "random" endpoint that gives back JSON containing the URL for a dog picture it chooses randomly from its database. That URL will be the value of your custom claim.

Let's go back to the [Auth0 Dashboard](https://manage.auth0.). Choose _Actions_ on the left-hand side menu, and you should see two options there:

1. **Flows:** the processes that can be extended with Actions. Each Flow is made up of one or more triggers and represents the logical pipeline through which information moves during a single point in the Auth0 journey, for example, the _Login_ Flow;
1. **Library:** contains all your Actions. They can be either ready-to-use [Actions built by third parties and published in the Auth0 Marketplace](https://marketplace.auth0.com/features/actions) or custom Actions, like the one we are building today.

So click on _Flows_ and choose the _Login_ flow. This will take you to the following page, where you can see your current login flow. There you will be able to edit the flow and add your custom action:

![image of the page for the login flow where you can adjust the flow and add Actions](https://images.ctfassets.net/23aumh6u8s0i/1fnnTVUuTmerNDjqA0fF9c/aa26492109ec1521e38c5ce0488454ce/login-flow-action-page.png)

On the right-hand side, you'll see the list of your Actions. The ones that come from the marketplace and the custom ones you implement yourself.

![image of the Actions menu on the flow page](https://images.ctfassets.net/23aumh6u8s0i/6wIs79eD5UC4GQwY49JeGQ/632a1db6c9949144157648f6f26af717/actions-menu-on-login-flow-page.png)

Click on the **+** sign button on the top right-hand corner, and you'll see a menu that will either take you to the marketplace if you select _Browse Actions_ or will allow you to create a new Action if you select _Build Custom_. The latter is the option you'll want. It will then display a _Create Action_ form. Now you can give your Action a name that represents what it does. For example, you could use _"Assign random dog"_ to the action you are creating:

![image of the create new action form filled with the assigned new dog name](https://images.ctfassets.net/23aumh6u8s0i/2s1L6MHln402rQRrd7zsIo/776766567106baaee161667655a26331/create-new-action-assign-random-dog.png)

You can keep the default values for the other two fields. These fields define the flow where the action can work, in this case, the _Login Flow_, and which Node.js runtime will be used to run the Action. Click the _Create button_ in the form, this will create your Action, and you will see the in-browser editor.

![image showing the in-browser editor for Actions](https://images.ctfassets.net/23aumh6u8s0i/1Navuh8xu0m94CKGT9Xgz0/a08f24e24f063e3127ba828c841c850c/assign-random-dog-actions-in-browser-editor.png)

Take a closer look and see the editor already has some code and comments to help you write code for your Action. Let's take a moment to understand what it says.

First of all, since you are editing an Action that will run during login, it can be an event that occurs _post login_ or an event that happens after the user _resumes the login after an external redirect_. For this case, you need a _post-login_ event so you can focus on that part of the code copied below:

```javascript
/**
* Handler that will be called during the execution of a PostLogin flow.
*
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onExecutePostLogin = async (event, api) => {
};
```

The function `onExecutePostLogin` receives the `event` and the `api` parameters.

The `event` object carries information about the login context, for example, which authorization was granted to the user while logging in. For more details on this, [refer to the post-login `event` object documentation](https://auth0.com/docs/customize/actions/triggers/post-login/event-object).

The `api` object, on the other hand, has methods for changing the behavior of the flow, like denying access to the app if you want more details on this object [refer to the post-login `api` object documentation](https://auth0.com/docs/customize/actions/triggers/post-login/api-object).

For the Action to work, you will also need to install `axios`, an NPM package that will make the request to the _Dog API_ `random` endpoint. A cool feature of Actions is that you can add almost any NPM package as long as it can be installed without relying on native add-ons. So let's do this first and then go back to the code.

Notice that there are three tabs on the left-hand side of the editor:

- The ▶️ icon: where you can run a test suite to see if your action is performing as expected;
- The 🔑 icon: where you can access the secret storage menu; 
- The 📦 icon: where you can install NPM modules.

Since you need to install `axios` on the environment for your Action to work properly, click on the 📦 icon, and you'll see a sidebar inside the editor with the _Add Module_ button. Click the _Add Module_ button, and you'll see a form where you can put the name of the module you want to add, like this:

![image showing the add module form](https://images.ctfassets.net/23aumh6u8s0i/6Y06KN0mPllDHs7fZ2vMAJ/b4e1bb4112650ed2866a4fdffb445fdd/adding-axios-package-on-actions-modules-page.png)

Now `axios` is available for you to use on your action. If you click the 📦 icon, the modules sidebar will be hidden, and you can go back to full editor space. Now substitute the code in the editor with the following code:

```javascript
exports.onExecutePostLogin = async (event, api) => {
  const axios = require("axios");

  const randomDog = await axios.get("https://dog.ceo/api/breeds/image/random");

  if (event.authorization) {
    api.idToken.setCustomClaim("https://dogfy.com/random_dog", randomDog.data.message);
  }
};
```

Inside the function, the logic is as follows:

1. First, you import the `axios` package into the variable `axios` so you can use it;
1. Second, you make a `GET` request to the `random` endpoint of the Dog API and restore the resulting response in the `randomDog` variable;
1. Finally, if the event is an _authorization_ flow, you use the `api.idToken.setCustomClaim` to create your custom claim.

The third and last step uses the `setCustomClaim` method to create the custom claim and give it the value returned from the Dog API. There are two important things to notice here:

1. The first one is that your custom claim name should always try to avoid clashes with standard claims, one way to achieve this is by using the URI format to name that claim. For example, here, we used `"https://dogfy.com/" + "random_dog"` to set the name of your claim, and the URL doesn't even need to be a real-life URL. [You can read more about naming custom claims here](https://auth0.com/docs/secure/tokens/json-web-tokens/create-namespaced-custom-claims).
2. The second thing to notice is that to access the URL for the dog picture, you use `randomDog.data.message` because the JSON containing the URL is located inside `data` on the response structure.

Now that you've got your code, you can go ahead and click the *Deploy* button on the top left corner, which will save the Action and make it available for use. After deploying your Action, you need to go back to the flow to add it. On the right-hand main menu, choose _Actions_, then _Flows_, and pick the _Login_ flow; now, if you look at your _Add action_ section, and if you click on the _Custom_ tab, you should see your Action in there:

![image of the Add action section showing the action under the Custom tab](https://images.ctfassets.net/23aumh6u8s0i/2niMVNWCOOGLBXX41aBHqf/888096695e7902859ddde3c27af044fe/custom-action-being-displayed-on-add-action-section.png)

With that said, it is time to drag your Action, drop it on the Flow, and don't forget to click _Apply_ to make your Action part of your _Login_ flow.

![gif showing the drag and drop of the action into the flow and its deployment](https://images.ctfassets.net/23aumh6u8s0i/3uf5YKYg6kbcnbNgeTPetO/553b988408dc4063a4484f787eaf44b5/drag-and-drop-new-action-into-the-login-flow.gif)

You can test to see if the change worked by logging out of your application then logging back in once more. You should see on the _Profile_ page that the ID token content was updated and the new custom claim is there:


![image of the profile page for the react sample showing the id token the new custom claim](https://images.ctfassets.net/23aumh6u8s0i/1lDrIOzfo8Mp2nWv9W0I19/34299cfc6cfafe925e2953c94cb789ce/updated-profile-page-react-spa-with-custom-claim.png)

## Updating Your Application to Use the Custom Claim

Now that we have the URL for the dog picture is time to update the profile page to display it. Let's see how to do that.

> Since the sample application is built with React, the steps described in this subsection are strictly related to this library. <u>This step aims to update the profile page to display a cute dog picture</u>, so feel free to adapt this step to your needs.

On the project source code, navigate to the file `Profile.js` inside `src/views` directory. Then add the code highlighted below:

```javascript
import React from "react";
import { Container, Row, Col } from "reactstrap";

import Highlight from "../components/Highlight";
import Loading from "../components/Loading";
import { useAuth0, withAuthenticationRequired } from "@auth0/auth0-react";

export const ProfileComponent = () => {
  // ...existing code...

      <Row>
        <Highlight>{JSON.stringify(user, null, 2)}</Highlight>
      </Row>

    // 👇 new code
    {user["https://dogfy.com/random_dog"] &&  <div style={{textAlign: 'center'}}>
    <h2>Our Doggy!</h2 >
    <img
        src={user["https://dogfy.com/random_dog"]}
        alt="Random dog"
        className="img-fluid profile-picture mb-3 mb-md-0"
      />
    </div>}
    // 👆 new code

    </Container>
  );
};

// ...existing code...
```

This code will add a picture from the ID token to the profile page whenever there is a `"https://dogfy.com/random_dog"` claim. Your page should automatically reload itself and display the current dog picture:

![image showing the new profile page displaying the dog picture](https://images.ctfassets.net/23aumh6u8s0i/75eMhiO9yzow8C9Z3b2hor/006aceb5662bb41d70f0e0f4e07a98a8/updated-profile-page-to-display-the-dog-picture.png)

With that done, your application is ready. 🎉 Congratulations! 

You can check out [the complete code changes, access this link](https://github.com/auth0-blog/assign-random-dog/tree/profile-page-updated) or switch to the branch `profile-page-updated` on your sample app.


## Recap

You just implemented a brand new Action to be used during the Login flow 🎉. Let's recap what you've learned:

1. You set up a SPA using Auth0;
1. You learned what Actions are and how you can use them to expand Auth0's functionalities;
1. You implemented an Action that makes a call to an external API, and that creates a custom claim with data from the response;
1. Finally, you deployed that custom action and updated your app to use the custom claim.

Keep in mind that this was a colorful way to show how you can use Actions to make a call to an external resource and add a custom claim on the user's ID token. Now you can let your imagination fly and use the knowledge you acquired today to add useful information to your user's ID tokens.

Are you ready to add more custom claims to your user's ID tokens? Let me know in the comments 😉.

Adding Custom Claims to ID Tokens with Auth0 Actions

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?

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.


"id_token"