Understanding OAuth: Can I play in your garden?

We all face this situation many times. You have a standard 9-5 job, but you need to get things done at home. Maybe your house maid comes to clean up your home only at 10am. Maybe, you need our living room tiles redesigned and the mason is scheduled to come in at 2pm. You make the necessary arrangements to leave a copy of your house keys with your neighbour, who in turn allows the maid or mason into the house on your behalf.

However there are a few problems with this method. Firstly, you need a highly trustworthy neighbour who will not misuse your keys. Secondly, neither you, nor your neighbour knows if the maid or the mason can be entrusted with being in the house when you are not. It is unreasonable to ask the neighbour to stay in your house for hours to watch over.

However, consider the situation where you have broken up the security into multiple locks & keys, one pair to guard almost every aspect of our home, instead of one central lock & key for the entire home itself. You have a lock for every room. Every cabinet and shelf is locked. You also lock up each water faucet, such that only those you trust to use water wisely can open the faucets. Everything must be unlocked before use. The main door itself is either simply latched or maybe opened remotely (say via Internet) if the person requests you over the phone to open it. Before the person visits, you make sure that he/she is given the right keys to part of the house that he/she needs access to. E.g. the maid only needs access to the bathroom faucet to use the water and access to the janitor’s supply place for mops, brushes and the like. The mason needs access to the living room alone.

Such modular security seems complicated while setting up, but it prevents misuse by micro-managing the gateway to every resource. It seems largely difficult, even slightly ridiculous to achieve in the real world, but it can be done without a hassle in the digital world. And that exactly is the premise behind Open Authentication or OAuth.

Intro to OAuth-speak

Let us consider the example above and use some OAuth parlance / jargon and a widely used Internet service as a digital example.

003-why-oauth

  1. Your home is your resource. You are the ‘owner’ of the resource. Similarly, you own your Facebook profile.
  2. The maid is an ‘external app’ who wants to use/alter your resources. Ditto for the mason. We can also call them ‘resource clients’. Candy Crush and Instagram are external apps that can use your Facebook profile.
  3. External apps may simply ‘use’ your resources or ‘alter’ them. Let’s say that you give permission to your neighbour’s children to play in your garden. The children bring their own toys and simply use your garden as a playground. Unless they are mischievous brats, they’ll leave your garden and its lawn, flower-pots and trees alone. However, the maid is going to clean up the floor / carpet in your rooms and alter their state. The mason takes it a step further by ripping up the existing tiles and laying down new ones. Similarly, Candy Crush only needs to read your name from your profile and use your profile picture to show on its leader board. Instagram however is going to directly put photos into your Facebook timeline and albums every time you use the app to take pictures.
  4. Permissions are ‘scoped’ for every resource client. Your maid gets to walk on the floors in every room. She also gets to use the faucets in the bathroom to use the running water for cleaning. She gets access to the janitor’s supply room for the tools. However she cannot open the fridge and eat your special pastry. You have given her only those keys that enable her to unlock each room to swab their floors and to the rooms which hold the water and the supplies. The mason gets only the key to the living room. The children get the keys to the garden’s gate.
    Candy Crush only gets to read your name and profile picture. Instagram gets to read your name and profile picture, while also being allowed to post to your timeline and albums.

The OAuth flow at work

Let us get behind the scenes and see how the OAuth flow works. OAuth has three players.

  1. The resource owner is the person who owns a resource, e.g. You own your Facebook profile, albums, etc.
  2. The resource client is the person who wants access to one of the owner’s resources.
  3. The authentication server is responsible for checking if the resource owner is okay with handing out access to the client. If yes, then the server hands out a token (keys) to the client. The client uses this token in all further communication. The token can be called the keys to the resources.

Let us imagine that you have just opened a piece of software (either an app or a website) called XYZ (resource client) and it has an option to use your Twitter account for authentication and other features (resources) such as posting to your timeline. Here is how the OAuth flow works in this case.

002-twitter-authorize

  1. You choose to use your Twitter account for authentication in XYZ.
  2. XYZ approaches Twitter and requests it to speak to you regarding access to various parts of your profile. Namely it needs access to your read your profile name, handle and display picture and also to write to your timeline. In more precise words, XYZ approaches Twitter for permission to access a certain ‘scope’ in your Twitter profile.
  3. Armed with this information, Twitter’s permission system now approaches you to ask for those rights. This manifest itselfs in the form of a permission dialog that you generally see when apps and websites ask for your permission for certain rights in your Twitter, Google or Facebook accounts. If you happen to be signed out of your Twitter account at that moment, Twitter also asks you to first log in, before presenting the permissions dialog.
  4. Once you have approved, Twitter’s permission system returns a temporary entity called a ‘grant’ to XYZ. This is like a small receipt that Twitter hands to XYZ, stating that you have given permission for certain scope of usage. However, this is still not the key to your account.
  5. With the grant in possession, XYZ now approaches another big system in Twitter, named the authorisation server. XYZ gives the grant to the authorisation server, which quickly checks with the permission system to check if the grant is genuine.
  6. Once the authorisation server is pleased, it provides XYZ with a ‘token’, which is indeed the key to unlock your Twitter resources, that you have permitted XYZ to use.
  7. Whenever XYZ needs something from your Twitter account, it approaches Twitter along with the token. Twitter quickly verifies the authenticity of the token with its authorisation server and once satisfied, gives XYZ the resource, e.g. the handle, profile name, profile picture, etc.

Conclusion

OAuth seems very complicated to understand at first, but in reality is quite simple and has a lot of moving parts. In the end it all boils down to tokens to selectively access certain resources from a large pool, just like keys to various rooms / tools inside your house. By micro-managing authorisation, OAuth has made Internet a lot more possible to maintain your privacy among the crowd.