How OAuth works

Java Brains
Jul 30, 2020 · 8 min read
Image for post
Image for post
Photo by Laura Gariglio on Unsplash

OAuth is one of those technologies that is almost as widely misunderstood as it’s used. In this article, let’s strip away the jargon and really understand how the technology behind OAuth actually works.

First of all, as you can guess from the name, OAuth has something to do with Auth. But does auth mean authentication or authorization? Well, the short answer is — OAuth is meant for authorization, not authentication. More importantly, OAuth was originally created not for a service to authorize a person. It was meant for a service to authorize another service. Now why on earth would a service need to be authorized?

Did you know: The “Auth” in OAuth is for authorization, not authentication!

When two services talk

Let’s take a classic example of a photo printing service. You must have seen websites like this. You provide them an image file and you pay them to ship printed photos to your address.

Imagine you are starting a new photo printing business. You build a website that lets people upload photos and order prints online. Now, here’s the thing. Nobody keeps photos on their machines anymore. They use the cloud! And so you keep getting feature requests to provide users the ability to import their photos from somewhere like Google Drive and then print it directly from there, without the users having to download them and upload again.

Image for post
Image for post

Okay, that’s a fair ask. Now what do you have to do to implement an Import from Google Drive feature for your application? You need to connect to the user’s Google Drive account and access their files. But wait! How can your application do that? The user’s files on Google Drive needs the user’s Google authentication. How can you write code for your website that can authenticate with Google on behalf of your users?

Well, here’s something you can do. You can ask the user for their Google ID and password. Your app could say:

“Hey user, do you want me to print your photos on Google? Well, Google doesn’t give me access. So, here’s this screen where you enter your Google ID and password. Give them to me, and I’ll login to your Google account and access your photos and print them”.

Image for post
Image for post

Do you think users will hand your photo printing service their Google ID and password? They don’t trust you! What they want to give you is access to just certain photos. They don’t want to give you access to their whole Google drive and email and everything else. Your service might pinky-promise that it’ll access just their photos, but there is no guarantee! So, while this works in theory, this is not practical.

Now you might say — Google Drive has a share feature! You can ask the user to share the files out and then provide the shared link to your service. But there are problems there too. What if the users don’t want to share files out to anyone. Also, what if it’s a different scenario where sharing isn’t an option? For example, think of a scenario where your service wants to access the user’s contacts to send app invites? There’s no way you can ask the user to share their address book. Such a feature doesn’t even exist! So, how do you have a third party service authorize with a service like Google without your user providing it their credentials?

Enter OAuth

To solve this problem of services trying to access each other on behalf of the user, there was a standard protocol created called OAuth. The first version of the standard, now called OAuth 1, wasn’t that popular. But the current version, OAuth 2, is very widely used and adopted. When anyone mentions OAuth these days, they are almost always referring to OAuth 2.

Okay, so how does OAuth work? A very commonly used analogy that’s used to help people understand OAuth is the valet key model for cars. Let me explain.

The valet problem

Think of how parking attendants or valets work. The idea is that a car owner drives up to a parking garage, and instead of fighting for a parking spot. themselves, they just get down, hand their key to the valet and say, “Hey Mr Valet guy, park my car for me”. The valet takes the key, drives the car, finds a spot and parks the car.

Now I wouldn’t have a problem handing my beat-up old car to any valet. But imagine if a rich guy pulling in with a million dollar sports car. They would be justified in being a little hesitant to hand over the keys. What if a malicious valet picks up the keys and takes the car for a long drive or opens the trunk or glove compartment?

Image for post
Image for post

This is why some cars come with an additional key called the valet key. This key is just like the main car key but with reduced access. It can start and stop the car. But it cannot open the trunk or the glove compartment. It cannot open the fuel tank. Stuff like that. If the sports car owner has such a key, they would be more comfortable handing this key to the valet.They know the valet cannot do a whole lot with that key apart from their intended purpose.

Image for post
Image for post

So, here the car owner is using two “services”. The car service and the valet service. The valet service needs to access the car service directly to do the job. So, rather than give the complete “credentials” of the car service to the valet service, the car owner gives reduced or limited access to the car service.

The OAuth flow

OAuth is an authorization mechanism where services can authorize against each other on your behalf once you’ve given them permission. It is often referred to as delegated access for this reason. It is also an open standard — as it obviously needs to be — because multiple services over the internet need to talk to each other. So there is a specification that all these services need to follow so that they understand each other. There is a certain flow that needs to happen for this whole process to work — the OAuth flow.

OAuth is an authorization mechanism where services can authorize against each other on your behalf once you’ve given them permission. It is often referred to as delegated access for this reason.

Back to our photo printing example. Here’s the situation:

  1. You have a service that needs to access the user’s Google Drive files
  2. We have a user who is logged into both this service and to Google. Both services trust the user. They just don’t trust each other.
  3. The problem we want to solve is to have these two services work with each other.

If both these services have OAuth implemented, here’s how the interaction works

Image for post
Image for post
  1. The photo print service goes to Google and says, “Hey, I need this user’s files”.
  2. With OAuth implemented, Google does something interesting. It goes to the user and says “Look here, user. There’s this service here that wants to access some of your files. Is this legit? Here’s the list of things this service wants to do. Shall I go ahead and allow it?”
  3. Now the user sees a screen that clearly specifies A) Who is asking for access to the user’s Google account and B) What’s the list of permissions that the service wants.
  4. Now if the user is the person who is trying to print the photo, they’ll look at that and say “Okay, this is all correct. Please allow access”.
  5. Now Google has reason to trust the service, so it gives the service a key token (called the authorization token) that contains all the allowed permissions. It’s a limited access token. A “valet key token”, if you will!
  6. And now every time the photo printing service needs to access the Google Drive, it just hands this token with the request and says “Hey Google, I need access to that file. Here’s the token that you gave me which has user verified access to these permissions. Let me in!”
  7. And each time this happens, Google looks at the token and says “Hmm, okay, that’s legit. You can access this”. With the token, the photo service has limited access to only the permissions the user has previously approved

You might have seen these screens from Facebook or Google asking for permissions.

Image for post
Image for post

The screen informs you which service is trying to access what permissions on your behalf. If you accept, an access token is handed to the service which allows future access so that you don’t have to click allow every time.

Access token

What does this access token look like? It has to be a token that contains information about all the allowed permissions and also needs to be tamper-proof — something that the service can verify. How do you create a token that can contain data within it but is also secure so that it cannot be modified? There is a specific token format called JWT that works perfectly. Check out this article to learn how JWT works!

Now that you know how this flow works, it is also obvious to see why OAuth is used for authorization, not authentication. In this case, the user is actually authenticated to both the services already. The problem being solved here is how to authorize one service with another.

Now that you know the OAuth flow, the next time you see these OAuth access consent screens, you’ll know what’s happening and why!

Weekly Webtips

Explore the world of web technologies through a series of tutorials

By Weekly Webtips

Get the latest news on the world of web technologies with a series of tutorial Take a look

By signing up, you will create a Medium account if you don’t already have one. Review our Privacy Policy for more information about our privacy practices.

Check your inbox
Medium sent you an email at to complete your subscription.

Java Brains

Written by

Weekly Webtips

Explore the world of web technologies through a series of tutorials

Java Brains

Written by

Weekly Webtips

Explore the world of web technologies through a series of tutorials

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app