OAuth was built on the assumption that every client is registered with the authorisation server before it is used, which breaks down when thousands of AI agents and MCP clients need to connect to servers they have never met. OAuth Client ID Metadata Documents (CIMD) solve this by making the client_id an HTTPS URL that points to a JSON document describing the client, so the authorisation server learns about the client by fetching that URL. The Model Context Protocol authorisation specification (version 2025-11-25) now prefers CIMD over Dynamic Client Registration. This guide explains how CIMD works, what the draft requires, how to set a trust policy, and how to defend against the risks it introduces: server-side request forgery, localhost impersonation and phishing through borrowed client names. It is for authorisation server operators, MCP server owners and teams building agent clients.
Key takeaways
- The URL is the identity. A CIMD client is identified by an HTTPS URL it controls; the document at that URL must state the same
client_id, and the server compares them exactly. - No shared secrets, ever. The draft forbids
client_secret_*methods and private key material in the document. Confidential clients publish public keys and useprivate_key_jwt. - Fetching is an attack surface. The authorisation server makes outbound requests to URLs supplied by strangers, so SSRF controls (no special-use IP addresses, no redirects, a 5 KB read limit) are mandatory engineering, not options.
- CIMD proves who publishes the metadata, not who is running the client. Anyone can present a public client's URL; with localhost redirect URIs the server cannot tell the real app from an impersonator.
- A trust policy turns CIMD into governance. Decide per server whether to accept any HTTPS client, an allowlist of domains, or reputation-checked domains, and show the client hostname on every consent screen.
What CIMD is and its status
CIMD is defined in draft-ietf-oauth-client-id-metadata-document, an OAuth Working Group Internet-Draft by Aaron Parecki and Emelia Smith. When checked on 27 October 2026 the current version was -02, dated 6 July 2026 and expiring 7 January 2027. It is a draft, so details may change; the core idea has been stable since the individual draft it replaced. The MCP 2025-11-25 authorisation specification references the -00 version and says authorisation servers and MCP clients SHOULD support it. The AT Protocol (used by Bluesky) uses the same model, with a URL client_id pointing to client metadata.
See the MCP Authorisation Specification Guide for the full MCP flow and the OAuth 2.1, GNAP and FAPI Guide for where CIMD sits in the wider OAuth landscape.
Client registration options compared
| Approach | How the server learns about the client | Strengths | Weaknesses | Best fit |
|---|---|---|---|---|
| Pre-registration | Administrator or developer portal creates the client | Full vetting, known owner, strongest trust | Does not scale to unknown clients | Enterprise apps, partners, high-value APIs |
| Dynamic Client Registration (RFC 7591) | Client POSTs metadata to /register and receives a client_id (often a secret) | Standardised, widely implemented | Unbounded registrations, secrets issued to unknown parties, no stable identity across servers | Backwards compatibility; MCP lists it as a fallback |
| Client ID Metadata Document | Server fetches the JSON at the client_id URL | Same identity at every server, no registration state, owner controls updates, no secrets | SSRF risk, impersonation of public clients, trust depends on domain | MCP clients, agents and tools meeting servers for the first time |
| Software statements | Signed assertion about the client from a trusted issuer | Third-party vouching | Needs an ecosystem issuer | Federated or regulated ecosystems |
The MCP specification gives clients that support all options a priority order: use pre-registered details if available, then CIMD if the server advertises client_id_metadata_document_supported, then Dynamic Client Registration if a registration_endpoint exists, then prompt the user. See the OAuth Dynamic Client Registration Security Guide for hardening the fallback.
How the flow works
- Discovery: the client reads the authorisation server metadata and checks
client_id_metadata_document_supported: true. - Authorisation request: the client sends its URL as
client_id, for examplehttps://app.example.com/oauth/client-metadata.json, with its redirect URI, PKCE challenge and, in MCP, theresourceparameter. - Fetch: the server detects a URL-formatted client_id and fetches the document (or uses a cached copy), without following redirects.
- Validate: the document is valid JSON, its
client_idmatches the URL exactly, the redirect URI in the request exactly matches one inredirect_uris, and the domain passes the server's trust policy. - Consent: the server shows the
client_nameand, critically, the client_id hostname and redirect URI hostname. - Token exchange: the client redeems the code with the same client_id, authenticating with
private_key_jwtusing keys from the document if it is confidential, or as a public client with PKCE.
Rules for the client_id URL and the document
| Element | Requirement (draft -02 unless noted) |
|---|---|
| Scheme and path | https scheme, must contain a path; no userinfo or fragment; should not include a query; no . or .. segments |
| Comparison | Exact string matching, so an explicit :443 is a different identifier |
| Stability | Short, stable URLs recommended; root paths and URL shorteners discouraged (shorteners rely on redirects, which are not followed) |
client_id in the document | Must match the URL fetched |
| Required fields in MCP | client_id, client_name, redirect_uris (MCP 2025-11-25) |
| Authentication method | MUST NOT be client_secret_post, client_secret_basic, client_secret_jwt or any shared-secret method |
| Keys | Public keys via jwks or jwks_uri; private key material MUST NOT be included |
| HTTP response | 200 status; servers should cap reads at 5 KB and treat larger responses as errors |
| Caching | Respect HTTP cache headers, with server-defined upper and lower bounds; never cache errors or invalid documents |
Threats and controls for authorisation server operators
| Threat | How it works | Controls |
|---|---|---|
| Server-side request forgery (CAPEC-664) | Attacker supplies a client_id URL that resolves to an internal address or cloud metadata endpoint | Draft Section 8.6: MUST NOT fetch URLs resolving to special-use IP addresses (RFC 6890); resolve then check the IP at connect time to defeat DNS rebinding; egress through a dedicated fetcher with network policy; https only; no redirects |
| Resource exhaustion | Huge or slow documents, many unique URLs | 5 KB read limit, short timeouts, rate limits per domain, bounded cache |
| Localhost impersonation | Attacker presents a legitimate public client's URL and a localhost redirect URI on a port they control, receiving the code when the user approves | MCP: SHOULD warn on localhost-only redirect URIs, MAY require attestation, MUST display the redirect URI hostname; restrict high-privilege scopes for such clients |
| Phishing with borrowed names | Attacker hosts a document with a trusted-looking client_name and logo | Display the client_id hostname prominently; prefetch and moderate logos; reputation checks for unknown domains |
| Metadata changes after consent | Owner (or attacker who controls the host) changes redirect URIs, scopes or keys | Draft Section 8.4: assess changes; on key or redirect changes, revoke tokens or re-request consent |
| Domain takeover | Expired domain or hijacked hosting lets an attacker serve the document for a trusted client_id | Allowlists for protected servers, domain age checks, monitoring of trusted client documents |
| Development services treated as trusted | Shared hosting that issues temporary client URLs | Label such clients clearly and never grant full trust |
Note on loopback: the draft allows loopback fetches only in development deployments where the authorisation server itself runs on loopback and says this exception MUST NOT be applied in production. Redirect URIs on localhost are a separate matter: they remain legitimate for native and desktop MCP clients, which is exactly why impersonation is hard to rule out.
Why localhost impersonation matters for agents
Many MCP clients are desktop or command-line tools that receive the authorisation code on http://127.0.0.1:<port>/callback. The MCP example document uses token_endpoint_auth_method: none with localhost redirect URIs. For such a public client, any local process (or a malicious tool the user installed) can present the same client_id. The user sees the genuine client's name; the server sees the genuine document. CIMD cannot fix this on its own. Practical mitigations are to warn the user, limit scopes and token lifetimes for localhost-only public clients, prefer clients that hold keys (private_key_jwt) for privileged access, and watch for attestation mechanisms such as the OAuth Attestation-Based Client Authentication Guide describes.
Designing a trust policy
| Policy | What it accepts | When to choose it |
|---|---|---|
| Open | Any HTTPS client_id that passes validation | Public MCP servers with low-risk, read-only scopes |
| Reputation-gated | Any domain, with warnings or limits for new, unknown or low-reputation domains | Public servers with some sensitive scopes |
| Allowlist | Only approved client domains or exact client_id URLs | Enterprise servers, internal data, regulated workloads |
| Allowlist plus key requirement | Approved client_ids that also authenticate with private_key_jwt | Write access, financial or personal data |
Decision guidance: an organisation exposing internal tools through an MCP server should start with an allowlist; CIMD then gives it a stable, auditable identifier per approved client rather than a pile of anonymous dynamic registrations. A public developer platform will usually run reputation-gated policy and rely on scope design. Small teams can implement the allowlist as a simple list of exact client_id URLs; large platforms need domain-level rules, reputation data and an approval workflow. Map each client_id to an owner in your NHI inventory, the same as any other machine identity.
Where identity fits
A CIMD client is a non-human identity like any other OAuth client, but its definition lives outside your control, on someone else's web server. That changes how it should be governed.
- Inventory by URL: record each client_id URL your servers have issued tokens to, the scopes granted, the users who consented and the last time the document was fetched. Unlike dynamic registrations, the same URL identifies the client at every server, so the inventory can be shared across an organisation's MCP servers.
- Owner of record: for allowlisted clients, name an internal owner who is accountable for reviewing the vendor or project that publishes the document.
- Agents acting for users: tokens issued to an agent client through CIMD carry the consenting user's authority. Review them with the same rigour as delegated SaaS grants. See the SaaS and OAuth App Governance Guide.
- Offboarding: when a client is removed from the allowlist, revoke its refresh tokens; removal from the policy alone does not end existing grants.
Rolling out CIMD
- Decide policy first: pick open, reputation-gated or allowlist per server and per scope set, and write down who approves new client domains.
- Build the fetcher: a dedicated, isolated service that enforces https, no redirects, special-use IP blocking after DNS resolution, a 5 KB limit, timeouts and caching bounds. Test it with internal addresses, cloud metadata addresses, redirect chains and oversized responses before exposing it.
- Validate strictly: exact client_id match, required fields, exact redirect URI matching, no shared-secret methods, and key retrieval only from the document's
jwksorjwks_uri. - Update consent screens: show the client_id hostname and redirect URI hostname, plus warnings for localhost-only and unknown-domain clients.
- Pilot: advertise
client_id_metadata_document_supportedon a staging server, onboard known clients, and keep Dynamic Client Registration available as the fallback. - Enforce and review: enable in production, monitor metadata changes and fetch failures, and reduce Dynamic Client Registration where CIMD covers the same clients.
- Rollback: set
client_id_metadata_document_supportedto false; compliant clients fall back to DCR or pre-registration. Existing tokens remain subject to normal revocation.
For client publishers: host the document at a stable path on a domain you control with strong DNS and hosting protections, list exact redirect URIs, never include secrets, use private_key_jwt with the issuer as audience when you can hold a key (see the JWT Client Authentication Guide), and treat a change to the document as a production change.
Detection and measurement
- Fetcher logs: every fetch with client_id URL, resolved IP, status, size and duration; blocked special-use addresses are a strong SSRF signal.
- Change monitoring: hash each cached document and alert when redirect URIs, keys or authentication method change for a client with active grants.
- Consent analytics: new client domains, localhost-only clients requesting sensitive scopes, and look-alike hostnames.
- Token use: tokens issued to a CIMD client used from unexpected networks (ATT&CK T1528 Steal Application Access Token).
| Metric | Target |
|---|---|
| Fetches blocked by SSRF rules investigated | 100% |
| CIMD clients with a named owner (allowlist servers) | 100% |
| Metadata changes on clients with active grants reviewed | 100% within one working day |
| Privileged scopes granted to localhost-only public clients | Zero, or explicitly approved |
| Share of new client onboarding via CIMD rather than DCR | Rising |
Framework mapping
| Framework | Reference | CIMD relevance |
|---|---|---|
| OWASP ASVS 5.0 | V1.3.6, V15.3.2 | SSRF protection with allowlists; outbound calls do not follow redirects |
| OWASP ASVS 5.0 | V10.4.7 | Mitigating malicious clients when registration is open |
| OWASP ASVS 5.0 | V10.7.1, V10.7.2 | Consent with clear client information when identity cannot be assured |
| NIST SP 800-53 Rev. 5 | SC-7 Boundary Protection; SA-9 External System Services | Fetcher egress control; trust in externally hosted client metadata |
| NIST CSF 2.0 | ID.AM-02, PR.AA-05 | Inventory of clients and services; policy for which clients get access |
| MITRE CAPEC and ATT&CK | CAPEC-664, T1566.002, T1528 | SSRF; consent phishing via links; token theft |
Common failure patterns
- Naive fetcher: the authorisation server fetches client_id URLs with a general HTTP library that follows redirects and reaches internal addresses.
- Trusting client_name: consent screens show only the display name and logo, so a look-alike domain borrows a trusted brand. See the Consent Phishing and Illicit OAuth Grants Guide.
- Prefix matching of redirect URIs: the document lists one URI and the server accepts anything under it, undoing exact matching.
- Ignoring metadata drift: a client's redirect URIs or keys change after consent and existing grants keep working without review.
- Treating CIMD as authentication: high-privilege scopes granted to public localhost clients on the basis that "the document checked out".
- Caching errors: a failed or invalid fetch is cached, breaking legitimate clients or freezing a bad state.
Practitioner checklist
- Choose a trust policy per server and scope set, with a named approver for new client domains.
- Run CIMD fetches through an isolated fetcher with https only, no redirects, special-use IP blocking after resolution, 5 KB limit and timeouts.
- Validate exact client_id match, required fields and exact redirect URI matching.
- Reject documents that declare shared-secret authentication or contain private keys.
- Show client_id hostname and redirect URI hostname on consent, with warnings for localhost-only clients.
- Limit scopes and lifetimes for public localhost clients; require
private_key_jwtfor privileged access. - Monitor document changes and revoke or re-consent on key or redirect changes.
- Keep Dynamic Client Registration hardened as a fallback, and reduce it as CIMD adoption grows.
- Track the draft version and update validation rules when it changes.
Standards and references
- IETF: draft-ietf-oauth-client-id-metadata-document OAuth Client ID Metadata Document (Internet-Draft)
- Model Context Protocol: Authorization specification (2025-11-25)
- IETF: RFC 7591 OAuth 2.0 Dynamic Client Registration Protocol
- IETF: RFC 8414 OAuth 2.0 Authorization Server Metadata
- IETF: RFC 9700 Best Current Practice for OAuth 2.0 Security
- IETF: draft-ietf-oauth-rfc7523bis, update to RFC 7523 audience rules (Internet-Draft)
- AT Protocol: OAuth specification
Related NHI Mgmt Group resources: MCP Authorisation Specification Guide · OAuth Dynamic Client Registration Security Guide · OAuth 2.1, GNAP and FAPI Guide · JWT Client Authentication Guide