OAuth 2.0 Concepts for Testers

Why it matters

OAuth defects are security defects. A redirect URI that is not matched exactly can deliver codes to an attacker, a missing state check accepts a forged sign-in, an unenforced scope turns read access into write access, and a refresh token that never expires keeps a lost phone signed in. RFC 9700, the current OAuth security best practice, describes these attacks and their countermeasures.

For a tester, one sign-in crosses the browser, the client, the authorization server and the API. Knowing the roles and messages turns "login does not work" into the exact step that failed and its error.

The four roles and what they exchange

RFC 6749 defines four roles: the resource owner (usually the user), the client (the application that wants access), the authorization server (signs the user in, asks for consent, issues tokens) and the resource server (the API). A confidential client, such as a web app with a back end, can keep a secret; a public client, such as a single-page or mobile app, cannot.

• Authorization code: short-lived and single-use, returned through the browser; RFC 6749 recommends at most 10 minutes.
• Access token: sent to the API, usually as a Bearer token as in the API authentication lesson. OAuth does not fix its format: a JWT or an opaque string.
• Refresh token: optional and longer-lived; sent only to the authorization server for new access tokens, never to the API.
• Scope: permissions such as appointments.read. The server may grant fewer than requested and must then return the granted scope.

Try it: OAuth Token Decoder Try it: Mock Authentication Response

The authorization code flow with PKCE

A grant is how a client obtains tokens. With a user involved, use the authorization code grant with PKCE (Proof Key for Code Exchange, RFC 7636). The user signs in at the authorization server, so the password never reaches the client. The server then redirects the browser back to the client with a code; this browser leg is the front channel. The client redeems the code in a direct request to the token endpoint, the back channel.

PKCE binds the code to the client that asked for it. The client makes up a random code_verifier and sends only its SHA-256 hash, encoded as Base64url, as the code_challenge (method S256). A hash is a one-way fingerprint: anyone can compute it from the verifier, but no one can work the verifier out from it. When the client redeems the code it presents the verifier itself, and the server checks that it hashes to the challenge, so a stolen code is useless without it. RFC 9700 requires PKCE for public clients and recommends it for confidential ones.

• state: a random value tied to the browser session and checked on return, so a forged callback is rejected.
• redirect_uri: matched exactly against a registered value. On a mismatch the server shows an error and does not redirect.

# Front channel: the browser carries the authorization request (wrapped for reading)
GET /authorize?response_type=code&client_id=booking-app
    &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcb
    &scope=openid%20appointments.read&state=af0ifjsldkj
    &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
    &code_challenge_method=S256 HTTP/1.1
Host: auth.example.com

# Front channel: after sign-in and consent, the redirect back with the code
HTTP/1.1 302 Found
Location: https://app.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=af0ifjsldkj

# Back channel: the client redeems the code with the verifier (body wrapped for reading)
POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&client_id=booking-app
&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcb
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

Try it: SHA-256 Generator

Client credentials, refresh and expiry

With no user involved, such as a nightly reporting job, a confidential client uses the client credentials grant: it authenticates with its own credentials and receives an access token for its own permissions, normally without a refresh token.

Access tokens are short-lived, so a leaked one is useful only briefly. On expiry the client sends grant_type=refresh_token and cannot gain scope the user never approved. For public clients RFC 9700 requires refresh tokens to be sender-constrained (cryptographically bound to that client instance, so a copied token is useless on its own) or rotated: with rotation each refresh returns a new refresh token and invalidates the old one.

# Basic credentials = Base64 of client_id:client_secret (example values from RFC 6749)
POST /token HTTP/1.1
Host: auth.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=reports.read

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{"access_token":"2YotnFZFEjr1zCsicMWpAA","token_type":"Bearer",
 "expires_in":900,"scope":"reports.read"}

OpenID Connect in brief

OAuth 2.0 tells the client what it may access, not who the user is. OpenID Connect (OIDC) adds identity: with the scope openid, the token response also carries an ID token, a JWT for the client that states who signed in, with claims such as iss, sub (the user's id at that issuer), aud (the client's own client_id), exp and, if the client sent one, nonce.

The client validates the ID token as the JWT guide describes and keeps it; only the access token goes to the API.

Worked example: testing a booking app's sign-in

A clinic booking app, a public client, uses the authorization code flow with PKCE and OIDC; its API requires appointments.read to list and appointments.write to book. You test the integration in the test environment with test users and the test client registration, not the identity provider's own product. The token endpoint returns its error value in a JSON body; the API returns it in the WWW-Authenticate challenge (RFC 6750). Most conditions are negative:

• Sign in, approve and list appointments → 200; the granted scope equals what the user approved.
• Alter state in the callback → the app rejects it and creates no session.
• Point redirect_uri at another host → an error page and no redirect.
• Redeem a code twice, or send a wrong code_verifier → 400 with invalid_grant.
• Deny consent → the app handles error=access_denied with a clear message.
• Book with a read-only token → 403 with insufficient_scope.
• Call the API with an expired access token or with the ID token → 401 with invalid_token.
• With rotation on, reuse an old refresh token → 400 with invalid_grant, and RFC 9700 expects the newest refresh token to be revoked as well.

Try it: API Authentication Tester Try it: JWT Expiration Checker

Frequently asked questions

References

• RFC 6749: The OAuth 2.0 Authorization FrameworkIETF · 2012The OAuth 2.0 roles, grant types and token endpoints that issue access and refresh tokens.
• RFC 9700: Best Current Practice for OAuth 2.0 SecurityIETF · 2025Current security guidance for OAuth 2.0: PKCE for public clients, exact redirect matching, sender-constrained tokens.
• RFC 7636: Proof Key for Code Exchange by OAuth Public ClientsIETF · 2015PKCE: the code_verifier and code_challenge (S256) that bind an OAuth authorization code to the client that requested it, defeating code interception.
• OpenID Connect Core 1.0 incorporating errata set 2OpenID Foundation · 2023The identity layer on top of OAuth 2.0: the ID Token and how to validate it, the authentication flows, standard claims and the UserInfo endpoint.