andrea-chiarelli

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

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

Principal Developer Advocate

Andrea Chiarelli

Learn to implement DPoP with Auth0 to secure your SPA and API. This guide shows how to protect your tokens and prevent token replay attacks with Auth0's SDKs.

In our [previous article](https://auth0.com/blog/protect-your-access-tokens-with-dpop/), we explored the inner workings of Demonstrating Proof of Possession (DPoP), a powerful standard that binds access tokens to a specific client. You learned how DPoP uses public key cryptography to ensure that even if an access token is leaked, it's useless to an attacker without the corresponding private key.

We discussed [DPoP’s security benefits](https://auth0.com/blog/protect-your-access-tokens-with-dpop/#The-Benefits-of-DPoP) and highlighted its flexibility for modern applications. Since DPoP is implemented at the application level, it is particularly well-suited for Single-Page Applications (SPA), for example. However, you may have concerns about this. Implementing cryptographic key management and signing proofs for every API request sounds complicated. Actually, manually handling DPoP would indeed add significant complexity to your application code.

The good news is that you don't have to. The [Auth0 SDKs](https://auth0.com/docs/libraries) are designed to handle this complexity for you. With just a few lines of configuration, you can enable robust DPoP protection in both your client-side application and your backend API.

This article will show you how by walking through practical examples. We will focus on a JavaScript SPA and an Express.js-based API, but our SDKs allow you to easily implement DPoP support in other programming languages and frameworks as well.

> At the time of writing, DPoP support for Auth0 is in Early Access and not all the SDKs provide support for it at the moment.

## Enabling DPoP in Auth0

Before you write any code, you must enable DPoP in Auth0 for both your API and client application. This ensures the entire authentication and authorization flow enforces Proof of Possession.

### Enable DPoP in your API

First, you must tell Auth0 that your API requires DPoP-bound tokens. Navigate to your [Auth0 dashboard](https://manage.auth0.com/) and follow these steps:

1. Go to [Applications > APIs](https://manage.auth0.com/#/apis) and select the API you want to secure.  
2. Click on the *Settings* tab.  
3. Scroll down to the "Token Sender-Constraining" section.  
4. Select “DPoP” as the sender-constraining method and switch on the “Require Token Sender-Constraining” toggle as shown below:
   ![Auth0 API settings dashboard showing DPoP selected as the sender-constraining method and required for token validation.](https://images.ctfassets.net/23aumh6u8s0i/23LuyoMxGRcdBmJUyuLcNE/bd35d6551c81d54873dedceb146fc929/configure-dpop-on-auth0-for-api.png)  
5. Click *Save*.

> Note: In our example we are going to make DPoP mandatory for API requests. This is why you needed to switch the toggle button in addition to selecting DPoP as the sender-constraining method. If you don’t switch the toggle button, the API can accept both bearer and bound access tokens.

### Enable DPoP in your client application

Next, you should enforce DPoP on your client application. This setting ensures that your application **must** use DPoP and cannot fall back to using regular bearer tokens. Follow these steps in your Auth0 dashboard:

1. Go to [Applications > Applications](https://manage.auth0.com/#/applications) and select your client application (e.g., your SPA).  
2. Click on the *Settings* tab and scroll down to the "Token Sender-Constraining" section.  
3. Toggle on the “Require Token Sender-Constraining” switch, as shown here:  
   ![Auth0 application settings dashboard showing the 'Require Token Sender-Constraining' switch enabled to enforce DPoP.](https://images.ctfassets.net/23aumh6u8s0i/6ychCNuPxttBRJOtqLxbpn/210f56bacd94211715d8cbab30d64584/configure-dpop-in-auth0-for-spa.png) 
4. Scroll down and click *Save*.

With both the API and the client application configured, your Auth0 environment is now ready to enforce DPoP from end to end:

* Any token request for this API's audience that doesn't include a valid DPoP proof will be rejected.  
* Any API request without a bound access token will be rejected.

## Securing Your SPA with DPoP and Auth0

For a JavaScript SPA, the [`auth0-spa-js` SDK](https://github.com/auth0/auth0-spa-js) simplifies identity management. It also provides first-class support for DPoP, handling key generation, storage, and proof creation automatically. Let’s see how to configure this SDK to support DPoP and how to request and use bound access tokens.

>Note: Make sure you have installed `auth0-spa-js` version 2.4.0 or later to include DPoP support.

### Configuring the Auth0 SPA SDK

To enable DPoP, you need to configure your Auth0 client instance with the `useDpop: true` setting. It tells the SDK to generate and manage a private/public key pair for the application instance. The SDK will then automatically create and attach DPoP proofs whenever it communicates with your Auth0 tenant's token endpoint.

Here is a typical initialization of the Auth0 client instance with DPoP enabled:

```javascript
import { createAuth0Client } from '@auth0/auth0-spa-js';

const auth0Client = await createAuth0Client({
  domain: 'YOUR_AUTH0_DOMAIN',
  clientId: 'YOUR_APPLICATION_CLIENT_ID',
  authorizationParams: {
    audience: 'YOUR_API_IDENTIFIER',
    redirect_uri: window.location.origin,
  },
  useDpop: true  //👈 DPoP setting
});
```

> Note: The `auth0-spa-js` SDK uses the [CryptoAPI](https://developer.mozilla.org/en-US/docs/Web/API/Crypto) and [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) APIs to use cryptographic keys and storage on the browser.

### Getting and using DPoP-bound tokens

The beauty of the SDK is that your application code for fetching and using tokens doesn't change. When you call [`getTokenSilently()`](https://auth0.github.io/auth0-spa-js/classes/Auth0Client.html#getTokenSilently), the SDK works its magic in the background. It will automatically create a DPoP proof specific to the API request and attach it to the `DPoP` header.

Once you get your access token, you could use it in the usual way with the `DPoP` scheme in the `Authorization` header instead of the `Bearer` scheme. However, things are not as easy as they seem. You need to [generate the DPoP proof and take care of nonces](https://auth0.com/docs/secure/sender-constraining/demonstrating-proof-of-possession-dpop#public-clients). The SDK provides methods to help you perform these tasks, but you still need to store nonces, manage retries, etc.

Fortunately, the SDK helps you with a powerful feature: `fetchWithAuth()`. In its simplest form, `fetchWithAuth()` can be used as shown in the following example:

```javascript
const fetcher = client.createFetcher({
  dpopNonceId: 'my_api_request'
});

try {
   const response = await fetcher.fetchWithAuth('https://api.example.com/products', {
     method: 'GET'
   });

    const data = await response.json();
    console.log(data);
  } catch (error) {
    console.error('Error calling the API', error);
  }
```

As you can see, you use `fetchWithAuth()` just like in the built-in `fetch()` function. However, under the hood, `fetchWithAuth()` takes care of getting an access token and injecting it into the HTTP header, generating and injecting DPoP proofs, managing nonces, handling retries, etc.

To learn more, see the [`auth0-spa-js` DPoP examples](https://github.com/auth0/auth0-spa-js/blob/main/EXAMPLES.md#device-bound-tokens-with-dpop).

## Validating DPoP Tokens in Your Auth0-Secured Express API

On the server side, your API must be configured to validate not just the access token but also the accompanying DPoP proof. The `express-oauth2-jwt-bearer` library provides middleware to handle this validation seamlessly.

### Configuring the Express Middleware

First, install the [necessary package](https://github.com/auth0/node-oauth2-jwt-bearer/blob/main/packages/express-oauth2-jwt-bearer) with the following command:

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

> Note: Make sure you install the latest version of the package (version 1.7.0 and later)

The good news is that the library enables server-side DPoP support by default. In fact, it supports both bearer tokens and bound tokens, so standard API protection code like the one shown below allows you to validate a DPoP-bound token without any changes:

```javascript
const express = require('express');
const { auth } = require('express-oauth2-jwt-bearer');

const app = express();
const port = 3001;

app.use(
  auth({
    issuerBaseURL: 'https://YOUR_AUTH0_DOMAIN',
    audience: 'YOUR_API_IDENTIFIER'
  })
);

app.get('/products', (req, res) => {
  //...your code...
});

app.listen(port, () => {
  console.log(`API server listening on port ${port}`);
});
```

However, according to the default behavior, this API will also accept HTTP requests with standard bearer access tokens. This is not how you configured DPoP in the Auth0 dashboard. You made it mandatory. 

Then you need to make DPoP mandatory in your API too. That’s just a matter of enabling a flag, as shown in the following code snippet:

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

app.use(
  auth({
    issuerBaseURL: 'https://YOUR_AUTH0_DOMAIN',
    audience: 'YOUR_API_IDENTIFIER',
    //👇 new code
    dpop: {
      required: true
    }
    //👆 new code
  })
);

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

The middleware now ensures that every request is checked against a valid access token *and* a DPoP proof that is bound to the token and the specific request. However, it rejects requests that have a valid access token but are missing the corresponding DPoP proof.

The middleware also allows you to control other parameters. Check out the [`express-oauth2-jwt-bearer` DPoP examples](https://github.com/auth0/node-oauth2-jwt-bearer/blob/main/packages/express-oauth2-jwt-bearer/EXAMPLES.md) to learn more.

## Conclusion

Sender-constrained tokens represent a significant step forward in API security, and DPoP is the standard leading the way. While the underlying cryptography is complex, implementing it doesn't have to be. By leveraging Auth0 SDKs on both the client and server, you can adopt DPoP with minimal changes to your application code.

Throughout this article, you've seen how to enable DPoP for your API and your SPA in the Auth0 dashboard. You also configured your SPA with `auth0-spa-js` to request and use DPoP-bound access tokens. Finally, you enforced DPoP validation in your Express.js API using the `express-oauth2-jwt-bearer` middleware.

By abstracting the complexity, the SDKs empower you to focus on building your application's features while ensuring your users' data is protected by a state-of-the-art security mechanism.

Implementing DPoP with Auth0

Dive into the structure of an OAuth 2.0 authorization request to understand its key parameters and why this knowledge is crucial for developers, even when using SDKs.

While modern SDKs and libraries abstract much of the complexity of OAuth 2.0, a good understanding of the underlying authorization request structure remains essential for developers. When issues arise, such as unexpected redirects, token rejection, or other error messages, having insight into the raw request helps in troubleshooting.

This mostly depends on [what type of developer you are](https://auth0.com/blog/zen-and-the-art-of-identity-management/), of course. It's like opening the hood of your car to diagnose a problem. You don't have to be a mechanic or even an engineer to understand every little detail of your car's engine. But being able to determine whether the engine is overheating because of insufficient coolant or the car won't start because a battery cable has come loose can help you speed up the troubleshooting process, sometimes even without the need for expert intervention.

Let's take a look at what's under the hood of an OAuth 2.0 authorization request.

## The Authorization Request Under X-Ray

I assume you have a basic understanding of OAuth 2.0. If not, you can read a quick [introduction to the authorization framework](https://auth0.com/docs/authenticate/protocols/oauth) and [its flows](https://auth0.com/docs/get-started/authentication-and-authorization-flow/which-oauth-2-0-flow-should-i-use). If you want to go more in depth, check out [OAuth 2.0 and OpenID Connect: The Professional Guide](https://auth0.com/resources/ebooks/oauth-openid-connect-professional-guide).

> While this article mentions OAuth 2.0, you will also find details related to OpenID Connect and other OAuth extensions. This is because it’s very common to see the two protocols interconnected. After all, OpenID Connect is nothing but an OAuth 2.0 specialization.

It all starts when a client application redirects a user's browser to the authorization server to begin the authorization process. The authorization request is usually a GET HTTP request sent to the authorization endpoint of the authorization server, although it may be a POST HTTP request too.

The following picture shows a typical authorization request:

<picture>
<img src="https://images.ctfassets.net/23aumh6u8s0i/3AdUXr1YF3wbKqCw1ajkht/8b088f0ddfe7da8232906b89230172a6/authorization-request-breakdown.png" alt="Diagram of an OAuth 2.0 authorization request showing the endpoint and parameters like client_id, response_type, and scope." style="width:80%; margin: .9em auto;">
</picture>

As you can see from the picture above, the authorization request structure expresses what the client application wants to achieve. You can highlight the main elements of its structure with something vaguely reminiscent of the [5 Ws](https://en.wikipedia.org/wiki/Five_Ws) of journalism:

* **Who** is making the request?  
* **What** artifact is requested?  
* **How** is the artifact returned?  
* **Where** will the artifact be sent?  
* **Why** is the artifact needed?

In addition to these fundamental elements of the request, there are other elements that help improve its security posture.

## The Core of an Authorization Request

With reference to the authorization request example mentioned in the previous section, let’s break down the elements that compose it.

### The authorization endpoint

The first element of the request we analyze is the authorization server URL: `https://my-tenant.auth0.com/authorize`.

This is an ordinary URL that includes the authorization server’s domain (`my-tenant.auth0.com`) and the authorization endpoint (`/authorize`). As in any common HTTP request, this URL identifies the server’s endpoint to which the client is sending its authorization request.

In the URL example, I’ve used an Auth0 subdomain as the authorization server domain, but in general it will be the domain where the authorization server is reachable. In the context of Auth0, you can use your [custom domain](https://auth0.com/docs/customize/custom-domains), for example.

Regarding the authorization endpoint, while the `/authorize` endpoint is pretty common, this name is not required by the specifications, which leaves OAuth 2.0 server implementors [free to use the name they prefer](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1).

> In an OpenID Connect context, you can take advantage of the [discovery protocol](https://openid.net/specs/openid-connect-discovery-1_0.html) that allows you to use the `/.well-known/openid-configuration` document to find the authorization URL and other configuration settings.

### The client ID

The parameter `client_id` responds to the question, **Who** is making the request? It identifies the client application that submits the authorization request. The authorization server generates this ID for your application and uses it to retrieve its specific configuration settings.

This is a **required** parameter.

### The response type

The parameter `response_type` answers the question, **What** artifact is requested? It specifies the [type of authorization flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/which-oauth-2-0-flow-should-i-use) desired and determines what information will be returned by the authorization server (the artifact).

The parameter can take one of the predefined values `code` or `token`. The value `code` indicates that the client application wants to receive an authorization code, and consequently use the [Authorization Code flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow) or its [variant with PKCE](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce). The value `token` requests an access token and refers to the [Implicit flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post), which is generally no longer recommended except in very specific cases.

The parameter `response_type` can also have [a custom value](https://datatracker.ietf.org/doc/html/rfc6749#section-8.4) as a sequence of strings separated by spaces. For example, OpenID Connect, which is an extension of OAuth 2.0, [defines the value `id_token` and some combinations of values](https://openid.net/specs/oauth-v2-multiple-response-types-1_0-08.html).

This parameter is **required**.

### The response mode

The parameter `response_mode` tells the authorization server **how** the requested artifact should be returned. This parameter [has been added later to the original OAuth 2.0 specification](https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html), and its possible values are:

* `fragment`. This value tells the authorization server to attach the requested artifact as a fragment to the `redirect_uri` (see below). In other words, you will get for example an authorization code as follows:

  `https://my-app.com/callback#we7fhHdi2rl6Adywyy1p0ff`

  The value `fragment` is associated with the Implicit flow and is not recommended for several reasons, including information leaking and size limitations.  
* `query`. This value tells the authorization server to return the requested artifact as a parameter of the query string of the `redirect_uri`. The following is an example of authorization code returned as a parameter in the query string:

  `https://my-app.com/callback?code=we7fhHdi2rl6Adywyy1p0ff`

  Returning the artifact as a parameter of the query string has similar security concerns as the fragment option, although techniques like [Proof Key for Code Exchange (PKCE)](https://datatracker.ietf.org/doc/html/rfc7636) help mitigate the risks.

* `form_post`. This value requests the authorization server to return the artifact as an HTML form value and send it via POST. This value [has been added](https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html) to overcome the security concerns affecting the `fragment` and `query` modes.  
  The following is an example of response from the authorization server:

```http
HTTP/1.1 200 OK
Content-Type: text/html;charset=UTF-8
Cache-Control: no-cache, no-store
Pragma: no-cache

<html>
 <head><title>Submit This Form</title></head>
 <body onload="javascript:document.forms[0].submit()">
  <form method="post" action="https://my-app.com/callback">
    <input type="hidden" name="state"
     value="DcP7csa3hMlvybERqcieLHrRzKBra"/>
    <input type="hidden" name="id_token"
     value="eyJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ.eyJzdWIiOiJqb2huIiw
       iYXVkIjoiZmZzMiIsImp0aSI6ImhwQUI3RDBNbEo0c2YzVFR2cllxUkIiLC
       ...
       0uVAwBBb772-86HpAkGWAKOK-wTC6ErRTcESRdNRe0iKb47XRXaoz5acA"/>
  </form>
 </body>
</html>

```

The `response_mode` parameter is **optional**, so what is the default response mode from the authorization server when the parameter is not specified? It depends on the response type sent by the client application. The following table summarizes the default response mode corresponding to each `response_type` value:

<style>
  table {
    width: 80%;
    margin: 2.4rem auto !important;
    border-collapse: collapse;
    font-size: 15px;
  }
  table, td, th {
    border: 1px solid;
  }
  table th {
    line-height: normal;
    padding: .8em;
  }
  td {
    padding: .8em;
    line-height: normal;
  }
</style>

| *response\_type* | default *response\_mode* |
| :---- | :---- |
| code | query |
| token | fragment |
| id\_token | fragment |
| code token | fragment |
| code id\_token | fragment |
| id\_token token | fragment |
| code id\_token token | fragment |

> Note that the upcoming [OAuth 2.1 specification will deprecate](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13) the `token` response type, so all the response types containing `token` will be deprecated as well.

### The redirect URI

The `redirect_uri` parameter specifies **where** the authorization server will send the artifact. This is a very important parameter that defines the exact address in your application where the artifact is expected to be returned. Since this URL will receive sensitive data (authorization code or tokens), it is imperative to use HTTPS. OAuth 2.0 and OpenID Connect are strict about `redirect_uri` validation: the URI specified in the request must be an exact match of a pre-registered value on the authorization server. This strictness prevents malicious actors from hijacking tokens by redirecting them to an unintended location.  
This parameter is **required**.

### The scopes

The `scope` parameter explains **why** the client application is submitting this request. Consider that OAuth 2.0 (and consequently OpenID Connect) enables a client to work on behalf of a user, so the client must specify the user permissions it needs to perform its activities.

The value of the `scope` parameter is a sequence of strings separated by spaces expressing the needed permissions. OAuth 2.0 does not define the syntax of these strings, so you can freely define them. However, OpenID Connect defines [a few reserved scopes](https://auth0.com/docs/get-started/apis/scopes/openid-connect-scopes).

This parameter is **optional**, however it is [highly recommended to use it to enforce the principle of least privilege](https://auth0.com/blog/oauth2-access-tokens-and-principle-of-least-privilege/). If you don’t specify the `scope` parameter in your authorization request, the resulting behavior is [up to the specific authorization server](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3).

## The Security Parameters

The parameters described in the previous section are the core parameters of an authorization request. They reflect the essential elements the authorization server needs to formulate a response after the user’s approval.

However, additional parameters are crucial too to guarantee the security of the request/response transaction. Let’s explore the most common ones.

### The state

The `state` parameter has a unique value generated by the client application. Its primary function is to maintain session state between the client’s request and the server’s response, and to mitigate [Cross-Site Request Forgery (CSRF) attacks](https://auth0.com/blog/cross-site-request-forgery-csrf/). The authorization server must  include the same value in its response to the client to ensure that it’s related to the original request.

This parameter is not mandatory but **recommended**.

### The nonce

The `nonce` parameter has been introduced by the OpenID Connect specifications and it acts as an alternative to the `state` parameter for preventing CSRF and token injection attacks. Its unique value is generated by the client at request time. The authorization server will include the exact value of the `nonce` parameter in the `nonce` claim of the ID token. By comparing the value of the parameter with the value contained in the ID token, the client application is guaranteed that the ID token comes from its original request.

This parameter is **required** for the [Implicit flow](https://openid.net/specs/openid-connect-core-1_0.html#ImplicitAuthRequest) and in some cases of the [Hybrid flow](https://openid.net/specs/openid-connect-core-1_0.html#HybridAuthRequest), while it’s **optional** in other flows.

### The PKCE protection

An authorization request can include the `code_challenge` and `code_challenge_method` parameters. These parameters are needed to implement [Proof Key for Code Exchange](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce) (PKCE), an OAuth 2.0 extension that prevents authorization code interception attacks.

To implement PKCE, the client application generates a unique `code_verifier` value and sends its hashed version (`code_challenge`) to the authorization server. The client also includes the `code_challenge_method` parameter to let the authorization server know what hashing algorithm it used. The possible values for the `code_challenge_method` parameter are:

* `plain`, which means no hash,   
* `S256`, which means that the SHA256 algorithm has been used.

The `S256` value is the recommended value.

When the client application will exchange the authorization code for an access token, it will provide the `code_verifier` to prove it is the original requester.

PKCE also acts as a protection measure against CSRF attacks, so it may be used as an alternative to the `state` and the `nonce` parameters, assuming that the authorization server supports it.

The `code_challenge` parameter is **required** for public client like mobile and browser apps using the Authorization Code flow and unable to secure client secrets. While optional for confidential clients, it’s highly **recommended**.

## Additional Parameters

The parameters discussed so far can be considered the minimum essential parameters for formulating an authorization request and ensuring its security. However, you may encounter other parameters whose necessity and meaning depend on specific contexts. We won't examine all the other possible parameters you might find in an authorization request, but we'll simply mention a few to give you an idea of what to expect

### The prompt

The `prompt` parameter has been introduced by OpenID Connect and tells how the authorization server should interact with the user during authentication. Its possible values are:

* `none`. The authorization server must not display an authentication window. If the user is not already authenticated, an error will be returned.  
* `login`. The authorization server prompts the user for authentication even if they are already authenticated.  
* `consent`. The authorization server prompts the user for their consent before returning back to the application client.  
* `select_account`. The authorization server prompts the user to select an account if they have multiple of them.  
* `create`. The authorization server shows the user creation form instead of the login form.

Values for the prompt parameter can be combined. For example, you can find `prompt=login consent`, which tells the authorization server to always show the login and the consent forms. Of course, you can’t combine other values with `none`.

### The login hint

The `login_hint` parameter tells the authorization server what username to use to authenticate the user. Its value is used by the authorization server to prepopulate the login form. For example, you can find `login_hint=john.doe@example.com`, telling the authorization server to show a login form with the username set to `john.doe@example.com`.

### The request URI

The `request_uri` parameter has been introduced by the [Pushed Authorization Requests](https://datatracker.ietf.org/doc/html/rfc9126) (PAR) specification. This is a special parameter because it essentially replaces all other parameters except `client_id`. It is used in specific contexts where a high level of security is required. To learn more, I recommend reading [this article about Pushed Authorization Requests (PAR)](https://auth0.com/blog/what-are-oauth-push-authorization-requests-par/).

In short, PAR allows the client application to pre-register an authorization request and receive a request identifier from the authorization server. The `request_uri` parameter allows you to specify the identifier of the already registered request and thus express the authorization request, as in the following example:

```bash
https://my-tenant.auth0.com/authorize?
client_id=32tqG0PwnSoA2Ly4sw
&request_uri=urn%3Aietf%3Aparams%3Aoauth...4ltcg4eY28s
```

The authorization server will use the identifier specified in the `request_uri` parameter to detect the registered authorization request and consider the associated parameters.

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

## Conclusion

Understanding the anatomy of the OAuth 2.0 authorization request is a foundational skill for any developer working with modern authentication and authorization. While SDKs simplify much of the implementation, knowing the purpose of each parameter—from `client_id` and `response_type` to `scope` and `nonce`—empowers you to troubleshoot effectively, design secure applications, and adapt to evolving standards like OAuth 2.1 and OpenID Connect. This knowledge moves you beyond simply using a library to truly mastering the underlying security flows that protect your applications and users. 

Anatomy of an OAuth 2.0 Authorization Request

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

Learn how to prevent CSRF attacks from compromising your users when implementing Google OAuth for user registration and user login.

Growing an active user base is a top priority for all developers. Your product pages need copy, design, and engineering that can efficiently and effectively convert visitors into users. A visitor is an anonymous person browsing your site or app. A user is a visitor who exchanges some information to access more layers or features of your app. Even with just an email address or username, you can build a profile or identity for a user.

As such, user authentication is the backbone of conversion. User registration and login must be secure and as frictionless as possible. Long and tedious forms or requirements during registration can turn prospects away. Errors or downtime during login can frustrate even your most loyal customers, leading to dissatisfaction or support tickets.

## Why Use Google OAuth for User Authentication

A reliable way to implement user registration and authentication in an application and turn visitors into users quickly and securely is by using a registration and authentication system that your visitors already use and trust, such as Google.

As a developer, you can take advantage of Google's high security and trust Google as a source to safeguard user credentials so that you don't have to. Google social login leverages the OAuth 2.0 protocol for authorization and uses [OpenID Connect (OIDC)](https://developers.google.com/identity/openid-connect/openid-connect) as the standard for user authentication. You can delegate to Google's UI/UX and engineering the burden of password requirements, password protection, password error handling, email verification, profile data collection, and more. 

How easy or difficult is it to implement Google Login on your own? It depends. On the surface, it may be like a simple endeavor: In the JavaScript ecosystem, use a library like [`google-auth-library`](https://www.npmjs.com/package/google-auth-library), write a few lines of code, and call it a day.

While `google-auth-library` is a robust client library for using OAuth 2.0 authorization and authentication with Google APIs, it's essential to know how to use it effectively to avoid introducing security vulnerabilities in your application that could put your end-users and your organization at risk.

For instance, a recent [post on X](https://x.com/forgebitz/status/1858616526540042521) went viral: a developer named Klaas shared with the X developer community a code snippet on how to implement "google login with just the google-auth-library, no frameworks in 50 lines of code":

```typescript
export const googleLoginAction = {
  getAuthUrl: () => {
    const query = {
      client_id: oauth_google.client_id,
      redirect_uri: oauth_google.redirect_uri,
      response_type: "code",
      scope: oauth_google.scopes,
    };

    const url = new URL(oauth_google.endpoint);
    url.search = new URLSearchParams(query).toString();
    return url.toString();
  },
  verifyGoogleCode: async ({ code }: { code: string }) => {
    log.info({ code }, "verifying google auth code");

    try {
      const tokenResponse = await fetch("https://oauth2.googleapis.com/token", {
        method: "POST",
        headers: {
          "Content-Type": "application/x-www-form-urlencoded",
        },
        body: new URLSearchParams({
          client_id: oauth_google.client_id,
          client_secret: oauth_google.client_secret,
          code,
          grant_type: "authorization_code",
          redirect_uri: oauth_google.redirect_uri,
        }),
      });

      const tokenData = (await tokenResponse.json()) as { id_token: string };

      const ticket = await client.verifyToken({
        idToken: tokenData.id_token,
        audience: oauth_google.client_id,
      });

      const userData = ticket.getPayload();
      log.info({ userData }, "google auth successful");
    } catch (error) {
      log.error({ error }, "failed to verify google auth code");
      throw new Error("Failed to verify Google authentication");
    }
  },
};
```

Klaas' X post ignited a passionate discussion around user authentication and general security. As of the time of writing, the post had gathered 449k impressions, 4.7k likes, 387 reposts, and 83 comments.

## Google OAuth Implementation Can Go Wrong

Some of the commenters asked questions about the code's security posture, while others offered insights and advice on how to improve the security of that Google OAuth implementation.

Some commenters assumed the code was running on the client and were alarmed by the code handling a client secret, which could lead to a security compromise. Klaas clarified that the code is intended to run in the backend and [further explained its purpose as follows](https://x.com/forgebitz/status/1858776267266441324):

 "_this [code] has two simple functions, create a URL where you redirect the user to and a verify code function, you have the create a /callback (on the server) to get that URL. You still need to make authentication/authorization_"

Some other commenters pointed out that the code could be subject to a [Cross-Site Request Forgery (CSRF) attack](https://en.wikipedia.org/wiki/Cross-site_request_forgery), which confused others: How can there be a CSRF attack if there's no cookie involved or when the code does not run in the client?

First and foremost, let's recap what a Cross-Site Request Forgery (CSRF) attack is. [Andrea Chiarelli](https://auth0.com/blog/authors/andrea-chiarelli), Principal Developer Advocate at Okta, [summarizes a CSRF attack as follows](https://auth0.com/blog/cross-site-request-forgery-csrf/#--What-is-CSRF--):

- A typical Cross-Site Request Forgery (CSRF or XSRF) attack aims to perform an operation in a web application on behalf of a user without their explicit consent.
- The attacker leads the user to perform an action, like clicking a link.
- This action sends an HTTP request to a website on behalf of the user.
- If the user has an active authenticated session on the trusted website, the request is processed as a legitimate request sent by the user.

Andrea warns us that "even though CSRF attacks are commonly associated with session cookies, be aware that [Basic Authentication sessions](https://en.wikipedia.org/wiki/Basic_access_authentication) are also vulnerable to CSRF attacks" and that, in fact, "a CSRF vulnerability relies on the authenticated session management".

[Sandrino Di Mattia](https://x.com/sandrinodm) is a Senior Director on the Product Architecture team at Okta with robust and deep experience in cloud, identity, and security. In the thread, Sandrino commented that the code doesn’t seem to perform any state validation, making it open to CSRF attacks.

You may be wondering like others did: ["CSRF attack without any cookies, must be a new thing"](https://x.com/__morse/status/1858951728852295909). Let's explore how improperly implemented OAuth can lead to a CSRF attack.

## Cross-Site Reference Forgery (CSRF) Are Not About Cookies

Sandrino shares that CSRF is not related to cookies. Missing state validation is the most basic vulnerability in OAuth flows. [OAuth 2.0 specification recommends a `state` parameter](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1) that allows you to verify the authenticated state of your browser. The `state` parameter preserves the browser's authenticated state set by the client in an authorization request, and the authorization server makes it available to the client in the response.

[The `state` parameter helps you mitigate CSRF attacks](https://datatracker.ietf.org/doc/html/rfc6749#section-10.12) by using a unique and non-guessable value associated with each authentication request about to be initiated. That value allows you to prevent the attack by confirming that the value from the response matches the one you sent.

**But how does a CSRF attack work without cookies?**

Sandrino explains that an attacker can go through the OAuth flow but stop right when the redirect with the authorization code to the callback URL happens. Now, the attacker can send the link to the callback URL, including the code, to the victim, which consumes the code on their machine.

Depending on the implementation of your application, a few security, privacy, and data exploits could happen. For example, the attacker's account is now forced on the victim’s browser. The victim now could be uploading docs or filling in and sending personal data to the attacker's account, thinking it’s the victim's account. Or a worse scenario: the victim is already signed in, and now this new identity (the attacker's identity) is automatically linked to the victim's existing account.

## Prevent CSRF Attacks in Google OAuth

Sandrino advises us that preventing this type of attack takes a few lines of code. In practice, on redirect, you store a random value in a cookie. You then send that value to Google using the `state` param. On callback, you validate the incoming `state` parameter with the value in the cookie. If the `state` value in the response does not match the `state` value in the cookie, you reject the login operation and stop further access. The `state` parameter and PKCE can help prevent this type of attack.

> For a deep dive on this topic, you can consult the ["More Guidelines Than Rules: CSRF Vulnerabilities from Noncompliant OAuth 2.0 Implementations"](https://www.cise.ufl.edu/~butler/pubs/dimva15.pdf) paper from the Georgia Institute of Technology and the University of Florida. Check out section 3.3 on page 8.

There's a saying that goes: "You don't know what you don't know". But then, how can you know? By doing precisely what Klaas did: share code with others and be open to feedback and constructive criticism. At the same time, you can leverage the knowledge and expertise of others who have been through similar and more complex situations, which can help you avoid falling into traps or dangerous holes.

You may be thinking, "I can rely on AI for that!" You can use AI tools to learn and understand, but remember that those tools are imperfect, as they are an aggregation of human knowledge and can also make mistakes. There are instances where an AI tool can present you with "security" code with high confidence. Still, that code could be anything but secure, missing the implementation of security best practices or defensive mechanisms.

## Use Libraries to Implement Google OAuth 

It's important to highlight that if you want to implement a standard protocol yourself, you need to understand its specifications well, be aware of its nuances, and follow its details diligently. Instruments like the `state` parameter and all other security measures included in specifications and standards are the result of discussions and experience of industry experts throughout the years.

As developers, we often fall into the dilemma of reinventing the wheel (do it yourself) or relying on those who have already done it in the best way (use a library).

Sandrino suggested in the thread that it's better to use a library like Passport.js over the code shared on the tweet&mdash;or rather, X post. Passport.js implements OAuth 2.0 the way that the standard defines it. You can inspect the implementation of Google OAuth in Passport.js by looking at the [`lib/strategy.js`](https://github.com/jaredhanson/passport-google-oauth2/blob/master/lib/strategy.js) file of the [`passport-google-oauth20`](https://github.com/jaredhanson/passport-google-oauth2/tree/master) npm package.

The `OAuth2Strategy` from Passport is well-documented. The comments in the code can quickly guide you on what's happening through that flow:

- The Google authentication strategy authenticates requests by delegating to Google using the OAuth 2.0 protocol.
Applications must supply a `verify` callback function that accepts an `accessToken`, `refreshToken`, and service-specific `profile` and then calls another `cb` callback function, supplying a `user`. The `user` value should be set to `false` if the credentials are invalid. If an exception occurs, `err` should be set.

Let's see an example of how you'd use Google OAuth login with Passport.js:

```javascript
passport.use(new GoogleStrategy({
    clientID: '123-456-789',
       clientSecret: 'shhh-its-a-secret'
       callbackURL: 'https://www.example.net/auth/google/callback'
     },
     function(accessToken, refreshToken, profile, cb) {
       User.findOrCreate(..., function (err, user) {
         cb(err, user);
       });
     }
));
```

As you inspect the implementation code, you'll notice that Passport.js does much more than handle the login. [OAuth 2.0 provides consented access and restricts actions](https://auth0.com/intro-to-iam/what-is-oauth-2) of what a client app can perform on resources on behalf of the user without users ever sharing their credentials with the application. Using Google OAuth 2.0, you can also request access to user contacts and other resources on the Google platform. As the needs of your application scale, you may see yourself needing a more complex data access policy that calls for more code to write and maintain and more scenarios and edge cases to be aware of.

## Google OAuth Attacks Go Beyond CSRF Attacks

Security is an ever-evolving landscape. It's critical for you to stay on the vanguard regarding security in the industry, especially with the rise of artificial intelligence (AI). Implementing authentication on your own is an investment in money, risk, and time. Relying on robust, time-tested libraries or identity service providers can minimize some of those costs.

As mentioned in the post, implementing social login with Google OAuth for your app is just one piece of the authentication puzzle. Once you have users, you are responsible for protecting the data they entrust you. For example, depending on the region where you operate, you may be subject to regulations around user management and privacy, such as GDPR, which also extends to logs, not just the user data you have in your databases.

As you scale and grow in popularity, you may also gain unwanted attention from bad actors and attackers who may want what you are securing: rich user data. But, even on a small scale, you may become the target of bad actors looking to test their skills to break into apps.

> Recommended read: [The biggest underestimated security threat of today](https://techcrunch.com/2024/11/01/the-biggest-underestimated-security-threat-of-today-advanced-persistent-teenagers/)

In the X thread we have been discussing, Jared Hanson, the creator of Passport.js and a Principal Product Architect at Okta, validated that "checking a nonce or state is highly recommended." Jared added, "It’s less simple, but it protects against common attacks."

[Aaron Parecki](https://aaronparecki.com/), Director of Identity Standards at Okta, reminded me that it's not just CSRF attacks that are the concern when it comes to OAuth 2.0 flows. Even if you fix the CSRF attacks we have described, you could still be open to an OAuth 2.0 authorization code injection attack, which you can prevent with PKCE. You can learn more about that type of attack by watching the video below: 

<AmpContent>
<amp-youtube
    data-videoid="1ot45WwQWJE"
    layout="responsive"
    width="480" height="270">
</amp-youtube>
</AmpContent>
<NonAmpContent>
<div className='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/1ot45WwQWJE' frameborder='0' allowfullscreen></iframe></div>
</NonAmpContent>

Aaron also hosted an "OAuth Happy Hour", which includes [a demo of the authorization code injection attack](https://www.youtube.com/watch?v=moQidjdV5cw). Be sure to check it out!

Let us know if you'd like a detailed follow-up blog post covering the OAuth 2.0 authorization code injection attack.

## Aside: Use Auth0 to Implement Google Social Login

Auth0 makes it even easier to get started with Google. Every new tenant has the Google social connection enabled by default. You don't even have to set up a Google Cloud project to see Google social login in action. Auth0 maintains a set of developer keys you can use to start testing Google social login in your applications in development. Follow the ["Google Social Connection to Login"](https://developer.auth0.com/resources/labs/authentication/google-social-connection-to-login#introduction) lab to learn how to use those Google dev keys and set up ones for production.


Prevent CSRF Attacks in OAuth 2.0 Implementations

Learn what Pushed Authorization Requests are and when to use them to strengthen the security of your OAuth 2.0 and OpenID Connect-based applications.

In highly sensitive contexts, such as in financial or healthcare sectors, the security bar must be raised to prevent any breach of information and artifacts that could give unauthorized access to user data. [Pushed Authorization Requests (PAR)](https://datatracker.ietf.org/doc/html/rfc9126) is one extension that enhances OAuth 2.0  and OpenID Connect so that they can be securely used in these scenarios. Let's explore how this OAuth 2.0 extension works.

## Why use PAR?

Let's start by first understanding why you may need PAR and what problem it tries to resolve.

### The OAuth authorization request

If you have some experience with OAuth 2.0 and OpenID Connect, you know that the initial step that a client application must take to get the tokens it needs is to send an authorization request to the authorization server. For this purpose, the user's browser is redirected to the authorization server with a URL similar to the following:

```bash
https://your-authorization-server.com/authorize?
    client_id=1234567890&
    redirect_uri=https://your-app/callback&
    scope=openid profile email phone address&
    response_type=code&
    audience=https://myapi&
    state=12c1d32c1aba2cc14f9b907a9ec90
```

This authorization request URL is pretty basic, but you can add other parameters based on the [OAuth flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow) you are using or on the specific extension/customization your authorization server implements. For example, if you are using the [Authorization Code Flow with PKCE](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce), you should also add the `code_challenge` and `code_challenge_method` parameters. In Auth0, you can also specify the `organization` or `invitation` parameters if you are using the [Auth0 Organizations](https://auth0.com/docs/manage-users/organizations) feature, and so on. The complexity of the authorization request can grow considerably depending on your specific use case.

### What's the problem with the authorization request?

As you can see, the authorization request is nothing but a GET HTTP request against a URL with its parameters:

```http
GET /authorize?
    client_id=1234567890&
    redirect_uri=https%3A%2F%2Fyour-app%2Fcallback&
    scope=openid%20profile%20email%20phone%20address&
    response_type=code&
    audience=https%3A%2F%2Fmyapi&
    state=12c1d32c1aba2cc14f9b907a9ec90 HTTP/1.1
Host: your-authorization-server.com
```

In this form, it may raise a few concerns:

- **The authorization request can be altered**. Usually, the client application redirects the user's browser to the authorization server with the authorization URL. Nothing prevents a malicious actor from changing one or more parameters of this request before sending it to the authorization server.
- **No guarantee of the request's provenance**. The authorization request is normally built by the client application, and the user's browser is in charge of sending it to the authorization server. However, there is no guarantee that the request has been built by the client application. Anyone can build an authorization request once they know a few data, such as the client ID and the redirect URI.
- **No guarantee of confidentiality**. Although the browser sends the authorization request via HTTPS, the request parameters can be intercepted by third-party applications, such as a proxy, a load balancer, or even a browser plugin. A malicious network component of this type can inject or change the request parameters, not to mention that the request itself can be logged.
- **Browser limitations**. Finally, a very complex query string in the authorization request may incur [possible browser limitations on URL length](https://stackoverflow.com/questions/417142/what-is-the-maximum-length-of-a-url-in-different-browsers).

This is where Pushed Authorization Requests come into play.

## How PAR Works

The basic idea of Pushed Authorization Requests is very simple: instead of redirecting the user's browser to make the authorization request with all the parameters, the client application *pushes* that request directly to the authorization server with a POST request and gets an identifier for that request. Now, the client application redirects the user's browser to the authorization server with just that identifier to make its authorization request, avoiding exposing all the details.

### The PAR endpoint

The first requirement for an authorization server supporting PAR is to expose the PAR endpoint. This is an additional endpoint that will accept authorization requests with the parameters in the payload. The following example shows how a request to the PAR endpoint looks like:

```http
POST /oauth/par HTTP/1.1
  Host: your-authorization-server.com
  Content-Type: application/x-www-form-urlencoded
  client_id=1234567890&
  client_secret=<YOUR_SECRET>&
  redirect_uri=https%3A%2F%2Fyour-app%2Fcallback&
  scope=openid%20profile%20email%20phone%20address&
  response_type=code&
  audience=https%3A%2F%2Fmyapi
```

Notice the reference to the `/oauth/par` path and how the parameters are passed through POST. You can see some differences between the parameters passed in the standard GET-based authorization request and this request. Apart from the usual parameters such as `client_id`, `redirect_uri`, `scope`, etc., you may notice that the `client_secret` is passed here. This is a request coming from a [confidential client](https://auth0.com/docs/get-started/applications/confidential-and-public-applications#confidential-applications), that is, a client capable of securely storing a secret, such as a server-running application. By passing `client_id` and `client_secret`, the request is authenticated by the authorization server resolving the confidentiality concerns we discussed earlier.

> The PAR specification does not limit access to the PAR endpoint to confidential clients only. It states that "*the rules for client authentication as defined in [[RFC6749](https://datatracker.ietf.org/doc/html/rfc6749)] for token endpoint requests, including the applicable authentication methods, apply for the PAR endpoint as well.*"
>
> This entails that even public clients can potentially access the PAR endpoint. However, their public nature does not allow them to safely determine their identity, so some of the concerns about the integrity and confidentiality of the request still remain in this case.

As a response to this request, the authorization server will respond with something like the following:

```http
HTTP/1.1 201 Created
Content-Type: application/json

{
  "request_uri": "urn:ietf:params:oauth:request_uri:6esc_11ACi5bwq064ltcg4eY28s",
  "expires_in": 30
}
```

The authorization server's response is a JSON object with two properties:

- `request_uri`. This is the identifier of the authorization request pushed by the client application.
- `expires_in`. This is the number of seconds that the authorization request is valid.

With these basic notions, let's take a look at how the whole authorization process works.

### The PAR authorization flow

The following diagram illustrates the OAuth authorization flow using PAR:

![Pushed Authorization Request flow](https://images.ctfassets.net/23aumh6u8s0i/6FWUrUsNmimPr10XuqI26k/984cf829065bab1dacd1a6dafc08e92c/pushed-authorization-requests-flow.png)

Here are the steps highlighted in the diagram:

1. The client application sends an authorization request to the PAR endpoint of the authorization server.

2. The authorization server authenticates the application client, validates the request, and stores it. Then, it replies with a response containing the authorization request's identifier (`request_uri`) and the validity time (`expires_in`).

3. The client application uses the `request_uri` to build the authorization request URL for the user's browser and redirects it to the authorization server. The authorization request URL will look like the following:

   ```bash
   https://your-authorization-server.com/authorize?
       client_id=1234567890&
       request_uri=urn%3Aietf%3Aparams%3Aoauth...4ltcg4eY28s
   ```

4. The user's browser sends a GET request to the authorization server using the authorization request URL received by the client application. The authorization server retrieves the authorization request identified by the `request_uri` value, and from now on, the usual steps of the requested OAuth flow are carried out.

As you can see, the browser's request no longer contains the details of the authorization request. There is no risk of tracking or in-transit manipulation of the request. Also, the complexity of the URL is considerably reduced.

## PAR Metadata

OAuth and OpenID Connect servers publish the configuration metadata in the `/.well-known` URI to publicly declare the supported capability and other protocol details. PAR specification adds two new keys to this metadata:

- `pushed_authorization_request_endpoint`. This key defines the PAR endpoint where the client application can push the authorization request and get the corresponding  `request_uri`.
- `require_pushed_authorization_requests`. This key has a boolean value indicating whether using PAR is mandatory (`true`) or optional (`false`). If this key is not present, the default value is `false`.

With this metadata, your application can check if an authorization server supports PAR using the usual [discovery approach](https://auth0.com/docs/get-started/applications/configure-applications-with-oidc-discovery).

## PAR and Auth0

Auth0 supports PAR as part of the [Highly Regulated Identity](https://auth0.com/docs/secure/highly-regulated-identity) add-on of the Enterprise plan. Highly Regulated Identity is Auth0's implementation of FAPI 1, the set of standards that raises the security level to protect application operations in sensitive contexts, such as finance, healthcare, e-commerce, etc.

By default, PAR is not active in an Auth0 tenant. You have to enable it at the tenant level to make the PAR endpoint available to your applications. You can do it through your Auth0 dashboard. Follow [the steps described here to enable PAR](https://auth0.com/docs/get-started/applications/configure-par#set-par-for-a-tenant) in your Auth0 tenant.

Once you enable PAR at the tenant level, your applications can use the classic authorization endpoint or the PAR endpoint. If you want to make the endpoint mandatory for a specific application, you should require it at the Auth0 application configuration level. You can use the Auth0 dashboard or the Auth0 Management API to set PAR endpoint mandatory. Follow [these instructions](https://auth0.com/docs/get-started/applications/configure-par#set-par-for-an-application) to enable mandatory PAR for your application.

<include src="SignupCTA" text="Try out Auth0 authentication for free." linkText="Get started →" />

## Conclusion

Pushed Authorization Requests (PAR) are a great addition to strengthen the security of OAuth 2.0 and OpenID Connect protocols. As you have learned, it enables client applications to make authorization requests without exposing the details of the call to potential tracking and manipulation.

This security improvement is critical in scenarios where data confidentiality must be preserved, and Auth0 offers PAR support through Highly Regulated Identity (HRI). Combined with other strong security enhancements supported by HRI, you can build applications with high-security standards and comply with the most common regulations. Check out this document to learn more about [Highly Regulated Identity](https://auth0.com/docs/secure/highly-regulated-identity).



What Are OAuth Pushed Authorization Requests (PAR)?

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

jimena-garbarino

Jimena is an experienced result and value-oriented programmer with a strong engineering background. She excels with Ruby on Rails, Java, and Scrum development. She has worked in web development for 10+ years in many industries and has a master's degree in software engineering from Universidad de Buenos Aires.

Spring Cloud Developer

Jimena Garbarino

Implementing OpenID Connect authentication in Java Web Applications with Okta Spring Boot Starter and Spring Security support for Authorization Code Flow with PKCE

Proof Key for Code Exchange (PKCE) in Web Applications with Spring Security

Let’s explore the latest security enhancements in the OAuth 2.0 specification.

OAuth 2.0 is now widely adopted, but some security concerns remain. Recently, two new specifications were released to improve OAuth 2.0 security and address some of these concerns: *Demonstrating Proof of Possession* (DPoP) and *Step-Up Authentication Challenge Protocol*. Let’s take a high-level look at them to understand how they work.

## Demonstrating Proof of Possession (DPoP)

The most popular artifact associated with OAuth 2.0 is the access token. This token, as well as the refresh token, is a **bearer token**, and [there is a specification on how to use it](https://datatracker.ietf.org/doc/html/rfc6750). As mentioned in that specification, a fundamental feature of a bearer token is "that any party in possession of the token (a "bearer") can use the token in any way that any other party in possession of it can."

While this feature simplifies the token management, it raises some security concerns. In fact, if a bad actor manages to steal an access token, they can use it without any problem. Therefore, some [security measures](https://datatracker.ietf.org/doc/html/rfc6750#section-5) should be taken to mitigate potential threats.

> Read [this article to learn more about access tokens and how they differ from ID tokens](https://auth0.com/blog/id-token-access-token-what-is-the-difference/).

[Demonstrating Proof of Possession (DPoP)](https://www.rfc-editor.org/rfc/rfc9449) is a mechanism designed to restrict who can use an access or refresh token. With this mechanism, the authorization server issues a token that is bound to the requesting client, so that no one other than that specific client can use the access or refresh token. In other words, a token issued by using DPoP is no longer a bearer token.

### Request a DPoP access token

The client using an access token with DPoP must prove that it is the legitimate recipient of the token. This is done using public key cryptography: the client must prove that it has the private key of the public/private key pair. But let's go in order to understand how DPoP works with a standard OAuth 2.0 flow.

For simplicity, we will use the [Authorization Code flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow), but the same applies to the other flows. The high-level steps are listed below:

1. The user is redirected to the authorization server with a request to initiate the flow.
2. The authorization server authenticates the user and redirects them back to the application with an authorization code.
3. The client application generates a public/private key pair and creates a DPoP proof, which is a JWT containing the public key and the method and URI of the HTTP request where it will be used. This also binds the DPoP proof to a specific HTTP request.
4. The client application sends the authorization code to the authorization server to request an access token. The HTTP request includes the DPoP proof in the `DPoP` header field. The following is an example of access token request with DPoP proof:

```http
POST /token HTTP/1.1 
Host: server.example.com 
Content-Type: application/x-www-form-urlencoded 
DPoP: eyJhbGciOiJFUzI1NiIsInR5cCI6ImRwb3Arand0IiwiandrIjp7Imt0eSI6IkVDIiwiY3J2I...  
grant_type=authorization_code 
&code=3LgurgEWbtafaqTn2VxkASV 
&redirect_uri=https%3A%2F%2Fapp.example.com 
```

5. The authorization server validates the DPoP proof by checking the signature and the request details (HTTP method and URI). It then generates a hash of the client's public key (JWK thumbprint) and embeds it in the access token. For non-JWT access tokens, the JWK thumbprint can be checked through the [introspection endpoint](https://www.rfc-editor.org/rfc/rfc7662.html). Finally, the authorization server sends the access token with the JWK thumbprint to the client application.

### Use a DPoP access token

When the client application needs to call a protected API, it performs the following steps:

1. The client application creates a new DPoP proof bound to the HTTP request it's about to make.
2. The client sends the access token in the `Authorization` header field of the HTTP request using the `DPoP` scheme. It also provides the DPoP proof in the `DPoP` header field. The following is an API call example with DPoP proof:

```http
GET /protectedresource HTTP/1.1 
Host: api.example.com 
Authorization: DPoP eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K0pXVCIsImNuZiI6eyJqa3QiOiJybW56aTJvSWNYW...
DPoP: eyJhbGciOiJFUzI1NiIsInR5cCI6ImRwb3Arand0IiwiandrIjp7Imt0eSI6IkVDIiwiY3J2I...
```

3. In addition to the standard access token validation, the API also validates the DPoP proof to make sure that this request comes from the intended sender.

While using DPoP provides more security than the simple bearer token, this does not mean that there are no threats to DPoP access tokens. Take a look at [the security considerations in the DPoP specification](https://www.rfc-editor.org/rfc/rfc9449#section-11) to learn more.

> To learn [the details about DPoP, check out this article](https://auth0.com/blog/protect-your-access-tokens-with-dpop/).

## Step-Up Authentication Challenge Protocol

A second security enhancement to OAuth 2.0 has been introduced with the [Step-Up Authentication Challenge Protocol specification](https://www.rfc-editor.org/rfc/rfc9470.html), which has our [Vittorio](https://auth0.com/blog/authors/vittorio-bertocci/) as its author along with [Brian Campbell](https://www.pingidentity.com/en/resources/blog/author/brian-campbell).

This specification adds [Step-Up Authentication](https://auth0.com/blog/what-is-step-up-authentication-when-to-use-it/) to OAuth 2.0-protected APIs to enforce stronger authentication requirements when a risky operation is requested by a client. In other words, when a client calls a critical API endpoint, the server checks that the access token meets specific authentication requirements, and if it's doesn't, it returns an error response to the client with directions on what is required.

### The step-up authentication flow

Basically, the high-level flow has the following steps:

1. The client sends a request to a critical API endpoint including the access token.
2. The API endpoint extracts information about user authentication from the access token.
3. If the user authentication information meets the authentication requirements for that endpoint, the request is processed. Otherwise, the API endpoint returns an error response that includes the authentication requirements.
4. The client requests a new access token from the authorization server that meets the authentication requirements.

### The authentication requirements

The specification defines two types of authentication requirements:

- *Authentication Context Class Reference* (ACR): This requirement indicates one or more specific authentication methods. For example, it can specify that Multi-Factor Authentication (MFA) is required.
- *Maximum Authentication Age*: This requirement specifies the elapsed time since the last *active* user authentication. An active user authentication occurs when the user is actively involved, for example by entering a username and password. An implicit authentication due to a still valid authenticated session is not considered an active user authentication.

These requirements are embedded in a JWT access token through the standard `acr` and `auth_time` claims. For non-JWT access tokens, the requirements can be verified through the [introspection endpoint](https://www.rfc-editor.org/rfc/rfc7662.html).

<include src="SignupCTA" text="Try out Auth0 authentication for free." linkText="Get started →" />

## Summary

This article provided a high-level overview of the new specifications released in September 2023 to improve the security of OAuth 2.0. The DPoP specification defines a mechanism to bind an access token to the client application that requested it, overcoming the risks associated with bearer tokens. The Step-up Authentication Challenge Protocol defines a way to request more stringent authentication requirements when accessing a critical resource or requesting a risky operation from a client.

OAuth 2.0 Security Enhancements

alisa-duncan

Alisa Duncan is a Senior Developer Advocate at Okta, a full-stack developer, and a community builder who loves the thrill of learning new things. She is a Google Developer Expert in Angular and organizes coding workshops and community events locally and internationally. Her background is primarily working on enterprise software platforms, and she is a fan of all things TypeScript and JavaScript.

Senior Developer Advocate

Alisa Duncan

OAuth 2.0 provides a more secure model than API keys for machine-to-machine communication. Learn why.

Why You Should Migrate to OAuth 2.0 From API Keys

A walk-through of building a microservices architecture with JHipster, Keycloak, Auth0, and Google Kubernetes Engine (GKE) deployment.

Identity in Spring Boot with Kubernetes, Keycloak, and Auth0

andrew-hughes

Andrew is a senior web app developer with 15+ years of experience and solid expertise with React, Node, and React Native, as well as tons of SQL/NoSQL knowledge. He has performed complicated back-end API integrations for clients, including payment platforms like Stripe and PayPal along with InfusionSoft and WordPress. His extensive professional background also includes working with PHP, Laravel, Java, and Swift/iOS.

Andrew Hughes

Learn how to use Java and embedded Jetty to create a simple servlet-based web service. Then see how to do it with Spring Boot.

Get Started with Jetty, Java, and OAuth

I stream, blog, and make youtube videos about tech stuff. I love coding, I love AI, and I love building stuff!

Staff Developer Advocate

Juan Cruz Martinez

amin-abbaspour

G'day. I look after Professional Services in APAC. I'm passionate about helping customers build and secure their applications and get the best value out of their investment with Auth0. Besides work, I love spending time with my kids, Ryan and Adeline, as well as reading, weightlifting and watching NRL (National Rugby League).

Lead Solutions Architect

Amin Abbaspour

Learn how to add user authentication to Flutter apps using OAuth 2.0 and OpenID Connect.

Get Started with Flutter Authentication

matt-raible

Matt Raible is a well-known figure in the Java community and has been building web applications for most of his adult life. For over 20 years, he has helped developers learn and adopt open source frameworks and use them effectively. He's a web developer, Java Champion, and Developer Advocate at Okta. Matt is a frequent contributor to open source and a big fan of Java, IntelliJ, TypeScript, Angular, and Spring Boot. 

Developer Advocate

Matt Raible

Use JHipster to build a photo-sharing app for web and mobile that has a React front-end with OIDC authentication and a Spring Boot back-end with OAuth2 authorization.

Integrate React Native and Spring Boot Securely

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

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

Find out how you can handle the Instagram API deprecation using Auth0's account linking feature.



## Legacy Instagram API Deprecation

The [Legacy Instagram API](https://www.instagram.com/developer/) will be shutting down on **March 31, 2020**, in favor of the [Instagram Graph API](https://developers.facebook.com/docs/instagram-api) and [Instagram Basic Display API](https://developers.facebook.com/docs/instagram-basic-display-api).

This means that if you have implemented [Instagram authentication through the legacy API](https://www.instagram.com/developer/authentication/), your Instagram users will no longer be able to sign in to your application starting March 31, 2020.

Instagram now requires developers to use the [Facebook Login](https://developers.facebook.com/docs/instagram-api/getting-started) flow instead, so you'll need to re-implement authentication using the [Instagram Graph API](https://developers.facebook.com/docs/instagram-api) and re-submit your application to Instagram for review.

The new [Instagram Basic Display API](https://developers.facebook.com/docs/instagram-basic-display-api/) does allow you to get a user access token, but this cannot be used for authentication. As noted in the [Instagram documentation](https://developers.facebook.com/docs/instagram-basic-display-api):

> Note: Instagram Basic Display is not an authentication solution. Data returned by the API cannot be used to authenticate your app users or log them into your app. If you need an authentication solution, we recommend using Facebook Login instead.

If you try to do this anyway, your application will be rejected at the review stage.

These changes can cause a headache if you have users that are still using the legacy Instagram login, and you haven't had time to implement Facebook Login instead. Fortunately, Auth0 has a simple solution.

## How Auth0 can Handle Instagram API Deprecation

If you're still using the Legacy Instagram API for Instagram login, you can take advantage of [Auth0's user account linking](https://auth0.com/docs/users/concepts/overview-user-account-linking) feature for a quick fix.

### What is account linking

Auth0 offers a simple way to take two or more separate accounts and [link them into one profile](https://auth0.com/docs/users/concepts/overview-user-account-linking#automatic-account-linking). For example, when a user logs in with email and password, you can [create a rule](https://auth0.com/docs/rules) that automatically links any other accounts using that same email.

### Account linking for Instagram

If you have users that are only using Instagram for login and you're using the Legacy Instagram API, you can still take advantage of account linking, even though they don't yet have another account to link.

You can create a [user-initiated account linking](https://auth0.com/docs/users/concepts/overview-user-account-linking#user-initiated-account-linking) solution that runs when a user tries to sign in with Instagram.

Once they log in, you'll display a message that they will no longer be able to sign in to their account after March 31, 2020, and they need to choose another method such as email/password or a different social provider.

You'll list the authentication options on that page so that the user can sign up right then. After they sign in with their new account, you'll then be able to link the old Instagram account to the new account.

![Auth0 account linking](https://images.ctfassets.net/23aumh6u8s0i/5x4IVeFoam2v0q55S8TiqT/722bc8ad4fbae49e98f0184c2ea85353/spa-user-settings)

Now, the user will still be able to access their account, and you won't need to go through the trouble of migrating to the new Instagram API if you're only using it for authentication.

> Note: The first step in this method requires the user to still authenticate with Instagram. If you'd like to take advantage of Auth0's account linking, you must notify your users of the upcoming change and instruct them to create their new account before March 31, 2020.

<include src="asides/AboutAuth0" />

If you have any questions about account linking with Auth0, please reach out in the comments or click the "Talk to Sales" button in the header. You can also <a href="https://auth0.com/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> now to explore the dashboard.


Handling Instagram API Deprecation with Auth0 Account Linking

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

Everything you always wanted to know (but were afraid to ask)

OAuth2 Implicit Grant and SPA

ramiro

I am an internet guy who loves reading and asking questions—those are the two things that helped me the most as an autodidact 🤓. If I am not learning about the latest trends in digital marketing or listening to house music, you can probably find me watching a tennis tournament. And also, I manage Social Media at Auth0 ✌️

Manager, Social Media

Ramiro Nunez Dosio

Our 10 most-popular identity posts in 2018 ranging from auth standards to web authentication.



Time flies when you are having fun. It's December already and we are getting ready to wrap up this year. 2018 was a prolific year for the Auth0 blog: we published more than 200 posts (😱) where we tackled a diverse amount of topics: frontend and backend technologies, data breaches, GDPR, Cybersecurity, Company Culture, and of course, Identity.

We believe looking back is key to look ahead. That is why this week, we are going to take a look back at the best and most impactful posts we have published in 2018.

One article wouldn't be enough to review this amazing year, that's why we have decided to split this year in review into 3 parts: [Developer Posts](https://auth0.com/blog/10-most-popular-developer-posts-in-2018/), [Security Posts](https://auth0.com/blog/10-most-popular-security-posts-in-2018/), and Identity Posts.

Without much further ado, here's the roundup of our 10 most-popular Identity posts this year!

![Auth0's 10 Most-Popular Identity Posts](https://images.ctfassets.net/23aumh6u8s0i/2PZojrBsthRTB6sKxDI0nw/cf5db7303eafa89f7ef46b4bc5f05e81/identity-posts)

## Auth0's 10 Most-Popular Identity Posts in 2018

> The following posts are not listed in any particular order.

1. <a href="#an-overview-of-open-standards" target="_self">An Overview of Open Standards</a>
2. <a href="#3-iam-examples-to-support-digital-transformation" target="_self">3 IAM Examples to Support Digital Transformation</a>
3. <a href="#a-look-at-the-draft-for-jwt-best-current-practices" target="_self">A Look at The Draft for JWT Best Current Practices</a>
4. <a href="#introduction-to-web-authentication-the-new-w3c-spec" target="_self">Introduction to Web Authentication: The New W3C Spec</a>
5. <a href="#how-to-have-a-successful-idm-project" target="_self">How To Have a Successful IDM Project</a>
6. <a href="#how-to-have-a-successful-idm-project-part-2" target="_self">How To Have a Successful IDM Project (Part 2)</a>
7. <a href="#on-the-nature-of-oauth2s-scopes" target="_self">On The Nature of OAuth2’s Scopes</a>
8. <a href="#hashing-passwords-one-way-road-to-security" target="_self">Hashing Passwords: One-Way Road to Security</a>
9. <a href="#adding-salt-to-hashing-a-better-way-to-store-passwords" target="_self">Adding Salt to Hashing: A Better Way to Store Passwords</a>
10. <a href="#how-utilities-can-use-ciam-to-avoid-3-common-problems" target="_self">How Utilities Can Use CIAM to Avoid 3 Common Problems</a>

## <a name="an-overview-of-open-standards"></a>1. [An Overview of Open Standards](https://auth0.com/blog/an-overview-of-open-standards/)

In this overview, we will go over what open standards are and why they matter. We will also go over the top open standards used for identity including OAuth 2, OpenID Connect, JWT, and SAML. Open standards are important to understand but one can easily get overwhelmed by the technical specifications.

<include src="ClickImg" externalUrl="https://auth0.com/blog/an-overview-of-open-standards/" imgUrl="https://cdn.auth0.com/blog/10-most-popular-identity-posts-in-2018/open-certificationpng.png" altText="Open Certification" imgWidth="560" imgHeight="560"/>

## <a name="3-iam-examples-to-support-digital-transformation"></a>2. [3 IAM Examples to Support Digital Transformation](https://auth0.com/blog/3-iam-examples-to-support-digital-transformation/)

From basic website authentication to implementing an OpenID Connect server and API authentication: This article covers 3 IAM examples to support your Digital Transformation.

<include src="ClickImg" externalUrl="https://auth0.com/blog/3-iam-examples-to-support-digital-transformation/" imgUrl="https://cdn.auth0.com/blog/iam-digital-transform/sso-data-model.png" altText="SSO Data Model" imgWidth="714" imgHeight="559"/>

## <a name="a-look-at-the-draft-for-jwt-best-current-practices"></a>3. [A Look at The Draft for JWT Best Current Practices](https://auth0.com/blog/a-look-at-the-latest-draft-for-jwt-bcp/)

In this post, we will take a look at the draft for the JWT Best Current Practices document. This document describes common pitfalls and attacks related to the use of JWTs, and how to implement mitigations against them. Read on!

<include src="ClickImg" externalUrl="https://auth0.com/blog/a-look-at-the-latest-draft-for-jwt-bcp/" imgUrl="https://cdn.auth0.com/blog/jwt-bcp/Substitution-Attack-Different-Recipient.png" altText="Different Recipient JWT Substitution Attack" imgWidth="590" imgHeight="492"/>

## <a name="introduction-to-web-authentication-the-new-w3c-spec"></a>4. [Introduction to Web Authentication: The New W3C Spec](https://auth0.com/blog/introduction-to-web-authentication/)

Web Authentication brings a stronger authentication mechanism to the masses by defining an API that both authenticators and web browsers can implement. Learn why Google, Paypal, Mozilla, and others back it up.

<include src="ClickImg" externalUrl="https://auth0.com/blog/introduction-to-web-authentication/" imgUrl="https://cdn.auth0.com/blog/webauthn/1-Web-Authentication-Entities.png" altText="Web Authentication Entities" imgWidth="617" imgHeight="409"/>

## <a name="how-to-have-a-successful-idm-project"></a>5. [How To Have a Successful IDM Project](https://auth0.com/blog/how-to-have-a-successful-idm-project/)

Learn how to create a realistic project plan to have a good Identity Management project deployment.

<include src="ClickImg" externalUrl="https://auth0.com/blog/how-to-have-a-successful-idm-project/" imgUrl="https://cdn.auth0.com/blog/good-idm-project/enabling-mfa.png" altText="Eanbling Multi-factor Authentication (MFA) from Auth0" imgWidth="617" imgHeight="361"/>

## <a name="how-to-have-a-successful-idm-project-part-2"></a>6. [How To Have a Successful IDM Project (Part 2)](https://auth0.com/blog/how-to-have-a-successful-idm-project-part-2/)

Learn how to plan for failures and changes in your identity project.

<include src="ClickImg" externalUrl="https://auth0.com/blog/how-to-have-a-successful-idm-project-part-2/" imgUrl="https://cdn.auth0.com/blog/how-to-have-a-successful-idm-project-part-2/resetting-a-users-multi-factor-account-with-auth0.png" altText="Resetting a user's multi-factor account" imgWidth="617" imgHeight="439"/>

## <a name="on-the-nature-of-oauth2s-scopes"></a>7. [On The Nature of OAuth2’s Scopes](https://auth0.com/blog/on-the-nature-of-oauth2-scopes/)

Auth0 Principal Architect and Identity expert Vittorio Bertocci on why using OAuth2 scopes in every authorization scenario is not a good idea.

<include src="ClickImg" externalUrl="https://auth0.com/blog/on-the-nature-of-oauth2-scopes/" imgUrl="https://cdn.auth0.com/blog/on-the-nature-of-oauth2-scopes/oauth2-scopes-mail-api.png" altText="OAuth2 Scopes Mail API exmaple" imgWidth="617" imgHeight="280"/>

## <a name="hashing-passwords-one-way-road-to-security"></a>8. [Hashing Passwords: One-Way Road to Security](https://auth0.com/blog/hashing-passwords-one-way-road-to-security/)

A strong password storage strategy is critical to mitigating data breaches that put the reputation of any organization in danger. Hashing is the foundation of secure password storage.

<include src="ClickImg" externalUrl="https://auth0.com/blog/hashing-passwords-one-way-road-to-security/" imgUrl="https://cdn.auth0.com/blog/hashing-one-way-road-to-security/hash-flow.png" altText="Hashing algorithm flow example - one-way" imgWidth="617" imgHeight="340"/>

## <a name="adding-salt-to-hashing-a-better-way-to-store-passwords"></a>9. [Adding Salt to Hashing: A Better Way to Store Passwords](https://auth0.com/blog/adding-salt-to-hashing-a-better-way-to-store-passwords/)

A salt is added to the hashing process to force their uniqueness, increase their complexity without increasing user requirements, and to mitigate password attacks like rainbow tables

<include src="ClickImg" externalUrl="https://auth0.com/blog/adding-salt-to-hashing-a-better-way-to-store-passwords/" imgUrl="https://cdn.auth0.com/blog/adding-salt-to-hashing-a-better-way-to-store-passwords/password-salt-example.png" altText="Example showing how using a salt with hashing produces unique hashes." imgWidth="617" imgHeight="277"/>

## <a name="how-utilities-can-use-ciam-to-avoid-3-common-problems"></a>10. [How Utilities Can Use CIAM to Avoid 3 Common Problems](https://auth0.com/blog/how-utilities-can-use-ciam-to-avoid-3-common-problems/)

Customer identity and management technology helps utilities reshape how they interact with users, improve their services, and tighten security.

<include src="ClickImg" externalUrl="https://auth0.com/blog/how-utilities-can-use-ciam-to-avoid-3-common-problems/" imgUrl="https://cdn.auth0.com/blog/how-utilities-can-use-ciam-to-avoid-3-common-problems/progressive-profiling-flow.png" altText="Utility customer progressive profiling flow" imgWidth="617" imgHeight="303"/>

## What's Next?

We are already preparing our content pipeline for 2019. Identity and digital transformation are key areas that will keep businesses evolving to tackle challenges around privacy, usability, growth, and sociopolitical policies. We are committed to keep our content relevant to these changes and offer effective solutions through our products and services.

We'd like to take this opportunity to thank all of our readers for their consistent support and feedback. Is there anything that you'd like us to cover in 2019? Any particular identity topic or trend? Please let us know in the comments below or through social media ([Twitter](https://twitter.com/auth0), [LinkedIn](https://www.linkedin.com/company/auth0)). As always, you can subscribe to our newsletter to receive a weekly digest of our blog content.

Happy Holiday Season!

<include src="asides/AboutAuth0" />


10 Most-Popular Identity Posts in 2018

332d7898dae6bc56031ac3507a0248ba

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

Developer Experience Engineer

Steve Hobbs

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

Build and Secure APIs with Scala and the Play Framework

30b8d1b7c0dab4bb311c121a47a6aae9?s=80 avatar

30b8d1b7c0dab4bb311c121a47a6aae9?s=80

Guest Author

Vladimir Fomene

Learn how to secure your Spring Boot APIs and your SPAs with OAuth 2.0.

Securing Spring Boot APIs and SPAs with OAuth 2.0

Stretching OAuth2 scopes beyond intended usage leads to trouble in complex architectures.



**TL;DR:** Scopes only come into play in delegation scenarios, and always limit what an app can do on behalf of a user: a scope cannot allow an application to do more than what the user can do.

Although stretching scopes beyond that usage is possible, it isn’t trivial or natural – contrary to what common naïve narratives would want you to believe.

<include src="TweetQuote" quoteText=".@vibronet on why using OAuth2 scopes in every authorization scenario is not a good idea."/>

## The Problem

OAuth2 scopes are misunderstood. Developers are victim of the “man with a hammer” syndrome here — **scopes are the only primitive defined in OAuth2 that has something to do with authorization, and as a result people use them in every authorization scenario** — even the ones for which they weren’t conceived. Just like Newtonian laws are enough to tackle simple problems, the same can be said for those naïve uses of scopes — but as soon as architectures get more complicated, people discover (often painfully) that they need to rethink things in quantum terms to get out of trouble.

It certainly doesn’t help that protocol specs aren’t too prescriptive on this point — a common ailment in OAuth2 — but a deeper read usually helps to clarify things. Circumstantial evidence/spec intent and context on one side, “laws of physics” on the other leave little room for interpretation.

Let me stress: most misunderstandings I discuss here come from legitimate authorization requirements; scopes just happen to be the wrong artifact to carry them. If anything, this points to the need for more prescriptive guidance on the matter (for a primer, see [Jared Hanson’s session at Identiverse](https://www.youtube.com/watch?v=eEI4ShHPh-8)).

Here’s an extra note to clarify further what I am trying to do here, given that I expect some people will push back hard when their beliefs are challenged.

Like everything that doesn’t really exist in ground reality, **the semantic of scopes is entirely in our head**: a consensual hallucination where we all agree on the meaning of the term — hence formally you are free to refuse the entire premise of this post and use “scope” to mean whatever you like. The main selection criteria I am using here is, what’s the choice of meaning that will be best conducive of us “thinking good thoughts,” as in taking decisions that will make our solutions work reliably? That’s a terribly relative, very arbitrary thing to establish — one that doesn’t scale linearly. Heuristic for prime numbers is super handy and we could embrace it, but if we need to work beyond a certain number it will stop working: our intended range determines whether the heuristic takes care of our needs, or it’s a dangerous oversimplification that will force us to backtrack and rip out a lot of logic in the process. Same with scopes: we can hold on to simplified views and revel in their apparent neatness, and feel the burn when we go beyond trivial cases and start having to architect serious shit.

## Scopes Inception

To all intents and purposes, scopes didn’t really exist before OAuth. The quintessential use case OAuth was devised for is a simple scenario, which has been presented ad nauseam already. LinkedIn asks for your Gmail password so it can use it to log in as you in Gmail, programmatically harvest your contacts (via API/scraping/etc) and spread itself; but knowledge of your Gmail password allows LinkedIn to do far more than that (e.g. sending mails on your behalf, read your messages, etc) and put the secrecy of your credentials at risk.

OAuth shows up, devises a mechanism for LinkedIn to ask Gmail just for the action it requires (access contacts) and nothing else — and makes all this possible without ever sharing with LinkedIn your gmail credentials. Done. Scopes happen to be the primitive that OAuth2 introduced for allowing LinkedIn to request delegated access to your Gmail’s contacts, to the exclusion of everything else. Intent clear and mission accomplished, right?

To me, that would be enough to demonstrate my thesis (scopes only come into play in delegation scenarios, and always limit what an app can do on behalf of a user; they are not meant to grant the application permissions outside of the privileges the delegated user already possesses). However, I know that this scenario alone won’t be enough to convince everyone: a classic objection is “fine, that might have been the original intent, but that doesn’t mean that they can’t be successfully used for more scenarios!.” Fair. Let’s dig deeper and explore more ramifications.

<include src="TweetQuote" quoteText="Scopes only come into play in delegation scenarios, and always limit what an app can do on behalf of a user."/>

## Scopes as Claims

What I described so far is all about using scopes for asking for permissions. **OAuth2 says nothing about scopes being claims in access tokens**, given that access tokens (ATs from now on) don’t need to carry claims at all (ATs are shapeless, per OAuth — and per OpenId Connect as well: only id_tokens are defined as JWTs). Nonetheless, the belief that scopes can be used to express authorization beyond delegated scenarios is deeply entrenched in the assumption that scopes do travel in the access token in form of claims. More precisely, the essence of the problem lies the conviction that **the presence of a scope claim in an access token invests the bearer with its corresponding permission, and that a resource (API, etc) being invoked with such a token can/should grant the corresponding access level without any further check**. It is pretty easy to show that in the general case, that logic wouldn’t work.

To set up our counterfactual, let’s entertain the notion that we are indeed using ATs in a specific format (JWT) carrying scope claims. Here there’s a corollary of the thesis: in the general case, scopes alone in an access token are not enough to carry on authorization decisions. Stealing my own thunder, I’ll tell you the two reasons why that’s the case: 1) the resource visible at the OAuth level isn’t usually the real resource requiring authorization, and 2) the authorization server isn’t omniscient. Let me unpack this through examples: I’ll use Azure AD because the Microsoft Graph is a really good example of this phenomenon.

## The OAuth2 Resource Isn’t The Real Resource

Say that I want my web app to call an API to list all the email messages of the currently signed in user. I request an AT for invoking the Microsoft Graph, and I request the scope **Mail.Read**. Once I get it, I make my web app call **me/messages**, and get a nice list of emails. All is good.
Now, let me make a small change to the call syntax. Instead of me/messages, I’ll call **users/guid/messages**. Still works, awesome! No surprise there.

Here’s the twist. Let me repeat that call, this time asking for the messages for another user. I don’t think anyone would be surprised to see the request result in a 400. And yet, my AT carried the **Mail.Read** scope! The point here is that **the scope is only saying to the authorization server (AS) what the app can do on the user A’s behalf**, which means that the app can list messages just like user A would, but cannot list messages for user B regardless of the presence **Mail.Read** scope. In other words, **Mail** in **Mail.Read** is a resource type, a family of resources — not a specific instance of inbox. But at access time, the specific inbox being requested does matter. Intuitive, right? If the API behavior would be any different we would be in serious trouble. Figure 1 provides a visual summary of the scenario.

![OAuth2 Scopes Mail API exmaple](https://images.ctfassets.net/23aumh6u8s0i/1fcJ0pv60sB1eWrQm9w7KX/8d076bb0f3982735272e00616af27388/oauth2-scopes-mail-api)

_Figure 1: A token carrying the scope Mail.Read indicates that the app can gain delegated access to the user’s mailbox. That scope doesn’t grant to the app privileges that the user doesn’t have: attempts to access another user’s mailbox will fail._

This is an example of 1). The resource we are asking a token for is an API offering a façade for multiple, more granular resources — with their own lifecycle, permissions, privileges and authorization rules. The scope in this scenario is not expressing one of those finer-grained, “ground reality” resources. The true resources in this example are really the inboxes of each user, and that was carried by the REST call rather than the token used to secure it… and the authorization decision emerged from combining the scope **Mail.Read** (without which we wouldn’t have bothered doing anything else), the identifier of the user (carried through a different claim in the token) and the entity requested (in the URL of the entity, hence in the actual call).

But the solution is simple, then! Let’s just describe those sub-level resources at the OAuth2 level, let’s surface the true resource in the protocol — so that scopes can finally express actual privileges. That is sometimes possible, if the resources you are exposing are ultra-simple, which usually means they don’t exist outside of your API. In term of “thinking good thoughts,” I am still somewhat against that. The fact that you might concoct cases where scopes express authorization directives context-free doesn’t make the aforementioned context-dependent scope uses disappear: if your access control logic now assumes scopes to be of the context-free kind (and more importantly, if you/your developers now understand scopes in those terms), your access checks will be too permissive when you do receive classic delegated scopes as you’ll take the permissions in the incoming scopes as directives, without making the further contextual checks they require (“Sure, he got mail.read — but does he own this inbox?”).

However, that’s not the biggest problem with using scopes to represent granted permissions (as opposed to delegated ones). The biggest challenge derives from the fact that permissions are always resource specific, and that transfers a lot of complexity to the AS and the tokens it issues. Resources can be very numerous, leading to A LOT more token requests than in the general case; they can have heavily decentralized life cycles, which makes it hard for the AS to know enough about assigned permissions (or learn about it in timely fashion) to be able to express that as claims; and permissions on an individual resource can be numerous and/or verbose, leading to unmanageably large tokens.

To make things more concrete, think of the case in which the resources being accessed are documents in some repository. According to the naïve view I sketched earlier, we can turn scopes from a delegated hint (which requires the resource to intersect the delegated permission in the scope, with the actual user privileges on lower-level resource being requested to obtain the effective permissions reflected in the access control logic) to an actual assigned privilege (the sheer presence of the scope is all the resource need to grant access, without checking anything elsewhere) just by directly expressing the document itself in our token request, rather than a generic API for accessing documents in the repository. The scenario is on display in Figure 2.

![OAuth2 Scopes assigned privilege example](https://images.ctfassets.net/23aumh6u8s0i/iZG02a9fyVSgvSZF08yFc/fcbcbd01ab22dd2402556d45c43d64fd/oauth2-scopes-doc-api)

_Figure 2: it is possible to surface at the protocol level the actual resources being accessed; it is also possible to relieve the web API from the need to keep track of access policies, relying entirely on the claims included with the incoming token. However the price to pay is an omniscient AS and more tokens than the approach shown in Figure 1 required._

Note: The mechanism we use for expressing that in the request to the AS doesn’t matter for the purpose of this discussion. for example, we can add a prefix to the scope string to point to the exact document we want, followed by the action we request (e.g. <documentID>:read), although in a real system it would make a big difference in term of usability.

The approach hinges on the assumption that the AS knows every resource, and knows all the policies governing who has access to what — and in what terms. This is represented by the access policies store in Figure 2. Armed with that knowledge, the AS can immediately evaluate whether the requestor has indeed the privileges corresponding to the permissions being requested and A) refuse to issue a token if the requirement aren’t met or B) issue a token containing a statement that access policies have been evaluated and the user should be allowed to perform the requested operation. In the case of B), any resource trusting the AS (and any resources whom delegated its full access management policies to the AS, a function NOT enshrined in either OIDC or OAuth) would simply follow the authorization directive contained in the token.

Now, let’s ignore for a moment that there’s no reason for such a statement to travel in a scope claim — one can pick ANY claim type without the need to overload an entity meant for a different scenario and make scopes consuming logic more complicated. Regardless of what claim is used, requesting a different token for each different document would create a very large increase in traffic. It’s not uncommon to see repositories with millions of documents, even in mid-sized businesses. Imagine the traffic generated by a simple thumbnail generator for a folder, multiplied for all the concurrent users across all the apps portfolio of the company, and all the ripples downstream to that (e.g. increase in size for token caches for offline use, increased lookup time to use those caches, etc., etc.).

Then there’s the matter of how many privileges you’d want to transmit in a token. Although having a client request different tokens for read and write operations is possible, that would exacerbate the tokens explosion challenge; but batching all the privileges a user has for a given document would be problematic as well, as the token itself could become very large. Expressing claims by reference is always possible, but having to make an API call for evaluating a claim would somewhat defeat the purpose of having scopes as a simple, immediately consumable source of truth for all things authorization.

## The Authorization Server Isn’t (Usually) Omniscient

But finally, the biggest problem of all is that having to keep the AS in the loop whenever documents are created, destroyed or assigned in different capacity to users is a daunting task — one that isn’t done even in much simpler settings than cloud and distributed systems based on public networks.

Think of how access to files is regulated in Unix or Windows: the domain controller doesn’t keep track of every file’s ACL — every file has a local policy, which is evaluated at access time rather than at ticket generation time. If OSes have to rely on resource side policies, despite all the simplifying conditions they enjoy (homogeneous resource types; constant line of sight with the domain controller; reliable network operations; etc), how could we expect this to be mainstream in the far more challenging public cloud scenario?

Now, technically all of this can be done. But it requires A LOT of work, very precise assumptions about the resources types and lifecycle, a very flexible AS, and so on — far from the naïve assumption that given that the ‘A’ in “AS” stands for “authorization”, all authorization logic can be centralized in the AS and all authorization decisions can be expressed as scopes values.

## In Summary

In the general case, scopes are used to express what an application can do on behalf of a given user — and that is always a subset of what the user can do in the first place. In other words, scopes are used for handling delegation scenarios. Resources are responsible to combine the incoming scopes and the actual user privileges to calculate the call’s effective permissions and make access control decisions accordingly.

Again in the general case, overloading scopes to represent actual privileges assigned to the app (as opposed to the delegated permissions mentioned above) is problematic — as it requires the AS to have specialized authorization knowledge at a granularity that is often not practical to achieve and maintain; even in the case in which that’s viable, the increase in traffic and token size might still render the approach unfeasible.

That is not to say that the AS should not make authorization decisions; if the AS happens to have access to data and logic that make it possible to take authorization evaluations at token issuance time, those can certainly be reflected in the decision of withholding issuance, or in the content of the issued token — but there’s no reason for the latter to be expressed in scopes claims, and doing so can in fact contribute to keep alive the urban legend that made me spend about half of a long flight writing this also long post.


On The Nature of OAuth2’s Scopes

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

Embed Multi-Factor Authentication using push notifications, SMS, or TOTP anywhere, taking full control of the experience.



We are pleased to announce the availability of our [Multi-Factor Authentication API](https://auth0.com/docs/api-auth/tutorials/multifactor-resource-owner-password). Up to now, we have provided support for MFA through a simple switch in the Auth0 Dashboard, following our premise of *simplicity* and ease of use. However, we also believe in providing powerful *building blocks* for our users. For this reason we have developed a new API to perform the full MFA flow, even with multiple authenticators, in a flexible and convenient way. In this article we will take a look at the API and build a simple CLI app to demonstrate how to use it. Read on!

<include src="TweetQuote" quoteText="The MFA API is now available, learn how to embed MFA in your apps taking full control of the experience!"/>

> **Note**: for most MFA scenarios, we still recommend the use of [Universal Login](https://auth0.com/docs/hosted-pages/login) whenever possible. This new API is meant for advanced use cases where Universal Login is not flexible enough. [Universal Login is the best alternative](https://auth0.com/blog/authentication-provider-best-practices-centralized-login/) in most cases.

---

## Why?
Up to now, enabling MFA at Auth0 was simply a matter of flipping a switch and optionally selecting which application you wanted to enable MFA for. When MFA is enabled, hitting the `/authorize` endpoint or starting an authorization flow through one of our libraries was enough to trigger MFA. Simple, convenient.

![MFA Switch](https://images.ctfassets.net/23aumh6u8s0i/4Fk1xnLP6wm5Ay24YJLeex/c7047fc95a6712dfa7a92f5b7c5522e7/1-mfa-enable)

However, some of our customers have requested to have more control over the MFA process. For this reason, we have been working with [ATEA Norge](https://www.atea.no/) and other customers under a private BETA program to find the right implementation for this feature. The result: a new API for MFA to give back control to you when required. Let's check it out.

> **Note**: for most MFA scenarios, we still recommend the use of [Universal Login](https://auth0.com/docs/hosted-pages/login) whenever possible. This new API is meant for advanced use cases where Universal Login is not flexible enough. [Universal Login is the best alternative](https://auth0.com/blog/authentication-provider-best-practices-centralized-login/) in most cases.

## A Simple API
The API works by introducing some changes to how the `/token` endpoint behaves. Let's take a look.

<include src="TweetQuote" quoteText="The new MFA API is simple, it works on top of the existing /token endpoint."/>

The API works in four simple steps:

1. Access token request to `/token`.
2. Challenge request to `/challenge`.
3. Asking the user for a code (if necessary).
4. Final request to `/token`.

> This scenario assumes the user is already enrolled in MFA and has at least one authenticator enabled. There's also a [new API for enrollment](https://auth0.com/docs/multifactor-authentication/api/otp) to have full control over the enrollment process. This API also allows for obtaining a list of associated authenticators, useful for using multiple authenticator, as we will see in step 2 below.

### 1. Access Token Request to `/token`
When a request is made to the `/token` endpoint to get an access token, normally you either get an error, or you get an access token. However, when the MFA API is enabled, the `/token` endpoint may return a new error code: `mfa_required`.

```
POST /oauth/token HTTP/1.1
...

{
  "username": "...",
  "password": "...",
  "grant_type": "password"
  ...
}
```

Response:

```
HTTP/1.1 403 Forbidden
...

{
  "error": "mfa_required",
  "mfa_token": "..."
}
```

The `mfa_token` in the response value must be used in the following requests.

> MFA is also supported for the `refresh_token` [grant type](https://auth0.com/docs/applications/application-grant-types). This allows for use cases in which you want to require 2FA (TOTP, SMS, push notifications) when refreshing an access token, useful for extra security and step-up authentication.

### 2. Perform an MFA Challenge
When the `mfa_required` error is returned, the client must then perform a `challenge`. This is done by sending a request to the `/mfa/challenge` endpoint.

```
POST /mfa/challenge HTTP/1.1
...

{
  "mfa_token": "<from step 1>",
  "challenge_type": "otp oob",
  "authenticator_id": "optional, if known"
}
```

Response:

```
HTTP/1.1 200 OK
...

{
  "challenge_type": "oob",
  "binding_method": "prompt",
  "oob_code": "..."
}
```

The response tells the client which type of authenticator will be used (`challenge_type`) and also returns additional arguments relevant for that method. The `binding_method` parameter tells the client it should ask the user for a code.

The client may optionally request a specific authenticator through `authenticator_id`. This allows for multiple authenticators, even for the same resource.

> `OOB` means "out-of-band". All methods that are not [TOTP](https://auth0.com/blog/from-theory-to-practice-adding-two-factor-to-node-dot-js/) are OOB.

### 3. Prompt For Input (If Necessary)
If the `challenge_type` is `otp` or the `binding_method` parameter is set to `prompt`, the client should ask the user to input a code before continuing.

### 4. Get The Access Token
Finally, a new request to the `/token` endpoint is performed.

```
POST /oauth/token HTTP/1.1
...

{
  "mfa_token": "<from step 1>",
  "oob_code": "<from step 2, optional>",
  "binding_code": "<from step 3, if 'binding_method' === 'prompt'>",
  "otp": "<from step 3, if challenge_type === 'otp'>",
  "grant_type": "<one of two strings, see below>"
}
```

Grant type must be one of two values:
- For OTP: `http://auth0.com/oauth/grant-type/mfa-otp`
- For OOB: `http://auth0.com/oauth/grant-type/mfa-oob`

Response:

```
HTTP/1.1 200 OK
...

{
  "access_token": "...",
  "expires_in": "...",
  ...
}
```

Note that certain methods do not require the user to input anything (push notifications, for example). For those cases, this request must be performed repeatedly until an access token is returned or the authorization is denied. If the client is expected to repeat the request again in the future (after a certain amount of time) the response will be:

```
HTTP/1.1 400 Bad Request
...

{
  "error": "authorization_pending"
}
```

This means the user has not performed any actions yet and the client should wait a bit before trying again. The `error` can also be `slow_down` if the client is not waiting enough between requests.

That's it! If all went well, you now have an access token issued through MFA!

## Example: A CLI App with MFA
To give you a better understanding of how the API works we have developed a [simple CLI app that uses MFA](https://github.com/auth0-blog/oauth2-mfa-cli-example).

<video src="https://cdn.auth0.com/blog/oauth2-mfa-api/cli-demo-2.m4v" controls autoplay loop></video>

Take a look at the [full code in GitHub](https://github.com/auth0-blog/oauth2-mfa-cli-example). You will find the interesting bits in the `/token-endpoint.mjs` file, particularly in the `token` function.

To use the app, make sure that:
- You have created a new [Application](https://manage.auth0.com/#/applications) in the Auth0 Dashboard. Select the `Machine-to-Machine type`.
- The `token authentication method` is set to `none` in the Auth0 Application settings.
- You have enabled the `Password` and `MFA` grants in `Application -> Advanced Settings -> Grant Types`.
- You have MFA enabled. Go to [Multifactor Auth](https://manage.auth0.com/#/guardian) and enable SMS and push notifications for [Guardian](https://auth0.com/docs/multifactor-authentication/guardian/user-guide).
- You have set the right client ID (get this from the [application](https://manage.auth0.com/#/applications) settings area) in the MFA rule in the [Multifactor Auth](https://manage.auth0.com/#/guardian) section. Otherwise MFA will be enabled for all clients.

To use the app simply do:

```sh
git clone git@github.com:auth0-blog/oauth2-mfa-cli-example.git
cd oauth2-mfa-cli-example
npm install
node src/index.js login
```

The app supports some other commands. You can take a look at them by running it with no arguments.

## Other Use Cases
The sky is the limit! Here are some scenarios where using the new MFA API could make sense:

- Protect a VPN like OpenVPN (Pritnul) or Juniper with a second factor.
- Integrate with a PAM module to do second factor with SSH.
- Integrate with an LDAP service to provide a second factor.
- Step up authentication when refreshing an `access_token` (`refresh_token` grant).
- Trigger second factor from any backend process.

You are now free to build powerful MFA flows wherever you want!

## Conclusion
The MFA API brings flexibility to the use of MFA in your apps. One thing you may have noticed is that we are using the [OAuth 2.0 `/token` endpoint](https://tools.ietf.org/html/rfc6749#section-3.2). In fact, we designed this to be compatible with OAuth 2.0 right from the start. We have prepared two specification drafts, [one for MFA](https://github.com/jaredhanson/draft-oauth-mfa/blob/master/Draft-1.0.txt), [the other for authenticator association](https://github.com/jaredhanson/draft-oauth-mfa-assoc/blob/master/Draft-1.0.txt), to be sent to the [IETF OAuth 2.0 Working Group](https://tools.ietf.org/wg/oauth/). Other implementations of OAuth 2.0 can follow these specifications to implement MFA in a flexible, yet powerful way, while remaining compatible. We will have more information about this in an upcoming post.

We can't wait to see how you use this API to build powerful multi-factor flows! Let us know what you think in the comments.

<include src="TweetQuote" quoteText="We can't wait to see how you use this API to build powerful multi-factor flows!"/>


Introducing the Multi-Factor Authentication API

In this tutorial we implement centralized logins for iOS both manually and using the Auth0 SDK.

Add Authentication To Your iOS Apps with Centralized Login

avatar

Sathyaish Chakravarthy

Learn how to create a simple application using Kotlin, a statically typed programming language that targets the Java Virtual Machine (JVM)

Create an Application in Kotlin and Secure It Using JWTs

Learn how to implement social logins on Android with Facebook, Google, Twitter and Instagram as providers

"oauth2"