go-oidc-provider

English

日本語

English

日本語

Appearance

Authorization Code + PKCE ​

The most common OIDC flow. Used by every web app, mobile app, SPA, and desktop app that logs a human in. PKCE (Proof Key for Code Exchange, RFC 7636) is mandatory for every public or native client in this library, and mandatory for all authorization-code clients under FAPI profiles. Confidential clients outside a FAPI profile can still run the older OIDC Core shape, but new deployments should send S256 everywhere.

Current behavior

Public and native clients that omit code_challenge are rejected at /authorize with invalid_request. Register these clients with PKCE and always send code_challenge_method=S256; the OP no longer issues a non-PKCE authorization code to a client that cannot authenticate at /token.

Specs referenced on this page
New to the vocabulary?
  • Authorization code — a one-time, opaque string the OP hands to the RP via a browser redirect. The RP swaps it at /token for the actual tokens.
  • PKCE ("pixie") — a small extra dance with code_verifier / code_challenge that proves "the client redeeming this code is the same one that started the flow." Stops a malicious app from stealing a redirected code. Walked through in detail below.
  • state — a random opaque value the RP sends with the authorize request and re-checks on the callback; CSRF defence for the redirect.
  • nonce — a random opaque value bound into the ID Token; replay defence at the RP.

The full sequence ​

Authorization Code + PKCE — browser to API
Authorization Code with PKCE, in four phases: the authorization request the Relying Party builds, the authentication and consent the OpenID Provider runs, the token exchange where the PKCE verifier is checked, and the resource access that follows.1 · authorization request2 · authenticate and consent3 · token exchange4 · resource accessUserbrowserRelying Partyyour web appOpenID Providergo-oidc-providerResource Serveryour APIRP builds the PKCE paircode_challenge = S256(code_verifier)1open the app2302 to the OP/authorize · code_challenge · state · nonce3GET /authorize4validate the requestredirect_uri exact match · client_id · S2565200 login page6POST credentials7authenticatepassword · passkey · step-up MFA8200 consent page9POST consent10302 back to redirect_uricode · state11GET /callback?code&state12verify statemust equal the value stored at step 213POST /tokencode · code_verifier · client auth14verify PKCES256(code_verifier) == code_challenge15200 OKaccess_token · id_token · refresh_token16verify the ID tokeniss · aud · exp · nonce17set the session cookie18GET /api/me19GET /api/meAuthorization: Bearer …20optionalintrospect · or verify the JWT locally21200 { user data }
Steps 4, 7 and 14 are the only ones the OP performs on its own; everything else is a hop between two parties. Step 14 is what PKCE buys: the code redeemed at /token is only accepted from whoever knows the verifier behind the challenge sent at step 2.

Parameter glossary ​

ParameterSent atPurpose
response_type=code/authorizeAsks for the authorization-code grant.
client_id/authorize, /tokenIdentifies the registered RP.
redirect_uri/authorize (and echoed at /token)Where the OP sends the user back. Exact match against the registered list.
scope/authorizePermissions requested. Must include openid for OIDC.
state/authorizeRandom opaque value the RP echoes on callback. CSRF defense for the redirect.
nonce/authorizeRandom value bound into the ID Token's nonce claim. Replay defense.
code_challenge/authorizeBASE64URL(SHA256(code_verifier)).
code_challenge_method/authorizeS256 (the only one this library accepts).
code/authorize responseSingle-use. This library defaults to a 60 s max-age; RFC 6749 §4.1.2 recommends a 10-minute maximum.
code_verifier/tokenThe pre-image of code_challenge. The OP recomputes the SHA-256.
grant_type=authorization_code/tokenSelects this grant.
Client auth/tokenOne of client_secret_basic, client_secret_post, private_key_jwt, or none (PKCE-only). mTLS sender constraint is separate from token-endpoint client authentication.
state vs nonce — what's the difference?

Both are random opaque values, both defend against replay-style attacks, but they protect different legs of the flow:

  • state travels on the front channel (browser query string). The RP stashes it in the user's session before redirecting and re-checks it on the callback. It defends the redirect against CSRF — an attacker can't forge a callback to your /callback and have your app accept it.
  • nonce travels in the ID Token claim. The RP stashes it in the user's session before redirecting and re-checks it after token exchange. It defends the ID Token against replay — an attacker can't reuse a stolen ID Token at a different RP, or at the same RP for a different login attempt.

Use both when your RP validates an ID Token. OIDC makes nonce mandatory for response types that include an ID Token; this library accepts response_type=code only, so hybrid and implicit response types are rejected before the authorization flow starts.

code_verifier / code_challenge / S256 — what's that?

code_verifier is a high-entropy random string the RP generates and keeps to itself. RFC 7636 §4.1 mandates 43-128 URL-safe characters.

code_challenge is what the RP sends to the OP at /authorize. With code_challenge_method=S256, it's BASE64URL(SHA-256(code_verifier)) — a one-way hash. The OP can't reverse it; only the RP can prove ownership later by sending the verifier itself.

S256 is the SHA-256-based transform; it's the only code_challenge_method this library accepts. The legacy plain method (where challenge equals verifier) provides no protection against an attacker who reads the URL, so RFC 9700 forbids it for new deployments.

redirect_uri — strict exact-match, and why

The redirect_uri on /authorize is checked byte-for-byte against the client's registered list — no tail-slash normalisation, no path-prefix matches, no wildcards. That strictness is on purpose: open-redirect bugs and "any subpath of https://app.example.com/" patterns are a well-trodden way to leak codes to attacker-controlled URLs. RFC 9700 §2.1 requires exact match, and this library enforces it. At /token, the RP must repeat the same redirect_uri it sent on /authorize; a mismatch returns invalid_grant.

response_type=code — what's that?

response_type=code asks for the authorization code flow — the OP returns a short-lived code on the redirect, and the RP swaps it at /token for the actual tokens. The alternatives (token, id_token token, code id_token, etc.) are legacy hybrid / implicit flows that OAuth 2.0 BCP (RFC 9700) discourages. This library supports code only and rejects every other response type.

PAR — what's that, and when do I need it?

PAR (Pushed Authorization Requests, RFC 9126) lets the RP POST the authorize parameters to a server-side /par endpoint first, get back a short-lived request_uri, then redirect the browser with just ?client_id=...&request_uri=.... The benefits:

  • The full request never appears in browser history, server logs, or referrer headers.
  • Tampering at the user-agent boundary is moot — only the request_uri is exposed there.
  • Required by FAPI 2.0 Baseline. Optional (but worth opting in) elsewhere.

Wire it via op.WithFeature(feature.PAR) and the discovery document advertises pushed_authorization_request_endpoint.

What PKCE prevents ​

Walk-through: the attack PKCE blocks

Without PKCE, a malicious app on the same device that controls a URI-handler for myapp:// can intercept the authorization-code redirect:

  1. User logs in on the legit RP. OP issues code=abc to myapp://callback.
  2. Malicious app intercepts the redirect (race condition or universal-link spoof) and reads code=abc.
  3. Malicious app posts code=abc to /token and gets tokens.

PKCE binds the code to a secret only the legitimate RP knows:

  1. The legit RP generates a random code_verifier and sends only SHA256(code_verifier) (the code_challenge) to /authorize.
  2. The OP stores code_challenge alongside the issued code.
  3. At /token, the OP requires code_verifier and recomputes the SHA-256.
  4. The malicious app saw the code but never saw the verifier — its /token call fails.

This works even when the RP can't store a client secret (SPA / native).

How this library enforces it ​

BehaviourWhere
code_challenge_method=plain is rejected — only S256 accepted.internal/pkce
Authorization request without code_challenge is rejected when the client's RequiresPKCE is true (default for public clients, forced for FAPI 2.0).internal/authorize
code_verifier length and char-set are validated against RFC 7636 §4.1.internal/pkce
Mismatch returns RFC 6749 §5.2 invalid_grant at /token (not /authorize).internal/tokenendpoint/authcode.go

Common errors and what they mean ​

Wire errorCauseWhere to look
invalid_request code_challenge_methodClient sent plainSend S256
invalid_request_uriPAR request_uri expired or already consumedNew PAR request
invalid_grant (at /token)code_verifier doesn't match, or code already used / expiredDon't reuse codes, regenerate
invalid_grant (at /token)The redirect_uri at /token differs from /authorizeThey must be byte-identical

Run the flow yourself ​

examples/03-fapi2 runs a FAPI 2.0 Baseline OP that demands PAR + JAR + DPoP + PKCE in one wiring. The OFCS conformance suite drives this exact sequence through ~129 modules in two FAPI plans; OFCS status shows the breakdown.