deepu-sasidharan

Deepu is a polyglot developer, Java Champion, and OSS aficionado. He mainly works with Java, JS, Rust, and Golang. He co-leads JHipster and created the JDL Studio and KDash. He's a Staff Developer Advocate at Okta. He is also an international speaker and a published author.

Staff Developer Advocate

Deepu K Sasidharan

Learn how to build a tool-calling AI agent using LangGraph, Vercel AI SDK, and Next.js. Integrate different kinds of tools in them. Use Google services like Gmail, Calendar, and Drive as tools secured using Auth0 Token Vault.

**AI agents** and **Operators** are the next big things in software development. In a [previous post](https://auth0.com/blog/genai-tool-calling-intro/), we discussed how AI agents are taking center stage by seamlessly integrating with multiple digital tools to be more efficient. In this post, we will be building a personal assistant that can use different types of tools. Both simple unauthenticated tools and more complex authenticated tools like Gmail, Calendar, and Google Drive.

If you haven't read the previous post, I recommend you do so before continuing to better understand tool calling in AI agents and how security is currently handled.

<include
  src="LinkCard"
  title="Tool Calling in AI Agents: Empowering Intelligent Automation Securely"
  link="https://auth0.com/blog/genai-tool-calling-intro/"
  description="Discover how AI agents are taking center stage by seamlessly integrating with multiple digital tools to be more efficient. Learn why it is important to secure them."
  img="https://images.ctfassets.net/23aumh6u8s0i/4LrNhImjPcdPVpmCIrhlG9/4efed8dfb26630e6cf48b4a478a1f550/genai-tool-calling-intro.png"
/>

To keep this post focused on tool calling, we will only focus on the AI agent part and not the UI. Each step of the tutorial, including building the UI, can be found as a distinct commit in the [GitHub repository](https://github.com/auth0-samples/auth0-assistant0).

## Technology Stack

We will use a [Next.js](https://nextjs.org/) application called **Assistant 0** as the base, Assistant 0 is an AI personal assistant that consolidates your digital life by dynamically accessing multiple tools to help you stay organized and efficient.

Apart from Next.js, we mainly use the following technologies:

- [LangGraph.js](https://langchain-ai.github.io/langgraphjs/) and [LangChain's JavaScript framework](https://js.langchain.com/docs/introduction/) for building agentic workflows.
- [LangChain community tools](https://js.langchain.com/docs/integrations/tools/).
- Vercel's [AI SDK](https://github.com/vercel-labs/ai) to stream response tokens to the client and display the incoming messages.
- The [Auth0 AI SDK](https://github.com/auth0-lab/auth0-ai-js) and [Auth0 Next.js SDK](https://github.com/auth0/nextjs-auth0) to secure the application and call third-party APIs.

## Prerequisites

> **You will need the following tools and services to build this application**:
>
> - [Bun v1.2](https://bun.sh/) or [NodeJS v20](https://nodejs.org/en/download)
> - An Auth for GenAI account. [Create one](https://a0.to/ai-content).
> - An OpenAI account and API key. [Create one](https://platform.openai.com) or use any [other LLM provider supported by LangChain](https://js.langchain.com/docs/integrations/llms/).
> - A SerpAPI account and API key. [Create one](https://serpapi.com/).
> - A Google account for Gmail, Calendar, and Drive. Preferably a new one for testing.

## Getting Started

First clone [the repository](https://github.com/auth0-samples/auth0-assistant0) and install the dependencies:

```bash
git clone https://github.com/auth0-samples/auth0-assistant0.git
cd auth0-assistant0
git switch step-1 # so that we skip building the UI and get straight to the AI agent

bun install # or npm install
```

Next, you'll need to set up environment variables in your repo's `.env.local` file. Copy the `.env.example` file to `.env.local`. To start you'll just need to add your OpenAI API key.

Now, start the development server:

```bash
bun dev # or npm run dev
```

Open `http://localhost:3000` with your browser to see the result! Ask the agent something, and you'll see a streamed response.

![Assistant 0](https://images.ctfassets.net/23aumh6u8s0i/ePzgV9PLYqmwdsqdJC2VU/3507e783ee8199b6a5599742ef81fed7/assistant-0.png)

### A Peek into the Code

The application is structured as below:

- `src/app`: Contains the Next.js application routes, layout, and pages.
- `src/app/page.tsx`: Home page with chat interface.
- `src/api/chat/route.ts`: API route for handling chat requests. This is where the AI agent is defined.
- `src/components`: UI components used in the application.
- `src/lib`: Services and configurations. This is where custom tools will be defined.
- `src/utils`: Utility functions

Let's take a look at the `src/api/chat/route.ts` file where the AI agent is defined.

```js
// src/api/chat/route.ts
// ...
const AGENT_SYSTEM_TEMPLATE = `You are a personal assistant named Assistant0. 
You are a helpful assistant that can answer questions and help with tasks. 
You have access to a set of tools, use the tools as needed to answer the user's question.`;

export async function POST(req: NextRequest) {
  // ... Process the request and get messages
  // Create a new OpenAI chat model
  const llm = new ChatOpenAI({ model: 'gpt-4', temperature: 0 });
  const tools = [];
  // Use a prebuilt LangGraph agent.
  const agent = createReactAgent({
    llm,
    tools,
    messageModifier: new SystemMessage(AGENT_SYSTEM_TEMPLATE),
  });
  // Stream back all generated tokens and steps from their runs.
  const eventStream = agent.streamEvents({ messages }, { version: 'v2' });
  // Log tool calling data. Only in development mode
  const transformedStream = logToolCallsInDevelopment(eventStream);
  // Adapt the LangChain stream to Vercel AI SDK Stream
  return LangChainAdapter.toDataStreamResponse(transformedStream);
}
```

The route uses a prebuilt LangGraph agent and OpenAI chat model. No tools are defined yet; we will add them in the next section.

Here is a high-level architecture of the application with the tools we will be adding in this post.

![Assistant 0 architecture](https://images.ctfassets.net/23aumh6u8s0i/6ZTtsivmBOPUmKGWx479Xm/d8d90c3bf3f24f1c8ce99ff703a1ba7d/architecture.jpg)

Now that the base application is running, let's start building our personal assistant with tool-calling capabilities.

## Add Tools to the Assistant

If you recall the previous post, we discussed authenticated and unauthenticated tools. Let's start with an unauthenticated tool and then proceed to add more complex tools like Gmail, Calendar, and Google Drive.

### Add a Calculator Tool

We will start with a simple calculator tool from LangChain community tools to perform basic arithmetic operations.

Install the `@langchain/community` package.

```bash
bun add @langchain/community # or npm i @langchain/community
```

Update the `src/api/chat/route.ts` file with the following code.

```js
// src/api/chat/route.ts
import { Calculator } from '@langchain/community/tools/calculator';
// ...
export async function POST(req: NextRequest) {
  // ...
  const tools = [new Calculator()];
  // ...
}
```

It's that simple! Now try asking the assistant to perform some calculations. For example, `what is (2+56) x 200`. You should see the answer in the UI. If you check the console where Next.js dev server (`bun dev`) is running, you should see the tool calling data like below.

```bash
Tool calls state: {
  "call_E3Za9klJcJ5TADWiMj8XfjdB": {
    "name": "calculator",
    "args": "{\n  \"input\": \"(2+56) * 200\"\n}"
  }
}
 POST /api/chat 200 in 8382ms
```

### Add a Web Search Tool

Now let's add a web search tool to search the web for information. Let's use [SerpAPI](https://serpapi.com/) for this. It's an authenticated tool. But since this is going to be API usage and not a user impersonation, we can simply use an API key.

First, get an API key from SerpAPI and add that to your `.env.local` file.

```bash
SERPAPI_API_KEY=your-api-key
```

Now, update the `src/api/chat/route.ts` file with the following code.

```js
// src/api/chat/route.ts
import { SerpAPI } from '@langchain/community/tools/serpapi';
// ...
export async function POST(req: NextRequest) {
  // ...
  const tools = [new Calculator(), new SerpAPI()];
  // ...
}
```

Again, quite simple! Now try asking the assistant to search the web for information. For example, `What is the top 10 news today?`. You will see the response in the UI.

![Assistant 0 web search](https://images.ctfassets.net/23aumh6u8s0i/h4hWDQwBBTUiDh6gdaVET/137647c87dd51c6cc34ec0a44d6e453d/assistant-0-web-search.png)

If you check the console, you should see the tool calling data like the one below.

```bash
Tool calls state: {
  "call_e8vqAPW45vMsUbFiIF9SW5Yn": {
    "name": "search",
    "args": "{\n  \"input\": \"top 10 news today\"\n}"
  }
}
 POST /api/chat 200 in 15443ms
```

This corresponds to the `step-2` branch in case you want to double-check your code.

```bash
git switch step-2
```

### Add Gmail Tools

Now, let's get into business. I know you are here for this part, not to learn about adding calculators and web search tools. But before we can add a Gmail tool, we need to add Auth0 authentication to the application since we will be using Auth0's [Token Vault](https://auth0.com/docs/secure/tokens/token-vault) feature to get access tokens to call the Gmail API via a tool.

#### Add Auth0 Authentication

First, let's add Auth0 as the authentication provider to the application.

Follow the [Auth0 Next.js quickstart guide](https://auth0.com/ai/docs/user-authentication) to set up the application.

> If you want to create the Auth0 application manually, create a new application (Type: **Regular Web App**, Callback URL: `http://localhost:3000/auth/callback`) and get the **client ID** and **client secret**.

Update the `.env.local` file with credentials, and create the `src/lib/auth0.ts` and `src/middleware.ts` files.

If you want to skip to the next step, check out the `step-3` branch. The [full changelog for this step is on GitHub](https://github.com/auth0-samples/auth0-assistant0/commit/9a6db1ec49511afa7c361080c3f5a1854ee8efe5).

```bash
git switch step-3
```

#### Configure Auth0 for Gmail

To use Gmail API with Auth0 via a Google Social Connection, you need to do the following:

- Create Google OAuth 2.0 credentials
- Configure Gmail social connection in Auth0

You can follow the [Google Sign-in and Authorization](https://auth0.com/ai/docs/google-sign-in-and-auth) guide from Auth0 to configure this.

#### Add Gmail Search Tool

We can add Gmail tools now that we have Auth0 authentication in place. Let's start with a Gmail search tool. This tool will allow the assistant to search for emails in the user's Gmail account.

First, we need to get an access token for the Gmail API. We can get this using the [Auth0 Token Vault](https://auth0.com/docs/secure/tokens/token-vault) feature.

Update `src/lib/auth0.ts` with the following code.

```js
// src/lib/auth0.ts
// ...
export const auth0 = new Auth0Client({
  // this is required to get federated access tokens from services like Google
  authorizationParameters: {
    access_type: 'offline',
    prompt: 'consent',
  },
});

export const getGoogleAccessToken = async () => {
  const { token } = await auth0.getAccessTokenForConnection({
    connection: 'google-oauth2',
  });
  return token;
};
```

Install the `googleapis` package.

```bash
bun add googleapis # or npm i googleapis
```

Import the `GmailSearch` tool from LangChain community tools and update the `src/api/chat/route.ts` file with the following code.

```js
// src/api/chat/route.ts
import { GmailSearch } from '@langchain/community/tools/gmail';
import { getGoogleAccessToken } from '@/lib/auth0';
// ...
export async function POST(req: NextRequest) {
  // ...
  // Update the LLM model to gpt-4o-mini to support a larger context window
  const llm = new ChatOpenAI({
    model: 'gpt-4o-mini',
    temperature: 0,
  });
  // Get the access token via Auth0
  const accessToken = await getGoogleAccessToken();
  // Provide the access token to the Gmail tools
  const gmailParams = {
    credentials: { accessToken },
  };
  const tools = [new Calculator(), new SerpAPI(), new GmailSearch(gmailParams)];
  // ...
}
```

We are all set! Now try asking the assistant to search for emails. For example, `What is the latest unread email?`. You should see the response in the UI.

![Assistant 0](https://images.ctfassets.net/23aumh6u8s0i/14n2drq2woolLeJybBMWk6/3bbc575f92493dc2322f485a6b4f4ac9/assistant-0-gmail-search.png)

If you check the console, you should see the tool calling data like the one below.

```bash
Tool calls state: {
  "call_rCzcZRjueyD8p2kzTmeZMiSK": {
    "name": "search_gmail",
    "args": "{\"query\":\"is:unread\",\"maxResults\":1,\"resource\":\"messages\"}"
  }
}
 POST /api/chat 200 in 10892ms
```

#### Add Gmail Draft Tool

We will add a Gmail draft tool next. This tool will allow the assistant to draft emails on behalf of the user.

Update the `src/api/chat/route.ts` file with the following code.

```js
// src/api/chat/route.ts
import { GmailDraft } from '@langchain/community/tools/gmail';
// ...
export async function POST(req: NextRequest) {
  // ...
  const tools = [
    new Calculator(),
    new SerpAPI(),
    new GmailSearch(gmailParams),
    new GmailDraft(gmailParams),
  ];
  // ...
}
```

Now, ask the assistant to draft an email. For example, `Draft an email to John Doe about the meeting tomorrow.` You should see the response in the UI.

![Assistant 0](https://images.ctfassets.net/23aumh6u8s0i/hWz4f6iUXTacbCNoqxwLz/c16c70d786027012b4c4944639339999/assistant-0-gmail-draft.png)

If you check the console, you should see the tool calling data like the one below.

```bash
Tool calls state: {
 "call_pPAk6rFYJSSyAuYkNWFf5KYX": {
   "name": "create_gmail_draft",
   "args": "{\"message\":\"Hi John,\\n\\nI hope this message finds you well. I wanted to … [Your Name]\",\"to\":[\"john.doe@example.com\"],\"subject\":\"Meeting Reminder\",\"cc\":[],\"bcc\":[]}"
 }
}
 POST /api/chat 200 in 7594ms
```

You can find the [full changelog of these two steps on GitHub](https://github.com/auth0-samples/auth0-assistant0/commit/ae2dd28b2fd2248d1d9ca76bd77269ea75817379).

This corresponds to the `step-4` branch in case you want to double-check your code.

```bash
git switch step-4
```

## Learn more about AI Agents and Auth for GenAI

You have successfully built an AI personal assistant that can search the web, search your emails, and draft emails. In the next chapter, we will add more tools like User Info, Google Calendar, Google Drive, and Slack to the assistant.

This tutorial is part of a series of posts on tool-calling Agents with [Auth for GenAI](https://a0.to/ai-content), we learned how to add tools to an AI agent and how to secure them using Auth0.

Sign up for [Auth for GenAI in Developer Preview](https://a0.to/ai-content).

Before you go, we have some great news to share: we are working on more content and sample apps in collaboration with amazing GenAI frameworks like [LlamaIndex](https://www.llamaindex.ai/), [LangChain](https://www.langchain.com/), [CrewAI](https://www.crewai.com/), [Vercel AI](https://vercel.com/ai), and [GenKit](https://firebase.google.com/docs/genkit). [Auth for GenAI](https://auth0.com/blog/introducing-auth-for-genai-launching-identity-for-ai-agents/) is our new product to help you protect your user's information in GenAI-powered applications. Make sure to join the [Auth0 Lab Discord server](http://a0.to/auth0-lab-discord) to hear more and ask questions.


Build an AI Assistant with LangGraph, Vercel, and Next.js: Use Gmail as a Tool Securely

37590801?s=460&v=4

A software engineer who dreams about non-electric sheep and autonomous vehicles and likes to champion security.

Software Engineer

Dan Arias

Secure Fastify APIs easily with the Auth0 Fastify SDK. It simplifies Auth0 integration, offering route protection and token validation.

Fastify is rapidly gaining traction among Node.js developers, and for good reason! If you're looking for a high-performance and low-overhead way to build web applications and APIs, Fastify is an excellent choice. Its plugin architecture is powerful, but securing those APIs remains a critical concern for developers.

To help address this, we are introducing the **`auth0-fastify-api` SDK**. This new package brings seamless Auth0 integration into your Fastify projects, simplifying API endpoint protection.

## So, What is Fastify, Anyway?

For those who might be new to it, Fastify is a web framework for Node.js focused on delivering a strong developer experience with minimal overhead, built around a robust plugin system. Key features include:

- **High Performance:** Fastify is known as one of the fastest Node.js frameworks, utilizing optimizations like schema-based request/response serialization.
- **Extensibility:** A rich ecosystem of plugins allows developers to easily add needed functionality.
- **Developer Experience:** Features like built-in logging, developer-friendly error handling, and first-class TypeScript support contribute to a smoother development process.
- **Schema-Powered:** Use JSON Schema to validate routes and serialize outputs, leading to more predictable and robust applications.
- **Helpful CLI:** The **`fastify-cli`** tool streamlines common development tasks like running the app and generating project scaffolds ([See fastify-cli on GitHub](https://github.com/fastify/fastify-cli)).
- **NestJS Integration:** Fastify's performance can also be leveraged within the popular NestJS framework by using it as the underlying HTTP provider ([Learn More](https://docs.nestjs.com/techniques/performance#performance-fastify)).

## Introducing `auth0-fastify-api`

This new SDK is specifically designed to secure Fastify APIs. It functions as a dedicated Fastify plugin to simplify the validation of access tokens issued by Auth0.

Here's what the SDK offers:

- **Simple Integration:** Sets up as a standard Fastify plugin.
- **Automatic Token Validation:** Handles the validation of incoming JWT access tokens (sent as Bearer tokens) against your Auth0 tenant configuration.
- **Route Protection:** Provides a **`requireAuth`** decorator for easily securing specific routes.
- **Scope Enforcement:** Allows specification of required scopes (permissions) needed to access certain endpoints.
- **User Information Access:** Makes the validated token payload available on **`request.user`**.
- **Token Access Utility:** Includes **`request.getToken()`** for accessing the raw token string if necessary.
- **Standard Error Handling:** Sends standards-compliant `WWW-Authenticate` headers on authentication/authorization errors.

## Getting Started: Quick Setup

Integrating the SDK involves two main steps:

1.  **Install the SDK:**

```bash
npm install @auth0/auth0-fastify-api
# or
yarn add @auth0/auth0-fastify-api
```

2.  **Register the Plugin:**

In your main Fastify application file, register the plugin, providing your Auth0 domain and API audience:

```typescript
import Fastify from "fastify";
import Auth0 from "@auth0/auth0-fastify-api";

const fastify = Fastify({ logger: true });

fastify.register(Auth0, {
  domain: "YOUR_AUTH0_DOMAIN", // For example: your-tenant.auth0.com
  audience: "YOUR_API_AUDIENCE", // The Identifier of your API in Auth0
});

// ... rest of your setup
```

> Remember to replace the placeholder values with your actual Auth0 domain and API identifier.

### A Functional Example

Let's look at a functional example that demonstrates setting up a basic server, loading configuration from the environment, and protecting a route.

Create a `fastify` directory anywhere in your system and initialize a Node.js project within it:

```bash
npm init -y
```

Within that directory, create a `server.ts` file and follow the instructions in this section to build it up.

First, import the necessary modules and use `dotenv` to load configurations like your Auth0 domain and audience from a `.env` file, which avoids hardcoding sensitive credentials.

```typescript
import Fastify from "fastify";
import Auth0 from "@auth0/auth0-fastify-api";
import * as dotenv from "dotenv";

dotenv.config();

const fastify = Fastify({
  logger: true,
});

if (!process.env.AUTH0_DOMAIN || !process.env.AUTH0_AUDIENCE) {
  fastify.log.error("Auth0 domain or audience not configured in .env file");

  process.exit(1);
}
```

It's good to check that the environment variables were loaded correctly.

Next, register the `Auth0` plugin, passing the configuration loaded from the environment variables:

```typescript
fastify.register(Auth0, {
  domain: process.env.AUTH0_DOMAIN,
  audience: process.env.AUTH0_AUDIENCE,
});
```

To ensure the `Auth0` plugin has finished loading before defining routes that use its decorators, such as `requireAuth`, register your protected routes inside an anonymous plugin function:

```typescript
fastify.register(() => {
  fastify.get("/", { preHandler: fastify.requireAuth() }, (_, reply) => {
    reply.send({ ok: true });
  });
});
```

Finally, start the server, listening on the port `3000`:

```typescript
fastify.listen({ port: 3000 }, function (err, address) {
  if (err) {
    fastify.log.error(err);
    process.exit(1);
  }

  fastify.log.info(`Server is now listening on ${address}`);
});
```

You can run this short example by following these steps:

Install dependencies:

```bash
npm install fastify @auth0/auth0-fastify-api dotenv
```

Create a `.env` file with your Auth0 details:

```bash
AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_AUDIENCE=your-api-identifier
```

You can follow the steps on the ["Register APIs"](https://auth0.com/docs/get-started/auth0-overview/set-up-apis) document to learn how to create an API in the Auth0 Dashboard and get the required values: the Auth0 Domain, which is your tenant domain, and the Auth0 Audience, which is a unique identifier for your API.

Run the server:

```bash
npx ts-node server.ts
```

This provides a basic but functional starting point that loads configuration securely and correctly waits for the Auth0 plugin before defining protected routes.

## Securing A Route with `requireAuth`

As you saw earlier, to protect an individual API endpoint, use the **`requireAuth`** decorator provided by the SDK. Add it as a `preHandler` in your route definition:

```typescript
fastify.get(
  "/private",
  { preHandler: fastify.requireAuth() },
  async (request, reply) => {
    const user = request.user;
    return { message: "This is a protected route", user };
  }
);
```

Fastify will only reach the body of the route event handler if the token sent in the request authorization header is valid. The decoded token claims of the token are available in the `request.user` object.

If a request is made to `/private` without a valid Bearer token in the `Authorization` header, the SDK automatically rejects it with a `401 Unauthorized` status.

### Securing Multiple Routes

Applying the `preHandler` to every route can be repetitive if multiple routes require the same protection. Fastify's plugin system and encapsulation offer an efficient way to apply an authorization guard at the router level to protect multiple routes at once.

Group related routes within their own plugin and apply the **`requireAuth`** hook once using [`fastify.addHook`](https://fastify.dev/docs/latest/Reference/Server/#addhook) within that plugin's context. All routes defined within that plugin will then inherit the hook.

Let's see this concept in action.

**1. Create a routes plugin:**

Within an asynchronous Fastify plugin, you use `fastify.addHook("preHandler", fastify.requireAuth())` to run the authentication check before any route defined within this plugin. Routes defined after this hook (`/profile`, `/orders`, etc.) are automatically protected.

```typescript
// private-routes.ts
import { FastifyPluginAsync } from "fastify";

const privateRoutes: FastifyPluginAsync = async (fastify, opts) => {
  // Apply the hook once for all routes in this plugin
  fastify.addHook("preHandler", fastify.requireAuth());

  fastify.get("/profile", async (request, reply) => {
    // Token is already validated by the hook
    return { user: request.user };
  });

  fastify.get("/orders", async (request, reply) => {
    // Hook handles main auth; specific checks can still happen here
    if (!request.user.scope?.includes("read:orders")) {
      return reply.code(403).send({ error: "insufficient_scope" });
    }
    return {
      orders: [
        /* ... */
      ],
      user_id: request.user.sub,
    };
  });
  // Define more protected routes here...
};

export default privateRoutes;
```

**2. Register the plugin in your main server file:**

In your main server setup (likely within the `fastify.register(async function(fastify){...})` block), import the `privateRoutes` plugin. Use `fastify.register` to load it, passing the `prefix` option (e.g., `{ prefix: "/api/v1" }`) to mount all routes from the plugin under that path.

```typescript
import Fastify from "fastify";
import Auth0 from "@auth0/auth0-fastify-api";
import * as dotenv from "dotenv";
import privateRoutes from "./private-routes"; // Import the routes plugin

dotenv.config();

const fastify = Fastify();

fastify.register(Auth0, {
  domain: process.env.AUTH0_DOMAIN,
  audience: process.env.AUTH0_AUDIENCE,
});

fastify.register(async function (fastify) {
  if (!process.env.AUTH0_DOMAIN || !process.env.AUTH0_AUDIENCE) {
    fastify.log.error("Auth0 domain or audience not configured in .env file");
    
    process.exit(1);
  }

  // Register the protected routes plugin under the /api/v1 prefix
  fastify.register(privateRoutes, { prefix: "/api/v1" });

  // Routes defined outside that plugin don't inherit its hooks 
  // and need their own protection
  fastify.get("/", { preHandler: fastify.requireAuth() }, (_, reply) => {
    reply.send({ ok: true });
  });
});

fastify.listen({ port: process.env.PORT || 3000 });
```

Now, requests to `/api/v1/profile`, `/api/v1/orders`, or any other route inside `private-routes.ts` are automatically protected by the **`requireAuth`** hook applied at the plugin level.

## Enforcing Scopes

If you need to ensure the user has been granted specific permissions (scopes) in their access token, use the `scopes` property of the **`requireAuth`** decorator:

```typescript
const requiredScopes = ["read:messages", "write:messages"];

fastify.post(
  "/messages",
  { preHandler: fastify.requireAuth({ scopes: requiredScopes }) },
  async (request, reply) => {
    return { message: "Message created successfully", user: request.user };
  }
);
```

Only requests with valid tokens containing both `read:messages` and `write:messages` scopes will reach the route event handler body.

If you don't have multiple scopes to check, you can also assign `scopes` a string as its value. For a single scope, you could use the following:

```typescript
const requiredScopes = "read:messages";
```

If the validated token doesn't include _all_ the specified scopes, the SDK will return a `403 Forbidden` error with an `insufficient_scope` code.

## Accessing User Information

Once a token is validated by `requireAuth`, its decoded payload (claims) is attached to the Fastify request object at `request.user`. This typically includes information like the user ID (`sub`), audience (`aud`), issuer (`iss`), and granted scopes (`scope`).

```typescript
fastify.get(
  "/profile",
  { preHandler: fastify.requireAuth() },
  async (request, reply) => {
    // Access the user's unique identifier (subject)
    const userId = request.user.sub;
    // Access the scopes granted in this token
    const scopes = request.user.scope;

    return { userId, scopes, fullProfile: request.user };
  }
);
```

## Conclusion

The `auth0-fastify-api` SDK provides a straightforward way to secure your Fastify APIs by integrating Auth0 token validation. It offers simple decorators for protecting routes and checking scopes, allowing you to focus on your application's core logic.

We encourage you to try it out in your next Fastify project and share your feedback! Check out the [source code](https://github.com/auth0/auth0-fastify/blob/main/packages/auth0-fastify-api) and [examples](https://github.com/auth0/auth0-fastify/blob/main/packages/auth0-fastify-api/EXAMPLES.md) to learn more.

Happy coding!

Announcing the Auth0 Fastify API SDK: Secure Your APIs with Speed!

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

Nelson Matias

As a Group Product Manager at Auth0, I focus on delivering innovative solutions that enhance security and user experience for both businesses and developers. With hands-on experience as a Developer, Consultant, and Solution Architect, along with years of working in Technical Account Management, I’m passionate about solving complex problems and shaping the future of identity management.
Outside of work, I often watch football, listen to music, or spend quality time with my kids.

Group Product Manager

Continuous Session Protection empowers customers to meet a wide range of session and refresh token security needs, including custom lifetimes and revocation capabilities. Let’s dive deeper into how these features can enhance your security strategy.

Continuous Session Protection Now Available for Enterprise Customers

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

A wrong interpretation of the OAuth specifications can lead to hours of debugging and headaches. Learn the details to avoid them.

Specifications aim to find a common way to interoperate. This is why they need to be precise and unambiguous. But sometimes wrong interpretations occur, leading to implementations that break that desired interoperability. The “case” of the bearer scheme in OAuth 2.0 is one of these situations.

## The Problem with the Bearer Scheme

Imagine your application is calling a protected third-party API and getting an error you don’t understand. Everything worked fine in your test environment when you mocked the API. Why does it fail when you call the actual API? This happens many times, but you have checked everything this time, and your code looks fine. You are passing an access token, which you are sure is valid and not expired. Yet you still have that *500 - Internal Server Error* as response status code or, if you're lucky, *401 - Unauthorized*.

After hours of investigations, you find that you were using “bearer” as the string that qualifies the scheme of your access token while the API expects “Bearer”. That's to say, your HTTP request is like the following:

```http
GET /shop/orders
Host: api.example.com
Authorization: bearer eyJhbGciOiJIUzI1...
```

But the API expects a request like this:

```http
GET /shop/orders
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1...
```

The letter case of "b" in "bearer" is the only difference! 😳

You can’t change the third-party API, of course, so you need to change your application. Is it fair?

## The Discussion on the Bearer Scheme Case

You may think that the situation described in the previous section is an exceptional case. Actually, it's more common than you think (see [this](https://www.googlecloudcommunity.com/gc/Apigee/Case-sensitivity-of-AccessTokenPrefix-is-not-properly-handled/m-p/640501), [this](https://community.auth0.com/t/call-protected-apis-from-a-blazor-web-app/132123/26), [this](https://github.com/golang/oauth2/issues/113), and [this](https://jira.atlassian.com/browse/BCLOUD-14135?focusedId=3315945&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel), just for a few public examples).

There are many discussions about the correct letter case of the bearer scheme identifier in OAuth 2.0. Some say it should be capitalized, while others say it should be case-insensitive. Someone turned from case-insensitive to capitalized just to *honor* the specifications, not because they had any issue ( [here](https://github.com/mauriciovigolo/keycloak-angular/issues/217) and [here](https://github.com/spring-attic/spring-security-oauth/issues/457), for example).

Many argue that the first letter should be capitalized and mention [the specifications](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1):

```
The syntax for Bearer credentials is as follows:
     b64token    = 1*( ALPHA / DIGIT /
                       "-" / "." / "_" / "~" / "+" / "/" ) *"="
     credentials = "Bearer" 1*SP b64token
```

Others claim that it should be case-insensitive and mention [the specifications](https://datatracker.ietf.org/doc/html/rfc6749#section-5.1) as well:

```
token_type
         REQUIRED.  The type of the token issued as described in
         Section 7.1.  Value is case insensitive.
```

It sounds like a philosophical discussion, but it has practical consequences. Who is right?

## Solving the Bearer Scheme Case

The [OAuth 2.0 specifications](https://datatracker.ietf.org/doc/html/rfc6749#section-5.1) clearly state that the token type (i.e., the "bearer" string) must be case insensitive. However, the syntax defined in [the Bearer Token Usage specifications](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1) seems to contradict what the other one established. The [ABNF](https://en.wikipedia.org/wiki/Augmented_Backus%E2%80%93Naur_form) expression defining the syntax uses "Bearer", the capitalized version:

```
b64token    = 1*( ALPHA / DIGIT /
                       "-" / "." / "_" / "~" / "+" / "/" ) *"="
credentials = "Bearer" 1*SP b64token
```

Apparently the specifications seem inconsistent. 🤔

However, according to [the specifications of the ABNF grammar](https://www.rfc-editor.org/rfc/rfc5234#page-5):

```
NOTE:
      ABNF strings are case insensitive and the character set for these
      strings is US-ASCII.
   Hence:
         rulename = "abc"
   and:
         rulename = "aBc"
   will match "abc", "Abc", "aBc", "abC", "ABc", "aBC", "AbC", and
   "ABC".

   To specify a rule that is case sensitive, specify the characters
   individually.

   For example:
         rulename    =  %d97 %d98 %d99
   or
         rulename    =  %d97.98.99
   will match only the string that comprises only the lowercase
   characters, abc.
```

That means that the *case-insensitive party* is right! 🎉

You can write the "bearer" keyword however you like. This is more of a warning to API implementers than client builders because to be truly OAuth 2.0 compliant, they MUST accept any form of "bearer" keyword.

To remove any doubt, the OAuth discussion group added a note to the upcoming [OAuth 2.1 specifications](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-11#section-5.1.1):

```
As described in Section 2.3 of [RFC5234], the string Bearer is case-insensitive. This means all of the following are valid uses of the Authorization header:

Authorization: Bearer mF_9.B5f-4.1JqM

Authorization: bearer mF_9.B5f-4.1JqM

Authorization: BEARER mF_9.B5f-4.1JqM
```

Keep in mind that even `auThoriZation: bEAReR mF_9.B5f-4.1JqM` must be accepted. The [HTTP header field names are case-insensitive](https://datatracker.ietf.org/doc/html/rfc2616#section-4.2), too. 😜

## Conclusion

Small details that may seem insignificant can sometimes create incompatibility problems, and it may take a lot of time to figure out what's going on and find the correct solution. Writing (and reading) protocol specifications is complex. You must avoid ambiguities in their drafting and have a good technical background to read and implement them correctly.

I hope that this brief digression into the details of the OAuth specifications will be helpful to you and save you hours of debugging when an API is a little reluctant to accept creative ways of writing "bearer". 😇


The Curious “Case” of the Bearer Scheme

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

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 how to validate a JSON Web Token (JWT) in different contexts using C# in .NET.

**JSON Web Tokens (JWTs)** have become very popular. Many developers use them in their applications for authentication and authorization purposes, but not all of them really know why and how to validate their JWTs.

This article will explain why you need to validate a JWT, what it means in general, and give you an overview of the many ways you can do it in the .NET platform.

## What Are JWTs?

If you landed on this article, you probably know what a JSON Web Token is. If not, [here is a great introduction to JWTs](https://jwt.io/introduction) and [a tool to decode them](https://jwt.io/#debugger-io).

Simply put, JSON Web Token is an [open standard](https://datatracker.ietf.org/doc/html/rfc7519) that defines how to share information between parties using the [JSON format](https://datatracker.ietf.org/doc/html/rfc8259). The [JWT structure](https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-token-structure) consists of three concatenated Base64 url-encoded strings, separated by dots: the header, the payload, and the signature The information carried by a JWT is **digitally signed so you can verify its origin and trust it**. The digital signature also guarantees the integrity of the information, but it doesn't guarantee privacy unless explicitly encrypted.

Besides this, the JWT specification doesn't define the specific purpose of a token. While most developers think of authentication when dealing with JWTs, this is not an intrinsic property of tokens in the JWT format. JWT is just a format. The meaning of the token depends on the specific context or application.

For example, in the [OpenID Connect](https://openid.net/developers/how-connect-works/) (OIDC) context, the JWT format is used for the ID token, which is the token that proves a user is authenticated. In the [OAuth 2.0](https://auth0.com/docs/authenticate/protocols/oauth) context, the [JWT format can optionally be used for the access token](https://datatracker.ietf.org/doc/html/rfc9068), which is the token that allows a client application to access a specific resource on behalf of the user.

> To learn more about ID and access tokens and their differences, you can read [this blog post](https://auth0.com/blog/id-token-access-token-what-is-the-difference/) or watch [this video](https://www.youtube.com/watch?v=vVM1Tpu9QB4) instead.

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

## What Does Token Validation Mean?

The main purpose of a JWT is to carry information that the recipient can trust. So, the first thing your application needs to do when it receives a JWT is to ensure that the information it carries is trustworthy. This is where validation comes in.

In short, validating a JSON Web Token means ensuring that the token has the structure defined in the standard specification and that you can trust the information it carries.

The JWT validation is based on the following five criteria:

- **Token structure**. The first check is about the token's structure. Does the token match the structure of a JSON Web Token? If the token doesn't follow the standard guidelines, it's not valid.

- **Token integrity**. The next check is for the token's integrity. Has the token been tampered with? You can verify this by checking the signature. If you verify that the token's signature is valid, then it has not been altered in any way.
- **Token expiration**. JWTs have an expiration time defined in the `exp` claim. Is the token expired when it has been received? If a token has expired, you should no longer trust its contents.
- **Expected authority**. The next check is to verify that the token was issued and signed by the expected sender (authority). There are two steps to this check:
  - Verify that the authority is the one expected by your application by comparing it to the `iss` claim (issuer).
  - Verify that the key used to sign the JWT actually belongs to the expected authority.
- **Expected audience**. Finally,  verify that the token is intended for your application. In other words, you should check that the `aud` claim matches with the value that identifies your application. For example, in an ID token, the value for the audience is the client ID; in an access token in JWT format, the value for the audience is the [API identifier](https://auth0.com/docs/get-started/apis/api-settings#general-settings).

> To learn more about [digital signatures, read this article](https://auth0.com/blog/how-to-explain-public-key-cryptography-digital-signatures-to-anyone/). Check out [this article](https://auth0.com/blog/rs256-vs-hs256-whats-the-difference/) for the differences between the signing algorithms used in a JWT.

Token validation doesn't involve the custom information carried by the token. This is an application-specific logic, which is out of the scope of token validation. For example, validating an ID token does not include verifying that the user's email address in the `email` claim exists.

## Validate a JWT Using an Auth0 SDK

Now that you know what validating a JWT means, you are ready to learn how to validate your tokens in .NET.

Before jumping into the validation code, you should evaluate whether you really need to explicitly validate the JWTs you receive from an issuer like Auth0. Depending on the specific application, you may want to use an Auth0 SDK, which will take care of all the validation steps for you. For example, if you are developing an ASP.NET Core MVC application or a Blazor Server application, you can use the [Auth0 ASP.NET Core Authentication SDK](https://github.com/auth0/auth0-aspnetcore-authentication). This SDK will take care of the entire process of obtaining the JWT tokens for your application, including token validation. Check out [this article](https://auth0.com/blog/exploring-auth0-aspnet-core-authentication-sdk/) for an overview of this specific SDK.

So, if your application can benefit from an SDK, the best move is to write less code and get the JWT validation for free. Take a look at [this article to learn which Auth0 SDK is right for your .NET application type](https://auth0.com/blog/choose-the-right-dotnet-sdk-for-auth0/). 

## Using the ASP.NET Core Middleware

If, for some reason, you can't use an Auth0 SDK, you can configure your ASP.NET Core application by using two middleware:

- The [OpenIdConnect middleware](https://www.nuget.org/packages/Microsoft.AspNetCore.Authentication.OpenIdConnect), which allows your ASP.NET Core web applications to authenticate users and get ID and access tokens via [OpenId Connect](https://openid.net/developers/how-connect-works/).
- The [JwtBearer middleware](https://www.nuget.org/packages/Microsoft.AspNetCore.Authentication.JwtBearer), which enables your ASP.NET Core web API to handle access tokens.

Both middleware provide you with a convenient way to obtain and validate JWT tokens. The following code snippet shows an example of how to configure OpenIdConnect middleware:

```csharp
// Program.cs

var builder = WebApplication.CreateBuilder(args);


builder.Services.AddAuthentication(options => {
    options.DefaultAuthenticateScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultSignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = CookieAuthenticationDefaults.AuthenticationScheme;
  })
  .AddCookie()
  .AddOpenIdConnect("Auth0", options => {
    options.Authority = $"https://{builder.Configuration["Auth0:Domain"]}";
    options.ClientId = builder.Configuration["Auth0:ClientId"];
    options.CallbackPath = new PathString("/callback");
  });

// ...other code...
```

The next example shows how to use the JwtBearer middleware:

```csharp
// Program.cs

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
  .AddJwtBearer(JwtBearerDefaults.AuthenticationScheme, options =>
  {
    options.Authority = $"https://{builder.Configuration["Auth0:Domain"]}";
    options.Audience = builder.Configuration["Auth0:Audience"];
  });

// ...other code...
```

In both cases, by configuring the `Authority` option, you implicitly ask the middleware to validate your tokens. The middleware will use this value to retrieve the issuer's signing key, which is needed to validate the token's signature. All the other required validation steps are performed automatically. There is nothing else you need to do.

### Simplified configuration for the JwtBearer middleware

Starting with .NET 7, you can [use the JwtBearer middleware in a simplified way](https://auth0.com/blog/whats-new-in-dotnet-7-for-authentication-and-authorization/#Simplified-Configuration). You define your validation values in the `appsettings.json` file, as in the following example:

```json
// appsettings.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Authentication": {
    "Schemes": {
      "Bearer": {
        "Authority": "https://{DOMAIN}",
        "ValidAudiences": [ "{AUDIENCE}" ],
        "ValidIssuer": "{DOMAIN}"
      }
    }
  }
}
```

Then you can simply add the middleware to your ASP.NET Core application, as follows:

```csharp
// Program.cs

// ...existing code...

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication().AddJwtBearer();

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

The behavior is exactly the same as before but with much less code.

### Custom validation with the ASP.NET Core middleware

If you have specific needs, you can customize the JWT validation using the `TokenValidationParameters` option. For example, if you already have the issuer's public key stored on your file system, you can configure your middleware as shown in the following example:

```csharp
// Program.cs

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
  .AddJwtBearer(JwtBearerDefaults.AuthenticationScheme, options =>
  {
    options.Audience = builder.Configuration["Auth0:Audience"];
    options.TokenValidationParameters = 
      new Microsoft.IdentityModel.Tokens.TokenValidationParameters
      {
        ValidateIssuer = true,
        ValidIssuer = $"{builder.Configuration["Auth0:Domain"]}",
        ValidateIssuerSigningKey = true,
        IssuerSigningKey = new X509SecurityKey(new X509Certificate2(certificateFilePath)),
        ValidateLifetime = true
      };
  });

// ...other code...
```

You can see that the `Audience` option is still there while the `Authority` option is missing. Instead of the `Authority` option, you find the `TokenValidationParameters` option, which is assigned an instance of the `TokenValidationParameters` class. The properties of this instance define what to check in order to complete the JWT validation. Specifically, you ask to validate the issuer (`ValidateIssuer`) and provide the value to match with (`ValidIssuer`). You ask to validate the issuer's signature (`ValidateIssuerSigningKey`) and provide the issuer's public signing key (`IssuerSigningKey`) embedded in a certificate stored in the file system. And finally, you ask to check the expiration time (`ValidateLifetime`).

You can see how removing the `Authority` option from the middleware configuration forces you to manually specify what to check in order to validate the token.

## Validate a JWT “By Hand”

In case you can't use the ASP.NET Core middleware, for example, when you are not developing a web application, don't get desperate. .NET gives you what you need, although this requires some effort on your side.

### Validate your token

First, you need to install the `Microsoft.IdentityModel.Tokens` package from NuGet:

```bash
dotnet add package Microsoft.IdentityModel.Tokens
```

This package provides everything you need for token manipulation, including validation, of course.

Have a look at the following function:

```csharp
public bool ValidateToken(
  string token, 
  string issuer, 
  string audience, 
  ICollection<SecurityKey> signingKeys,
  out JwtSecurityToken jwt
)
{
  var validationParameters = new TokenValidationParameters {
          ValidateIssuer = true,
          ValidIssuer = issuer,
          ValidateAudience = true,
          ValidAudience = audience
          ValidateIssuerSigningKey = true,
          IssuerSigningKeys = signingKeys,
          ValidateLifetime = true
  };

  try
  {
    var tokenHandler = new JwtSecurityTokenHandler();
    tokenHandler.ValidateToken(token, validationParameters, out SecurityToken validatedToken);
    jwt = (JwtSecurityToken)validatedToken;
    
    return true;
  } catch (SecurityTokenValidationException ex) {
    // Log the reason why the token is not valid
    return false
  }
}
```

This function takes a token and validates it by using the other parameters: the issuer, the audience, and the signing keys. If the token is valid, it returns `true` and provides a `JwtSecurityToken` instance representing the token as the `jwt` output parameter.

Once again, you see the `TokenValidationParameters` class, which allows you to define the validation criteria. This time there is no implicit validation. You need to specify all the required validation criteria and the valid values. Then you create a token handler (`JwtSecurityTokenHandler`) and use it to validate the token against the validation parameters. If the validation succeeds, you get an object representing the token, which you assign to the output parameter after casting to `JwtSecurityToken`. Finally, the function returns `true`.

If the validation fails, it should log the reason for the failed validation and return `false`.

### Get the signing keys

The `ValidateToken()` function expects you to pass the basic information for the token validation: the token issuer identifier, the audience, and the issuer's signing keys. You may have all this information on hand or need to retrieve some of it. For example, you can obtain the signing key of the issuer online. According to the [OIDC standard](https://openid.net/specs/openid-connect-discovery-1_0.html), you can find the set of keys (*JSON Web Key Sets*) to verify the issuer's signatures at a public and well-defined URL: `https://{DOMAIN}/.well-known/openid-configuration`.

Read [this document to learn more about the JSON Web Key Sets](https://auth0.com/docs/secure/tokens/json-web-tokens/locate-json-web-key-sets).

To validate a JWT using the `ValidateToken()` function, you must first retrieve the signing key from this URL. As you can see, things start to get complex. This is why I suggest using an Auth0 SDK in the first place, or at least the ASP.NET Core middleware, if possible.

However, if using one of these tools is not feasible in your specific case, here is what you need to do to get the issuer's signing keys.

First, you need to install another package from NuGet: the `Microsoft.IdentityModel.Protocols.OpenIdConnect` package:

```bash
dotnet add package Microsoft.IdentityModel.Protocols.OpenIdConnect
```

This package provides you with the `ConfigurationManager` class, which helps you retrieve the JSON Web Key Sets. The following code shows you how to obtain the signing key of your JWT issuer:

```csharp
var configurationManager = new ConfigurationManager<OpenIdConnectConfiguration>(
  $"https://{builder.Configuration["Auth0:Domain"]/.well-known/openid-configuration}",
  new OpenIdConnectConfigurationRetriever(),
  new HttpDocumentRetriever());

  var discoveryDocument = await configurationManager.GetConfigurationAsync();
  var signingKeys = discoveryDocument.SigningKeys;
```

Once you have the signing keys, you are ready to use the `ValidateToken()` function.

## Recap

Throughout this article, you have learned what JWT validation is and why you need to do it. You also learned that as a .NET developer, you have many options for validating the JWTs your application receives: from a zero-code approach to an almost manual validation.

With the Auth0 SDKs, you get the JWT validation for free. No specific code is required. The SDKs validate tokens for you.

Using the ASP.NET Core middleware, OpenIdConnect and JwtBearer, you get implicit token validation in the default cases. However, you can customize your validation criteria if you are dealing with special cases.

In case you need full control over the validation process, you can rely on the `Microsoft.IdentityModel.Tokens` package for the JWT manipulation and validation and on the `Microsoft.IdentityModel.Protocols.OpenIdConnect` package for retrieving the issuer's signing keys.

Of course, the suggestion is to delegate as much as possible to the SDKs and middleware because the less code you write, the fewer bugs you may create 🙂.


How to Validate JWTs in .NET

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

Use Refresh Tokens in ASP.NET Core Apps

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

Call Protected APIs in ASP.NET Core

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?

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

randy_nasson

Director of Product Management for Customer Identity Cloud (formerly Auth0) in our Identity and Access Management (IAM) domain. I joined Auth0 in 2018 and assembled a world-class IAM product team dedicated to delivering customer value and enabling developers to quickly implement secure, robust, and seamless identity solutions. In addition to my current work with CIC, I regularly work with our Auth0 Lab team on greenfield initiatives and with our Strategic and Technical Partner teams on opportunities to drive revenue.

Director, Product Management (IAM)

Randy Nasson

Delight users while providing a secure CIAM solution for accessing applications and services



## Summary

* Refresh tokens [can be effectively used for maintaining a seamless user experience](https://auth0.com/blog/securing-single-page-applications-with-refresh-token-rotation/) in browser-based apps without suffering the limitations imposed by ITP2
* Configuring absolute lifetimes for refresh tokens helps reduce the risk of using RTs in single-page applications
* Inactivity lifetime enables refresh token lifetimes to be extended as long as the end-user interacts with the client within the configured period, resulting in less end-user friction
* **Auth0 now provides both absolute and inactivity lifetimes for refresh tokens, along with more secure refresh token defaults, as of December 16, 2020**
<br /><br />

## Balancing Security and User Experience

Most businesses want to afford a friction-free experience for end-users when using their applications. Requiring people to manually enter credentials every time they visit a commerce site or open an app can yield frustration and hurt the business bottom line. A common request in business-to-consumer (B2C) industries is to only require users to log in once and then to never require them to log in again unless they are explicitly logged out, either by choice or necessity.

The practice of using long-lived [refresh tokens](https://auth0.com/blog/refresh-tokens-what-are-they-and-when-to-use-them/) paired with short-lived Access Tokens is a common solution to delivering an uninterrupted experience, particularly in native mobile apps. With additional security capabilities such as [Refresh Token Rotation](https://auth0.com/blog/securing-single-page-applications-with-refresh-token-rotation/) and [Automatic Reuse Detection](https://auth0.com/blog/securing-single-page-applications-with-refresh-token-rotation/#Automatic-Reuse-Detection), refresh tokens can safely be used in Single Page Applications (SPAs) to afford continuous access on the web.

![Refresh Token](https://images.ctfassets.net/23aumh6u8s0i/6lBzS4ElN5ZEULvNM50Hvi/1a84f912b03d26661286ec71b4016f71/01-image-refresh-token)

## Refresh Token Expiration

However, a refresh token is considered a powerful artifact in identity management. If a refresh token is leaked or stolen, it could be used to acquire a new Access Token. As such, the [OAuth 2.0 Best Current Practices (BCP)](https://tools.ietf.org/html/draft-ietf-oauth-security-topics-14#section-4.12.2) states that refresh tokens **should** expire if the application (client) is inactive for too long, particularly when used in Public Clients (a client that cannot secure its own credentials, such as a native mobile app). This means that refresh tokens should expire at some point in time, but that expiration can be based on activity and not merely an arbitrary point in the future.

When the refresh token expires, it can no longer be used to get a new Access Token. The user will be required to re-authenticate the next time they use the application. More importantly, an attacker’s window for using a leaked token is limited. 

But, what about the business desire for only wanting the end-user to log in once and not again thereafter? For SPAs, this can still be afforded within the OAuth 2.0 BCP guidance provided that the end-user’s activity in the application remains consistent.

Let’s consider an example: A media company publishes content on a regular basis that is only available to authenticated subscribers. In addition, the company sells subscriptions and related goods (books, print media, access to premium video content, etc.) using stored payment methods associated with the account. 

In this scenario, the website is a SPA with Auth0 as the authorization server, and refresh tokens are used to overcome the session limitations incurred by ITP2 or similar privacy mechanisms. Because there is sensitive information in the account, maintaining an indefinite application session is not ideal.

Leveraging absolute lifetimes, end-users can be required to log in again after a predetermined period of time. But that experience is not optimal for the business or the end-user. Requiring re-authentication creates friction between the user and the content or purchases. What if the user could remain logged in as long as they were active in the application on a regular basis, for example, once every two weeks?

## Introducing Inactivity Lifetime

Unlike absolute lifetime, which expires a refresh token after a fixed period, inactivity lifetime extends the expiration period each time the client uses a refresh token to get a new access token. Using the example above, this effectively preserves the seamless user experience as long as there is an activity within the inactivity lifetime.

![Introducing Inactivity Lifetime](https://images.ctfassets.net/23aumh6u8s0i/6vutURQweArCulYsO5eBvL/f54e0ef9f358058bde3b185c474ab814/04-at-expiration-1-day-flow)

As of today, both absolute and inactivity lifetimes for refresh tokens are available for all Auth0 customers hosted in our cloud environment and will be available in December 2020 for private cloud customers. This enables you to configure refresh token lifetimes based on your own app usage data, for example, by evaluating your application log data to determine how often users return to your app so that people who use applications regularly can have that period extended as long as usage remains consistent. 

Auth0 makes it easy to configure refresh token lifetimes using the [Auth0 Management API](https://auth0.com/docs/api/management/v2#!/Clients/post_clients), our [Deploy CLI](https://auth0.com/docs/extensions/deploy-cli-tool), or the Auth0 Dashboard.

![Auth0 Management API](https://images.ctfassets.net/23aumh6u8s0i/4P5VvuP2z41wvUoBDlRzvH/840a1ebbbf639eb0827ad62b4ab645c2/05-refresh-token-expiration)

Inactivity lifetime can be used in all supported refresh token flows and in conjunction with Refresh Token Rotation.

## Using Inactivity and Absolute Lifetimes Together

Both inactivity and absolute lifetimes can be configured on a per-application basis, enabling you to craft experiences to suit the expected usage of your applications.

Setting absolute lifetimes for refresh tokens ensures that refresh tokens cannot be used to retrieve a new access token after the specified period. For example, if you set the absolute lifetime to 30 days, the refresh token issued to the application can be used for up to 30 days from its issuance to retrieve a new access token. If you are leveraging Refresh Token Rotation, the absolute lifetime [applies to the entire token family](https://auth0.com/docs/tokens/refresh-tokens/refresh-token-rotation#automatic-reuse-detection). After the lifetime expires, the user will be required to re-authenticate.

You can also use a combination of absolute and inactivity lifetimes to afford an uninterrupted user experience for much longer durations, provided that the user remains active within the inactivity lifetime. For example, you can set the absolute lifetime to 365 days and the inactivity lifetime to 14 days. This would allow a user who was active in your application at least once every two weeks to continuously stay logged in until the absolute lifetime expires.

You can also use an inactivity lifetime _without_ an absolute lifetime in a similar manner to achieve the effect of never having to log in again as long as the user remains active within the inactivity lifetime (and the user never explicitly logs out).

![Auth0 Management API](https://images.ctfassets.net/23aumh6u8s0i/1og3ppkzZWZlMEXh1NNqLM/c2f2998f7509d6568fd87ca40622fdcf/06-refresh-token-expiration-2)

## Guidance & Defaults

As part of Auth0’s continued commitment to securing applications and protected resources, we’ve updated default refresh token settings for new applications as follows.

### Confidential Clients

Confidential clients, such as machine-to-machine applications or traditional web applications that can securely store client credentials and can, therefore, prove that requests are coming from the client and not an illegitimate actor. As such, when refresh tokens are enabled, for confidential clients, default settings are optimized for convenience as follows: 

![Confidential Clients](https://images.ctfassets.net/23aumh6u8s0i/3ZABGcvqKpo7NIanSD1v4e/c83ca317f6483ccae212a9ac2db827fb/07-confidential-clients)

### Public Clients (Native Apps)

Because Public Clients, such as native mobile applications, cannot securely store client credentials and are susceptible to other attack vectors when refresh tokens are enabled for public clients, the default settings are optimized for security, as follows: 

![Public Clients](https://images.ctfassets.net/23aumh6u8s0i/5sUFHqXRJ1OQZnb4MvMOMu/62b5e02b574bbe4c1b74cfee434d628e/08-public-clients)

### SPAs

Until recently, refresh tokens were not recommended for use with SPAs because browsers are more vulnerable to token leakage than native applications. Leveraging Refresh Token Rotation, the risk of using refresh tokens in SPAs is lowered. Nevertheless, Auth0 recommends that SPAs use refresh tokens with Absolute lifetimes specified and sets the following defaults when refresh tokens are enabled for SPAs:

![SPAs](https://images.ctfassets.net/23aumh6u8s0i/1S9d6u2w8dgSZ4D3cEpwIa/b0d00b921376cf6ec28bb86ac5f95145/09-spas)

## Let’s Get Started

As of December 16, 2020, both absolute and inactivity lifetimes for refresh tokens are available for all Auth0 customers hosted in our cloud environment and will be available in December 2020 for private cloud customers. You can read more about refresh token expiration, absolute lifetimes, and inactivity lifetimes and how to configure them for use in your applications in the [Auth0 documentation](https://auth0.com/docs/tokens/refresh-tokens/configure-refresh-token-expiration). We hope that you find this new capability helpful for balancing user experience with added security.

Secure the applications that you care about. But do it in a way that delights the people who use them.


Achieving a Seamless User Experience with Refresh Token Inactivity Lifetimes

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

dfea5c5f769cc4a6cce74d3eda20bba3?size=200 avatar

dfea5c5f769cc4a6cce74d3eda20bba3?size=200

Guest Author

Tim McLean

Which libraries are vulnerable to attacks and how to prevent them.



**TL;DR:** If you are using [node-jsonwebtoken](https://github.com/auth0/node-jsonwebtoken), [pyjwt](https://github.com/jpadilla/pyjwt/), [namshi/jose](https://github.com/namshi/jose), [php-jwt](https://github.com/firebase/php-jwt) or [jsjwt](https://github.com/kjur/jsjws) with asymmetric keys (RS256, RS384, RS512, ES256, ES384, ES512) please update to the latest version. See [jwt.io](http://jwt.io) for more information on the vulnerable libraries. *(Updated 2015-04-20)*

> This is a guest post from Tim McLean, who is a member of the [Auth0 Security Researcher Hall of Fame](https://auth0.com/whitehat#hall-of-fame). Tim normally blogs at [www.timmclean.net](https://www.timmclean.net).

Recently, while reviewing the security of various JSON Web Token implementations, I found many libraries with critical vulnerabilities allowing attackers to bypass the verification step.  The same two flaws were found across many implementations and languages, so I thought it would be helpful to write up exactly where the problems occur.  I believe that a change to the standard could help prevent future vulnerabilities.

<include src="TweetQuote" quoteText="I found many libraries with critical vulnerabilities allowing attackers to bypass the verification step."/>

For those who are unfamiliar, [JSON Web Token (JWT)](https://auth0.com/learn/json-web-tokens/) is a standard for creating tokens that assert some number of claims.  For example, a server could generate a token that has the claim "logged in as admin" and provide that to a client. The client could then use that token to prove that they are logged in as admin. The tokens are signed by the server's key, so the server is able to verify that the token is legitimate.

JWTs generally have three parts: a header, a payload, and a signature.

The header identifies which algorithm is used to generate the signature, and looks something like this:

``` javascript  
header = '{"alg":"HS256","typ":"JWT"}'
```

`HS256` indicates that this token is signed using HMAC-SHA256.

The payload contains the claims that we wish to make:

``` javascript  
payload = '{"loggedInAs":"admin","iat":1422779638}'
```

As suggested in the JWT spec, we include a timestamp called `iat`, short for "issued at".

The signature is calculated by base64url encoding the header and payload and concatenating them with a period as a separator:

``` javascript  
key = 'secretkey'
unsignedToken = encodeBase64(header) + '.' + encodeBase64(payload)
signature = HMAC-SHA256(key, unsignedToken)
```

To put it all together, we base64url encode the signature, and join together the three parts using periods:

``` javascript  
token = encodeBase64(header) + '.' + encodeBase64(payload) + '.' + encodeBase64(signature)

# token is now:
# eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsb2dnZWRJbkFzIjoiYWRtaW4iLCJpYXQiOjE0MjI3Nzk2Mzh9.gzSraSYS8EXBxLN_oWnFSRgCzcmJmMjLiuyu5CSpyHI
```

To learn more about JSON Web Tokens, check out our free ebook below.

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

## Great. So, What's Wrong with That?

Well, let's try to verify a token.

First, we need to determine what algorithm was used to generate the signature. No problem, there's an `alg` field in the header that tells us just that.

But wait, we haven't validated this token yet, which means that we haven't validated the header.  This puts us in an awkward position: in order to validate the token, we have to allow attackers to select which method we use to verify the signature.

This has disastrous implications for some implementations.

## Meet the "None" Algorithm


The `none` algorithm is a curious addition to JWT.  It is intended to be used for situations where the integrity of the token has already been verified. Interestingly enough, it is one of only two algorithms that are mandatory to implement (the other being `HS256`).

Unfortunately, some libraries treated tokens signed with the `none` algorithm as a valid token with a verified signature.  The result?  Anyone can create their own "signed" tokens with whatever payload they want, allowing arbitrary account access on some systems.

Putting together such a token is easy. Modify the above example header to contain `"alg": "none"` instead of `HS256`.  Make any desired changes to the payload.  Use an empty signature (i.e. `signature = ""`).

Most (hopefully all?) implementations now have a basic check to prevent this attack: if a secret key was provided, then token verification will fail for tokens using the `none` algorithm.  This is a good idea, but it doesn't solve the underlying problem: attackers control the choice of algorithm.  Let's keep digging.

## RSA or HMAC?

The JWT spec also defines a number of asymmetric signing algorithms (based on RSA and ECDSA).  With these algorithms, tokens are created and signed using a private key but verified using a corresponding public key.  This is pretty neat: if you publish the public key but keep the private key to yourself, only you can sign tokens, but anyone can check if a given token is correctly signed.

Most of the JWT libraries that I've looked at have an API like this:

``` javascript  
# sometimes called "decode"
verify(string token, string verificationKey)
# returns payload if valid token, else throws an error
```

In systems using HMAC signatures, `verificationKey` will be the server's secret signing key (since HMAC uses the same key for signing and verifying):

``` javascript  
verify(clientToken, serverHMACSecretKey)
```

In systems using an asymmetric algorithm, `verificationKey` will be the public key against which the token should be verified:

``` javascript  
verify(clientToken, serverRSAPublicKey)
```

Unfortunately, an attacker can abuse this.  If a server is expecting a token signed with RSA, but actually receives a token signed with HMAC, **it will think the public key is actually an HMAC secret key**.

How is this a disaster?  HMAC secret keys are supposed to be kept private, while public keys are, well, public.  This means that your typical [ski mask-wearing attacker](https://i.imgur.com/18fM5ja.jpg) has access to the public key, and can use this to forge a token that the server will accept.

Doing so is pretty straightforward.  First, grab your favorite JWT library, and choose a payload for your token.  Then, get the public key used on the server as a verification key (most likely in the text-based PEM format). Finally, sign your token using the PEM-formatted public key as an HMAC key. Essentially:

``` javascript  
forgedToken = sign(tokenPayload, 'HS256', serverRSAPublicKey)
```

The trickiest part is making sure that `serverRSAPublicKey` is identical to the verification key used on the server.  The strings must match exactly for the attack to work -- exact same format, and no extra or missing line breaks.

End result?  Anyone with knowledge of the public key can forge tokens that will pass verification.

## Recommendations for Library Developers

I suggest that JWT libraries add an `algorithm` parameter to their verification function:

``` javascript  
verify(string token, string algorithm, string verificationKey)
```

The server should already know what algorithm it uses to sign tokens, and it's not safe to allow attackers to provide this value.

Some might argue that some servers need to support more than one algorithm for compatibility reasons.  In this case, a separate key can (and should) be used for each supported algorithm.  JWT conveniently provides a "key ID" field (`kid`) for exactly this purpose.  Since servers can use the key ID to look up the key and its corresponding algorithm, attackers are no longer able to
control the manner in which a key is used for verification.  In any case, I don't think JWT libraries should even look at the `alg` field in the header, except maybe to check that it matches what the expected algorithm was.

Anyone using a JWT implementation should make sure that tokens with a different signature type are guaranteed to be rejected.  Some libraries have an optional mechanism for whitelisting or blacklisting algorithms; take advantage of it, or you might end up at risk.  Even better: have a policy of performing security audits on any open source libraries that you use to provide mission-critical functionality.

## Improving the JWT/JWS Standard

I would like to propose deprecating the header's `alg` field.  As we've seen here, its misuse can have a devastating impact on the security of a JWT/JWS implementation.  As far as I can tell, key IDs provide an adequate alternative. This warrants a change to the spec: JWT libraries continue to be written with security flaws due to their dependence on `alg`.

JWT (and JOSE) present the opportunity to have a cross-platform suite of secure cryptography implementations.  With these fixes, hopefully, we're a little bit closer to making that a reality.

<include src="asides/Jwt" />


Critical vulnerabilities in JSON Web Token libraries

0b3b0a5bf530f8c3a1fdee5233979c81?s=200 avatar

0b3b0a5bf530f8c3a1fdee5233979c81?s=200

Director, Engineering

Shawn Meyer

Learn how to start using RS256 for signing and verifying your JWTs.



## TL;DR:

When signing your JWTs it is better to use an asymmetric signing algorithm.  Doing so will no longer require sharing a private key across many applications. Using an algorithm like RS256 and the JWKS endpoint allows your applications to trust the JWTs signed by Auth0.

The code snippets below have been adapted from Auth0's [node-jwks-rsa](https://github.com/auth0/node-jwks-rsa) and [express-jwt](https://github.com/auth0/express-jwt).

Check out the sample [repository](https://github.com/sgmeyer/auth0-node-jwks-rs256).

> [Auth0 offers a generous **free tier**](https://auth0.com/pricing) to get started with modern authentication.

## RS256 vs HS256

 When creating clients and resources servers (APIs) in Auth0, two algorithms are supported for signing JSON Web Tokens (JWTs): RS256 and HS256.  HS256 is the default for clients and RS256 is the default for APIs.  When building applications, it is important to understand the differences between these two algorithms.  To begin, HS256 generates a symmetric MAC and RS256 generates an asymmetric signature.  Simply put HS256 must share a secret with any client or API that wants to verify the JWT.  Like any other symmetric algorithm, the same secret is used for both signing and verifying the JWT.  This means there is no way to fully guarantee Auth0 generated the JWT as any client or API with the secret could generate a validly signed JWT.  On the other hand, RS256 generates an asymmetric signature, which means a private key must be used to sign the JWT and a different public key must be used to verify the signature.  Unlike symmetric algorithms, using RS256 offers assurances that Auth0 is the signer of a JWT since Auth0 is the only party with the private key.

## Verifying RS256

Due to the symmetric nature of HS256, we favor the use of RS256 for signing your JWTs, especially for APIs with 3rd party clients.  However, this decision comes with some extra steps for verifying the signature of your JWTs.  Auth0 uses the [JWK](https://tools.ietf.org/html/rfc7517) specification to represent the cryptographic keys used for signing or verifying tokens.  This spec defines two high level data structures: JWKS and JWK.  Here are the definitions directly from the specification:

> JSON Web Key (JWK)
>
> A JSON object that represents a cryptographic key.  The members of the object represent properties of the key, including its value.

> JWK Set
>
> A JSON object that represents a set of JWKs.  The JSON object MUST have a "keys" member, which is an array of JWKs.

At the most basic level, the JWKS is a set of keys containing the public keys that should be used to verify any JWT issued by the authorization server.  Auth0 exposes a JWKS endpoint for each tenant, which is found at _https://your-tenant.auth0.com/.well-known/jwks.json_.  This endpoint will contain the JWK used to sign all Auth0 issued JWTs for this tenant.  Here is an example of the JWKS used by a demo tenant.

```
{
"keys": [
  {
    "alg": "RS256",
    "kty": "RSA",
    "use": "sig",
    "x5c": [
      "MIIC+DCCAeCgAwIBAgIJBIGjYW6hFpn2MA0GCSqGSIb3DQEBBQUAMCMxITAfBgNVBAMTGGN1c3RvbWVyLWRlbW9zLmF1dGgwLmNvbTAeFw0xNjExMjIyMjIyMDVaFw0zMDA4MDEyMjIyMDVaMCMxITAfBgNVBAMTGGN1c3RvbWVyLWRlbW9zLmF1dGgwLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMnjZc5bm/eGIHq09N9HKHahM7Y31P0ul+A2wwP4lSpIwFrWHzxw88/7Dwk9QMc+orGXX95R6av4GF+Es/nG3uK45ooMVMa/hYCh0Mtx3gnSuoTavQEkLzCvSwTqVwzZ+5noukWVqJuMKNwjL77GNcPLY7Xy2/skMCT5bR8UoWaufooQvYq6SyPcRAU4BtdquZRiBT4U5f+4pwNTxSvey7ki50yc1tG49Per/0zA4O6Tlpv8x7Red6m1bCNHt7+Z5nSl3RX/QYyAEUX1a28VcYmR41Osy+o2OUCXYdUAphDaHo4/8rbKTJhlu8jEcc1KoMXAKjgaVZtG/v5ltx6AXY0CAwEAAaMvMC0wDAYDVR0TBAUwAwEB/zAdBgNVHQ4EFgQUQxFG602h1cG+pnyvJoy9pGJJoCswDQYJKoZIhvcNAQEFBQADggEBAGvtCbzGNBUJPLICth3mLsX0Z4z8T8iu4tyoiuAshP/Ry/ZBnFnXmhD8vwgMZ2lTgUWwlrvlgN+fAtYKnwFO2G3BOCFw96Nm8So9sjTda9CCZ3dhoH57F/hVMBB0K6xhklAc0b5ZxUpCIN92v/w+xZoz1XQBHe8ZbRHaP1HpRM4M7DJk2G5cgUCyu3UBvYS41sHvzrxQ3z7vIePRA4WF4bEkfX12gvny0RsPkrbVMXX1Rj9t6V7QXrbPYBAO+43JvDGYawxYVvLhz+BJ45x50GFQmHszfY3BR9TPK8xmMmQwtIvLu1PMttNCs7niCYkSiUv2sc2mlq1i3IashGkkgmo="
    ],
    "n": "yeNlzlub94YgerT030codqEztjfU_S6X4DbDA_iVKkjAWtYfPHDzz_sPCT1Axz6isZdf3lHpq_gYX4Sz-cbe4rjmigxUxr-FgKHQy3HeCdK6hNq9ASQvMK9LBOpXDNn7mei6RZWom4wo3CMvvsY1w8tjtfLb-yQwJPltHxShZq5-ihC9irpLI9xEBTgG12q5lGIFPhTl_7inA1PFK97LuSLnTJzW0bj096v_TMDg7pOWm_zHtF53qbVsI0e3v5nmdKXdFf9BjIARRfVrbxVxiZHjU6zL6jY5QJdh1QCmENoejj_ytspMmGW7yMRxzUqgxcAqOBpVm0b-_mW3HoBdjQ",
    "e": "AQAB",
    "kid": "NjVBRjY5MDlCMUIwNzU4RTA2QzZFMDQ4QzQ2MDAyQjVDNjk1RTM2Qg",
    "x5t": "NjVBRjY5MDlCMUIwNzU4RTA2QzZFMDQ4QzQ2MDAyQjVDNjk1RTM2Qg"
  }
]}
```

**Note:** At the time of writing, Auth0 only supports a single JWK for token verification, however it is important to assume this endpoint could contain multiple JWKs.  As an example, multiple keys can be found in the JWKS when rotating signing certificates.

The JWKS above contains a single key.  Each property in the key is defined by the JWK specification [RFC 7517 Section 4](https://tools.ietf.org/html/rfc7517#section-4).  We will use these properties to determine which key was used to sign the JWT.  Here is a quick breakdown of what each property represents:

* **alg:** is the algorithm for the key
* **kty:** is the key type
* **use:** is how the key was meant to be used.  For the example above, `sig` represents signature verification.
* **x5c:** is the x509 certificate chain
* **e:**   is the exponent for a standard pem
* **n:**   is the moduluos for a standard pem
* **kid:** is the unique identifier for the key
* **x5t:** is the thumbprint of the x.509 cert (SHA-1 thumbprint)

## Verifying a JWT using the JWKS endpoint

Now that we understand JWKS and the specific properties of each JWK let's put this together and verify a JWT signed by Auth0 with RS256.  In our example we are going to build a first party API for our ficticious company c0der.io.  The API will have a single endpoint returning metadata about our API, which requires a valid JWT.  Ideally your resource server would also validate necessary scopes, however, that is beyond this topic.  We will assume an API and client have been created and we will focus on what happens once our API recieves a request.

**Here are the steps for validating the JWT:**

1. Retrieve the JWKS and filter for potential signature verification keys.
2. Extract the JWT from the request's authorization header.
3. Decode the JWT and grab the `kid` property from the header.
4. Find the signature verification key in the filtered JWKS with a matching `kid` property.
5. Using the `x5c` property build a certificate which will be used to verify the JWT signature.
6. Ensure the JWT contains the expected audience, issuer, expiration, etc.

> **Note:** There are many good libraries for verifying a JWT.  You can use the curated list to find one for your language at [JWT.io](https://jwt.io/#libraries-io).

Let's jump into some code and see this in action.

## Retrieving the JWK

The first thing we are going to do is grab the key set from the Auth0 JWKS endpoint.  Using `request` we can simply perform a `GET` to retrieve the JSON blob.

```javascript
/**
 * https://github.com/sgmeyer/auth0-node-jwks-rs256/blob/master/src/lib/JwksClient.js#L7-L28
 **/

export class JwksClient {
  constructor(options) {
    this.options = { strictSsl: true, ...options };
  }

  getJwks(cb) {
    request({
      uri: this.options.jwksUri,
      strictSsl: this.options.strictSsl,
      json: true
    }, (err, res) => {
      if (err || res.statusCode < 200 || res.statusCode >= 300) {
        if (res) {
          return cb(new JwksError(res.body && (res.body.message || res.body) || res.statusMessage || `Http Error ${res.statusCode}`));
        }
        return cb(err);
      }

      var jwks = res.body.keys;
      return cb(null, jwks);
    });
  }
}

```

After grabbing the JWKS we will filter out all the keys that are not intended for verifying a JWT.  This step may seem unneccessary as the Auth0 JWKS endpoint typically contains a single signature verification key, however it is good practice to assume multiple keys could be present (i.e. key rotation).

```javascript
export class JwksClient {
  constructor(options) { ... }

  getJwks(cb) { ... }

  /**
   * https://github.com/sgmeyer/auth0-node-jwks-rs256/blob/master/src/lib/JwksClient.js#L30-L58
   **/
  getSigningKeys(cb) {
    const callback = (err, keys) => {
      if (err) {
        return cb(err);
      }

      if (!keys || !keys.length) {
        return cb(new JwksError('The JWKS endpoint did not contain any keys'));
      }

      const signingKeys = keys
        .filter(key => key.use === 'sig' // JWK property `use` determines the JWK is for signature verification
                    && key.kty === 'RSA' // We are only supporting RSA (RS256)
                    && key.kid           // The `kid` must be present to be useful for later
                    && ((key.x5c && key.x5c.length) || (key.n && key.e)) // Has useful public keys
        ).map(key => {
          return { kid: key.kid, nbf: key.nbf, publicKey: certToPEM(key.x5c[0]) };
        });

      // If at least one signing key doesn't exist we have a problem... Kaboom.
      if (!signingKeys.length) {
        return cb(new JwksError('The JWKS endpoint did not contain any signature verification keys'));
      }

      // Returns all of the available signing keys.
      return cb(null, signingKeys);
    };

    this.getJwks(callback);
  }
}
```

Quick recap, we have retrieved the set of keys (JWKS) from Auth0 and we have filtered out all keys that are not intended for verifying a JWT with the keytype of RSA.  As an additional measure, we filtered out any key missing a public key and a `kid` property.  This step is important as later we will need to use the `kid` property to find the exact key necessary to verify the JWT.

## Finding the exact signature verification key

Continuing with our example, we will add an additional method to `JwksClient` called `getSigningKey` taking a key identifier (`kid`) as an argument and return the expected key (JWK) used to sign the JWT.   If a JWK is not found, then an error must be thrown.  This means the JWT supplied with the request was signed with a key that is not supported by Auth0.  This should ultimately be treated as a `401 Unauthorized`.  If a matching key is found, then that key will be passed as an argument to the callback.

```javascript
export class JwksClient {
  constructor(options) {
    this.options = { strictSsl: true, ...options };
  }

  getJwks(cb) { ... }

  getSigningKeys(cb) { ... }

  /**
   * https://github.com/sgmeyer/auth0-node-jwks-rs256/blob/master/src/lib/JwksClient.js#L67-L84
   **/
  getSigningKey = (kid, cb) => {
    const callback = (err, keys) => {
      if (err) {
        return cb(err);
      }

      const signingKey = keys.find(key => key.kid === kid);

      if (!signingKey) {
        var error = new SigningKeyNotFoundError(`Unable to find a signing key that matches '${kid}'`);
        return cb(error);
      }

      return cb(null, signingKey)
    };

    this.getSigningKeys(callback);
  }
```

So far we have built a client that can be used to retrieve the JWKS and find the signature verification key using the value of the `kid` property.  At this point, we have neither verified the JWT nor extracted it from the request.  

> **Note:** As an optimization for production it would be wise to implement a caching mechanism for the JWKS or keys so that each request does not require a call to the JWKS endpoint.

## Creating a Signing Secret Wrapper

Before we move on to processing the JWT we want to create a quick wrapper for the `JwksClient` that returns a method that will eventually hand off the key we need to verify the JWT.  This class is a bit specific to the node async model, however it is necessary for the final step when we tie together the final middleware.

```javascript
/**
 * https://github.com/sgmeyer/auth0-node-jwks-rs256/blob/master/src/lib/expressJwtSecret.js#L4-L38
 **/
const handleSigningKeyError = (err, cb) => {
  // If we didn't find a match, can't provide a key.
  if (err && err.name === 'SigningKeyNotFoundError') {
    return cb(null);
  }

  // Any other error we will bubble up.
  if (err) {
    return cb(err);
  }
};

export default (options) => {
  if (options === null || options === undefined) {
    throw new ArgumentError('An options object must be provided when initializing expressJwtSecret');
  }

  const client = new JwksClient(options);
  const onError = handleSigningKeyError;

  return function secretProvider(req, header, payload, cb) {
    // Only RS256 is supported.
    if (!header || header.alg !== 'RS256') {
      return cb(null, null);
    }

    client.getSigningKey(header.kid, (err, key) => {
      if (err) {
        return onError(err, (newError) => cb(newError, null));
      }

      // Provide the key.
      return cb(null, key.publicKey || key.rsaPublicKey);
    });
  };
};
```

## Grabbing the JWT from the Request

Now we need to move on to extract the JWT from the request.  Most APIs expect the JWT is sent as a [Bearer Token](https://tools.ietf.org/html/rfc6750) in the authorization header or as a URL parameter.  Now we are going to start building an Express middleware that will extract the JWT, create a signing secret, and verify the token using the `jsonwebtoken` module.  We will start by creating a file called `expressJWt.js` and extract the JWT from the request.

```javascript
export default (options) => {

  var middleware = (req, res, next) => {
    // https://github.com/sgmeyer/auth0-node-jwks-rs256/blob/master/src/middleware/expressJwt.js#L12-L23
    var authHeader = req.headers.authorization;
    var parts = authHeader.split(' ');

    if (parts.length != 2) {
      throw new UnauthorizedError('credentials_required', { message: 'No authorization token was found' });
    }

    var scheme = parts[0];
    if(!/^Bearer$/i.test(scheme)) {

      throw new UnauthorizedError('credentials_bad_scheme', { message: 'Format is Authorization: Bearer [token]' });
    }
  }

  return middleware;
}

```

> **Note:** It is important to differentiate between verifying and decoding a token.  Decoding simply means to base64url decode the header and payload.  This step is not concerned with validating the signature, audience, expiration, etc.  Verifying the token is the process of ensuring the token's signature, but also the audience, expiration, etc are valid.

At this point the middleware is pretty boring.  It simply parses the authorization header for the format `Authorization: Bearer [token]`.  If the authorization header doesn't exist, is empty, or does not fit the format the we will throw an `UnauthorizedError` which later is treated as a `401 Unauthorized` response.  If the header does meet the criteria the JWT is pulled from the authorization header.

## Decoding the JWT

Now that we have our hands on the JWT we need to decode the token.  This will be important later when we want to grab the `kid` property to find the key we need to verify the signature.  Recall we can decode the JWT as it is simply base 64 url encoded.  To do this we will use the `jsonwebtoken` node module.  If you are interested in learning more about how a JWT is constructed check out our [blog post](https://auth0.com/blog/brute-forcing-hs256-is-possible-the-importance-of-using-strong-keys-to-sign-jwts/).

```javascript
export default (options) => {

  var middleware = (req, res, next) => {
    ...

    // https://github.com/sgmeyer/auth0-node-jwks-rs256/blob/master/src/middleware/expressJwt.js#L25-L28
    var token = parts[1];

    // This could fail.  If it does handle as 401 as the token is invalid.
    var decodedToken = jwt.decode(token, {complete: true});
  }

  return middleware;
}

```

## Retrieving the Secret and Verifying the JWT

Now that we have the decoded token we have all the pieces we need to call get the JWKS and find the signature verification key.  First, we will use the `options.secret` to wrap our calls to `JwksClient` and assign it to `getSecret`.  Next, using the `jsonwebtoken` node module, we will verify the token.  Lastly, we will use `async.waterfall` to call `getSecret` and invoke `verifyToken` with the results of `getSecret`.  This will ultimately be used to verify the JWT.

```javascript
export default (options) => {

  var secretCallback = options.secret;

  var middleware = (req, res, next) => {
    ...

    // https://github.com/sgmeyer/auth0-node-jwks-rs256/blob/master/src/middleware/expressJwt.js#L30-L58
    if (decodedToken.header.alg !== 'RS256') {
      // we are only supporting RS256 so fail if this happens.
      return cb(null, null);
    }

    var tasks = [
      function getSecret(callback) {
        secretCallback(req, decodedToken.header, decodedToken.payload, callback);
      },
      function verifyToken(secret, callback) {
        jwt.verify(token, secret, options, function(err, decoded) {
          if (err) {
            callback(new UnauthorizedError('invalid_token', err));
          } else {
            callback(null, decoded);
          }
        });
      }
    ];

    async.waterfall(tasks, (err, result) => {
      if (err) {
        return next(err);
      }

      set(req, _requestProperty, result);
      next();
    });
  }

  return middleware;
}

```

## Calling our middleware

Now that we have all the pieces in place to validate an RS256 token, we need to configure the middleware and apply it to the route.

```javascript
/**
 * https://github.com/sgmeyer/auth0-node-jwks-rs256/blob/master/src/middleware/jwtCheck.js#L8-L17
 **/

import expressJwt from './expressJwt';
import expressJwtSecret from '../lib/expressJwtSecret';

export const jwtCheck = expressJwt({
  secret: expressJwtSecret({
    jwksUri: `https://your-tenant.auth0.com/.well-known/jwks.json`
  }),

  // Validate the audience and the issuer.
  audience: 'https://api.c0der.io/v1/',
  issuer: `https://your-tenant.auth0.com/`,
  algorithms: ['RS256']
});

app.get('/meta', jwtCheck, api());

```

As you can see anytime we call the api's `/meta` endpoint a token will be verified.  This is where all of the pieces are pulled together.  Each time a request is made to `/meta` the JWT will be verified against the appropriate key in the JWKS.  Also, if the JWT passes signature verification the audience and issuer will be checked using `jsonwebtoken` module.

> Auth0 provides the simplest and easiest to use [user interface tools to help administrators manage user identities](https://auth0.com/user-management) including password resets, creating and provisioning, blocking and deleting users.

<include src="asides/Jwt" />

## Happy Coding

At this point we have seen an end to end sample for verifying a RS256 signed JWT.  This process not overly difficult, however it does add significant complexity as opposed to a symmetric algorithm like HS256.  Despite the added complexity it offers significant security benefits over HS256 and will surely pay off in the long run.  We highly recommend using RS256 as a means to sign your JWTs.

You can find the full sample on [GitHub](https://github.com/sgmeyer/auth0-node-jwks-rs256).


Navigating RS256 and JWKS

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

How Auth0 helps you securely maintain user sessions and engagement in the era of ITP


## TL;DR

 * The ability to maintain seamless experiences for end-users in Single Page Applications (SPAs) is often business-critical and can have an enormous impact on revenue.
 * New browser privacy controls adversely impact the user experience in SPAs by preventing access to third-party cookies, which are used for silent authentication.
 * Auth0 now offers an alternative--Refresh Token Rotation--that provides a secure method for using refresh tokens in SPAs while providing end-users with seamless access to resources without the disruption in UX caused by browser privacy technology like ITP.

## The Business Imperative

Maintaining an uninterrupted user experience without the need to continually log in is critical for continued engagement, conversion rates, and sustained revenue. If an end-user returns to your site and they are automatically authenticated, they are much more likely to make purchases because they can be shown relevant promotions, see items they may have left in their cart, and have one less barrier on the way to a successful checkout. According to a [2018 report from Accenture](https://www.accenture.com/t20171031T052156Z__w__/us-en/_acnmedia/PDF-34/Accenture-Pulse-Check-Dive-Key-Findings-Personalized-Experiences.pdf), 91% of consumers are more likely to shop with brands who **recognize, remember**, and provide relevant offers and recommendations.

This is especially important on mobile websites and in mobile applications, where having to re-enter credentials can be a nuisance and result in abandoned carts or users opting to access the content later (when they have time to remember/enter their credentials) rather than being able to do so at the moment. Anyone who’s made an impulse purchase on their phone after seeing something cool or remembering at the last minute that a loved one’s birthday is next week can attest to how nice it is to not have to provide username and password credentials in the throws of inspiration (or panic).

## OAuth2 and Securing SPA Access to APIs

Single Page Applications (SPAs) are everywhere, driven by the business needs for richer user experiences and exposed APIs for use by other services. Unfortunately, providing secure authentication in SPAs has a number of challenges based on your application’s use case. 

The former guidance of using the Implicit Grant to provide access tokens (ATs) to SPAs is fairly straightforward but carries with it several security risks that each require explicit mitigations you must account for. If you want a more detailed exposition on the challenges of using the Implicit Flow in SPAs, please read [this excellent treatise](https://auth0.com/blog/oauth2-implicit-grant-and-spa/) by the incomparable [Vittorio Bertocci](https://www.linkedin.com/in/vittoriobertocci).

Auth0’s guidance to date is to use the [Authorization Code Flow with Proof Key for Code Exchange (PKCE)](https://auth0.com/docs/flows/concepts/auth-code-pkce) in SPAs. This is a much more secure solution than the Implicit Flow, and when used in conjunction with [silent authentication](https://auth0.com/docs/api-auth/tutorials/silent-authentication), it ensures that SPAs can silently renew access tokens without interrupting the user experience.

This technique uses a hidden iframe to request a code from Auth0, leveraging the Auth0 session cookie to prove the user is authenticated, subsequently enabling the SPA to then exchange that code for a new AT without prompting the end-user. 

However, recent browser enhancements threaten the uninterrupted user experience businesses rely on. Browsers are building more capabilities to safeguard user privacy, including [Safari blocking access to all third-party cookies](https://webkit.org/blog/10218/full-third-party-cookie-blocking-and-more/) and [Chrome’s commitment](https://techcrunch.com/2020/01/14/google-wants-to-phase-out-support-for-third-party-cookies-in-chrome-within-two-years/) to do so within two years. 

Beyond the marketing and tracking implications of these changes, which many people applaud, there are unfortunate impacts on how SPAs leverage OAuth to access resources. These advancements, unfortunately, mean that the technique of preserving an uninterrupted user experience via Code Flow with PKCE in conjunction with silent authentication are no longer feasible because the hidden iframe can no longer access the Auth0 session cookie.

## What About Refresh Tokens? 

Beyond silent authentication, another technique for getting new access tokens is to use Refresh Tokens (RTs), which are typically long-lived and are used to request new ATs after the shorter-lived ATs expire.  [Refresh Tokens](https://auth0.com/blog/refresh-tokens-what-are-they-and-when-to-use-them/) are an elegant solution that is often used in native applications on mobile devices in conjunction with short-lived ATs to provide seamless UX without having to issue long-lived ATs. 

![Refresh Tokens]( https://images.ctfassets.net/23aumh6u8s0i/10MGE8a5mYfQ5B6vJQX7MW/4be95e14a614b51ab88c477a382fe710/01_RTs_ATs)
(Like our fancy icons?
[Learn more about Auth0’s free Identicons](https://auth0.com/blog/introducing-auth0-identicons-identity-icons/)!)

This is why you can access streaming video services on your smart TV without signing in after you complete the initial Device Authorization; RTs are getting new ATs for you all the time. 

Unfortunately, long-lived RTs are not suitable for SPAs because there is no persistent storage mechanism in a browser that can assure access by the intended application only. As there are vulnerabilities that can be exploited to obtain these high-value artifacts and grant malicious actors access to protected resources, using refresh tokens in SPAs has been strongly discouraged. 

So... Privacy technology is impeding the Code Flow with PKCE & silent authentication. Refresh tokens can’t securely be persisted in browsers for long periods of time. What can we do?

## Introducing Refresh Token Rotation

As previously mentioned, using RTs in SPAs was considered insecure because they typically have long lifetimes (hence, their use in retrieving new short-lived ATs) and browser storage is susceptible to token theft. However, there are acceptable mitigations outlined in the most recent [OAuth2 BCP for browser-based applications](https://tools.ietf.org/html/draft-ietf-oauth-browser-based-apps-05) stipulating that refresh tokens may be used provided that they adhere to [specific recommendations](https://tools.ietf.org/html/draft-ietf-oauth-browser-based-apps-05#section-8), including having a maximum lifetime and requiring rotation to protect against malicious re-use.

_"The best practices doc states that another acceptable mechanism for protecting refresh tokens for use in public clients (not just browsers) is **refresh token rotation**, a feature that invalidates a refresh token and issues a new one whenever it is used to refresh an access token. Security-wise, that's a great feature."_

Reference: [https://auth0.com/blog/oauth2-implicit-grant-and-spa/](https://auth0.com/blog/oauth2-implicit-grant-and-spa/)

Auth0 is proud to announce that as of today, **Refresh Token Rotation with Reuse Detection** is available for all customers. With Refresh Token Rotation enabled, every time a client exchanges an RT to get a new AT, a new RT is also returned and the preceding RT is invalidated. This means you don’t need to worry about having a long-lived RT that, if compromised, could provide illegitimate access to resources. As RTs are continually exchanged and invalidated, the threat surface area is greatly reduced.

Auth0 makes it easy to get started with Refresh Token Rotation. You can enable it via API call or using the Auth0 Dashboard with just a few clicks.

![Refresh Token Rotation with Reuse Detection]( https://images.ctfassets.net/23aumh6u8s0i/5QNg54N5PHCx1Wkp40uI7D/e31f25ef32c16c04f256b773be2508c8/02_rotating-tokens)

RTR is supported for any application using the following flows:

 * OAuth2 Authorization Code Flow
 * OAuth2 Authorization Code Flow with Proof Key for Code Exchange (PKCE)
 * OAuth2 Device Authorization Grant (Device Flow)
 * Resource Owner Password Grant (ROPG)

The following diagram illustrates how Refresh Token Rotation is used in conjunction with the Authorization Code Flow with PKCE, but the general principle of getting a new refresh token with each exchange applies to all supported flows.

![RTR Sequence Diagram](https://images.ctfassets.net/23aumh6u8s0i/31zrZnDZ9lQVNE4Xsu0J2w/b7d7686b3764798eff19ce134229ae8b/03_RTR_Sequence_Diagram)

## Automatic Reuse Detection

When a client needs a new AT, it sends the RT with the request to Auth0 to get a new RT/AT pair. As soon as the new RT/AT pair is issued by Auth0, the RT used in the request is invalidated. This helps safeguard your application from replay attacks resulting from compromised RTs.

Without enforcing sender-constraint using techniques like mTLS or Proof of Possession that require the client to prove it is the same one originally authorized, which are not yet widely adopted, it’s impossible for the Authorization Server (AS) to know which actor is legitimate or malicious in the event of a replay attack. Therefore, it’s important that when a previously-used RT (already invalidated) is sent to the AS that the most recently issued RT is immediately invalidated as well, preventing any RTs in the same token family--all RTs descending from the original RT issued for the client--from being used to get new ATs.

Let’s consider the following scenario: 

1. Legitimate Client has RT1, and RT1 is leaked to or stolen by Malicious Client. 
2. Legitimate Client uses RT1 to get a new RT/AT pair.
3. Auth0 returns RT2/AT2.
4. Malicious Client then attempts to use RT1 to get an access token. Auth0 recognizes that RT1 is being reused, and immediately invalidates the RT family, including RT2 because the reappearance of RT1 is indicative of token leakage. It is important that RT2 is also invalidated to prevent any subsequent damage, such as the attacker gaining access to that token.
5. Auth0 returns an Access Denied response to Malicious Client.
6. AT2 Expires and Legitimate Client attempts to use RT2 to request a new RT/AT pair. 
7. Auth0 returns an Access Denied response to Legitimate Client. Re-authentication is required.


![RTR Token Family](https://images.ctfassets.net/23aumh6u8s0i/4sQHivXQ1DSIYiySY7LfBx/69640b448b38980cb8433341e4fe646a/04_RTR_Token_Family)

This protection mechanism works regardless of whether the legitimate client or the malicious client is able to exchange RT1 for a new RT/AT pair before the other. As soon as reuse is detected, all subsequent requests will be denied until the user re-authenticates. And when reuse is detected, Auth0 captures this event in logs to provide visibility for security reviews/audits. This can be especially useful in conjunction with Auth0’s new log streaming capabilities.

This means that you can safely use RTs to mitigate the adverse effects of browser privacy tools and provide continuous access to end-users without disrupting the user experience.

## A Little Leeway Sometimes Helps

To ensure that re-use detection doesn’t adversely affect users that suffer intermittent network performance, we’ve also included a **configurable reuse interval** to account for scenarios where the tokens issued from Auth0 are not received before the client application retries using the original refresh token. This is especially important in cases where users may be on slower cellular connections or congested networks.

For example, a client application has a refresh/access token pair (RT1 & AT1). AT1 is short-lived and expires. The client needs to use RT1 to get a new AT. The client sends RT1 to Auth0, but experiences a network error before getting a response from Auth0, and never receives AT2 or RT2. So the client retries a few seconds later using RT1 again (the only RT it currently has in its possession). Without a sufficient reuse interval configured, Auth0 would recognize the retry as a reuse attempt, invalidate the entire RT family, and require a re-authentication. 

By configuring a reuse interval, you can account for known network issues based on your use-cases, such as scenarios where the client is accessed on a mobile device with spotty connectivity. Should you choose to configure a reuse interval, the safest practice is to use the shortest amount of time to afford protection from replay attacks.

## SDK Support

The following SDKs are updated to include support for Refresh Token Rotation:

 * [Auth0 SPA SDK (1.7.0)](https://auth0.com/docs/libraries/auth0-spa-js)
 * [Auth0 Swift (iOS) SDK (1.23.0)](https://auth0.com/docs/libraries/auth0-swift)
 * [Auth0 Android SDK (1.23.0)](https://auth0.com/docs/libraries/auth0-android)

The Auth0 SPA SDK previously did not support refresh tokens of any kind, until today. Now, you can enable the use of rotating RTs and successfully mitigate the effects of browser privacy tools when performing silent authentication. 

One additional security feature that has been included is the ability for the SDK to leverage web workers to make requests to the token endpoint and store new RTs. This makes it much harder for malicious actors to retrieve refresh tokens straight out of the in-memory store.

In addition, we now enable the developer to opt-in to storing tokens in either local storage or browser memory, the default being the latter.

You can read more about all of the new features in the [SDK documentation](https://auth0.com/docs/libraries).

## Let’s Get Started

As of April 15, 2020, Refresh Token Rotation is available for all Auth0 customers. You can read more about Refresh Token Rotation and how to configure it for use in your applications in the [Auth0 documentation](https://auth0.com/docs/tokens/concepts/refresh-token-rotation). We hope that you find this new capability helpful for sustaining user sessions and maintaining engagement in this era of heightened user privacy tools.

Stay healthy. Stay safe. And secure your SPAs!

<include src="asides/AboutAuth0" />


Securing Single Page Applications with Refresh Token Rotation

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

001c9ddc5ceb9829b6aaf24f5d28502a

I am software developer with a keen interest in open-source technologies, Linux, and native development. I've worked on many different platforms Android, iOS, Win32, Linux, FreeRTOS, the Web, and others. I've gone through the whole stack and I enjoy learning and using the latest technologies. I now work as a full-stack developer at Auth0.

Senior Engineer

Sebastian Peyrott

Learn about WebAuthn, a new standard for secure authentication on the web.


[News](https://www.engadget.com/2018/05/09/mozilla-firefox-passwords-web-authentication-support/) about [Web Authentication](https://webauthn.me/introduction), or WebAuthn for short, reaching maturity and being enabled by default in web browsers hit the headlines recently. Web Authentication is a fairly recent W3C standard backed by major players like Google, Paypal, Mozilla, Microsoft, and Qualcomm. It aims at defining a web-browser API for the creation and use of strong authentication credentials based on public key cryptography. The driving force behind the proposal is to increase security for the authentication process by removing or complementing password-based authentication while remaining convenient for end-users. Although implementations are still in their early days, and the standard has not been finalized, the strong push from major players, and the fact that both Firefox and Chrome are enabling their implementations by default, are strong indicators that this may cause a significant impact in the authentication space. Let's check it out!

<include src="WebAuthnMeCTA" group="A"/>

---

## Introduction
The traditional username/password scheme for user authentication has been in use for decades. Even in the face of modern approaches like social logins and [Face ID](https://en.wikipedia.org/wiki/Face_ID), username and passwords remain the most popular and widely used mechanism for authentication. Stronger authentication mechanisms such as certificates and hardware tokens have been supported for a long time for specific applications and use cases, but they remain unusual for end users.

Most of the authentication flows performed by end users are done through web browsers. In a sense, web browsers have become the nexus between credentials and applications on the two major platforms: desktop and mobile. It is natural, then, that changes to authentication flows require support from browsers. The web, however, is built on consensus. This means that changes to the platform need to be implemented by several players. For this reason, the W3C WebAuthn Working Group was formed: to produce a new specification that can be implemented by all parties and that remains interoperable.

The draft specification says:

> This specification defines an API enabling the creation and use of strong, attested, scoped, public key-based credentials by web applications, for the purpose of strongly authenticating users.

<include src="TweetQuote" quoteText="Web Authentication defines an API enabling the creation and use of strong, attested, scoped, public key-based credentials by web applications, for the purpose of strongly authenticating users."/>

To better understand Web Authentication, let's go through a quick overview.

## Web Authentication In a Nutshell
Let's take a look at the entities involved in WebAuthn:

![Web Authentication (WebAuthn) Entities](https://images.ctfassets.net/23aumh6u8s0i/5c7KKyElhmYWEPB4R8TQje/d46dec602523f6af3cb4d68b03e15232/1-Web-Authentication-Entities.png)

These entities work together in two separate use cases: **registration** and **authentication**. All communications between the different entities in the diagram are handled by the user agent (usually a web browser).

Registration makes the authenticator create a new set of public-key credentials that can be used to sign a challenge generated by the relying party. The public part of these new credentials, along with the signed challenge, can be sent back to the relying party for storage. The relying party can later use these credentials to verify the identity of a user whenever required.

![Web Authentication (WebAuthn) Registration](https://images.ctfassets.net/23aumh6u8s0i/2xxX1F2zya0XdsiCRz5dXk/3c3350168175e59b2e41be8afda3e9fd/2-Registration.png)

Authentication, in contrast, allows the relying party to send a challenge to the authenticator. This challenge can then be signed with the previously generated public-key credentials and sent back to the relying party. This way, the relying party can verify that a user is in possession of the required credentials, proving their identity.

![Web Authentication (WebAuthn) Authentication](https://images.ctfassets.net/23aumh6u8s0i/6iz4I2CXCV5CW7qNaSknTK/88fe1dd04f4bdde733d11f1fd947cfe4/3-Login.png)

Both processes work with the help of public-key cryptography and digital signatures. If you are not familiar with how public-key cryptography or digital signatures work, the important thing you must know is that there is a public key and a private key. The private key is secret, and only the user (or the authenticator) must know it. The public key, in contrast, is public and can be seen or stored by anyone. The public key can be used to verify signatures generated by the private key. No other key, other than the private key, can generate a signature that the public key can verify as valid. This way, the relying party can store a public key and use it to verify signatures performed by the user holding the private key.

Let's take a quick look at the actual API.

### API
The Web Authentication API has two main calls: [`navigator.credentials.create`](https://www.w3.org/TR/webauthn/#createCredential), and [`navigator.credentials.get`](https://www.w3.org/TR/webauthn/#getAssertion). There is also an [accessory API to list authenticators](https://www.w3.org/TR/webauthn/#isUserVerifyingPlatformAuthenticatorAvailable).

`create` can be used to perform the registration step. `get` can be used to perform the authentication step.

Here is a sample call of the `create` function inside an [EJS](http://ejs.co/) template:

```javascript
navigator.credentials.create({
  publicKey: {
    // random, cryptographically secure, at least 16 bytes
    challenge: base64url.decode('<%= challenge %>'),
    // relying party
    rp: {
      name: 'Awesome Corp' // sample relying party
    },
    user: {
      id: base64url.decode('<%= id %>'),
      name: '<%= name %>',
      displayName: '<%= displayName %>'
    },
    authenticatorSelection: { userVerification: "preferred" },
    attestation: 'direct',
    pubKeyCredParams: [
      {
        type: "public-key", alg: -7 // "ES256" IANA COSE Algorithms registry
      }
    ]
  }
}).then((res) => {
  var json = publicKeyCredentialToJSON(res);
  // Send data to relying party's servers
  post('/webauthn/register', {
    state: '<%= state %>',
    provider: '<%= provider %>',
    res: JSON.stringify(json)
  });
}).catch(console.error);
```

Here is a sample call of the `get` function in an EJS template:

```javascript
navigator.credentials.get({
  publicKey: {
    // random, cryptographically secure, at least 16 bytes
    challenge: base64url.decode('<%= challenge %>'),
    allowCredentials: [ {
      id: base64url.decode('<%= id %>'),
      type: 'public-key'
    }],
    timeout: 15000,
    authenticatorSelection: { userVerification: "preferred" },
  }
}).then((res) => {
  var json = publicKeyCredentialToJSON(res);
  // Send data to relying party's servers
  post('/webauthn/authenticate', {
    state: '<%= state %>',
    provider: '<%= provider %>',
    res: JSON.stringify(json)
  });
}).catch(err => {
  alert('Invalid FIDO device');
});
```

But the cool thing about all of this is that you don't need to care about any of it! If you use Auth0, you don't need to understand the gritty details of Web Authentication to use it.

<include src="TweetQuote" quoteText="Web Authentication at Auth0 will work with the flip of a switch!"/>

## A Working Web Authentication Implementation at Auth0
One of the cool things about our architecture is that changes in the login system can be integrated with little or no changes to client code. In other words, once our implementation of Web Authentication is released, enabling it for your apps will be a matter of making a few clicks in the [Auth0 Dashboard](https://manage.auth0.com/).

This is a proof-of-concept of how WebAuthn as a second factor will work in Auth0:

<video src="https://cdn.auth0.com/blog/webauthn/Auth0-Web-Authentication-2-small.mp4" title="Web Authentication proof-of-concept video - WebAuthn as a second factor with Auth0" controls autoplay loop></video>

What you see in this video is already working internally. We are eager to finish the implementation so you can start enabling Web Authentication in your apps.

Of course, there is more to Web Authentication than just using it as a second factor. We are also planning to enable Web Authentication as a **primary login solution**, that is, as a **passwordless login** mechanism. If you are not familiar with passwordless login and how it works, [take a look at our introduction](https://auth0.com/passwordless). Can you imagine logging in to your bank with just a push of your USB authenticator's button? <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 an Auth0 account</a> and start improving your logins today. When WebAuthn integration is ready, enabling it for your apps will be a breeze.

<include src="TweetQuote" quoteText="Web Authentication (a.k.a. WebAuthn) is backed by major players in the industry, let's find out what it's all about!"/>

## Conclusion
Web Authentication brings a stronger authentication mechanism to the masses by defining an API that both authenticators and web browsers can implement. With the release of [Firefox 60](https://www.mozilla.org/en-US/firefox/60.0/releasenotes/) and [Chrome 67](https://www.chromium.org/developers/calendar), Web Authentication has become available to a big number of users. Authenticators, such as [Yubikeys](https://www.yubico.com/), already support the necessary protocols and work with current implementations. At Auth0 we care about providing the necessary building blocks for your identity infrastructure, and Web Authentication could eventually become a major improvement in security and user experience. If you would like to use Web Authentication with Auth0 for your product, let us know in the comments, or [contact us through our "Talk to Sales" contact form](https://auth0.com/).


Introduction to Web Authentication: The New W3C Spec

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

1097492785caf9ffeebffeb624202d8f?s=200 avatar

1097492785caf9ffeebffeb624202d8f?s=200

Prosper is a great speaker, community leader, open source hacker, technical consultant, and a fervent Developer Advocate. He is a full-stack software engineer who has worked on biometric, health and developer tools. Prosper recently co-founded a startup called Eden that’s focused on improving the quality of lives in Nigeria and currently leads the engineering team. He also co-founded forloop, the largest developer community in Africa.

Prosper Otemuyiwa

Cracking a JWT signed with weak keys is possible via brute force attacks. Learn how Auth0 protects against such attacks and alternative JWT signing methods provided.



JSON Web Tokens are an open, industry standard [RFC 7519](https://tools.ietf.org/html/rfc7519) method for representing claims securely between two parties. They can be digitally signed or encrypted and there are several algorithms that can be employed in signing a JWT. In this article, we'll look at the two most common algorithms and discover how using weak keys can allow malicious parties to brute force the secret key from the JWT.

## What is a JSON Web Token?

A JSON Web Token encodes a series of claims in a JSON object. Some of these claims have specific meaning, while others are left to be interpreted by the users. These claims can be verified and trusted because it is digitally signed. Examples of these claims are `issuer (iss)`, `subject (sub)`, `audience (aud)`, `expiration time (exp)`, `not before (nbf)`, and `issued at (iat)`. JWTs can be signed using a secret (with HMAC algorithm) or a public/private key pair using RSA or Elliptic-Curve.

## Structure of a JSON Web Token

A signed, compact-serialized JWT consists of three main parts separated by a `.` namely:

* Header
* Payload
* Signature

A JWT comes in this structure, `aaaaaa.bbbbbb.ccccc`.  `aaaaaaa` represents the header, `bbbbb` represents the payload while `cccccc` represents the signature.

### Header

The header typically consists of two parts: the type of the token, which is JWT, and the hashing algorithm such as `HS256` or `RS256`. Example:

```js

{
  "alg": "HS256",
  "typ": "JWT"
}

```

Then, this JSON is Base64Url encoded to form the first part of the JWT.

### Payload

This part of the token carries the claims. An example of a payload can be found below:


```js

{
  "sub": "1234567890",
  "name": "John Doe",
  "manager": true
}

```

The payload is then `Base64Url` encoded to form the second part of the JWT.

### Signature

The last part of the token is the signature. The signature is composed from the signing of the encoded header, encoded payload, and a secret.

An example of a signature using the HMAC SHA256 (HS256) algorithm can be created like so:

```bash

HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  secret)

```

_A signed JWT_

![](https://images.ctfassets.net/23aumh6u8s0i/37Di6AISUDai5Pex1TX8dk/b457fd206dc3c3ea9cfc5b6f9503d831/encoded-jwt4)

## JWT Signing Algorithms

The most common algorithms for signing JWTs are:

* HMAC + SHA256 (HS256)
* RSASSA-PKCS1-v1_5 + SHA256 (RS256)
* ECDSA + P-256 + SHA256 ( ES256)

### HS256

Hash-based Message Authentication Code (HMAC) is an algorithm that combines a certain payload with a secret using a cryptographic hash function like `SHA-256`. The result is a code that can be used to verify a message only if both the generating and verifying parties know the secret. In other words, HMACs allow messages to be verified through shared secrets.

This is an example showcasing a HMAC-based signing algorithm:

```js

const encodedHeader = base64(utf8(JSON.stringify(header)));
const encodedPayload = base64(utf8(JSON.stringify(payload)));
const signature = base64(hmac(`${encodedHeader}.${encodedPayload}`,
                              secret, sha256));
const jwt = `${encodedHeader}.${encodedPayload}.${signature}`;

```

An example of signing a JWT with the `HS256` algorithm using the `jsonwebtoken` JavaScript library can be found below:

```

var jwt = require('jsonwebtoken');

const payload = {
  sub: "1234567890",
  name: "John Doe",
  manager: true
};

const secretKey = 'secret';

const token = jwt.sign(payload, secretKey, {
    algorithm: 'HS256',
    expiresIn: '10m' // if ommited, the token will not expire
});

```

### RS256

RSA is a public-key algorithm. Public-key algorithms generate split keys: one public key and one private key.

For public-key signing algorithms:

```js

const encodedHeader = base64(utf8(JSON.stringify(header)));
const encodedPayload = base64(utf8(JSON.stringify(payload)));
const signature = base64(rsassa(`${encodedHeader}.${encodedPayload}`,
                                privateKey, sha256));
const jwt = `${encodedHeader}.${encodedPayload}.${signature}`;

```

When signing and verifying JWTs signed with RS256, you deal with a public/private key pair rather than a shared secret. There are many ways to create RSA keys. OpenSSL is one of the most popular libraries for key creation and management:

```bash

# Generate a private key
openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048

# Derive the public key from the private key
openssl rsa -pubout -in private_key.pem -out public_key.pem

```

Both `PEM` files are simple text files. Their contents can be copied and pasted into your JavaScript source files and passed to the `jsonwebtoken` library.

```js

// You can get this from private_key.pem above.
const privateRsaKey = `<YOUR-PRIVATE-RSA-KEY>`;

const signed = jwt.sign(payload, privateRsaKey, {
    algorithm: 'RS256',
    expiresIn: '5s'
});

```

```js

// You can get this from public_key.pem above.
const publicRsaKey = `<YOUR-PUBLIC-RSA-KEY>`;

const decoded = jwt.verify(signed, publicRsaKey, {
    // Never forget to make this explicit to prevent
    // signature stripping attacks.
    algorithms: ['RS256'],
});

```

### ES256

ECDSA algorithms also make use of public keys. We can use OpenSSL to generate the key as well:

```bash

# Generate a private key (prime256v1 is the name of the parameters used
# to generate the key, this is the same as P-256 in the JWA spec).
openssl ecparam -name prime256v1 -genkey -noout -out ecdsa_private_key.pem

# Derive the public key from the private key
openssl ec -in ecdsa_private_key.pem -pubout -out ecdsa_public_key.pem

```

If you open these files you will note that there is much less data in them. This is one of the benefits of ECDSA over RSA. The generated files are in PEM format as well, so simply pasting them in your source will suffice.

```js

// You can get this from private_key.pem above.
const privateEcdsaKey = `<YOUR-PRIVATE-ECDSA-KEY>`;

const signed = jwt.sign(payload, privateEcdsaKey, {
    algorithm: 'ES256',
    expiresIn: '5s'
});

```

```js

// You can get this from public_key.pem above.
const publicEcdsaKey = `<YOUR-PUBLIC-ECDSA-KEY>`;

const decoded = jwt.verify(signed, publicEcdsaKey, {
    // Never forget to make this explicit to prevent
    // signature stripping attacks.
    algorithms: ['ES256'],
});

```

> **Note:** These algorithm notes above are excerpts from the very comprehensive [Auth0 JWT book](https://auth0.com/e-books/jwt-handbook) written by [Sebastian Peyrott](https://twitter.com/speyrott). Download it for more information on signing and validating JWTs using these algorithms mentioned above.

## Brute Forcing a HS256 JSON Web Token

As secure as `HS256` is, especially when implemented the right way, brute-forcing a JSON web token signed with small and medium sized shared-secrets using **HS256** is still very possible.

Recently, I came across a [tool](https://github.com/brendan-rius/c-jwt-cracker) written in C on GitHub. It is a multi-threaded JWT brute force cracker. With a huge computing power, this tool can find the secret key of a `HS256` **JSON Web token**.

*Please note the RFC7518 standard states that "A key of the same size as the hash output (for instance, 256 bits for "HS256") or larger MUST be used with this algorithm." Auth0 secret keys exceed this requirement making cracking via this or similar tools all but impossible.*

### Implementing a Brute Force Attack

I used a Mac computer to try out the brute force attack. First, make sure you have `openssl` installed. If it is not, install it with homebrew like so:

```bash

brew install openssl

```

Then run this command in the terminal like so:

```bash

make OPENSSL=/usr/local/opt/openssl/include OPENSSL_LIB=-L/usr/local/opt/openssl/lib

```

On Ubuntu, you can install `openssl` like so:

```bash

apt-get install libssl-dev

```

The specs of my MacBook are mentioned below:

* Processor 2.7 GHz Intel Core i5
* Memory 8GB 1867 MHz DDR3
* Graphics Intel Iris Graphics 6100 1536 MB

Go ahead and clone the `jwt-cracker` from [GitHub](https://github.com/brendan-rius/c-jwt-cracker).

An example JWT signed with `HS256` and a secret, `Sn1f` is:

```bash

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.cAOIAifu3fykvhkHpbuhbvtH807-Z2rI1FS3vX1XMjE

```

Now, run the `jwt-cracker` from your terminal to crack the token like so:

```bash

time ./jwtcrack eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.cAOIAifu3fykvhkHpbuhbvtH807-Z2rI1FS3vX1XMjE

```

> **Note:** Make sure the `jwtcrack` script is executable by running `chmod a+x ./jwtcrack`

![Crack](https://images.ctfassets.net/23aumh6u8s0i/4udpHoOAXVjH7EHJBFUHle/ed28c644a954ca7b1920f87698414c37/token)

It took about 6.16s on my laptop to crack the secret key.

With the help of [jwt.io](https://jwt.io), let's sign another token quickly, but with a secret, *secret*.

Run the cracker again with the new JWT like so:

```bash

time ./jwtcrack eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ

```

![Crack a new token](https://images.ctfassets.net/23aumh6u8s0i/1IkSqwXYwSO0R9omXHtLrZ/62a47800d3d2284a969265fd126c5508/anothertoken)
_Crack another token_

From the results shown above, it cracked the token and got our secret, which is actually *secret* in about 3273.51s.

### Security Concerns and Recommendation

Let's take another look at the keys we used to generate the tokens that were cracked easily. What are the key sizes? The first key, `Sn1f` is 32-bit.

> 1 character = 8 bits

The second key, `secret` is 48-bit. This is simply too short to be a valid key. In fact, the [JSON Web Algorithms RFC 7518](https://tools.ietf.org/html/rfc7518#page-7) states that a key of the same size as the hash output (for instance, 256 bits for "HS256") or larger MUST be used with the HS256 algorithm.

I therefore recommend that anyone trying to generate a JSON Web token and signing them with HS256 to use a properly sized secret key. [Auth0](https://auth0.com) secret keys are 512 bits in length and not susceptible to this type of brute force attack. Additionally, Auth0 allows you to easily sign your JWTs with **RS256**.

## Using Auth0 to sign JWT with RS256

With [Auth0](https://auth0.com), you can easily generate JWTs for authentication and authorization. By default, we use HS256 to sign the JWTs generated, but we also allow customers to use RS256 if their use case calls for it. The [Auth0 Lock](https://auth0.com/lock) library returns a signed JWT that you can store on the client side and use for future requests to your APIs.

> [Auth0 offers a generous **free tier**](https://auth0.com/pricing) to get started with modern authentication.

In the vast majority of use cases you would never need to change the signing algorithm, but on the off chance that you do, let's see how to accomplish it with Auth0.

Create a client on the [dashboard](https://manage.auth0.com) like so:

![Create a client](https://images.ctfassets.net/23aumh6u8s0i/LnYGvipbhOTBha4iyrAMA/e9aef6949c9c42bd2e675ee3e733e7b4/create_app)
_Create a client_

Go to settings like so:

![Settings Page](https://images.ctfassets.net/23aumh6u8s0i/78uskAzSxRaSLqEm0l7A8D/c0ee3f4a001be8234235b000f0b78bdf/settings)
_Settings Page_

Scroll down to *Show Advanced Settings* like so:

![Show Advanced Settings](https://images.ctfassets.net/23aumh6u8s0i/7d3biIg5qkJQ0IfotBBMR4/99201a709219ae972e15972d6e0eda0c/show_advanced_settings)
_Show Advanced settings_

Switching to **RS256** is as easy as selecting the option from the dropdown on the Auth0 dashboard like so:

![Switch to RS256](https://images.ctfassets.net/23aumh6u8s0i/4kOPzgbRdWXKZCARj6h2AG/fe0e79bdc3b72366afe3798ee5f37a8e/switch_to_rs256)
_Default is HS256, Switching to RS256 is simple_

> Auth0 provides the simplest and easiest to use [user interface tools to help administrators manage user identities](https://auth0.com/user-management) including password resets, creating and provisioning, blocking and deleting users.

## Conclusion

JSON Web Tokens (JWTs) are lightweight and can easily be used across platforms and languages. They are a clever way to pass signed or encrypted information between applications. There are several [JWT libraries](https://jwt.io/#libraries-io) available for signing and verifying the tokens.

We have also been able to show that brute forcing of HS256 JWTs is certainly possible, when used with short and weak secret keys. Unfortunately, this is a limitation of most shared-key approaches. All cryptographic constructions, including HS256, are insecure if used with short keys, so ensure that implementations satisfy the standardized requirements.

As a rule of thumb, make sure to pick a shared-key as long as the length of the hash. For HS256 that would be a 256-bit key (or 32 bytes) minimum. Luckily, if you are an Auth0 customer you have nothing to worry about as we follow all the standards and best practices when generating secret keys.


Brute Forcing HS256 is Possible: The Importance of Using Strong Keys in Signing JWTs

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

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."/>


"token"