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.

Siva Narayanan

I am known to be "the CTO of one, the father of two, and the roasting baba of many."

More of our stories from

Engineering
How we created a Medium-like blurry background effect

Here's how we improved user experience, decreased load time and made Fyle accessible for users without a fast internet.

Read more...
Bye bye WordPress, welcome Webflow.

This blogpost documents our journey as we bid goodbye to WordPress and migrated to Webflow.

Read more...
How we reduced our website build time by 59%

I came up with five 3 second changes to reduce the build time by over 59%. Here's more about my experience.

Read more...
Hello, Web Technologies!

I’m a first-time entrepreneur and I’ll be recording my learnings and experiments over time. I am always eager to interac

Read more...
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

Read more...
Dealing with Nested Objects in your Web Application

A couple of weeks ago, I ran into a peculiar problem that I think might be useful to talk about. It took me a bunch of

Read more...
Eliminate Boilerplate Java code with Lombok

I’ve been writing a lot of boilerplate Java code, lately — getters, setters, hashCode, equals and toString. Actually, I’

Read more...
Hello, Web Technologies! — Part II

This is a follow-up to my first post about technology choices I made while building out our product. I wanted to pen my

Read more...
Sharing Files using S3 Pre-signed URLs

Amazon’s S3 is a reliable, cheap way to store data. We use it to store user-uploaded images and documents as s3 objects

Read more...
JSON Web Token Concepts

There are many technical articles about JSON web tokens (JWT) on the interwebs, but I haven’t found one that explains...

Read more...

All Topics