A Tutorial on OAuth, Part 4: Authorization Process

In the overview we stated there are three parts to OAuth: setup, authorization process, and API calls. There are five ordered events that make up these parts. Here we will look at the three events that make up the authorization process: request token request, user authorization, and access token request.

As a preface to this section I will note again that this tutorial focuses on general theory, not specifics. In other words, this tutorial will help you understand, for example, what is involved in making a request token request, but will not show how to make them.

URL Endpoints

As stated, redirection-based authorization is the typical way the OAuth authorization process is implemented. It involves transferring data between URL endpoints using redirects or XHR calls depending on what endpoint is being contacted. Unofficially, there are two kinds of endpoints: redirect and XHR. Redirect endpoints send data through URL parameters (the GET method) which will include the callback endpoint and the response will be a redirect to that callback endpoint with data sent through URL parameters. Redirect endpoints are typically communicated to through redirecting the parent window in a web browser, popups, or the like.

XHR endpoints will be sent data through HTTP headers or the POST and GET methods with a response given in the HTTP header or in the body in XML or JSON format. That said, do note that this is a typical situation; each service provider may have variations of this such as using other methods like PUT or by returning a response format other than XML or JSON. Though this may be obvious, XHR endpoints are typically communicated to via AJAX, cURL, or the like.

There are four URL endpoints involved in the OAuth process:

  1. Request Token Endpoint
  2. User Authorization Endpoint
  3. Callback Endpoint
  4. Access Token Endpoint

Note: the title text includes the variant names of the above endpoints.

Requests and Responses

The event of sending data to an endpoint is called a request. The key-value pairs sent in a request are called send parameters. All XHR endpoints in the authorization process require the send parameters to be signed. Forming signed requests is the part where developers being to rip their hair out. That said, we will stick to generalities. Suffice it to say that a signed request includes a signature parameter which is composed by applying a signature method to a base string.

The event of receiving data from an endpoint is called a response. The key-value pairs received in a response are called response parameters. Response data is typically sent through GET or POST, HTTP headers, or the response body in JSON or XML format.

2. Request Token Request

Alright, now to the actual authorization process. The request token request is the first event in the authorization process and the second in the overall OAuth process. The request token request obtains request tokens. The request tokens are used to identify the authorization process through the next two events. Typically, this event involves using AJAX or cURL to make an XHR call to the request token endpoint.

Send Parameters:

  • oauth_callback (callback endpoint)
  • oauth_consumer_key
  • oauth_token (an empty string)
  • oauth_signature_method
  • oauth_timestamp
  • oauth_nonce
  • oauth_version
  • oauth_signature

Response Parameters:

  • oauth_token (request token)
  • oauth_token_secret (request token secret)
  • oauth_callback_confirmed

Note: the oauth_secret for HMAC-SHA1 signature method will be an empty string

3. User Authorization

User (resource owner) authorization involves the user authenticating to the resource provider and either approving or denying the consumer’s request to access the user’s protected resources. This event isn’t the most tricky, but can be the most confusing. This event is what makes most people stray into thinking that OAuth handles authentication instead of authorization. All this event does is ask the user to approve the consumer’s request to access that user’s protected resources. In other words, this is the event where you see the Facebook or Twitter “allow” box and the list of permissions requested by the application, say Flickr.

This event will involve the user’s browser being redirected to the service provider (Twitter, for instance) or a popup. For a mobile device, this will be a webview. We won’t go into it here, but it is worth mentioning, that this is also where the Out Of Band (OOB) method differs. Instead of the browser or popup redirecting back to the application a PIN is shown that the user has to manually enter.

Send Parameters:

  • oauth_token (request token)

Response Parameters:

  • oauth_token (the same request token as earlier)
  • oauth_verifier

Note: this request is not signed

4. Access Token Request

The access token request obtains access tokens. The access tokens are used in the event after this: making API calls (resource requests). Typically, this event involves using AJAX or cURL to make an XHR call to the request token endpoint. This is the last step of the authorization process. Once the access tokens are obtained the consumer can begin making API calls (resource requests).

Send Parameters:

  • oauth_verifier (obtained in previous event)
  • oauth_consumer_key
  • oauth_token (request token)
  • oauth_signature_method
  • oauth_timestamp
  • oauth_nonce
  • oauth_version
  • oauth_signature

Response Parameters:

  • oauth_token (access token)
  • oauth_token_secret (access token secret)

Note: the oauth_secret for HMAC-SHA1 signature method will be the request token secret

There is a lot of information to pack into the authorization process, but the point is to give a general view of what is involved so that when you begin to look at the specifics you understand what it’s doing in the larger picture. Different service providers will implement the authorization process differently, but these are the basics. The next step after the authorization process is to make API calls, which we will get to next time.

By Joe Purcell

Joe Purcell is a technology virtuoso, cyberspace frontiersman, and connoisseur of Linux, Mac, and Windows alike.

Leave a comment