Home
AtomsAbout me
NOTES, THOUGHTS, SCRIBBLES

OAuth.

Some quick references to various OAuth documents that I find myself repeatedly looking up, for work.

Registry of parameters#

This is a super helpful all-up view of the exact parameter names from various OAuth RFCs.

https://www.iana.org/assignments/oauth-parameters

The main RFC's#

OAuth 2.1#

Most important changes:

ChangePractical effect
Authorization code + PKCE requiredPKCE is required for both public and confidential clients. Only the S256 method is supported.
Implicit grant removedUse authorization code + PKCE instead of returning access tokens directly in the authorization response.
Password grant removedApplications must not collect user passwords to exchange them for tokens.
Exact redirect URI matchingPrevents loose matching from sending authorization responses to attacker-controlled locations.
Stronger refresh-token protection for public clientsRefresh tokens must be sender-constrained or rotated after each use.
No bearer tokens in URL query stringsReduces exposure through logs and other URL storage.

Source: Draft §10 — Differences from OAuth 2.0.

Authorizing your TV or fridge#

Device Authorization Grant 8628 is the RFC that breaks that flow down.

Requirements

  1. The device is already connected to the Internet.
  2. The device is able to make outbound HTTPS requests.
  3. The device is able to display or otherwise communicate a URI and code sequence to the user.
  4. The user has a secondary device (e.g., personal computer or smartphone) from which they can process the request.
A mermaid diagram image
A mermaid diagram image

Example from amp CLI that uses the []verification_uri_complete](https://datatracker.ietf.org/doc/html/rfc8628#section-3.2) repsonse field.

And to constrast, here's amp CLI taking the user through the usual authorization_code flow,

Authorization Server Metadata#

An authorization server's means of advertising its configuration and supported features to clients.

Here's example data from https://clerk.thekevinwang.com/.well-known/openid-configuration. Another valid endpoint is https://clerk.thekevinwang.com/.well-known/oauth-authorization-server.

{issuer: "https://clerk.thekevinwang.com",authorization_endpoint: "https://clerk.thekevinwang.com/oauth/authorize",token_endpoint: "https://clerk.thekevinwang.com/oauth/token",revocation_endpoint: "https://clerk.thekevinwang.com/oauth/token/revoke",introspection_endpoint: "https://clerk.thekevinwang.com/oauth/token_info",userinfo_endpoint: "https://clerk.thekevinwang.com/oauth/userinfo",jwks_uri: "https://clerk.thekevinwang.com/.well-known/jwks.json",scopes_supported: [0: "email",1: "profile",2: "public_metadata",3: "private_metadata",4: "openid",5: "offline_access",6: "mcp:all"],response_types_supported: [0: "code"],response_modes_supported: [0: "form_post",1: "query"],grant_types_supported: [0: "authorization_code",1: "refresh_token"],subject_types_supported: [0: "public"],id_token_signing_alg_values_supported: [0: "RS256"],token_endpoint_auth_methods_supported: [0: "client_secret_basic",1: "none",2: "client_secret_post"],claims_supported: [0: "email",1: "given_name",2: "name",3: "preferred_username",4: "sub",5: "aud",6: "exp",7: "email_verified",8: "family_name",9: "picture",10: "iss",11: "iat"],code_challenge_methods_supported: [0: "S256"],backchannel_logout_supported: false,frontchannel_logout_supported: false,authorization_response_iss_parameter_supported: true}

PKCE#

Proof key for code exchange (PKCE) prevents intercepted authorization codes from being exchangeable for access tokens.

PKCE adds:

  • code_verifier: high-entropy, per-request secret.
  • code_challenge: one-way derived verifier value.
  • code_challenge_method: S256. OAuth 2.1 removes plain.
  • Challenge binding: authorization server stores the challenge with the authorization code.
  • Proof at redemption: client sends the verifier to POST /token.
  • Server validation: derive and compare; reject mismatch.
  • One-time, short-lived authorization code: required container for that binding.
A mermaid diagram image
A mermaid diagram image

MCP & Token exchange#

A sequence diagram for MCP auth flow, commonly seen nowadays.

Token exchange in this scenario is one option for complying with acceess token privilege restriction, as documented in the MCP 2026-07-28 spec.

If the MCP server makes requests to upstream APIs, it may act as an OAuth client to them. The access token used at the upstream API is a separate token, issued by the upstream authorization server. The MCP server MUST NOT pass through the token it received from the MCP client.

A mermaid diagram image
A mermaid diagram image

ID-JAG (XAA)#

Overview#

Hypothetical scenario

A mermaid diagram image
A mermaid diagram image

Registration steps#

  1. Google enables ID-JAG issuance and RFC 8693 token exchange.
  2. booking.ai registers the Travel Agent with Google Identity.
  3. Google gives the Travel Agent an OAuth client ID and credentials.
  4. booking.ai registers the Travel Agent with BigAirline OAuth.
  5. BigAirline gives the Travel Agent a separate client ID and credentials.
  6. BigAirline configures trust in Google’s issuer, signing keys, and identity claims.
  7. Google and BigAirline map the two client registrations. A global URL client ID can replace this mapping.
  8. Google configures which BigAirline audiences, resources, and scopes the Travel Agent can request.
  9. BigAirline configures user matching and local access policy.
  10. The BigAirline API configures trust in tokens from BigAirline OAuth.

Runtime steps#

  1. The traveler signs in to booking.ai with Google.
  2. Google authenticates the traveler.
  3. Google returns an ID Token and, optionally, a refresh token.
  4. The Travel Agent sends the ID Token to Google in an RFC 8693 token-exchange request.
  5. The request identifies BigAirline OAuth as the audience and the BigAirline API as the resource.
  6. Google validates the traveler, client, requested access, and policy.
  7. Google returns a signed ID-JAG for BigAirline OAuth.
  8. The Travel Agent authenticates to BigAirline OAuth.
  9. The Travel Agent redeems the ID-JAG with an RFC 7523 JWT bearer grant.
  10. BigAirline validates the Google signature, audience, client binding, user identity, and requested access.
  11. BigAirline returns an access token for its API.
  12. The Travel Agent calls the BigAirline API with that access token.
  13. The API validates the token and returns the authorized data.
  14. booking.ai shows the result to the traveler.

Registration#

A mermaid diagram image
A mermaid diagram image

Runtime#

A mermaid diagram image
A mermaid diagram image

FAQ#

Q: What is the state parameter's purpose in a autorization code flow,#

The client:

  1. Creates a random state value and stores it against the browser session.
  2. Sends it in the authorization request.
  3. Receives the same value in the redirect from the authorization server.
  4. Checks that it matches, then removes the stored value.

An unexpected or missing value causes the client to reject the response. This helps prevent
cross-site request forgery (CSRF), including unwanted login attempts.

Q: Which parties govern the aud claim in an access token?#

RFC 8707 §2.2 leaves acceptable resources to authorization-server policy and configuration 1

RFC 9068 §3 also leaves scope-to-default-resource mappings to the implementation. 2

RFC 9728 §4 An authorization server can publish an optional protected_resources list in its metadata. However, that list can omit supported resources, so it is not necessarily the canonical database. 3

Q: What is the Step up flow?#

Allows a resource server to request a client to obtain a new access token with a higher level of authentication and or recency.

RFC 94704 extends RFC 67505 with new parameters and a new error code:

NameUsage LocationProtocol ExtensionRef
acr_valuesauthorization requesthttps://openid.net/specs/openid-connect-core-1_0.html
max_ageauthorization requesthttps://openid.net/specs/openid-connect-core-1_0.html
insufficient_user_authenticationresource access error responseOAuth 2.0 Step Up Authentication Challenge ProtocolRFC 9470

The resource server can use these parameters to explicitly communicate to the client the required authentication strength or recentness.

Client then makes an auth request to AS w/ acr_values and max_age.

A mermaid diagram image
A mermaid diagram image

Footnotes#

  1. RFC 8707 Resource Indicators for OAuth 2.0: https://www.rfc-editor.org/info/rfc8707 ↩

  2. RFC 9068 JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens: https://www.rfc-editor.org/info/rfc9068 ↩

  3. RFC 9728 OAuth 2.0 Protected Resource Metadata: https://www.rfc-editor.org/info/rfc9728 ↩

  4. RFC 9470 OAuth 2.0 Step Up Authentication Challenge Protocol: https://www.rfc-editor.org/info/rfc9470 ↩

  5. RFC 6750 The OAuth 2.0 Authorization Framework: Bearer Token Usage: https://www.rfc-editor.org/info/rfc6750 ↩