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 SummaryIn 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:
|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 DanceThe table below describes the OAuth 2.0 dance in detail...
|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) |
client_id (app key)
|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)
|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)
|User||Confirms the above to the SaaS||client_id: (app key) |
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)
|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)
|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.