Understanding OAuth: Can I play in your garden?

Despite having a 9-5 job, you need to get things done inside your locked house. Your housemaid comes to clean every day at 10 am. You need your living room tiles redesigned, but the mason is scheduled to come at 2 pm. 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.

Is this approach really safe? Can you simply entrust the keys to your entire house to someone? Or can you restrict access so that access is given only to those parts of the house where work needs to be done? OAuth makes such selective access possible.

The problem with giving total access

There are a few problems with giving the keys to your entire house to another person.

  • First, you need a highly trustworthy neighbour who will not misuse your keys.
  • Second, neither you nor your neighbour knows if the maid or the mason can be trusted being alone in the house.
  • It is unreasonable to ask the neighbour to stay in your house to watch over the housemaid and the mason as long as it takes them to complete their work.

What to do instead

Here is a solution.

  • You do away with the single lock and key that guards your house’s front door.
    From now on, the door is simply closed with a latch to keep the dust and stray animals out.
  • You have broken up your home security into multiple locks & keys, one pair to guard every detail in your home. You have a lock for every room and every cabinet.
  • You also set up special locks for every water tap/faucet at your home. With this lock in place, no one can open the faucets, and so cannot get running water.
  • If a person is appointed to visit your home, you will give them a copy of the keys to only what they need.
    The maid needs access to the cabinet where you store mops, brushes and cleaning agents. She also needs access to one faucet in your house from where she can draw water for mopping.
    The mason needs access to the living room. He’ll probably bring his own tools and doesn’t need access to your toolbox.
  • While the maid visits every day, the mason’s job is one-time. So you will visit him later and take the living room keys back. Or he may leave the keys with your neighbour.

Such modular security is complicated to set up, but it prevents misuse. This type of security micromanages the gateway to every resource. It seems daunting, even ridiculous to achieve in the real world. But it can be done without hassle in the digital world. Using Open Authentication or OAuth.

Intro to OAuth-speak

Let us revisit our home security example, but this time with OAuth jargon. We will also draw similarities with widely used Internet services.

003-why-oauth

  • Your home and the things inside are resources. You are the owner of the resources.
    Similarly, you own your Facebook profile and Facebook timeline.
  • The maid and the mason are external apps who want to use/alter your resource. We can also call them resource clients.
    Candy Crush and Instagram are external apps that use your Facebook profile.
  • External apps may simply use your resources or alter them.
    If you give permission to your neighbour’s children to play in your garden, the children bring their own toys and use your garden as a playground. Unless they are mischievous brats, they’ll leave your lawn, flowerpots and trees alone.
    The maid cleans the floor/carpet in your rooms, thus altering their state from dusty to clean.
    The mason rips apart existing tiles and lays new ones, thus altering the state of the living room.
    Candy Crush needs to read your name from your profile. It uses your profile picture on its leader board. But with your permission, Instagram puts photos into your Facebook timeline every time you click a picture, thus altering timeline’s state.
  • Permissions are specific, such that particular clients can access only certain resources. The set of permissions available to a particular client is called a scope.
    Your maid gets to walk on the floors in every room. She also gets to use one faucet for running water. She gets access to the cabinets with cleaning supplies. But she cannot open the fridge and eat your pastry. The scope of her permissions supports only cleaning.
    The mason gets only the key to the living room.
    The children get the keys to the garden.
    Candy Crush only gets to read your name and profile picture. Instagram too gets to read your name and profile picture but also gets to post to your timeline.

The OAuth flow at work

Let us see how OAuth works. OAuth has the following players.

  • The resource owner is the person who owns a resource. E.g, you own your Facebook profile, albums, etc.
  • The resource client is the app that wants access to one of the owner’s resources.
  • The authentication server authenticates the resource owner and asks for permission to grant access to the client.
  • If the owner agrees, then the authorisation server hands out a token to the client. The client uses this token for all further access to the resource. The token is the key to the resource.
  • Tokens are usually time-bound. They may be single-use. They can also be short term or long term, e.g. valid for a week or a month. They can also be permanent, i.e. valid for an indefinite time until the access is revoked by the resource owner.

Here is the OAuth flow for an app (or a website) XYZ (resource client) which wants to use your Twitter account for authentication and your timeline (resources).

002-twitter-authorize

  1. On the XYZ app, you choose to read from/post to your Twitter timeline.
  2. XYZ approaches Twitter and asks for permission to read your profile name, Twitter handle and display picture, and also to write to your timeline. That is the scope of the permissions requested by XYZ.
  3. Twitter’s authentication server asks you for those rights. A dialog box is shown to ask for your permission. You are probably quite familiar with such dialog boxes by now. If you are signed out, Twitter first asks you to log in.
  4. Once you approve, the authentication server returns a temporary entity called a ‘grant token’, a temporary token. This is still not the key to your Twitter account.
  5. XYZ gives the grant token to Twitter’s authorisation server, which checks the validity of the grant with the authentication server.
  6. Once the authorisation server is pleased, it provides XYZ with the access token, which is the key to unlock the permitted Twitter resources.
  7. Whenever XYZ wants your Twitter profile or to write to your timeline, it approaches Twitter with the access token. Twitter verifies the authenticity of the token with the authorisation server and once satisfied, gives XYZ the requested resource.

Conclusion

OAuth seems complicated with many moving parts, but is quite simple. It provides tokens for selective access to resources, just like keys to various rooms/tools inside your house. By micromanaging authorisation, OAuth has made the Internet safer and given it the ability to maintain your privacy within the crowd.

Further reading