OAuth2 Tutorial

Intro

OAuth2 is a widely used authorization framework enables third-party applications to obtain limited access to a web service and it has been around for some time now. Though it is popular and there are a handful of really helpful introductions and descriptions on the subject, it can be a challenge for someone unfamiliar with the topic to wrap their head around. With that in mind, my goal with this article is to give a simpler but proper understanding of OAuth2 to anyone interested; using an everyday metaphor – more or less 🙂

oauth2 wanari

Baseline

The base of the analogy I decided to go with is provided by the OAuth Community Site (https://oauth.net/about/introduction/) and is also mentioned by other posts quite often.

‘Many luxury cars today come with a valet key. It is a special key you give the parking attendant and unlike your regular key, will not allow the car to drive more than a mile or two. Some valet keys will not open the trunk, while others will block access to your onboard cell phone address book. Regardless of what restrictions the valet key imposes, the idea is very clever. You give someone limited access to your car with a special key, while using your regular key to unlock everything.’

This special key is called the access token in the context of the authorization process and the car is the resource you grant access to. The original key would be your username and password to a site or application in most cases. The valet key metaphor is a good starting point to understand how OAuth2 works but we’ll have to throw in a couple of additional parties to get the full picture. So let’s mix things up a little 🙂

Magical Car Renting

Imagine a car renting service that lets anyone lend their car through their system to strangers. It utilizes valet keys with similar purposes as described above. A specific valet key grants you access to specific functionalities of a specific car. However the company wants to provide a wide range of possibilities so they developed a method that can magically produce all kinds of valet keys instead of just one, all assigned a different subset of the car’s capabilities. Let’s take a look at how the renting service works!

So who are the participants of the process?

  • Customer: The person who wants to use the car
  • Car Owner: The person who owns the car
  • Renting company: The company that provides a secure system for renting cars
  • Car: The bundle of resources that the customers want to access

How does the process go down?

oauth2 example analogy

Customer ↔ Car Owner

Once a customer decides that they want to rent a car they have to ask the owner if they allow it. If the owner decides no, the process comes to a halt here. If the answer is yes, the owner gives the customer a permit.

Customer ↔ Renting company

The customer takes the permit from the car owner and brings it to the renting company. The company then checks whether the permit is valid. If they find it to be so the customer gets a valet key. As described above, a valet key is a special key that gives you access to a car’s specific functionalities. In this scenario a valet key is only valid for a given amount of time after which it simply stops working. Expired valet keys can be discarded as they no longer possess any value. This way if someone unauthorized gets their hands on a valet key, they can’t use it for long. The costumer also receives an RFID card that can be used to acquire a new valet key with the same properties as the previous one. When a valet key expires, the costumer has to use this card if they want to continue renting the car’s resources. An RFID card does not expire but can be revoked. If the company decides the permit is not valid the process stops.

Customer ↔ Car

Finally the customer can use the valet key to access the bundle of resources that the car is.

Magical Car Renting = OAuth2?

So how does this all compare to OAuth2? The process you just read through is basically equivalent to the Abstract Flow of Oauth2. In reality the flow has multiple versions but the abstract flow is enough to understand the basics. Now let’s see how the process looks like with a more proper terminology.

oauth2 example analogy tutorial

Matching the parts:

  • Access Token: Valet key
  • Refresh Token: RFID card
  • Resource Owner: Car owner
  • Resource Server: The car itself
  • Authorization Server: Renting company
  • Client: Costumer
  • Authorization request: Customer wants to rent a car
  • Authorization Grant: Permit
  • Resource: Car functionalities

Outro

I hope you enjoyed this interesting little introduction to OAuth2 and that I could help you better understand a protocol that otherwise might be harder.

If you’d like to see more from us, follow Wanari on Facebook or on Linkedin. If you have any questions, give them a go in the comment section!

Fanni Medvey

Fanni Medvey

Junior Backend Developer at Wanari

Latest posts by Fanni Medvey (see all)