Introduction
Sometimes back, I wrote a blog on the concepts involved in OAuth 2.0. Now, it’s time dig a bit deeper. OAuth 2.0 is a flexible/open authorization framework. This article is a tutorial on OAuth 2.0 authorization code with refresh token flow. It actually covers both Authorization Code grant type and also Authorization Code with refresh token grant type. Just to note, both of these flows are almost similar. However, In the later one, there is a refresh token. Using this token, we can obtain a new access token in case the existing access token is expired.
OAuth2.0 provides several other methods (also referred as GRANT TYPES) for an OAuth client to get access to the protected resource. Followings are some of the popular grant types used today in various situations/scenarios –
- Authorization code grant flow (described here)
- Authorization code grant flow with refresh token (described here)
- Implicit Grant flow
- Resource Owner Password Grant flow
- Client credential flow
So, let’s get started!!
Stakeholders in the Authorization Process
- Resource Owner (user) – A user or an application who/which owns a protected resource on the Resource Server.
- Resource Server (service/API server) – It’s the server that hosts the protected resource. This data/resource is to be shared with the client/third party application.
- Client – The client or third party application requests access to the resources/data (owned by Resource Owner) stored in Resource Server
- Authorization Server – It issues access tokens to the Client after the resource owner successfully authenticates itself and provides all the necessary authorization.
Concepts
- Authorization Server exposes two end points –
- AUTHORIZATION end point – This is responsible for presenting Login UI to the user for signing in and obtaining the consent from the user for data access.
- TOKEN end point – This is used to exchange tokens between the client and the authorization server.
- Client Id – The client must have a unique id and is called Client Id
- Client Secret – The client must also have a client secret. This is used to prevent situations fraudulent request is sent.
- Authorization Code – This is a short lived token that is used to obtain access token and refresh token.
- Access Token – This is the token that is used while obtaining the data from restricted resource. This has medium lifetime; may expire in an hour’s time.
- Refresh Token – This is the long-lived token that is also obtained in exchange for a valid Authorization Code. This is used to get a new Access Token when the current one expires.
Where to use OAuth 2.0 Authorization Code Flow?
As you noticed the client needs to store the Access Token and Refresh token. There are very confidential and must be kept in secret. This is the reason Authorization Code grant type is suitable for OAuth clients that can keep the tokens confidential. These are the clients that are generally deployed in secure server.
One possible example might be when one links his/her Facebook or LinkedIn account with Twitter. In such cases the user goes to the settings (or relevant) pages of Facebook/LinkedIn and chooses to link twitter. Then the twitter login page pops up; user provides the twitter credential and upon successful login the accounts get linked.
Sequence Diagram
oauth-authorization-code-with-refresh-tken-grant-type
Flow Description
STEP 1
- If you look at the above sequence diagram, the flow starts with when Resource Owner/User instructs the Client to access the its protected resource in the Resource Server. This is the point OAuth process kicks in.
STEP 2
- Upon getting the user instruction to access a protected resource, the Client sends a request to the AUTHORIZATION end point of with following parameters –
- client_id – As already described above, this is the unique identification number of the client.
- redirect_uri – This is the URL where the AUTHORIZATION server will send the response back with an authorization-code (if successful).
- state – Client sends a request to AUTHORIZATION end-point with certain value in this parameter. When the AUTHORIZATION server sends a response back to redirect_uri, it sends back the value of state parameter unchanged. Then the Client checks this value to ensure that if it’s indeed the call back for the same request it sent to the AUTHORIZATION server.
- scope – For which the Client is requesting authorization. These are space delimited list of scope string; for example – profile, email, location etc.
- response_type – It’s defaulted to code. This denotes that the request is for obtaining the Authorization Code.
STEP 3
- The AUTH end point verifies the client_id in the request with the stored client_id.
- It may also optionally validate based on the redirect_uri
STEP 4
- Thereafter, open the sign-in webpage/dialog and also mention what all information (scope) will be accessed by the Client.
STEP 5
- User or the Resource Owner provides credential and also provides the consent that the Client can access the the list of scope.
STEP 6
- If the provided credential is correct, user is signed in and consents are recorded.
- If the user the does not provide the consent, the entire process halts.
STEP 7
- After successful signing in and record of user consent, AUTH server generates authorization code.
STEP 8
- Redirect the user’s browser to the URL specified in redirect_uri (in STEP 2). AUTH server also passes the state parameter without change along with the authorization code.
STEP 9
- Client will compare the value of state to ensure that it’s the same value that was sent in STEP 2. This is to avoid any CSRF attack.
STEP 10
- Then the Client exchanges the short-lived authorization code with the access token. In order to do that the Client invokes the TOKEN end point with following information –
- client_id – A unique string identifying the client
- client_secret – A secret string for the client
- grant_type – it can be something like authorization_code
- code – This is the authorization code obtained in earlier step
STEP 11
- AUTH server sends back the access token and refresh token (refresh token optional in case of Authorization Code Flow Grant; however, it must be sent for the refresh token grant type)
STEP 12 & 13
- Client then uses the access token to hit the protected resource URL and accesses the protected data.
STEP 14 & 15
- In case the access token expires, the Client invokes the TOKEN end point once again; however with the grant_type value something like refresh_token.
- AUTH server validates the refresh token and reverts back with a renewed access token for further use.
Conclusion
Please let me know if you have any further question on the explanation so far. Following are some of the references that I have used for my own learning process.
 flow){kind=link}
 flow){kind=link}