oauth-flow-test-author

Overview

OAuth 2.0 (RFC 6749) defines four grant types per datatracker.ietf.org/doc/html/rfc6749 (opens in new window):

"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 (opens in new window)) 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

1. Identify the grant(s) the client uses from the flow-selection table below.
2. Author the authorization-code + PKCE happy path (the Worked example) - the canonical flow for browser / native / mobile clients.
3. 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.
4. Run the end-to-end coverage checklist for every OAuth/OIDC client in scope.

Flow-selection decision surface

Worked example - authorization-code + PKCE (canonical)

Per RFC 6749 §4.1 (per rfc6749 (opens in new window)) the flow:

1. 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).
2. Authorization server authenticates the resource owner.
3. Server redirects back to client with the authorization code + the original state.
4. Client requests token endpoint with grant_type=authorization_code, code, redirect_uri, client_id, and PKCE code_verifier.
5. Server returns access token (+ refresh token + ID token if OIDC).

PKCE per RFC 7636 §4.2 (rfc7636 (opens in new window)):

"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:

1. Auth-code + PKCE happy path (Worked example)
2. State parameter validation (references)
3. Client-credentials happy path (if M2M; references)
4. Refresh-token rotation + reuse detection (references)
5. OIDC nonce validation (if OIDC; references)
6. Scope-downgrade handling (references)
7. Redirect-URI strict matching (references)
8. Token expiration handling (use-after-expiry returns 401)
9. Token revocation (RFC 7009) if endpoint supports it

Anti-patterns

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 (opens in new window) - RFC 6749 OAuth 2.0 Authorization Framework
• rfc7636 (opens in new window) - 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 patterns
• session-management-test-author - companion: post-auth session lifecycle