Client ID Metadata Documents: what the check tests and how to fix it

Bonus, weight 0.5. Passes when authorization server metadata sets client_id_metadata_document_supported to true. Never lowers a score; otherwise skipped.

Agent Auth · Weight 0.5 in the w2agent Score

How common is it?

4% of 1223 measured sites publish a passing result (observed adoption).

Latest audit of each site under rubric v3.1. A site with nothing published counts as not passing. A partial result does not count as a pass.

What this check tests

This is a bonus check. It can raise your score by its small weight (0.5) but it cannot lower it, because it returns only two results.

It uses the authorization server document that the OAuth discovery check resolved, and only when that check ended with a full chain from a protected resource to an authorization server with both authorization_endpoint and token_endpoint.

  • Pass 100: the document has client_id_metadata_document_supported set to the JSON value true. A string "true" does not count.
  • Skip: everything else. That covers no resolved chain (including a site with no OAuth at all), and a server that does not set the flag. If the server has a registration_endpoint the message says it offers Dynamic Client Registration but not Client ID Metadata Documents.

Because absence is a skip, the rate shown on this page counts every measured site that did not pass as not adopting, including those that have no authorization server at all. It is a share of all measured sites, not of OAuth servers.

Why it matters to agents

An agent usually has no prior relationship with your authorization server. The older fix was Dynamic Client Registration, where each client registers itself and receives a client ID. The IETF draft takes another route: the client uses an HTTPS URL as its client_id, and the authorization server fetches the JSON document at that URL to learn the client's name and redirect URIs. No registration step is needed.

The draft defines the client_id_metadata_document_supported flag so that clients can avoid sending a user to an authorization server that would reject their URL-style client ID. The MCP authorization specification (2026-07-28) says authorization servers and clients SHOULD support these documents and describes Dynamic Client Registration as deprecated and kept for backward compatibility. A client that knows the flag is true can use the flow; otherwise it falls back.

Keep the status in mind. The document is an IETF Internet-Draft, a work in progress, and the draft can change. The MCP specification cites an earlier revision. The audit treats it as a bonus rather than a requirement. It only applies if you run your own OAuth authorization server.

How to fix it

Do this only if you operate the authorization server and can implement the draft's server behavior. Setting the flag without the behavior misleads clients.

  1. Implement the fetch: when client_id is an HTTPS URL, retrieve the document, require a 200 response without following redirects, check that its client_id equals the URL, and check the authorization request's redirect URI against the document. The MCP client registration page summarizes these rules, and the draft has the security considerations, including protection against server-side request forgery.
  2. Declare it in the metadata served at /.well-known/oauth-authorization-server:
{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/authorize",
  "token_endpoint": "https://auth.example.com/token",
  "client_id_metadata_document_supported": true
}

If you use a hosted identity provider, check its documentation for support before you rely on this. The flag is a single field next to the one that PKCE S256 reads.

Examples from measured sites

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

Passing

Sources

Verified against these sources on

Does your site pass this check?

Check your own site →