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

A new ebook is available to explain why FAPI is essential for regulated industries, and how to move beyond OAuth bearer tokens for top identity security.

FAPI for Developers: Here Is Your Guide


Learn the critical differences between OAuth State, Nonce, and PKCE. Discover how these parameters prevent CSRF, replay attacks, and code interception.

When building secure authentication and authorization flows, the [OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749) and [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) (OIDC) specifications are the industry standard. But as developers, we quickly encounter a few cryptic parameters that can be a major source of confusion: `state`, `nonce`, `code_challenge`, and `code_verifier`. The last two are tied to a security mechanism known as [Proof Key for Code Exchange](https://datatracker.ietf.org/doc/html/rfc7636) (PKCE).

All these parameters appear to be random secret strings passed around during the login flow. This leads to common and sometimes dangerous questions: Are they interchangeable? Does PKCE replace the need for `state`? If I'm using `state`, do I still need `nonce`?

The short and emphatic answer is: **No, they are not interchangeable.**

Think of them as three distinct security specialists, each guarding a different door at a different stage of the authentication process. Using one does not and cannot do the job of the others. They work together to create a layered defense that protects your application and your users from a variety of attacks.

To better understand them, let’s analyze them one by one, looking at the specific problem each one was designed to solve.

## The State Parameter: Preventing OAuth CSRF

Let's begin with the `state` parameter. It exists to answer a simple question for your application: **"Is this the incoming login response I actually requested?"**.

Its entire purpose is to prevent a class of attacks known as [**Cross-Site Request Forgery (CSRF)**](https://auth0.com/blog/cross-site-request-forgery-csrf/).

### The Attack: Cross-Site Request Forgery (CSRF)

Imagine a user who is logged in to their online bank. In another browser tab, they visit a malicious website. That website might have a hidden link or form that crafts a fake OAuth authorization response and sends it to the callback URL of the user’s online bank, as shown below:

```shell
https://online-bank.com/callback?code=FAKE_CODE_FROM_ATTACKER
```

This is a "forged request." The attacker is *tricking* the user’s browser into sending a request to their bank application that the user *did not initiate*. Without a `state` parameter, your application's callback endpoint might receive this fake code. If the attacker is clever, they could potentially use this vector to trick the bank application into associating the user's session with the *attacker's* account, a "login CSRF" attack.

### The Solution: Add the State Parameter

The `state` parameter solves this by acting as a "claim check." It's an opaque, random, and unguessable string that your application generates **before** the authentication flow even begins.

The flow becomes a secure, verifiable loop. First, your client application generates this unique `state` value. It then *saves* this value, typically in the user's session or a secure short-lived `HttpOnly` cookie. This value is now tied to *this specific user's browser session*.

Next, your application redirects the user to the authorization server's login page and includes the `state` value as a query parameter in the URL. The authorization server knows nothing about this value; its only job is to hold onto it and **echo it back, unmodified**, when it redirects the user back to your application.

When the user returns to your `redirect_uri` (or "callback URL"), the *very first thing* your application must do is compare the `state` value in the incoming request with the `state` value it stored in the user's session.

If they match, this is a legitimate response. Your application can confidently say, "I recognize this. This is the response to the request I sent out just moments ago for *this specific user*". You can now proceed to the next step: exchanging the authorization code.

If they do not match (or if the `state` is missing), this is a red alert. This request is unsolicited. It did not originate from your application, or it's being sent to the wrong user. Your application **must** reject the request immediately, log the attempt, and show an error.

The `state` parameter is your application's way of maintaining context across the HTTP redirects and ensuring the response it's processing is not a forgery.

## The Nonce Parameter: Preventing ID Token Replay

Next, we have `nonce`. This parameter is specific to OpenID Connect (OIDC), which is the authentication layer built on top of OAuth 2.0. If you are *only* using OAuth for *authorization* (getting an access token for an API), you won't use a `nonce`. But if you are using OIDC to *log a user in* and get an [ID token](https://auth0.com/blog/id-token-access-token-what-is-the-difference/), the `nonce` parameter is critical.

The `nonce` (a "number used once") exists to answer a different question: **"Is this ID token I just received *actually* for the login I just initiated?"**.

Its primary job is to prevent **ID token replay attacks**.

### The Attack: ID Token Replay

An ID token is a signed [JSON Web Token (JWT)](https://www.jwt.io/introduction). It's a digital identity card that proves *who* the user is and *when* they authenticated. But what if an attacker somehow intercepts a valid ID token from a previous legitimate login?

The attacker could try to "replay" this token to your application. They could try to trick your application into starting a new login flow and then, at the right moment, substitute their *stolen* (but still validly signed) ID Token. Without a `nonce`, your application might accept this token. It would check the signature, see it's valid, and log the attacker in *as the user from the stolen token*.

### The Solution: Add the Nonce Parameter

The `nonce` parameter solves this attack by cryptographically binding the ID token to the *specific client session that requested it*.

The flow is similar to `state` but has a crucial difference in *where* it's verified. Just like `state`, your client application generates a unique unguessable `nonce` value **before** the redirect and stores it in the user's session. It sends this `nonce` value in the [authorization request](https://auth0.com/blog/anatomy-of-an-oauth2-authorization-request/) alongside the `state`.

The authorization server, upon authenticating the user, takes the `nonce` value you sent and **embeds it as a claim inside the ID token's JWT payload**, as in the following example:

```json
{
  "iis": "https://your-domain.auth0.com",
  "sub": "1234567890",
  "name": "John Doe",
  "nonce": "q-385k-2Pc7",
  "iat": 1516239022,
  "exp": 1516240022
}
```

When your application receives the ID token (typically after exchanging the authorization code), its verification process is now twofold. It must, of course, validate the token's signature. But it *also* must:

1. Decode the ID token.  
2. Extract the nonce claim from inside the token.  
3. Compare this `nonce` claim against the `nonce` value it stored in the user's session.

If they match, the application knows this ID token was *just* minted and was created specifically for *this* login request. If they do not match, this is a replay attack. The token is either old or was intended for a different session. Your application **must** reject it.

This ensures that even a validly signed ID token cannot be reused to impersonate a user in a new login flow.

## PKCE: Securing the Authorization Code

Finally, we come to PKCE. This is a more recent extension to OAuth 2.0, initially meant for [public clients](https://auth0.com/docs/get-started/applications/confidential-and-public-applications), but it is now considered a mandatory best practice for *all* client types.

PKCE answers a question for the *authorization server*: **"Is the client exchanging this authorization code for a token the *same client* that originally requested the code?"**.

It was designed to prevent **authorization code interception attacks**.

### The Attack: Authorization Code Interception

This vulnerability is most dangerous for public clients, like mobile apps and browser-based Single Page Applications (SPAs). These clients cannot securely store a client secret because any code bundled in an app or running in a browser can be reverse-engineered.

In the standard [Authorization Code flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow), the authorization server sends an authorization code back to the client's `redirect_uri`. On a mobile device, this might involve a custom URL scheme (for example, `my-app://callback?code=...`). A malicious app on the same device could register itself to handle the *same* URL scheme, intercept this callback, and *steal the authorization code*.

The attacker, having stolen the code, could send it to the token endpoint. And since the token endpoint for a public client didn't require a client secret, the server had no way to know this *wasn't* the legitimate app. It would happily trade the stolen code for a valid access token, giving the attacker full access to the user's account.

### The Solution: Use PKCE

PKCE prevents this attack by requiring the client to prove it's the same one that started the flow. It's a cryptographic extension that works like a two-part secret handshake.

The flow now involves two new values. First, **before the redirect**, your client application generates a unique, random, high-entropy string called the `code_verifier`. This is the *secret*.

Second, your client transforms the `code_verifier` (usually using a SHA-256 hash and then Base64-URL-encoding it) to create a `code_challenge`. This is the *public* part of the secret.

Your application saves the secret `code_verifier` in its local storage. It then sends the public `code_challenge` (and the hashing method) to the authorization server in the initial authorization request (along with `state` and `nonce`). The authorization server stores this `code_challenge`, associating it with the authorization code it's about to generate.

When the user returns, the client receives the authorization code (which an attacker might still intercept). Now, the crucial step: when the client goes to the `/token` endpoint to exchange the code, it includes the authorization code *and* the original, secret `code_verifier` it had saved.

The authorization server receives this request and performs its check:

1. It takes the `code_verifier` from the request.  
2. It hashes it using the same method the client said it would use.  
3. It compares the result to the `code_challenge` it stored earlier.

If they match, the authorization server knows the client on the other end of this request is the *exact same client* that initiated the flow. It's safe to issue the tokens.

If they do not match, this is an imposter. The attacker only had the code, not the original `code_verifier` secret. The authorization server **must** reject the request.

PKCE effectively creates a dynamic one-time secret for every login flow, protecting the code from theft and misuse, even for clients that live in insecure environments.

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

## Why You Need All Three

It should now be clear that these three parameters are not redundant. They are a perfect example of layered security, protecting different assets at different stages of the process, as the following diagram shows:

![Diagram showing where State, PKCE, and Nonce are verified in the OAuth 2.0 and OIDC authentication flows.](https://images.ctfassets.net/23aumh6u8s0i/2t9QcxUTJSwtMXDRiGRfVz/ee823255803bdce5916f042ba1d296b7/state-nonce-pkce.png)

Following the numbered steps, let's visualize an attacker's very bad day trying to break into a *properly secured* OIDC flow:

1. **CSRF Attack.** The attacker crafts a malicious link with a fake auth code and sends it to a logged-in user.  
   The user's browser sends the request to the client's `redirect_uri`. The client checks for a `state` parameter in the URL, compares it to the one in the user's session, finds it's missing or mismatched, and rejects the request.  
   The `state` parameter protected the **authorization request step**.  
2. **Code Interception Attack.** The attacker is on the user's mobile device and successfully intercepts the *real* authorization code from a legitimate login.  
   The attacker sends the stolen code to the token endpoint. The authorization server, which is expecting a PKCE flow, asks for the `code_verifier`. The attacker doesn't have it.  
   PKCE protected the **code exchange step**.  
3. **Token Replay Attack.** The attacker somehow bypassed all this and got their hands on a *valid ID token* from a previous session. They initiate a new login and try to send this stolen token to the client.  
   The client, which just initiated a *new* login, has a *new* `nonce` stored in its session. It decodes the attacker's stolen ID Token, looks at the `nonce` claim inside, and sees it doesn't match the one in the session.  
   The `nonce` parameter protected the **token issuing/validation step**.

You are not "choosing" between `state`, `nonce`, and PKCE. You are leveraging all three to build a fortress around your authentication flow.

## Comparison Summary

Now you have a clear understanding of `state`, `nonce`, and PKCE. Keep these concepts handy with the following summary table:

![Comparison table summarizing the purpose, attack vector, and verification steps for State, Nonce, and PKCE.](https://images.ctfassets.net/23aumh6u8s0i/6dvoCIgginxQN74zM88ooF/05383b8015d793634ec63e968bce9e56/state-nonce-pkce-table.png)

Demystifying OAuth Security: State vs. Nonce vs. PKCE

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

deepu-sasidharan

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

Deepu K Sasidharan

Learn how Auth0 Token Vault uses OAuth 2.0 Token Exchange to provide secure, delegated access, letting AI agents act on a user's behalf without handling refresh tokens.

Auth0 Token Vault: Secure Token Exchange for AI Agents

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

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

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

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

## What is the Principle of Least Privilege?

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

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

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

## OAuth 2.0 and its Role in Access Control

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

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

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

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

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

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

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

### No scopes, No party!

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

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

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

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

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

### Designing granular scopes

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

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

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

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

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

### Leveraging hierarchical scopes

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

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

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

### Using dynamic scopes

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

### Ensuring user consent

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

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

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

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

## Beyond Scopes: Advanced Token Security and Validation

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

### Token validation best practices

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

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

### Short-lived access tokens and refresh tokens

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

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

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

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

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

## Security Review Checklist for Access Token-Based Systems

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

**Scope and Permissions**

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

**Token Issuance and Lifecycle**

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

**Token Validation at the Resource Server**

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

## Conclusion

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

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

OAuth 2.0 Access Tokens and the Principle of Least Privilege

jess-author

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

Sr. Developer Advocate

Jessica Temporal

Learn about the new classification of MCP servers as OAuth Resource Servers, implementing Resource Indicators to prevent token misuse, and the clearer security best practices designed to help you build more robust and secure MCP applications

As developers, we're building the next generation of applications on a foundation of interconnected services. The Model Context Protocol (MCP) is rapidly becoming a key part of that foundation, enabling seamless context sharing between AI models and applications. But as adoption grows, how do we ensure the connections we build are secure?

The [latest changelog](https://modelcontextprotocol.io/specification/2025-06-18/changelog), released on June 18, 2025, introduces updates that clarify how authorization should be handled for MCP Servers and how MCP Clients should implement [Resource Indicators](https://www.rfc-editor.org/rfc/rfc8707.html) to prevent malicious servers from obtaining access tokens.

Let's break down what’s new for auth and what it means for you as you build with MCP.

## MCP Servers Now Classified as OAuth Resource Servers

MCP servers are now officially classified as [OAuth Resource Servers](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#authorization-server-discovery). This might seem like a small semantic change, but it has significant implications for security and discovery.

By defining MCP servers this way, the protocol now includes a mechanism to add protected resource metadata. What does this mean in practice? It allows an MCP server to advertise where its corresponding Authorization Server is located. This discovery mechanism is vital for clients, as it removes ambiguity and ensures they request tokens from the legitimate, intended authority, streamlining the authorization process securely.

## Preventing Token Misuse by Implementing Resource Indicators (RFC 8707)

Have you ever worried about a token intended for one service being misused at another? This is a legitimate threat known as "token mis-redemption." To combat this, MCP clients are now required to implement Resource Indicators, as specified in [RFC 8707](https://datatracker.ietf.org/doc/html/rfc8707).

![A diagram illustrating MCP security, showing how Resource Indicators (RFC 8707) prevent token misuse by locking an access token to a specific audience (resource server)](https://images.ctfassets.net/23aumh6u8s0i/5H7veAQxKRIcnI6bOHWyEI/c2c6881322830a9283a5360af6906c68/Uploaded_from_Model_Context_Protocol__MCP__Spec_Updates_from_June_2025__One_Small_Step_for_a_Spec__One_Giant_Leap_for_Security)

By using a resource indicator in the token request, a client explicitly states the intended recipient (the "audience") of the access token. The Authorization Server can then issue a token that is _tightly scoped_ and only valid for that specific MCP server. This prevents a malicious or compromised server from taking a token it received and using it to access a different protected resource on the user's behalf. Put plainly, this practice ensures your tokens can't be used where they don't belong.

## Clearer MCP Security Guidance and Best Practices

Building secure systems is easier when the rules of the road are crystal clear. This update brings significant clarifications to the core [authorization spec's security considerations](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#security-considerations) and introduces a brand new, dedicated page for [security best practices](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices).

This new guidance provides actionable advice for developers like you and me so we can implement both clients and servers more securely. It centralizes security guidance, making it easier to build robust and secure MCP integrations from the ground up. We strongly recommend all developers working with MCP review these pages.

## Building a More Secure Future

These updates represent a significant step forward in hardening the Model Context Protocol. By formalizing the roles of servers, mandating token protection with resource indicators, and providing clearer documentation, the MCP is becoming an even more robust and trustworthy standard for the AI application ecosystem.

While these aren’t the only changes in the June 18th MCP specification changelog, they are the most impactful ones concerning authentication and authorization. If you are building and securing MCPs you should check out our documentation on Auth for MCP and the Getting Started with Auth0 Model Context Protocol (MCP) Server.

Now you’re ready to go forth and enhance the security of your MCP servers and clients.

Model Context Protocol (MCP) Spec Updates from June 2025: One Small Step for a Spec, One Giant Leap for Security

The final release of Vittorio Bertocci’s book about OAuth 2.0 and OpenID Connect is finally out! Learn more about the project journey and download your free copy.

The final release of the ebook [OAuth 2.0 and OpenID Connect: The Professional Guide](https://auth0.com/resources/ebooks/oauth-openid-connect-professional-guide) has been published. [Get your free copy here!](https://auth0.com/resources/ebooks/oauth-openid-connect-professional-guide)

Born from the initiative of one of the most influential personalities in the world of Identity, the late [Vittorio Bertocci](https://auth0.com/blog/in-celebration-of-vittorio-bertocci/), the book analyzes OAuth 2.0 and OpenID Connect, explaining not only how they work but also the motivations that led to the creation of these standards as they are today.

## The Origins of the Project

I met Vittorio when I joined Auth0 in 2019. I only knew him as an authoritative expert in the field of Identity, and I knew very little about that topic. Usually, he was in charge of onboarding training for the technical staff, but when I went to Bellevue for my onboarding, another trainer was assigned. However, he came to the office to greet me because he had learned an Italian was in the group of new hires. A clear signal that he was more than just an Identity expert: he was a person full of empathy.

I had the honor of working closely with Vittorio at the beginning of my career at Auth0. Partly for helping him with this book and partly for his review of other developer content my team and I created. This gave me the opportunity to learn a lot, not only about the technical aspects of Identity but also about how to explain complex concepts based on the specific audience. His style, which is rich in metaphors and anecdotes (you will find several in this book), has always fascinated me. His histrionic manner, his marked accent, and his all-Italian gestures establish him in my imagination as a great storyteller.

We started this book project at the end of 2019 and have published it incrementally in two editions. Vittorio had already drawn up the roadmap for the book and shared diagrams and notes with me, but his innumerable commitments led him to postpone its completion.

## Vittorio's Premature Passing

His untimely death in October 2023 shocked me, as well as the entire community of Identity professionals. Several times, I received requests for information from developers about the book's completion. Therefore, I thought it was right not to disappoint readers and honor Vittorio's memory by completing the book according to the original roadmap and based on his notes. I tried as much as possible to maintain his style, even if it was unique and unrepeatable. Since this project started, some things have changed, so I had to update some references, even in the already published chapters. In this work of adaptation, updating, and revision, the help of [Aaron Parecki](https://aaronparecki.com/) and [Filip Skokan](https://cz.linkedin.com/in/filipskokan) was invaluable, and my heartfelt thanks go to them.

## A Final Note on the Book

One last note before leaving you to read the book. This is not a technical handbook about OAuth 2.0 and OpenID Connect. This book will not give you detailed guidelines on how to use OAuth 2.0 and OpenID Connect in your applications. Or rather, you will learn this too, but more than anything else, this guide will explain to you the reason for the small details of these protocols, why we arrived at them, and how we arrived at them.

Understanding the reason for the technical choices and, therefore, the history behind them will help you better understand OAuth 2.0 and OpenID Connect and gain professional knowledge of them. That said, I hope you will enjoy [reading this book](https://auth0.com/resources/ebooks/oauth-openid-connect-professional-guide)!

OAuth 2.0 and OpenID Connect: The Professional Guide

Discover the Model Context Protocol (MCP) and its authorization mechanisms. Learn how to use API keys, OAuth 2.1 implementation, and best practices for secure LLM API connections.

An Introduction to MCP and Authorization

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

peterfernandez_360

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

Peter Fernandez

A step-by-step guide to leveraging OAuth 2.0 when accessing protected APIs via an iOS app built with Swift and integrated with Auth0.

Calling a Protected API from an iOS Swift App

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

Using a Refresh Token in an iOS Swift App

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

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

Should developers know Identity protocols like OIDC and OAuth, or should they only rely on high-level abstractions like SDKs?

Do developers need to understand the underlying details of OpenID Connect, OAuth, and other standards to implement authentication and authorization? Maybe yes, maybe no. Let’s explore some different points of view.

## The Hard Journey to Identity

Sooner or later, a developer will have to deal with authentication and authorization, whether they are building a SPA, an API, a mobile app, or a microservice, whether they are using Java, C#, JavaScript, or other programming languages.

Some will probably try to implement a homemade solution because it is, after all, a simple login box 😱. And after overcoming the hurdle of username and password authentication, they face the burden of [single sign-on](https://auth0.com/docs/authenticate/single-sign-on), delegated authorization, [Multi-Factor Authentication](https://auth0.com/docs/secure/multi-factor-authentication), and so on. Perhaps just by trying to build a homemade solution, they will understand the complexity of the problem and look for proven solutions.

As they learn about standards such as [SAML](https://auth0.com/blog/how-saml-authentication-works/), [OIDC](https://auth0.com/docs/authenticate/protocols/openid-connect-protocol), [OAuth](https://auth0.com/docs/authenticate/protocols/oauth), [WebAuthn](https://auth0.com/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn), etc., they will probably realize that they have tried to reinvent the wheel. And most likely, they have not considered scenarios that could compromise the security of their application.

But even if you look at these standards from a high level, you will realize that there are many facets, many different scenarios to consider, several details and nuances.

In summary, sooner or later, developers will learn that Identity management is hard.

## To Know or to Ignore? That Is the Question

Once they understand that following standards is the high road to managing the identity of their application users, developers are at a crossroads:

1. Understand and implement the details of these standards.
2. Use a library or SDK and completely ignore the underlying complexity.

The two options seem divergent: know the details or ignore them altogether. Perhaps they reflect the two approaches that developers can take to deal with standards, not just in the Identity space. The choice may depend on the developer's inclination but also on other factors, such as competencies, available time and budget, and so on.

### Developers don't care...

[Someone has argued](https://developer.okta.com/blog/2019/01/23/nobody-cares-about-oauth-or-openid-connect) that "*99.99% of developers out there don’t know (or want to know) anything about OAuth, OIDC, or any other security specifications. All they want to do is find the simplest and most straightforward way to support user authentication and authorization in their application. They don’t care about standards, specifications, grant types, JWTs, or scopes and timeouts – all they want to do is log a user in and check to see what permissions they have.*"

That's pretty understandable. As a developer, I want to solve my problem as quickly as possible without getting lost in the details. If I'm developing an e-commerce application, I want to focus on the business logic of my application. I don't want to worry about every technical detail that my application relies on. I don't want to know the little internal details of the framework my application runs on, the necessary compilation steps, or the network infrastructure that it will use. I prefer to use tools that take care of that and abstract the internal behavior. Tools that are accurately built by real experts in their field. After all, that is what we at Auth0 are trying to do: take care of the complexity of Identity and free developers from knowing the details of standards and security issues.

### ...developers do care

On the other hand, there are [those who argue](https://www.scottbrady91.com/oauth/why-developers-do-care-about-oauth-and-openid-connect) that "*there is an appetite from developers to learn more about OAuth and OpenID Connect and how to use them effectively. So maybe it’s a little too much to state that developers don’t care.*"

Well, in my experience, that is also true. I've found a lot of developers trying to understand how to properly use an [access token](https://auth0.com/docs/secure/tokens/access-tokens) and which [OAuth flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/which-oauth-2-0-flow-should-i-use) to use in a given scenario, even if they're using a third-party library. And I think that's pretty understandable as well. While I don't want to learn every little detail of the infrastructure my application will run on, I can't ignore it completely. Some features of my application might depend on it to work well.

So, what is the right choice to make when dealing with standards in the Identity management space (and also in other areas)? Know their details or ignore them?

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

## The Third Way

“[Zen and the Art of Motorcycle Maintenance](https://en.wikipedia.org/wiki/Zen_and_the_Art_of_Motorcycle_Maintenance)” is one of the cult books of the 1970s. It is a kind of philosophical novel in which the author, [Robert M. Pirsig](https://en.wikipedia.org/wiki/Robert_M._Pirsig), explores the concept of quality by interweaving it with his almost-fictional biography and his passion for motorcycles.

### Two types of developers

In one of the book's disquisitions, the main character divides humanity into two types:

- Those who see the world as a complex mechanism to be explored in its inner workings (*classical understanding*).
- Those who see the world primarily in its superficial appearances (*romantic understanding*).

Romantic people are those who ride their motorcycles without worrying about how they work. They are not interested in the mechanics of the drivetrain or the ignition or the lubrication system. If their motorcycle breaks down, they take it to the mechanic. And they hardly hear in advance that something is going to break down.

Classical people are those who feel their motorcycle. When they ride it, they hear every little noise, they imagine the movement of the chain, they are one with their means of transportation. They feel when something is about to go wrong because they know every little part of their bike and prefer to fix it themselves.

These two categories of people also apply to developers, in my opinion. Romantic developers don't care about the underlying technology or standard. They want to use a library that simplifies their lives and gets right to the point. Classical developers, on the other hand, want to know what happens inside a library: what technology, standard, and algorithm it uses. Classical developers are the traditional hackers, the ones who get their hands dirty with grease to fix or customize the engine of their motorcycle.

Maybe the choice between the two options for dealing with Identity management is driven by these two developer personalities. And perhaps each of you can identify with one of these two profiles.

<include src="BigQuote" quoteText="Although motorcycle riding is romantic, motorcycle maintenance is purely classic." quoteAuthor="R. M. Pirsig" />

### In medio stat virtus

Starting from a *classical* position, the protagonist realizes that virtue lies in the middle, just as the Latins used to say (*in medio stat virtus*). And virtue, excellence, quality is what he is looking for: what the ancient Greeks called *areté* and Eastern cultures call *Dharma*.

While each developer tends to use a romantic or classical approach to the Identity management problem, based on their personal nature, I think that each of the two positions should only be a starting point.

If Identity management is not your business, it is not cost-effective to implement standards from scratch and take care of all the details. Standards evolve, as do scenarios, best practices, etc. If your core business is not Identity management, implementing OIDC, OAuth, and the other standards may be too expensive and risky for your project.

On the other hand, simply using a library or SDK and ignoring what lies beneath it cannot last long. It can be frustrating when problems occur and you have no idea what is going on. You don't know if the problem depends on your code, your configuration, your library, the environment your application is running in. Understanding at least at a high level how the library you are using works and what standards it uses can help you at least to narrow down the area of investigation when problems occur.

In summary, I think every developer has their own starting point for dealing with problems. But whether you decide to do everything yourself based on standards or prefer to ignore everything under a library, in either case, it will impact the cost of your application.

I think the best solution is to get a medium level of expertise in technologies and standards so that you can at least choose your library with knowledge. What do we call this type of developer? The *pragmatic developer*?

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

## What Auth0 Offers

Whether you are a romantic or classical developer, Auth0 helps you integrate authentication and authorization into your applications by letting you use the approach you prefer.

You have [SDKs and libraries](https://auth0.com/docs/libraries) that abstract the complexity of Identity management, but you are not locked into using our libraries. Your choice is free. But you can look into [our code](https://github.com/auth0) and contribute.

You also have [documentation on standards](https://auth0.com/docs/authenticate/protocols), [guides](https://developer.auth0.com/resources/guides) specific to your favorite framework, [code samples](https://developer.auth0.com/resources/code-samples), [videos](https://www.youtube.com/oktadev), and a [community](https://community.auth0.com/) to share what you've learned.

You can choose your preferred path to becoming a *pragmatic* developer by taking advantage of the resources Auth0 provides.

What kind of developer are you? Are you romantic or classical? Are you aiming to become a pragmatic developer? How can we help you? Leave your comments below.


Zen and the Art of Identity Management

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

bruno-krebs

I am passionate about developing highly scalable, resilient applications. I love everything from the database, to microservices (Kubernetes, Docker, etc), to the frontend. I find amazing to think about how all pieces work together to provide a fast and pleasurable experience to end users, mainly because they have no clue how complex that "simple" app is.

R&D Content Architect

Bruno Krebs

Learn how to secure your Electron applications using standards like OpenID Connect and OAuth 2.0.

Securing Electron Applications with OpenID Connect and OAuth 2.0

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

Vittorio

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

Principal Architect

Vittorio Bertocci

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

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

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

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

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

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

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

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

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

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


## What Is an ID Token?

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

Consider the following diagram:

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## What Is an Access Token?

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

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

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


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

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

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

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

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

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

## What Is an ID Token NOT Suitable For?

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

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

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

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

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

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

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

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

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

## What Is an Access Token NOT Suitable For?

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

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

## A Quick Recap

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

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

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

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

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

ben-dechrai

A technologist with a staunch focus on security and privacy. I love helping developers find the joy of experimentation, and designing unconventional solutions for the purposes of learning something new.

Ben Dechrai

Configure MongoDB as an Auth0 custom database to simplify user migration or just add OAuth/Open ID Connect.



Configuring MongoDB as an Auth0 custom database can simplify your user migration process, or even just add an OAuth and OpenID Connect layer on top of your existing database of users. Whatever your reason, let's step through the process of connecting Auth0 to MongoDB.

<div style="text-align: center; font-style: italic">This article is also available in video format</div>
<AmpContent>
<amp-youtube
    data-videoid="TXnDFU4sG0A"
    layout="responsive"
    width="480" height="270">
</amp-youtube>

</AmpContent>

<NonAmpContent>

<iframe width="560" height="315" src="https://www.youtube.com/embed/TXnDFU4sG0A" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

</NonAmpContent>

## Enabling Custom Databases

Don't already have an Auth0 account yet? <a href="https://a0.to/blog_signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">**Sign up for free today!**</a>

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

Once you're logged in, head to the [Database Connections](https://manage.auth0.com/#/connections/database) page, and click on the **Create DB Connection** button.

Give this database configuration a meaningful name, click the **Create** button, and then switch to the **Custom Database** tab.

![Creating a new Custom Database in Auth0](https://images.ctfassets.net/23aumh6u8s0i/496MewuOZuw98e3bzPjxYP/39e421381b97dc89bb189cb35496095c/02-enable-custom-database)

On this screen, you can enable the **Use my own database** option and define the JavaScript that will run when the following events are triggered:

* **Login** - executed each time a user attempts to login, to validate the authenticity of the user against a MongoDB record;
* **Create** - executed when the user signs up, to create a record in MongoDB;
* **Verify** - executed after a user signs up and follows the email "verification" link, to set a corresponding flag in MongoDB;
* **Change Password** - executed when the user changes their password, or the reset email was sent and the user follows the "change password" link, to update a record in MongoDB;
* **Get User** - executed to determine the current state of existence of a user, which returns a matching MongoDB record if any, without requiring the user's credentials; and
* **Delete** - executed when a user is deleted, to deactivate or delete the respective MongoDB record.

For each of these scripts, you'll see a **Templates** drop-down above the code editor, and MongoDB is one of the options that come out of the box. You'll come back to this later.

![Using a predefined custom database script template](https://images.ctfassets.net/23aumh6u8s0i/1tHHzz76Yla76NbwM0Y7H0/b90b814d25bb6eb9600156ee00c82d32/02-custom-db-script-editor)

## Setting up a MongoDB Cluster

Before you do that, though, set up your MongoDB instance. Assuming you already have an account at [https://mongodb.com/](https://mongodb.com/), head to your dashboard and go to the **Projects** tab. Then create a new project, and in that project, create a new cluster. The free, shared clusters with the default settings are sufficient for our purposes, but you might want to consider one of the paid options if their features better suit your needs.

>This guide should also work fine if you're using an existing database, but you might need to tweak some of the upcoming instructions to your specific circumstances.

Once the cluster is built, which can take up to three minutes, you need some connection details to use in the scripts back in the Auth0 dashboard.

Click on the **Connect** button, and configure the IP Addresses that can connect to your cluster. If you look back in the Auth0 interface, you'll see a list of IP addresses under the code editors for any of your scripts. Add these in using the **Add a different IP Address** button in MongoDB.

![Finding Auth0's IP addresses for allowing access to MongoDB](https://images.ctfassets.net/23aumh6u8s0i/5OM015On791Fbrcfx6VvvV/52cad1ca1e118ceb94547c93ecf8a6cf/auth0-ip-addresses-closeup)

The next thing you need to do is define a user that's allowed to connect to the system. Choose a username and sufficiently strong password, and continue.

Finally, you get to choose a connection method. The scripts you're configuring in Auth0 fall under the **Connect your Application** scenario, and clicking on this will reveal the connection string you need to use in your scripts.

![Obtaining connection details from MongoDB](https://images.ctfassets.net/23aumh6u8s0i/4cSocZbkMPCMFOggiaXyT0/6ec4e02b4cb76cd64d09197d1d4964b7/03-mongodb-connection-details-window)

## Defining the Auth0 Custom Database Scripts

Copy the connection string from MongoDB, and switch back to the Auth0 interface. Select to edit the **Login** script, and choose MongoDB from the templates drop-down.

You'll see the following line in the code:

``` javascript  
const client = new MongoClient('mongodb://user:pass@localhost');
```

Replace the entire connection string with the value you just copied from MongoDB, and you'll see something that looks like:

``` javascript  
const client = new MongoClient('mongodb+srv://user:<password>@xxx.mongodb.net/<dbname>?...');
```

You can remove `<dbname>` from this connection string, because it's already specified later in the script.

``` javascript  
const client = new MongoClient('mongodb+srv://user:<password>@xxx.mongodb.net/?...');
```

Now you need to replace `<password>` with the actual password, but you know it's bad practice to keep these in the scripts.

There's a solution for this, though. Under the script editor, you'll see a **Settings** section that allows you to store data exposed to all the scripts via environment variables. This is a much more secure way to store the password.

Add a key/value pair with the key `MONGO_PASSWORD` and the password you provided when configuring access in MongoDB.

![Storing credentials securely for use in Auth0 custom database scripts](https://images.ctfassets.net/23aumh6u8s0i/2qRxG3H9r2JrR8oAkKuhUn/b2c23edc2154e7482165fc8623eacc53/04-custom-db-script-settings-window)

You'll then be able to copy the **Code Snippet** from the new entry, and use that in your connection string instead:

``` javascript  
const client = new MongoClient('mongodb+srv://user:' + configuration.MONGO_PASSWORD + '@xxx.mongodb.net/<dbname>?...');
```

## Creating the Mongodb Database to Store Users In

The next thing you'll need to do is create a database and collection in MongoDB. Jumping to the MongoDB interface again, close the dialog box containing the connection information and click on the **Collections** button.

On the Collections page, click the **Add My Own Data** button, and provide the database name `db-name` and the collection name `users` and click **Create** to continue.

![Creating a database and collection in MongoDB](https://images.ctfassets.net/23aumh6u8s0i/2FGBFo0xCA7WIuAv1rBeTj/d9fc99f7483d0adc4d969845c2aed954/05-create-db-and-collection-window)

That's it for this step! The database is ready, and you just need to finish up the Auth0 custom database configuration.

## Finalizing the Auth0 Custom Database Scripts

Switch back to the Auth0 interface again and you should see the **Login** script editor. The script is already connecting to the `db-name` database and pulling users out of the `users` collection. If you used other names in the previous step, make sure you update the code in all the scripts on around lines 8 to 10:

![Code showing database and connection name definitions](https://images.ctfassets.net/23aumh6u8s0i/J3utFvV9KFRfeUuy2Vwax/d2cb5e1ef195473184403244a1daf165/script-configure-db-and-connection-names)

Before you move on, copy line 4 into your clipboard, which instantiates the client with the correct connection string.

To configure the other scripts, simply iterate through each one, select MongoDB from the templates dropdown, and replace the client instantiation line with the one you just copied from the **Login** script.

There are just two more little changes you'll need to make to make everything work.

By default, each new user won't have an `email_verified` flag at all, so setting it later won't work. To remedy this, head back to the **Create** script, and find the line that defines the value of `user.password`:

``` javascript  
user.password = hash
```

This is probably line 24. Directly after this line, add the following:

``` javascript  
user.email_verified = false
```

Now, when someone creates a new account, the new user object in MongoDB will be created with the `email_verified` flag as false.

The second change is to the **Delete** script. On around line 11, you'll see the line that tells MongoDB to delete the user:

``` javascript  
users.remove({ _id: id }, function (err) {
```

The issue here is that the value of `id` is the user's email address, whereas the `_id` in MongoDB is an object ID. Change the key in this filter to `email` in order to correctly identify the MongoDB record to be removed:

``` javascript  
users.remove({ email: id }, function (err) {
```

Clicking on the **Save** button above the code editor will save all changes in all the scripts. So hit that, and you're done!

## Testing the Database

You can use the **Try** button to test each of these scripts out now. If you're starting with a new database, try the **Create** script first, and go from there.

![Testing the Auth0 custom database by creating a new user](https://images.ctfassets.net/23aumh6u8s0i/1hc21gDm65ROXTXVQstdYB/8becfaa89d9735532be3d1c449a9a208/06-user-created)

If you're using an existing database, you can try logging in with an existing user's credentials. If you're having authentication issues, make sure the **Login** script is using the same hashing mechanism as the code that generated these users in the first place.

And if you're having trouble, head over to our Community Forum and drop your request below.


Connecting Auth0 to MongoDB

## What is The OAuth 2 Game?

The OAuth 2 game is a fun and easy way to learn about how to use OAuth to protect the most common types of applications.

The OAuth 2 specification lists different ways of obtaining access tokens meant to leverage the different capabilities and security characteristics of distinct client (application) types. We call those different ways grants through the years. The OAuth 2 family of specifications gained new methods, called extension grants, meant to provide guidance for new types of clients. 

It is not always easy to know what grant to use for your application, especially if you aren’t an identity expert. Usually, SDKs and libraries help, taking care of details for you, but it is often useful to know what is going on behind the scenes - for example, when you need to troubleshoot an issue.

The OAuth 2 game can help you to familiarize yourself with the most common grant choices for the most frequently used application types. It features two dice, one for grants and another for application types. Throw the dice and consult the instructions to discover whether the combination of grant and application type you obtained happens to be a good one! Play a few times, and before you know it, you’ll be familiar with the most common combinations!

## Learn More About OAuth 2

Naturally, there’s only so much we can express with two dice. The OAuth 2 game is based on the most obvious choices of grant per application type, but there are always nuances, exceptions, and more things to consider. If you want to take your understanding of OAuth 2 to the next level, here’s a collection of links to help you take your next steps:

* The Authorization code grant, in both its public and confidential client flavors, is defined in the original [OAuth 2 core](https://www.rfc-editor.org/rfc/rfc6749.html) specification. PKCE, a security measure device to further protect the exchange of authorization codes, is defined [here](https://www.rfc-editor.org/rfc/rfc7636.html).
* The client credentials grant is also defined in the O[Auth 2 core specification](https://www.rfc-editor.org/rfc/rfc6749.html).
* The device authorization grant is an extension grant defined [here](https://www.rfc-editor.org/rfc/rfc8628.html).
* The resource owner password grant was introduced in the original [OAuth 2 core specification](https://www.rfc-editor.org/rfc/rfc6749.html) but is being omitted by the [OAuth 2.1 revision](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-02) given its poor security track record.
* You will find useful information on how to apply OAuth 2 in best practice documents - in particular for [native clients](https://www.rfc-editor.org/rfc/rfc8252.html), [browser apps](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-browser-based-apps) and for [security best practices](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics-18).
*   Finally, if you want a high-level discussion on modern identity development and some tips on how to choose grants per-app type, you can check out [this session ](https://identiverse.gallery.video/detail/videos/developer/video/6188857523001/modern-identity-for-developers-101?autoStart=true)from the Identiverse 2020 conference. 

## OAuth 2 on Identity, Unlocked Podcast

Want something to listen to while you play? OAuth 2 made several appearances in the last two seasons of Identity, Unlocked.

#### What’s new with OAuth 2.1 with Aaron Parecki

<AmpContent>
<div><iframe width="100%" id="casted-embed-c71b9fbd" scrolling="no" style="border: none" src="https://identityunlocked.auth0.com/player/c71b9fbd"></iframe></div>
</AmpContent>
<NonAmpContent>
<div><iframe width="100%" id="casted-embed-c71b9fbd" scrolling="no" style="border: none" src="https://identityunlocked.auth0.com/player/c71b9fbd"></iframe><script type="text/javascript">window.addEventListener("message", function(message){if(message.origin === "https://identityunlocked.auth0.com" ) { if( message.data.event) { if(message.data.event === "castedSizeUpdate") { var casted_episode_player = document.getElementById('casted-embed-' + message.data.payload.slug); if(casted_episode_player) { casted_episode_player.height = message.data.payload.height;if(casted_episode_player.contentWindow) {casted_episode_player.contentWindow.postMessage({ event: "castedStopUpdate" }, "https://identityunlocked.auth0.com");}}}}}}, false)</script></div>
</NonAmpContent>

<br \> 

#### A Lap Around the OAuth 2 Security BCP with Daniel Fett

<AmpContent>
<div><iframe width="100%" id="casted-embed-23714281" scrolling="no" style="border: none" src="https://identityunlocked.auth0.com/player/23714281"></iframe></div>
</AmpContent>
<NonAmpContent>
<div><iframe width="100%" id="casted-embed-23714281" scrolling="no" style="border: none" src="https://identityunlocked.auth0.com/player/23714281"></iframe><script type="text/javascript">window.addEventListener("message", function(message){if(message.origin === "https://identityunlocked.auth0.com" ) { if( message.data.event) { if(message.data.event === "castedSizeUpdate") { var casted_episode_player = document.getElementById('casted-embed-' + message.data.payload.slug); if(casted_episode_player) { casted_episode_player.height = message.data.payload.height;if(casted_episode_player.contentWindow) {casted_episode_player.contentWindow.postMessage({ event: "castedStopUpdate" }, "https://identityunlocked.auth0.com");}}}}}}, false)</script></div>
</NonAmpContent>

<br \>

#### JWT Profile for OAuth 2 Access Tokens with Vittorio Bertocci

<AmpContent>
<div><iframe width="100%" id="casted-embed-7efd0ecb" scrolling="no" style="border: none" src="https://identityunlocked.auth0.com/player/7efd0ecb"></iframe></div>
</AmpContent>
<NonAmpContent>
<div><iframe width="100%" id="casted-embed-7efd0ecb" scrolling="no" style="border: none" src="https://identityunlocked.auth0.com/player/7efd0ecb"></iframe><script type="text/javascript">window.addEventListener("message", function(message){if(message.origin === "https://identityunlocked.auth0.com" ) { if( message.data.event) { if(message.data.event === "castedSizeUpdate") { var casted_episode_player = document.getElementById('casted-embed-' + message.data.payload.slug); if(casted_episode_player) { casted_episode_player.height = message.data.payload.height;if(casted_episode_player.contentWindow) {casted_episode_player.contentWindow.postMessage({ event: "castedStopUpdate" }, "https://identityunlocked.auth0.com");}}}}}}, false)</script></div>
</NonAmpContent>


<br \>

## Wanna Play?

The OAuth2 Game will be available at Identiverse 2021, but check back here soon for your chance to receive your own set.

Introducing: The OAuth 2 Game

JWT Profile for OAuth 2.0 Access Tokens with Vittorio Bertocci

## The Overview

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

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

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

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

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

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

## Key Takeaways

What is the JWT profile spec, in a nutshell:

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

How a spec evolves from an idea:

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

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

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

Vittorio explains the potential advantages of this JWT spec:

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

Vittorio’s Call to Action: 

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

### Links/Resources:

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

<br>

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

<br>

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

<include src="asides/IdentityUnlocked" />

<include src="asides/AboutAuth0" />

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

Aaron Parecki joins the show to discuss the development of the OAuth 2.1 specification.



### The Overview

In this episode of _Identity. Unlocked_, principal architect at [Auth0](https://auth0.com) and podcast host, Vittorio Bertocci, speaks with Aaron Parecki. Aaron is currently senior security architect at [Okta](https://developer.okta.com/), and he has spent much of his career focusing on [OAuth](https://oauth.net/). He writes and teaches on the subject and joins Vittorio to discuss the latest project he's been working on: the development of the OAuth 2.1 specification.

OAuth 2.1 is a revision of the OAuth 2 core specification and involves a dramatic reduction in the amount of reading that identity providers and SDK authors need to get up to speed on OAuth. The project aims to consolidate current material on OAuth, offering a guide to best practices and including the most relevant guidance directly in the core specification.

Moving into more of the details of the project, Vittorio first asks what OAuth2.1 adds to the OAuth 2 core.
One major addition is the requirement to use PKCE in every authorization grant, including the cases involving confidential clients. 
Recommendations for browser-based apps are in the works, and the new guide will include some stricter requirements defined in the security best current practices document, such as restrictions around refresh tokens. OAuth 2.1 will also introduce a new term, "credentialed client," defined as a client that has credentials but no confirmed identity. The concept already exists in OAuth 2, OAuth 2.1 simply gives it a name so that it can be treated as a legitimate client type, along with the classic public and confidential.
Aaron also explains that OAuth 2.1 omits any mention of implicit flow and password grants, and he and Vittorio finish the conversation with a deep dive on the differences between id tokens and access tokens.

### Highlights

**[5:59]** - Vittorio asks Aaron about OAuth 2.1.

As mentioned during the discussions, [OAuth 2.1](https://tools.ietf.org/html/draft-ietf-oauth-v2-1-00) (currently in [draft 00](https://tools.ietf.org/html/draft-ietf-oauth-v2-1-00))consolidates a number of different specifications. Here's the current list:

* [OAuth 2.0 Core (RFC6749)](https://tools.ietf.org/html/rfc6749)
* [OAuth 2 Bearer Token Usage (RFC6750)](https://tools.ietf.org/html/rfc6750)
* [Proof Key for Code Exchange by OAuth Public Clients (RFC7636)](https://tools.ietf.org/html/rfc7636)
* [OAuth2 Security BCP (draft 15)](https://www.ietf.org/id/draft-ietf-oauth-security-topics-15.html)
* [OAuth2 for Native Apps (RFC8252)](https://tools.ietf.org/html/rfc8252)
* [OAuth2 for Browser-Based Apps BCP (draft 6)](https://tools.ietf.org/html/draft-ietf-oauth-browser-based-apps-06)

By providing a single document with the best & more relevant sections of all those specifications, developers building identity tools, authorization server products, and SDKs will have a much easier time finding the most up to date guidance on how to implement delegated authorization in their scenarios. 

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

**[11:00]** - Addressing the main additions to the OAuth 2 core, Aaron first talks about the main new requirement introduced by OAuth2.1: imposing the use of PKCE for every authorization grant, regardless of the client type. 

The PKCE requirements is currently introduced in [section 4.1.1 of OAuth 2.1](https://tools.ietf.org/html/draft-ietf-oauth-v2-1-00#section-4.1.1) (location likely to change as the spec structure evolves). We don't go in the details of PKCE here, as we'll cover the topic more in-depth in an upcoming episode this season (the one about the OAuth2 security BCP, with Daniel Fett); however, if you are interested in the details of the code injection attack, Aaron mentions, please check out [this video](https://www.youtube.com/watch?v=1ot45WwQWJE).

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

**[14:30]** - Besides PKCE, what is being added to the core?

You can find a good backgrounder on refresh token rotation in [this post](https://auth0.com/blog/securing-single-page-applications-with-refresh-token-rotation/). 
The podcast episode discussing sender constraint, MTLS and DPoP can be found [here](https://identityunlocked.auth0.com/public/49/Identity%2C-Unlocked.--bed7fada/4d4e8add).

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

**[20:48]** - Vittorio and Aaron turn to credentialed clients, the new term defined in OAuth 2.1.

Credentialed clients are defined in [Section 2.1](https://tools.ietf.org/html/draft-ietf-oauth-v2-1-00#section-2.1) of the current draft of the OAuth 2.1 specification.

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

**[25:55]** - What has been removed from the core? 

The arguments for not including in OAuth 2.1 the resource owner password grant (ROPG) are well known; hence there isn't much to add or explain on top of what we say on the podcast.

The implicit discussion is a bit more nuanced. You can find a more in-depth discussion in this post from a while back- but there's no doubt about its omission from OAuth 2.1 being a good move. The detail that is perhaps worth expanding on is how the considerations that led to omitting the implicit flow from OAuth 2.1 don't really impact the use of implicit + form POST to get an id token in OpenID Connect for web sign-on in traditional web apps.

In a nutshell: OAuth 2 introduced the implicit flow as a way of getting access tokens, the only token type it defines, directly from the authorization endpoint- and mostly with single-page apps in mind. As we have seen in the podcast episode on sender constraint, leaking access tokens meant to be used as bearer tokens has serious consequences, as attackers can successfully reuse leaked tokens. If you consider the fact that returning access tokens via implicit flow for single-page apps specifically creates more attack surface for stealing tokens (token bits in referral headers, browser history, etc.), you can see how it's prudent to fall back on more robust methods, such as authorization code with PKCE directly in JavaScript.

None of the above really applies to get id tokens via implicit + form post when implementing web sign-on in OpenID Connect That's for two main reasons, as identified in the podcast discussion:

1. The mechanics of returning a token via form post are more robust than the ones using a fragment. Tokens returned via form post don't end up in referral headers or the browser history as query elements do.
2. More importantly: OpenID Connect implements measures that make it hard to reuse a leaked id token, for example, by using a nonce.

To better understand the last point, take a look at the following diagram.

![Diagram Token](https://images.ctfassets.net/23aumh6u8s0i/5JM77M913ht4ohtWiulli4/091cff95c794b0b13f30a3dc6c83b725/diagram-token)

When a web app wants to perform a sign in with an OpenID Connect provider, it generates a nonce (random unguessable string), it saves the value of the nonce so that it can be retrieved in the context of the current transaction (for example, by asking the browser to save a cookie containing the nonce value and somehow protected from tampering, for example by signing the cookie with a secret) and it includes the nonce in its sign-in request.

Leg 1 in the diagram shows the step right after all that occurs, with the sign-in request including the nonce reaches the authorization server acting as OpenID Connect provider.  
Upon successful authentication, the provider returns an id token that, besides being signed (not shown in the diagram), featuring the canonical claims, etc. etc., also includes a nonce claim carrying the nonce value received during the sign-in request.

In the form post case, the browser reacts as shown in leg 3- by immediately POSTing a form containing the id token to the requesting app, along with the nonce cookie created at request time.
Upon receiving the id token, the web app validates it as established by the OpenID Connect spec, and, as part of its validation checks, it verifies that the nonce claim value corresponds to the nonce saved in the tamper-proof cookie. If the values do match, the web app considers the request valid- and, as shown in leg 4 of the diagram, establishes a session of its own and, importantly, removes the nonce tracking cookie (or any other measure that would make the nonce single use).

If an attacker manages to steal the id token and attempts to use it, they will be unable to present a corresponding nonce tracking cookie with the value matching the id token content- as they don't have access to the crypto material the web app uses to manufacture and verify such cookies. Voila, the replay attack is defeated! 

Although this is not directly germane to OAuth 2.1 per se, you can expect discussions like above to be common in the months ahead as the community digests the impact of the changes in OAuth 2.1. Hopefully, this diagram, and this podcast episode in general, equipped you to contribute to those discussions and decide how to apply this knowledge to your own scenarios!

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

If you want to dig further on the topic of OAuth 2.1, you can also take a look at the recording of a 30 mins session from the ASC 2020 conference [here](https://www.youtube.com/watch?v=tEUIsc6skJQ).

### Links/Resources:

Learn more about [Aaron Parecki](https://aaronparecki.com/)<br />

Aaron Parecki on [Twitter](https://twitter.com/aaronpk)<br />
Aaron’s ebook on [OAuth](https://oauth2simplified.com/)<br />

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

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

<include src="asides/IdentityUnlocked" />

<include src="asides/AboutAuth0" />


Identity, Unlocked... Explained | Episode 2

Learn how the OAuth 2.0 Device Flow offers smooth authentication and authorization to limited-input devices.



Tired of wrestling with remote controls and on-screen TV keyboards to enter credentials on your smart TV? You’ve dealt with it too many times, and you can bet your customers have to. What if you could help them get logged in with just a few taps on their cell phone?

![Image of person using TV remote control to enter credentials](https://images.ctfassets.net/23aumh6u8s0i/40YgdeQssI4jVCDkuUFBhK/84a3c8111f80e7c8f1e0c45c0366f7ac/do-not-use-remote-controls-to-enter-credentials)

Hi, Dan from Auth0 here bringing you the [**OAuth 2.0 Device Flow**](https://auth0.com/device-flow/): a fast, easy, and safe way to log into apps on your Smart TV and other input-constrained devices. No keyboard? No browser? No problem!

Ordinary login can be tedious and error-heavy. The OAuth 2.0 Device Flow is lightweight, authenticates you in seconds and not only works with TVs, but also with game consoles, CLIs, printers, and much more!

Auth0 offers developers a fully compliant implementation of the OAuth 2.0 Device Flow to tackle this user experience pain point easily. Let’s learn more about what input-constrained devices are, how this authorization grant works, and how Auth0 can help.

## What Are Internet-Connected, Input-Constrained Devices?

Do you have an internet-connected device that either (1) has no browser or (2) offers impractical ways for you to input text?

If you answered yes, then you have an input-constrained device! What type of devices came to your mind? I am thinking...

- All-in-One printers
- Fitness trackers
- Streaming devices
- Toothbrushes
- Game consoles
- Fridges
- Teddy bears
- Car infotainment systems
- Smart TVs
- Really, anything with the word “smart” in front of it

![Smart TVs, printers, gaming consoles, and other typical input-constrained devices](https://images.ctfassets.net/23aumh6u8s0i/2f4VYWXdICGOnMhmtm0u1G/d847718b30d453a63bd3f4d21c9d0e89/typical-input-constrained-devices)

The Internet of Things (IoT) frenzy has put a lot of devices online. Today or in the future, the software running on these devices may talk to your service APIs to get the data needed to offer your customers a rich user experience across devices and platforms. However, that user experience may not be so rich or secure if a device doesn’t offer a convenient way to authorize external services.

<include src="TweetQuote" quoteText="Granting authorization on input-constrained devices is challenging. But what are input-constrained devices anyway? Learn more in this blog post!"/>

As a competitive business, you don’t want to limit the devices that can use your services by not being able to provide browserless authentication. But, if the device does offer a browser or user interface, you wouldn’t want your customers to enter credentials using the arrows of a TV remote control to select keys from a giant on-screen keyboard. Their credentials could be compromised by someone recording their screen as they slowly input them, for example.

Furthermore, you’ll want to ensure that user credentials are not entered on systems that you don’t control and that may store them for future access, like smart displays that sometimes leverage proprietary systems or third-party clients that access your APIs.

What you do want is a way to authorize third-party applications with controlled access to your APIs on a variety of devices. The OAuth 2.0 Device Flow lets you do exactly that! Even on devices without a browser, you can take advantage of the security and user experience benefits of a standard delegated authorization protocol.

<include src="ProfileCard" picture="https://cdn.auth0.com/blog/auziro/julian-lywood-mulcock-mini.png" name="Julian Lywood-Mulcock" title="Customer Success Architect" team="Customer Success" location="London, United Kingdom" body="With Device Flow, we reduce end-user frustration and we ensure the log-in action is as secure as it can be. <br /><br />By decoupling the log-in experience from input-constrained devices, end-users can benefit from a secure method of authentication while having a frictionless user experience they will tell their friends about."/>

To understand how to go with the Device Flow, it’s better for you to see it at play using a video streaming app as an example.

## OAuth 2.0 Device Flow In Action

Say that you want to watch AuthU TV, _a fictional video platform for techies_, on your television. You start by downloading the AuthU TV app to your smart TV. When you open the app for the first time, you’ll be welcomed by a login screen.

To kick things off, you’ll be asked to visit a URL on another device (like a smartphone or laptop), enter a short code, and then log in to your AuthU account to authenticate yourself.

Completing this process gives the software on your TV access to your AuthU account and lets you use your remote control to navigate AuthU content &mdash; not enter credentials.

![Illustration of OAuth 2.0 Device Flow that connects your devices](https://images.ctfassets.net/23aumh6u8s0i/2fc4mgnGc7TLVmFSyFCEmq/a1a849dbf53cc82ec7c30e6f6ff63b31/device-flow-banner-2)

At a high level, this process is very similar to how YouTube redirects to accounts.google.com to process a user login. With the OAuth 2.0 Device Flow, you manage the authentication process on a centralized login page, using a secondary device to make the input of credentials faster and more secure. By moving authentication off the device and into a browser, you are able to take advantage of more advanced identity and security features, such as MFA, SSO, and Social Login.

But talk is cheap: let’s see the Device Flow in action! Our engineers at Auth0 created an interactive demo that lets you simulate the authorization of the AuthU smart TV app right from your browser.

Start by visiting the [_Device Flow Playground_](https://auth0.github.io/device-flow-playground/). Once there, you can either try the playground with our default demo settings or configure with your Auth0 account settings to try in your own applications.

> Need an Auth0 account? <a href="https://auth0.com/signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">Get started for free today</a>. You’ll be saying “Wow!” while using everything that Auth0’s free trial has to offer!

You can also select the desired scopes you want to have. Once that’s done, click on “Get Started”.

![Image showing dashboard for how to get started with Auth0 Device Flow](https://images.ctfassets.net/23aumh6u8s0i/2kEgfhvZh84ty2XsEfjDS4/282e39d53d32deef8e381d012bbce385/getting-started)

Next, to stream content from the mock AuthU TV app, you are prompted to authorize the app by clicking on the “Authorize” button.

![Auth0 Device Flow: authorization request](https://images.ctfassets.net/23aumh6u8s0i/YYQyy8IRjr6yMu5bZ2CVK/a1d955489836849e35411d38da360a2e/authorization-request)

Now you are prompted to authorize the device by navigating to the activation URL, [_acme-demo.auth0.com/activate_](https://acme-demo.auth0.com/activate), using another device and entering the code displayed on your smart TV. You can also scan the QR code, which would automatically input the user code. The TV app will be waiting for you to complete the process on your secondary device which would trigger an authorization response it can use to get access to the AuthU TV service.

![Auth0 Device Flow: token request](https://images.ctfassets.net/23aumh6u8s0i/1kbV5mJIgdzqj1zKttXvhx/edefed4de2bfd100c411b0e4192c6892/token-request-2)

Visit the provided link, enter the one-time code, and click “Continue”. You can do this using another browser tab or your smartphone mobile browser.

![Auth0 Device Flow: device activation](https://images.ctfassets.net/23aumh6u8s0i/2DyardhZGZL9dsFkyv1ntI/eeee2eee9563b6c32066c3b5df3223c2/device-activation-enter-code)

![Auth0 Device Flow: device activation code](https://images.ctfassets.net/23aumh6u8s0i/5PUMsCJHIxEqQuqBhec3oC/6b3a2704a91bfd070ac57ad87983d7c9/device-activation-code-entered)

Confirm that the code displayed on the site matches the one shown on the smart TV and click “Continue”.

![Auth0 Device Flow: device confirmation](https://images.ctfassets.net/23aumh6u8s0i/7c5GzgdHLuYt2iPuqDzBhd/c5cd28ea0e35deee1a8648a757fd18d6/device-confirmation)

Next, sign up for an account or log in with an existing one.

![Auth0 Device Flow: user authentication](https://images.ctfassets.net/23aumh6u8s0i/1s4Z8pZ2FknPYkMD3BtcNr/0e46e566969ef95f364bb30afd12bb5e/authentication)

A message will show up on the site confirming that the device is now connected.

![Auth0 Device Flow: device connection](https://images.ctfassets.net/23aumh6u8s0i/6rJnFfbuz2vv0gn5Du3ivY/3df5ee90405b34ebe7816149d8777d7f/your-device-is-now-connected)

Back on the smart TV, the AuthU app is ready to start streaming content. The TV app has the authorization to fetch additional information about you to customize the UI.

![Auth0 Device Flow: activation completion](https://images.ctfassets.net/23aumh6u8s0i/01qheEW2pvdEikaQlCUq2l/12338b0c904089d2d86eace3f955cff7/activation-complete)

That’s it for a high-level technical overview of the OAuth 2.0 Device Flow. Let’s peek under the hood at how using Auth0 as your identity platform facilitates this process.

## OAuth 2.0 Device Flow Made Easy with Auth0

When your input-constrained device needs to fetch user data from your API, the following process takes place:

![Overview of OAuth 2.0 Device Flow with API calls](https://images.ctfassets.net/23aumh6u8s0i/2Ykjsm2pB8MBDiqWLTq6RQ/e80d6aa8ab913d990107e81b2aa41dbc/overview-flow-call-api-device-app)

1. If the device application is not already authorized, your device application calls your Auth0 Authorization Server to retrieve a device code.

2. Auth0 responds with a URL and user code. Your device app asks the user to visit a specific URL on a secondary device (like a laptop or smartphone) and provide the activation code.

3. Your device app begins to poll your Auth0 Authorization Server for an Access Token and a Refresh Token.

4. The user authenticates with Auth0 on the secondary device using one of your already configured authentication methods. Auth0 is an identity hub that supports many [_Identity Providers using various protocols_](https://auth0.com/docs/identityproviders) (like OpenID Connect, SAML, WS-Federation, and more).

5. Once authentication is complete, Auth0 responds to your device app with an Access Token and a Refresh Token, which lets you refresh the Access Token without having to request permission from the user again.

6. The Access Token can be used to call your API and retrieve requested data.

<include src="TweetQuote" quoteText="With access tokens and refresh tokens, you make authentication fast and make it last! Learn more about how tokens work in the OAuth 2.0 Device Flow."/>

## Recap

Today, you learned what internet-connected, input-constrained devices are, the challenges that these devices present to developers and customers alike, and how Auth0 along with OAuth 2.0 let you tackle those challenges through the implementation of the Device Flow.

The best part of the OAuth 2.0 Device Flow is that it lets you extend your existing authentication solutions to smart device platforms. This authorization grants simply lets your customers authenticate and authorize applications running on one device through another.

You may be curious about how you or your development team can implement this through code. We'll provide you with a detailed tutorial on Device Flow soon. Stay tuned! In the meantime, check the following resources for more information:

- [Introducing Device Flow](https://auth0.com/device-flow/)

- [Auth0 Device Authorization Flow Documentation](https://auth0.com/docs/flows/concepts/device-auth)

- [Calling an API Using the Device Authorization Flow](https://auth0.com/docs/flows/guides/device-auth/call-api-device-auth)

- [OAuth 2.0 Device Authorization Grant, Draft 15](https://tools.ietf.org/html/draft-ietf-oauth-device-flow-15)

<include src="TweetQuote" quoteText="The OAuth 2.0 Device Flow is designed for applications executed on internet-connected devices that either don’t have a browser or are input-constrained. It enables end-users to authorize device applications to access service APIs."/>

<include src="asides/AboutAuth0" />


OAuth 2.0 Device Flow, No Hassle Authentication - As Seen On TV

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

OAuth2 Implicit Grant and SPA

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

eHk3ciM

I am the Group Manager, Developer Content at Okta, and a Google Developer Expert in Web Technologies and Angular. I'm passionate about identity, authentication, constant learning, and developer communities. As a developer advocate, engineer, mentor, and international speaker, I love learning from and sharing with other inhabitants of the tech space.

Group Manager, Developer Content

Kim Maida

The IETF has released Best Current Practice (BCP) for OAuth 2.0 in native apps. Learn about it now.



**TL;DR:** In October, 2017, the [Internet Engineering Task Force (IETF)](https://www.ietf.org/) released the [Best Current Practices (BCP) when using OAuth 2.0 with native mobile applications](https://www.rfc-editor.org/rfc/rfc8252.txt). This BCP states that OAuth 2.0 authorization requests from native apps should _only_ be made through external user agents, primarily the user's browser. We'll discuss what this means for developers and users and any security considerations involved.

---

## OAuth 2.0 Best Current Practice for Native Apps

The IETF ([Internet Engineering Task Force](https://www.ietf.org/)) recently released the [Best Current Practice for OAuth 2.0 for Native Apps Request For Comments](https://www.rfc-editor.org/rfc/rfc8252.txt). This document requires that, in accordance with best practices, only external user agents (such as the browser) should be used with the [OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749) by native applications; this is known as the "AppAuth pattern". Embedded user agents should not be implemented.

> _For authorizing users in native apps, the best current practice is to perform the OAuth authorization request in an external user agent (typically the browser) rather than an embedded user agent (such as one implemented with web-views)._
>
> -_[OAuth 2.0 for Native Apps](https://www.rfc-editor.org/rfc/rfc8252.txt)_

Using the browser to make native app authorization requests results in better security. It also enables use of the user's current authentication state, making single sign-on possible. Embedded user agents are unsafe for third parties. If used, the app has access to the OAuth authorization grant as well as the user's credentials, leaving this data vulnerable to recording or malicious use. Embedded user agents also don't share authentication state, meaning no single sign-on benefits can be conferred.

We'll go into the security and implementation advantages of using the browser for authorization requests in more detail below.

<include src="TweetQuote" quoteText="Using the browser to make native app authorization requests results in better security."/>

### Authorization Flow for Native Apps Using the Browser

The authorization flow for native apps using the browser acts as illustrated in the following diagram:

![Authorization flow for OAuth 2.0 in native apps using the browser](https://images.ctfassets.net/23aumh6u8s0i/3ULKZFPLQiGXHa9NFNCpCS/bd5c463c34ae60a1aee86af0db199b3a/hoauth-flow)

> 1. Client app opens a browser tab with the authorization request.
2. Authorization endpoint receives the authorization request, authenticates the user, and obtains authorization. Authenticating the user may involve chaining to other authentication systems.
3. Authorization server issues an authorization code to the redirect URI.
4. Client receives the authorization code from the redirect URI.
5. Client app presents the authorization code at the token endpoint.
6. Token endpoint validates the authorization code and issues the tokens requested.
>
> _Figure 1, [OAuth 2.0 for Native Apps](https://www.rfc-editor.org/rfc/rfc8252.txt)_

URIs are used for OAuth 2.0 on the web for authorization requests and responses. Similarly, URIs can also be used in native apps. When the built-in browser is employed by the user for all native app logins, certain advantages are conferred, such as the ability to use a single sign-on session stored in a central location and additional security afforded by an authentication context that is separated from the app. Browser security is also a major focus of vendors, and they tend to manage security and sessions policies quite well. In addition, supporting and implementing the same approach in web and native apps reduces complexity and increases interoperability.

<include src="TweetQuote" quoteText="Implementing external user agents in both web & native apps reduces complexity and increases interop."/>

### Initiating and Receiving Authorization Requests

Native apps now must request user authorization by creating a URI with the appropriate [grant type specified in the OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749#section-4.1). The app then redirects the user to this request URI. A redirect URI that the native app can receive and parse appropriately must also be supplied. This must be implemented using an _external user agent_. Use of the device browser is recommended.

The authorization server must permit at least three redirect URI options for the response sent back to the native app:

* Private-Use URI Scheme Redirection
* Claimed "https" Scheme URI Redirection
* Loopback Interface Redirection

You can read about these three options in detail in Section 7 of [OAuth 2.0 for Native Apps](https://www.rfc-editor.org/rfc/rfc8252.txt).

## OAuth 2.0 Security Considerations for Native Apps

When implementing OAuth 2.0, there are a number of security considerations that developers must be mindful of when using best current practice with an external user agent. We'll go over a few of them now.

### Authorization Code and Grant Flow

Using the redirect options above means that the authorization code can only be received by native apps on the same device. While this increases security, it does still mean that another app on the same device could potentially intercept the code. The [Proof Key for Code Exchange (PKCE) protocol](https://tools.ietf.org/html/rfc7636) was created to defend against this attack vector. Public apps as well as servers _must_ use PKCE, and servers should reject authorization requests from apps that do not.

It is _not_ recommended to implement [implicit grant flow](https://auth0.com/docs/api-auth/grant/implicit) in native apps because this flow cannot be protected by PKCE. Instead, [authorization code grant flow with PKCE](https://auth0.com/docs/api-auth/grant/authorization-code-pkce) should be used.

### Authorization Servers and Clients

In most cases, native apps are considered public clients and must be registered with the authorization server. Authorization servers must also register a client's complete redirect URI. If an authorization request does not match the registered redirect URI, the request must be rejected.

User authentication and consent will be required by the authorization server, as per any other web browser based OAuth 2.0 flows.

### User Agents

Embedded user agents should not be used to masquerade as an external user agent. Authorization servers can protect against these fake agents by requiring an authentication factor only available to genuine external user agents.

Cross-Site Request Forgery (CSRF) attacks should also be mitigated by using the `state` parameter to link client requests and responses. More details are available in section 5.3.5 of [OAuth 2.0 Threat Model and Security Considerations](https://tools.ietf.org/html/rfc6819).

The user's browser is the recommended external user agent. Embedded user agents must not be used for authorization requests. Authorization servers may detect and block requests from embedded user agents, as they are unsafe for third parties, such as the authorization server itself. The reason for this is because the app can then access not only the OAuth authorization grant, but also the user's full authentication credentials. The app could then potentially record or use this information maliciously. In addition, embedded user agents don't share authentication state with other apps or the browser and therefore disabling single sign-on benefits.

## Conclusion

If you're a native app developer, it's very important to adhere to best current practices. Please take the time to read over the [OAuth 2.0 for Native Apps](https://www.rfc-editor.org/rfc/rfc8252.txt) RFC yourself. Using an external user agent for OAuth 2.0 authorization requests provides better security as well as an improved user experience as it enables [single sign-on](https://auth0.com/blog/what-is-and-how-does-single-sign-on-work/) across the device's apps and browser.

### Centralized Login with Auth0

[Auth0](https://auth0.com) provides a [centralized login approach](https://auth0.com/docs/hosted-pages/login) that adheres to the OAuth 2.0 Best Current Practice for native apps. Centralized login provides the most secure experience and is also easy to implement for developers. A URI is used to trigger an authentication request and the centralized login page is shown to users. This login page can use the [Auth0 Lock widget](https://auth0.com/lock) or your own custom UI. After authorization, the user is returned to your app via your provided redirect. Auth0 provides extensive documentation to help you easily implement the appropriate flows to keep your apps secure and user-friendly as well.

Check out the following resources to learn more about implementing Auth0 with centralized login in your native apps in accordance with the OAuth 2.0 Best Current Practice:

* [Centralized Login Page](https://auth0.com/docs/hosted-pages/login)
* [OAuth 2.0](https://auth0.com/docs/protocols/oauth2)
* [Calling APIs from Mobile Apps (Authorization Code PKCE)](https://auth0.com/docs/api-auth/grant/authorization-code-pkce)
* [iOS Swift Quickstart - Login](https://auth0.com/docs/quickstart/native/ios-swift/00-login)
* [Android Quickstart - Login](https://auth0.com/docs/quickstart/native/android/00-login)

You can sign up for a <a href="https://auth0.com/signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">free Auth0 account now</a> and get started right away, or check out [Auth0's pricing here](https://auth0.com/pricing).


OAuth 2.0 Best Practices for Native Apps

1097492785caf9ffeebffeb624202d8f?s=200 avatar

1097492785caf9ffeebffeb624202d8f?s=200

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

Former Auth0 Employee

Prosper Otemuyiwa

OAuth authorization requests made to Google via embedded browsers have been blocked by Google.



Last year, Google warned that starting **April 20, 2017**, it will no longer allow OAuth requests to Google via embedded browsers, otherwise known as web views. Before now, developers could successfully use web views such as the WebView UI element in Android, UIWebView/WKWebView in iOS, and the equivalents on Windows and OS X to make OAuth requests to Google.

In November, 2016, Google added a notification to their iOS consent page to create awareness amongst developers of the forthcoming deprecation. Earlier this year, **March 2017**, Google added the same notification on the Android consent page.

As of April 20, 2017, Google has blocked OAuth authorization requests via web views. Unfortunately, a lot of developers have not migrated their current apps away from using embedded browsers to make such requests. Therefore, users trying to use their Google accounts to sign in to third party apps that still make use of web views for OAuth logins constantly get the dreaded **403 disallowed_useragent** error like the one below:

<img src="https://images.ctfassets.net/23aumh6u8s0i/5j6Trz9XThrMGb8HQjpDvR/bcf5033d19688de860392db30dc3ab2b/403error" width=400 height=400 />

---

## Solution for Users and Developers

One way to fix this challenge is for developers to upgrade their apps to use the recommended **Google Sign-in** SDK for sign-in and OAuth with Google Accounts for [Android](https://developers.google.com/identity/sign-in/android) and [iOS](https://developers.google.com/identity/sign-in/ios).

Another option is to make use of *AppAuth* (open source OAuth client library) for [Android](http://openid.github.io/AppAuth-Android), [iOS and OSX](http://openid.github.io/AppAuth-iOS).

Google also offers [GTMAppAuth library](https://github.com/google/GTMAppAuth)(iOS and OSX), which enables you to use [AppAuth](http://openid.github.io/AppAuth-iOS) with the [Google Toolbox for Mac - Session Fetcher](https://github.com/google/gtm-session-fetcher) and [Google APIs Client Library for Objective-C For REST](https://github.com/google/google-api-objectivec-client-for-rest) libraries by providing an implementation of `GTMFetcherAuthorizationProtocol` for authorizing requests with AppAuth.

Windows developers can check the [OAuth for Apps: Windows Samples](https://github.com/googlesamples/oauth-apps-for-windows) to learn how to use the device browser (and not an embedded browser) to implement an OAuth Authorizatiom flow to Google in a native app. These are the specific samples:

* [OAuthUniversalApp](https://github.com/googlesamples/oauth-apps-for-windows/blob/master/OAuthUniversalApp/README.md) - Universal Windows Platform app sample.
* [OAuthDesktopApp](https://github.com/googlesamples/oauth-apps-for-windows/blob/master/OAuthDesktopApp/README.md) - Traditional desktop app sample, **WPF(Windows Presentation Foundation)**.
* [OAuthConsoleApp](https://github.com/googlesamples/oauth-apps-for-windows/blob/master/OAuthConsoleApp/README.md) - Console application sample.

## Aside: Using Auth0

One of the most complex features to implement in an application is [user authentication and identity management](https://auth0.com/user-management). Auth0 ships by default with the ability to use device browsers (and not embedded browsers) for Google Sign-in and OAuth with Google accounts. As a developer, using companies like Auth0 to implement this functionality saves you a lot of headache. You won't have to care about changes in the implementation, as Auth0 will take care of them.

![Auth0 hosted login screen](https://images.ctfassets.net/23aumh6u8s0i/4ve30M1qt7GmE2nAYNKOhs/358e1f9aab4405b66fbeb5ca4cfa1eae/angular-aside-login)

Check out how to use [Auth0 Lock for web and native applications](https://auth0.com/lock). Also check out our [quickstarts](https://auth0.com/docs/quickstart/).

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

## Conclusion

Switching away from embedded browsers might be a bit of work, but it provides a large user benefit. This should increase the conversion rate of your sign-in flow because users who are already signed into Google will be able to sign into your app via the tap of a single button. Furthermore, users will experience a smooth login experience, as those that are not signed in will have to sign into Google for the first app they use, but then won't have to sign in again for subsequent apps.


Google Blocks OAuth Requests Made Via Embedded Browsers

df6c864847fba9687d962cb80b482764?size=200 avatar

df6c864847fba9687d962cb80b482764?size=200

Martin Gontovnikas, a.k.a Gonto, is a software engineer at heart who moved to the ‘dark side’ and became VP of Marketing at Auth0. He considers himself lucky to have found a way to combine his two passions and apply his engineering thinking model to marketing.<br/><br/> Gonto’s analytical thinking is a huge driver of his data-driven approach to marketing strategy and experimental design. He is based in the Bay area, and in his spare time, can be found eating gourmet food at the best new restaurants, visiting every local brewery he can find, or traveling the globe in search of new experiences.

Former SVP of Marketing and Growth at Auth0

Martin Gontovnikas

Bluetooth, a standards based organization, chooses Auth0 to implement standards based authentication via OpenID Connect and OAuth for improved security, access, and interoperability.



**BELLEVUE, WA** - [Bluetooth Special Interest Group](https://www.bluetooth.com/) (SIG), a standards based organization that oversees the development and licensing of Bluetooth technologies, has chosen Auth0 to implement standards based authentication throughout their organization. Thanks to Auth0, Bluetooth was able to implement OpenID Connect and OAuth throughout their organization in record time, meeting the needs of today and also laying the foundation for future expansion.

![Bluetooth Website](https://images.ctfassets.net/23aumh6u8s0i/5WAxWlxKMK57zildCrXUv/34eba0420e66aa592dcd657e76c42f2e/site)

Auth0 was chosen not solely for technological capability, but also for state-of-the-art security, top-notch documentation, excellent customer support, and a superior licensing model that was a right fit for Bluetooth. Auth0 allowed Bluetooth to keep their existing infrastructure in place, while adding the standards based authentication layer on top. This allowed the Bluetooth engineering team to quickly implement the solution across multiple disparate apps.

> “Being a standards based organization, it was important for Bluetooth SIG to implement a standards based identity solution for our platform.”
– Jeremy Syme, Director of Systems Engineering

Read the [case study](https://auth0.com/learn/bluetooth-case-study/) to learn more about why Auth0 was the right fit for Bluetooth.

<include src="asides/AboutAuth0" />


Bluetooth Chooses Auth0 to Implement Standards Based Authentication

6222081fd7dcea7dfb193788d138c457?s=60 avatar

6222081fd7dcea7dfb193788d138c457?s=60

Jerrie Pelser

Learn how to use the new OAuth middleware in ASP.NET Core to authenticate a user.

Authenticating a user with LinkedIn in ASP.NET Core

bc94ff6211e645a2bdb4fdc60e23ad85

Kassandra Perch

This is the recording and transcription of a webinar we ran about OAuth 2 recently.

"OAuth"