Sketio

OAuth 2.0 Authorization Code Flow with PKCE Diagram

Updated

The authorization code flow with PKCE (Proof Key for Code Exchange) is the usual way for an application to get permission to call an API on a user's behalf without handling the user's password. The user signs in at the authorization server, the client receives a short-lived authorization code, and the client exchanges that code for an access token. RFC 6749 defines the flow and RFC 7636 defines PKCE.

A sequence diagram fits this flow because the order of the messages is the point. Read each lane from top to bottom and each arrow from sender to receiver. The User lane stands for the person together with their browser, since the redirects pass through it. The OAuth 2.0 Security Best Current Practice (RFC 9700) says public clients must use PKCE, recommends it for confidential clients too, and advises against the implicit grant, so this template shows only the code flow.

Click Sign inAuthorization request + code_challengeSign in and approveRedirect with code and stateToken request + code_verifierAccess tokenAPI call + access tokenProtected dataUserClientAuthorization serverResource server

Scroll sideways to see the whole diagram

OAuth 2.0 Authorization Code Flow with PKCE Diagram. Open it in Sketio to change it.

Start from this diagram and edit it on your own board.

By continuing, you agree to the Terms of Service and Privacy Policy, including sending images of your strokes, diagram labels and similar data to providers in the United States (Cloudflare, Inc. and TypeSafe AI, Inc.) for AI conversion.

What each part does

User
The resource owner: the person who decides whether the client may reach their data. Their browser carries the redirects between the client and the authorization server. The client never sees their password.
Client
The application that wants the data: a single-page app, a mobile app or a web back end. Before it starts, it makes a random code_verifier (43 to 128 characters) and derives the code_challenge from it as the Base64url-encoded SHA-256 hash, which is the S256 method. It keeps the verifier to itself until the token request.
Authorization server
Signs the user in, asks for consent, and issues the code and the tokens. It stores the code_challenge with the code. At the token endpoint it hashes the code_verifier it receives and compares the result, and it answers invalid_grant if they differ. It also accepts a code once, and only for a redirect URI that equals one registered for the client.
Resource server
The API that holds the data. It serves a request only when it carries a valid access token, which a client sends in the Authorization header as Bearer followed by the token, and it checks that the token's scope covers the call.

How the sign-in flows

  1. The user chooses to sign in. The client makes a random code_verifier, computes the code_challenge from it, and usually makes a state value as well.
  2. The client sends the user's browser to the authorization endpoint with response_type=code, its client_id, redirect_uri, scope, state, the code_challenge and code_challenge_method=S256.
  3. The authorization server signs the user in, shows what the client is asking for, and the user approves.
  4. The server redirects the browser back to the client's redirect URI with the authorization code and the same state. The code is short-lived (RFC 6749 recommends at most 10 minutes) and works once. The client checks that the state matches the one it sent.
  5. The client calls the token endpoint directly, not through the browser, with grant_type=authorization_code, the code, the same redirect_uri, its client_id and the code_verifier. A confidential client also authenticates here.
  6. The server hashes the code_verifier and compares it with the stored code_challenge, checks the code and the redirect URI, and returns an access token, and optionally a refresh token.
  7. The client calls the API with the access token.
  8. The resource server checks the token and returns the protected data.

When to use it

Common variations

A confidential client on a server

A web back end can keep a secret, so it also authenticates when it calls the token endpoint. RFC 9700 still recommends PKCE for it, because PKCE gives strong protection against misuse and injection of authorization codes. A client secret mostly does not help against injection, since the legitimate client authenticates when it redeems the injected code.

Add refresh tokens

Add a message from the client to the authorization server with grant_type=refresh_token and one back with a new access token. RFC 9700 requires refresh tokens for public clients to be sender-constrained or rotated, so draw which one you use.

Show the error path

If the user denies consent, the authorization server redirects back with an error parameter instead of a code. Add that arrow beside the code redirect, and have the client show a sign-in failed screen.

Skip state when the server supports PKCE

RFC 9700 lets a client rely on PKCE for protection against cross-site request forgery if it has confirmed that the authorization server supports PKCE. Clients still send state for other reasons, such as returning the user to the page they started from. If your server does not support PKCE, state or nonce is required.

Register exact redirect URIs

The authorization server must compare the redirect URI in the request with the registered values by exact string matching (RFC 9700), apart from the port of a localhost redirect URI in a native app. Register each full URI and avoid wildcards.

Do not draw the implicit or password grants

The implicit grant returns the access token in the redirect itself. RFC 9700 says clients should not use it, and recommends the code flow instead. It also says the resource owner password credentials grant must not be used, because the client would handle the user's password.

Make it yours

Replace the generic names with your own client and API, then rewrite the message texts with your real endpoints, such as /authorize and /token.

Opens this diagram as a board you can edit.

By continuing, you agree to the Terms of Service and Privacy Policy, including sending images of your strokes, diagram labels and similar data to providers in the United States (Cloudflare, Inc. and TypeSafe AI, Inc.) for AI conversion.

All templates