Ensure authorization_servers lists a fully resolvable, operational domain — do not use dummy subdomains that are not bound in DNS; a 530 Origin DNS Error means the URL is unreachable.
The agent_auth block MUST exist in the oauth-authorization-server metadata file.
The agent_auth block MUST include a "skill" attribute pointing to the absolute URL of auth.md.
Use "register_uri" (not identity_endpoint) and "claim_uri" (not claim_endpoint) — the field names are exact; any deviation will fail scanner validation.
Define credential_types_supported nested inside the identity type blocks (e.g., anonymous.credential_types_supported), NOT at the root of agent_auth.
Both anonymous and identity_assertion credential paths must be documented if the service supports them.
All endpoints must be served with Content-Type: application/json and appropriate CORS headers.
enforce PKCE (Proof Key for Code Exchange) as mandatory for all agent OAuth flows, asserting code_challenge_methods_supported: ["S256"] in authorization metadata
support OpenID Connect (OIDC) Dynamic Client Registration by exposing a POST endpoint that accepts the Agent Card JSON as input
bind issued access tokens cryptographically to agent identities using the azp and agent DID claims in the JWT payload
validate that the agent_auth configuration complies with isitagentready.com and WorkOS requirements
Treat the OAuth metadata as a public, signed contract: do not include client secrets or sensitive callback URLs in the served JSON (OWASP ASI03)
Verify every URL in authorization_servers resolves in public DNS before each deploy; a 530 error must fail the scanner run (OWASP ASI04)
After the 2026-07-28 changes, every metadata file must assert code_challenge_methods_supported: ["S256"]; reject metadata that does not

When to Use

Setting up WorkOS Agentic Registration for the first time on a domain
Correcting agent_auth field names after scanner validation failures
Adding OAuth metadata endpoints to a Cloudflare Pages or Workers site
Verifying that isitagentready.com or equivalent scanner passes the OAuth metadata checks
Updating authorization server metadata after adding or changing credential types

Suggested Process

Locate or create metadata files: Identify where oauth-protected-resource.json and oauth-authorization-server.json are served from. For Cloudflare Pages, these live under public/.well-known/. For Workers, serve them from dedicated route handlers.

Structure the oauth-authorization-server payload: Include the required top-level fields (issuer, authorization_endpoint, token_endpoint) and the agent_auth block:

{
  "issuer": "https://auth.yourdomain.com",
  "authorization_endpoint": "https://auth.yourdomain.com/authorize",
  "token_endpoint": "https://auth.yourdomain.com/token",
  "agent_auth": {
    "skill": "https://yourdomain.com/.well-known/auth.md",
    "register_uri": "https://auth.yourdomain.com/agent/register",
    "claim_uri": "https://auth.yourdomain.com/agent/claim",
    "anonymous": {
      "credential_types_supported": ["anonymous"]
    },
    "identity_assertion": {
      "credential_types_supported": ["jwt_bearer"]
    }
  }
}

Structure the oauth-protected-resource payload: Include resource (the service URL) and authorization_servers (array of issuer URLs):
```
{
  "resource": "https://yourdomain.com",
  "authorization_servers": ["https://auth.yourdomain.com"]
}
```
Validate DNS: Confirm every domain in authorization_servers resolves correctly in public DNS. A non-resolving domain causes 530 errors in scanners.
Mount metadata endpoints: Ensure each file is reachable at its standard path. Set Content-Type: application/json and CORS headers.
Expose via Link headers: Use configure-agent-headers to add Link headers pointing to both well-known files for passive agent discovery.
Run scanner validation: Test with isitagentready.com or the WorkOS scanner. Review the diagnostic output against specific rule names — e.g., "anonymous registration requires anonymous.credential_types_supported" maps to a specific nesting requirement.

2026: Mandatory PKCE and Token Binding

To secure machine-to-machine interactions and prevent authorization code interception, A2A OAuth flows require strict PKCE and cryptographic token binding:

Mandatory PKCE: All client authorization requests must use PKCE with SHA-256 challenge. The authorization server metadata must declare "code_challenge_methods_supported": ["S256"].
Authorized Presenter: The token payload must contain the azp (Authorized Party) claim, which identifies the client agent that was issued the token.
DID Token Binding: The token must bind the agent's DID. The JWT claims include the agent's public key identifier or DID URI in custom claims to ensure only the holder of the agent's private key can present the token.

2026: OIDC Dynamic Client Registration

Dynamic registration allows new worker agents to register as OAuth clients on-the-fly:

Registration Endpoint: Expose a registration endpoint (register_uri) responding to POST requests.
Payload Schema: The endpoint accepts OIDC Dynamic Client Registration payloads containing client metadata or directly accepting the worker's signed Agent Card JSON.
Client Credentials: Upon validation of the Agent Card signature and capabilities, the server registers the client and returns a client identifier and registration access token.

Checklist

Related Skills

manage-auth-md: Manage the auth.md discovery file that agent_auth.skill points to.
debug-identity-provider: Diagnose and fix scanner validation failures after configuring metadata.
configure-agent-headers: Expose OAuth metadata well-known paths via HTTP Link headers.
configure-mcp: Wire up OAuth 2.1 + PKCE for the MCP server card.
manage-agent-identity: Issue NHI credentials bound to the OAuth metadata scopes.

Output Contracts

When the OAuth metadata configuration is recorded as a deployable artifact (CI output, edge-config change, or handoff to an infra agent), emit:

contracts/schemas/edge-deployment-spec.json listing the well-known paths, the served content types, the CORS headers, and the resolved DNS status of every authorization_servers entry.
contracts/schemas/api-contract-spec.json describing the metadata JSON shapes (with required vs optional fields) so the deployment agent can validate before serving.
For human-readable reports, a markdown summary of the scanner run output and any field-level failures.

Skip emission for ad-hoc local edits.

Failure Modes

Field name drift: a legacy field name (identity_endpoint, claim_endpoint) is used instead of register_uri/claim_uri. Mitigation: copy field names from the current spec; CI must reject the legacy names.
DNS dead link: an authorization_servers URL does not resolve. Mitigation: CI must dig every URL and fail the deploy on NXDOMAIN or 530.
Nesting error: credential_types_supported is at the agent_auth root instead of inside anonymous or identity_assertion. Mitigation: validate against the current schema; reject mis-nested structures.
auth.md H1 wrong: the file starts with a different heading (case, BOM, or alternate phrasing). Mitigation: enforce # Auth.md exactly; lint on the first non-empty line.
PKCE not asserted: metadata does not list code_challenge_methods_supported: ["S256"]. Mitigation: scanner must reject; CI must include the assertion.
OIDC registration endpoint unreachable: register_uri returns non-200. Mitigation: e2e test the POST endpoint before each deploy; surface the failure in the scanner report.
CORS blocking agent clients: cross-origin agent clients cannot fetch the metadata. Mitigation: set Access-Control-Allow-Origin per the deployment's CORS policy; verify with a preflight.

Security Guardrails (OWASP ASI)

ASI03 Identity & Privilege Abuse: the metadata defines the auth surface; do not include client secrets, signing keys, or unreleased callback URLs in the served JSON.
ASI04 Supply Chain: the metadata must be schema-validated against the current agent_auth draft before every deploy; reject schema-drifted metadata.
ASI05 RCE Guard: never construct metadata JSON from dynamic template strings derived from external content; build the JSON from a static schema and merge only allowlisted fields.
ASI07 Inter-Agent Communication: the metadata is consumed by external agents and scanners; treat it as a public contract and review all changes before deploy.
ASI09 Human-Agent Trust Exploitation: do not present a metadata set as "scanner-compliant" without a successful scanner run; surface the scanner output in the deploy record.

configure-oauth-metadata

Configure OAuth Metadata

Core Rules