Authorization code with PKCE

This is the flow for web applications, desktop applications and single-page applications. Everything with a browser uses it, whether or not it can keep a secret.

The shape#

1. Generate a verifier and a challenge

   A random string, and its SHA-256, base64url encoded.

2. Send the browser to the authorize endpoint

   With the challenge, a redirect URI, a state value and your scopes.

3. The person signs in and consents

   On CEagle accounts, not in your application.

4. They come back with a code

   To your redirect URI, along with the state you sent.

5. Exchange the code for tokens

   Server to server, with the verifier.

Step 1: the verifier#

VERIFIER=$(openssl rand -base64 60 | tr -d '\n=+/' | cut -c1-64)
CHALLENGE=$(printf '%s' "$VERIFIER" | openssl dgst -binary -sha256 | openssl base64 | tr '+/' '-_' | tr -d '=')

Keep the verifier in the session. Send only the challenge.

Step 2: authorize#

https://account.ceagle.cc/oauth2/authorize
  ?response_type=code
  &client_id=CLIENT_ID
  &redirect_uri=https%3A%2F%2Fsnake.example%2Fcallback
  &scope=openid%20profile%20email%20offline_access
  &state=RANDOM
  &nonce=RANDOM
  &code_challenge=CHALLENGE
  &code_challenge_method=S256

How errors come back#

This endpoint answers with a redirect, never with JSON.

An error that can be attributed to a registered redirect URI is delivered there, as error and error_description. One that cannot — an unknown client, an unregistered redirect URI — is rendered as a page instead, because sending it onward would turn the authorization endpoint into an open redirector.

Step 3: exchange#

Form-encoded, never JSON.

curl -s -X POST https://account.ceagle.cc/oauth2/token \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri=https://snake.example/callback \
  -d client_id="$CLIENT_ID" \
  -d code_verifier="$VERIFIER"

curl -s -X POST https://account.ceagle.cc/oauth2/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri=https://snake.example/callback \
  -d code_verifier="$VERIFIER"

{
  "access_token": "…",
  "token_type": "Bearer",
  "expires_in": 600,
  "refresh_token": "…",
  "id_token": "…",
  "scope": "openid profile email offline_access"
}

Codes are single use and short-lived. A second exchange answers invalid_grant.

Step 4: use it#

curl -s https://account.ceagle.cc/oauth2/userinfo \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Claims are filtered to what the token's scopes allow. sub is always there; preferred_username and name need profile; email and email_verified need email.

A checklist#

Common errors#