Protocol practice · Federation & Identity Standards

OAuth 2.0: the authorization code flow, with PKCE

Objective: You’re building Lumen Notes, which shows a user’s calendar events. Get permission to read their calendar and fetch today’s events, without ever seeing their password.

About 10 minutes · simulated, no real servers

1Ask for access
2Handle the callback
3Swap the code
4Keep the tokens
5Call the API

Where OAuth fits

Sign-inWho is this?

OpenID Connectbuilt on OAuth SAMLenterprise single sign-on KerberosWindows domains

AccessWhat may this app do?

OAuthYou are here

AccountsDoes the account exist?

SCIMjoiners, movers, leavers

Not sure? Which protocol?

OAuth at work, every day

Each of these asks you to approve a limited token, never your password.

A scheduling app reads your calendarRead access to events, nothing else.
A chat integration posts to a channelWrite access to one place, revocable any time.
A backup tool copies your filesLong-running access, renewed with a refresh token.

Step 1 of 5

Send the user to sign in

Your app builds a link to the authorization server and sends the browser there. Four values in it are yours to choose.

GET https://auth.example/authorize
  ?response_type=______
  &client_id=lumen-notes
  &redirect_uri=https://notes.example/callback
  &scope=______
  &state=______
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=______

Fill in the four blanks, then send the request.

response_type: what you want back

scope: what the feature needs

state: how you’ll know the answer is yours

code_challenge_method: how the challenge was made

Pick an answer for each blank to continue.

This step

Client: The app asking for access: here, Lumen Notes. It never sees the user’s password.
Authorization server: Signs the user in, asks for consent, and issues tokens.
Scope: What the token is allowed to do. The user sees it on the consent screen.
State: A random value the client sends and checks on the way back, so a forged callback is refused.
PKCE: Proof Key for Code Exchange. A secret verifier and its hash tie the code to the app that asked for it.

Earlier steps (0)

All terms (13)

Client: The app asking for access: here, Lumen Notes. It never sees the user’s password.
Authorization server: Signs the user in, asks for consent, and issues tokens.
Scope: What the token is allowed to do. The user sees it on the consent screen.
State: A random value the client sends and checks on the way back, so a forged callback is refused.
PKCE: Proof Key for Code Exchange. A secret verifier and its hash tie the code to the app that asked for it.
Authorization code: A one-time, short-lived ticket. Worthless without the client’s verifier.
Front channel: Messages carried by the browser, in redirects. Anything here can be seen or changed.
Back channel: A direct call from your server to the authorization server. Tokens travel here.
Redirect URI: Where the authorization server may send the user back. Registered in advance, matched exactly.
Access token: Short-lived proof of what the user allowed. Sent to the API.
Refresh token: Long-lived. Swapped for new access tokens, only ever with the authorization server.
Resource server: The API that holds the data. It checks the access token on every call.
Bearer token: Whoever holds it can use it. Protect it like a password, and keep it short-lived.