For this example, I am assuming We have a restaurant website (IndianSpice.com) and we want to allow users to log into it using oauth service (Google, Facebook etc.) We need to follow these steps.

1. Register our app IndianSpice with Oauth Provider.

2. open consent window from indianSpice.com

3. handle code from oauth Provider and get tokens

4. make api calls using valid access tokens.

Registering app

This includes going to the developer's section of oauth Provider and creating a new app . They would ask for some of the details from this list -

name, [company logo], [purpose], email, redirect url, [terms of use link], [privacy policy link ], [address], [mobile number].

It could also ask for some more details. Some of the above details will be optional. It will vary from oauth provider to oauth provider.

The redirect url corresponds to an endpoint on our server that will handle code. More on this later.

once the app is registered, a client Id and client secret will be generated for the app.

you have to get your app approved by oauth provider before using in production but it is ok for developement.

Open Consent Window

At our server, we will have to create an endpoint that generates the authorization url. This will url will be similar to

http://oauthProvider.com/{auth}?clientId={OUR_CLIENT_ID}&redirecturl={OUR_REDIRECT_URL}&scopes={readScope%20writeScope}

here scopes are the permission that we are requesting on behalf of our user. These permissions will show up in the consent window. and redirect url is the url of our server that we registered in the previous step.

Once the user clicks on login with the Oauth Provider button we will make a GET request to our server localhost:3000/create-auth-url . And on the server side, we will generate the auth url and send a redirect response to open this auth url in the browser.

we will need to check the docs of the OAuth Provider for the exact format of the auth url.

On this auth url if the user will accept the permission and provide his consent. After that the OAuth Provider will make a GET request to our redirectUrl by redirecting the browser from oauth Provider page to the redirectUrl .

handle the code

the request from the previous step to the redirecturl after user consent will contain a special query parameter with key name code it will be like

GET localhost:3000/handle-code?code={some_long_string} .

We can use this code and exchange it for tokens by making a request to the OAuth Provider's token endpoint. It will be like

POST http://oauthProvider.com/token
{
    "code":"<CODE_RECIEVED>"
    "clientId":"OUR_CLIENT_ID"
    "clientSecret": "OUR_CLIENT_SECRET"
    "redirectUrl":"OUR_REDIRECT_URL"
    "grantType": "authorization_code"
}

And in response, we will receive 2 tokens

{
    "accessToken": "some_token_string",
    "refreshToken":"some_token_string" 
}

we need to save refreshToken in some persistent storage (our DB) at the very least.

Making the api calls

To Authorize our requests to OAuth provider we add accessToken in the Authorization header with every request. But there is one caveat, the accessTokens will expire most likely after 1 hour. we start getting 403 Access Denied response status in our requests.

If the the accessToken has expired we can request a new accessToken using the refreshToken from the database. The refresh tokens are long-lived and generally do not expire. This request would look like

POST http://oauthProvider.com/token
{
    "clientId":"OUR_CLIENT_ID"
    "clientSecret": "OUR_CLIENT_SECRET"
    "redirectUrl":"OUR_REDIRECT_URL"
    "grantType": "refresh_token"
}

The response would have a new access token which will be valid for another hour.

{
    "accessToken":"new access token"
}

Now we can perform our requests to the OauthProvider again Hurrah!

Caveats

• All this information is a simplified example and you have to check the documentation for the OAuth provider that you are trying to integrate.

• you might have to create separate apps for development, qa servers and production servers.

• some oauth Providers may not allow using http redirect urls and require https redirect urls . It may become a problem for local developement. you can use a tunneling solution like ng-rok or localtunnel for creating a temporary https endpoint.

• getting the app approved may take around a week and you may have your app rejected a few times before it gets approved.

• there are often libraries for oauth providers and they can save you some time so do check them out.

• here the user may also deny permission on consent window so that has to be handled also.

• Expiring Refresh Tokens: For some OauthProviders the refresh tokens also expire after an expiry time. Ex- Instagram. Also the refresh tokens can be revoked or there can be a limit on active refresh tokens causing the older ones to expire.

• Rotating Refresh Tokens: Some Oauth Provider will provide a new refresh token with each request so do check that and update the DB. ex- Microsoft

• on refresh token expire the user has to re-authenticate. So that has to be handled gracefully.

• Content Type: accepted by the requests could be different from json also. Some accept x url form ecoded. check the oauth Provider docs.

• Oauth Provider may not provide a refresh token in such cases access token does not expire.

• offline scope: some providers require you to add a offline scope to get refresh token in response.