OAuth 2.0 Webapp Flow Overview

In my last few blogs I’ve been talking about accessing Software as a Service (SaaS) providers such as Facebook and Twitter using Spring Social. Some of you may have noticed that my sample code may have been a bit thin on the ground as I’ve being trying to describe what’s going on in the background and what Spring Social is doing for you.

So far I taken a bird’s eye view of OAuth defining it as the need for your application to get hold of an Access Token so that it can access your user’s private data from an SaaS provider without the need for your users to give your app their credentials. I’m concentrating on OAuth 2.0 and I’ve also hinted that before it can request an Access Token your app needs something called an Authorization Code, which it combines with its app secret.

This blog zooms in some more and hopefully explains what going on - at least in the case of OAuth 2.0.

One thing to remember about OAuth 2.0 is that there are six different flows covering different client scenarios such as the User-Agent flow and the Device Flow. This description covers the Web Server Flow for OAuth clients that are part of a web server application.

OAuth Steps in Summary

In summary, in the Web Server Flow, the following high level steps take place:

1. The user logs into their SaaS provider
2. Your application is sent an Authorisation Code
3. Your application uses the Authorisation Code to retrieve an Access Token
4. The Access Token is used to retrieve the user’s private data

For some, such a high level overview will suffice but, if you’re like me, then you’ll want to understand some of the nitty-gritty of what’s going on.

Obtaining an OAuth 2.0 authorisation token if often referred to as the ‘OAuth Dance’ and in this dance there are three dancers or actors:

OAuth Actors

Actor	Description
User	The user’s browser as controlled by a human user
TheApp	The webapp that wants to access the user’s SaaS Data
SaaS App	The Software as a Service provider such as Facebook

The OAuth Dance

The table below describes the OAuth 2.0 dance in detail...

Actor	Description	Data
User	Navigates to TheApp in browser. TheApp in loading a page needs to ask for SaaS data
TheApp	TheApp has no AccessToken for this User on this SaaS provider and can't return the SaaS data. It returns enough information to the User to allow him/her to request one.	authorize_url (The URL of the SaaS OAuth service) redirect_uri client_id (app key) response_type: code
User	The User contacts the SaaS provider asking for an Access Token	Does a GET to the SaaS authorize_url passing the following params: client_id: (app key) redirect_url: response_type: code
SaaS	Responds with the User’s login page on the SaaS webapp
User	Types in their Username and Password on the SaaS site and presses okay.	POSTs back SaaS login details such as user name and password
SaaS	The SaaS provider asks user to confirm that TheApp can access their data. It usually does this by presenting a small screen that asks something like: “Do you want TheApp to access your SaaS data?	This is REST so the following are carried through in hidden fields: client_id: (app key) redirect_url: response_type: code
User	Confirms the above to the SaaS	client_id: (app key) redirect_url: response_type: code authorize=1 (or YES)
SaaS	The SaaS provider does not immediately create Access Token, instead it creates an authorization code and stores it for later before passing it back to the User. The Access Token can then be requested and generated using this code. The SaaS provider passes the code to the User as part of an HTTP redirect (Status codes 3xx).	The redirect is to TheApp’s redirect_url and contains: code: (The authorisation code) expires_in: (expiry time)
User	Does a redirect using the URL from the last step back to TheApp with a GET request	code: (The authorisation code) expires_in: (expiry time)
TheApp	TheApp then calls SaaS provider using a POST to retrieve the Access Token	client_id (The App Id/Key) client_secret code (The App secret code) redirect_url grant_type: authorisation-code
SaaS	The SaaS provider recognises the authorisation code and creates an Access Token. It also revokes the authorisation code.	Returns the Access Token to TheApp access_token (The prized Access Token) expires_in (expiry time) refresh_token
TheApp	TheApp tells the user that the OAuth process has worked.
TheApp	TheApp can now access the User’s SaaS data using a GET request.	Passes Access Token as HTTP authorization header (or request param) For example: https://graph.facebook.com/me/friends?access_token=AAAAAAITEghMWiBBlEC5OG... etc ...eAVbjNnWjIlE
User	The user now sees their SaaS data as displayed by TheApp in their browser

In the table above I've included many of the data parameters that are carried through from request to request, even though they aren't always needed at that point in the sequence. The thing to remember here is that for very practical reason a SaaS provider is a REST service and therefore doesn't maintain state between client requests.

A final point to note here is that all this takes place using SSL to ensure that keys, secrets, codes etc are hidden from prying eyes.

A really good way of seeing all this in action is to create a Hootsuite account and use it to access your Twitter, Facebook, LinkedIn etc data: all the screens popup in all the right places: probably a classic implementation.