How to use OAuth2 from the third-party providers

Authorization

The main purpose of the authorization using third-party service providers is to obtain access to their APIs for users of our application. At its most basic level, we can simplify registration and login processes. In more complex cases, we can, for example, change user data, or subscribe to his/her notifications and obtain them for use in our application.

To get started, you need to register the application on the provider’s side and get a client_id and client_secret. Additionally, you must specify redirect_uri — the URI to which the provider redirects the user after login. Ultimately, the problem is reduced to obtaining an access token that we can include in the authorization header.

Standard OAuth2 authentication consists of 3 steps:

1) Firstly, we redirect a user to the provider’s site, where he/she enters the data. As a result of this step we want to get the authorization code. As a rule, required request parameters are client_id, redirect_uri, response_type, scope, and an optional parameter is state. For clarity:

About these parameters:

client_id — client identifier, which we received during the registration of our application on the provider’s side.

response_type — for almost all providers the first value must be ‘code’, because we want to get the authorization code.

redirect_uri — redirecting path which leads to our service. It must match with the value specified during registration on the provider’s side.

scope — line which describes the permissions granted to our application.

state — line that will be returned unchanged as a redirect parameter. It can be used for verification and for storing additional data.

2) After authorization is successfully completed, the user will be redirected to our service with the following parameters:

The answer may contain other parameters (depending on the provider), but as a rule these 2 parameters are always present.

3) Now that we have the authorization code, we can send a request for an access token. Sample data input to receive access token:

About these parameters:

client_id — client identifier, which we received during the registration of our application on the provider’s side.

client_secret — secret of a client which we received during the registration of our application on the provider’s side.

grant_type — for almost all providers the first value must be ‘authorization_code’, because we want to get the authorization code which we received in step 2.

redirect_uri — redirecting path which leads to our service. It must match with the value specified during registration on the provider’s side.

code — authorization code which we received in step 2.

If the request was successful, we’ll obtain access token, which can be used for authorization requests.

That’s all. Finally, it is worth noting that query parameters may be slightly different depending on the provider (you should always look into the documentation before implementation). Nevertheless, basic OAuth2 authentication scheme is the same for all providers.

Limited Token Lifetime

It is very important that the access token has a lifetime and it differs significantly based on a provider. Some providers have perpetual tokens (such as Github), while others have a very short validity period (for example, for Gmail it is 1 hour). Most providers offer the ability to update the token and obtain a refresh token, while others leave only one option — to repeat the authorization process (e.g. Linkedin).

I‘d like to detail the process of updating the token and review the simplest algorithm of interaction with the providers that allow us to do this.

To update the token autonomously (without user intervention) the providers offer such options as offline_access. It is included during the first step of authorization so that a user sees that our service wants to get this type of access. A method of enabling this option also depends on the provider, but the two main ways to do that are either to add an additional field to the query, or by the expansion of the value of the parameter ‘scope’ during the first authorization step.
With offline_access included in the third step of authorisation, we will get one additional parameter — refresh_token. For clarity:

All we need is to keep these two values in our database including the last modification date and the validity of a token for the specific provider. For example, a simple MongoDB document will look like this:

Now, every time when we need to make authorization request to the API of a provider, we simply check that the time difference between the current time and the time of the last update does not exceed our value of expiration_time. If not, we make a request using our available token.

If the token validity period has expired, update it using refresh_token and save the new value in our database.