The Non-Boring Guide to OAuth 2.0

If you’re developing an application that needs access to a user’s Google / Facebook / LinkedIn information, you’ll need to understand how OAuth 2.0 works. I read quite a few articles and most of them give terribly, terribly dry explanations using words like “secure delegated access”, “third-party clients” and “hypertext transfer protocol”. I’m going to try to make it a little more fun, if that is possible at all!

Batman, as we all know, is a terribly busy superhero fighting the Riddler, Joker, Penguin and other villains. He owns a fancy Batmobile that resides in a secure Batcave. One cannot look grubby while fighting crime — therefore, Batman requires his Batmobile to be washed and waxed every week. Batman’s assistant, Alfred, is responsible for maintaining Batmobile. This figure summarizes the important actors and components.

Batman obviously owns Batmobile and is the resource owner. Batmobile is the resource in question that is secured by an Authorization Server i.e. Batcave’s security. Alfred is the 3rd party application who needs to access Batmobile on Batman’s behalf.

At this point, you’re probably wondering — “Hold on! Alfred raised Bruce (Batman), why can’t he be trusted with a master key a.k.a Batman’s username / password?” Did you know that there have been 27 attempts to kidnap Alfred? Imagine if Bane had gotten control of all of Batcave and its contents. Furthermore, Alfred himself became a supervillain briefly when he wanted to kill Batman.

Sharing username / password with a 3rd party application is not a good idea.

We need something better. Let’s try to outline the high-level requirements for an authorization solution:

  • Batman should be able to offer limited access to Batmobile to Alfred — e.g. he should be able to open the door, but not drive the Batmobile
  • Batman shouldn’t have to be physically present all the time when the Batmobile is being cleaned
  • Batman should be able to revoke access to Alfred at any point, even if he’s not physically in the Batcave

OAuth 2.0 basically solves this problem in two steps:

  • Get Alfred an access token
  • Allow Alfred limited access to the Batmobile using the access token

The second part is pretty straightforward. When presented with an access token, Batcave security has to look up some internal structures to see if Alfred is attempting to do something he shouldn’t. The access token is passed through a HTTP header.

The first part is where the meat of the problem is: how do you get Alfred an access token? There are two important authorization flows to get the access token (there are 4 in total — but others are not as important).

  1. Authorization code flow — this is the more common use-case and is used when Alfred would like to access Batmobile even when Batman is not around (that’s our use-case). The 3rd party application, in this case, is a server application that does direct calls to Google on your behalf even when you are not around (e.g. syncing Google Calendar tasks at 3am everyday). This flow also allows for automatic refreshing of access tokens even when the user is not around.
  2. Implicit flow — let’s say Alfred was on vacation and Batman uses Acme Cleaning service this one time. Acme cleaning service should get a one-time entry to clean Batmobile and Batman would want to be around coz you never know. In a real-life application, you could use this flow to do information gathering (name, photo, email) to make signup process easier. The access token is given to an untrusted user-agent (a.k.a. Javascript) that makes appropriate calls to Google to gather the info and pre-populate your signup form. The access token expires quickly and cannot be refreshed automatically.

In both cases, the resource owner (Batman) is presented a screen detailing the resources the 3rd party application (Alfred) would like to access.

Independent of the authorization flow, the authorization server would implement a way to revoke granted access tokens and bar future access.

In conclusion, the way to solve this problem is to get Alfred (server side 3rd party application) a refreshable access token to clean Batmobile. If Batman employs Acme cleaning services (e.g. javascript 3rd party application), they should get a limited-time access token with very restricted access.

IMHO, this looks a lot like employee badges and visitor badges

Hopefully, this blogpost has demystified OAuth 2.0 a little bit. There are a bunch of details around authorization flow that other blogs have covered in depth. I liked Digital Ocean’s OAuth 2.0 explanation. You should also read Google and LinkedIn’s developer documentation to talk OAuth 2.0 with their services.