OAuth 2 - Easy Tutorial

Why and when do you need Oauth 2?

OAuth 2 is a protocol that enables apps to act on behalf of users. There are many potential use cases for this. Maybe you want to build an app that lets a person know how many facebook likes they've got over their lifetime. But how does facebook know that your app can get a user's data? That's where OAuth 2 comes into play.

OAuth 2 is the successor of OAuth 1. It's not backwards compatible and should be seen as a completely new protocol.

This purpose of this schematic is to illustrate the general purpose of OAuth 2 and not the entire process. I think the entire process is a bit easier and clearer just to describe in words, as will be done in the sections below.

OAuth 2 Roles

So as you could see from the introduction, there are (at least) three parties involved in the process:

• The user - also referred as "Resource Owner". This is typically a human who has an account for a certain service, let's stick with the example of facebook.
• facebook itself is the Resource Server, but also the Authorization Server. facebook will provide authorization to the user or to app and once authorization is granted, they will send the resource. We'll also call it service provider here.
• Then we have the third party app, because of which we're doing the whole OAuth 2 stuff in the first place. This is referred to as the Client. We'll also call it third party app here.

Registration of the Third Party App

First, in order for all of this to work, the third party app must be registered with the service provider. In particular, the third party app must provide a redirect URL, where the service provider should redirect the user to after a successful authorization.

If the service provider accepts the third party apps registration, it will provide it with a Client ID and a Client Secret. The Client ID is a public string that is used by the service provider to identify the client. The Client Secret lets the service provider verify that a client is really who it says it is.

Let's stick with our example of an application that reads the number of facebook likes from a user. We'll call it "likey". Then a likey-employee goes to facebook.com and signs up likey for OAuth 2 at facebook. If the form is accepted, the employee receives the client-id: likey-app and client-secret: 84HAu1jdjjfXuquq.

OAuth 2 Authorization (Grant Type: Authorization Code)

So now, how does facebook know that our third party app can access the data of "hans@gmail.com"? Hans somehow needs to tell facebook "hey guys, it's ok that <insert application name here> accesses (parts of) my data."

facebook can grant access to likey in different ways, but the most common is the Grant Type: Authorization Code. This grant type is suited for third party applications, that have web servers themselves. That way, the client secret can be used as an additional security measure to prevent attackers from retrieving a user's data, even if they manage to get an authorization code.

Now, what's the series of events that need to happen here such that likey gains access to the users facebook data?

Step 1: Authorization Code Link

The user visits the likey page. likey has placed a link on their page that points to the facebook oauth endpoint that looks something like:

https://api.facebook.com/oauth-2/authorize?response_type=code&client_id=likey-app&redirect_uri=CALLBACK_URL&scope=read_likes

As you can see, the user is directed away from the likey page to the facebook page. But the link also contains the information where the user should be redirected after a successful authentication in the redirect_uri parameter. The scope request parameter declares for which part of the service provider access is asked for. For example, you might want to grant likey access to how many likes you have on posts, but it shouldn't be allowed to view your friends or to write posts on your behalf.

Step 2: User Authorizes Application

Once the user clicks the link, he or she is leaving likey (for the moment) on being routed to the facebook page. What happens there, stays between the user and facebook. This is important, because the user doesn't want to share his or her facebook password with likey. facebook then asks the user (once he or she is authenticated / logged in) if he or she wants to grant access to the third party app for a certain scope (for example: read likes). The user can then accept or deny this.

Step 3: Application Receives Authorization Code

If the user clicks on "Authorize", the service provider (facebook) redirects the user back to the third party app (likey). In the redirect url, facebook will also put the Authorization Code:

https://www.likey.com/oauth-callback?code=AUTHORIZATION_CODE

Step 4: Application Requests Access Token

Now that likey has the Authorization Code, it uses that code to get an Access Token. To do so, it sends a POST request to an endpoint provided by facebook, which could look like this:

https://api.facebook.com/oauth-2/token?client_id=likey-app&client_secret=CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=CALLBACK_URL

Again there are client_id and redirect_uri redirect parameters. Additionally, the client_secret is provided.

The secret is an additional security layer, such that an attacker that managed to snatch an authorization code somehow still cannot retrieve a user's data without also knowing the client secret.

Step 5: Application Receives Access Token

If everything matches, facebook sends back an access token. That response might look like this:

{
   "access_token": "XYZ",
   "token_type": "bearer",
   "expires_in": 2592000,
   "scope": "read_likes",
   "uid": 55
}

This access token is meant to be kept secret between likey and facebook.

Step 6: Application Uses Access Token

Now likey can send a request to facebook like this:

POST to

api.facebook.com/get-likes

// body
{uid: 55}

// HTTP Headers
Authorization: 'bearer XYZ'
    

This allows likey to finally retrieve the user data!

Summary

OAuth2 lets third party applications access user data. There are different authorization procedures, of which we have discussed "Grant Type: Authorization Code". This procedure involves two layers of security: First, the user must authenticate at the service provider and tell him "hey, it's okay that this app accesses that part of my data". If the user authorizes the third party app, then the service provider issues an authorization code. Second, the third party app must trade that authorization code together with the client secret for an access token. Only now, with this access token (that stays between app and service), the app can act on behalf of the user.