Understanding Workflow Of OAuth2.0 Authorization Grant Types

Introduction

OAuth is an open standard used for authorization; i.e. to grant access to functionality/data/etc. without having to deal with the original authentication.

It allows a user to grant access to a client application to the user's protected resources, without revealing user credentials. These resources could be photos or contacts that are usually stored on resource servers. OAuth does this by granting the requesting client application a token after the user approves access. Each token grants limited access to specified resources for a specific period.

This article demonstrates the basic workflow of various authorization grant types in the OAuth2.0 framework.

Different Types of Authorization Grants

The application that uses an OAuth flow to get an access token and then which flow we use will depend on what kind of app it is things like where it is deployed and other properties about the app.

There are four Authorization grant types defined and used in different contexts.

1. Authorization Code: Used for back-end web apps, native apps
2. Implicit: Used for SPA app executing on the user's browser.
3. Client Credential: Used for machine-to-machine authentication or service accounts where there isn't a user involved
4. Resource Owner Password Credential: Used for highly trusted apps, not recommended.

Actors in OAuth2.0 workflow

• User/Resource Owner
  Owner of a user resource; i.e. end-user, who is giving access to some portion of his/her account.
• User-Agent
  Browser or native app.
• Client Application
  The application that is attempting to get access to the user’s account or a resource on the Resource Server i.e. APIs. This application could be a website, desktop, or mobile app.
• Authorization Server
  The server where the client applications are registered. It holds user identities, authenticates a user, and asks him/her to grant the client app to access a protected resource hosted by a resource server, and then issues an access token to the client app.
• Resource Server
  The Web API or web service that hosts the secured and protected user resources and is protected by OAuth. It shares user resources with the client app in possession of an appropriate access token.

Authorization server endpoints

To generate an access token, the authorization server uses two endpoints.

• Authorization endpoint: used by the client to obtain authorization from the resource owner via user-agent redirection.
• Token endpoint: used by the client to exchange an authorization grant for an access token, typically with client authentication.

Workflow of Authorization Code Grant Type

This grant type is commonly used because it is optimized for server-side web-based applications where the source code is not publicly exposed and client secret confidentiality can be maintained.

This is a redirection-based flow where the authorization code is routed through the user agent.

The authorization code grant type is used to obtain both access tokens and refresh tokens.

Client Application Registration

Before using OAuth, the client application must be registered into the authorization server with the below information.

• Application Name
• Application Website
• Redirect URI or Callback URL

The redirect URI is where the service will redirect after authorization or denial by the authorization server. Once the client is registered in the authorization server, the authorization server will provide the Client ID and Client secret to the client, and then the client will use this while requesting any resources for a user.

The client ID is the publicly exposed string that is used by the authorization server to identify the client application. The client secret must be kept private between the client and the authorization server and used to authenticate the client app when a client is requesting user resources.

Below workflow diagram of the authorization code grant type below is self-explanatory and demonstrates how an access token is generated from the authorization server and the same token is used to access protected resources.

Step 1. Calling Authorization endpoint by the client application.

The user is using the browser and visiting the client website and they click the login button to use the app. The client redirects the request to the Auth Server by calling the authorized endpoint to grant user access and request an authorization code.

response_type should be set as code while calling the authorized endpoint.

Method: POST
Content-Type: application/x-www-form-urlencoded
URL: https://your-authserver.com/authorize?
    response_type=code
    &client_id=<<Client_ID>>
    &redirect_uri=<https://clientapp.com/callback>>
    &scope=<<photo+offline_access>>
    &state=<<iX15fHJ415VMLClp>>

Here

• response_type=code: Indicates that your app expects to receive an authorization code.
• client_id: The Client identifier provided by Auth Server.
• redirect_uri: Indicates the URL to return after authorization is complete. This is nothing but a callback URL.
• Scope: A space-separated string indicating which parts of the user account you wish to access.
• State: A random string generated by your application, which you will verify later.

Step 2. User Authorize the client application

The Auth Server requests credentials from the user and asks him/her to approve consent. Sample login screen for your reference.

The user enters credentials and is granted consent. Sample consent screen for your reference.

Step 3. The client application receives an authorization code.

The Auth server redirects the request to the user agent to the application redirect URI, which was specified during client registration with an authorization code that's a one-time use time-limited code that goes back into the browser, the browser then delivers it back to the client application saying here's the temporary code. Now the application can use this code to get an access token.

https://clientapp.com/callback? 
state=iX15fHJ415VMLClp
&code=5HcrmpuvvY98gZQw_gq9MivXui97kTaaLPQvGnj3x4o9sOhk 

Verify state query parameters in the URL. It should match with the value stored in this user's session so that will protect against CSRF attacks.

Step 4. Exchange authorization code to retrieve access token

The application's web server will go and talk to the OAuth server again with this authorization code to get an access token along with client authentication details including client ID and client secrets and do a POST request to the token endpoint.

grant_type should be set as authorization_code while calling the token endpoint.

Method:POST
Content-Type:application/x-www.form-urlencoded
URL:https://your-authserver.com/token?
grant_type=authorization_code
&client_id=wP_wLcKoURU8U_dELDYuGzvE
&client_secret=nnlTJLSMCp2yiVM74HTgSHL4YTSvZJsSVi6KrFRfsGWOkJa0
&redirect_uri=<<CallabckURL>>
&code=5HcrmpuvvY98gZQw_gq9MivXui97kTaaLPQvGnj3x4o9sOhk

Here

• grant_type=authorization_code: Indicates request contains authorization code.
• client_id: The Client ID you receive when you first create an application.
• client_secret: The Client secret provided by the Auth server during registration.
• redirect_uri: This should match the redirect URI used in the original request.
• code: Include the authorization code which is retrieved in the authorized endpoint.

Step 5. The application receives an access token in response

Now client app receives an access token and using this token client makes API requests to the resource server on behalf of the user. The response includes the access token and refresh token.

{
  "token_type": "Bearer",
  "expires_in": 86400,
  "access_token": "QKY08tqDO8aeNebZbfgUFs1PH-cjerK2WBvE9FZpYGgZHnS_nLfhKYTECMBmPF_chz5GipOA",
  "scope": "photo offline_access",
  "refresh_token": "8V2dMpzRqB5cQDvoTb6X_Msl"
}

Workflow of Implicit Grant Type

This grant type is used for mobile apps and SPA web applications where the client's secret confidentiality is not guaranteed.

Using this grant type, instead of issuing the client an authorization code, the client issued an access token directly.

This is also a redirection-based flow but the access token is given to the user agent to forward to the client application, so it may be exposed to the user and other applications on the user’s device.

In addition, this type does not authenticate the identity of the client application and relies on the redirect URI to serve this purpose. That is why it is having security concerns as if access tokens are exposed to resource owners and can be misused.

Below workflow diagram of implicit grant type is self-explanatory and demonstrates how an access token is generated from the authorization server and the same token is used to access protected resources.

Step 1. Calling Authorization endpoint by the client application.

The user is using a browser and visiting the client's website and they click the login button to use the app. The client redirects the request to the Auth Server by calling the authorized endpoint to grant user access and request an authorization code.

response_type should be set as a token while calling the authorized endpoint.

Method:POST
Content-Type:application/x-www.form-urlencoded
URL:https://your-authserver.com/authorize?
response_type=token
&client_id=<Client_ID>
&redirect_uri=<<https://clientapp.com/callback>>
&scope=<<photo+offline_access>>
&state=iX15fHJ415VMLClp 

Step 2. User Authorize the client application

The Auth Server requests credentials from the user and asks him/her to approve consent.

Step 3. User-agent receives access token directly with redirect URI

User-agent directly receives the access token in the callback URL. Here, the client does not need to perform extra steps to call the token endpoint.

https://clientapp.com/callback?
state=iX15fHJ415VMLClp
&access_token=QKY08tqDO8aeNebZbfgUFs1PH-cjerK2WBvE9FZpYGgZHnS_nLfhKYTECMBmPF_chz5GipOA
&expire_in=3600
&token_type=abc

Workflow of Client Credentials Grant Type

This grant type is designed for client applications who are resource owners. E.g. Console application or Windows services.

The best use case would be machine-to-machine communication when the client and resource owner are the same entity and a separate user entity is not involved in this workflow.

The below workflow diagram of client credentials type is self-explanatory and demonstrates how an access token is generated from the authorization server and the same token is used to access protected resources.

Step 1.  Calling Token endpoint by client application

The client is directly calling the token endpoint to get an access token. grant_type should be set as client_credentials while calling the token endpoint.

Method: POST
Content-Type:application/x-www.form-urlencoded
URL: https://your-authserver.com/token?
grant_type=client_credentials
&client_id=<<CLIENT_ID>>
&client_secret=<<CLIENT_SECRET>>
&scope=<<abc>>

Step 2.  The client application receives an access token directly

A client receives an access token after the auth server validates the client request and then the client makes an API access request using this token.

{
  "token_type": "Bearer",
  "expires_in": 86400,
  "access_token": "QKY08tqDO8aeNebZbfgUFs1PH-cjerK2WBvE9FZpYGgZHnS_nLfhKYTECMBmPF_chz5GipOA",
  "state": "iX15fHJ415VMLClp"
}

Workflow of Resource Owner Password Credential Grant Type

Designed for legacy applications and should not be used frequently.

The user provides their credentials directly to the client app that uses the credentials to obtain an access token from the auth server.

This grant type should be enabled on the authorization server if other flows are not viable. It is only used when applications are trusted by the user.

The below workflow diagram of password grant type is self-explanatory and demonstrates how an access token is generated from the authorization server and the same token is used to access protected resources.

Step 1. Calling Token endpoint by client application

The client is directly calling the token endpoint to get an access token. grant_type should be set as a password while calling the token endpoint.

Method:POST
Content-Type:application/x-www.form-urlencoded
URL:https://your-authserver.com/token?
grant_type=password
&username=<<Username>>
&password=<<Password>>
&scope=<<offline_access>>

Step 2. The client application receives an access token directly

A client receives an access token after the auth server validates the client request and ten clients make API access requests using this token.

{
  "token_type": "Bearer",
  "expires_in": 86400,
  "access_token": "QKY08tqDO8aeNebZbfgUFs1PH-cjerK2WBvE9FZpYGgZHnS_nLfhKYTECMBmPF_chz5GipOA"
}

Conclusion

In this article, we saw how different types of authorization grants work internally with the client app, auth server, and resource server to generate access tokens and access protected resources in the OAuth2.0 framework. Hope you find this information useful! Happy Learning!

Copyright Anupam Maiti. All rights reserved. No part of this article, including text, may be reproduced, distributed, or transmitted in any form or by any means, including photocopying, recording, or other electronic or mechanical methods, without the prior written permission of the copyright owner.