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 Staff 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

andrea-chiarelli

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

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

Principal Developer Advocate

Andrea Chiarelli

Dive 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

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

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)?

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

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

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

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

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

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

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"