d-OAuth-Server/docs/OAUTH.md

OAuth

This is an OAuth 2.1-only authorization server. It deliberately does not implement the OAuth 2.0 behaviors that 2.1 removes. The server core is the grant machinery under src/protocol/.

Specification reference

This server targets draft-ietf-oauth-v2-1-16, "The OAuth 2.1 Authorization Framework".

• Published: 3 September 2026.
• URL: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1
• Versioned text: https://www.ietf.org/archive/id/draft-ietf-oauth-v2-1-16.txt

This is an Internet-Draft (work in progress), not a published RFC. It may be updated, replaced, or obsoleted by other documents at any time, and citing it here does not imply endorsement. The version above is the one this implementation was reviewed against.

The draft consolidates RFC 6749 (OAuth 2.0), RFC 6750 (Bearer Token Usage), RFC 8252 (OAuth 2.0 for Native Apps), RFC 9700 (Security Best Current Practice), and the Browser-Based Apps draft.

Purpose

For a protocol implementer or an integrator: the exact deltas from OAuth 2.0 and the section citation behind each, the endpoints, the five grants and their parameters, PKCE, redirect matching, and the error codes.

Mandatory OAuth 2.1 deltas from 2.0

The 2.1 draft consolidates the OAuth 2.0 core with the security best current practice in RFC 9700. This server enforces every one of these:

Delta	Behavior here	Reference
PKCE is mandatory for every authorization-code flow	A request without code_challenge is rejected; only S256 is accepted.	draft-ietf-oauth-v2-1-16, RFC 9700 §2.1.1
The plain PKCE method is removed	code_challenge_method=plain is rejected.	RFC 7636 §4.3, RFC 9700 §2.1.1
The implicit grant is removed	Only response_type=code exists; there is no token response.	draft-ietf-oauth-v2-1-16, RFC 9700
The resource-owner-password grant is removed	There is no grant_type=password code path.	draft-ietf-oauth-v2-1-16
Bearer credentials in the URI query are rejected	Access tokens are presented in the Authorization header.	RFC 6750 §2
Redirect URIs are matched exactly	No prefix or wildcard match; one loopback exception.	RFC 9700 §2.1, RFC 3986 §6.2.1
Public-client refresh tokens rotate	Rotation on every use, with tombstone reuse detection.	RFC 9700 §2.2.2, §4.14
Authorization codes are single-use and short-lived	A code is consumed atomically and capped at 60 seconds.	RFC 9700 §4.5.3
state is supported and echoed	The value is returned on the success and error redirects.	RFC 6749 §4.1.2.1
No open redirect	The redirect URI must be registered, attached, and enabled.	RFC 9700 §4.1.3

Endpoints

All endpoints are on the TLS public listener. The plaintext health listener mounts only /health/live and /health/ready.

Method	Path	Reference	Status
GET	/.well-known/oauth-authorization-server	RFC 8414	Wired
GET	/authorize	RFC 6749 §4.1.2.1, RFC 9700 §4.1.3	Wired
POST	/par	RFC 9126 §2.1	Wired
POST	/token	RFC 6749 §4.1.3, RFC 8628 §3.4, RFC 8693 §2	Wired
POST	/device_authorization	RFC 8628 §3.1	Wired
GET, POST	/device	RFC 8628 §3.3	Wired
GET, POST	/login	RFC 9700 §4.7.1	Wired
GET, POST	/logout	server-specific	Wired
GET, POST	/consent	RFC 9700 §4.7.1	Wired
POST	/introspect	RFC 7662 §2.1	Wired
POST	/revoke	RFC 7009 §2.1	Wired
POST	/register	RFC 7591 §2	Wired
GET, PUT, DELETE	/register/{client_id}	RFC 7592 §2	Wired

GET /logout and POST /logout are a server-specific session endpoint, not a feature defined by OAuth 2.1 or OIDC. GET /logout is read-only: it renders a confirm page (live session) or a neutral signed-out page (anonymous) and never destroys the session or writes cookies. Only POST /logout, carrying the session-bound CSRF form_token, destroys the authorization-server session and expires the session cookie (__Host-session_id, or plain session_id when cookie_secure = false; the clearing cookie mirrors the session cookie's name and its Path/HttpOnly/SameSite/Secure; no Domain is ever emitted, so the cookie stays host-only in both variants). In production the session reader honors only __Host-session_id: a plain session_id cookie is never read, so a cookie planted by a sibling subdomain cannot fixate a victim's login onto an attacker presession. The development variant reads plain session_id and may additionally fall back to __Host-session_id; POST /logout clears every name the reader honors. GET /logout takes no query parameters and issues no redirect at all, so a forced navigation cannot cause an open redirect; only POST /logout may redirect, and only to a post_logout URI that was registered for the client and frozen in session meta when the authorization flow was bound. It redirects there only when the owning client is still active and still registers that exact URI (exact-string match, with the RFC 8252 loopback exception); otherwise it renders a neutral signed-out page. A POST /logout with a live session but no bound redirect target renders the neutral signed-out page instead of redirecting. This is what lets a client end the browser SSO session so a different user can sign in. There is no post_logout_redirect_uri parameter, no id_token_hint, and no end_session_endpoint in metadata.

The POST /token handler parses the form once, authenticates the client through the shared client_auth dispatch, verifies the fresh sender proof, dispatches on grant_type to the matching grant, and shapes the RFC 6749 §5.1 JSON response; an unknown grant_type is unsupported_grant_type. The DCR routes map onto protocol::dcr::register_handler and protocol::dcr::manage::{read,update,delete}_handler (RFC 7591 / RFC 7592).

Dynamic client registration

Dynamic registration redirect policy (dcr_redirect_policy): catalog attaches only catalog-registered URIs; catalog_loopback additionally upserts RFC 8252 loopback URIs; open additionally upserts any absolute https URI with a non-empty host and no userinfo, fragment, or whitespace. Loopback URIs are always allowed. Anything else is invalid_redirect_uri.

The five grants

The advertised set is authorization_code, refresh_token, client_credentials, urn:ietf:params:oauth:grant-type:device_code, and urn:ietf:params:oauth:grant-type:token-exchange. DCR may register only authorization_code, refresh_token, and device_code; client_credentials is never registered for a dynamically created client.

authorization_code

Reference: RFC 6749 §4.1.3, RFC 9700 §4.5.3, RFC 7636, RFC 9449 §6.

Parameters: code, code_verifier, client_id, optional redirect_uri, client_secret or client_assertion_type with client_assertion, and a DPoP proof when the code is DPoP-bound.

Behavior: the code is consumed exactly once. redirect_uri is accept-but-ignore (draft-16 §4.1.3, §10.2): a missing or empty value skips the binding check; a supplied value must still match exactly or redemption fails invalid_grant. The client, PKCE verifier, and sender proof are all checked before minting. The token is minted under the code's grant chain. A refresh token is issued only if the client is registered for the refresh grant.

refresh_token

Reference: RFC 6749 §6, RFC 9700 §2.2.2 and §4.14, RFC 9449 §5.

Parameters: client_id, refresh_token, optional requested_scope (which may narrow but never widen), and a freshly verified sender proof. The replacement refresh token keeps the presented scope re-checked against the current enabled catalog and the client's current registration and the user's current entitlements (fresh Postgres reads), so a revoked scope or entitlement drops from the retained refresh scope on refresh; an explicit narrower scope (§4.3.1) narrows only the access token and the response scope, and the next rotation from the retained refresh token can still use the full scope.

Behavior: rotation on every use. The presented token is tombstoned with a rotated_to member. Presenting a rotated token again is reuse: the whole grant family is revoked and the request fails with invalid_grant. A lost reply does not double-rotate, because the rotation is keyed by a deterministic request id and a retry returns the same tokens. If the refresh token's non-empty subject resolves to a disabled user, the request fails invalid_grant before minting or rotating.

client_credentials

Reference: RFC 6749 §4.4, RFC 9449 §6, RFC 8705 §3.

Parameters: client_id (confidential clients only), optional requested_scope, and a sender proof when the client is sender-constrained.

Behavior: no user and no subject. The granted scope is the requested scope intersected with the client's registered scope. No refresh token is issued.

device_code

Reference: RFC 8628 §3.1 through §3.5.

Authorization: POST /device_authorization returns a device code, a user code, a verification URI, an expiry, and a polling interval. The user completes GET /device and POST /device and approves or denies.

Polling: grant_type=urn:ietf:params:oauth:grant-type:device_code with device_code. Before approval the response is authorization_pending; polling faster than the interval returns slow_down; denial returns access_denied; expiry returns expired_token. On approval the token is minted with the scope recomputed against the approving user's entitlements.

token_exchange

Reference: RFC 8693 §2 through §4.1.

Parameters: subject_token, subject_token_type (an access-token type), optional actor_token and actor_token_type, optional requested_token_type, optional requested_scope, and a sender proof that matches the subject token's confirmation, not merely the caller's.

Behavior: disabled by default and enabled with allow_token_exchange. The exchange must be on the explicit (caller, subject, scopes) allowlist. The granted scope is the subject's scope intersected with the caller's registered scope, the subject's entitlements, the enabled catalog, and the allowlist, and it can only narrow. Chained exchange is rejected.

PKCE

Reference: RFC 7636, RFC 9700 §2.1.1.

• S256 is the only accepted code_challenge_method. plain is never advertised and never accepted.
• The verifier is 43 to 128 characters from ALPHA / DIGIT / - . _ ~.
• The challenge is exactly 43 base64url characters without padding.
• The verifier is checked against the challenge at redemption with a constant-time comparison.
• A challenge without a verifier, a verifier without a challenge, and neither are all rejected. The verifier cannot be omitted to downgrade the request.
• RFC 7636 Appendix B test vector is covered by a unit test.

Redirect URI matching

Reference: RFC 3986 §6.2.1, RFC 8252 §7.3, RFC 9700 §2.1.

• Matching is exact Simple String Comparison: scheme, host, port, path, and query must match byte for byte. There is no decoding, no case folding, and no prefix or wildcard match.
• The one exception is a native-app loopback URI. A registered http://127.0.0.1 or http://[::1] matches the same scheme, host, and path on any port, and the request must carry no userinfo, query, or fragment.
• localhost is never treated as a loopback host.
• A private-use URI scheme must contain reverse-DNS dot notation (draft-16 §2.3.1): com.example.app:/cb is accepted, myapp:/cb is rejected. https and the loopback http exception are unaffected.
• A registered URI with userinfo, query, or fragment is never eligible for the loopback exception.

Error-delivery matrix

Before a redirect URI is validated, the server must not redirect anywhere. It returns an HTML page with no Location header for: absent or unknown client_id, a JAR/PAR resolution failure, a client_id binding mismatch, and a missing or unregistered redirect_uri. The page carries the error's HTTP status: client errors render 400, a fail-closed Postgres/PII outage (temporarily_unavailable) renders 503 with Retry-After: 1, and a masked internal failure renders 500.

After the redirect URI is validated, errors are delivered on the redirect as 302 with error, error_description, the echoed state, and the RFC 9207 iss. This covers a missing or unsupported response_type (invalid_request when absent, unsupported_response_type otherwise), invalid_scope, the PKCE failures, and a post_logout catalog outage (temporarily_unavailable/server_error).

Error codes

Errors use the RFC 6749 §5.2 body {error, error_description}.

Code	HTTP	Typical causes
invalid_request	400, or 302 on the /authorize error redirect once client_id and redirect_uri are validated	Missing or duplicated parameter; PAR misuse; JAR misuse.
invalid_client	401 with WWW-Authenticate for Basic or Bearer, else 400	Bad client authentication; ambiguous mTLS certificate.
invalid_grant	400	Unknown, consumed, or foreign code; rotation reuse; PKCE mismatch; proof against the wrong grant.
invalid_scope	400	Unknown, disabled, over-registered, or non-entitled scope; refresh widening.
unsupported_grant_type	400	A grant_type outside the five.
unsupported_response_type	302 error redirect	A response_type other than code.
unauthorized_client	400	A client that may not use the requested grant.
invalid_request_object	400	Malformed, unsigned, mis-bound, or conflicting JAR request object.
invalid_dpop_proof	400	Missing or invalid DPoP proof; replayed jti.
invalid_redirect_uri	400	DCR redirect URI not in the catalog or otherwise ineligible.
invalid_client_metadata	400	DCR metadata that violates the rules.
access_denied	400	Resource-owner denial; RFC 7592 token mismatch.
authorization_pending	400	Device flow before approval.
slow_down	400	Device polling faster than the interval.
expired_token	400	Device code or code expired.
temporarily_unavailable	503 with Retry-After: 1	Postgres or Redis is unavailable on a security path.
server_error	500	A masked internal failure.

The server never fails open on a security path: a dependency outage yields 503, never a silent success.

Sender constraints

Every sender-constrained grant requires a freshly verified proof of possession on every use.

Client class	Binding
Public	DPoP mandatory. A missing proof is a hard invalid_grant.
Confidential	mTLS and/or DPoP; the confirmation reports both when both are proven.

private_key_jwt is client authentication only. It produces no confirmation and never satisfies sender constraint. For token exchange, the proof must match the subject token's confirmation. See SECURITY.md for the full matrix and the confirmation propagation rule. It accepts RS256, PS256, ES256, and EdDSA only (none and HMAC are rejected); exp may lie at most 300 s past now plus 30 s clock skew, and the single-use jti marker lives for the assertion's remaining validity, clamped to [1 s, 360 s].

Metadata

GET /.well-known/oauth-authorization-server returns the RFC 8414 document. The only state-dependent member is scopes_supported, read from the enabled scopes table on every request. The catalog is mutated out of process by the CLI, so a per-request read makes a change visible immediately on every replica with no restart. When Postgres is unavailable the endpoint returns 503 rather than advertising an unknown list.

The document carries no jwks_uri: the server signs no artifact of its own. code_challenge_methods_supported advertises only S256. authorization_response_iss_parameter_supported is true, so the authorization response carries iss (RFC 9207). The document advertises token_endpoint_auth_signing_alg_values_supported = [ES256, EdDSA, RS256, PS256]; dpop_signing_alg_values_supported stays [ES256, EdDSA, RS256].

JAR and PAR

Reference: RFC 9101 §4.1 and §5.2, RFC 9126 §2 and §3.

• At /authorize, a confidential client must use either a PAR-issued request_uri or a signed request object. A public client may use the query string.
• A signed request object must be signed, must have iss equal to client_id, must target the issuer as aud, and must use RS256, PS256, ES256, or EdDSA (none and everything else are rejected before key selection). Conflicts between the object and the query string are rejected.
• A request_uri is a one-time, client-bound PAR handle or an exactly pre-registered URI. It is fetched only with the SSRF guard: https only, no redirects, global IPs only, size and time capped. The connection is pinned to the addresses validated before the fetch, so a rebinding hostname cannot steer it to a blocked address.
• A remote (pre-registered, non-PAR) request_uri is fetched over outbound HTTPS, which the shipped cluster network policy default-denies. It is available only when the deployment adds a scoped egress allowance for the specific host; see DEPLOYMENT.md.

Security properties

• A code or device code is single-use and consumed atomically.
• A rotation is idempotent and reuse is tombstoned and detected.
• A redirect is matched exactly, and errors before redirect validation do not redirect.
• The confirmation claim propagates to every newly minted token.
• A dependency outage fails closed.

Edge cases

• A refresh request that omits scope keeps the prior grant on both new tokens after re-checking against the current enabled catalog, client registration, and user entitlements (fresh Postgres reads), with revoked entries dropped silently from the retained scope (possibly to empty); an explicit scope must be a subset of the prior grant and all three current sets, and narrows only the access token and the response scope — the replacement refresh token retains the full re-checked scope (draft-16 §4.3.1 + §4.3.3), so a later rotation with an omitted scope restores the full retained scope.
• A second authorization code made from the same request is a distinct code; each is single-use.
• A DPoP proof outside the iat freshness window, or with a replayed jti, is rejected.
• A pre-7.2 Redis has no WAITAOF; the server then requires instance-wide appendfsync always, or fails closed.

Operational runbook

• Confirm the advertised capabilities:

  curl -s https://auth.example.com/.well-known/oauth-authorization-server | jq .
  

• A code flow starts with GET /authorize?response_type=code&client_id=...&redirect_uri=...&scope=...&state=...&code_challenge=...&code_challenge_method=S256.

• Introspect a token: POST /introspect with token and client authentication. A token whose subject is a disabled user returns {"active": false} like an unknown token.

• Revoke a token: POST /revoke with token and an optional token_type_hint.

• If every security endpoint returns 503, check /health/ready and the Postgres and Redis connections.

File and directory references

• src/protocol/authorize.rs for authorization validation and the error matrix.
• src/protocol/code.rs for code issuance and the success redirect.
• src/protocol/token/ for the grants and TokenService.
• src/protocol/par.rs, src/protocol/device.rs, src/protocol/introspect.rs, src/protocol/revoke.rs for the other endpoints.
• src/protocol/dcr.rs, src/protocol/dcr/manage.rs for registration.
• src/protocol/metadata.rs for the RFC 8414 document.
• src/crypto/pkce.rs for PKCE.
• src/protocol/redirect_repo.rs for redirect matching.
• src/jose/ for DPoP, JAR, and private_key_jwt.
• src/error.rs for the error-to-HTTP mapping.