--- title: Client ID Metadata Documents (CIMD) in the AuthPlayground description: Explore how Client ID Metadata Documents help OAuth servers discover and evaluate dynamic AI and MCP clients in the Identity for AI AuthPlayground. component: identity-for-ai page_id: identity-for-ai:protocols:authplayground-cimd canonical_url: https://developer.pingidentity.com/identity-for-ai/protocols/authplayground-cimd.html llms_txt: https://developer.pingidentity.com/identity-for-ai/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2026-08-24T07:38:08Z keywords: ["Identity for AI", "OAuth 2.0 protocols", "Client ID Metadata Documents", "CIMD", "dynamic AI clients", "MCP clients", "enterprise authorization", "AuthPlayground"] section_ids: the-cimd-model: The CIMD model why-this-matters-for-ai-and-mcp: Why this matters for AI and MCP the-authplayground-implementation: The AuthPlayground implementation step-1-fetch-authorization-server-metadata: "Step 1: Fetch authorization server metadata" step-2-send-an-authorization-request-with-the-client-identifier-url: "Step 2: Send an authorization request with the client identifier URL" step-3-retrieve-the-client-id-metadata-document: "Step 3: Retrieve the client ID metadata document" step-4-exchange-the-authorization-code: "Step 4: Exchange the authorization code" how-cimd-relates-to-other-concepts: How CIMD relates to other concepts cimd-helps-oauth-servers-identify-dynamic-clients: CIMD helps OAuth servers identify dynamic clients discovery-doesnt-mean-automatic-trust: Discovery doesn't mean automatic trust key-takeaways: Key takeaways --- # Client ID Metadata Documents (CIMD) in the AuthPlayground Helping authorization servers understand dynamic AI clients. Sarah asks the company's AI assistant to prepare her for the Apex Logistics meeting. The assistant might need Salesforce opportunity data, ServiceNow support history, and information from other enterprise systems. Traditional OAuth deployments often rely on client registration ahead of time. The authorization server already knows the client identifier, redirect URIs, authentication method, and other metadata. In dynamic AI and Model Context Protocol (MCP) ecosystems, clients and authorization servers can operate independently. What happens when the authorization server doesn't already have a registration relationship with an AI application or MCP client? Before the enterprise can decide what a client is allowed to access on Sarah's behalf, it needs to understand which client is making the request and where it can obtain the metadata describing this client. CIMD ([IETF draft](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/)) addresses this problem. ## The CIMD model Instead of using an opaque client identifier, such as `client_id=playground-demo-client`, in CIMD the MCP or OAuth client uses an HTTPS URL as its identifier: ``` client_id=https://.../cimd/clients/playground-demo-client ``` The HTTPS URL identifies a JSON metadata document describing the client. The client ID metadata document contains properties such as: ``` client_id client_name redirect_uris grant_types response_types token_endpoint_auth_method scope ``` The `client_id` is more than an opaque lookup value. It identifies the client and tells the authorization server where to retrieve the client's metadata. The specification places requirements on these identifiers. For example, the client identifier uses HTTPS and contains a path. The `client_id` inside the metadata document must exactly match the document URL. ### Why this matters for AI and MCP Imagine that Sarah's AI assistant invokes an independently deployed MCP client that needs OAuth access to continue the workflow. CIMD gives the client a way to identify itself using an HTTPS URL from which its metadata can be retrieved. This doesn't mean the authorization server automatically accepts an unknown client. CIMD changes how client metadata is discovered. The authorization server still decides which clients it accepts. ## The AuthPlayground implementation **Entities involved**: Client application, CIMD service, IdP (authorization server) The AuthPlayground demonstrates the [Client ID Metadata Document](https://www.authplayground.dev/flows/cimd) flow in four steps: 1. Fetch authorization server metadata. 2. Send an authorization request with the client identifier URL. 3. Retrieve the client ID metadata document. 4. Exchange the authorization code. ### Step 1: Fetch authorization server metadata The client retrieves the authorization server metadata: ```json GET /.well-known/oauth-authorization-server/idp Accept: application/json ``` The response returns metadata: ```json { "issuer": "https://.../idp", "authorization_endpoint": "https://.../idp/authorize", "token_endpoint": "https://.../idp/token", "pushed_authorization_request_endpoint": "https://.../idp/par", "client_id_metadata_document_supported": true, "code_challenge_methods_supported": [ "S256" ] } ``` The important signal is the `client_id_metadata_document_supported` property. A value of `true` tells the client that the authorization server supports CIMD. ### Step 2: Send an authorization request with the client identifier URL The client starts an Authorization Code flow with PKCE. The important difference is the client identifier. Instead of a simple string such as `client_id=playground-demo-client`, the playground uses a full URL: ```json GET /idp/authorize response_type=code client_id=https://.../cimd/clients/playground-demo-client redirect_uri=https://.../callback scope=openid profile email state= code_challenge= code_challenge_method=S256 ``` The HTTPS URL identifies both the client and the metadata document associated with it. The rest of the authorization request is familiar OAuth. ### Step 3: Retrieve the client ID metadata document The authorization server retrieves the metadata associated with the client identifier: ```json GET /cimd/clients/playground-demo-client Accept: application/json ``` The returned document describes the client: ```json { "client_id": "https://.../cimd/clients/playground-demo-client", "client_name": "AuthPlayground CIMD Demo Client", "client_uri": "https://www.pingidentity.com", "redirect_uris": [ "https://.../callback" ], "grant_types": [ "authorization_code" ], "response_types": [ "code" ], "token_endpoint_auth_method": "none", "scope": "openid profile email" } ``` Two relationships are particularly important: * The `client_id` inside the metadata document must match the URL used to identify the client in the authorization request. * The `redirect_uri` in the authorization request must appear in the metadata document's `redirect_uris` array. The authorization server now has metadata it can evaluate when deciding whether to proceed with the client. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | The playground uses `token_endpoint_auth_method=none` for this particular client. This is a playground example, not a requirement that all CIMD clients use no client authentication. CIMD can be used with appropriate asymmetric client-authentication mechanisms where supported. | ### Step 4: Exchange the authorization code The client performs the normal Authorization Code token exchange using PKCE: ```json POST /idp/token Content-Type: application/x-www-form-urlencoded grant_type=authorization_code code= redirect_uri=https://.../callback client_id=https://.../cimd/clients/playground-demo-client code_verifier= ``` Notice that the HTTPS URL continues to be used as the `client_id`. The resulting access token contains claims about the user and the client: ```json { "sub": "demo-user@example.com", "scope": "openid profile email", "client_id": "https://.../cimd/clients/playground-demo-client", "iss": "https://.../idp" } ``` CIMD hasn't introduced a new OAuth grant type. The flow is still Authorization Code with PKCE. What changed is how the client identifies itself and how the authorization server obtains the metadata needed to understand the client. ## How CIMD relates to other concepts ### CIMD helps OAuth servers identify dynamic clients To help Sarah prepare for her meeting, the MCP client fetching Salesforce and ServiceNow data needs OAuth access. The client uses an HTTPS metadata URL as its `client_id`. The authorization server retrieves the metadata document, evaluates the client identifier and redirect URI, and applies enterprise policy to decide whether to accept the client. If accepted, the authorization server issues an access token for the downstream integrations to Salesforce and ServiceNow. CIMD answers which OAuth client is participating in the workflow and where to obtain the metadata needed to evaluate it. CIMD doesn't answer: * What Salesforce data Sarah can access. That's an authorization question. * Who Sarah is. That's an identity question. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | | Salesforce and ServiceNow are examples of resources the AI workflow might need to reach. This doesn't imply that these SaaS platforms implement CIMD. | ### Discovery doesn't mean automatic trust CIMD makes client metadata discoverable, but doesn't make that metadata automatically trustworthy. The authorization server remains responsible for safely retrieving and evaluating the document and deciding whether the client is acceptable. An enterprise can explicitly onboard approved clients or combine CIMD with its own client governance policies. Easier discovery shouldn't become a shortcut around enterprise security controls. ## Key takeaways CIMD provides a standard model for making dynamic clients understandable to authorization servers. The client identifies itself with an HTTPS URL, the authorization server retrieves the associated metadata, and evaluates the client according to its own policy. In dynamic AI and MCP ecosystems, CIMD creates a useful bridge between dynamic software and enterprise OAuth infrastructure without requiring the authorization server to blindly trust unfamiliar clients.