Understanding OAuth2 Authorization Code Grant Type

In a previous tutorial we had seen how OAuth has evolved to authorize websites/apps like Yelp to access protected resources like our email contacts without sharing of passwords.
For this Authorization Code Grant Type is used by web and mobile apps. In this tutorial we will be looking at the Authorization Code Grant Type to understand its working and and the associated terminology.

Understanding the Authorization Code Grant Type Flow

Suppose we want to signup on stackoverflow. In order to signup stackoverflow, we need to provide it the user information like your name,email id etc. to stackoverflow. We already have this information with gmail and we can now sign up using Gmail Account. This is done using Authorization Code grant type. When making use of this grant type , the client i.e web and mobile app launch a browser to begin the flow.
As we had seen in the first chapter of this series that without OAuth2 we would have needed to share our Gmail credentials with stackoverflow so that it could access this information. Now this is password antipattern and not a good way.
So here we authorize stackoverflow to access the user information from gmail using Authorization Code Grant.

Different actors involved

• Resource Owner i.e User. The person who wants to sign up for stackoverflow. He will be sharing his personal details with stackoverflow by using google sign up
• Client application i.e Stackoverflow. The client application making protected requests on behalf of the resource owner and with its authorization
• Authorization Server i.e Google Authorization Server. The server issuing access tokens to the client application after successfully authenticating the Resource Owner and obtaining authorization
• Resource Server i.e Gmail. The server hosting the protected resources, and which is capable of accepting and responding to protected resource requests using access tokens. In our case the protected resource is the user information that gmail has.

In case of authorization code grant the client should already be registered with the Authorization Server.
In our case stackoverflow is already registered with the Google Authorization Server. On registration with the Authentication Server it provides the client application with a Client Id and the Client Secret.

The Client Id and the Client Secret are used during Authorization Code Grant. As the name suggests the client secret should never be shared and kept secret.
Let us now look at how OAuth2 Authorization Code Grant is used when user signs up for stackoverflow using Gmail.

1. User clicks on sign up using gmail
2. Stackoverflow sends a request to google authorization server with following parameters -
   • client_id=717762328687-iludtf96g1hinl76e4lc1b9a82g457nn.apps.googleusercontent.com - The public identifier for the application, obtained when stackoverflow first registered itself with google
   • scope=profile,email -One or more space-separated strings indicating which permissions the application is requesting. The specific OAuth API you are using will define the scopes that it supports. Here the scope mentioned by stackoverflow is profile and email. If we look at the OAuth 2.0 Scopes for Google APIs it is mentioned that stackoverflow wants the users basic profile and the email address. Basic profile involves information like ID, Full name, Given Name, Family Name.
   • redirect_uri=https%3A%2F%2Fstackauth.com%2Fauth%2Foauth2%2Fgoogle - Tells the authorization server where to send the user back to after they approve the request
   • state=%7B%22sid%2lc1b9a82g457nn.apps.googleusercontent.com - The application generates a random string and includes it in the request. It should then check that the same value is returned after the user authorizes the app. This is used to prevent CSRF attacks.
   • response_type=code - This tells the authorization server that the application is initiating the authorization code flow.
3. The google authorization provides user login page.
4. User logs in with google credentials
5. The google authorization server after authenticating the credentials redirects to the redirect uri provided by stackoverflow and also provides the authorization code.
6. Stackoverflow on receiving the authorization code on the redirect uri, makes a post call to the authorization server with following parameters -
   • grant_type=authorization_code - This tells the token endpoint that the application is using the Authorization Code grant type.
   • code - The application includes the authorization code it was given in the redirect.
   • redirect_uri - The same redirect URI that was used when requesting the code. Some APIs do not require this parameter, so you will need to double check the documentation of the particular API you are accessing.
   • client_id - The application's client ID.
   • client_secret - The application's client secret. This ensures that the request to get the access token is made only from the application, and not from a potential attacker that may have intercepted the authorization code.
7. Google Authorization Server provides the access token to stackoverflow
8. Using the received access token stackoverflow makes a call to the resource server to get the authorized user information.
9. The resource server will validate the access token with the authorization server. On successful authorization it will share the authorized user details with stackoverflow
10. User is successfully signed up with stackoverflow