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).

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
- Browser to App server (client)1GET /loginThe person opens the app or selects its tile in My Apps.
- App server (client) to Browser2302 to /oauth2/authorizeThe app stores state and the PKCE verifier for this browser.
- Browser to Authorization server3Authorization request with code_challenge and state
- Authorization server4Sign-in and sign-in policySSOGEN authenticates the person and checks they may use the app.
- Authorization server to Browser5302 to /auth/callback with code and state
- Browser to App server (client)6GET /auth/callback?code=...&state=...
- App server (client) to Authorization server7POST /oauth2/token with code and code_verifierA direct HTTPS call from the app server.
- Authorization server to App server (client)8Tokens: access_token, id_token, expires_in
Steps 2 to 6: the front channel
HTTP/1.1 302 FoundLocation: 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=S256SSOGEN checks, before anyone signs in:
client_idbelongs to a registered application.redirect_urimatches a registered URI character for character.response_typeiscodeandcode_challenge_methodisS256.
HTTP/1.1 302 FoundLocation: https://wiki.acme.example/auth/callback ?code=SplxlOBeZQQYbYS6WxSbIA &state=af0ifjsldkj
GET /auth/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=af0ifjsldkj HTTP/1.1Host: wiki.acme.exampleThe app checks:
stateequals the value it stored for this browser at step 2 (RFC 6749 section 10.12).- The query holds a
code, not anerror.
Steps 7 and 8: the back channel
POST /oauth2/token HTTP/1.1Host: sso.acme.exampleContent-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_wW1gFWFOEjXkSSOGEN checks:
- The code is valid, unused and was issued to
acme-wiki. redirect_uriis identical to the one in step 3 (RFC 6749 section 4.1.3).- The base64url SHA-256 of
code_verifierequals the stored challenge.
HTTP/1.1 200 OKContent-Type: application/jsonCache-Control: no-store
{ "access_token": "2YotnFZFEjr1zCsicMWpAA", "token_type": "Bearer", "expires_in": 60, "id_token": "eyJraWQiOi..."}The app checks:
- The ID token’s
issishttps://sso.acme.example. - Its
audis the client ID,acme-wiki. expires_inis 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.
code_challengeE9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM- Step 3, in the authorization request URL
code_verifierdBjftJeZ4CVP-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-configurationconfigures 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
audequal 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