oauth-flow-test-author
Overview
OAuth 2.0 (RFC 6749) defines four grant types per datatracker.ietf.org/doc/html/rfc6749:
"1. Authorization Code (§1.3.1): The authorization code is
obtained by using an authorization server as an intermediary
between the client and resource owner.
2. Implicit (§1.3.2): The implicit grant is a simplified
authorization code flow optimized for clients implemented in a
browser using a scripting language such as JavaScript.
3. Resource Owner Password Credentials (§1.3.3): The resource
owner password credentials (i.e., username and password) can
be used directly as an authorization grant to obtain an access
token.
4. Client Credentials (§1.3.4): The client credentials can be
used as an authorization grant when the authorization scope is
limited to protected resources under the control of the
client."
Per RFC 9700 (OAuth 2.0 Security Best Current Practice, March 2025):
- Implicit grant is deprecated.
- Resource Owner Password Credentials grant is deprecated.
- Authorization Code with PKCE (per datatracker.ietf.org/doc/html/rfc7636)
is the canonical flow for all clients, public or confidential.
This skill is the per-flow test recipe. The canonical authorization-code +
PKCE flow is authored end to end in the Worked example below; the
less-common grants and negative cases live in
references/per-flow-test-recipes.md.
When to use
- Authoring tests for an OAuth 2.0 / OIDC client (web, mobile,
SPA, M2M).
- Reviewing PRs that touch auth-flow code.
- The team needs flow-coverage independent of the IdP choice
(Keycloak / Auth0 / Okta / mock).
How to use
- Identify the grant(s) the client uses from the flow-selection table below.
- Author the authorization-code + PKCE happy path (the Worked example) - the canonical flow for browser / native / mobile clients.
- Add the negative and secondary-grant tests each client needs (state CSRF, client-credentials, refresh-token rotation, OIDC nonce, scope-downgrade, redirect-URI) from references/per-flow-test-recipes.md.
- Run the end-to-end coverage checklist for every OAuth/OIDC client in scope.
Flow-selection decision surface
| Client type | Grant to test | Required tests | Recipe |
|---|
| Browser / SPA / native / mobile | Authorization Code + PKCE (S256) | Happy path + state CSRF + redirect-URI + (OIDC nonce if openid) | Worked example + references |
| Machine-to-machine (M2M) | Client Credentials | Happy path; assert no refresh_token | references |
| Any client holding a refresh token | Refresh Token | Rotation + reuse-detection | references |
| Any OIDC client | Authorization Code + ID Token | Nonce match + scope-downgrade | Worked example + references |
| Legacy Implicit / RO-Password | (none - deprecated per RFC 9700) | Migrate to Auth Code + PKCE | - |
Worked example - authorization-code + PKCE (canonical)
Per RFC 6749 §4.1 (per rfc6749) the flow:
- Client directs resource owner to authorization endpoint with
client_id, redirect_uri, response_type=code, scope,
state (RECOMMENDED for CSRF defense per §10.12), nonce
(OIDC), and PKCE params (code_challenge + code_challenge_method).
- Authorization server authenticates the resource owner.
- Server redirects back to client with the authorization code +
the original
state.
- Client requests token endpoint with
grant_type=authorization_code,
code, redirect_uri, client_id, and PKCE code_verifier.
- Server returns access token (+ refresh token + ID token if OIDC).
PKCE per RFC 7636 §4.2 (rfc7636):
"Two methods are defined:
- plain:
code_challenge = code_verifier
- S256:
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))"
Always use S256; plain defeats the purpose of PKCE.
Test pattern (Python with requests + Playwright for browser flow):
import secrets, hashlib, base64, requests
from urllib.parse import urlparse, parse_qs
def make_pkce_pair():
verifier = secrets.token_urlsafe(64)
challenge = base64.urlsafe_b64encode(
hashlib.sha256(verifier.encode("ascii")).digest()
).rstrip(b"=").decode("ascii")
return verifier, challenge
def test_authz_code_pkce_flow(idp_url, client_id, redirect_uri, browser):
verifier, challenge = make_pkce_pair()
state = secrets.token_urlsafe(32)
nonce = secrets.token_urlsafe(32)
# Step 1: redirect to authorize endpoint
authz_url = (
f"{idp_url}/authorize?"
f"client_id={client_id}&response_type=code&"
f"redirect_uri={redirect_uri}&scope=openid+profile&"
f"state={state}&nonce={nonce}&"
f"code_challenge={challenge}&code_challenge_method=S256"
)
# Browser interaction (simulated via Playwright):
page = browser.new_page()
page.goto(authz_url)
page.fill("#username", "alice")
page.fill("#password", "alicepass")
page.click("#submit")
# Step 3: redirect lands on redirect_uri with code + state
redirected_to = page.url
parsed = urlparse(redirected_to)
query = parse_qs(parsed.query)
assert query["state"][0] == state # RFC §10.12 CSRF defense
code = query["code"][0]
# Step 4: token endpoint
token_response = requests.post(
f"{idp_url}/token",
data={
"grant_type": "authorization_code",
"code": code,
"redirect_uri": redirect_uri,
"client_id": client_id,
"code_verifier": verifier, # PKCE proof
},
)
assert token_response.status_code == 200
body = token_response.json()
assert "access_token" in body
assert body["token_type"] == "Bearer"
The happy path asserts the returned state matches; the negative
state-mismatch test, plus the client-credentials, refresh-rotation,
OIDC-nonce, scope-downgrade, and redirect-URI recipes, are in
references/per-flow-test-recipes.md.
End-to-end coverage checklist
For each OAuth/OIDC client in scope:
- Auth-code + PKCE happy path (Worked example)
- State parameter validation (references)
- Client-credentials happy path (if M2M; references)
- Refresh-token rotation + reuse detection (references)
- OIDC nonce validation (if OIDC; references)
- Scope-downgrade handling (references)
- Redirect-URI strict matching (references)
- Token expiration handling (use-after-expiry returns 401)
- Token revocation (RFC 7009) if endpoint supports it
Anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|
Use PKCE plain method | Defeats PKCE; RFC 7636 §4.2 specifies S256 as recommended | Always S256 (Worked example) |
| Skip state validation in the callback handler | CSRF vulnerable | State CSRF negative test (references) |
| Hardcode redirect_uri prefix matching | Substring match accepts evil URIs | Strict equality (references) |
| Test only the happy path | Negative cases (mismatched state, invalid PKCE, expired token) untested | Negative tests (references) |
| Use Implicit or RO-Password grants in new code | Deprecated per RFC 9700 | Auth Code + PKCE |
Limitations
- This is a build-an-X workflow. Tests use the application's HTTP
client + browser automation library; this skill is the per-flow
checklist.
- IdP-specific quirks (audience, custom auth servers, sign-in
policies) layer on top - see
keycloak-tests,
auth0-tests,
okta-tests for IdP-specific patterns.
- RFC 9700 supersedes earlier security BCPs; pin to the latest
version when authoring tests.
- OAuth 2.1 (in-progress) consolidates the deprecations from RFC
9700; prefer 2.1 patterns when the IdP supports them.
References
- rfc6749 - RFC 6749 OAuth 2.0 Authorization Framework
- rfc7636 - RFC 7636 PKCE
- IETF RFC 9700 - OAuth 2.0 Security Best Current Practice (March 2025)
- IETF RFC 7009 - OAuth 2.0 Token Revocation
- openid.net/specs/openid-connect-core-1_0.html - OIDC Core spec
- references/per-flow-test-recipes.md - state CSRF, client-credentials, refresh-token rotation, OIDC nonce, scope-downgrade, and redirect-URI recipes.
keycloak-tests,
auth0-tests,
okta-tests - IdP-specific patternssession-management-test-author - companion: post-auth session lifecycle