OAuth Grant Types Guide

In today’s text, I will describe and explain OAuth Grant Types — the processes of authorization. I will start with a quick recap of the most basic OAuth roles.

Recap of OAuth Roles

Although you probably know them already, I want to make a quick recap for everyone reading this to be on the same page.

There are four main concepts in OAuth:

1. Resource owner — entity capable of granting access to the protected resource. When a resource owner is a person, they are referred to as an end-users.
2. Resource server — server hosting the protected resources. Capable of accepting and responding to protected resource requests using access tokens.
3. Client — application making protected resource requests on behalf of the resource owner and with its authorization.
4. Authorization server — server issues access tokens to the client after successfully authenticating the resource owner and obtaining authorization.

What Is Grant Type?

Grant Type is a process of obtaining an Access Token. It describes the exact sequence of steps involved in handling a particular request. Grant Type affects how applications involved in handling particular requests communicate with one another.

Because of that, an OAuth service must be configured to support a particular Grant Type before a client application can initiate it. The client application specifies which grant type it wants to use in the initial authorization request it sends to the OAuth service.

In most cases, information about the picked Grant Type is stored under the grant_type param of the authorization request. Besides, Grant Type determines the shape and form of an access token.

Although the original protocol of authorization described in the OAuth specification looks quite complex.

Modern tools do a lot of work behind the scenes. Thanks to that, we usually have to send only one request similar in structure to the one below.

https://api.authorization-server.com/token&
  grant_type=authorization_code&
  code=AUTH_CODE_HERE&
  redirect_uri=REDIRECT_URI&
  client_id=CLIENT_ID&
  client_secret=SECRET

As for naming conventions, Grant Types are often referred to as “Flows” or “Specification.” Remember that these three terms may describe the same thing.

OAuth Grant Types

The original OAuth specification describes four different grant types:

1. Authorization Code
2. Implicit (or Implicit Flow)
3. Resource Owner Password Credentials (or Password Grant),
4. Client Credentials.

We can also count Refresh Token as a separate grant type. This is because it has its own process description and relies on exchanging refresh tokens for access tokens. Moreover, OAuth provides the mechanism for creating new custom grant types, so if you have enough determination, you can create your own grant type.

Over the years, a few things have changed. Password and Implicit grants became obsolete — not in the way that they are not supported. They are no longer recommended; using them is considered a bad practice.

We also got a new grant type — Device Code and security extension called — Proof Key for Code Exchange (PKCE).

Grant Types Lexicon

Authorization Code

Authorization Code is a grant type used to obtain access and refresh tokens. It works by exchanging an authorization code for an access token. The Authorization Code grant is optimized for confidential clients but also can work with public clients.

It is one of the grants which require redirection to work. The client must be able to interact with the resource owner’s user agent (typically a web browser) and receive incoming requests (via redirection) from the authorization server. The authorization code itself will be embedded in a redirect URL from the resource owner’s agent and used to request an access token.

What is notable here is that the resource owner’s credentials are never shared with the client. Moreover, the direct transmission of the access token to the client without passing it through the resource owner’s user-agent eliminates the possibility of exposing our valuable tokens to unwanted agents.

Implicit

This grant type is the simplified version of the Authorization Code grant. It is optimized for clients running in the browser. It imminently returns an access token, omitting the authorization code exchange step.

Implicit grant can improve the responsiveness and efficiency of some clients because it reduces the overall number of steps needed to achieve the final result. On the other hand, this grant type does not authenticate the client. The token can be exposed to any other agent with access to the resource owner’s user app.

It means that we can expose our app to many new security attacks. It is the reason why Implicit Grant is no longer recommended by OAuth creators. Instead, they favor the Authorization Code grant with PKCE extension.

What is more, OAuth 2.0 Security Best Practice recommends not using the Implicit Grant at all.

Resource Owner Password Credentials

In my opinion, it is the simplest grant type around, as it requires only one request to retrieve an access token. It works by exchanging user credentials (for example, username and password) to obtain an access token.

This grant type can eliminate the need for the client to store the resource owner credentials for future use by exchanging the credentials with a long-lived access token or refresh token.

Previously it was believed that it should be used only in cases when there is a high degree of trust between the resource owner and the client and when using other grant types is not possible. However, because of direct access to user credentials, this grant type is no longer recommended.

The latest OAuth 2.0 Security Best Practice disallows the Resource Owner Password Credentials grant entirely.

Client Credentials

It is a grant type used to obtain an access token without user context — using only client credentials. It is the best grant in use cases when the authorization scope is limited to the protected resources under the control of the client or when protected resources were previously arranged with the authorization server. Moreover, this grant requires the usage of confidential clients.

Refresh Token

This grant type is probably the most crucial one. It allows the client to achieve continuous usage of valid tokens without further interaction from the user side. As you might expect, it works by exchanging a refresh token for an access token that has expired.

According to OAuth Spec, a refresh token is a token issued optionally to the client by the Authorization Server alongside an access token. It is a string representation of the authorization granted to the Client by the Resource Owner and usually is opaque to the Client. Therefore, refresh Tokens are also intended to be used only with Authorization Servers and are never sent to Resource Servers.

Device Authorization Grant

Device Authorization Grant or Device Flow is an extension to OAuth 2.0 in the form of a single RFC 8628. Its main point is to add the possibility of obtaining an access token for devices with no browser or with limited input capabilities.

The device which you want to use with Device Authorization Grant must meet a few requirements:

• First, the device is already connected to the Internet.
• Second, the device is able to make outbound HTTPS requests.
• Third, the device is able to display or otherwise communicate a URI and code sequence to the user.
• Finally, the user has a secondary device (for example smartphone) from which they can process the request.

This grant type does not require two-way communication between the OAuth client and the user agent on the same device (unlike other OAuth grant types). Thus it can support several use cases that other grants are not able to cover. What is more, this is the only grant that requires using a secondary device to approve the access request.

Remember that this grant type is not intended to replace browser-based OAuth in apps on devices like smartphones. Instead, those apps should use yet another grant specified in a separate RFC.

Device Code

Device Code grant was created as an extension grant in RFC 6749 to play an important part in Device Authorization Grant. It uses Device Code grant to exchange the previously obtained device code for an access token. When performing a request, its “grant_type” URL parameter must be set to: "urn:ietf:params:oauth:grant-type:device_code".

Proof Key for Code Exchange

Proof Key for Code Exchange, or PKCE, was presented in RFC 7636. It is an extension to the Authorization Code grant type. It aims to provide additional protection against CSRF and authorization code injection attacks.

PKCE turned out to be useful also for web apps that use a client secret. Then it became a general recommendation in many other OAuth grant types.

Summary

OAuth specification describes grant types for many popular use cases. Starting from simple client-server authorization via mobile apps to two-factor authorization for more complex systems. Everyone can find something interesting in such a collection. I hope that this humble lexicon of flows will come in handy to you at some point. Thank you for your time.