SSOGEN / Learn / Authorization Code Flow, Request by Request

Learn

Authorization Code Flow, Request by Request

The browser carries only a short-lived, single-use code, and the app server trades it for tokens in a direct POST to the token endpoint: that split is the authorization code flow (RFC 6749 section 4.1).

Cutaway of a building: a paper ticket at a public service hatch, and a sealed blue tube joining two cabinets behind the wall
Steps 7 and 8 never pass through the browser: the verifier and the tokens stay between the app server and SSOGEN.

The split into two channels is the point of the authorization code flow. Anything in a URL can end up in browser history and logs, so only the code goes there. The tokens travel in a request the browser never sees.

The PKCE pair is the example from RFC 7636 Appendix B, so the SHA-256 of the verifier gives the challenge in step 3.

The flow, message by message

A sign-in takes eight steps between three parties. The code blocks below carry the same step numbers.

Sign-in to wiki.acme.example: browser, app server, SSOGEN

  • BrowserThe person signing in
  • App server (client)wiki.acme.example
  • Authorization serverSSOGEN in this example
  1. Browser to App server (client)1GET /loginThe person opens the app or selects its tile in My Apps.
  2. App server (client) to Browser2302 to /oauth2/authorizeThe app stores state and the PKCE verifier for this browser.
  3. Browser to Authorization server3Authorization request with code_challenge and state
  4. Authorization server4Sign-in and sign-in policySSOGEN authenticates the person and checks they may use the app.
  5. Authorization server to Browser5302 to /auth/callback with code and state
  6. Browser to App server (client)6GET /auth/callback?code=...&state=...
  7. App server (client) to Authorization server7POST /oauth2/token with code and code_verifierA direct HTTPS call from the app server.
  8. Authorization server to App server (client)8Tokens: access_token, id_token, expires_in
Steps 7 and 8 never pass through the browser: the verifier and the tokens stay between the app server and SSOGEN.

Steps 2 to 6: the front channel

Steps 2 and 3: the app redirects to the authorization endpoint
HTTP/1.1 302 Found
Location: https://sso.acme.example/oauth2/authorize
?response_type=code
&client_id=acme-wiki
&redirect_uri=https%3A%2F%2Fwiki.acme.example%2Fauth%2Fcallback
&scope=openid%20profile%20email
&state=af0ifjsldkj
&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
&code_challenge_method=S256

SSOGEN checks, before anyone signs in:

  • client_id belongs to a registered application.
  • redirect_uri matches a registered URI character for character.
  • response_type is code and code_challenge_method is S256.
Steps 5 and 6: SSOGEN redirects back with the code
HTTP/1.1 302 Found
Location: https://wiki.acme.example/auth/callback
?code=SplxlOBeZQQYbYS6WxSbIA
&state=af0ifjsldkj
GET /auth/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=af0ifjsldkj HTTP/1.1
Host: wiki.acme.example

The app checks:

  • state equals the value it stored for this browser at step 2 (RFC 6749 section 10.12).
  • The query holds a code, not an error.

Steps 7 and 8: the back channel

Step 7: the app redeems the code
POST /oauth2/token HTTP/1.1
Host: sso.acme.example
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fwiki.acme.example%2Fauth%2Fcallback
&client_id=acme-wiki
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

SSOGEN checks:

  • The code is valid, unused and was issued to acme-wiki.
  • redirect_uri is identical to the one in step 3 (RFC 6749 section 4.1.3).
  • The base64url SHA-256 of code_verifier equals the stored challenge.
Step 8: the token response (RFC 6749 section 5.1 shape)
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"access_token": "2YotnFZFEjr1zCsicMWpAA",
"token_type": "Bearer",
"expires_in": 60,
"id_token": "eyJraWQiOi..."
}

The app checks:

  • The ID token’s iss is https://sso.acme.example.
  • Its aud is the client ID, acme-wiki.
  • expires_in is in seconds: 60 is SSOGEN’s access token lifetime for a person’s sign-in.

What the browser sees, and what it never sees

The front channel is every URL the browser loads; the back channel is the app server’s own HTTPS call.

Value Travels in In browser history and proxy logs
code_challenge Step 3 URL Yes. A SHA-256 hash, useless without the verifier
state Steps 3 and 5 URLs Yes. Bound to one browser session, used once
code Step 5 URL Yes. Single use, short-lived, bound to client_id and redirect_uri
code_verifier Step 7 body No
Client secret or private key JWT assertion Step 7 request No
access_token, id_token Step 8 body No. Sent with Cache-Control: no-store

Why does OAuth return a code instead of a token?

A code in the URL is safe to leak, and a token is not.

Property Code in URL Token in URL
Lifetime
Expires quickly
Until expires_in runs out
Uses
Works once
Every request until it expires
Bound to
The client and redirect URI it was issued to
Nothing: whoever reads it holds it
Can be replayed
No. Redeeming it also takes the PKCE verifier, which never appeared in a URL
Yes, by anyone who reads it

The implicit grant skipped the code and put the access token in the redirect. RFC 9700 section 2.1.2 says clients should not use it; OAuth grant types shows the grants that remain.

What is the authorization code flow with PKCE?

It is the same flow with one added proof: a hash of a fresh secret at step 3, and the secret itself at step 7. On a mismatch the server returns invalid_grant (RFC 7636 section 4.6). The code verifier and challenge have their own page.

The PKCE pair, RFC 7636 Appendix B
code_challenge
E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
Step 3, in the authorization request URL
code_verifier
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
Step 7, in the token request body

When it fails: the error at each step

The error tells you which step failed. Quoted messages are the ones SSOGEN shows.

Step What you see Usual cause
3 An SSOGEN page, “Sign-in refused”: “The application sent a sign-in request this service cannot accept.” No redirect back client_id or redirect_uri does not match the registration, or code_challenge with S256 is missing. RFC 6749 section 4.1.2.1 forbids redirecting to an unverified URI
4 to 5 The browser returns with error=access_denied The person is not assigned, the app is not active, or the sign-in policy denies them. Run Test on the application as that person
6 The app reports a state mismatch The callback did not come from a sign-in this browser started, or the stored state was lost
7 invalid_grant The code expired, was already used or belongs to another client; redirect_uri differs from step 3; or the verifier does not match the challenge
7 invalid_client The app’s token endpoint authentication method differs from Client authentication in the Sign-in tokens tab, for example a secret sent for a public client
8 The app rejects the issuer or audience Use the Issuer from the Integration tab, and expect aud to equal the client ID

Running the flow against SSOGEN

SSOGEN runs the authorization code flow with S256 PKCE on every OpenID Connect sign-in. Most libraries need only the discovery URL, the client ID, the redirect URI and the scopes.

  • Discovery: one URL. https://sso.acme.example/.well-known/openid-configuration configures the endpoints and lists "code_challenge_methods_supported":["S256"].
  • Response type: code. SSOGEN signs people in with the authorization code flow only, as RFC 9700 recommends.
  • Redirect URIs: exact match. Up to 16, each starting with https://, no wildcards. A trailing slash makes a different URI.
  • Client authentication: public by default. PKCE alone at first; a server application adds a private key JWT or a client secret (client secret basic).
  • Access tokens: 60 seconds. SSOGEN’s lifetime for a person’s sign-in. Refresh tokens are optional, for this flow only.
  • Scopes: openid profile email. The ID token carries aud equal to the client ID.

The full setup is in register an OpenID Connect application. The product view is on the SSOGEN OpenID Connect provider page.

Questions people ask

Is the authorization code flow OAuth or OpenID Connect?

Both: it is an OAuth 2.0 grant, and OpenID Connect builds its main sign-in flow on top of it. Add the openid scope to step 3 and the token response at step 8 also carries an ID token, which says who signed in. What changes is in how OpenID Connect extends OAuth, including the ID token checks.

Should a single-page app use this flow?

Yes, with PKCE. A single-page app cannot keep a secret, so RFC 9700 section 2.1.1 requires PKCE for it as a public client. The verifier then protects the code its JavaScript redeems at step 7. A backend for frontend (BFF) can instead run the flow as a confidential client and keep the tokens server-side (RFC 10017 section 6.1).

How long is an authorization code valid?

RFC 6749 section 4.1.2 recommends a maximum of 10 minutes, and a code works only once. A second use must be refused, and the server should revoke the tokens already issued from that code. An expired or reused code gets invalid_grant at step 7 (RFC 6749 section 5.2).

Sources, all read 2026-11-18: RFC 6749, OAuth 2.0 (sections 4.1 to 4.1.4, 5.1, 5.2, 10.12), RFC 7636, PKCE (section 4.6, Appendix B), RFC 9700, OAuth 2.0 Security Best Current Practice (sections 2.1.1, 2.1.2), OpenID Connect Core 1.0 (section 3.1.3.3), RFC 10017 (section 6.1).

Updated