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:
- The user logs into their SaaS provider
- Your application is sent an Authorisation Code
- Your application uses the Authorisation Code to retrieve an Access Token
- 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 are 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.
Reference: OAuth 2.0 Webapp Flow Overview from our JCG partner Roger Hughes at the Captain Debug’s Blog blog.
