Barest bones of OAuth

A third party (aka the “client”) wants to access a resource on your behalf. These three parties — the client, the resource, and you — all trust an authorization server. You are only willing to reveal your password to the authorization server.

1. The client initiates the OAuth flow

The client, who wants to access the resource on your behalf, expresses this desire by redirecting you to the authorization server. It includes URL parameters that identify itself as the party who is requesting access (client_id) and what it’s asking for (scope).

https://sso.example.com/authorize?client_id=...&scope=...

You type your password into the authorization server’s web page. The authorization server asks: “Do you want to grant the client access to these scopes?” And you click yes.

3. The client gets an access token

The authorization server generates a credential (access token) and communicates it back to the client, somehow. The token acts as a proof that you “grant” the client access to the resource. Imagine this as a tuple (you, client, resource) signed by the authorization server, and that’s basically a JWT.

How does the token make its way to the client? This part is not inevitable, and it’s up to you to pick the right grant type for the situation.

  • Maybe the authorization server just gives the token to you, trusting that you’ll pass it along to the client. This is called the “implicit” grant type.
  • Maybe the authorization server doesn’t trust you with the token (after all it’s meant for the client, not you), so it gives the token to a pigeon, who flies it directly to the client. This too is OAuth!
  • Or the authorization server could temporarily store the token and give you a random “code” to pass along to the client. The client then exchanges this code for the token. And only the client is able to do this, because the authorization server will only reveal the access token if provided the correct client_secret. This is the “authorization code” grant type.

4. The client uses the access token

The client makes requests to the resource using the access token. The resource can verify that the tuple (you, client, resource) is properly signed by the authorization server, and can treat the request accordingly.

Note: sometimes two of the parties are the same

We modeled four parties (client, resource, you, authorization server) but sometimes there are fewer players involved because some of the parties are actually the same entity. For example, the authorization server could be the same as the resource, like if a web app has you do OAuth with GitHub in order to access your GitHub repositories.

Everything else is just epicycles on these basic steps

Things like PKCE and the state parameter were added for security. They came up with OIDC because people wanted to use OAuth for authentication (who is the user?) and didn’t care about the authorization part (doing stuff on their behalf). Refresh tokens are another grant type that create longer-lived credentials. You are now ready to read RFC 6749.