OAuth.

Ongoing note dump of oauth things, like I was student in highschool all over again. Some of this might make no sense, and some might be regurgitation from the specs...

Authorization Server Metadata#

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

Two valid forms:

• https://clerk.thekevinwang.com/.well-known/openid-configuration.
• https://clerk.thekevinwang.com/.well-known/oauth-authorization-server.

Various RFC's define additional metadata fields

• grant_types_supported
  • urn:ietf:params:oauth:grant-type:device_code - Device Authorization Grant 8628
  • urn:ietf:params:oauth:grant-type:token-exchange - Token Exchange Grant 8693

ID-JAG §7 introduces even more:

{
  "identity_chaining_requested_token_types_supported": [
    "urn:ietf:params:oauth:token-type:id-jag"
  ]
}

{
  "authorization_grant_profiles_supported": [
    "urn:ietf:params:oauth:grant-profile:id-jag"
  ],
  // ↑ Must also support ↓
  "grant_types_supported": [
    "urn:ietf:params:oauth:grant-type:jwt-bearer"
  ]
}

• JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants defines urn:ietf:params:oauth:grant-type:jwt-bearer, but doesn't define anything regarding metadata or advertisement.

AI Era#

How the pieces ladder up:

MCP & Token exchange#

A sequence diagram for OAuth powered 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.

All of this could take place with a single trust domain.

Identity Chaining#

OAuth Identity and Authorization Chaining

What problem does it solve?

describes how a request carries user identity and authorization context between two trust domains — eg. domain A & domain B.

Notes

• AS B SHOULD NOT issue refresh tokens — it's a redundant credential, requires additional security, and allows access token issuance to occur only within Domain B.

Steps 2 & 3, token exchange in Domain A

POST /auth/token HTTP/1.1
   Host: as.a.example
   Content-Type: application/x-www-form-urlencoded

   grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
   &resource=https%3A%2F%2Fas.b.example%2Fauth
   &subject_token=_RU..D03_Nsfw1_0F7den-SLO6WfIh8YHl.iRq4oJY038Kqr
   &subject_token_type=
    urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token

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

   {
     "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjI4MTMzMDgwMDQifQ.eyJpc3MiOiJodHRwczovL2FzLmEuZXhhbXBsZS9hdXRoIiwiZXhwIjoxNjk1Mjg3NzUyLCJpYXQiOjE2OTUyODc2OTIsInN1YiI6ImpvaG5kb2VAYS5leGFtcGxlIiwiYXVkIjoiaHR0cHM6Ly9hcy5iLmV4YW1wbGUvYXV0aCJ9.Li8Rh-c-R0xirbuXlX8x6sQkZRqJIms9U8Rk8cL7uh1Mm232O6mwz1osPEMNef4OFUW-qTfA0C9QdeIl-e0KsA",
     "token_type":"N_A",
     "issued_token_type":"urn:ietf:params:oauth:token-type:jwt",
     "expires_in":60
   }

// Token header
{
  "alg": "ES256",
  "kid": "2813308004"
}

// Token claims
{
  "aud": "https://as.b.example/auth",
  "exp": 1695287752,
  "iat": 1695287692,
  "iss": "https://as.a.example/auth",
  "sub": "johndoe@a.example"
}

Claims transcription#

One novel flow described is claims transcription.

Transcribing the subject identifier#

Identify chaining is unopinionated about subject identifier mapping. ID-JAG brings more opinions to the flow.

• GIVEN: client in Domain A is requesting access token in Domain B

• WHEN: subject ID can differ in trust domain A & B, e.g "johndoe@a.example" vs. "doe.john@b.example".

• THEN: mapping can happen in either of:

  • token exchange step in domain A
  • auth grant assertion — the front door to domain B

AS B MUST deny the request if it can't identify the subject.

Controlling scope

• check that requested scopes are not higher than the subject_token

New AS metadata#

identity_chaining_requested_token_types_supported

• Optional
• JSON array of supported token types, requestable during token exchange (requested_token_type)
• Advertisement !== to actual support.

ID-JAG and XAA#

What does this solve?

Parties involved; Example with three independent registrations.

Main flow#

Changes:

• XAA extends the IdP's role from single sign-on to brokering cross-domain API access
• XAA built on
  • identity chaining
  • token exchange
  • CIMD

The ID-JAG#

// Header
{
  "typ": "oauth-id-jag+jwt",
}

// Payload
{
  "jti": "9e43f81b64a33f20116179",
  "iss": "https://acme.idp.example",
  "sub": "user_id_at_IDP",
  "aud": "https://acme.chat.example/",
  "client_id": "f53f191f9311af35", // ID @ the resource AS; May be CIMD
  "exp": 1311281970,
  "iat": 1311280970,
  "resource": "https://acme.chat.example/api",
  "scope": "chat.read chat.history",
  "auth_time": 1311280970,
  "amr": [
    "mfa",
    "phrh",
    "hwk",
    "user"
  ]
}

Header typ MUST be oauth-id-jag+jwt. Highlighted payload claims are required.

Use case 1. Enterprise deployment#

Preconditions

• Client has a registered OAuth 2.0 Client with the IdP AS
• Client has a registered OAuth 2.0 Client with the Resource AS
• Enterprise trusts relationship between IdP and Client for SSO and ID-JAG
• Enterprise trusts relationship between IdP and Resource Authorization Server for SSO and ID-JAG.
• Enterprise grants the Client permission to act on behalf of users for the Resource AS with a set of scopes

Use case 2. Customer identity for developer SaaS components#

Use case 3. Email and calendaring applications#

Use case 4. AI agent using external tools#

Other#

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#

• RFC 6749: The OAuth 2.0 Authorization Framework
• RFC 9700 BCP 240: Best Current Practice for OAuth 2.0 Security

OAuth 2.1#

• Draft: The OAuth 2.1 Authorization Framework

Most important changes:

Source: Draft §10 — Differences from OAuth 2.0.

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.

Device Authorization Grant#

RFC: Device Authorization Grant 8628

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.

Example from amp CLI that uses the verification_uri_complete repsonse field.

user@~: $ amp
No API key found. Starting login flow...:
Would you like to log in to Amp? [(y)es, (n)o]: y
To log in, visit:

https://auth.ampcode.com/device?user_code=KWMP-LMDW

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

user@~: $ amp add-chatgpt-sub
Opening your browser to sign in to OpenAI...

If the browser does not open, visit:
https://auth.openai.com/oauth/authorize?response_type=code&client_id=app_EMoamEEZ73f0CkXaXp7hrann&redirect_uri=http%3A%2F%2Flocalhost%3A1455%2Fauth%2Fcallback&scope=openid+profile+email+offline_access&code_challenge=REDACTED&code_challenge_method=S256&id_token_add_organizations=true&codex_cli_simplified_flow=true&state=REDACTED

Received authorization from OpenAI, linking your subscription...
Success! Your ChatGPT subscription is now linked to Amp and active.