LAB 04: OIDC Flows End to End
with Authorization Code and PKCE

Lab Metadata

Lab Title and Description

The Flow the Web Runs On: Authorization Code with PKCE, Step by Step

In Lab 02 you obtained tokens with a single curl command using the password grant, and the lab warned you twice that no real application should work that way. This lab makes good on that warning. The password grant hands the user's credentials to the application, which is the exact anti pattern the whole IdP model exists to remove; it also bypasses MFA, adaptive policy, and the IdP's own login page. Every current standard, OAuth 2.1 and the OAuth Security Best Current Practice, tells you to delete it.

The replacement is the authorization code flow with PKCE, and it is what sits behind essentially every browser and mobile login you use: your bank, your email, your government tax account. The application never sees the password. Instead it sends the user to the IdP, the IdP authenticates them on its own hardened page and hands back a short lived, single use authorization code through the browser, and the application then exchanges that code for tokens on a back channel the browser never sees. PKCE, pronounced pixy, binds the code to the specific client instance that started the flow, so a code stolen in transit cannot be redeemed by anyone else.

You will run this flow the hard way first, constructing each URL and cryptographic value by hand with curl and openssl so nothing is hidden, capturing the code in your browser's address bar, and exchanging it at the token endpoint. Then you will run it the real way, with a tiny local application that completes the round trip, and you will attack it: replay a code, tamper a PKCE verifier, and watch the IdP refuse. By the end you will contrast this flow directly against the SAML assertion flow from Lab 03, two protocols solving one problem, and know exactly why the industry standardised on this one for new build. Estimated completion time is 3 to 3.5 hours.

Prerequisites

3.1 Prior labs required

# Bring the track containers up
docker start ib-openldap ib-keycloak ib-phpldapadmin

# Confirm the northgate realm and its token endpoint answer
curl -s http://localhost:8081/realms/northgate/.well-known/openid-configuration \
  | jq -r '.authorization_endpoint, .token_endpoint'
# Expected: two URLs under /realms/northgate/protocol/openid-connect/

3.2 System requirements

3.3 Required tools and versions

3.4 Verification of tools

openssl version
python3 --version
# Expected: OpenSSL 3.x (or 1.1.1) and Python 3.8+

Real World Problem Statement

This lab solves the problem hiding inside Lab 02's convenience: the application must never handle the password, and the mechanism that removes it must survive a hostile network. The password grant fails both tests, because the credential passes through the application, and any flow that returns tokens directly through the browser exposes them to redirect interception, malicious browser extensions, and referrer leakage. These are not theoretical: the authorization code interception attack on mobile and single page applications is exactly what PKCE was published to stop, and it is why OAuth 2.1 removes the implicit flow and the password grant from the specification entirely.

The authorization code flow with PKCE is the answer the entire industry converged on. Credentials stay at the IdP. What crosses the browser is a single use code that is useless on its own, because redeeming it requires proof of possession of a secret the legitimate client generated and never transmitted. This is the default for web applications, the mandatory pattern for mobile and single page applications that cannot hold a static secret, and the flow every modern SDK implements by default. A senior IAM architect signs off application onboarding against this pattern and rejects designs that deviate from it.

Why it matters, across four dimensions

Concrete scenario

Northgate Financial's security review of the Lab 02 HR portal integration returns one blocking finding: the portal uses the resource owner password grant, which is prohibited by the corporate authentication standard and by OAuth 2.1. The remediation is mandatory before go live. Your task in this lab is to re-platform the HR portal onto the authorization code flow with PKCE, prove the round trip works with a real redirect based login, demonstrate that credentials never touch the application, enable refresh token rotation so long sessions do not depend on long lived tokens, and produce captured evidence of the code exchange and its security properties for the reviewer to sign off.

Skills Mapped to Production Solutions

Architecture Overview

Component breakdown

Data flow

1. The client builds a challenge and redirects: the HR portal generates a random PKCE verifier, hashes it to a challenge, stores the verifier locally, and sends the browser to /authorize carrying the challenge, a random state, and its redirect URI. Why: the challenge commits the client to a secret it has not revealed, so the code that follows can only be redeemed by whoever holds the matching verifier.
2. The IdP authenticates the user: Keycloak shows its login page and validates the password by LDAP bind. Why: credentials reach the IdP alone, which is the entire security case for the flow, and it is where MFA in the next lab attaches.
3. The IdP returns a code through the browser: Keycloak redirects back to the client's registered URI with a single use authorization code and the echoed state. Why: the code is inert in transit; unlike a token, capturing it grants nothing without the verifier.
4. The client exchanges the code on the back channel: the HR portal calls /token directly, presenting the code, the original verifier, and its client secret. Why: this server to server call never touches the browser, so the tokens are never exposed to the front channel.
5. The IdP verifies and issues tokens: Keycloak confirms the client secret, hashes the presented verifier, matches it to the stored challenge, checks the redirect URI, and only then returns the ID, access, and refresh tokens. Why: three independent bindings, secret, PKCE, and redirect URI, must all hold, which is what makes the flow robust against interception.

Security considerations

Step by Step Implementation

# Work in a scratch directory
mkdir -p ~/ib-sia-04 && cd ~/ib-sia-04

# VERIFIER: 32 random bytes, base64url encoded, no padding.
# This is the secret the client keeps and never sends in the front channel.
VERIFIER=$(openssl rand -base64 96 | tr -d '\n' | tr '+/' '-_' | tr -d '=' | cut -c1-64)
echo "$VERIFIER" > verifier.txt
echo "verifier: $VERIFIER"

# CHALLENGE: SHA-256 of the verifier, raw binary, base64url encoded, no pad.
# This is what the client sends to /authorize.
CHALLENGE=$(printf '%s' "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 | tr -d '\n' | tr '+/' '-_' | tr -d '=')
echo "$CHALLENGE" > challenge.txt
echo "challenge: $CHALLENGE"

# STATE: random anti-CSRF value the IdP will echo back unchanged
STATE=$(openssl rand -hex 16)
echo "$STATE" > state.txt
echo "state: $STATE"

# Build the authorization request. response_type=code selects the
# authorization code flow; the challenge commits us to the verifier.
AUTH_URL="http://localhost:8081/realms/northgate/protocol/openid-connect/auth"
AUTH_URL="$AUTH_URL?client_id=hr-portal"
AUTH_URL="$AUTH_URL&response_type=code"
AUTH_URL="$AUTH_URL&scope=openid%20profile%20email"
AUTH_URL="$AUTH_URL&redirect_uri=http://localhost:9090/callback"
AUTH_URL="$AUTH_URL&code_challenge=$(cat challenge.txt)"
AUTH_URL="$AUTH_URL&code_challenge_method=S256"
AUTH_URL="$AUTH_URL&state=$(cat state.txt)"

echo "$AUTH_URL"
# Copy the printed URL into a private browser window.

# Extract the code from the callback URL you copied.
CALLBACK='PASTE_THE_FULL_CALLBACK_URL_HERE'
CODE=$(echo "$CALLBACK" | grep -oP 'code=\K[^&]+')
echo "code: $CODE"

# Exchange it. Note all three proofs travel here on the BACK CHANNEL:
#   client_secret  proves which client (confidential)
#   code_verifier  proves possession of the PKCE secret
#   redirect_uri   must match the one used at /authorize exactly
curl -s -X POST http://localhost:8081/realms/northgate/protocol/openid-connect/token \
  -d grant_type=authorization_code \
  -d client_id=hr-portal \
  -d client_secret="<CLIENT_SECRET>" \
  -d code="$CODE" \
  -d redirect_uri=http://localhost:9090/callback \
  -d code_verifier="$(cat verifier.txt)" | jq . | tee tokens.json

cat > ~/ib-sia-04/app.py << 'EOF'
import http.server, urllib.parse, urllib.request, json, secrets, hashlib, base64, webbrowser

KC = "http://localhost:8081/realms/northgate/protocol/openid-connect"
CLIENT_ID = "hr-portal"
CLIENT_SECRET = "<CLIENT_SECRET>"   # paste the hr-portal secret
REDIRECT = "http://localhost:9090/callback"

def b64url(b): return base64.urlsafe_b64encode(b).rstrip(b"=").decode()
verifier = b64url(secrets.token_bytes(48))
challenge = b64url(hashlib.sha256(verifier.encode()).digest())
state = secrets.token_hex(16)

auth = (f"{KC}/auth?client_id={CLIENT_ID}&response_type=code"
        f"&scope=openid%20profile%20email&redirect_uri={REDIRECT}"
        f"&code_challenge={challenge}&code_challenge_method=S256&state={state}")

class H(http.server.BaseHTTPRequestHandler):
    def do_GET(self):
        q = urllib.parse.urlparse(self.path)
        if not q.path.startswith("/callback"):
            self.send_response(404); self.end_headers(); return
        p = urllib.parse.parse_qs(q.query)
        if p.get("state", [""])[0] != state:
            self.send_response(400); self.end_headers()
            self.wfile.write(b"STATE MISMATCH - possible CSRF, aborted"); return
        data = urllib.parse.urlencode({
            "grant_type": "authorization_code", "client_id": CLIENT_ID,
            "client_secret": CLIENT_SECRET, "code": p["code"][0],
            "redirect_uri": REDIRECT, "code_verifier": verifier}).encode()
        tok = json.load(urllib.request.urlopen(f"{KC}/token", data))
        claims = json.loads(base64.urlsafe_b64decode(
            tok["id_token"].split(".")[1] + "=="))
        self.send_response(200); self.send_header("Content-Type","text/html"); self.end_headers()
        self.wfile.write(b"
Logged in via authorization code + PKCE
")
        self.wfile.write(json.dumps(
            {k: claims[k] for k in ("preferred_username","email","name","iss","aud")
             if k in claims}, indent=2).encode())
        self.wfile.write(b"
")
    def log_message(self, *a): pass

print("Open this URL to begin:\n" + auth)
webbrowser.open(auth)
http.server.HTTPServer(("localhost", 9090), H).serve_forever()
EOF

# Paste your hr-portal client secret into CLIENT_SECRET, then run:
cd ~/ib-sia-04 && python3 app.py

cd ~/ib-sia-04

# Capture the first refresh token from your Phase 3 exchange
RT1=$(jq -r '.refresh_token' tokens.json)

# USE 1: exchange it for new tokens. Note a NEW refresh token comes back.
curl -s -X POST http://localhost:8081/realms/northgate/protocol/openid-connect/token \
  -d grant_type=refresh_token -d client_id=hr-portal \
  -d client_secret="<CLIENT_SECRET>" -d refresh_token="$RT1" \
  | jq -r '.refresh_token' > rt2.txt
echo "got a new refresh token: $(cut -c1-24 rt2.txt)..."

# USE 2 (the attack): try to reuse the ORIGINAL refresh token again.
curl -s -X POST http://localhost:8081/realms/northgate/protocol/openid-connect/token \
  -d grant_type=refresh_token -d client_id=hr-portal \
  -d client_secret="<CLIENT_SECRET>" -d refresh_token="$RT1" | jq .
# Expected: {"error":"invalid_grant","error_description":"Token is not active"}

# And the rotation cascade: the NEW token is now also dead, because reuse
# of the old one triggered revocation of the whole chain.
curl -s -X POST http://localhost:8081/realms/northgate/protocol/openid-connect/token \
  -d grant_type=refresh_token -d client_id=hr-portal \
  -d client_secret="<CLIENT_SECRET>" -d refresh_token="$(cat rt2.txt)" | jq .
# Expected: invalid_grant as well. The session is gone; the user re-authenticates.

Testing and Validation

End to end scenario: the remediated HR portal

This confirms the security review finding is closed and the replacement flow holds.

# STAGE 1: the prohibited flow is gone. Password grant must be refused.
curl -s -X POST http://localhost:8081/realms/northgate/protocol/openid-connect/token \
  -d grant_type=password -d client_id=hr-portal \
  -d client_secret="<CLIENT_SECRET>" \
  -d username=asmith -d password="<USER_PASSWORD>" | jq -r '.error'
# Expected: unauthorized_client

# STAGE 2: the approved flow works, via app.py (Phase 4). Log in as asmith.
# Expected: the app shows her claims; the app never saw her password.

# STAGE 3: PKCE is mandatory. Attempt /authorize WITHOUT a challenge.
curl -s -o /dev/null -w "%{http_code} %{redirect_url}\n" \
  "http://localhost:8081/realms/northgate/protocol/openid-connect/auth?client_id=hr-portal&response_type=code&scope=openid&redirect_uri=http://localhost:9090/callback&state=x"
# Expected: a redirect back carrying error=invalid_request (missing
# code_challenge), because the client requires PKCE.

Negative tests

# TEST N1: intercepted code without the verifier is worthless.
# Get a fresh code (Phase 2), then exchange it with a WRONG verifier:
curl -s -X POST http://localhost:8081/realms/northgate/protocol/openid-connect/token \
  -d grant_type=authorization_code -d client_id=hr-portal \
  -d client_secret="<CLIENT_SECRET>" -d code="$CODE" \
  -d redirect_uri=http://localhost:9090/callback \
  -d code_verifier="wrong-verifier-wrong-verifier-wrong-verifier-1234567" | jq .
# Expected: invalid_grant, "PKCE verification failed". THIS is the attack
# PKCE defeats: an attacker who sniffed the code cannot redeem it.

# TEST N2: a code is single use. Redeem a valid code correctly once
# (it succeeds), then run the SAME exchange again.
# Expected on the second run: invalid_grant, "Code not valid". Replay dead.

# TEST N3: redirect_uri must match the authorization request.
# With a fresh code, exchange using a different redirect_uri:
curl -s -X POST http://localhost:8081/realms/northgate/protocol/openid-connect/token \
  -d grant_type=authorization_code -d client_id=hr-portal \
  -d client_secret="<CLIENT_SECRET>" -d code="$CODE" \
  -d redirect_uri=http://localhost:9090/evil \
  -d code_verifier="$(cat verifier.txt)" | jq -r '.error_description'
# Expected: an "Incorrect redirect_uri" style error. The URI is bound to
# the code; an attacker cannot divert the exchange to their own endpoint.

# TEST N4: confidential client still needs its secret.
# Exchange a fresh code with NO client_secret:
curl -s -X POST http://localhost:8081/realms/northgate/protocol/openid-connect/token \
  -d grant_type=authorization_code -d client_id=hr-portal -d code="$CODE" \
  -d redirect_uri=http://localhost:9090/callback \
  -d code_verifier="$(cat verifier.txt)" | jq -r '.error'
# Expected: invalid_client. Two independent proofs guard the exchange.

Protocol comparison: this flow versus the SAML flow from Lab 03

Having captured both a JWT and an assertion by hand, you can now answer the OIDC or SAML interview question from evidence rather than opinion: the same trust problem, one solved with a signed document, the other with a bound single use code, and the industry defaulting to the second for anything built this decade.

Common failure modes and solutions

Security Analysis

What makes this implementation secure

• The application never receives the user's password: it is entered only at the IdP, and Stage 1 proves the password grant is now refused.
• PKCE S256 binds the authorization code to the client instance: test N1 proved a captured code cannot be redeemed without the verifier, defeating the interception attack the flow exists to stop.
• Multiple independent bindings guard the token exchange: client secret (N4), PKCE verifier (N1), redirect URI (N3), and single use codes (N2) must all hold.
• State is generated, echoed, and checked, defending against CSRF, and nonce ties the ID token to the originating request.
• Refresh token rotation with reuse detection turns a leaked refresh token into a detected, self limiting incident rather than a silent long lived compromise.
• Tokens are short lived, audience scoped, and RS256 signed, consistent with the token discipline established in Lab 02.

What is intentionally simplified for the lab

• Everything runs over HTTP on localhost; a real deployment mandates TLS, without which the back channel and code are exposed.
• The demo application hand rolls the flow for teaching; production uses vetted libraries or a proxy.
• The client secret is a static shared secret; stronger client authentication (private_key_jwt, mTLS) is not yet used.
• No Pushed Authorization Requests, no DPoP or other sender constraining, no MFA in the login step yet.
• Access token lifetime and session timeouts are left at defaults rather than tuned to a risk model.

Production hardening recommendations

Cleanup Instructions

Option A: pause the lab, keep everything (recommended)

# Stop app.py with Ctrl C in its terminal, then:
docker stop ib-keycloak ib-openldap ib-phpldapadmin
# Resume later with:
docker start ib-openldap ib-keycloak ib-phpldapadmin

Option B: revert the Lab 04 client changes, keep the environment

# The flow changes live in Keycloak config. To revert for a fresh run:
#   Clients, hr-portal, Settings: leave Standard flow ON (it is correct),
#   and decide whether to re-disable Direct access grants (recommended OFF).
#   Realm settings, Sessions: Revoke refresh token can stay ON (good practice).

# Remove local scratch files, which contain a real code and tokens:
rm -rf ~/ib-sia-04

Recommended Learning Links

• RFC 6749: The OAuth 2.0 Authorization Framework
• RFC 7636: Proof Key for Code Exchange (PKCE)
• RFC 9700: Best Current Practice for OAuth 2.0 Security
• The OAuth 2.1 Authorization Framework (draft) (why implicit and password grants are removed)
• OpenID Connect Core 1.0 (authorization code flow, nonce, ID token)
• RFC 9126: Pushed Authorization Requests (PAR)
• Keycloak Server Administration Guide: OIDC clients and flows
• oauth.net PKCE overview (concise practitioner explanation)

Portfolio Publishing Guide: Evidence of a Flow You Drove and Broke

Lab 04 produces two portfolio assets most candidates lack: a from scratch, manual walkthrough of the flow every SDK hides, and a set of negative tests proving you understand why it is safe. The forty line application is a bonus artefact that reads as competence, provided you sanitise it.

12.1 Prepare sanitised artefacts

cd ~/identity-bytes-architect-labs
mkdir -p lab-04-oidc-pkce/{docs,src,evidence,screenshots}

# Publish the demo app with the secret removed
sed 's/CLIENT_SECRET = ".*"/CLIENT_SECRET = "<set-your-own>"/' \
  ~/ib-sia-04/app.py > lab-04-oidc-pkce/src/app.py

# Confirm no secret survived. Expected: the placeholder line only.
grep CLIENT_SECRET lab-04-oidc-pkce/src/app.py

# Save a REDACTED token response as evidence of the exchange shape.
# Blank the actual token strings, keep the structure.
jq '.access_token="REDACTED" | .refresh_token="REDACTED" | .id_token="REDACTED"' \
  ~/ib-sia-04/tokens.json > lab-04-oidc-pkce/evidence/token-response.redacted.json

12.2 Add Lab 04 to the repository and push

cat > lab-04-oidc-pkce/README.md << 'EOF'
# Lab 04: OIDC Flows End to End with Authorization Code and PKCE

Part of my Identity Bytes Senior IAM Architect lab series (IB-SIA-04).
Remediates the Lab 02 HR portal, which used the prohibited password grant,
by re-platforming it onto the authorization code flow with PKCE.

## Problem this solves
Applications must never handle the user's password, and the flow that
removes it must survive a hostile network. The authorization code flow
with PKCE keeps credentials at the IdP and makes an intercepted code
useless without the client's secret verifier.

## What I built
- Reconfigured the confidential client: standard flow only, password
  grant disabled, PKCE (S256) required
- Drove the full flow by hand: generated the PKCE verifier and challenge
  with openssl, built the authorization URL, captured the code, and
  exchanged it on the back channel
- A minimal ~40 line Python application that completes the round trip
  the way an SDK does, including state checking
- Refresh token rotation with reuse detection

## What I broke on purpose
- Exchanged a valid code with a wrong PKCE verifier: rejected (this is
  the interception attack PKCE defeats)
- Replayed a used code: rejected (single use)
- Diverted the exchange to a different redirect_uri: rejected
- Reused a rotated refresh token: whole session revoked

## OIDC vs SAML
Having captured a JWT here and a SAML assertion in Lab 03, the README
includes a side by side of sub vs NameID, aud vs AudienceRestriction,
and where each protocol fits today.

## Skills demonstrated
OAuth 2.1 / OIDC flow internals, PKCE, public vs confidential clients,
state and nonce, refresh token rotation, and evidence based protocol
selection.

Full guide: docs/IB-SIA-04-oidc-pkce.html
Demo app: src/app.py   Redacted evidence: evidence/token-response.redacted.json
EOF

cp <PATH_TO>/IB-SIA-04-oidc-pkce.html lab-04-oidc-pkce/docs/
git add .
git commit -m "Lab 04: authorization code + PKCE, manual flow, demo app, refresh rotation, negative tests"
git push
# Track index: | 04 | OIDC authorization code + PKCE, refresh rotation | Complete |

12.3 Share it on LinkedIn

Attach a screenshot of the terminal moment where a captured code is refused because the verifier is wrong, the single clearest picture of why PKCE matters. GitHub link in the first comment. A draft in the Identity Bytes style:

Same cadence: Tuesday to Thursday morning UK time, replies within two hours, hashtags at the end (#IAM #OAuth #OIDC #PKCE #CyberSecurity), and a comment linking the earlier labs.

12.4 Interview leverage from this lab

This lab evidences the token strategy and OIDC lines of the target role, and it hands you the strongest possible answer to "walk me through the authorization code flow", because you have driven every step from the command line and can explain not just the happy path but what each parameter defends against. When the interviewer asks why PKCE exists or how refresh rotation detects theft, you are describing experiments you ran, not paragraphs you read.