How OAuth works

Java Brains
Jul 30, 2020 · 8 min read
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

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.

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”.

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

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

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?

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.

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.

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

  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.

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

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

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

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store