Introduction to OAuth

OAuth 2 is rapidly becoming a preferred authorization protocol, and is used by major service providers such as Google, Facebook and Github.

An excellent introduction to Oauth is in the article Introduction to OAuth (in plain English). by Ron Sobers

Valet Key for the Web

Many luxury cars come with a valet key. It is a special key you give the parking attendant and unlike your regular key, will only allow the car to be driven a short distance while blocking access to the trunk and the onboard cell phone.

Regardless of the restrictions the valet key imposes, the idea is very clever. You give someone limited access to your car with a special key, while using another key to unlock everything else.

As the web grows, more and more sites rely on distributed services and cloud computing:

The problem is, in order for these applications to access user data on other sites, they ask for usernames and passwords. Not only does this require exposing user passwords to someone else – often the same passwords used for online banking and other sites – it also provides these application unlimited access to do as they wish. They can do anything, including changing the passwords and lock users out.

OAuth provides a method for users (you) to grant third-party (parking attendant) access to their resources (your luxury car) without sharing their passwords (the key of your car). It also provides a way to grant limited access (in scope, duration, etc. the equivalent of not having access to the trunk or the onboard cell phone).

For example,

Instead, she authenticates directly with the photo sharing service which issues the printing service delegation-specific credentials.

In OAuth, the client requests access to resources controlled by the resource owner and hosted by the resource server, and is issued a different set of credentials than those of the resource owner.

Instead of using the resource owner's credentials to access protected resources, the client obtains an access token - a string denoting a specific scope, lifetime, and other access attributes.

Access tokens are issued to third-party clients by an authorization server with the approval of the resource owner.

The client uses the access token to access the protected resources hosted by the resource server.

  1. The OAuth 2.0 Authorization Framework proposed standard document

Roles in OAuth

OAuth defines four roles:

  1. resource owner

    An entity capable of granting access to a protected resource. When the resource owner is a person, it is referred to as an end-user.

  2. resource server

    The server hosting the protected resources, capable of accepting and responding to protected resource requests using access tokens.

  3. client

    An application making protected resource requests on behalf of the resource owner and with its authorization.

    The term " client" does not imply any particular implementation characteristics (e.g., whether the application executes on a server, a desktop, or other devices).

  4. authorization server

    The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization.

    From an application developer's point of view, a service's API fulfills both the resource and authorization server roles.

The authorization server may be the same server as the resource server or a separate entity. A single authorization server may issue access tokens accepted by multiple resource servers.

Abstract Flow

  1. The application requests authorization to access service resources from the user
  2. If the user authorized the request, the application receives an authorization grant
  3. The application requests an access token from the authorization server (API) by presenting authentication of its own identity, and the authorization grant
  4. If the application identity is authenticated and the authorization grant is valid, the authorization server (API) issues an access token to the application. Authorization is complete.
  5. The application requests the resource from the resource server (API) and presents the access token for authentication
  6. If the access token is valid, the resource server (API) serves the resource to the application
The actual flow of this process will differ depending on the authorization grant type in use, but this is the general idea.

Application Registration

Before using OAuth with your application, you must register your application with the service.

This is done through a registration form in the developer or API portion of the service's website, where you will provide the following information (and probably details about your application):

Application Name
Application Website
Redirect URI or Callback URL
The redirect URI is where the service will redirect the user after they authorize (or deny) your application, and therefore the part of your application that will handle authorization codes or access tokens.

Client ID and Client Secret

Once your application is registered, the service will issue client credentials in the form of a client identifier and a client secret.

  1. The Client ID is a publicly exposed string that is used by the service API to identify the application, and is also used to build authorization URLs that are presented to users.

  2. The Client Secret is used to authenticate the identity of the application to the service API when the application requests to access a user's account, and must be kept private between the application and the API.

Visit Google Developers Console

Authorization Grant

In the Abstract Protocol Flow above, the first four steps cover obtaining an authorization grant and access token.

The authorization grant type depends on the method used by the application to request authorization, and the grant types supported by the API.

OAuth 2 defines four grant types, each of which is useful in different cases:

OAuth 2.0 is a version of the protocol which introduces different flows for web, mobile, and desktop applications. It also has the notion of token expiration (similar to cookie expiration), requires SSL, and reduces the complexity for developers by no longer requiring signing.

Grant Type: Authorization Code

The authorization code grant type is the most commonly used because it is optimized for server-side applications, where source code is not publicly exposed, and Client Secret confidentiality can be maintained.

This is a redirection-based flow, which means that the application must be capable of interacting with the user-agent (i.e. the user's web browser) and receiving API authorization codes that are routed through the user-agent.

Now we will describe the authorization code flow:

  1. User Authorization Request

    1. The user is redirected to the service provider.

      This is the scary part. If the consumer were super-shady Evil Co. it could pop up a window that looked like the service provider but was really phishing for your username and password. Always be sure to verify that the URL you’re directed to is actually the service provider

    2. Authorization Code Link

      First, the user is given an authorization code link that looks like the following:
      Here is an explanation of the link components:

      • the API authorization endpoint
      • client_id=CLIENT_ID: the application's client ID (how the API identifies the application)
      • redirect_uri=CALLBACK_URL: where the service redirects the user-agent after an authorization code is granted
      • response_type=code: specifies that your application is requesting an authorization code grant
      • scope=read: specifies the level of access that the application is requesting

    3. User Authorizes Application

      When the user clicks the link, they must first log in to the service, to authenticate their identity (unless they are already logged in).

      Then they will be prompted by the service to authorize or deny the application access to their account.

      Here is an example authorize application prompt: This particular screenshot is of DigitalOcean's authorization screen, and we can see that Thedropletbook App is requesting authorization for read access to the account of

  2. Application Receives Authorization Code If the user clicks Authorize Application, the service redirects the user-agent to the application redirect URI, which was specified during the client registration, along with an authorization code.

    The redirect would look something like this (assuming the application is

  3. Application Requests Access Token The application requests an access token from the API, by passing the authorization code along with authentication details, including the client secret, to the API token endpoint.

    Here is an example POST request to DigitalOcean's token endpoint:

  4. Application Receives Access Token

    If the authorization is valid, the API will send a response containing the access token (and optionally, a refresh token) to the application.

    The entire response will look something like this:

     "info":{"name":"Mark E. Mark","email":""}
    Now the application is authorized! It may use the token to access the user's account via the service API, limited to the scope of access, until the token expires or is revoked.

    If a refresh token was issued, it may be used to request new access tokens if the original token has expired

Once the application has an access token, it may use the token to access the user's account via the API, limited to the scope of access, until the token expires or is revoked.

Here is an example of an API request, using curl. Note that it includes the access token:

curl -X POST -H "Authorization: Bearer ACCESS_TOKEN""$OBJECT"
Assuming the access token is valid, the API will process the request according to its API specifications.

If the access token is expired or otherwise invalid, the API will return an invalid_request error.


Casiano Rodriguez León 2015-01-07