Join our Newsletter — 33% off our NHI Course
Home› Guides› OAuth Client ID Metadata Documents (CIMD) Guide: Client…
Guide Agent Identity & Access

OAuth Client ID Metadata Documents (CIMD) Guide: Client Identity Without Pre-Registration

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 27 October 2026 13 min read
On this page

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 use private_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

ApproachHow the server learns about the clientStrengthsWeaknessesBest fit
Pre-registrationAdministrator or developer portal creates the clientFull vetting, known owner, strongest trustDoes not scale to unknown clientsEnterprise 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 implementedUnbounded registrations, secrets issued to unknown parties, no stable identity across serversBackwards compatibility; MCP lists it as a fallback
Client ID Metadata DocumentServer fetches the JSON at the client_id URLSame identity at every server, no registration state, owner controls updates, no secretsSSRF risk, impersonation of public clients, trust depends on domainMCP clients, agents and tools meeting servers for the first time
Software statementsSigned assertion about the client from a trusted issuerThird-party vouchingNeeds an ecosystem issuerFederated 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

  1. Discovery: the client reads the authorisation server metadata and checks client_id_metadata_document_supported: true.
  2. Authorisation request: the client sends its URL as client_id, for example https://app.example.com/oauth/client-metadata.json, with its redirect URI, PKCE challenge and, in MCP, the resource parameter.
  3. Fetch: the server detects a URL-formatted client_id and fetches the document (or uses a cached copy), without following redirects.
  4. Validate: the document is valid JSON, its client_id matches the URL exactly, the redirect URI in the request exactly matches one in redirect_uris, and the domain passes the server's trust policy.
  5. Consent: the server shows the client_name and, critically, the client_id hostname and redirect URI hostname.
  6. Token exchange: the client redeems the code with the same client_id, authenticating with private_key_jwt using keys from the document if it is confidential, or as a public client with PKCE.

Rules for the client_id URL and the document

ElementRequirement (draft -02 unless noted)
Scheme and pathhttps scheme, must contain a path; no userinfo or fragment; should not include a query; no . or .. segments
ComparisonExact string matching, so an explicit :443 is a different identifier
StabilityShort, stable URLs recommended; root paths and URL shorteners discouraged (shorteners rely on redirects, which are not followed)
client_id in the documentMust match the URL fetched
Required fields in MCPclient_id, client_name, redirect_uris (MCP 2025-11-25)
Authentication methodMUST NOT be client_secret_post, client_secret_basic, client_secret_jwt or any shared-secret method
KeysPublic keys via jwks or jwks_uri; private key material MUST NOT be included
HTTP response200 status; servers should cap reads at 5 KB and treat larger responses as errors
CachingRespect HTTP cache headers, with server-defined upper and lower bounds; never cache errors or invalid documents

Threats and controls for authorisation server operators

ThreatHow it worksControls
Server-side request forgery (CAPEC-664)Attacker supplies a client_id URL that resolves to an internal address or cloud metadata endpointDraft 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 exhaustionHuge or slow documents, many unique URLs5 KB read limit, short timeouts, rate limits per domain, bounded cache
Localhost impersonationAttacker presents a legitimate public client's URL and a localhost redirect URI on a port they control, receiving the code when the user approvesMCP: 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 namesAttacker hosts a document with a trusted-looking client_name and logoDisplay the client_id hostname prominently; prefetch and moderate logos; reputation checks for unknown domains
Metadata changes after consentOwner (or attacker who controls the host) changes redirect URIs, scopes or keysDraft Section 8.4: assess changes; on key or redirect changes, revoke tokens or re-request consent
Domain takeoverExpired domain or hijacked hosting lets an attacker serve the document for a trusted client_idAllowlists for protected servers, domain age checks, monitoring of trusted client documents
Development services treated as trustedShared hosting that issues temporary client URLsLabel 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

PolicyWhat it acceptsWhen to choose it
OpenAny HTTPS client_id that passes validationPublic MCP servers with low-risk, read-only scopes
Reputation-gatedAny domain, with warnings or limits for new, unknown or low-reputation domainsPublic servers with some sensitive scopes
AllowlistOnly approved client domains or exact client_id URLsEnterprise servers, internal data, regulated workloads
Allowlist plus key requirementApproved client_ids that also authenticate with private_key_jwtWrite 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

  1. Decide policy first: pick open, reputation-gated or allowlist per server and per scope set, and write down who approves new client domains.
  2. 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.
  3. Validate strictly: exact client_id match, required fields, exact redirect URI matching, no shared-secret methods, and key retrieval only from the document's jwks or jwks_uri.
  4. Update consent screens: show the client_id hostname and redirect URI hostname, plus warnings for localhost-only and unknown-domain clients.
  5. Pilot: advertise client_id_metadata_document_supported on a staging server, onboard known clients, and keep Dynamic Client Registration available as the fallback.
  6. Enforce and review: enable in production, monitor metadata changes and fetch failures, and reduce Dynamic Client Registration where CIMD covers the same clients.
  7. Rollback: set client_id_metadata_document_supported to 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).
MetricTarget
Fetches blocked by SSRF rules investigated100%
CIMD clients with a named owner (allowlist servers)100%
Metadata changes on clients with active grants reviewed100% within one working day
Privileged scopes granted to localhost-only public clientsZero, or explicitly approved
Share of new client onboarding via CIMD rather than DCRRising

Framework mapping

FrameworkReferenceCIMD relevance
OWASP ASVS 5.0V1.3.6, V15.3.2SSRF protection with allowlists; outbound calls do not follow redirects
OWASP ASVS 5.0V10.4.7Mitigating malicious clients when registration is open
OWASP ASVS 5.0V10.7.1, V10.7.2Consent with clear client information when identity cannot be assured
NIST SP 800-53 Rev. 5SC-7 Boundary Protection; SA-9 External System ServicesFetcher egress control; trust in externally hosted client metadata
NIST CSF 2.0ID.AM-02, PR.AA-05Inventory of clients and services; policy for which clients get access
MITRE CAPEC and ATT&CKCAPEC-664, T1566.002, T1528SSRF; 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_jwt for 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

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

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 27 October 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.