OAuth Token Grants

In the previous blog post, I explained what’s OAuth and how it can be used when developing applications. And also I explained the four roles and the tasks of each role when it comes to retrieving protected resources.

Also in the previous blog post I simply describe about the main four grant types that a client can use to retrieve an access-token.

So in this blog post, I’m planning to go in detail with these grant types.

Authorization code grant type

The authorization code grant type is used to obtain both access tokens and refresh tokens, and this type is optimized for confidential client.

Refresh token are credentials to get an access-token, or in simple form, refresh token are used to get a new token when the current token was expired or invalid.

In authorization code grant type, first the client initiates the flow by directing the resource owner’s user-agent (the web browser) to the authorization endpoint at the authorization server using HTTP GET request. After that user will get the user concern page, where the user (Resource owner) approve the client. Along with this request we need to send some parameters. Since this is a GET request, all the parameters are going through URL query param.

·        Response_type

In this parameter the value should be code and it’s a mandatory parameter.

·        client_id

This is the unique id value that you get when you register a new application. This is also a mandatory parameter.

·        redirect_uri

The same uri that we used when registering the application.

·        scope

Indicate what resources that the client need.

·        state

This parameter is used to prevent cross-site request forgery.

The flow

As I mentioned in the above paragraph, the client initiate the flow by redirecting users web browser(user-agent) to the authorization endpoint using a HTTP GET request. The parameters I mentioned above also going along with this request.

Then the user will redirect to the user-concern page. We assume that user is already logged into the relevant resource server as an example the user is already logged in to his/her facebook account, if not the resource server will validate the user, example prompting the login page. If the resource owner approve the client, the authorization server will response to the previously send GET request’s “response_type” parameter with the code. This is call as the CODE in authorization code grant type. (if you give the state parameter in the request, the response also should have the same parameter with same value).

Still this is not the access token.

So the client now has the code, and need to send a HTTP POST request to the token endpoint in the authorization server. In this request the parameters are,

·        grant_type

this should be authorization_code.

·        code

the code we get from the authorization server’s authorization endpoint.

·        redirect_uri

·        client_id

Along with these parameters and all, we also need to add a header with the header name as authorization and the header value should be Basic<space>base64 encoded <client_id:client_secret>. To make this easy, let me give you an example from a code itself, 

Got the idea 😉? 

So this request goes to the authorization server and this server will authenticates the client by getting the authorization header and get the string next to the basic, that means the encoded client credentials, and decode it using the same algorithm (base64). Then the server gets the client_id and client_secret , and validates the client. And also validate the code comes in the body. If all the authentication and validation process is successful, the access-token along with the refresh-token will be issued via a JSON object. 

An example JSON response,
{ "access_token":"sjfgsljfgsljgvldjvldivdlvidvdbvlbd", "token_type":"bearer", "expires_in":3600, "refresh_token":"qwertyuiopsdfghjklkhcbdsf", "example_parameter":"example_value" }

So this is the entire flow of getting the access-token using OAuth 2.0 authorization code grant type. Obviously after retrieving the access-token the client can present it to the resource server, and obtain protected resources of the resource owner. 

Above is a simple sequence diagram to demonstrate the flow of OAuth 2.0 authorization code grant 😊

Implicit grant type

The implicit grant type is used only to obtain access tokens and it does not support the issuance of refresh tokens. This grant type is optimized for clients that are typically implemented in a browser using a scripting language such as JavaScript. 

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

In authorization code grant type as we discussed, the client makes two separate requests to the authorization server to get the authorization code and the access token. In implicit grant, the client receives the access-token as the result of the authorization request. So the implicit grant type does not require client authentication but relies on resource owner and the redirection uri.  

The flow

First the client initiate the flow by redirecting the resource owner’s user-agent to the authorization endpoint. Along with this request the following parameters will go to the authorization server,

• response_type 

            In this parameter the value should be token and it’s a mandatory parameter.

• client_id

This is the unique id value that you get when you register a new application. This is also a mandatory parameter.

• redirection_uri

The same uri that we used when registering the application. 

• scope

             Indicate what resources that the client need.

• state 

             This parameter is used to prevent cross-site request forgery.

So, this is the authorization request. 😊

Then, the authorization server authenticates the resource owner via the user-agent and confirms whether the resource owner grants or denies the client’s request. 

If the resource owner grants the client’s request, the authorization server redirects the user-agent back to the client using the redirection uri provided by the client when registering the application. In this response from the authorization server, the server issues an access token and delivers it to the client by adding the following parameters to the fragment component of the redirection uri.

• access_token

Required parameter. The access-token issued by the authorization server. 

• token_type

Required parameter. The type of token issued. The access token type provides the client with the information required to successfully utilize the access token to make a protected resource request. As examples, bearer type and mac type access tokens. 

• expires_in

The scope of the access-token. 

• scope

The scope of the access-token. 

• state

Required parameter if the “state” parameter was present in the client authorization request. This is used for prevent cross site request forgery attacks (CSRF).

As I mentioned above in this grant type, the authorization server will not issue a refresh-token.

After receiving the fragmented uri, the user-agent follows the redirection instruction by making a request to the web-hosted client resource. The user-agent retains the fragment information locally. The web-hosted client resource returns a web page capable of accessing the full redirection uri including the fragment retained by the user-agent, and extracting the access-token contained in the fragment. 

In simple terms😅, after receiving the redirection uri with the fragment which contain the access-token and above mentioned parameters, a client side script such as JavaScript will extract the access-token and other parameter values separately. 

So, after the user-agent gets the access-token, it will passes the access-token to the client.

An example response with the fragmented url,

http://example.com/callback#access_token=asgjhgjuekfwiuqjbiqbvivbihqv&state=xyz123
&token_type=bearer&expires_in=3600

This is the entire flow of getting the access-token using OAuth 2.0 Implicit grant type. 😉

Above is a simple sequence diagram to demonstrate the flow of OAuth 2.0 implicit grant 😊

Resource owner password credential grant type

The resource owner password credential grant type is suitable in cases where the resource owner has a trust relationship with the client, for an example we can take the Facebook mobile application. The authorization server should take special care when enabling this grant type and only allow it when other flows are not viable. 

This grant type is suitable for clients capable of obtaining the resource owner’s credentials such as the username and the password. This typically happens by using an interactive form.

The flow

The resource owner provides the client with its username and password which we called the “client credentials”.  

The client requests an access-token from the authorization server’s token endpoint by including the credentials received from the resource owner. Along with this request, the following parameters will go, 

• grant_type

Required parameter. Value must be set to password. 

• username

Required parameter. This should be the resource owner’s username. As an example if its facebook, user’s email will be the value of this parameter.  

• password

Required parameter. This should be the resource owner’s password. As an example if its facebook, user’s password. 

• scope

            Indicate what resources that the client need.

When making this request, the client authenticates with the authorization server. To this to happen, need to add Authorization header with client’s basic value (as mentioned above when explaining authorization code grant type). An example request,

POST /token endpoint Host: server.facebook.com Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/x-www-form-urlencoded grant_type=password&username=johndoe&password=A3ddj3w

(in here the Content-Type header related to url encoring)

Next, the authorization server authenticates the client and validates the resource owner credentials. If this whole thing is a success, authorization server will issue an access-token.

In the response, if it's a success response, authorization server returns 

• access_token 
• refresh_token 
• token_type 
• expires_in 

parameters along with their values to the client as a JSON object. an example response, 

{ "access_token":"ydfgkuyfwygweuyfggcg", "token_type":"bearer", "expires_in":3600, "refresh_token":"retywuytfcjhcsfisfycgte", }

So after all this, client gets an access-token and it will be presented to the resource server. Resource server will validate the access-token and provide the client with the requested resources. 

Above is an example sequence diagram to demonstrate the flow of OAuth 2.0 resource owner password credential grant 😊

Client credential grant type

The client can request an access-token using only its client credentials when the client is requesting access to the protected resources under it's control.

The client credential grant type must be used by confidential clients. 

The flow

First the client authenticates with the authorization server and requests an access-token from the token endpoint.

The client makes a request to the token endpoint using following parameters.

• grant_type

                  Required parameter, and the value must be set to client_credentials.

• scope

      Indicate what resources that the client need.

An example request, 

Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/x-www-form-urlencoded grant_type=client_credentials

Then the authorization server authenticates the client, and if valid, issues an access token in a JSON object with the following parameters, 

• access_token
• token_type
• expires_in
• and other parameters according to the request send by the client. 

An example response,

{ "access_token":"qwegdyvgdfuhkdsuhiushjsygvbsdch", "token_type":"bearer", "expires_in":3600, "example_parameter":"example_value" }

Above is an example sequence diagram to demonstrate the flow of OAuth 2.0 client credential grant 😊