OAuth 2.0 is an evolution of the original OAuth protocol that focuses on a streamline authorisation flow for web, desktop and phone applications.

If you keep up with my articles, I've been working on an STV Election system that's capable of working and submitting ballots on an election from an iPhone/iPad using the API on the server (which is powered by PHP) to authenticate access and validate a ballot (so only users can submit one). 

If you've not used OAuth before and you're new to the protocol and how it works, it can be quite a headache. However, once you've mastered it once it is the same for all future applications you need to use it (which always helps) and the flow is the same on all sites such as Facebook, Google, Twitter, etc.

To start, you may need to implement OAuth to act as a server (dealing with authorisation through your app and distributing access tokens). Here are a few good PHP bundles to get you started:

All of these are great and get the job done you, but we all have our preferences and so, my favourite is the OAuth 2.0 PHP library that is hosted on Google Code and has updates for revision OAuth 2.0 draft #10. This is mine just because I worked with it back in 2010 in older revisions so I didn't need much additional work to get running with the latest version.

You'll need to implement the endpoints:

  • Authorization Endpoint - the location where the resource owner logins, and grants authorization to the application e.g. /oauth/authorize
  • Token Endpoint - the location where the client exchanges authorization codes, client ID and secret key to retrieve an access token e.g. /oauth/token

Getting an Access Token

The process involves two stages; firstly, authorize the client with the application and then secondly, use the authorization code to get an access token and a refresh token.

Authorization Request

Send the user to the authorization URL with the following GET parameters:

  • client_id, required - your API client ID
  • response_type, required and must be set to code
  • redirect_uri, optional - your API client redirect URI (if provided, it must match against what is stored)
  • scope, optional - a possible scope for the request (specific permissions, etc.)
  • state, optional - any client state that needs to be passed on to the client request URI

For my STV application this would be:

Authorization Response

Once you've authorized the application (which may require the user to login) you'll be redirected to your URL which might resemble something similar too:

Token Request

Now we can extract the authorization code (in PHP, this is simply stored in $_GET['code']) and use this to send a new request to get an access token. For my API this must be sent as POST to the URI:


With the following parameters:

  • grant_type, required - must be set to authorization_code
  • code, required - the authorization code received from our authorization server
  • redirect_uri, required if the request URI was included in the authorization request. They must be identical in this case.
Token Response

Now you'll receive the following response:

    "access_token"  : "...",
    "expires_in"    : "...",
    "refresh_token" : "..."

You'll need to keep track of the access_token and refresh_token. You'll need the access_token appended to the URL requests and, if it has expired, the refresh_token to renew and get a new access_token without having to re-authorize.

Refreshing an Access Token

With OAuth 2.0, access tokens are typically short-lived and once they're expired you'll need to use your refresh token to get a new access token (missing the authorization procedure). To do this, you send another request to the token endpoint (POST on my API) with the following parameters:

  • grant_type, required - set to refresh_token
  • client_id, required - the API client ID
  • client_secret, required - the API client secret key
  • refresh_token, required - the refresh token that was issued along with the access token

If all goes successfully, you'll receive a new access token, expiry value and a new refresh token. Your old access and refresh tokens are now both invalid and you can only use the refresh token once.

Possible Grant Types

The grant_type parameter can be used to get a different variety of responses:

  • client_credentials, used when you want to create an account (e.g. a new user). A request to this endpoint will return a client access token and no refresh token as the client can obtain a new access token at any time. This type of endpoint will return an authorization code that we can use to get an access token.
  • authorization_code, used to get an access token (the flow discussed above).
  • refresh_token, used to fetch a new access token when your current access token has expired. Typically, you may store the time of expiry and use this to determine if you need a new token, or, handle any authentication errors returned and then issue a refresh request.

Have you used OAuth 2.0? What's your favourite framework? Let me know by mentioning #ALJTMedia on Twitter or leave a comment on our Facebook or Google+ page.

Other Resources

Make your Instagram beautiful. Preview your images before you post them ›