OAuth2.0 for dummies — Access and Refresh Tokens

In the previous articles, we covered the basic OAuth2.0 flow and the methods of obtaining user authorization. In the 2nd article in this series, we discussed the different methods used in obtaining authorization from the user, i.e. the grant types and flows. We came forward in the OAuth2.0 flow up to the point where the client receives the access token and refresh token from the authorization server.

Now, we are going to discuss more about the two token types that we have in our hands, how they behave and how to handle them.

1. Access Token

After the client receives an authorization code (we’re referring to the authorization code grant for this scenario to explain better), it then makes a token request to the authorization server, through the token endpoint of the server. The token request contains the following parameters.

• grant_type (REQUIRED) — value must be set to the relevant grant type (eg: “authorization_code”)
• code (REQUIRED) — the authorization code received from the authorization server
• redirect_uri (REQUIRED if the ‘redirect_uri’ parameter was included in the authorization request) — this must be identical to the redirect_uri provided in the authorization request. This is the URI to which the authorization server sends the tokens.
• client_id (REQUIRED) — if the client is not authenticating with the authorization server in a different manner (further explained in the Section 3.2.1 in the specification)

Please note that the token request takes different formats according to the grant type. Here, we have used the format according to the authorization code grant type.

2. Successful Response

If the request was successful, the authorization server sends back an access token and optionally a refresh token as well. If the request is invalid or unsuccessful, then the authorization server responds with an error response.

A successful token response will have the following parameters in the HTTP request, with a 200 (OK) status code.

• access_token (REQUIRED) — the access token issued by the authorization server
• token_type (REQUIRED) — the type of token issued (will be explained later)
• expires_in (RECOMMENDED) — the lifetime of the access token, in seconds.
• refresh_token (OPTIONAL) — the refresh token (will be explained later)
• scope — OPTIONAL if it’s identical to the scope requested by the client. Otherwise REQUIRED.

These parameters are sent in the JSON format, in which the order of parameters is not important. These are included in the entity-body of HTTP response using “application/json” media type.

Example successful token response:

3. Error Response

If the request fails, a HTTP 400 status code is sent back with the following parameters.

• error (REQUIRED) — specifies what the error is. Includes one of the following.
• error_description (OPTIONAL) — it’s a human readable text description on the error
• error_uri (OPTIONAL) — a URI which points to a human-readable web page which describes the error

We’ll now dive deeper into what kinds of errors can happen in token requesting, and which conditions can cause them.

invalid_request

This can happen due to,

• Missing a required parameter
• Includes an unsupported parameter value
• Repeats a parameter
• Includes multiple credentials
• Utilizes more than one way to authenticate client
• Any other malformation

invalid_client

Client authentication failed (authorization server returns a HTTP 401 (Unauthorized) status code). This can happen due to,

• Unknown client
• No client authentication included
• Unsupported authentication method
• Other

invalid_grant

This can happen due to,

• Invalid authorization grant provided
• Invalid refresh token provided when trying to get a new token after the issued access token expired (can also be expired or revoked)
• The redirection URI of refresh token does not match with the URI in the authorization request
• The refresh token was issued to a different client

unauthorized_client

The client is not authorized to use the grant type.

unsupported_grant_type

The grant type is not supported by the authorization server.

invalid_scope

The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.

Example error response:

4. Access token types

The type of access token must be understood by the client, since it contains the information on how to utilize the access token to create a successful protected resource request.

Two example access token types are given below.

‘bearer’ token type

It simply includes the access token string in the request

‘mac’ (Message Authentication Code) token type

Issues a message authentication code together with the access token

5. Refresh Token

The authorization server issuing a refresh token along with the access token is optional. If it was issued, it can be used to obtain a new access token when the existing one expires. You of course must remember that along with the access token, an expiration time is also defined (expired_in). If you don’t, just look up! We just discussed this.

If a refresh token was issued, then the client can make a refresh request to the authorization server by including the following parameters.

• grant_type (REQUIRED) — this value must be set to “refresh_token”
• refresh_token (REQUIRED)
• scope (OPTIONAL)

The refresh token is a long lasting credential. Therefore to ensure security, if the client type is ‘confidential’, the client must authenticate with the authorization server. It should also be done if the client was issued client credentials, from the authorization server.

Example token refresh request.

If the refresh request is valid and authorized, the authorization server issues a new access token for the client. If the request verification failed or if it’s invalid, an error response is returned.

We must note that the authorization server may or may not issue a new refresh token, in the refresh response. If one was issued, the client must replace the old refresh token with the new one.

6. Access token refresh flow

The below diagram gives a high level idea of the token refresh flow.

A: Authorization grant flow (depends on the grant type)

B: The client receives an access token and a refresh token

C: The client makes a resource request by sending the access token

D: Client accesses protected resources

(Steps C and D can happen repeatedly)

E: Client presents the access token after it is expired

F: Client receives an invalid token error from authorization server

G: Client makes a refresh request by sending the refresh token

H: Client receives a new access token and optionally a new refresh token

(From here, it continues from step C)

References:

• OAuth2.0 Specification: https://www.rfc-editor.org/rfc/pdfrfc/rfc6749.txt.pdf
• OAuth2.0 for dummies — Introduction to OAuth2.0 : https://medium.com/@malshanranawella/oauth2-0-for-dummies-4292a5a0bcde
• OAuth2.0 for dummies — Obtaining Authorization from the User : https://medium.com/@malshanranawella/oauth2-0-for-dummies-obtaining-authorization-from-the-user-1925b76bd2c6