Security · Lesson 06

OAuth 2.0

OAuth 2.0 is a framework for delegated authorization — it lets a user hand a limited key to a third-party app without ever revealing their password. It is not authentication; it is a permission slip.

The valet key analogy

Some luxury cars ship with a "valet key" — it starts the engine and unlocks the door, but it will not open the glove compartment or the boot. You hand it to the parking attendant without worrying they will rifle through your belongings. You have delegated limited access, not full access.

OAuth 2.0 is the valet key for software. A user can grant a third-party app permission to read their calendar without sharing their Google password. The scope of access is bounded; the original credential is never exposed.

The four roles

Authorization-code flow with PKCE

The most secure and most common flow for apps with a user present. PKCE (Proof Key for Code Exchange, pronounced "pixie") plugs a code-interception attack by binding the authorization request to the token exchange with a secret verifier the client generates itself.

Client-credentials flow

When there is no human in the loop — a back-end service calling another back-end service — the authorization-code flow is meaningless: there is no user to show a consent screen to. Use client-credentials flow instead. The client authenticates directly with the authorization server using its own credentials (a client ID and secret) and receives an access token.

# Client-credentials token request (machine-to-machine)
POST /oauth/token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=svc_billing
&client_secret=••••••••
&scope=invoices:read invoices:write

# Response
HTTP/1.1 200 OK
{
  "access_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "invoices:read invoices:write"
}

Access tokens, refresh tokens, and scopes

Access tokens are short-lived credentials (typically 15–60 minutes) that the client presents to the resource server. They are intentionally short so that a stolen token expires quickly. Refresh tokens are longer-lived and used only at the authorization server to obtain a new access token without re-authenticating the user. Scopes define exactly which operations the token permits — calendar:read does not grant calendar:write. Requesting the minimum set of scopes is both good security practice and a good user-experience choice (consent screens are less alarming).

Under the hood: authorization-code + PKCE message by message

The flow involves seven distinct HTTP messages. Each parameter has a security purpose — knowing what each one prevents tells you immediately which attack surfaces the flow is closing.

Here is the full first redirect in raw form, with each parameter annotated:

# ① The redirect URL the client constructs (line-wrapped for readability)
GET https://auth.example.com/authorize
  ?response_type=code
  &client_id=my_app_xyz
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
  &scope=calendar%3Aread%20profile
  &state=t9kRmQ2pX8vL          // random, stored in session — CSRF protection
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256   // SHA256(code_verifier), base64url-encoded

# Client generated locally (before the redirect):
code_verifier  = "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"  // random 43–128 chars
code_challenge = base64url(SHA256(code_verifier))               // sent in ①; verifier kept secret

# ④ Token exchange — client proves it started the flow
POST https://auth.example.com/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA        // from step ③ redirect; single-use, short-lived
&redirect_uri=https://app.example.com/callback  // must match ①
&client_id=my_app_xyz
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk  // auth server computes SHA256 and matches code_challenge

# ⑤ Successful response
HTTP/1.1 200 OK
{
  "access_token":  "eyJhbGci...",
  "refresh_token": "8xLOxBtZp8...",
  "token_type":    "Bearer",
  "expires_in":    3600,
  "scope":         "calendar:read profile"
}

What each parameter prevents

How to debug & inspect it

OAuth flows fail in exactly one of three places: the authorize redirect, the callback (with an error in the query string), or the token POST. The browser's Network panel and a curl reproduction find each one quickly.

OAuth debug checklist:

1. Open Network tab, initiate the flow, and inspect the initial 302 Location header — are all required params present and correctly URL-encoded?
2. Look at the callback URL after the auth server redirects back — does it have code= and state=? Or does it have error=? Read error_description.
3. Verify your client's stored state matches what the callback returned.
4. Reproduce the POST /token in curl (with a fresh code). Read the error body — OAuth servers return structured JSON error objects.
5. Decode the returned access token (split on ., base64-decode the middle segment) to inspect exp, aud, and scope.

In production: how leading APIs authenticate

OAuth 2.0 is a framework, not a single product. Different platforms implement it with different trade-offs — some add a proprietary token type, others layer OpenID Connect on top for identity, and at least one (HubSpot) has publicly deprecated bare API keys in favour of OAuth flows and scoped private-app tokens.

Deep dive: the GitHub App JWT-to-installation-token exchange

GitHub Apps do not run through a standard user-facing OAuth consent screen. Instead, the flow has two phases. In the first phase, the App authenticates as itself: it signs a short-lived JWT (10-minute maximum) using an RSA private key registered with GitHub at app creation time. This JWT carries the App's ID in the iss claim. In the second phase, the App sends that JWT to GitHub's REST API to request an installation access token scoped to a specific repository installation. GitHub verifies the JWT signature against the registered public key, checks that the requested permissions are within the App's declared manifest, and returns a bearer token valid for up to one hour.

This pattern is OAuth-adjacent but not a textbook OAuth flow: there is no user redirect, no authorization code, and no refresh token. The security properties are similar — the signing key never travels over the wire, the issued token is short-lived, and the scope is declared in advance rather than requested at runtime. It solves the same problem as client-credentials flow (no user present) but with stronger identity assurance because the private key is what authenticates the App, not a shared secret.

The practical lesson for API designers: short-lived, scoped tokens are safer than long-lived keys regardless of the mechanism that issues them. HubSpot's 2022 API-key deprecation reflects the same conclusion — an unscoped key that never expires is a liability.

How leading APIs do it

Sources & further reading

• oauth.net — OAuth 2.0 overview
• RFC 6749 — The OAuth 2.0 Authorization Framework
• RFC 7636 — Proof Key for Code Exchange (PKCE)
• oauth.net — Implicit Flow (deprecated)