Comparison of OAuth2/OIDC Grant Types

The OAuth2 and OpenID Connect (OIDC) specifications define Grant Types, which are different ways of performing authentication and authorization. The Grant types are:

• Authorization Code Grant
• Authorization Code + PKCE Grant
• Implicit Grant
• Hybrid Grant
• Resource Owner Password Grant
• Refresh Token Grant

Terminology

The OAuth2 and OpenID Connect specifications use different terminology than the SAML 2.0 and WS-Federation specifications. The terms and their meanings are:

• Resource Owner – The user.
• Client – The Oauth2/OIDC Enabled application. This can be an application on a web server, mobile, device, browser-based application (for example JavaScript), or thick client.
• Authorization Server – A Service that can authenticate users and prompt for users to grant requested permissions (the OptimalCloud for example). Can also validate OAuth2/OIDC tokens.
• Resource Server – An Oauth2/OIDC Enabled API.
• Access Token - A Token used to grant access to services on behalf of the user. The format is undefined by the OAuth/OpenID Connect specifications.
• ID Token - A Token used in OpenIDConnect to obtain Identity Information about the user. The ID Token must be a Jwt Token.
• Scope Values - Permissions granting access to user information.

Authorization Code Grant

How the Authorization Code Grant Works

In the Authorization Code Grant, the application performs a federation Request. The application may also include one or more scope values in the Request. If the user does not have an active session on the Authorization Server (the OptimalCloud), authentication is required. The user may be required to approve the the scope values included in the Request.

After authentication and authorization, an Authorization Code is returned to the application. The application then exchanges the Authorization Code and Client Secret for an Access Token and an ID Token. In certain cases, a Refresh Token may also be returned. The Access Token or ID Token can then be used by the application to make API calls to an OAuth2/OIDC enabled API.

When to Use the Authorization Code Grant

Because the Authorization Code Grant requires that the Client Secret be secured, it is not appropriate for browser-based applications, such as those written in JavaScript. For the same reason it is not appropriate for desktop applications and mobile applications. The Authorization Code Grant is best suited for applications hosted on a web server where the Client Secret can be secured.

Authorization Code and PKCE Grant

How the Authorization Code + PKCE Grant Works

The Authorization Code + PKCE Grant works very similar to the Authorization Code Grant, but before requesting an Authorization Code, the application generates a random value known as a Verifier, and a Challenge derived from the Verifier. The Challenge is sent along with the request for an Authorization Code. When exchanging the Authorization Code for a token, the application sends both the Authorization Code and the Verifier. The Authorization Server validates that the previously sent Challenge value cryptographically matches the Verifier value. The Client Secret is not needed in the Authorization Code + PKCE Grant.

When to Use the Authorization Code + PKCE Grant

The Authorization Code + PKCE Grant was designed for browser-based, desktop, and mobile applications, because there is no Client Secret that must be protected. It is also suitable for use for applications hosted on a web server.

Implicit Grant

How the Implicit Grant Works

In the Implicit Grant, the application performs a federation Request. The application may also include one or more scope values in the Request. If the user does not have an active session on the Authorization Server (the OptimalCloud), authentication is required. The user may be required to approve the scope values included in the Request.

After authentication and authorization, the Access Token and ID Token are returned to the application. In certain cases, a Refresh Token may also be returned. The Access Token or ID Token can then be used by the application to make API calls to an OAuth2/OIDC enabled API.

When to Use the Implicit Grant

The Implicit Grant was designed for browser-based, desktop, and mobile applications. Although it is still acceptable to use for those applications, it is now recommended to use the Authorization Code + PKCE Grant instead. Although the Implicit Grant is still widely used, there are no applications for which it is the recommended Grant.

Hybrid Grant

How the Hybrid Grant Works

The Hybrid Grant is a combination of the Authorization Code Grant and the Implicit Grant. The application can request any combination of Authorization Code, Access Token, or ID Token. In certain cases, a Refresh Token may also be returned. The Authorization Code, if requested, can then be exchanged for an Access Token or ID Token, even if those tokens were returned in the original Response.

When to Use the Hybrid Grant

Although the Hybrid Grant provides additional flexibility over the other grants, there is no compelling reason to use it. The Hybrid Grant is supported by the OptimalCloud, but Optimal IdM recommends using the Authorization Code + PKCE Grant instead.

Resource Owner Password Grant

How the Resource Owner Password Grant Works

In the Resource Owner Password Grant the user supplies his user ID and password to the application. The application requests a token, supplying the user’s user ID and password. The Access Token and ID Token are returned to the application. In certain cases, a Refresh Token may also be returned. The Access Token or ID Token can then be used by the application to make API calls to a Resource Server.

When to Use the Resource Owner Password Grant

The Resource Owner Password Grant is most applicable for applications that are not web applications such as Desktop Clients. When using the Resource Owner Password Grant, the user credentials must be handled in a secure fashion.

Refresh Token Grant

How the Refresh Token Grant Works

The Refresh Token is a longer-lived token that is only used to request new Access and ID Tokens. In the Refresh Token Grant, the application sends the Refresh Token to the Authorization Server (the OptimalCloud) and gets back a new Access Token and ID Token. A new Refresh Token is also returned, and the original Refresh Token should be discarded.

When to Use the Refresh Token Grant

The Refresh Token Grant should be used when an application needs a fresh Access or ID Token but doesn’t want to force the user to re-authenticate. This is most often used for desktop and mobile apps. Note the Refresh Token should be stored securely and used only once.

Setting up an OAuth/OIDC Application in The OptimalCloud

To set up an OAuth/OIDC Application in The OptimalCloud go to the Application Manager on the Identity Management tab in The OptimalCloud Portal.

Please see the Create Application section of The OptimalCloud documentation for further information.