Understanding OpenID Connect and OAuth2 Grant Types

Emmanuel Gautier · April 5, 2023

In today's digital world, securing web applications and APIs is essential to protect user data and prevent unauthorized access. OAuth2 and OpenID Connect are two popular authentication and authorization protocols that enable secure access to web applications and APIs. Both protocols define different grant types that dictate how access tokens are obtained and used to access protected resources. Understanding these grant types and their use cases is crucial for building secure and reliable applications. In this article, we will explore the various OAuth2 and OpenID Connect grant types, their differences, and when to use them.

Choosing the Right OAuth2/OpenID Connect Grant Type for Your Use Case

When it comes to selecting the appropriate OAuth2/OpenID Connect grant type for an application, there are several factors to consider. The right choice depends on the specific security requirements, the client type (SPA, mobile, TV, ...), and the user experience that you want to provide to your users.

If you need assistance creating your client, you can use our OAuth 2.0 client creation helper for guidance in addition to the explanations provided below.

Web and Mobile Application

If you're building a web application that requires user authentication, the Authorization Code Flow with PKCE extension is a good choice. It provides a higher level of security by requiring the user to authenticate directly with the authorization server, and it also allows for the use of refresh tokens to maintain a longer session.

Machine To Machine

The client credentials grant type is generally more suitable for machine-to-machine (M2M) scenarios such as when running automated tasks or background processes as it allows for the client to authenticate itself using a shared secret, such as a client ID and secret. This approach is more secure than using a user's credentials, as it avoids the need to store and transmit sensitive user information.

IoT and Smart TV

As an IoT device or Smart TV, you may not have a user interface to enter login credentials, which makes it challenging to obtain an access token. Device Authorization Grant is designed specifically for such scenarios, where the device is incapable of handling user interactions. Instead, it provides a unique code to the user that they can enter on a separate device, like a smartphone or a computer, to authorize the device to access their data on their behalf.

Authorization Code Flow

datatracker.ietf.org/doc/html/rfc6749#section-1.3.1

The Authorization Code Flow is one of the most commonly used OAuth2 grant types. It is typically used when a user needs to grant access to their resources to a third-party web or mobile application or service.

In this flow, the user is redirected to the authorization server's login page, where they must authenticate and authorize the application's access to their resources. After the user grants authorization, the authorization server returns an authorization code to the application.

The application then exchanges the authorization code for an access token and refresh token by sending a request to the authorization server's token endpoint. This access token can be used to access the user's protected resources for a specified period of time.

The Authorization Code Flow is considered to be more secure than other grant types like the implicit flow as it requires the client to securely store the client secret and only sends it to the authorization server over a secure channel. It also ensures that the user's credentials are not exposed to the client, as they are only handled by the authorization server during the login process.

Here is an example of an authorization code flow requests:

The client application redirects the user to the authorization server's authorization endpoint with the required parameters, including the client ID, redirect URI, response type set to code, and scope.

GET /authorize?response_type=code&client_id=abcd1234&redirect_uri=https://mydomain.com/callback&scope=<scopes>&state=<state>&nonce=<nonce> HTTP/1.1
Host: authorization-server.com

Here is some explanations about the query parameters used in the authorization code flow request:

response_type: Specifies the type of response desired. For the authorization code flow, this is set to code.
client_id: The unique identifier for the client application.
redirect_uri: The URI to which the authorization server will redirect the user after authorization.
scope: A space-separated list of scopes that specify the level of access requested.
state: An opaque value used to maintain state between the request and callback. It is used to prevent CSRF attacks.
nonce: A random value used to prevent replay attacks in OpenID Connect.

The user authenticates and authorizes the client application to access their resources.
The authorization server redirects the user back to the client application's redirect URI with an authorization code.

GET /callback?code=<authorization_code>&state=<state> HTTP/1.1
Host: mydomain.com

The client checks the state parameter to prevent CSRF attacks and ensures the authorization code is valid.
The client application exchanges the authorization code for an access token and refresh token by sending a request to the authorization server's token endpoint.

POST /oauth/token HTTP/1.1
Host: authorization-server.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=<authorization_code>
&redirect_uri=https://mydomain.com/callback
&client_id=abcd1234
&client_secret=<client_secret>

This flow is recommended for server-side applications where the client secret can be securely stored and is not easily accessible by potential attackers. For public clients like single-page applications (SPAs) or mobile apps, the Authorization Code Flow with PKCE extension is recommended.

PKCE Extension

datatracker.ietf.org/doc/html/rfc7636

PKCE (pronounced "pixie"), for Proof Key for Code Exchange, is an extension to the OAuth2 authorization code flow that provides enhanced security against code interception attacks. It is designed to protect public clients, such as mobile and single-page applications, that cannot keep a client's secret confidential. PKCE adds a unique secret, called a code verifier, to the authorization request. The authorization server responds with a code challenge, which is a hashed version of the code verifier. The client then exchanges the code and code verifier for an access token. PKCE is widely used in modern OAuth2 implementations and is considered a best practice for securing public clients.

You can learn more about PKCE in our dedicated article: What is PKCE and why you should use it?

Client Credentials Flow

datatracker.ietf.org/doc/html/rfc6749#section-4.4

The Client Credentials Flow is used when a client application needs to access resources that it owns or controls, without any user involvement. This flow is suitable for machine-to-machine communication, such as accessing APIs from a backend server.

In this flow, the client application sends its own credentials (client ID and secret) directly to the authorization server. The authorization server verifies the client credentials and issues an access token to the client application.

The client credentials flow involves the following steps:

The client application sends a request to the authorization server with its own client ID and secret, along with the grant type parameter set to client_credentials.
The authorization server validates the client credentials and generates an access token.
The authorization server sends the access token back to the client application.
The client application uses the access token to access the protected resources on the resource server.

Here's an example of a client credentials flow request:

POST /oauth/token HTTP/1.1
Host: authorization-server.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=abcd1234
&client_secret=<client_secret>

The client credentials flow is useful when the client application needs to access its own resources without involving a user in the process. However, it should not be used if the resource server needs to know the identity of the user accessing the resource. In such cases, the authorization code flow or another suitable flow should be used instead.

Refresh Token Grant Type

datatracker.ietf.org/doc/html/rfc6749#section-1.5

The Refresh Token grant type is used to obtain a new access token and refresh token pair using a refresh token that was previously issued to the client. This flow is useful when an access token has expired or is about to expire and the client needs to obtain a new one without initiating a new complete authorization process involving the user.

In this flow, the client sends a request to the authorization server with the grant_type parameter set to refresh_token and includes the refresh token that was previously issued. The authorization server then verifies the refresh token and issues a new access token and refresh token pair.

Refresh tokens are typically longer-lived than access tokens and can be revoked independently of access tokens. This makes them useful for maintaining long-lived sessions and providing a better user experience.

It's important to note that the use of refresh tokens introduces additional security considerations, as they represent long-lived credentials that can be used to obtain access tokens without requiring the user to re-authenticate. Therefore, refresh tokens must be protected appropriately and should only be issued to trusted clients that have been properly authenticated and authorized.

The Refresh Token grant type should be used in scenarios where the client needs to obtain a new access token without user intervention, and where the use of long-lived credentials is acceptable and properly secured.

Rotating Refresh Token Mechanism

The rotating refresh token mechanism is a security feature that helps to prevent long-term abuse of refresh tokens. It involves issuing a new refresh token along with a new access token whenever a refresh token is used. The new refresh token invalidates the previous refresh token, and the process repeats each time a new refresh token is used.

This mechanism ensures that if a refresh token is stolen, it will only be valid for a limited time, making it harder for attackers to use it to obtain unauthorized access. It also helps to detect and prevent replay attacks, where an attacker tries to use a previously obtained refresh token to obtain new access tokens.

When implementing the rotating refresh token mechanism, it's important to strike a balance between security and usability. If refresh tokens expire too quickly, users may be required to re-authenticate frequently, which can be frustrating. On the other hand, if refresh tokens last too long, the risk of a stolen refresh token being abused is higher.

Device Authorization Grant

datatracker.ietf.org/doc/html/rfc8628#section-3.4

The Device Authorization Grant type (also known as the Device Flow) was introduced in OAuth2.1 and is designed for devices that don't have a web browser, such as a TV or a game console, to obtain an access token. In this flow, the user visits a special authorization endpoint on a separate device, such as a mobile phone or laptop, to initiate the authorization process. The device that requires authorization then displays a message with a unique code and instructions for the user to enter the code on a separate device.

The authorization server polls for the authorization by the device and, once authorized, returns an access token to the device. This flow can also include a refresh token.

The Device Authorization Grant type is useful in situations where a user cannot directly enter their credentials on the device that requires authorization, or where the device lacks the ability to present a login screen. However, it should be noted that this flow can introduce security concerns, as the user may not be fully aware of the extent of the permissions they are granting to the device. As with any OAuth2 grant type, it should be used only in situations where it is appropriate and secure.

User Assertion Flow with JWT-Bearer Grant Type

datatracker.ietf.org/doc/html/rfc7523

In OAuth2, the User Assertion Flow is a mechanism that allows a client application to authenticate a user and obtain an access token on behalf of that user using a JSON Web Token (JWT) or a SAML as the user's assertion. The urn:ietf:params:oauth:grant-type:jwt-bearer grant type is specifically designed for this purpose.

How it works

The User Assertion Flow with the JWT-Bearer grant type typically involves the following steps:

User Authentication: The client application authenticates the user using a mechanism outside of OAuth2, such as a login form, a social media login, or a multi-factor authentication process. Once the user is authenticated, the client application obtains a JWT representing the user's identity.
JWT Creation: The client application creates a JWT using the user's authenticated information as the assertion. The JWT is typically signed using the client's private key to ensure its integrity.
Token Request: The client application sends a token request to the token endpoint of the authorization server, including the JWT as the user assertion in the request payload, along with other required parameters such as the grant type (urn:ietf:params:oauth:grant-type:jwt-bearer), client ID, and scope.

POST /oauth/token HTTP/1.1
Host: authorization-server.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&scope=<scopes>
&assertion=<jwt>

Assertion Validation: The authorization server receives the token request and validates the JWT user assertion. This typically involves verifying the signature of the JWT using the client's public key, checking the expiration time, and verifying any other relevant claims or attributes.
Access Token Issuance: If the JWT user assertion is valid, the authorization server issues an access token or other tokens, such as a refresh token, that represents the user's authorization. The client application can then use the access token to access protected resources on behalf of the user.

When implementing the User Assertion Flow with the JWT-Bearer grant type, there is an important consideration to keep in mind. As with any OAuth2 flow, security is paramount. The JWT used as the user assertion must be properly secured, including appropriate signing and encryption mechanisms, to ensure its integrity and confidentiality.

Token Exchange Grant Type

datatracker.ietf.org/doc/html/rfc8693

The Token Exchange Grant Type allows an entity (referred to as the "actor") to exchange one token for another token with a different set of permissions or scopes. The actor can be a client application or a user. This grant type enables delegation of access and allows for fine-grained control over the permissions granted to a token.

This grant type is used as urn:ietf:params:oauth:grant-type:token-exchange and involves the exchange of an existing token for a new token with different scopes and audiences. The exchange is facilitated by making a token exchange request to the token endpoint of the authorization server.

POST /oauth/token HTTP/1.1
Host: authorization-server.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&client_id=abcd1234
&client_secret=<client_secret>
&scope=<scopes>
&subject_token=<access_token>
&subject_token_type=urn:ietf:params:oauth:token-type:access_token

Implicit Grant

datatracker.ietf.org/doc/html/rfc6749#section-1.3.2

The Implicit flow is an OAuth2 authorization grant type that was initially designed for browser-based client-side applications such as single-page applications (SPAs). The flow was intended to simplify the client-side authentication process by removing the need for a server-side component to handle the client's secret.

However, the implicit flow has some significant security flaws, and its use is no longer recommended by the OAuth2 specification. One of the most significant issues with the implicit flow is that it returns the access token directly to the client-side application as a fragment identifier in the URL. This means that the access token is exposed to the client-side application and can be easily intercepted by a malicious actor.

Another issue with the implicit flow is that it does not support refresh tokens, which are used to obtain a new access token when the original one expires. This means that the user must re-authenticate every time the access token expires, which can be a poor user experience.

In summary, while the implicit flow was initially designed to simplify the client-side authentication process, its use is not recommended due to its security flaws. Instead, it is recommended to use the authorization code flow with PKCE, which provides a more secure and robust authentication mechanism for browser-based client-side applications.

Implicit Grant Deprecation

This flow is deprecated, you should not use it. Here are some resources giving details about this deprecation:

Resource Owner Password Credentials Grant (ROPC or ROPG)

The Resource Owner Password Credentials Grant (ROPC) allows an application to directly obtain the end user's username and password and exchange them for an access token. This grant type is often used for legacy systems or cases where other grant types are not feasible.

However, using ROPC introduces some significant security risks. First, the application must store the end user's credentials, which can be a major security concern if the application is compromised. Additionally, ROPC violates the separation of concerns principle that is a key part of OAuth 2.0.

ROPC must not be used. It's worth noting that some OpenID Connect providers may not support ROPC at all, as it is considered a less secure option.

Overall, it's recommended to use other grant types whenever possible to provide a more secure and robust authentication flow.

Resource Owner Password Credentials Grant Deprecation

This flow is deprecated, you should not use it. Here are some resources giving details about this deprecation:

OAuth 2.0 Security Best Current Practice Resource Owner Password Credentials Grant Section

OpenID Connect Hybrid Flow

https://openid.net/specs/openid-connect-core-1_0.html#HybridFlowAuth

The OpenID Connect Hybrid Flow is a combination of the authorization code flow and the implicit flow. This flow is designed for applications that require access to user information, and is recommended when the client application is a web application running on the server side.

The hybrid flow works by first sending the user to the authorization server to authenticate and authorize the application, similar to the authorization code flow. Once the user has authenticated and authorized the application, the authorization server sends an authorization code to the application.

The application then uses the authorization code to retrieve an access token from the authorization server, similar to the authorization code flow. However, in addition to the access token, the authorization server also returns an ID token, similar to the implicit flow.

The ID token contains user information, such as their name and email address, in a JSON Web Token (JWT) format. This allows the application to authenticate the user and access their information without having to make additional API calls.