Testing OAuth 2.0 Flows End-to-End: A Practical Guide
OAuth 2.0 is everywhere. Your app almost certainly uses it—to let users sign in with Google, to call a third-party API, to issue access tokens to mobile clients. And almost every auth-related security incident traces back to a flow that was never properly tested.
This guide walks through what end-to-end OAuth 2.0 testing actually looks like: which flows to test, what to assert, and where things break.
Understanding the OAuth 2.0 Flows
Before writing tests, you need to understand what you're testing. OAuth 2.0 defines four main grant types:
Authorization Code — the standard flow for web apps. User logs in, authorization server redirects back with a code, your server exchanges it for tokens. Most common, most attack surface.
Client Credentials — machine-to-machine. No user involved. Your service authenticates directly using a client ID and secret. Used for backend-to-backend API calls.
Implicit — deprecated. Tokens returned directly in the URL fragment. Don't build new things with this. Do test your existing systems if they still use it.
PKCE (Proof Key for Code Exchange) — Authorization Code with an extra layer for public clients (SPAs, mobile apps). Generates a code_verifier and code_challenge. Prevents authorization code interception attacks.
Each has different attack vectors and different things to validate.
What End-to-End OAuth Testing Covers
End-to-end testing isn't just "does login work." It means verifying the entire token lifecycle:
- Authorization request — correct parameters, scope, redirect URI, state
- User consent — redirected to correct authorization server, consent screen shown
- Authorization response — code or token returned with correct parameters
- Token exchange — code exchanged for access token, ID token, refresh token
- Token use — protected resources accessible with valid token
- Token expiry — expired tokens rejected
- Token refresh — refresh flow works, new tokens issued
- Revocation — tokens properly invalidated
Skipping any of these is how you end up with silent auth failures in production.
Setting Up Your Test Environment
Use a Real Authorization Server in Tests
Don't mock your authorization server in integration tests. Use a real instance:
- Keycloak (self-hosted, free) — runs in Docker, full-featured, excellent for CI
- Auth0 (cloud) — free tier works for test environments
- Okta — enterprise, has developer sandbox accounts
For CI, Keycloak in Docker is the easiest:
services:
keycloak:
image: quay.io/keycloak/keycloak:24.0
command: start-dev
ports:
- "8080:8080"
environment:
KEYCLOAK_ADMIN: admin
KEYCLOAK_ADMIN_PASSWORD: adminConfigure a test realm, a test client, and test users via the admin API or import. This gives you a predictable, isolated auth environment.
Test Users and Clients
Set up dedicated test users and OAuth clients. Never test against production users or shared test accounts—state bleeds between tests.
Create users with known credentials, specific roles, and specific attributes. Create OAuth clients with explicit redirect URIs set to your test environment.
Testing the Authorization Code Flow
The authorization code flow has the most moving parts and the most to test.
Happy Path
def test_authorization_code_flow():
# Step 1: Build authorization URL
state = generate_state()
auth_url = build_auth_url(
client_id="test-client",
redirect_uri="http://localhost:3000/callback",
scope="openid profile email",
state=state,
response_type="code"
)
# Step 2: Simulate user login and consent
session = requests.Session()
response = session.get(auth_url, allow_redirects=False)
# Follow redirects through login form...
code, returned_state = extract_code_and_state(response)
# Step 3: Validate state parameter
assert returned_state == state, "State mismatch — CSRF risk"
# Step 4: Exchange code for tokens
token_response = session.post("/oauth/token", data={
"grant_type": "authorization_code",
"code": code,
"redirect_uri": "http://localhost:3000/callback",
"client_id": "test-client",
"client_secret": "test-secret"
})
assert token_response.status_code == 200
tokens = token_response.json()
assert "access_token" in tokens
assert "refresh_token" in tokens
assert tokens["token_type"] == "Bearer"
assert tokens["expires_in"] > 0
# Step 5: Use access token
api_response = requests.get(
"/api/userinfo",
headers={"Authorization": f"Bearer {tokens['access_token']}"}
)
assert api_response.status_code == 200Testing with Browser Automation
For web apps, you need browser automation to test the full redirect flow. With Playwright:
def test_oauth_login_flow(page):
page.goto("http://localhost:3000")
page.click("[data-testid='login-with-google']")
# Should redirect to authorization server
page.wait_for_url("**/auth/realms/*/protocol/openid-connect/auth*")
# Fill login form
page.fill("#username", "testuser@example.com")
page.fill("#password", "testpassword")
page.click("#kc-login")
# Should redirect back to app
page.wait_for_url("http://localhost:3000/**")
# Assert user is logged in
assert page.locator("[data-testid='user-menu']").is_visible()
assert "testuser" in page.locator("[data-testid='user-name']").text_content()Testing Error Cases
Error cases are where most OAuth implementations break.
Invalid Client ID
def test_invalid_client_id_rejected():
response = requests.post("/oauth/token", data={
"grant_type": "authorization_code",
"code": valid_code,
"client_id": "nonexistent-client",
"client_secret": "secret"
})
assert response.status_code == 401
assert response.json()["error"] == "invalid_client"Invalid Redirect URI
The authorization server must reject redirect URIs that don't exactly match the registered URI. Even a trailing slash difference should fail:
def test_unregistered_redirect_uri_rejected():
auth_url = build_auth_url(
redirect_uri="http://attacker.com/steal-tokens"
)
response = requests.get(auth_url)
# Must NOT redirect to attacker.com
assert "attacker.com" not in response.headers.get("Location", "")
assert response.status_code in [400, 403]State Parameter Mismatch
Your application must validate the state parameter when processing the callback:
def test_state_mismatch_rejected():
# Initiate flow with legitimate state
session = start_oauth_flow(state="legitimate-state")
# Simulate callback with different state (CSRF attack)
response = client.get("/callback?code=someCode&state=forged-state")
assert response.status_code in [400, 403]
# User should NOT be logged in
assert not is_authenticated(session)Expired Authorization Code
Authorization codes are single-use and short-lived (typically 60 seconds):
def test_expired_code_rejected():
code = get_authorization_code()
time.sleep(65) # Wait for code to expire
response = exchange_code_for_token(code)
assert response.status_code == 400
assert response.json()["error"] == "invalid_grant"Code Reuse
Authorization codes must be single-use:
def test_code_reuse_rejected():
code = get_authorization_code()
# First use succeeds
first_response = exchange_code_for_token(code)
assert first_response.status_code == 200
# Second use fails
second_response = exchange_code_for_token(code)
assert second_response.status_code == 400
assert second_response.json()["error"] == "invalid_grant"Testing Client Credentials Flow
Simpler than authorization code, but still has important validations:
def test_client_credentials_flow():
response = requests.post("/oauth/token", data={
"grant_type": "client_credentials",
"client_id": "service-client",
"client_secret": "service-secret",
"scope": "api:read api:write"
})
assert response.status_code == 200
token = response.json()
assert token["token_type"] == "Bearer"
assert "refresh_token" not in token # Client credentials doesn't return refresh tokens
assert token["expires_in"] > 0
def test_wrong_client_secret_rejected():
response = requests.post("/oauth/token", data={
"grant_type": "client_credentials",
"client_id": "service-client",
"client_secret": "wrong-secret"
})
assert response.status_code == 401
def test_missing_scope_handled():
response = requests.post("/oauth/token", data={
"grant_type": "client_credentials",
"client_id": "service-client",
"client_secret": "service-secret",
"scope": "nonexistent:scope"
})
assert response.status_code == 400
assert response.json()["error"] == "invalid_scope"Testing Scope Enforcement
Scopes are often the weakest link. Test that your resource server actually checks them:
def test_insufficient_scope_rejected():
# Get token with read-only scope
token = get_token(scope="api:read")
# Attempt write operation
response = requests.post(
"/api/data",
headers={"Authorization": f"Bearer {token}"},
json={"key": "value"}
)
assert response.status_code == 403 # Forbidden, not 401
def test_correct_scope_allows_access():
token = get_token(scope="api:write")
response = requests.post(
"/api/data",
headers={"Authorization": f"Bearer {token}"},
json={"key": "value"}
)
assert response.status_code == 200 or response.status_code == 201Testing Token Validation
Your resource server validates tokens on every request. Test it directly:
def test_malformed_token_rejected():
response = requests.get(
"/api/resource",
headers={"Authorization": "Bearer this.is.not.valid"}
)
assert response.status_code == 401
def test_token_from_different_issuer_rejected():
# Token signed by a different key
fake_token = create_token_with_wrong_key(subject="user123")
response = requests.get(
"/api/resource",
headers={"Authorization": f"Bearer {fake_token}"}
)
assert response.status_code == 401
def test_no_token_rejected():
response = requests.get("/api/resource")
assert response.status_code == 401
assert "WWW-Authenticate" in response.headersEnd-to-End Automated Testing with HelpMeTest
For teams running continuous OAuth testing, HelpMeTest lets you describe auth flows in plain English and monitors them 24/7:
Test "OAuth login works":
1. Go to the login page
2. Click "Sign in with Google"
3. Enter test credentials
4. Assert user is redirected back and sees dashboard
5. Assert user name appears in navigationThis catches OAuth breakage immediately—not when a user reports they can't log in.
Test Coverage Checklist
Before shipping any OAuth implementation, verify:
- Authorization code flow happy path
- PKCE flow (if using public clients)
- Client credentials flow
- Invalid client ID rejected
- Invalid client secret rejected
- Unregistered redirect URI rejected
- State parameter validated
- Expired authorization code rejected
- Authorization code is single-use
- Wrong scope returns 403 (not 401)
- Malformed token rejected
- Expired access token rejected
- Token from wrong issuer rejected
- Refresh token flow works
- Refresh token rotation works
OAuth is not "works or doesn't work." It's a protocol with dozens of edge cases, each of which can be a security hole. The only way to know your implementation is correct is to test each one explicitly.