OAuth 2.0, but Hold the Jargon Please

You likely have profiles on dozens of applications containing personal information. Originally siloed, these applications have become increasingly connected. Discord searches Facebook for suggested friends, Jira creates user accounts with Github profiles, and so on. This trend of applications talking to each other on your behalf is called “Delegated Access” and has become a necessary part of our online lives.

However, because of the way these applications protect their data, developers run into a challenge: how do we delegate access? Almost every application is protected by a basic username/password schema. To allow Application A to get the data it needs from Application B would require constantly logging into Application B on behalf of Application A — how unwieldy! The workaround was to give Application A the username and password credentials to log in to Application B, which was problematic for a few reasons:

• Application A stored credentials as cleartext
• Application A was given broad, unfettered access to Application B
• Users could not easily revoke access for Application A
• A compromised Application A puts Application B at risk

OAuth was formed as a solution to this Catch-22 situation: how to provide delegated access without putting the end user’s data at risk.

OAuth Protocol Flow

Consider that Teslas have a “Valet Mode” for which you need a valet keycard. This keycard informs the vehicle that it is to operate with limited functionality, restricting the max speed and acceleration and locking the trunk. This technique is conceptually identical to how OAuth operates. The Tesla Owner gives the valet limited access to his/her Tesla without needing to provide the main vehicle key.

OAuth is quite popular for social media apps. You are likely familiar with requests like these:

When receiving a pop-up like this, the OAuth protocol operates in the background as follows:

1. Spotify sends a message to Bob requesting the rights to access his public profile, friend list, email and birthday.
2. Bob provides Spotify with a grant to collect said data.
3. Spotify sends the grant to a Facebook API.
4. Facebook API verifies grant and sends an access token for Spotify to access protected resources.
5. Spotify sends the access token to another Facebook API
6. Facebook API sends the requested data to Spotify.

Through the usage of grants and tokens, which we will discuss next, Spotify is given Bob’s valet card to his Facebook account.

Peeking Under the Hood

Scopes and Tokens

Scopes and tokens are how OAuth implements subjective access controls. Together they represent a “permission to do something.” The token is the “permission” part and the scope defines what the “do something” is. Think of a movie ticket: the scope is the name of the movie you are authorized to watch and the ticket itself is the token, which only a theater employee can validate as authentic. From our Tesla example, the scope is what vehicle functions are enabled when started with the valet key. The access token is the valet key itself, which the Tesla vehicle can recognize only if the key was issued by the Tesla dealership.

Going back to our Spotify example: in Step 4, Spotify receives an access token to successfully query Facebook’s servers. This token is meaningless to Spotify, but Facebook is able to decode it and verify that Spotify was really given permission from Bob. Contained within the token is a field for “scope” which lets Facebook know what Spotify is allowed to do. In this case, it is read Bob’s public profile, email, friend list, and birthday.

Grants and Flows

Grants dictate the order of operations for Spotify to obtain an access token. These unique orderings are called flows. Going back to our movie theater analogy, there are two ways to be granted a ticket: (1) Purchase in the theater (2) Purchase online. The method you’ve chosen dictates what you will do to obtain the ticket. Purchasing in the theater may look like:

1. Navigate to theater location
2. Enter theater
3. Walk to front counter
4. Select showtime
5. Provide credit card to theater employee
6. Sign receipt
7. Obtain physical ticket

Whereas purchasing online could follow these steps:

1. Navigate to theater webpage
2. Select showtime
3. Check out cart
4. Enter payment information
5. Obtain digital ticket through email

As you can see, grants are not material things in the same way a token is, but instead, they inform which flow Facebook should use when communicating with Spotify. Differing grants are optimized for specific use cases and will affect which security measures apply.

OAuth, being an internet protocol, works over HTTPS. All communication between Facebook, Spotify and Bob happens by way of URIs in your browser. These URIs are queries with parameters included as part of the string. Contained within these parameters is the information Facebook needs, to understand which flow to follow.

Knowing which of the five grant types to use is essential to setting up the right OAuth flow.

• Authorization Code Grant
• Authorization Code Grant with PKCE Extension
• Client Credentials
• Device Code
• Refresh Token

Conclusion

Despite providing an often overlooked convenience, OAuth is a complex protocol with hundreds of different ways to be implemented. Before diving into the deep end and drowning in all the terms and concepts, understanding the basic conceptual structure will make treading water much easier.