[[Graph 1 – the drawing of Login With X]]

It’s when websites or apps ask you to “Log In With Google”, “Log In With Instragram”.

[[Get lots of pictures of OAuth here]]

OAuth, specifically OAuth 2.1, though commonly just referred to as OAuth 2, is how things like “Log in with Google”, or “Log in with Instagram” work. You already have an account with Instagram, so it’s easier to just login with those credentials than to create a brand new login for yet another app.

When you select Log In With Google, you get redirected to Google’s own log-in form. This form shows you:

• Who is asking for permission from you
• What they want to have access to / what they want to be able to do

After considering this form, you confirm or deny the Authorization Request, and then you get redirected back to the site you were trying to log into originally. There was a bit of a bouncing from hither and tither, but it worked well and now you’re logged into the new website.

This means:

• The website does not know your Google password
• The website does not store your Google password
• The website cannot login as you
• The website cannot impersonate you
• The website cannot do whatever it wants

Whats important to know here is that when you login with Google, only Google knows about your password. The website doesn’t know anything. All it does is give the website access to specific aspects your account. What, specifically, it has access to was shown to you on the Authorization Screen.

For most purposes, the only thing you need to remember is that it reduces the amount of logins you need to keep track of. Instead of creating yet another account on yet another site, you can just use your Google account.

OAuth2 is how you login into one site with an account from another. It’s designed to avoid sharing actual credentials such as passwords, while still letting you access things associated with your account on one service, while using a different service. One example of this would be stats.fm, an app that shows listening statistics from your Spotify account. Stats.fm is not affiliated with Spotify, but it needs access to your Spotify account to work. When you log in, it asks you to “connect your Spotify account”, which brings you to the Spotify login screen. There, you log into Spotify like normal, on Spotify’s actual spotify.com domain, and then you get redirected back to stats.fm, with the redirect operation carrying some extra information. It is with this extra information that the app now has access to knowledge related to your Spotify account.

[[Animation 2 – anim including return of Access Token]]

Access Token

This is accomplished by the acquistion of an Access Token, which is string that is sent back and forth between stats.fm, and Spotify. This string is assocated with your specific account and gives its bearer access to information associated with your Spotify account. It is functionally similar to a cookie holding login information. The contents of the string are intended to be opaque to users. The contents are not important, what matters is that the string is sent over to the server exactly as-is.

Whoever bears this token has access to everything the token was given access to during the initial Authorization. Because of this property, an Access Token, and all other tokens similar to it, are known as a broad category, as Bearer Tokens. We will be referring to Bearer Tokens a lot, but just remember that a Bearer Token is a category of credential, and Access Tokens are a specific type of Bearer Token.

Access Tokens are typically short-lived. What this means in practice is that access tokens have a lifetime of about an hour (3600 seconds, this number will appear a lot as well), after which the the token becomes invalid. Continuing to use the token will result in a lot of 403 Unauthorized errors.

Refresh Token

So how do you get a new one if its expired? Does the user have to do another Authorization step? No, to get another Access Token we use something called a Refresh Token. When we got our original Access Token, a handful of other data was sent to us at the same time. One such piece data we got in addition to the Access Token was another token, called the Refresh Token. A Refresh Token’s only purpose is to be given back to the main server. When we do so, the sever sends us back another Access Token, and another Refresh Token.

[[Animation 3 – anim including return of Access And Refresh Tokens]]

[[Animation 4 – anim including the Auth Code, return, and exchange]]

OAuth 2 is a set of specifications for supplying third-party applications with first-party authorization (“authz”, or “what you are allowed to do”) information. What’s important to know is that [OAuth 2.1[(21 RFC)] is the current main spec, and that it defines the Authorization Flow with PKCE, and the Client Credentials flow. There’s also an extension to OAuth2 called OpenID Connect (OIDC) that deals with providing authentication (“authn”, or “who you are”) information. The difference between the two is often muddled.

OAuth 2 uses a standard set of terminology that one should be familiar with, otherwise it becomes confusing trying to understand what is talking to who and under what circumstances. The entities commonly seen in the spec are:

• Authorization Server
• Resource Server
• Resource Owner
• Resouce
• Client
• User
• User Agent
• Flow
• Token

The spec defines treats these entities seperately, but oftentimes they can be co-located, making the distinction hard to grasp when thinking about it from the perspective of certain services you may have encountered in the wild.

Working Definitions

You can find the true definitions in the spec, but let’s outline them here:

• Authorization Server
  • This is the authority with whom you are trying offer “Log In With” capability with.
  • This is Spotify, Instagram, Google, etc, where the users actual account lies
  • Specifically, this is their accounts.xyz.com doman, as opposed to their generaic xyz.com domain.
  • From the perspective of OAuth, the Authorization Servers only responsibility is providing access to user account checks.
  • Authorization Servers hold all the Resource Owners
• Resource Server
  • This is the server where “resources” are.
  • Typically, this is the api.xyz.com domain or the xyz.com/api/ endpoint.
  • The resouce server does not Authorize,
• Resource
  • A resource is anything that your integrating application might be interested in
    • Liked Songs
    • Friends List
    • Calendar Events
    • Product Reviews,
    • etc
• Resource Owner
  • This a term describing whose things you’re interested in
  • whose Liked Songs?
  • whose Friends List?
  • whose Calendar Events?
  • From the perspctive of OAuth, the Resouce Owner is the literal user account on the Authorization Server. As a matter of philosophy, that means that a “User” and a “Resource Owner” are the same abstract entity, represented at different concrete steps of the process.
  • A Resource Owner necessarily has an account on the Authorization Server
• User
  • The person trying to login, the person actually phsyically performing the button clicks to initiate the varius Flows
• User Agent
  • The user’s Browser, or the Web View used to phsyically handle the Authoriztion process
• Flow
  • Flows are a little more abstract, but they represent the various different types of back-and-forth to obtain Tokens
  • the two major flows are Client Credentials, and Authorization
    • n.b, 1: Authorization used to be called “Authorization”, and then an extension known as “Authorization with PKCE” was introduced, and then that got absorped into the main spec, so now it’s just back to “Authorization”.
    • n.b, 2: There used to be something called the “Implicit Flow”. This is now deleted, and servers that continue to support it are out of compliance with the current specification.
• Token
  • A string that can be used to access the API servers on behalf of a user.
• Client
  • A specific application that has bene registered with the Authorization Server, and is permitted to receive and use Tokens.
  • From the perspective of you, a developer integrating with an OAuth Server, this is is your application, that you have registered with the OAuth Server.

For reference, here is how the OAuth Spec depicts the main Flow

     +--------+                               +---------------+
     |        |--(1)- Authorization Request ->|   Resource    |
     |        |                               |     Owner     |
     |        |<-(2)-- Authorization Grant ---|               |
     |        |                               +---------------+
     |        |
     |        |                               +---------------+
     |        |--(3)-- Authorization Grant -->| Authorization |
     | Client |                               |     Server    |
     |        |<-(4)----- Access Token -------|               |
     |        |                               +---------------+
     |        |
     |        |                               +---------------+
     |        |--(5)----- Access Token ------>|    Resource   |
     |        |                               |     Server    |
     |        |<-(6)--- Protected Resource ---|               |
     +--------+                               +---------------+

As comparison, here’s how Spotify depicts the same process:

These graphs are as simple as it can be, but that doesn’t make it necessarily simple.