The OAuth 2.0 Flows - Part II - App Security Mantra

In the previous post, we learnt about main actors and terminologies used in OAuth 2.0. We started discussing about grant types (OAuth flows) and talked about most used grant type i.e. authorization code grant.

In this post we will discuss remaining three types of grants. Let’s start –

2. Implicit grant

The implicit grant type is used to obtain access tokens (it does not support the issuance of refresh tokens) and is optimized for public clients known to operate a particular redirection URI. These clients are typically implemented in a browser using a scripting language such as JavaScript.

This is again a redirection-based flow, the client must be capable of interacting with the resource owner’s user-agent (typically a web browser) and capable of receiving incoming requests (via redirection) from the authorization server.

Unlike the authorization code grant type, in which the client makes separate requests for authorization and for an access token, the client receives the access token as the result of the authorization request.

The implicit grant type does not include client authentication, and relies on the presence of the resource owner and the registration of the redirection URI. Because the access token is encoded into the redirection URI, it may be exposed to the resource owner and other applications residing on the same device.

The client will construct a request URI to the authorization server endpoint with the following parameters in the query string:
- response_type with the value token (Required)
- client_id with the client identifier (Required)
- redirect_uri with the client redirect URI (Optional)
- scope a space delimited list of scopes (Optional)
- state with a CSRF token (Recommended). This parameter is optional but highly recommended. You should store the value of the CSRF token in the user’s session to be validated when they return.

The client directs the resource owner to the constructed URI using an HTTP redirection response, or by other means available to it via the user-agent.

 For example, the client directs the user-agent to make the following HTTP request using TLS:

GET /authorize?response_type=token&client_id=s6BhdRkqt3&state=xyz&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1
Host: server.example.com

All of these parameters are validated by the authorization server. The user will then be asked to login to the authorization server and approve the client.
If the user grants the access request, the authorization server issues an access token and delivers it to the client by adding following parameters to the fragment component of the redirection URI :
- token_type with the value Bearer
- expires_in with an integer representing the life span of the access token
- access_token the access token itself
- state with the state parameter sent in the original request. You should compare this value with the value stored in the user’s session to ensure the authorization code obtained is in response to requests made by this client rather than another client application.

This grant does not return a refresh token because the browser has no means of keeping it confidential. It is mainly used with mobile apps or web applications (applications that run on the user’s device).

3. Resource owner password credentials grant

This grant type is suitable where resource owner has a trust relationship with the client such as device operating system or highly privileged application. The authorization server should only allow this grant type when other flows are not viable.

The method through which the client obtains the resource owner credentials is beyond the scope of OAUth 2.0 specification. The client must discard the credentials once an access token has been obtained.

Resource Owner Password Credentials Flow

The client will ask the user for their authorization credentials (usually a username and password). The client then sends a POST request with following body parameters to the authorization server:
- grant_type with the value password
- username with the user’s username
- password with the user’s password
- scope with a space-delimited list of requested scope permissions.

The authorization server will respond with a JSON object containing the following properties:
- token_type with the value Bearer
- expires_in with an integer representing the life span of the access token
- access_token the access token itself
- refresh_token a refresh token that can be used to acquire a new access token when the original expires

An example successful response:

     HTTP/1.1 200 OK
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "access_token":"2YotnFZFEjr1zCsicMWpAA",
       "token_type":"Bearer",
       "expires_in":3600,
       "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
       "example_parameter":"example_value"
     }

This grant type is suitable for clients capable of obtaining the resource owner’s credentials (username and password, typically using an interactive form). It is also used to migrate existing clients using direct authentication schemes such as HTTP Basic or Digest authentication to OAuth by converting the stored credentials to an access token.

It is used with trusted Applications, such as those owned by the service itself

4. Client credentials grant

The simplest of all of the OAuth 2.0 grants, this grant is suitable for machine-to-machine authentication where a specific user’s permission to access data is not required.

The client can request an access token using only its client credentials (or other supported means of authentication) when the client is requesting access to the protected resources under its control.

As the client authentication is used as the authorization grant, no additional authorization request is needed. So access token is directly requested.

The client sends a POST request with following body parameters to the token endpoint of the authorization server:
- grant_type with the value client_credentials
- client_id with the the client’s ID
- client_secret with the client’s secret
- scope with a space-delimited list of requested scope permissions

The authorization server will respond with a JSON object containing the following properties:
- token_type with the value Bearer
- expires_in with an integer representing the life span of the access token
- access_token the access token itself

A refresh token should not be included. If the request failed client authentication or is invalid, the authorization server returns an error response.

An example successful response:

     HTTP/1.1 200 OK
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "access_token":"2YotnFZFEjr1zCsicMWpAA",
       "token_type":"Bearer",
       "expires_in":3600,
       "example_parameter":"example_value"
     }

The client credentials grant type must only be used by confidential clients. It is used with Applications API access.

Refresh Token Flow

Once an access token expires, a request to the resource using this token will result in an “Invalid Token Error”. At this point, a refresh token can be used to request a fresh access token from the authorization server.

Refresh tokens carry the information necessary to get a new access token. If the authorization server issued a refresh token to the client, the client makes a refresh request to the token endpoint using the parameter grant_type as “refresh_token”.

Here is an example POST request, using a refresh token to obtain a new access token:

For example, the client makes the following HTTP request using transport-layer security:

     POST /token HTTP/1.1
     Host: server.example.com
     Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
     Content-Type: application/x-www-form-urlencoded

     grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA

Conclusion

OAuth 2.0 defines four types of major grants. Grants are basically methods to obtain access token. It is very important to understand and decide which type suits in your scenario which depends on mainly your client type and also on other parameters we just talked.

Some of the grant types support a refresh token which enables the client to get a new access token (when it is expired) without requiring the user to be redirected.

Thank you for reading, it was quite a long post! Stay Safe, Stay Secure!