PKCE S256 support: what the check tests and how to fix it

Weight 1.5. Passes when authorization server metadata lists S256 in code_challenge_methods_supported. Docs that only mention PKCE and S256 score partial.

Agent Auth · Weight 1.5 in the w2agent Score

How common is it?

22% of 667 measured sites where this check applied pass.

Latest audit of each site under rubric v3.1. Sites where the check did not apply or could not be measured (for example, no llms.txt for the llms.txt checks) are left out. A partial result does not count as a pass.

What this check tests

The check reads one field. It takes the authorization server document that the OAuth discovery check resolved and looks at code_challenge_methods_supported.

  • Pass 100: the array contains the exact string S256.
  • Partial 50: the field does not say S256, but the developer portal text contains both "PKCE" and "S256" (case-insensitive, anywhere in the page, not necessarily next to each other). The message says PKCE is mentioned in docs but not declared in metadata.
  • Fail 0: neither, or no developer portal was found.
  • Skip: the portal probes received no response at all. A fail is also changed to skip when both the OAuth discovery check and the portal check failed or were skipped, which is what a site with no API and no OAuth gets. A pass or partial is kept.

The metadata is only read when discovery ended with a full chain or with a valid root /.well-known/oauth-authorization-server. If discovery stopped at protected resource metadata with no usable authorization server, there is no metadata to read, and the check falls back to the portal text. The field is a declaration; the audit does not run an authorization flow to see whether the server enforces PKCE.

Why it matters to agents

PKCE has the client send a hash of a secret with the authorization request and the secret itself with the token request, so a stolen authorization code is useless on its own. RFC 7636 makes S256 mandatory to implement on servers that support PKCE and says a client that can use S256 MUST use it; plain exists only for constrained clients.

The client cannot find out whether a server supports PKCE except from metadata. RFC 8414 defines code_challenge_methods_supported for this. The MCP authorization specification (2026-07-28) tells clients to read it and to refuse to proceed if the field is absent, so an MCP client will not authorize against a server that does not declare it, whatever the server actually does. It also says that providers using OpenID Connect Discovery must include the field, because the OpenID metadata does not define it.

This applies only if you run an OAuth authorization server for agents. A site without one is not affected.

How to fix it

Two steps, in this order:

  1. Support PKCE with S256 in the authorization endpoint and token endpoint. Most authorization server software and hosted identity providers already do; enable it in their settings rather than writing it yourself, and check their documentation.
  2. Declare it in the metadata the audit reads:
{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/authorize",
  "token_endpoint": "https://auth.example.com/token",
  "code_challenge_methods_supported": ["S256"]
}

Serve this at /.well-known/oauth-authorization-server, with issuer identical to the authorization server identifier clients know you by (RFC 8414 section 3.3), which is the issuer URL without the /.well-known/ part. If you also serve OpenID Connect discovery, add the same field there. Do not list plain unless you must.

Confirm with curl -s https://auth.example.com/.well-known/oauth-authorization-server. The metadata must be reachable by the chain described on the OAuth discovery page; Client ID Metadata Documents is a separate flag in the same document.

Examples from measured sites

Up to 10 of the highest-scoring sites in each group, from recent audits. Failing includes partial results.

Passing

Failing or partial

Sources

Verified against these sources on

Does your site pass this check?

Check your own site →