What is OAuth and Why do Companies Use It?

There have been a lot of changes in the OAuth protocol over the past few years. You’re not alone if you’ve experienced confusion about what exactly is being changed, and you’re scratching your head as to the “what” and “why” of what’s going on.

Just for starters, let’s take a look at what exactly OAuth is. If you’re as old as us, then you remember the time when you had to enter your email address and a password for literally EVERYTHING you hoped to sign up for. Now, with OAuth…you can often just give authorization to the app or website, and just sail on through toward your goal.

Here’s an example. Back in the early days of Facebook, they used to ask you to connect your address book so you could find or invite your friends to join their network. When they first rolled out this feature, the only way to add your contacts automatically was to hand over your username and password to your email account. Gasp!

And many of us did this, despite it being very insecure because it was the easiest way to share this information with Facebook. But nowadays, we know better than to give our password to a random stranger.

This is why OAuth exists: it permits sharing your data without sharing passwords.

Why is sharing a password bad? In case you need a reminder, here’s why you don’t want to share your password.

• No limits – Whatever app holds your username and password has complete access to your account. In addition to reading your contacts, they could read all your personal emails. That’s not what you had intended to share! Furthermore, there is no way to revoke access short of resetting your password.
• No accountability – You have no record of the apps that you shared your password with. So if something changes that you didn’t expect, it’s very difficult to trace it back to which malicious or buggy app.
• Duplication – It’s human nature to reuse passwords. So if a malicious site knows one password that you’ve used, they will try to use the same password on other sites. And they’ll add it to a list of known passwords. The very best passwords are hard to guess, but even the best password is made insecure once they’ve been added to a list.

So to address these issues, a number of smart folks got together to design a process for online applications to do this kind of sharing without compromising people’s passwords. They called it OAuth1.0 and it was adopted by Facebook, Google, Twitter, and others. Microsoft didn’t join the OAuth party and came up with their own version called DelAuth, an abbreviated portmanteau of “delegated authentication”, which is more descriptive but less catchy than OAuth. Eventually, they came onboard with OAuth2.0 and discarded DelAuth.

There’s a useful analogy to help understand how OAuth allows sharing resources while protecting your privacy. In his article about OAuth, Matt Raible compares OAuth to a hotel key card:

You can think of this as hotel key cards, but for apps. If you have a hotel key card, you can get access to your room. How do you get a hotel key card? You have to do an authentication process at the front desk to get it. After authenticating and obtaining the key card, you can access resources across the hotel.

In his analogy, you have to imagine that you are a developer of an application (hotel guest), requesting access to a protected resource (a hotel room) which is controlled by the resource server (the front desk).

As of the writing of this article, the OAuth 2.0 protocol is the most common and successful out of the bunch. The OAuth protocol enables users to provide third-party access to their web resources without sharing passwords, which makes the user experience much more streamlined and “safe-feeling.” The origins of this can be traced to 2006 when a group of web developers put their brains together to figure out a solution for the never-ending cycle of API authorizations. They hoped for, and succeeded, in developing a way for third-party applications to have much easier and secure access to user data. By consolidating into a single, open protocol, it became much more secure as well.

How does OAuth work?

OAuth protects your password by making sure that you only enter it on the associated login screen. For example, you never enter your Google account password anywhere but on accounts.google.com. This means that when a different app wants to access some data in your Google account, it must send you away to sign in on Google’s site, and then Google must send you back to the app after you have granted consent.

Keep that round-trip in mind while we get into the details.

First, some nomenclature. There are three different parties that are involved with OAuth dialogue (trialogue?):

• The Resource Owner is the person who controls some data on the internet,
• the Resource Server hosts and controls access to the protected resources, and
• the Client which is the application that is requesting access to the resource.

Here are a few more key concepts:

• Scope – the permission being requested by the client
• Authorization Code – a short-lived code that can be exchanged for an access token. The resource server sends this to the client after the user grants permission.
• Access Token – a string of characters that is used to access the protected resources. This is the final output of the OAuth flow.

To understand OAuth, we have to understand the conversation that happens between these parties. It is vital that there is a specific order and structure to the system since it’s a universal standard.

The OAuth flow starts when a user wants to share their data with a website. The first step is for the website to send the user away to a special endpoint that starts the OAuth flow with the resource server.

They’ll go through a flow where they’re asked to sign-in to their account at the resource server. Typically this involves entering their username and password. Next, they’re going to be asked by this account to confirm that they want to provide this type of access to the website they were just visiting.

By agreeing, the user is basically answering whether or not they are allowing that website to have access to their private data. Either way, the browser window will be redirected back to the app’s webpage to a URL, specifically for the website. The query string of this URL app includes a time-limited “authorization code” that indicates the user’s consent.

This “authorization code” is useless on its own. It must be combined with the app’s OAuth credentials and be exchanged for an “access token”. The access token is the key that can be used to access the private data which the user shared. What the app can do with the access token is limited to the scopes that the user has approved. So if this is a “read my contacts” token, then the client app could use the access token to read their contacts through the Contacts API or the People API.

So basically, what’s happening is this. Google’s going to say, “Hey, this company is asking if they can see your contacts. Is that okay or not?” The user says, “Yeah, it’s okay.” Then access is granted.

The code is for single-use, with a very short expiration. The token is actually what the APIs are waiting for. The input parameter for all the API endpoints are not single-use and can be used multiple times with multiple APIs if the user has given the client app permission to use each of them.

At that point, it can be the end of the process…but not always. In some cases, an app will want to request what’s usually called “offline access.” In the case we just described the user has given access to the app, so the app just goes and does its thing…The End. However, apps can also request a longer timeframe for access, such that the app can continually synchronize the contacts or any other permissible data over the periods of hours or days. In that case, the app would go through a similar process as it did the first time, but instead of having a code available, it has what’s called a refresh token. It uses the refresh token to access the contacts at points in the future when the user is no longer present.

The user signs into their account and then is able to review the requested access. If the user is OK with giving access, they will consent and be redirected back to the app. That’s all the user needs to see.

All the complexity in this flow is to ensure that the app never sees the user’s password. Notice that the password never went to the app. The app only saw an authorization code after the user granted consent. And the app uses an access token to authorize subsequent requests to the API. This access token is like the hotel key card which allows the app to access the hotel room and services for a limited time.

Here’s how it happens:

1. The app sends the user’s browser to a predefined URL to start the authorization process, typically in a new browser window.
2. The server authenticates the user and displays the consent screen to the user clearly showing what access is being requested. The user approves the access request.
3. The server responds by redirecting the browser back to the client’s app and includes a code in the URL. This is when the client app will typically close the popup window and bring the user back to their app.
4. The client app exchanges this code for an access token, communicating directly with the server.
5. The app can now (finally!) use the access token to make calls to access the resources.

These steps describe broadly how the user experience and backend calls coordinate to complete the OAuth flow, protecting the end-user’s credentials.

Now, you may be asking: How does the server know who the app is?

Before the user can be involved in the OAuth flow, the app and the resource server need to get together to agree on a few things. Typically, this means that the server offers an interface where developers can register their apps. The developer will describe their app and typically upload a logo to be shown to users. An important step is for the developer to enter the URL where they expect the server to send the authorization code. This ensures security by predefining this endpoint for the return trip of the OAuth flow.

Each of the popular address book providers handles this registration process a little differently. In our next article, we break down the similarities and differences between Google, Microsoft, and Yahoo so that you can save some time if you’re doing these integrations yourself. of course, if you’d rather not do it yourself you can always use our Contact Picker instead!

OAuth is not simple but it protects users’ credentials and limits access granted to third-party apps. You may not be building an OAuth provider but now you should have the key concepts to understand how an OAuth client interacts and why the set up is necessary. These tools should help you be successful when setting up your own OAuth client.