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.

Principal Developer Advocate

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

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

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 - Developer Experience & Analytics

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

A step-by-step guide to leveraging OAuth 2.0 Refresh Tokens in an iOS app built with Swift and integrated with Auth0.

Using a Refresh Token in an iOS Swift App

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.

Andrea Chiarelli

Learn how to keep tokens more secure by using the Backend for Frontend (BFF) architectural pattern.

One of the biggest challenges for applications using OAuth 2.0 and OpenID Connect is token security. Preventing an ID, access, or refresh token from falling into the wrong hands is a priority of these protocols. The specs have adopted several technical solutions, and some best practices have been proposed. Among the latter is the use of the Backend for Frontend pattern, whose rationale and architecture we will analyze in this article.

## OAuth 2.0 Client Types and Security

OAuth 2.0 defines two types of client applications: public and confidential clients. This classification is based on the application's ability to keep authentication credentials secure. From [the specs](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1):

- **Confidential**. Clients capable of maintaining the confidentiality of their credentials (e.g., client implemented on a secure server with restricted access to the client credentials), or capable of secure client authentication using other means.
- **Public**. Clients incapable of maintaining the confidentiality of their credentials (e.g., clients executing on the device used by the resource owner, such as an installed native application or a web browser-based application), and incapable of secure client authentication via any other means.

In a nutshell, confidential clients are those applications that run in a protected environment, such as a server, while public clients are applications that run in an uncontrolled environment, such as the user's device. Typical confidential clients are traditional web applications, while typical public clients are Single-Page Applications (SPA), desktop and mobile apps.

From a security perspective, public clients can't store their credentials securely. There is a high risk of tokens falling into the wrong hands. This can happen either because of a potential lack of protection on the local system or because of the potentially large number of instances of the application that increase the attack surface.

To mitigate the problem of issuing a token to a client that can't be authenticated (i.e., a public client), a specific flow has been designed: the [Authorization Code Flow with PKCE](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce). Anyway, this does not solve all the concerns about the security of a public client.

## SPA Security and Tokens

Another concern for public clients is token storage. Once an ID or access token is received from the server, how can a public client protect it from unauthorized access? As long as the application is running, the application memory is the safest place to store tokens. But what if the application stops running temporarily?

For example, consider a SPA that has a token in memory. What happens when the user refreshes the page on which the application is running? The token is lost, and the user is forced to authenticate again for the application to obtain a new token.

You could consider storing the token in the browser's local storage or in a cookie and reloading it after the refresh, but this is not a recommended practice. A malicious user or application could gain access to the local storage or cookie and obtain the token. See [this article for more information on the risks of using browser storage](https://auth0.com/blog/secure-browser-storage-the-facts/).

Something similar happens with native applications (desktop and mobile): when the user closes the application, all tokens are lost, requiring authentication the next time the application is opened. While this may be acceptable in certain contexts, many users have become accustomed to not having to authenticate every time they open their app, especially in the mobile environment. However, native applications have an advantage over SPAs. The presence of secure storage mechanisms in most popular operating systems, such as Keychain in iOS/Mac or Keystore in Android.

The level of security required by an application depends on its specific functionality. It is the result of balancing the data confidentiality requirements with the ease of implementation. Therefore, in some contexts, using the Authorization Code Flow with PKCE and all the concerns about token management in a SPA may be acceptable. In other contexts, it is not. What can you do for those contexts where you can't absolutely risk a token falling into the wrong hands?

## The Backend For Frontend Pattern

A seemingly marginal note in [the definition of client in the OAuth 2.0 specification](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1) suggests a solution:

*A client may be implemented as **a distributed set of components, each with a different client type and security context** (e.g., a distributed client with both a confidential server-based component and a public browser-based component).*

This paves the way for the adoption of a well-known architectural pattern: the **Backend for Frontend** (BFF) pattern. This is a popular pattern to address specific needs for a client platform by building a dedicated backend. The needs may be of various types: decoupling of concerns, flexibility and maintainability, optimized performance, security, etc.

> Read [this document](https://philcalcado.com/2015/09/18/the_back_end_for_front_end_pattern_bff.html) to learn how this architectural pattern was born.

In our case, we are interested in strengthening the security of SPAs in the context of OIDC and OAuth 2.0, and the [best current practices](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-browser-based-apps#name-backend-for-frontend-bff) give us some guidelines about using this pattern.

Let's explore how the BFF pattern works.

### The BFF architecture

The actors involved in a typical scenario where a SPA uses the Authorization Code Flow with PKCE are shown in the following diagram:

![Architecture of a SPA using OIDC and OAuth2](https://images.ctfassets.net/23aumh6u8s0i/4PBIbTFxPR4PalUltQQEgV/69698b96960c0368e7429f6d1e3d8549/spa-oidc-oauth-architecture.png)

The SPA interacts with the authorization server to get the ID, access, and refresh tokens. Then, the SPA uses the ID token to get data about the user, the access token to call an API, and the refresh token to get a new access token once it expires.

In this scenario, all the tokens are in the hands of the SPA.

By applying the BFF pattern, we are going to enter a new component in this architecture, the dedicated backend, as shown below:

![BFF architecture](https://images.ctfassets.net/23aumh6u8s0i/43eXspNnMJS3ImbvAva0R9/5cf40b564dcbd03eb7394c15078d8b63/bff-architecture.png)

In this new scenario, the backend has three core responsibilities:

- It interacts with the authorization server as a confidential client.
- It manages all the tokens on behalf of the SPA, which can't access them anymore.
- It proxies all requests to the API, embedding the access token before forwarding them.

The SPA only interacts with the backend, relying on traditional cookies for authenticated sessions. Basically, the backend exposes a number of endpoints that let the SPA access the user profile data and the remote API.

This architecture improves the security of token negotiation, since it now happens via a confidential client, and token storage, since it now occurs on the server side.

### The BFF flow

Let's take a look at how the actors in this architecture interact with each other by following this diagram:

![Backend for Frontend flow](https://images.ctfassets.net/23aumh6u8s0i/6uM2x48XekNyFpODMiFjJq/c351e6278219b3865bd0bc6dd33e828b/backend-for-frontend-bff-flow.png)

Here are the descriptions for each step:

1. The SPA points to a backend URL (`/login` in the example above) to let the user authenticate.
2. The backend starts the usual OpenID Connect negotiation with the authorization server: it redirects the user browser to the authorization endpoint to authenticate the user and get the needed tokens.
3. The authorization server issues the tokens to the backend, which can store it in a cache.
4. The backend issues a cookie representing the user session and triggers the reloading of the SPA in the browser.
5. The SPA makes an API request to the backend including the cookie.
6. The backend validates the SPA request, retrieves the associated access token, and uses the token to make a call to the API.
7. The API returns a response to the backend.
8. The backend forwards the response to the SPA.

## Caveats and Variations

The BFF pattern solves the main concerns about using SPAs in an OIDC/OAuth 2.0 flow:

- There is no longer a public client negotiating the tokens, but this negotiation is now the responsibility of a confidential client represented by the backend.
- The SPA no longer needs to store tokens to prevent user re-authentication after page refresh.

To properly implement the BFF, there are a few caveats you need to pay attention to:

- The session cookie issued by the backend must be marked `Secure` and `HttpOnly`.
- The cookie must be associated with the token(s) issued by the authorization server.
- The tokens can be stored on the server side or in the session cookie. In the latter case, the cookie must be encrypted.
- The backend must implement all the measures to prevent Cross-Site Request Forgery (CSRF) attacks.
- The BFF pattern does not work for a standalone SPA that relies on calling a protected API directly from JavaScript. The SPA must be hosted by the backend, which is implemented as a regular web application.

While the BFF pattern solves the main security concerns of token exchange and storage for SPAs, some developers are concerned about performance issues. Specifically, the mediation run by the backend as a proxy API can be a bottleneck in some contexts. There is an alternative to the BFF pattern that meets this need, but it comes at the cost of reduced security.

This alternative is the [Token-Mediating Backend pattern](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-browser-based-apps#name-token-mediating-backend), which allows the backend to negotiate the tokens as in the BFF pattern but provides the access token to the SPA. This way, the SPA can directly call the protected API using the access token. While this pattern keeps token negotiation secure by always relying on the backend as a confidential client, it leaves the issue of storing and protecting the access token open. To overcome this issue, you can consider [using OAuth 2.0 with DPoP](https://auth0.com/blog/oauth2-security-enhancements/#Demonstrating-Proof-of-Possession--DPoP), which binds an access token to the client, making it no longer a bearer token. In this case, you need a DPoP-enabled authorization server, of course.

## Summary

Now you have a better understanding of the concerns related to token management and SPAs. You learned that SPAs, like any public client, are not always a safe place to handle ID, access, and refresh tokens. Much depends on the specific business requirements of the application, of course.

If you need a more secure architecture for your SPA, you can apply the Backend for Frontend pattern. This pattern introduces a dedicated backend for token negotiation and management on behalf of the SPA. This way, no tokens will reach the SPA, while the backend will also take charge of proxying the requests to a protected API.

The Backend for Frontend Pattern

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

Learn why and how to use refresh tokens in ASP.NET Core applications.

Use Refresh Tokens in ASP.NET Core Apps

Majid Hajian

I am a Google Developer Expert and Media Developer Expert and a passionate software developer with years of developing and architecting complex web and mobile applications. my passions are Flutter, PWA, and performance. I love sharing my knowledge with the community by writing and speaking, contributing to open source, and organizing meetups and events.

Google Developer Expert

In this tutorial, you’ll learn how to enhance your Flutter apps by enabling authentication, supporting federated identity providers, adding authorization by introducing roles and permissions, all leveraging Auth0.

In the exercise from the previous section, you added Auth0 authentication to an existing Flutter app. This added a username/password authentication flow to the app. You also gave the app the ability to request and submit refresh tokens, which enhance the user experience by not requiring the user to authenticate every time they use the app.

This section will expand on the app by examining some useful Auth0 features:

* Refresh token rotation
* Social logins
* Managing your Auth0 account

> **Look for the 🛠 emoji if you’d like to skim through the content while focusing on the build and execution steps.**


## Add Refresh Token Rotation

When the app makes an authentication request to Auth0’s authentication server, it includes the `offline_access` scope. This causes the authentication server to issue a refresh token, which the app can use to re-authenticate without requiring the user to log in again. The app stores this token in the device’s secure storage.

While this enhances the app’s user experience, it also introduces risk. The refresh token is long-lived, and the app could use it as a “lifetime pass” to endlessly request new access tokens and keep the user logged in forever.

I highly recommend taking advantage of *Refresh Token Rotation* and *Automatic Reuse Detection* to help mitigate this risk. With these features enabled, each refresh token can be used only once. When the app exchanges its refresh token for a new access token, the authentication server also returns a new refresh token and invalidates the old one. 

Let’s enable these features!

🛠 Navigate to the **Applications** section of your Auth0 dashboard, select the **MJ Coffee** application, and then select its **Settings** tab. Scroll down the page to the **Refresh Token Rotation** section and turn on the **Rotation** and **Absolute Expiration** options:

![Turn on the “Rotation” and “Absolute Expiration” options.](https://images.ctfassets.net/23aumh6u8s0i/6EizPZZnkGjxoAOle1Q8eL/e06c99f4a49413572736bbf0f470436c/rotation_and_absolute_expiration.png)

It is recommended that you issue a refresh token that expires after a preset lifetime. The refresh token’s lifetime can be extended each time one is used to get a new access token or access token/refresh token pair.

There are two options for token lifetimes, and they can be set independently of each other:

- **Absolute Lifetime:** Enabling **Absolute Expiration** sets a specified *absolute lifetime* for the application’s refresh tokens. Refresh tokens can be exchanged for new access tokens during this lifetime. Once the token’s age goes past its lifetime, the user will need to re-authenticate in order to get a new access token. If **Absolute Expiration** is disabled, the refresh token has an indefinite absolute lifetime.
- **Inactivity Lifetime:** Enabling **Inactivity Expiration** specified *inactivity lifetime* for the application’s refresh tokens. Refresh tokens can be exchanged for new access tokens if the user is active in the application during this lifetime. If the user is inactive in the application for a period longer than the inactivity lifetime, they will need to re-authenticate in order to get a new access token.

🛠 Scroll to the bottom of the page and click the **Save Changes** button:

![The “Save Changes” button. The user is directed to click it.](https://images.ctfassets.net/23aumh6u8s0i/7KsLW4adJ6PNIPAI12al4g/f2c0e8abf6d7377595cfb7df11493e67/save_changes.png)


## Social Logins

These days, it's pretty common to have login methods beyond the standard username/password combination. These include logging in with social media account, which will significantly enhance your users’ experiences.

Implementing these additional login methods and adding them to your authorization server is time-consuming and will come with many considerations and risks. 

Luckily, Auth0 provides lots of integration with well-known third parties’ authentication systems, and even allows you to write your custom connections. Let's add connections to both Google’s and Apple’s authentication systems.


### Create a Google/Gmail social connection

🛠 In the Auth0 dashboard, select **Authentication** in the left column menu, then select **Social**. This takes you to the **Social Connections** page, where you should click the **Create Social Connection** button:

![The steps to create a new social connection in Auth0](https://images.ctfassets.net/23aumh6u8s0i/61w1eXrbY7bGOpNo6ODbaU/da810c63bacd28cabf71e6dee4baa349/create_social_connection.png)

You will be taken to the **New Social Connection** page, which has a list of social login providers that integrate with Auth0. 

🛠 Select **Google**:

![Selecting Google from all the available social connections](https://images.ctfassets.net/23aumh6u8s0i/2YdUxIkwmCTcc9QFlo584q/22f7fd0bf4bc1c93c4ebc555e21009f8/select_google.png)

You will now be on the  **New Google / Gmail Social Connection** page, which tells you what kind of user information is accessed by Google social login.

🛠 Click **Continue**:

![Initial page for creating a new Google/Gmail social connection](https://images.ctfassets.net/23aumh6u8s0i/2SQwtF0vqtXJucnGbE3DNS/baf5bd9d7103a6ecbd59b879bbe2aaf4/click_continue.png)

A new page with a number of fields will appear; this is the connection’s **Settings** tab. 

As long as you’re working in a development environment, you only need to fill the **Name** field (which provides a name for this connection) and leave all the other fields empty. You can always use the default value in the **Name** field:

![New Google/Gmail social connection](https://images.ctfassets.net/23aumh6u8s0i/7Jzsn4ryILOOdACN2urlSo/fdaa205ef09352c0b9aba0acbd592977/new_google_gmail_social_connection.png)

However, production apps require you to provide a **Client ID** and **Client Secret** ([doc](https://auth0.com/docs/connections/social/google)) and specify the **Allowed Mobile Client IDs**. These topics will be covered in another video or article.

🛠 Create the Google/Gmail connection by scrolling to the bottom of the page and clicking **Create**:

![Creating the Google/Gmail connection](https://images.ctfassets.net/23aumh6u8s0i/4S8AJUaj4xehVwVxhNDt5X/69eb88b8bec557d310d0e9d678fe9b7e/click_create.png)

This will create the connection, and you’ll be taken to its **Applications** tab. You’ll see a list of your applications, which will allow you to enable the Google/Gmail connection for any of them. Enable the connection for the *MJ Coffee* application:

![The Google/OAuth2 applications tab](https://images.ctfassets.net/23aumh6u8s0i/681u1RRcha4ABJJ5GRZivy/c7eea90ca4e19ec5ab3b333caa47e5ba/google-oauth2_applications_tab.png)

You may also set more permissions that the end-user will need to approve during authorization. These permissions depend on your application and what you want to do on behalf of the user. The *MJ Coffee* app doesn’t need any extra permissions beyond the basic and extended profile.

![Google Permission](https://images.ctfassets.net/23aumh6u8s0i/13CvLX8tQUTuqU6jpZ6K94/a0eaac13b8fc83fc11b3ca3f6651ebd9/google_permissions.png)

🛠 Make sure you sync user profile attributes at each login and hit the **Save** button.


### Create an Apple ID social connection

🛠 Once again in the Auth0 dashboard, select **Authentication** in the left column menu, then select **Social**. This takes you to the **Social Connections** page, where you should click the **Create Social Connection** button:

![The steps to create a new social connection in Auth0](https://images.ctfassets.net/23aumh6u8s0i/1sohaZxDHuq8X8ZvT5nhvE/d2b7a7e2647708327f8fc6971ddb43a9/create_connection.png)

🛠 This time, select **Apple**:

![Selecting Apple from all the available social connections](https://images.ctfassets.net/23aumh6u8s0i/3JAgbtDSNOsfYrjxkE1wCI/e51d80f7418706c29cd6e9dc06b93719/select_apple.png)

You will now be on the  **New Apple Social Connection** page, which tells you what kind of user information is accessed by Apple social login.

🛠 Click **Continue**:

![Continue](https://images.ctfassets.net/23aumh6u8s0i/3zt2ntLwoHwp6bldLmOOsD/8db3e7f5c057d5782c7202b748013420/click_connect_-_apple.png)

As long as you’re working in a development environment, you can leave the **Client ID** and **Client Secret Signing Key** fields empty. You *will* need proper keys for those fields when the app goes to production; [this document covers that topic in more detail](https://auth0.com/docs/connections/apple-siwa/set-up-apple).

The **Apple Team ID** and **Key ID** values are required:

![Google Permission](https://images.ctfassets.net/23aumh6u8s0i/2qNvT5zkxB1TY06ywkH5Re/7c46fa1399743de9e7bb05d1d804fab0/apple_dev.png)

* To get your Apple Team ID, you need an Apple Developer Account.
* To get a Key ID for your app, you need to register that app using your Apple Developer Account. 

🛠 Sign in to your Apple Developer Account, and go to the **Membership** page and make a note of your Team ID.

🛠 If you have a registered app, you can skip the following steps and jump to the list of tasks for creating a service ID. Otherwise, follow the steps below:

- In the Apple Developer Portal, go to **Certificates, IDs, & Profiles > Identifiers** and click the blue “plus” icon next to **Identifiers** to create a new App ID.
- Choose **App IDs** as the identifier type and click **Continue**.
- Provide a description and a Bundle ID in reverse-domain name format (e.g.: `com.mydomain.mjcoffee`).
- Scroll down and check **Sign In with Apple**.
- Click **Continue**, and then click **Register**.

🛠 Once the app is registered, it’s time to create a service ID:

- Return to the **Certificates, IDs, & Profiles** section, and click the blue “plus” icon next to **Identifiers**.
- Choose **Service IDs** and select **Continue**. Fill in the description and identifier (e.g.: `com.mydomain.mjcoffee`).
- After checking **Sign In with Apple**, select **Configure**, and define your Web Domain (e.g.: `com.mydomain.mjcoffee`) and your "Return URL". Ensure that your Return URL is your Auth0 domain and that it follows this format: `https://YOUR_AUTH0_DOMAIN/login/callback`.

![Return URL apple sign in](https://images.ctfassets.net/23aumh6u8s0i/5Wetff0Tutv55UXsYz0gKq/ab19cd3e48604aea314410d22d194982/callback_apple.png)

🛠 Finally: save, continue and then register the service.


#### Set up your Client Secret Signing Key

🛠 Follow these steps:

- Go to **Keys**, which is located in the **Certificates, Identifiers, & Profiles** section of your Apple developer dashboard.
- Select the blue “plus” icon to add a new key.
- Enter a **Key Name** and check the **Sign In with Apple** option.
- Select **Configure** to make sure the **Choose a Primary App ID** field is filled with the correct App ID.
- Select **Save, Continue**, and then **Register**.
- On the page to which you're redirected after registering, make a note of the Key ID. Then download the key; it will have a `.p8` filename extension.

🛠 Go back to your Apple social connection settings and paste the Key ID. Ensure the proper attributes are selected (Name, Email) and sync user profile at each login is enabled. Hit **Save**.


## Enable Social Connections

🛠 Once you have created all your social connections and set them up correctly, go back to your applications. Go to the **Connections** tab and enable your newly-made social connections:

![app social connections](https://images.ctfassets.net/23aumh6u8s0i/59SCRbiX055qDcmTSNwPVl/fa175f974ceb43515893f24f7747d549/app_social_connections.png)

As you can see, adding and removing social connections for your apps is now as simple and flicking a switch.

On the Flutter side, I have good news: you don’t need to implement anything there! 

Restart the app, log out, then try to log in. You’ll see this:

![app social connections](https://images.ctfassets.net/23aumh6u8s0i/4b6BIaeZ8EHcN1a3MYVOrF/91c9039cf0d56051c99397d1a7524a3e/social_buttons_flutter.png)

That's it! The login screen will now display social login buttons, and their login flows will be ready to use.


## Branding 

While it’s fine to use the default branding in development, you want the login page to be customized to your “look and feel” once the app’s in production.

Auth0 allows you to customize your login page through a number of options. You can change the look and feel of the login page by adding colors and logos, and you can customize the user notification part of the process as well: email templates, text messages, and so on. It’s all in the **Branding** section of the Auth0 dashboard:

![Auth0 branding](https://images.ctfassets.net/23aumh6u8s0i/7oq6VzFQ3nSUcStZTXvjQu/38d1e272f3bef751d9feaca704d580dc/branding.png)


### Add Roles

You may want to provide certain functionalities to the user based on their roles. This is easy with proper authorization server such as Auth0, which facilitates adding roles and specifying what users in each role are allowed to do. 

In the MJ Coffee app, there are three different roles:

- **Admin:** These are administrators, and they will have access to all the app’s functionality with full permissions.
- **Customer:** This is the default role for registered or logged-in users. They are limited to the app’s customer-facing features. You will automatically assign this role to all users upon registration or login, and you will learn how to do so later on in this tutorial.
- **Employee:** These are coffee shop employees. They can access the community screen to answer customer requests in the support chat, as well as other employee-facing features.

![Auth0 roles](https://images.ctfassets.net/23aumh6u8s0i/7nVdiU86TPCF1tLXrBg6ID/54a078bfe7d2382a6776c26adfc5cba4/roles.png)

You can add more roles to the app as the need arises.


## User Management in Auth0

Auth0 provides the infrastructure to store users and their information on its cloud database.

For the *MJ Coffee* app, Auth0’s cloud database is sufficient. One of Auth0’s goals is to reduce the cost of extra infrastructure maintenance and cost.

You can access users by selecting **User Management** in the left column menu of the Auth0 dashboard. The **Users** page allows you to create new users and manage your existing ones by changing their details, adding permissions and roles, or revoking their access.

![Auth0 users](https://images.ctfassets.net/23aumh6u8s0i/3O0JDGBqXHmPfrKaEavP2D/260c804cf50a308e696ecd9a446ab4a9/users.png)

When you open a user, you’ll see that Auth0 provides in-depth details about that user, including basic account data, metadata, their devices, and their history, which might be pretty helpful for debugging the application or investigating a particular user’s access activity, permissions, and roles.

![Auth0 user roles](https://images.ctfassets.net/23aumh6u8s0i/JcGTMspZ9hKtu9RAi4Oq9/257a692aa9a65cd12e96f645b56aafd1/user_roles.png)

Each user account stores some basic information about the user: name, email address, the date and time when the account was created, and so on. 

Additional information can be attached to a user by adding to these metadata stores:  their user metadata, which is a key-value structure for storing information about the user. You can also store information in the user_metadata or manipulating `app_metadata`, which helps to provide more information to the Flutter application while receiving user details.


## Moving Forward

In the next section of this tutorial, you will learn how to add real-time chat to the app.


Flutter Authentication and Authorization with Auth0, Part 2: Refresh Tokens, Social Logins, and More

adam-mcgrath

I've been working as an Engineer on the web for over 20 years at companies including the BBC, Google and IG. At Auth0, I build and maintain our JavaScript SDKs for servers and browsers.

SDK Engineer

Adam McGrath

Learn how the OAuth 2.0 Express SDK released by Auth0 makes protecting your Express API easier.

Auth0 has released [express-oauth2-jwt-bearer](https://github.com/auth0/node-oauth2-jwt-bearer/tree/main/packages/express-oauth2-jwt-bearer), a new [Express](https://expressjs.com/) SDK that makes it super easy to protect APIs with JWT Bearer Tokens. Let's take an overview of its features.

## Why a New Express SDK?

Auth0’s previous advice for protecting Express APIs was with a combination of three SDKs: [express-jwt](https://github.com/auth0/express-jwt), [express-jwt-authz](https://github.com/auth0/express-jwt-authz), and [jwks-rsa](https://github.com/auth0/node-jwks-rsa). And whilst these work well and are popular SDKs, we felt the developer experience could be improved.

We first wanted to simplify the process of protecting an Express API by reducing the number of dependencies from three to one. This also reduces the install size from ~2 MB to ~500 KB. You can see the benefit by comparing our [QuickStart](https://auth0.com/docs/quickstart/backend/nodejs) before and after implementing the new SDK, as shown in the following screenshot:

![SDK code lines comparison](https://images.ctfassets.net/23aumh6u8s0i/3Mkzs9yeeOboyJkwJIR9Pb/2518cadc35f2e378edbb5cb925f69026/express-sdk-comparison.jpg)

We also wanted to teach the developer community how to protect their APIs with authorization standards like OAuth2.0 rather than a collection of libraries representing token formats, algorithms, and industry abbreviations (`jwt`, `jwks`, `rsa`, and `authz`).

This is why the project's first incarnation, [express-oauth2-bearer](https://github.com/auth0/express-oauth2-bearer), was released experimentally to support our excellent [Identity Labs](https://auth0.com/docs/identity-labs/identity-lab-2-calling-api) series ([express-oauth2-bearer](https://github.com/auth0/express-oauth2-bearer) will now be deprecated in favor of [express-oauth2-jwt-bearer](https://github.com/auth0/node-oauth2-jwt-bearer/tree/main/packages/express-oauth2-jwt-bearer)).

## The Role of Standards

[express-oauth2-jwt-bearer](https://github.com/auth0/node-oauth2-jwt-bearer/tree/main/packages/express-oauth2-jwt-bearer) protects Express APIs using a combination of the well-established [OAuth2 Bearer Token Usage spec](https://datatracker.ietf.org/doc/html/rfc6750) and the new specification of [JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens](https://datatracker.ietf.org/doc/html/rfc9068).

While there’s always been a clear path for developers to acquire an Access Token from a request using the Bearer Token Usage spec, they’ve relied on best practice and industry convention when determining how to verify their authenticity.

With [JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens spec](https://datatracker.ietf.org/doc/html/rfc9068), they are able to leverage new standards to consume Access Token JWTs in an interoperable manner. [express-oauth2-jwt-bearer](https://github.com/auth0/node-oauth2-jwt-bearer/tree/main/packages/express-oauth2-jwt-bearer) partially implements the JWT Profile for OAuth 2.0 Access Tokens specification. It implements the full specification when you enable the `strict` option. Also, it is deeply customizable so that you can use it across a broad range of Identity Providers.

## Protect an Express API with JWT Bearer Tokens

[express-oauth2-jwt-bearer](https://github.com/auth0/node-oauth2-jwt-bearer/tree/main/packages/express-oauth2-jwt-bearer) uses a similar mechanism to [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) to configure itself, so it’s easy to set up with minimal effort. In just a few lines of code, you can easily add it to your API to protect it with Access Tokens issued by Auth0, for example.

To easily protect your Express API with Auth0, start by installing the SDK using npm or yarn, as in the following example:

```bash
npm install express-oauth2-jwt-bearer
```

You can initialize the SDK in code or via environment variables. For the latter, the minimal `.env` file would look like the following:

```bash
ISSUER_BASE_URL=https://<YOUR_TENANT>.auth0.com
AUDIENCE=<YOUR_API_IDENTIFIER>
```

Replace `<YOUR_TENANT>` and `<YOUR_API_IDENTIFIER>` with the values of your Auth0 tenant name and API identifier that you’ll find in the [Auth0 Dashboard](https://manage.auth0.com/). 

Then add the [express-oauth2-jwt-bearer](https://github.com/auth0/node-oauth2-jwt-bearer/tree/main/packages/express-oauth2-jwt-bearer) middleware to your API like so:

```javascript
const express = require('express');
const { auth } = require('express-oauth2-jwt-bearer');
require('dotenv').config(); // Load the .env variables

const app = express();
app.use(auth());

app.get('/api/private', (req, res) => {
  res.json({ message: `Hello ${req.auth.payload.sub}!` });
});

app.listen(3000, () => console.log('listening at http://localhost:3000'))
```

You can then start your API and test it using curl:

```bash
curl http://localhost:3000/api/private \
--header 'Authorization: Bearer ${YOUR_JWT_ACCESS_TOKEN}'
```

If you’re wondering where to get an Access Token from, you can get one for testing purposes from the Test tab of your [API configuration in the Auth0 Dashboard](https://manage.auth0.com/#/apis), as shown in the following picture:

![Copy access token from Auth0 Dashboard](https://images.ctfassets.net/23aumh6u8s0i/785NRBn9KBkiML9UF3NGO5/bcd2954c29af6637f783426e7b89ed7c/copy-access-token.png)

Check out [express-openid-connect](https://github.com/auth0/express-openid-connect) to see an example of how to [programmatically obtain an Access Token to call external APIs](https://github.com/auth0/express-openid-connect/blob/master/EXAMPLES.md#4-obtaining-access-tokens-to-call-external-apis).

## Checking for Required Scopes

If you want to additionally check the Access Token’s scopes for a specific route you can use the `requiredScopes` middleware, as shown below:

```javascript
const express = require('express');
const { auth, requiredScopes } = require('express-oauth2-jwt-bearer');
require('dotenv').config();

const app = express();
const checkJwt = auth();

app.get('/api/private-scoped', checkJwt, requiredScopes('read:msg'), (req, res) => {
  res.json({
    message: 'You need to be authenticated and have a scope of read:messages to see this.'
  });
});
```

You can also check custom claims in the Access Token using [claimCheck](https://auth0.github.io/node-oauth2-jwt-bearer#claimcheck), [claimEquals](https://auth0.github.io/node-oauth2-jwt-bearer#claimequals), and [claimIncludes](https://auth0.github.io/node-oauth2-jwt-bearer#claimincludes) (see [the docs for the full API](https://github.com/auth0/node-oauth2-jwt-bearer/tree/main/packages/express-oauth2-jwt-bearer#api-documentation)).

## Under the Hood

[express-oauth2-jwt-bearer](https://github.com/auth0/node-oauth2-jwt-bearer/tree/main/packages/express-oauth2-jwt-bearer) is a small [Express](https://expressjs.com/) wrapper around two framework agnostic packages:

- [oauth2-bearer](https://github.com/auth0/node-oauth2-jwt-bearer/blob/main/packages/oauth2-bearer): it gets Bearer tokens from a request and issues errors per the [Bearer Token Usage spec](https://tools.ietf.org/html/rfc6750).
- [access-token-jwt](https://github.com/auth0/node-oauth2-jwt-bearer/blob/main/packages/access-token-jwt): it verifies and decodes Access Token JWTs following the [JWT Profile for OAuth 2.0 Access Tokens spec](https://datatracker.ietf.org/doc/html/rfc9068) using the [jose](https://github.com/panva/jose) library.

The following diagram shows the dependencies among these packages:

![OAuth2 Express SDK dependency graph](https://images.ctfassets.net/23aumh6u8s0i/78D0oQvCSHj5SUTANEFihw/31924abc24a7841cbb73db1afd297f83/oauth2-express-libraries-dependency.png)

## What’s Happening to `express-jwt`, `express-jwt-authz`, and `jwks-rsa`?

[express-jwt](https://github.com/auth0/express-jwt), [express-jwt-authz](https://github.com/auth0/express-jwt-authz) and [jwks-rsa](https://github.com/auth0/node-jwks-rsa) are well used and loved by many Auth0 customers and remain fully supported. There’s no need to rush to update your existing apps. We will keep fixing bugs and patching them. We plan to stop adding new features to these SDKs, though, and the bar for the bugs we fix will be tuned accordingly.

If you are about to start a new Express API project, we recommend using [express-oauth2-jwt-bearer](https://github.com/auth0/node-oauth2-jwt-bearer/tree/main/packages/express-oauth2-jwt-bearer), as it will be our target for all innovation for authorization on the Node.js platform for the foreseeable future.

<include src="SignupCTA" text="Try out the most powerful authentication platform for free." linkText="Get started →" />

## What’s Next

[oauth2-bearer](https://github.com/auth0/node-oauth2-jwt-bearer/blob/main/packages/oauth2-bearer) and [access-token-jwt](https://github.com/auth0/node-oauth2-jwt-bearer/blob/main/packages/access-token-jwt) are as yet unpublished and currently just share space in the [node-oauth2-jwt-bearer](https://github.com/auth0/node-oauth2-jwt-bearer) monorepo. However, you can see how they could easily be used standalone or to create simple wrappers for other Node.js server frameworks like [Koa.js](https://www.simform.com/blog/best-nodejs-frameworks/#Koa), [Nest.js](https://www.simform.com/blog/best-nodejs-frameworks/#Nest), [Hapi.js](https://www.simform.com/blog/best-nodejs-frameworks/#Hapi). You can also use them in a range of serverless platforms, which we’ll be reviewing as part of our roadmap going forward.

If you have feedback or notice any issues hit us up via the [issues list](https://github.com/auth0/node-oauth2-jwt-bearer/issues) or the [Auth0 community](https://community.auth0.com/).

Happy coding!


Introducing the OAuth 2.0 Express SDK for Protecting APIs with JWT Bearer Tokens

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?

37590801?s=460&v=4

Howdy! 🤠 I do technology research at Auth0 with a focus on security and identity and develop apps to showcase the advantages or pitfalls of such technology. I also contribute to the development of our SDKs, documentation, and design systems, such as <a target='_blank' rel='noopener noreferrer' href='https://github.com/auth0/cosmos'><strong>Cosmos</strong></a>.<br /><br />The majority of my engineering work revolves around AWS, React, and Node, but my research and content development involves a wide range of topics such as Golang, performance, and cryptography. Additionally, I am one of the core maintainers of this blog. Running a blog at scale with <strong>over 600,000 unique visitors per month</strong> is quite challenging!<br /><br />I was an Auth0 customer before I became an employee, and I've always loved how much easier it is to implement authentication with Auth0. Curious to try it out? <a href='https://auth0.com/signup' data-amp-replace='CLIENT_ID' data-amp-addparams='anonId=CLIENT_ID(cid-scope-cookie-fallback-name)'><strong>Sign up for a free account</strong></a> ⚡️.

Staff Developer Advocate

Dan Arias

Learn about refresh tokens and how they help developers balance security and usability in their applications.

What Are Refresh Tokens and How to Use Them Securely

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

Brian Campbell joins the show to discuss sender constraint and associated specifications.



### The Overview

On the first episode of _Identity, Unlocked_, host Vittorio Bertocci, Principal Architect at [Auth0](http://www.auth0.com?utm_source=podcast&utm_medium=blog&utm_campaign=identity-unlocked), is joined by Brian Campbell. Brian joins the show to discuss the sender constraint and associated specifications. 
 
The mechanism described by OAuth2 for using the access token to access resources, as defined in the bearer token usage specification ([RFC6750](https://tools.ietf.org/html/rfc6750)), simply entails attaching a token to the request to the API. The approach is extremely simple to implement, but token leaks can have disastrous consequences: nothing stops an attacker from using a stolen bearer token to access a resource successfully. 

"Sender constraint" indicates a series of techniques that bind tokens to a particular sender, for example, by forcing the token to travel on a specific channel or requiring proof of knowledge of a given key. The goal is to guarantee that only the legitimate sender can successfully use a token to access resources, thus making it impossible for an attacker to access a resource using leaked tokens. 

There are two different specifications in the OAuth 2 family offering viable sender constraint capabilities today: OAuth 2.0 Mutual TLS Client Authentication and Certificate-Bound Access Tokens (MTLS, [RFC8705](https://tools.ietf.org/html/rfc8705)) and OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer ([DPoP](https://www.ietf.org/id/draft-ietf-oauth-dpop-01.html)). 

MTLS is robust and stable, but not easy to implement in various important scenarios. For a while, the identity community worked on an alternative, a set of specifications under the general token binding moniker (main one: [RFC8471](https://tools.ietf.org/html/rfc8471)); however, support from key industry players disappeared or never materialized, making token binding non-viable.

DPoP quickly emerged as an easy to implement an alternative that could fill that gap, and although it is still in draft state, it is already very popular and making quick progress.

Brian touches on all those specs during the episode, walking us through the trajectory that led us to today's situation and taking the time to dig deeper into the trade-offs, strengths, and attention points of the various approaches. The episode concludes with important practical considerations to keep in mind when planning an implementation strategy for the sender constraint in your solutions today.  

Read on for more in-depth information on this episode and make sure to subscribe and join us for the next episode, where [Aaron Parecki](https://twitter.com/aaronpk) (Senior Security Architect) talks about what's new with OAuth2.1.

### Highlights:

In the following, we highlight key passages of the interview. We added some background information here and there to make it easier to follow the conversation if you aren't already familiar with the topic.

**[4:45]** - What is sender constraint and what problem is it trying to solve?

<iframe width="100%" height="230px" scrolling="no" style="border: none" src="https://identityunlocked.auth0.com/public/49/Identity%2C-Unlocked.--bed7fada/4d4e8add?clip=9506a0f1&embed=true"></iframe> 

The figure below shows a typical OAuth 2 flow for calling an API- a good example to understand how bearer tokens are meant to work.

![Bearer](https://images.ctfassets.net/23aumh6u8s0i/3IJk6fHvBHJcUj5za8yAmt/78444158ad7ab009e2c2a1bddf66b027/1-bearer)

In the first leg of the diagram, a client requests an access token - this might be the redemption of an authorization code, of a refresh token, anything that leads to an access token being issued to the client as shown in step 2.
In this particular example, we are issuing tokens that are digitally signed by the `authorization` server via its private key (other token encodings are possible).

In step 3, the client calls the API by simply attaching the access token to the request (typically by placing it in the authorization HTTP header).

In step 4, the API validates the incoming access token (in this example, that includes validating the signature with the public key associated with the authorization server), and the call succeeds. 

The following diagram shows what happens when a bearer token is leaked.

![BearerAttack](https://images.ctfassets.net/23aumh6u8s0i/5TsCBLxiteQCHodPQYdMhp/3657fc2c592b822f960b90395be69cc0/2-bearerattack)

In step 1, an attacker steals an access token. For the purpose of highlighting the problem with bearer token leaks, it doesn't matter how the leak occurs (the token might be leaked from a cache, a referral header, an HTTPS tunnel termination, erroneously forwarded to a malicious address etc., etc.) as it doesn't change the consequences of the leak.
Once an attacker has the token, all they need to do to access the API successfully is to attach it to an API call - the API will perform the same validation we had observed in the former diagram when the call was originating the legitimate sender. 
This is the key limitation of bearer tokens: everything hinges on not making them fall into the wrong hands, as when that happens, there's no easy recourse.

**[11:35]** - What are the current standards with sender constraint?

<iframe width="100%" height="230px" scrolling="no" style="border: none" src="https://identityunlocked.auth0.com/public/49/Identity%2C-Unlocked.--bed7fada/4d4e8add?clip=1e5c3b2a&embed=true"></iframe>

The main specifications extending OAuth 2 with sender constraint capabilities are:

* MTLS ([RFC8705](https://tools.ietf.org/html/rfc8705))
* DPoP ([DPoP](https://www.ietf.org/id/draft-ietf-oauth-dpop-01.html))
* Token binding ([RFC8471](https://tools.ietf.org/html/rfc8471))

Token binding is mentioned out of exhaustiveness, but it isn't really a viable option as of today. 
For the other ones, we give more details later on in the interview.

**[11:51]** - Brian explains mutual TLS profile for OAuth 2.

<iframe width="100%" height="230px" scrolling="no" style="border: none" src="https://identityunlocked.auth0.com/public/49/Identity%2C-Unlocked.--bed7fada/4d4e8add?clip=d98141ee&embed=true"></iframe>

Here's a super quick primer to explain how MTLS works in OAuth 2. This leaves out lots of details, so if you are interested, you should consider taking a look at the spec itself ([RFC8705](https://tools.ietf.org/html/rfc8705)).
Please consider the diagram below.

![MTLS](https://images.ctfassets.net/23aumh6u8s0i/3nVuTSuMHCkIm7XS3pyxDw/5a97276eaa4f3a1a8e7f1c45d1a08274/3-mtls)

The client application has access to an X509 certificate, which it uses to perform client TLS authentication (hence proving possession of the corresponding private key) when requesting a token from the authorization server.
The authorization server issues a token containing (or referencing, if other token encoding methods are used) a claim cnf carrying the thumbprint of the X.509 certificate used to establish the channel. 
Important note: the access token is still meant to be signed by the authorization server, and the API is still meant to validate that signature, but we are omitting it in all diagrams from now on for simplicity. 

In step 2, the client establishes a channel with the API/resource server, again using its X509 certificate to establish client TLS. 

In step 3, the API validates the incoming token as usual, and additionally, it verifies that the certificate thumbprint corresponds to the certificate used to establish the TLS channel. If the two matches, the call is considered valid.  

![MTLSAttack](https://images.ctfassets.net/23aumh6u8s0i/479dKTr0VNwPDUT3i8Fwyl/e57676ac4b63edca06a5409ba42d6e3a/4-mtlsattack)

Consider now the case in which an attacker successfully steals a token. The attacker does not have access to the same certificate as the legitimate client; hence it cannot establish a client TLS channel with the API when attempting to use the stolen token - or it has to use a different certificate.
However, the API will easily spot that the certificate thumbprint carried by the cnf claim in the incoming access token does NOT correspond to the certificate used in client TLS authentication by the attacker; hence the API will deny access.

**[15:32]** - Brian explains DPoP. 

<iframe width="100%" height="230px" scrolling="no" style="border: none" src="https://identityunlocked.auth0.com/public/49/Identity%2C-Unlocked.--bed7fada/4d4e8add?clip=36aff654&embed=true"></iframe>

To help you follow the discussion, here’s a diagram exemplifying how DPoP works. 

![DPOP](https://images.ctfassets.net/23aumh6u8s0i/xrkq0ZMdUIwjiCeuZ6aXf/f333027993663e18e5f714e7d7d43d7f/5-dpop)

The idea is simple: the client uses some keys when requesting a token, those keys are referenced by the access token issued by the authorization server, and the client demonstrates knowledge of the same keys to the resource server when using that access token to call an API. Let's break that down in the steps shown in the diagram.

The client generates a private-public keys pair. It then creates a JWT, called DPoP proof, including in it a claim `jwk`carrying the public key from the pair, an `htu` claim indicating the intended destination of the call (in this case, something like [`https://server.example.com/token`](https://server.example.com/token)), a claim `htm` the HTTP method to be used in the call, and (not shown in the diagram) a `jti` claim (identifier) and an `iat` claim (issuance instant). It then proceeds to digitally sign the JWT with the private key from the generated pair.

In step 1, the client attaches the DPOP proof in a DPOP HTTP header to a token request to the authorization server.

In step 2, the authorization server uses the public key in the `jwk` claim from the DPoP proof to validate its signature, verifying that the sender does indeed have access to the corresponding private key. That done; it issues a new access token (once again, the token signature is omitted, but it is there, just like in the first diagram in this post) and embeds in it a `cnf` claim containing the public key received from the client.

In step 3, the client calls the API. Using the DPoP, the client creates a new DPoP proof, including the same `jwk` with the generated public key, a `htu` with the URL of desired API endpoint (for example, [`https://resource.example.org/protectedresource`](https://resource.example.org/protectedresource)) and `htm`, `jti`, and `iat` claims of the appropriate value. The client then attaches the DPoP proof and the access token to the request to the API.

In step 4, the client validates the incoming access token as it would do in a normal bearer case. In addition to that, it validates the DPoP signature with the `jwk` it carries, validates that the content of the DPoP proof accurately describes the targeted API and thatthe thumbprint of the key embedded in the `cnf` claim in the incoming access token corresponds to the `jwk` in the DPoP proof. If all that checks out, the API has proof that the caller is indeed entitled to use that token and allows the request to succeed.
The failure case here is very similar to the one shown in the MLTS diagram. An attacker stealing a token would not have access to the private key the legitimate client-generated at request time; hence it would not be able to manufacture the appropriate DPoP proof that would convince the API to accept the stolen access token. Bam. Sender constraint!

**[18:42]** - If DPOP blossoms like some anticipate, is there any reason to continue mutual TLS?

<iframe width="100%" height="230px" scrolling="no" style="border: none" src="https://identityunlocked.auth0.com/public/49/Identity%2C-Unlocked.--bed7fada/4d4e8add?clip=db16444d&embed=true"></iframe>

**[23:23]** - Brian’s opinion on how DPoP can be rolled out.

<iframe width="100%" height="230px" scrolling="no" style="border: none" src="https://identityunlocked.auth0.com/public/49/Identity%2C-Unlocked.--bed7fada/4d4e8add?clip=dcdf8d37&embed=true"></iframe>

### Links/Resources:

Learn more about [Brian Campbell](https://www.linkedin.com/in/bcampbell)<br />
Brian Campbell on [Twitter](https://twitter.com/__b_c)<br />

Vittorio Bertocci on [LinkedIn](https://www.linkedin.com/in/vittoriobertocci/)<br />
Vittorio Bertocci on [Twitter](https://twitter.com/vibronet)<br />

Learn more about [Identity, Unlocked](https://identityunlocked.auth0.com/public/49/Identity%2C-Unlocked.--bed7fada/episodes)<br />
Learn more about [Auth0](https://auth0.com/)<br />

<include src="asides/IdentityUnlocked" />

<include src="asides/AboutAuth0" />


Identity, Unlocked... Explained | Episode 1

5e074956ee8ba1fea26e30d28c190495?s=300 avatar

5e074956ee8ba1fea26e30d28c190495?s=300

Full stack developer creating content at Auth0. I love taking a deep dive into hard-to-understand concepts and creating content that makes them easier to grasp. In my free time you can usually find me reading, hanging out with my dogs, or curling in the squat rack.

Former Developer Content Manager

Holly Guevara

99c4080f412ccf46b9b564db7f482907?s=200 avatar

99c4080f412ccf46b9b564db7f482907?s=200

I'm currently a Senior Developer Advocate at MongoDB. I'm also a Google Developer Expert for Web Technologies and spend most my time giving talks at conferences and meetups, mentoring developers and running workshops, and creating online content to help technology professionals.

Former Auth0 Employee

Ado Kukic

Practice Go and React by building and authenticating a RESTful API with JSON Web Tokens (JWTs).

Authentication in Golang with JWTs

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 about the Hasura platform and how their GraphQL APIs can be secured using JSON Web Tokens



If you're developing an API today for consumption by third-parties, you'd be more than forgiven for choosing the [REST interface](https://www.smashingmagazine.com/2018/01/understanding-using-rest-api/) to develop the API, as it is a tried and tested standard for delivering data to consumers, as well as accepting changes to the data in a structured way. In more recent times, [GraphQL](https://graphql.org/) has become an attractive alternative for developing APIs thanks to its flexible, semantic, and performant nature.

But what if you'd like finer control over the details of the data exchange, including [integration with third-party authorization servers using JWTs](https://docs.hasura.io/1.0/graphql/manual/auth/jwt.html), and being able to quickly and easily set [role-based permissions at the field level](https://docs.hasura.io/1.0/graphql/manual/auth/basics.html#restrict-access-to-certain-columns)?

That's what Hasura have achieved with their [GraphQL platform](https://hasura.io/) that generates a GraphQL API over a [PostgreSQL](https://www.postgresql.org/) database. To highlight just a few of the features:

*   A PostgreSQL database schema can be designed and populated with data, using the built-in interface
*   The database can be queried using the GraphQL syntax, as well as the ability to view the GraphQL schema documentation from within the Hasura admin console
*   Roles can be assigned to individual tables and fields, as well as assigned different roles and permissions to individual operations such as selecting or inserting data
*   Authorization can be conducted using [JSON Web Tokens](https://jwt.io/), issued by a third-party authorization server such as [Auth0](https://auth0.com/)

<include src="TweetQuote" quoteText="The Hasura platform takes advantage of JWT and GraphQL technologies to provide a  platform for querying and manipulating data in a PostgreSQL database,  taking into account the role specified in the authorization token."/>

## <a class="toc-target" id="a-short-introduction-to-json-web-tokens"></a>A Short Introduction to JSON Web Tokens

From [jwt.io](https://jwt.io/introduction):

> _JSON Web Token (JWT) is an open standard ([RFC 7519](https://tools.ietf.org/html/rfc7519)) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the **HMAC** algorithm) or a public/private key pair using **RSA** or **ECDSA**._

What this looks like in practice is a string that is made up of three parts separated by a period:

* The first part defines the header, containing information such as the signing algorithm used
* The second part is the main body of the token and includes all the claims. This could be things like the user name, expiry date, issue date, and email address
* The last part is the signature, which is derived by cryptographically signing the header and the body together to ensure that the data has not been tampered with

A JWT is issued as a result of a user authenticating with an authorization server. In the case of the Hasura platform, this JWT can then be used to authorize the request and as such can make queries and mutations depending on the claims present in the token. We will see how this works in the demo a little bit later in the article.

The compact nature of a JWT makes it easy to pass around in query strings, headers, and request bodies, or [store in a cookie](https://auth0.com/docs/security/store-tokens#understanding-sessions-and-cookies).

## <a class="toc-target" id="what-is-graphql-an-overview"></a>What is GraphQL? An Overview

GraphQL is essentially a query language that allows you to define your API in terms of types. It is datastore-agnostic and has [server-side support for many different platforms and languages](https://graphql.org/code/#server-libraries). Instead of defining your API in terms of status codes and semantic URLs, you define the types and then construct queries using a familiar but powerful syntax. As an example:

```js
{
  article {
    id,
    title,
    author {
      name
    }
  }
}
```

This describes a query for articles, returning the id, title, and the author's name. As you can see, it supports nested database objects (the author is another table in the schema, linked to from an article). Mutations can also be defined, which describe how to change data.

In addition, _multiple queries_ can be made in a single request, which is most useful when a client wants to retrieve lots of possibly unrelated data points from the server.

## <a class="toc-target" id="the-hasura-approach"></a>The Hasura Approach

The Hasura platform takes advantage of these technologies to provide a platform for querying and manipulating data in a PostgreSQL database, taking into account the role specified in the authorization token.

The Hasura console allows the user to create a database, define its schema, and populate it with data. Hasura will then generate a GraphQL API on top of this database, automatically generating the appropriate types, queries, and mutations that allow the client to completely query for and manipulate the underlying data.

Hasura takes a role-based approach to authorization, and as such an individual role's access can be narrowed down to only a subset of the overall schema (even down to the field level). As each role is mapped to certain authorization rules, it can even be prevented from running certain mutations if so desired. Furthermore, queries can be delegated to an upstream service based on the claims present in the authorization token.

[Custom claims](https://auth0.com/docs/scopes/current/custom-claims) inside the JWT are used to tell Hasura about the role of the caller, so that Hasura may enforce the necessary authorization rules to decide what the caller can and cannot do.

![Hasura GraphQL engine authorization flow chart](https://images.ctfassets.net/23aumh6u8s0i/3hUYnCpHRwjnTU6LRLl2Oc/eaf8a50276dcb8fde4eb80adf451ced9/hasura-01_arch)

[[Source](https://docs.hasura.io/1.0/graphql/manual/auth/jwt.html)]

An example of the claims used by Hasura may look like the following:

```js
{
  "https://hasura.io/jwt/claims": {
    "x-hasura-default-role": "anonymous",
    "x-hasura-allowed-roles": [
      "user",
      "anonymous"
    ]
}
```

These two keys define the possible roles as well as the default role in the absence of the ["X-Hasura-Role" header](https://docs.hasura.io/1.0/graphql/manual/auth/basics.html#add-a-simple-access-control-rule-for-a-logged-in-user). In the case of Auth0, these custom claims can be put in place using [Rules](https://auth0.com/docs/rules), a platform feature that can be used to dynamically enhance tokens as users are authenticated.

## <a class="toc-target" id="demo-querying-data"></a>Demo: Querying Data

Let's have a look at how authorization with Hasura and JWTs works in practice. A demo has been set up that will allow you to construct queries and see the role-based permissions system in action.

This demo has been pre-configured with a database that has authors, articles, tags, and a relationship table that joins many articles to many tags. Let's see how we can query for some of this data.

### Executing anonymous queries

Browse to [https://auth0-hasura-demo.herokuapp.com](https://auth0-hasura-demo.herokuapp.com/console/api-explorer), and use "hasurademo" as the access key.

![Hasura console login screen deployed with Heroku](https://images.ctfassets.net/23aumh6u8s0i/4enFGmDUiStr0A9RQ5TfnI/aeee19ffd1dd1c727a1abbb938a6f22a/hasura-01_login)

Next, you will be presented with the Hasura console:

![The Hasura console and GraphQL explorer](https://images.ctfassets.net/23aumh6u8s0i/3LlFxGsCpDUBzi78yRV1V7/1df5659f6e04290a13609f7f43e4d071/hasura-01_console-1)

The interface gives you the opportunity to specify some request headers that will be used when querying the GraphQL interface. To demonstrate how the user's role affects their ability to query and modify data, remove the `X-Hasura-Access-Key` header by clicking on the cross on the right-hand side, and enter a new header `X-Hasura-Role` with a value of "anonymous":

![Setting the X-Hasura-Role header to anonymous in the Hasura console](https://images.ctfassets.net/23aumh6u8s0i/7gltFstbQEnUuMDX3sHmLS/644c0ff9f3ca7528c8571dd3c4d437ec/hasura-01_console-2)

Now, let's make a query. Use the following query inside the Graphiql query entry area in the lower half of the screen:

```
{
  article {
    id,
    title
  }
}
```

To run the query, press Ctrl+Enter (Cmd+Enter if you're on a Mac), or click on the large 'play' button above the query panel. You will see the results of the query on the right-hand side of the screen; you have successfully managed to retrieve the results for two articles that are currently in the database!

![Hasura GraphQL API query explorer - viewing query results](https://images.ctfassets.net/23aumh6u8s0i/5LQrzHTNJ4gGvYYp0B6z5B/1d0ffbcd5f01bc76d23ab04f28d64f3a/hasura-01_console-3)

Now let's try a mutation. Alter the query so that it executes the following mutation:

```
mutation {
  insert_tag(objects:[{name:"<YOUR TAG NAME HERE>"}]) {
    returning {
      name
    }
  }
}
```

This is a mutation that inserts a new tag with your specified tag name into the database. You should replace the value `<YOUR TAG NAME HERE>` with a value of your choosing.

Running this mutation right now will return an error, letting you know that the mutation does not exist.

![Showing a failed mutation error in the Hasura console](https://images.ctfassets.net/23aumh6u8s0i/3GysSZ0xtaGnlQevp0hLgF/3394f4a20b210e1271fb8615a0433a7e/hasura-01_console-4)

This is correct since the permissions have effectively been set up so that the anonymous role cannot make changes to the database. This is also indicated by the GraphQL API docs, as it does not show any mutations that can be called by this role. To see this, click the "< Docs" button on the right-hand side of the query window to open the API documentation.

![Viewing the GraphQL API documentation explorer in the Hasura console](https://images.ctfassets.net/23aumh6u8s0i/5DNNzhAp4eAUwjhLqMga9s/091a706d83350562be740ba9b54b1f71/hasura-01_console-5)

Only queries and subscriptions are available as root types here, but no mutations.

Let's have a closer look at how permissions are set within the Hasura interface.

### Validating query permissions

To view the permissions matrix for the "tag" table:

1.  Click the "data" tab at the top of the screen
2.  Click the "tag" table on the left-hand side
3.  Click the "permissions" tab in the main part of the interface

![Viewing the permissions and roles explorer in Hasura](https://images.ctfassets.net/23aumh6u8s0i/uO6od521er4QdJvxtLmC6/ee59f070bf583ea843cfa86b701643b2/hasura-01_console-6)

You will arrive at a matrix that describes all the role permissions for the "tag" table. On this screen we can see a number of things:

*   The "anonymous" role can select data (denoted by the tick icon in the "select" column), but it can't insert, update, or delete (indicated by the cross icon in the relevant columns)
*   The "user" and "admin" roles can do everything

You can see here that, since the "anonymous" user cannot modify or insert any data, it makes sense that there are no mutations available.

Let's now switch to the "user" role and see how we can make this mutation work.

## <a class="toc-target" id="executing-authorized-queries"></a>Executing Authorized Queries

Click the "Graphiql" heading at the top of the screen to return to the query interface. Now, change the "X-Hasura-Role" request header so that its value is "user".

If you try to run the mutation again now, you will notice that it will fail for the same reason as before. This is because the "user" role needs to also provide a valid JWT in order to be properly authorized to run this mutation.

<include src="TweetQuote" quoteText="Learn how to create a GraphQL API and secure it using JSON Web Tokens using the @HasuraHQ platform"/>

### Generating a valid JWT

For the purposes of this demo, a tool has been provided to make it easy for you to generate a JWT and run this mutation.

Browse to [https://auth0-hasura-demo.now.sh/](https://auth0-hasura-demo.now.sh/) and log in with your Auth0 account. If you do not currently have one, you can <a href="https://auth0.com/signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">register for a free account</a>.

> **Note:** In a real-world application, you would retrieve an access token directly from the authorization server when the user logs in, and use that in your requests to the GraphQL engine. This tool has been provided only as a convenience for the purposes of this demo.

![Generating a valid JWT for demonstration purposes](https://images.ctfassets.net/23aumh6u8s0i/6lI7QMcEz5nB3EbLGYsYii/112f674d24644fda68df1f7e471666ef/hasura-01_console-7)

Once logged in, you will be able to see your token. Select the entire token string and press Ctrl+C (or Cmd+C on a Mac) to copy it into your clipboard.

Before we head back to the Hasura console, let's inspect the token to see if it contains the claims that we inspect. Head to [http://jwt.io](http://jwt.io), scroll down and paste the token into the left-hand side of the screen. The right-hand side will automatically update to show you the data contained within the token, and you should be able to see that the correct Hasura claims have been included:

![Testing the JWT token at jwt.io](https://images.ctfassets.net/23aumh6u8s0i/3UghmdynnrceKJlxCu9XQ8/e066af2a85423a3f80312ab87b33dd1a/hasura-01_jwt-io)

With the token still in your clipboard, head back to the Hasura console. The way we attach this token to the request is through the standard "Authorization" request header.

Add a new header into the "headers" section, specifying the Authorization header and the JWT that you have in your clipboard as the bearer token:

![Adding the JWT to authorization request header in Hasura](https://images.ctfassets.net/23aumh6u8s0i/4wv6EC1ul56yPyI7icp2RQ/385c6bf02446601e5f1cb71dbbf12cf5/hasura-01_console-8)

Next, try running the mutation again. You should find that the query now works and that the name of the tag is being played back to you in the response:

![Authorized and successful run of previously failing mutation](https://images.ctfassets.net/23aumh6u8s0i/58rXtEu8Xe83VAv4dh8nqQ/574614e0324061ab0c7d3e6d1ace3f6f/hasura-01_console-9)

> **Note**: The "tag" database uses the tag name as its primary key. Since this demo is a cloud deployment that could potentially be used by many people, you should use your own made-up name for a tag as you cannot enter duplicate primary keys. If you have used a tag name that already exists, you will receive an error result in the query results window. Try running the mutation again with a different tag name.

Before we head away from this screen, let's expand the API docs again to show that the "mutations" root now appears and that you can browse through all the available mutations given that you are now authorized to do so:

![GraphQL API documentation explorer in Hasura showing mutations](https://images.ctfassets.net/23aumh6u8s0i/4lohzmsY0Hgy4MYWgNEuQ5/73012dbceb3010874feb695060db4738/hasura-01_console-10)

Finally, to prove that the mutation has worked we can explore the raw data in the database. Once again, click the "Data" heading at the top of the screen and then click on the "tags" table on the left.

![Raw data in Hasura after the mutation has been executed](https://images.ctfassets.net/23aumh6u8s0i/5ZVbWL8bJxXeASO1KsyRLs/85935085b9dec9ec08ff5ae29ae065c1/hasura-01_console-11)

The resulting screen will show you the data that is present in the table, and you can see that the "example-tag" entry that was created by the mutation is there.

## <a class="toc-target" id="wrapping-up"></a>Wrapping Up

In this post, you learned a bit about GraphQL and the main differences from a traditional REST API. You also had an introduction to JSON Web Tokens, how they are made up, and how easy they are to pass around.

Next, you discovered how Hasura tackles the idea of a role-based architecture when it comes to securing GraphQL APIs, and how it uses JWTs to authorize incoming requests and grant permissions to specific areas of the schema, even down to the field level.

Finally, you had a practical look at the Hasura platform, learning how to perform anonymous queries, and how to perform authorized mutations using a JWT that was issued to you by Auth0.

### Further reading

*   [Hasura.io](https://hasura.io/)
*   [Hasura GraphQL Engine Documentation](https://docs.hasura.io/1.0/graphql/manual/index.html)
*   [jwt.io](https://jwt.io)
*   [Introduction to GraphQL](https://graphql.github.io/learn/)

<include src="asides/AboutAuth0" />

## <a class="toc-target" id="about-hasura"></a>About Hasura

Based out of Bangalore and San Francisco, Hasura makes developer tools that simplify and accelerate product development.

The Hasura GraphQL engine is an open-source service that gives you instant, realtime, high-performance GraphQL for any Postgres app (including on existing databases).

Read more at [Hasura.io](https://hasura.io).


Using JWTs for GraphQL Authorization with Hasura

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

A practical tutorial showing how to use JSON Web Tokens in ASP.NET Core 2 applications.

Securing ASP.NET Core 2.0 Applications with JWTs

685342d5e7f42c3ab8d251d7d4a53308?s=100&d=mm&r=g avatar

685342d5e7f42c3ab8d251d7d4a53308?s=100&d=mm&r=g

Robin Percy

Continuing on from my Introduction to Crystal article, this time we're going to build our first Crystal web app and authenticate users via JSON Web Tokens.

Building Your First Crystal Web App & Authenticating with JWTs

4ff2f1955778896cc06318b342dabf55?size=200 avatar

4ff2f1955778896cc06318b342dabf55?size=200

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.


Why You Should Always Use Access Tokens to Secure an API

bc94ff6211e645a2bdb4fdc60e23ad85

Kassandra Perch

This is transcript and recording of a JSON Web Tokens 101 Webinar we ran a few weeks ago.


<include src="Vidyard" id="t5gytBAKhZPbiHHzhGYLw1" />

## Transcript

Good afternoon. This is Kassandra with Auth0. This webinar is about JWTs. So what I'm going to do is go over what JWTs are used for and then I'm actually going to write a small note application that generates JWTs and show you how they're used in the debugger so that you can write and debug your own JWTs. I have a questions panel open and I will check it from time to time. So if you have a question, feel free to put it in there. Let's get started. I'm going to start by sharing my screen and going over here. 

This rather dry looking document is the RFC for JSON web tokens. It hasn't been changed since 2015. However, I like to bring this up because it's actually one of the easier documents I've found to read. The reason I pull it up is to start talking about what a JWT is. A JWT is a series of JSON objects that are base 64 encoded and then signed with a key. So the reason you would use these, the two most common are used as authentication tokens because you can verify the sender using the key, which is usually signed with a secret, or passing data between two parties, knowing that the party that sent the data is who they say they are, again, because the key is signed with a secret. 

So when we talk about the JSON objects that make up a JWT we're going to start talking about claims. Claims is really just a fancy word for JSON key value pairs, but there are three types of claims, and I'm going to go over them. On my screen now is a list of what are called the reserved or registered claims. These are claims that are held by the JWT standard itself in order to make sure that JWTs can be globally used. These claims are three letters long. That is so you basically have a more compact JSON object. One of the reasons we use JWTs is because they're compact. Registered ones include issuer, expiration time, issued at, which we'll use in our application, and you'll definitely want to look up some of these because they are used on a regular basis, especially GTI, which is an ID or a globally used ID for that particular JSON web token. We'll check the questions. Nope, nothing yet. 

As for public claims, these are claims that are registered in this particular document, and they are again to make JWTs more global. It's just this way with public claims you don't have to modify the RFC every time you want to add a new global claim. As you can see, a lot of the public claims that are available are due to Open ID. Open ID Connect, which is the standard that gives identity to...it's an identity wrapper around the 0Auth authentication specification, is where a lot of our public claims come from, including things like name, email, picture, phone number, things that you would use in an Open ID Connect identity. 

So the last website I'm going to show you before we start working on our JWT generator is the JWT debugger. This is located at JWT.io, and you click on Debugger. What we've got here is, on this left side we've got our JSON web token or JWT. It puts the header in red, the body magenta, and the key in this light blue color. As you can see on the right, it's decoded the header and payload, and it's verifying the signature. Now, you can see the secret is changeable, and this is where the validity of your JSON web tokens comes into play. If I put a different secret than the one that it's expecting, it will say "Invalid signature." So we'll know that it was not sent with the correct secret. We'll talk a little bit more about secrets as we generate our JSON web tokens. No questions in the bin, so I'll keep going. 

What I'm going to start with is I have my terminal open and I'm going to run Node Mon, which is a process that will run my little node scripts. Every time I save it it will refresh it. What I've got in that node file right now is just a bunch of comments. Those are mostly so I don't forget anything. First, some basic house tidying. I'm going to bring in the colors module, which I'm going to use so that our console output is colored in a way that we can see what's going on, and the crypto-module. We're bringing this in for use with the key. When we sign the key we'll use that. I'm also going to set strict mode. It would help if I get...there we go. I'm going to go back to my terminal. Okay, cool. Nothing's gone wrong.

Like I said, the JSON web token consists of a header, a payload, and a key. What we're going to do is welcome the user to our little application here. The reason I used colors is, like I said, it makes it easier to see what's going on in the terminal. So now you can see this, "Welcome to our JWT generator." I'll make this a little bigger. So I've got our JWT generator. Now I'm going to say step one is creating our header. Checking it, and it works. 

So our header usually only consists of two registered claims. These claims are TYP, which stands for type, and it's JWT because it's a JSON web token, and ALG, which stands for algorithm. We're going to use HST56. Now, you can sign JSON web tokens symmetrically, which is what we're doing here. What you use is a secret. That's usually in the form of a string which is shared with the server and the client. However, you can also sign JWTs asymmetrically with a public and private key pair using RSA256. So keep that in mind if you're interested in an asymmetrical way to check that the party is valid. You can use a public/private key pair.

So now that we have our header, let's show our user what our header looks like. Actually, before I do that I'm going to say that our header is JSON.stringify. That's so our header is already in a string. Then I go over here, and as you can see, you can now see what our header looks like as a string. So in order to get our header from that to in the debugger, what we're going to do is base 64 encode it. In order to do that, what we're going to do is say the header is a new buffer with the contents of the original string header, and then call two string on it with base 64 as the argument. That will create our base 64 encoded string.

Then we're going to show our users what that base 64 encoded header looks like. Then we're going to tell the user the header is complete. I'm going to make my header that's encoded red to make it a little easier to see. So when I go over to my terminal you can now see again that same JSON object, and then you can see it base 64 encoded. So our header is complete. Now I'm going to set up our JSON payload.

First I'm going to tell the user that that is step two. Then I'm going to actually create my payload object. Now, I'm going to use a few different claims to go over, again, the difference between registered claims, public claims, and private claims. So I went over registered and public, but I didn't go over private. Private is any claim that you wish to use yourself that's not preregistered either with the specification or with the database. I'm going to check the questions. I just realized it's been a bit. Okay, cool. 

I'm going to use one of each in this payload. First I'm going to use IAT, which is a registered claim. That stands for issued at. So I'm going to use date.now. That will be our issued at time. I'm going to use the public claim of name because, like I showed you over here, in our public claim database, you can see name, full name, and that's registered by the Open ID Connect. So it's actually my full given name. So I'm going to put that there instead. Then finally a private claim. I'm just going to call it My Claim. Again, this is any claim that is not registered either with the specification or the public database. I'm just going to call that True. 

So now I'm going to show the user what my payload looks like. I almost forgot, JSON.stringify. Then payload.green. Let's check the output. As you can see, I've got my time stamp for IAT and then my name, and the private claim My Claim. So now just like before I'm going to base 64 encode this. I'm going to say Payload = New Buffer with the original payload.twostring with the argument base 64. Then I'm going to show this to the user.

Now you can see our payload right there. So now that we have our header and our payload, it's time to construct the key. Now, there are two steps to constructing the key, assembly and then signing it. I'm going to tell the users that the payload is complete. Now I'm going to assemble the key. The key is the header concatenated with the period concatenated with the payload all base 64 encoded. So I'm going to say, "Let key equal header plus a period plus the payload." Then I'm going to show this to the user. Also, notice that step 3A is assembling the key. 

Our key looks like this. Now when I look at the terminal, as you can see I've got my key here and it looks like the header and then a dot and then the payload, just like I said. Now that we've assembled our key, it's time to sign it. This is where the secret comes in. I'm going to tell the user that step 3B is signing the key. So I'm going to create a secret. My secret is going to be a string. Remember, you can use a string with the HST56 or you can use a public/private key pair. However, public/private key pair isn't regularly used. So that's why we're using symmetric today. 

So we've got our secret and we're going to say our secret is 'nyancat'. I'm going to tell our user the secret is...it would help if I put Secret instead of 'nyancat', because otherwise there would be a bit of a problem. So we've got our secret, and I go here, and you can see our secret is 'nyancat'. Now we've got our secret and our unsigned key. We're going to sign our key. This is why we required it in the crypto-library earlier. Notice my Const HMAC is a crypto.create HMAC. I want to use the SHA256 encryption and I'm going to pass out my secret. Then I'm going to update the HMAC with my key. Then finally I'm going to say, "Key = HMAC.digest base 64." So it's base 64 encoded after signing, just like everything else. I'll make sure I did all that right. I did. 

So now we can show the user . . . Key.red. So you can see our key here. All right. Now that we have the key and it's signed, the last step is putting it all together. I'm going to tell the user, and the key is complete.

To put it all together, it will look remarkably like when we put together the key. A finished JWT is the header concatenated with a period, concatenated with the payload, concatenated with a period, concatenated with a signed key. So now I'm going to show the user. 

So when I go over here, as you can see, our JWT is here. Now, I mentioned the debugger earlier and I'm going to show it to you again. First I'm going to check the questions bin. Okay, I don't see anything. Now that we have our finished JWT I'm going to show you how the debugger works with our JWT as opposed to the pre-populated one. So when we go back to JWT.io I'm going to paste our brand new key in there. Just like before I highlighted the header, payload, and the key for us. Now you'll note when I leave it alone and it says Secret, this is an invalid signature. However, everything else is there. That's because we didn't encrypt any of the header or the payload. We just base 64 encoded it. So getting all of that data back out was just base 64 unencoding it, but this invalid signature means we don't have the same secret as our server. So we can't trust that it came from the right source. 

So what I'm going to do is type the secret that we used in our application, 'nyancat', and as you can see the signature is now verified. That's where the security of JWTs comes in. If that signature isn't verified, you cannot trust that the JWT came from the source that it claims to be coming from. Otherwise they would have either that shared secret or a public/private key match.

I'm Kassandra with Auth0, and that's our webinar on JWTs. Thanks for listening!


JWT 101 Webinar Video-- learn more about JSON Web Tokens

d5365965372e0c5843d836f660b51a84?size=200 avatar

d5365965372e0c5843d836f660b51a84?size=200

Jeff Smith

Using JWTs to authenticate your React Native app will help it to be both secure and easy to integrate with a variety of services.

Adding Authentication to Your React Native App Using JSON Web Tokens

6c0654e56c8c73ffee8f76fe03d18ccf?s=80 avatar

6c0654e56c8c73ffee8f76fe03d18ccf?s=80

Guest Author

Alex Sears

JSON Web Tokens (JWT) provide an easy way to add authentication to Ruby apps. Learn all about how to secure your Rack API!



Early on in my career, when I was a wee little junior dev, learning Ruby on Rails and looking to impress, I came across an issue that is all too common these days. How do I authenticate a request with an API when the consuming client is a browser? This is a problem that will need to be solved if you are building a single page application.  At the time, I thought a single numeric "API token" that was returned to the user when they logged in was enough. Looking back, I realize how dumb of a move this was. It's extremely insecure!

Recently, I have been reading that [JSON Web Tokens](https://auth0.com/learn/json-web-tokens/) (also written as JWTs and pronounced "jots") are the way to go when authenticating with an API. If you haven't heard of JWTs, check out [the website](https://jwt.io/) and [read this blog post on using them with APIs](https://auth0.com/blog/2014/12/02/using-json-web-tokens-as-api-keys/). They make authenticating a user securely very easy.

Today, we are going to explore using JWTs in a Ruby environment, specifically with Rack apps. This includes Rails and Sinatra applications. Let's get to it! Create a new directory for this project and move into it.

```
mkdir ruby-jwt-api
cd ruby-jwt-api
```

First, let's setup the basic API itself. Create a `Gemfile` with the following in it.

```
source "https://rubygems.org"

gem 'sinatra'
gem 'jwt'
gem 'json'
```

Then, run `bundle`. If you don't already have bundler installed, run `gem install bundler`. This will install the dependencies we need. Next we need to create our `config.ru` file to run our Sinatra application.  Put the following in a file called `config.ru`.

```
require File.expand_path '../main.rb', __FILE__

run Rack::URLMap.new({
  '/' => Public,
  '/api' => Api
})
```

Here we are loading a file called `main.rb` and then setting up a new Rack application and running it. We create the application this way so we can put our JWT protection on only the API routes and not the public routes. We are loading the file, but we haven't created it yet! Let's do that. Create a file called `main.rb` and put the following in it.

```
require 'json'
require 'jwt'
require 'sinatra/base'

class Api < Sinatra::Base

  def initialize
    super

    @accounts = {
      tomdelonge: 10000,
      markhoppus: 50000,
      travisbarker: 1000000000
    }
  end

  get '/money' do
    content_type :json
    { message: "Hello, World!" }.to_json
  end
end

class Public < Sinatra::Base

  def initialize
    super

    @logins = {
      tomdelonge: 'allthesmallthings',
      markhoppus: 'therockshow',
      travisbarker: 'whatsmyageagain'
    }
  end

  post '/login' do
    username = params[:username]
    password = params[:password]

    if @logins[username.to_sym] == password
      content_type :json
      { message: "You logged in. Yay you!" }.to_json
    else
      halt 401
    end
  end

end
```

This code sets up our two application routes. The only public route we have right now is `/login`. It authenticates a user based on a username and password. Currently, it just returns a confirmation message. This is where we will eventually return a JWT the user can use to authenticate with the API. The API only has one route for now also called `/money`. It returns a simple message now too. Notice, we have hardcoded the values for our users. Normally this would come from a database of some sort.

Run `rackup` on the command line to start the server. Here are what our responses look like if we hit each of these endpoints. We hit the login route and get a success...

![First successful hit to the server endpoint](https://images.ctfassets.net/23aumh6u8s0i/37oTdL3zyegFb024TeBDxY/9104f52d64e6fdf6f46e1a05f75a075e/first_successful_hit)

...hit the login route and get an error...

![First unsuccessful hit to the server endpoint](https://images.ctfassets.net/23aumh6u8s0i/7E72SbsOBfnwiv74PxQNWo/74cc17454812ac79cfbb64ee310dea60/first_unsuccessful_hit)

...and hit the `/api/money` route to make sure our routing works correctly.

![First Successful API Hit](https://images.ctfassets.net/23aumh6u8s0i/5mSTx6nuOTca2kOHhVY1EF/a0f1d9f115419ea560f24dadc16d322b/first_successful_api_hit)

Now that we know our endpoints are working, let's add authentication and authorization using JWTs. We need to make sure that when we log our user in, we return a JWT so the user can use it to authenticate in the future.

```
post '/login' do
  username = params[:username]
  password = params[:password]

  if @logins[username.to_sym] == password
    content_type :json
    { token: token(username) }.to_json
  else
    halt 401
  end
end

def token username
  JWT.encode payload(username), ENV['JWT_SECRET'], 'HS256'
end

def payload username
  {
    exp: Time.now.to_i + 60 * 60,
    iat: Time.now.to_i,
    iss: ENV['JWT_ISSUER'],
    scopes: ['add_money', 'remove_money', 'view_money'],
    user: {
      username: username
    }
  }
end
```

Let's analyze this. We have changed what happens on a successful login. We set the content type to JSON and then return a Hash that has the token in it.

The token is generated by calling the `token` method and passing it the username. `token` uses [the jwt gem](https://github.com/jwt/ruby-jwt) to create an encoded JWT. It takes the payload, the secret, and the algorithm we want to use to sign the token. Our `token` method calls another method we created called `payload` which simply returns a Hash that contains all the data we want in our token payload.

Some things to note about the payload. It has an expiration date, which will be verified later. We also give it an issuer that we can verify later, a set of scopes that this token allows a user to do, and some data about our user. A sample response would look like this.

Restart your server. Make sure to pass the environment variables to it when you run it like so.

```
JWT_SECRET=someawesomesecret JWT_ISSUER=moneyapi.com rackup
```

![Retrieving a Successful JSON Web Token](https://images.ctfassets.net/23aumh6u8s0i/53TJSyy6aNrVQ0HE46bSZI/14262f5c738be70af3d1b76438bdd223/successful_token)

We have our first token! Yay! Notice how I have passed two environment variables on the command line. It's a good practice to pass these sorts of values in environment variables to avoid hardcoding them in our source code. These variables are used when creating (and later validating) our tokens.

Now we need to create a piece of middleware that will validate our token and then add the scopes and user data from the token to the request environment. This will allow us to access this information in our API routes. Add the following to our `main.rb` file.

```
class JwtAuth

  def initialize app
    @app = app
  end

  def call env
    begin
      options = { algorithm: 'HS256', iss: ENV['JWT_ISSUER'] }
      bearer = env.fetch('HTTP_AUTHORIZATION', '').slice(7..-1)
      payload, header = JWT.decode bearer, ENV['JWT_SECRET'], true, options

      env[:scopes] = payload['scopes']
      env[:user] = payload['user']

      @app.call env
    rescue JWT::DecodeError
      [401, { 'Content-Type' => 'text/plain' }, ['A token must be passed.']]
    rescue JWT::ExpiredSignature
      [403, { 'Content-Type' => 'text/plain' }, ['The token has expired.']]
    rescue JWT::InvalidIssuerError
      [403, { 'Content-Type' => 'text/plain' }, ['The token does not have a valid issuer.']]
    rescue JWT::InvalidIatError
      [403, { 'Content-Type' => 'text/plain' }, ['The token does not have a valid "issued at" time.']]
    end
  end

end
```

This is a simple Rack middleware setup. In the `call` method, we get the `HTTP_AUTHORIZATION` value out of the environment hash, which represents the `Authorization` header in the request.  We use `fetch` so we get a string if `HTTP_AUTHORIZATION` doesn't exist and then use `slice` to prevent throwing an error if the string indexes we want don't exist. This will strip off the "Bearer: " part of the `Authorization` header. We then decode the JWT and add the scopes and user data to the environment hash. Lastly, we call the next part in our middleware stack and pass it our modified environment.

We have wrapped this code in a `begin, rescue`. This is because the `jwt` gem will throw different exceptions for each thing that may be wrong with it, such as the validation not passing. We catch each one and return a good error message for it.

Now that we have the data available on our request environment, let's use it in our API route.

```
class Api < Sinatra::Base

  use JwtAuth

  def initialize
    super

    @accounts = {
      tomdelonge: 10000,
      markhoppus: 50000,
      travisbarker: 1000000000
    }
  end

  get '/money' do
    scopes, user = request.env.values_at :scopes, :user
    username = user['username'].to_sym

    if scopes.include?('view_money') && @accounts.has_key?(username)
      content_type :json
      { money: @accounts[username] }.to_json
    else
      halt 403
    end
  end

end
```

Here, we initialize the class with some data, like we did with the `Public` class. Notice we `use JwtAuth` in this class. This is our way of including our token authentication middleware. This causes it to be run before the routes on this class are run. We then setup a `/money` route. This route grabs the scopes and user out of the environment. It then gets the username out of the user data. It checks to make sure this token has the `view_money` scope and that the username is a valid one in the data we have. If all this checks out, it returns the amount of money in the account. That's all there is to it.

![Hiting the Get Money route](https://images.ctfassets.net/23aumh6u8s0i/2hmmyaWekQu2TTSqsagON2/0ca839945394450177cb232ffa92bb9b/get_money)

We can use this same setup to add and remove money from these accounts.

```
post '/money' do
  scopes, user = request.env.values_at :scopes, :user
  username = user['username'].to_sym

  if scopes.include?('add_money') && @accounts.has_key?(username)
    amount = request[:amount]
    @accounts[username] += amount.to_i

    content_type :json
    { money: @accounts[username] }.to_json
  else
    halt 403
  end
end

delete '/money' do
  scopes, user = request.env.values_at :scopes, :user
  username = user['username'].to_sym

  if scopes.include?('remove_money') && @accounts.has_key?(username)
    amount = request[:amount]

    @accounts[username] -= amount.to_i
    if @accounts[username] < 0
      @accounts[username] = 0
    end

    content_type :json
    { money: @accounts[username] }.to_json
  else
    halt 403
  end
end
```

Here we are doing similar work as the previous route except we are sending `POST` and `DELETE` requests to add and remove money.  Our output would look like this when adding money...

![Adding Money using the API endpoint](https://images.ctfassets.net/23aumh6u8s0i/6cREs0pHtL5ghb0aT9QHMc/5c45ddd136e86614f197c0427bc3f501/add_money)

...and when removing money.

![Deleting Money using the API endpoint](https://images.ctfassets.net/23aumh6u8s0i/4AGDt3bC0dQJGI3PyRpD5F/94877eba401879712cac3e1765c5d579/delete_money)

As you can see, we can now use JWTs to add and remove money also. You may have noticed that we have some duplicated code here though. That's not good when we can prevent it! Luckily, we can. We can refactor our code like so.

```
get '/money' do
  process_request request, 'view_money' do |req, username|
    content_type :json
    { money: @accounts[username] }.to_json
  end
end

post '/money' do
  process_request request, 'add_money' do |req, username|
    amount = req[:amount]
    @accounts[username] += amount.to_i

    content_type :json
    { money: @accounts[username] }.to_json
  end
end

delete '/money' do
  process_request request, 'remove_money' do |req, username|
    amount = request[:amount]

    @accounts[username] -= amount.to_i
    if @accounts[username] < 0
      @accounts[username] = 0
    end

    content_type :json
    { money: @accounts[username] }.to_json
  end
end

def process_request req, scope
  scopes, user = req.env.values_at :scopes, :user
  username = user['username'].to_sym

  if scopes.include?(scope) && @accounts.has_key?(username)
    yield req, username
  else
    halt 403
  end
end
```

We have extracted the common code out into its own method and pass in the functionality for each route into the `process_request` method as a block.

That's all there is to it. We can now use our `JwtAuth` middleware anywhere we want to protect routes with JSON web tokens.

![Drop the mic](https://images.ctfassets.net/23aumh6u8s0i/71PTFQvHyCb4tSTO4bUwr8/611c9310a6b1713a01992f3eb6a2a142/giphy)

## What about Auth0?

[Auth0](https://auth0.com/) handles all this business of authenticating your users and creating JWTs so you can concentrate on building your application. There's even [a gem](https://github.com/auth0/ruby-auth0) that makes interacting with the Auth0 API so much easier. Let them handle the boring authentication while you build the next MyFaceTwiSterGram.

Wanna integrate Auth0 with RoR? Simple. The excellent writers over at Auth0 have you covered. They have written [extensive documentation](https://auth0.com/docs/quickstart/webapp/rails/) on how to do just that. It goes a little something like this.

### Add Omniauth and Auth0's strategy

Add the following to your `Gemfile` and run `bundle install`.

```
gem 'omniauth', '~> 1.3'
gem 'omniauth-auth0', '~> 1.4'
```

### Initialize Omniauth

Put the following in a file at `config/initializers/auth0.rb`, replacing the ALL_CAPS values with their actual values received when creating an application on the Auth0 dashboard.

```
Rails.application.config.middleware.use OmniAuth::Builder do
  provider(
    :auth0,
    'YOUR_CLIENT_ID',
    'YOUR_CLIENT_SECRET',
    'YOUR_NAMESPACE',
    callback_path: "/auth/auth0/callback"
  )
end
```

### Add the callback handler for Auth0

Use this command to create a controller to handle the Auth0 callback.

```
rails generate controller auth0 callback failure --skip-template-engine --skip-assets
```

In this newly-created file, add the logic to handle the success and failure of the callback.

```
class Auth0Controller < ApplicationController
  def callback
    # This stores all the user information that came from Auth0
    # and the IdP
    session[:userinfo] = request.env['omniauth.auth']

    # Redirect to the URL you want after successfull auth
    redirect_to '/dashboard'
  end

  def failure
    # show a failure page or redirect to an error page
    @error_msg = request.params['message']
  end
end
```

Also, replace the routes we created earlier with the following ones instead.

```
get "/auth/auth0/callback" => "auth0#callback"
get "/auth/failure" => "auth0#failure"
```

### Add the callback to Auth0's dashboard

You need to make sure you add the callback URL to the [Application Settings](https://manage.auth0.com/#/applications) in the Auth0 dashboard area.

For example, the callbacks we have created will be reached at `http://yourUrl/auth/auth0/callback`.

### Pick a method of triggering the login

There are multiple ways you can trigger the login flow in your application. For example, you could use the Auth0 Lock widget, Passwordless, or some custom UI. Here is what the code would look like to use the Lock widget in modal form.

```html
  <script src=“https://cdn.auth0.com/js/lock/10.0/lock.min.js"></script>
  <script type="text/javascript">

    var lock = new Auth0Lock('YOUR_CLIENT_ID', 'YOUR_NAMESPACE');


    function signin() {
      lock.show({
        callbackURL: '',
        responseType: 'code',
        authParams: {
          scope: 'openid email'  // Learn about scopes: https://auth0.com/docs/scopes
        }
      });
    }
  </script>
  <button onclick="window.signin();">Login</button>
```

### Accessing User Info

Once all this is setup, you can access user information like you normally would when using the Omniauth gem and its provider gems.

```ruby
class DashboardController < SecuredController
  def show
    @user = session[:userinfo]
  end
end
```

```html
  <div>
    <img class="avatar" src="<%= @user[:info][:image] %/>"/>
    <h2>Welcome <%= @user[:info][:name] %></h2>
  </div>
```

This is only a portion of the information you can get from their docs. [Head over there](https://auth0.com/docs/quickstart/webapp/rails) to get more information on integrating with Rails.

## Authentication is hard

Authentication in a web application can be difficult. However, whether you use Auth0 or roll your own solution, the `jwt` ruby gem offers a simple way to use JWTs in your ruby application. This allows stateless authentication that can be used in a traditional application or a decentralized API.

<include src="TweetQuote" quoteText="Authentication in a web application can be difficult. However, Auth0 simplifies it with JWTs."/>


Ruby Authentication: Secure Your Rack Application with JWT

Secure your internet-connected NodeBots projects with JSON Web Tokens.

# Securing your NodeBots with JSON Web Tokens

NodeBots are amazing! One of the best things about them is that you can connect them to the internet in new and amazing ways. This can include controlling NodeBots via your own Node.JS API!

However, this can lead to some interesting scenarios regarding security-- especially if you choose to control a system like a door lock via NodeBots. Without a cloud service like Particle's Cloud or Electric Imp's agent/client system, security can be tricky! Even with third-party cloud solutions providing basic security, this security mainly covers your API's communication with your NodeBot-- not the internet's communication with your API!

Luckily for us, NodeBots means Node, and Node has several easy-to-use security systems. One way is to use JSON Web Tokens as a bolstered authentication system for your NodeBots server.

## What are NodeBots?

Just in case you've never heard of them, NodeBots refers to any project that runs hardware with Node.JS or javascript in some form or another. One of the most popular frameworks for this is [johnny-five](http://johnny-five.io). An example of a NodeBot is this Rose Pin, which allows people to change the color of the lights inside the rose via a web interface:

![The NodeBots Rose Pin](https://images.ctfassets.net/23aumh6u8s0i/3l1EppfHNEPrnft7fbzSfL/d6ced699d8f901c9d739fe3b9ce9aa07/nodebots)

## JSON Web Tokens

If you've never used JSON Web Tokens, there is some great introductory material [at jwt.io](https://auth0.com/learn/json-web-tokens/).

When using your own Node server for robotics control and code, JSON Web Tokens can provide an extra level of security-- especially when you're stuck on HTTP. JSON Web Tokens use a payload, encryption, and either a secret or private/public key pair in order to provide a signed token that allows you to verify that your NodeBots APIs are only being used by you (or other NodeBots and users that you approve)!

<include src="TweetQuote" quoteText="When using your own Node server for robotics control, JSON Web Tokens can provide an extra level of security"/>

In order to use JSON Web Tokens with NodeBots, you'll want to look into [jsonwebtoken](https://www.npmjs.com/package/jsonwebtoken). This library allows you to create JSON Web Tokens:

```javascript
var jwt = require('jsonwebtoken');
var myToken = jwt.sign({ user: 'username' }, 'my secret');
```

the `.sign()` method takes a payload (which is a javascript object that will be converted to JSON), and a secret-- JWT, unlike other token types, allows for not only the use of secrets, but the use of public/private key pairs:

```javascript
var cert = fs.readFileSync('private.key');  // get private key
var token = jwt.sign({ sensorData: 1024 }, cert, { algorithm: 'RS256'});
```

Once you have your token, it's safe to pass as an authentication header:

```
Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoidGVzdCIsImlhdCI6MTQ0NjUyNDM5NH0.NDlWo8qunNFJvU9GGTeniAfUxwV0z38LhgkN57m-hvI
```

Want to learn even more about JWT tokens before getting started? Check out Auth0's [extensive documentation on the subject at JWT.io](http://jwt.io). You can also read about the different ways to sign JWT's in [this blog post.](https://auth0.com/blog/2015/12/17/json-web-token-signing-algorithms-overview/)

## Using JWT for request authentication

But how do we check for a valid token on our API requests? You can check headers manually using your own methods, but a very easy way is to use [express-jwt](https://www.npmjs.com/package/express-jwt), an npm module and express middleware. All you have to do is set up this middleware:

```javascript
var express = require('express');
var jwt = require('express-jwt');

var app = express();

app.use(jwt({ secret: 'my secret'});

app.get('/protected', function(req, res){
	res.send('This route requires a JWT to be reached-- this message means you are authenticated!');
});
```

Now all of your requests to this API will require the authentication header to contain a valid JWT token signed with your secret in order to complete-- otherwise they will return with a 401.

## When is this useful for NodeBots?

This technique is mainly useful for Johnny-Five, and other NodeBots projects, that are accessible via the internet. This can include thin clients (e.g. [Particle Photons](http://particle.io) using the [Javascript SDK](https://www.npmjs.com/package/spark)), or [Johnny-Five](http://johnny-five.io) bots that have been made available via local wireless.

This is also useful in situations where you use an external client (be it a client-side app, a different API server, or even a third-party service) to work with your NodeBot. For instance, if you have a GET route that moves a servo, and you don't want someone hacking together a script in a few minutes that takes over movement using that GET request, you can use JWT to lock down that route so only scripts that you've written, containing tokens signed with your secret, can move that servo.

## Aside: User Management with Auth0

If you want to provide a user login for your NodeBots project, you can use Auth0 to manage your users and easily create a login dialog! Check out [Lock](https://auth0.com/lock) for more information. You can implement Lock easily on your front-end and your Node.JS server [with just a few lines of javascript](https://auth0.com/docs/quickstart/spa/vanillajs/nodejs).

For instance, in your web interface's index.html, add

```html
  

  ...

  
  <script src="//cdn.auth0.com/js/lock-7.11.1.min.js"></script>

  ...
```

To call in the Auth0 Lock script. Then, add a login button:

```html
	

	...

	
	<input id="btn-login" class="btn-login" type="submit" />

	...
```

To wrap-up the front-end, add a call to Lock from the login button:

```javascript
document.getElementById('btn-login').addEventListener('click', function() {
  lock.show(function(err, profile, token) {
    if (err) {
      // Error callback
      console.error("Something went wrong: ", err);
      alert("Something went wrong, check the Console errors");
    } else {
      // Success calback  

      // Save the JWT token.
      localStorage.setItem('userToken', token);

      // Save the profile
      userProfile = profile;

      document.getElementById('nick').textContent = profile.nickname;
    }
  });
});
```

Then, on your server, we're going to modify our use of express-jwt to work with the JWTs that Auth0 creates to authenticate users:

```javascript
var express = require('express');
var app = express();
var jwt = require('express-jwt');

var jwtCheck = jwt({
  secret: new Buffer('YOUR_CLIENT_SECRET', 'base64'),
  audience: 'YOUR_CLIENT_ID'
});
```

**Important API Security Note:** If you want to use Auth0 authentication to authorize _API requests_, note that you'll need to use [a different flow depending on your use case](https://auth0.com/docs/api-auth/which-oauth-flow-to-use). Auth0 `idToken` should only be used on the client-side. [Access tokens should be used to authorize APIs](https://auth0.com/blog/why-should-use-accesstokens-to-secure-an-api/). You can read more about [making API calls with Auth0 here](https://auth0.com/docs/apis).

This way, you can easily allow users to log into your NodeBots interface, with just a few lines of JavaScript!

## Other tips

Some things to keep in mind when using this method to protect your robotics APIs:

* **You can revoke access in multiple ways, quickly:** the `jsonwebtoken` API gives you ways to revoke specific tokens, but you can quickly invalidate all tokens by changing your secret.
* **You can provide a login, but you don't have to!:** as long as you can use the API to generate tokens using your secret, you don't need to provide a login interface to the rest of the world.
* **Be sure to set expirations on your tokens:** security is a "better safe than sorry" topic, so be sure to set a lifetime on your tokens to prevent an old token coming back to haunt you!

Hopefully now you're on your way to taking the first steps to secure communications with your NodeBots APIs! I'd really like to see what you build-- let me know [on Twitter](https://twitter.com/nodebotanist).

<include src="asides/Jwt" />

Securing your NodeBots with JSON Web Tokens

ryan-chenkie

Ryan is a full-stack JavaScript developer and trainer who mainly works with React, Angular, Node, and GraphQL. He runs a consultancy where he builds apps for companies and also helps established dev teams with their modern JavaScript challenges.<br /><br />Ryan is a Google Developer Expert, the host of the Entrepreneurial Coder Podcast, the author of Securing Angular Applications, and an all-around fanatic about application security.

Developer

Ryan Chenkie

Conventional authentication is challenging for today's web applications. Learn about the reasons and how to use JSON Web Tokens (JWT) for modern authentication.



---

**TL;DR:** Traditional session-based authentication with cookies presents difficulties, especially for modern web applications. We can instead use JSON Web Tokens (JWT), which make our apps stateless. Migrating a legacy app over to JWT authentication can be done piece by piece, and if we need to, we can use cookies to handle JWTs. To see how this is done, take a look at the [repo](https://github.com/auth0/cookie-jwt-auth) for this tutorial.

---
Authentication for web applications has historically been fairly straightforward and followed a common pattern, but this has been changing significantly in recent years. There are several reasons for these changes, and the prominent ones are related to the way in which modern applications are built and distributed.  In this article, we'll see how things have changed and also some ways we can adapt legacy applications to modern day practices.

## Traditional Web Applications

In a general sense, traditional websites and applications typically implement user authentication using **sessions** and **cookies**. When users log in to a site, their username and password are matched against database entries. If the login is successful, the server saves the user's authentication state in memory and sends a cookie back in the response that contains some data, which in most cases includes the user's ID. Browsers will save the cookie for the domain from which it came and then automatically send it back when subsequent requests are made. For example, if a cookie is saved with a domain of auth0.com, it will be sent back on any future request to auth0.com as long as it is valid. This works great for traditional web apps.

![modern authentication jwt](https://images.ctfassets.net/23aumh6u8s0i/2E0gj0N91SqR18iJcYX0pS/2843825e62cc48a85c287ffad235efc9/legacy-app-auth-1)

Even though we've labeled the process described above as being "traditional", it should be noted that *most* of the web still operates this way. While this approach is still perfectly valid for a lot of use cases, we're going to explore some of the reasons why relying on it has become challenging for modern web applications.

## Authentication Challenges for Modern Web Apps

Modern web applications present a few challenges for authentication that are difficult to solve using conventional methods. The reasons for this have to do with how applications are crafted and the environment in which applications reside.

### 1. Apps are distributed across many servers

Many of today's applications aren't deployed the same way they were in the past. It is now very common--and often necessary--for apps to be distributed across many servers so that up-time is increased and latency issues are mitigated. With this comes the side effect that, when a user accesses an application, it is no longer guaranteed that they are always accessing the same server.

Since traditional authentication relies on the server to keep the user's authentication state in memory, things break down when the app is accessed from different servers. The user might be logged in on one server but not on the others that the application is distributed across.

We can get around this by using methods like [**sticky sessions**](http://stackoverflow.com/questions/10494431/sticky-and-non-sticky-sessions). A sticky session will essentially route the user to the server instance from which they logged in so that the authentication state can be presevered. This type of workaround will do the job, but as we'll see, stateful servers in general don't play that well with modern applications.

### 2. Apps use APIs for data

A common pattern for modern applications, especially single-page apps, is to retrieve and consume JSON data from a [RESTful API](http://www.restapitutorial.com/). Serving data from an API has several distinct advantages, one of them being the ability for data to be used in more than just one application. For example, an organization might start with the intent to build an internally facing application, but may soon realize that some of its functionality could be used in a public-facing app. Down the road, the organization might also decide that some of its data should be accessible by other application developers to build third-party apps with. This can all be made possible with an API.

Using APIs in this fashion is great, but things can become challenging when it comes to authentication. The traditional approach of using sessions and cookies for the user's identity doesn't work so well in these cases because their use introduces **state** to the application. One of the tenets of a RESTful API is that it should be **stateless**, meaning that, when a request is made, a response within certain parameters can always be anticipated without side effects. A user's authentication state introduces such a side effect, which breaks this principle. Keeping the API stateless and therefore without side effect means that maintainability and debugging are made much easier.

<include src="TweetQuote" quoteText="Keeping the API stateless means that maintainability and debugging are made much easier."/>

Another challenge here is that it is quite common for an API to be served from one server and for the actual application to consume it from another. To make this happen, we need to enable [Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS). Since cookies can only be used for the domain from which they originated, they aren't much help for APIs on different domains than the application.

### 3. Apps rely on downstream services

Another common pattern seen with modern web applications is that they often rely on downstream services. For example, a call to the main application server might make a request to a downstream server before the original request is resolved. The issue here is that cookies don't "flow" easily to the downstream servers and can't tell those servers about the user's authentication state. Since each server has its own scheme for cookies, there is a lot of resistance to flow, and connecting to them is difficult.

## A Modern Alternative: The JSON Web Token (JWT)

To combat the issues detailed above, we can take a token-based approach by using JSON Web Tokens (JWTs) for authentication. A JWT contains three parts:

**1. Header**

The header tells us about the algorithm and token type. It is Base64URL encoded.

**2. Payload**

The payload contains any arbitrary information in the form of claims that we as developers find useful for our applications. The user's ID must be sent as a `sub` claim, but we can also send other useful information, such as the username, email, and more. The payload is also Base64URL encoded.

**3. Signature**

The signature is used to verify the authenticity of the JWT. There are several different algorithms that can be used for the signature. Some algorithms implement a shared secret (HMAC), and others use public-private key secrets (RSA).

![modern authentication jwt](https://images.ctfassets.net/23aumh6u8s0i/1sS3oSviChEPzlXMAYHHLQ/b58c9c25c3ecb38505a5e77e5965e981/legacy-app-auth-5)

From the user's perspective, logging in to an application that uses JWTs looks much like traditional authentication. Users enter their credentials as usual, but instead of the server creating a session and returning a cookie, it will respond with a JSON object that contains a JWT. The JWT then needs to be saved locally, which is normally done with local storage. However, as we'll see in the next section, it is possible to save the JWT in a cookie.

The JWT must be sent to the server to access protected routes, and it is typically sent as an `Authorization` header. The scheme used for this header is `Bearer`, so the full header looks like this:

```js
Authorization: Bearer <token>
```

Middleware on the protected API routes will check for a valid JWT, and if there is one, it will let the request through and return the data being requested. Since the user's information is contained within the JWT itself, there is no need to look the user up in a database, so there is less latency in the application.

It should be reiterated that the user's state is never saved in memory on the server, meaning that the user isn't "logged in" in the conventional sense. However, a valid JWT gives the user the keys to access data each time a request is made, and in this way, a stateless authentication mechanism is in place.

![](https://images.ctfassets.net/23aumh6u8s0i/1f37fJAPR7UgfFW8oYYeKs/5f00a4413b04510ad6bd6801f04a2fed/legacy-app-auth-2)

Using a JWT for authentication helps to solve the challenges noted above. We can fully rely on data APIs that are stateless and even make requests to downstream services. Since JWT is a specification [implemented nearly everywhere](http://jwt.io), connecting to downstream services built on a stack other than our own is easy. It also doesn't matter which domain is serving our API, nor does it matter which specific server a request goes to if the app is deployed across many.


## Bridging the Gap: Using JWTs in Cookies

Modernizing legacy applications by implementing token-based authentication can lead to many gains. If it isn't feasible for an organization to totally throw away cookies, there are still ways to make token authentication viable. Let's take a look at how this can be done with NodeJS and the **express-jwt** package.

### Step 1: Set Up a Back End

To follow along, you can download Auth0's [NodeJS seed project](https://auth0.com/docs/node-auth0/master/create-package?path=examples/nodejs-api&filePath=&type=server) from the [docs page](https://auth0.com/docs/quickstart/backend/nodejs/). Even though we're using an Auth0 seed project here, doing cookie-based authentication in this way will work with any service.

### Step 2: Install Cookie Parser

Once the dependencies for the seed project are installed by following the [installation steps](https://github.com/auth0/node-auth0/tree/master/examples/nodejs-api), we'll need to add one more package: **cookie-parser**. This package will allow us to read JWTs from cookies that are sent to the server.

```bash
npm install cookie-parser --save
```

With **cookie-parser** installed, we now need to require and use it in `server.js`.

```js
// server.js

...

var cookieParser = require('cookie-parser');

...

app.configure(function() {

  app.use(cookieParser());

  ...

});
```

### Step 3: Save the JWT as a Cookie

We'll need to retrieve a JWT for a user and save it locally as a cookie. If you're using Auth0 for this tutorial, you can find out more about retrieving JWTs for users in your Auth0 account by reading the [API documentation](https://auth0.com/docs/api/v2). We'll use jQuery in this example to make the AJAX calls easy.

Lets make a call to Auth0 to get a JWT.

```js
// app.js

$('.btn-login').click(function() {
  $.ajax({
    type: 'POST',
    url: 'https://{your-auth0-account}.auth0.com/oauth/ro',
    data: {
      client_id: '{your-client-id}',
      username: document.querySelector('#username').value,
      password: document.querySelector('#password').value,
      grant_type: 'password',
      scope: 'openid',
      connection:'Username-Password-Authentication'
    },
    success: function(data) {
      getJwtCookie(data.id_token);
    },
    error: function(error) {
      console.log('There was an error: ' + error)
    }

  });
});
```

In the success handler, we're calling a function called `getJwtCookie` and passing in the token that was received from Auth0. We need to create an endpoint on our application server that can validate the JWT that was received from Auth0 and send it back to us as a cookie, and we can do that in the `getJwtCookie` function.

```js
// app.js

function getJwtCookie(token) {
  $.ajax({
    type: 'POST',
    url: 'http://localhost:3001/secured/authorize-cookie',
    data: {
      token: token
    },
    headers: {
      'Authorization' : 'Bearer ' + token
    },
    success: function() {
      console.log('Cookie received!');
    },
    error: function() {
      console.log('Problem with cookie');
    }
  });
}

```
Next, lets set up the `authorize-cookie` endpoint to handle this call.

```js
// server.js

app.post('/secured/authorize-cookie', authenticate, function(req, res) {
  res.cookie('id_token', req.body.token, {
    expires: new Date(Date.now() + 36000),
    httpOnly: true
  });
  res.send(200, { message: 'Cookie set!' });
});
```

In the next step, we'll set up our **express-jwt** middleware, but we're making use of it already in the `authorize-cookie` route by passing it in as the second argument, `authenticate`. The middleware secures the endpoint and a valid JWT will be needed to access it. If the JWT is valid, we simply reflect it back as a cookie and set the `httpOnly` flag to `true` so that the cookie can only be accessed by the server. This route accomplishes the steps of validating the JWT that was received from Auth0, as well as the step of setting a cookie with the JWT.

**Note:** We are using an `Authorization` header to accomplish our cookie JWT in this example. This is the only place we would need to make a request using this header--the rest of the application will handle JWTs with cookies.

### Step 4: Set Up Middleware to Check for the Cookie
Normally, the **express-jwt** middleware will look for the presence of a header and retrieve the JWT from there. However, we can also create a custom function to define how the token should be retrieved.

```js
// server.js

...

var authenticate = jwt({
  secret: new Buffer(process.env.AUTH0_CLIENT_SECRET, 'base64'),
  audience: process.env.AUTH0_CLIENT_ID,
  // Custom function to retrieve the JWT
  // We first look for the JWT in a header and if it isn't there,
  // we look for it in a cookie
  getToken: function fromHeaderOrCookie(req) {
    if(req.headers.authorization && req.headers.authorization.split(' ')[0] === 'Bearer') {
      return req.headers.authorization.split(' ')[1];
    } else if(req.cookies && req.cookies.id_token) {
      return req.cookies.id_token;
    }
    return null;
  }
});

...
```

We've added the `getToken` function as an option on the object that is passed into `jwt`. Our implementation here says that we want to first look for the presence of a JWT as an `Authorization` header, and if there isn't anything there, we want to check whether there is a cookie with the name `id_token`.

### Step 5: Test the Secured Route

With the `id_token` cookie in place, we can see that requests to the `secured/ping` endpoint go through just fine.

![modern authentication jwt](https://images.ctfassets.net/23aumh6u8s0i/4j5ZnQitsiwgVbLtwupT71/104a61fb2584f11a192c1fb36e476f92/legacy-app-auth-3)

<include src="asides/Jwt" />

## Wrapping Up

As we've seen, modern web applications are crafted and deployed in ways that make conventional user authentication challenging. JWT authentication is an excellent way to get around these challenges and allows us to keep our application server stateless. If we need to lean on old practices, such as using cookies, we can do so and still support JWT authentication with a little tweaking on the server.


5 Steps to Add Modern Authentication to Legacy Apps Using JWTs

0cd73f2f2f39709bd03646e9225cc3d3?s=200 avatar

0cd73f2f2f39709bd03646e9225cc3d3?s=200

I’m an engineer with a passion for building frictionless products. I’ve built effective teams and have grown them into successful engineering organizations. I like to forge a culture.

CTO and Co-founder

Matias Woloski

Json Web Tokens (JWT) gets a logo, new website and more

In 2013 when we started building Auth0 we had to decide which standard we wanted our platform to be built on. Back then there was [WS-Fed](https://en.wikipedia.org/wiki/WS-Federation) and [SAML2](http://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf). I was very familiar with both, having worked on many projects with Microsoft technologies. My main issue with these standards was that they were too complex: too many knobs and levers, interop issues and above all, a lack of libraries.



On the other extreme we had OAuth2 which was rapidly being adopted because of its simplicity. It was also being used by Facebook, Google and many others. There were already libraries written in many languages, making it even more appealing.

However, [OAuth2](https://tools.ietf.org/html/rfc6749) was/is an __authorization__ protocol, not one specific for __authentication__ [[1](http://www.thread-safe.com/2012/01/problem-with-oauth-for-authentication.html)] [[2](http://homakov.blogspot.com.ar/2012/08/oauth2-one-accesstoken-to-rule-them-all.html)].

[OpenID Connect](http://openid.net/specs/openid-connect-core-1_0.html) was being drafted as a very thin layer on top of OAuth2 to overcome exactly that issue. With the introduction of [JSON Web Tokens](https://tools.ietf.org/html/rfc7519) there was now a simple way of verifying user identity and audience (the consumer of these tokens).

Back then it was on [draft-06](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-06), and I decided to join the Working Group.

## Why is JWT so popular?

![](https://images.ctfassets.net/23aumh6u8s0i/6eRP0BpQt8Hf1qY6WHNRGk/34336bf2f0d2af90d7d920b9c0ed84c7/jwt-google-trend)

I think there are many reasons why JWT is being widely adopted:

* It embraces JSON which is already heavily adopted across many stacks.
* It is simple to use and simple to implement (hence more libraries and fewer interop issues).
* It supports symmetric and asymmetric crypto which solves the majority of use cases.

## Numbers speak for themselves

About 2 years since the first draft this simple, yet useful standard expanded:

![](https://images.ctfassets.net/23aumh6u8s0i/1PUSHZTPdUqD2jvVlkN47L/9f2f1b3696ac54aae970f444e9751a0d/banner-jwt)

* [972 GitHub repos](https://github.com/search?q=jwt) related to JWT.
* [2600+ StackOverflow](http://stackoverflow.com/search?q=jwt) threads.
* 400K page views on [jwt.io](http://jwt.io).
* [50K Google](https://www.google.com.ar/search?q="json+web+token") results.

If you use Android, AWS, Microsoft Azure, Salesforce, or Google then chances are that you are already using JWT.

<include src="TweetQuote" quoteText="If you use AWS, Microsoft Azure, Salesforce, or Google then chances are that you are already using JWT."/>

We very much believe in this standard so we wanted to keep making contributions to foster its adoption. We are happy to share the **new logo**, the **new website**, **badges**, and other things. :)


## New Logo

The central component of the branding is a logo symbol representing an individual JSON Web Token. The circular icon was designed to suggest a coin while avoiding being mistaken for a digital currency symbol.

Here are some initial sketches and colors:

![](https://images.ctfassets.net/23aumh6u8s0i/4XQlyCKEVRjmXqvPOwSj5q/3af5e76fc7292dfd4e7b437d282a9eaf/jwt_02)
![](https://images.ctfassets.net/23aumh6u8s0i/2idVA183X17v3CfGC0uOmB/35b22395ff6ee0bbd090f81a57cd08c1/jwt_04)

We decided to use the starburst shape representing the crypto protection of a JSON Web Token. Multicolored spokes radiate from the centralized hub representing the various claims within a payload.
Here is the final symbol:

![](https://images.ctfassets.net/23aumh6u8s0i/6sw33rq7EM8nCi5Gov3RCD/6b1d1cf37d688b3e81d2445da694e938/jwt_01)

JSON Web Token has been abbreviated to the initials JWT and custom lettering was developed.

![](https://images.ctfassets.net/23aumh6u8s0i/6w5TnOcVKczBfjTvk5zpWU/96dd7ee784a2171e263bc71a15f9b343/jwt_03)
![](https://images.ctfassets.net/23aumh6u8s0i/16VIM0ExdiVtMpEVamzZzG/a0b6699a966257d51fa001ab55ddf5b4/jwt_05)

## New Site

We redesigned [jwt.io](http://jwt.io), incorporating the new branding. The debugger is still the central piece. We added support for RS256 in addition to HS256.

<img src="https://images.ctfassets.net/23aumh6u8s0i/5ng8giWbaI8NDj6ze9gLje/912d6a18286b995b182592eafda32760/jwt-1" class="expand"/>

In the libraries section, we improved the readability by color coding each library and using the proper logos for each. In addition to that, we added the number of stars from the GitHub repository.

<img src="https://images.ctfassets.net/23aumh6u8s0i/58Jbwy39S0YKyg9rDsICdv/d619bf661636457130fa4a31c948d68b/jwt-2" class="expand"/>

## Badges and Others

If your API supports JSON Web Tokens, feel free to add this badge

![](https://images.ctfassets.net/23aumh6u8s0i/jZkOsCfAXX0zSbq0Ae82v/77da371796a706d6b96b7cda06c6cde5/jwt-compatible)

If there is some functionality on your site that uses and exposes JSON Web Tokens, you can use the following button to open the JWT on jwt.io.

[![](https://images.ctfassets.net/23aumh6u8s0i/38tcsWr8NpjrGjCwMWQLZ7/b786abbaf88c090d025319eb3a91a087/jwt-view)](http://jwt.io/#id_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ)

The token is sent through the hash like this: `http://jwt.io/#id_token=eyJhbGciOi....`

Finally, we designed some cool JWT t-shirts that you can order from [swag.auth0.com](http://swag.auth0.com).


## Acknowledgements

Special thanks to [Ty Wilkins](http://tywilkins.com/) for crafting the logo and lettering, [Ricky Rauch](http://twitter.com/rickyrauch) and [team](http://dribbble.com/auth0) for the awesome looking website, [Alberto Pose](http://twitter.com/thepose) who created the initial jwt.io version and curates the community contributions, [Guillermo Rauch](http://twitter.com/rauchg) for his constant advice, [Mike Jones](http://self-issued.info) for introducing me into the working group and all of you who [contributed to jwt.io](https://github.com/jsonwebtoken/jsonwebtoken.github.io/graphs/contributors) through GitHub.

**JWT all the things!**

<include src="asides/Jwt" />

JWT: 2 years later

Damian Schenkelman

Damian was one of Auth0's earliest employees. He loves building products for developers and taking things from 0 to 1.
<br><br>
He played key roles in implementing product features and growing the engineering organization in the early stages, and later on defining Auth0's architecture for scale and creating new products. Today he helps shape Auth0's long term strategy and leads Auth0Lab, a small and amazing team doing research and development of forward-looking products.
<br><br>
He spends his spare time with family, and friends, exercising, and catching up on all things NBA.

VP R&D (Auth0Lab)

Most APIs today use an API Key to authenticate legitimate clients. API Keys are very simple to use from the consumer perspective:  You get an API key from the

Most APIs today use an **API Key** to authenticate legitimate clients. **API Keys** are very simple to use from the consumer perspective:

1. You get an **API key** from the service (in essence a shared secret).
2. Add the key to an `Authorization` header.
3. Call the API.

It can't get simpler than that, but this approach has some limitations.

The last couple of months, we've been working on our [API v2](https://docs.auth0.com/apiv2). We wanted to share what we've learnt implementing a more powerful security model using [JSON Web Tokens](http://jwt.io).



Using a JSON Web Token offers many advantages:

* **Granular Security**: API Keys provide an all-or-nothing access. JSON Web Tokens can provide much finer grained control.
* **Homogenous Auth Architecture**: Today we use cookies, API keys, home grown SSO solutions, OAuth etc. Standardizing on JSON Web Tokens gives you an homogenous token format across the board.
* **Decentralized Issuance**: API keys depend on a central storage and a service to issue them. JSON Web Tokens can be "self-issued" or be completely externalized, opening interesting scenarios as we will see below.
* **OAuth2 Compliance**: OAuth2 uses an opaque token that relies on a central storage. You can return a stateless JWT instead, with the allowed scopes and expiration.
* **Debuggability**: API keys are opaque random strings. JSON Web Tokens can be inspected.
* **Expiration Control**: API keys usually don't expire unless you revoke them. JSON Web Tokens can (and often do) have an expiration.
* **Devices**: You can't put an API key that has full access on a device, because what is on a phone or tablet can easily be stolen. But you can put a JWT with the right set of permissions.

If you'd like an in-depth introduction to **JSON Web Tokens**, check out our **free** ebook below.

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

## Granular Security

One of the most interesting benefits of using JWTs is the first one listed above. Back in the old days, when databases were at the center of our client-server applications, we could create users with specific permissions on the database:

<a href="https://images.ctfassets.net/23aumh6u8s0i/2paJRM6vdAq4RO2k6ypich/b960d3ab0c364b327b2d4a2f1afc66c4/permissions-sql" target="_blank"><img src="https://images.ctfassets.net/23aumh6u8s0i/s9tyvnrUrUjg7i39zWBOn/db84bd0b3a904e879c3484841d34cd1a/permissions-sql.png"/></a>

_Remember this?_

APIs are becoming central pieces of our distributed systems architecture. They are now the "gatekeepers" of our data. But in contrast with what was available in databases, virtually all API keys provide all-or-nothing access. Readers will likely be familiar with the `scope` parameter of OAuth2 based systems that offers this finer grained consent to access.

There are many situations in which you want to keep the simplicity of an **API Key** but only for a subset of all possible API operations.

[GitHub acknowledged this requirement](https://help.github.com/articles/creating-an-access-token-for-command-line-use/) and now provides a way of creating a token with the scopes you need (mimicking the OAuth2 consent):

![](https://images.ctfassets.net/23aumh6u8s0i/6fdGKpvxjgD7seKbyvjb9O/4d82a5cb332aa836d93cb7e3044b5707/token_scopes)

In the next section, we will go through the details of how this can be implemented.

### How to implement it?

We don't know how GitHub implemented it (they probably used Ruby), but we will use it as an example. Let's say we want to implement an endpoint in the API to **create new repos**. You could model this with the following **JSON Web Token** payload. If you provide any of those scopes, then you can create repos:

```
{
  iat: 1416929109, // when the token was issued (seconds since epoch)
  jti: "aa7f8d0a95c", // a unique id for this token (for revocation purposes)
  scopes: ["repo", "public_repo"]  // what capabilities this token has
}
```
_Look at this token in <a href="http://jwt.io?value=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE0MTY5MjkxMDksImp0aSI6ImFhN2Y4ZDBhOTVjIiwic2NvcGVzIjpbInJlcG8iLCJwdWJsaWNfcmVwbyJdfQ.XCEwpBGvOLma4TCoh36FU7XhUbcskygS81HE1uHLf0E" target="_blank">jwt.io</a>_

The API endpoint would simply check for the presence of the right **scope** atribute (this example is written in node.js but any language would work):

```
// intercept all calls to API and validae the token
app.use('/api', express_jwt({secret: SECRET, userProperty: 'token_payload'}));

// for POST /user/repo validate that there is a scope `repo` or `public_repo`
app.post('/api/user/repo',
        check_scopes(['repo', 'public_repo']),
        function(req, res, next) {
    // create a repo
    ....
});

```

Notice the `check_scopes` middleware on the `/api/user/repo` route. This is how the `check_scopes` function is implemented:

```
function check_scopes(scopes) {
  return function(req, res, next) {
    //
    // check if any of the scopes defined in the token,
    // is one of the scopes declared on check_scopes
    //
    var token = req.token_payload;
    for (var i =0; i<token.scopes.length; i++){
      for (var j=0; j<scopes.length; j++){
          if(scopes[j] === token.scopes[i]) return next();
      }
    }

    return res.send(401, 'insufficient scopes')
  }
}

```

> Notice that no one can change the scopes variables. JWTs are digitally signed, so its content cannot be tampered with.  

Documenting an API is equally important. What would be a good way for surfacing this on an API explorer?

For Auth0, we decided to build our own documentation using [swagger](http://swagger.io/). Since we are a multi-tenant system, each tenant has an API Key and Secret that is used to sign the token. As a developer, you mark which scopes you need and a token will be auto-generated. You can copy and paste it to [jwt.io](http://jwt.io) to see the structure (this is the __debuggable__ piece, by the way).

<a href="https://images.ctfassets.net/23aumh6u8s0i/33kBdPt5Hlzt2UEt0yoRQp/e7227bdb1d82dc16fed9a145dc64896b/api-explorer3" target="_blank"><img src="https://images.ctfassets.net/23aumh6u8s0i/7uKm8Sq6OiHUEs5v9AoKT7/3550cf71dfa93c43bbd0eb2b2b2c2191/api-explorer3.gif"/></a>

Scopes required by each operation are clearly identified:

<a href="https://images.ctfassets.net/23aumh6u8s0i/4FDPqZmzwJWGdg9YGSUcEf/5f6ecef62c9d7f3ae0f64edad904a3a1/api-scopes2" target="_blank"><img src="https://images.ctfassets.net/23aumh6u8s0i/4FDPqZmzwJWGdg9YGSUcEf/5f6ecef62c9d7f3ae0f64edad904a3a1/api-scopes2"/></a>

Our token format is a bit different from the one in the example we showed for GitHub. The good thing about JWTs is that they can contain _any_ data structure:

```
{
  iat: 1416929061,
  jti: "802057ff9b5b4eb7fbb8856b6eb2cc5b",
  scopes: {
    users: {
      actions: ['read', 'create']
    },
    users_app_metadata: {
      actions: ['read', 'create']
    }
  }
}
```

The string representation of the scope is `read:users` but in the JSON Web Token, we are using a more structured representation (note the hierarchy), this allows us to be more consistent. It also allows us to have an easy way to extend it for other scenarios.

## Conclusion & Resources

We have shown a new way of securing APIs based on JSON Web Tokens. This approach has some interesting benefits, in particular around _granular security_. In future posts we will go over other aspects, starting with how to revoke tokens.

Below are some of the resources that we used in our node.js backend implementation:

* The [hapi.js](http://hapijs.com) framework to create the API.
* A [fork](https://github.com/auth0/hapi-auth-jwt) of [hapi-auth-jwt](https://github.com/ryanfitz/hapi-auth-jwt) with [support for multitenant apps](https://github.com/ryanfitz/hapi-auth-jwt/pull/10) to handle authentication with JWTs.
* The awesome [ratify](https://github.com/mac-/ratify) library to both validate API input using [JSON schemas](http://json-schema.org) and automatically generate [swagger](http://swagger.io/) from said schemas for our docs.
* Swagger's support for arbitrary [authorizations objects](https://github.com/swagger-api/swagger-spec/blob/master/versions/1.2.md#514-authorizations-object) and a slightly [customized swagger-ui template](https://github.com/swagger-api/swagger-ui#customize) to render the scopes per operation.

If you want to see an example of this working, you can check out our API v2: <https://docs.auth0.com/apiv2>

We would love to hear your thoughts about this approach!

[Discuss here](https://ask.auth0.com/t/using-json-web-tokens-as-api-keys/357)

<include src="asides/Jwt" />

"tokens"