OAuth2 – Authorization Code Grant

OAuth2 has become the de facto in modern web application security.  If you are a front end, back end or mobile developer, chances are you have had to consume or secure  protected resources with OAuth2. As such, having a good understanding of OAuth2 is invaluable. When implementing or using OAuth2 in your application, you typically face with four different grant types. Knowing the differences between the four grant types and which one to use can be quiet confusing. In this blog post series, I go over the different grant types by providing examples. This post is part of the series about OAuth2. In this post,  I’ll cover the Authorization Code Grant and when it is appropriate to use it.

If you are not familiar with the jargons, this post may help.

Authorization Code Grant

• Let’s look at a scenario where you are developing an application which needs to interact with Facebook and retrieve a user’s friends list.

With the authorization code grant, the flow looks something like this:

1. The user selects the option to log in to Facebook.
2. Your app redirects the user’s browser to Facebook authorization server, passing in the app’s client id as it is required for Facebook to identify your application. Your app also passes in scope in which it specify it needs access to the user’s friend list.
3. The user authenticates with the user’s Facebook credentials.
4. If the user’s has not provide consent for your app to access the user’s Facebook data, Facebook presents the user the permissions your app requires. The user must agree for the flow to continue. Otherwise, the user can cancel the operation.
5. Once the user has authenticated and gave permissions to your app, Facebook returns the authorization code to your application.
6. The application redirects the user’s browser to another url to request an access token. The request includes the authorization code as well as the application’s client id and secret. The client id is to verify that the client is indeed the one which requested the authorization code which the user has authorized, and the secret further ensure the client is authentic. This is to prevent a fake request that could happen if a bad guy somehow has compromised the authorization code and also know the id of the application that requested the authorization code.
7. Facebook issues an access token and sends back to the application via redirect endpoint.
8. The user’s browser requests protected resource with the access token.

When your application redirects the user to the authorization endpoint to obtain authorization code, typically you provide an optional state parameter to protect against CSRF – Cross side request forgery. A cross side request forgery is basically a type of attack which an attacker treats the user into providing sensitive information to a server which contain the attacker’s resource. For instance, an attacker can send a request to the application’s redirect endpoint with an authorization or access token code along with a malicious url to treat the user into accessing that url with the attacker’s access token. That url may be a form where the user enters credentials which then get saved on the server which the attacker has access to.

To protect against this type of attack, your application should ensure to validate the redirection endpoint and check for the state parameter. It should match with the value in the user’s agent cookie. The application should send the state value when making a request to the authorization server and validate that it gets the same value back when the authentication server redirects the browser back to the redirection url and include the authorization code.

When should I use the Authorization Code Grant?

The Authorization Code Grant provides certain security benefits:

• The resource owner does not need to share the credentials with a third party application. In the example, the user only authenticates against Facebook. The application does not know the user’s credentials. However, it only needs the access token as a proof that the user has authenticated and authorized the app to access certain resources pertaining to the user.
• Passing of the access token is more secure. In the above example, the application makes a separate call to Facebook to obtain an access token. Facebook returns the access token straight back to the client, without exposing it in the URL, thus limiting the exposure. For comparison, the implicit grant type, which we’ll go over in more details in another post, does return the access token via the redirection uri; as such, the access token may be exposed to the resource owner or anyone who has access to the resource owner user-agent.

You should consider the Authorization Code Grant if you are developing a backend API or mobile application which has the capability to keep the access token safe. For comparison, the Authorization Code Grant would not be ideal for a front-end application which uses javascript as the application cannot keep the access token hidden from the resource owner anyways. Front-end application could benefit from using the Implicit Grant which provides better performance as there is no extra request to obtain the access token.

References:

https://tools.ietf.org/html/rfc6749#section-1.3.1