---
title: Client ID metadata document (CIMD)
description: Configure Advanced Identity Cloud to accept OAuth 2.0 clients that identify themselves using a URL pointing to a hosted JSON metadata document, without requiring prior registration.
component: pingoneaic
page_id: pingoneaic:am-oauth2:oauth2-cimd
canonical_url: https://docs.pingidentity.com/pingoneaic/am-oauth2/oauth2-cimd.html
llms_txt: https://docs.pingidentity.com/pingoneaic/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
revdate: 2026-09-07T20:35:41Z
keywords: ["OAuth 2.0", "CIMD", "Client ID Metadata Document", "AI agents", "MCP", "dynamic client", "registration"]
section_ids:
  cimd-how-it-works: How it works
  cimd-document-format: Document format
  cimd-supported-grants: Grant types
  cimd-supported-auth-methods: Authentication methods
  cimd-limitations: Limitations
  cimd-configure: Configure a CIMD profile
  cimd-example-flow: Example authorization code flow
---

# Client ID metadata document (CIMD)

The client ID metadata document (CIMD) feature lets you configure OAuth 2.0 clients to identify themselves using an HTTPS URL as their `client_id`. Advanced Identity Cloud fetches the JSON metadata document at that URL and uses it to configure the client at runtime, with no prior registration required.

CIMD is particularly suited to large numbers of clients such as [AI agents](../identity-for-ai/ai-agent-identities.html) in Model Context Protocol (MCP) flows, where preregistering every short-lived or externally-hosted client is impractical.

Advanced Identity Cloud's support for CIMD aligns with the [IETF OAuth Client ID Metadata Document draft specification](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/).

## How it works

When Advanced Identity Cloud receives an OAuth 2.0 request with a `client_id` that begins with `https://`, it treats the value as a URL pointing to a CIMD document and performs the following steps:

![How CIMD works](_images/oauth2-cimd-how-it-works.svg)

1. Advanced Identity Cloud receives a request with a URL-valued `client_id`.

2. Advanced Identity Cloud checks the realm for a CIMD profile whose URL pattern matches the `client_id`.

   If no matching profile exists, or if more than one profile matches, Advanced Identity Cloud rejects the request with an `invalid_client` error.

3. A matching CIMD profile defines the security settings that Advanced Identity Cloud applies to the request.

4. Advanced Identity Cloud fetches the JSON document at the `client_id` URL over HTTPS.

   Redirects aren't followed. Only an HTTP 200 response is accepted.

5. Advanced Identity Cloud receives the metadata document and …​

6. …​ validates that the document's own `client_id` field exactly matches the URL it was fetched from.

   If validation fails, the request is rejected with an `invalid_client` error.

7. Advanced Identity Cloud applies the security checks defined in the matching CIMD profile, including server-side request forgery (SSRF) protection and metadata denylist.

8. If the security checks are successful, Advanced Identity Cloud uses the fetched metadata as the client's runtime configuration for the flow.

9. The resulting client exists only for the duration of the flow and isn't persisted to the identity store.

10. The OAuth 2.0 flow continues.

## Document format

The metadata document follows the RFC 7591 [OAuth 2.0 Dynamic Client Registration Protocol](https://www.rfc-editor.org/rfc/rfc7591) client metadata format.

Example document:

```json
{
  "client_id": "https://app.example.com/oauth/client.json",
  "client_name": "Example MCP Client",
  "client_uri": "https://app.example.com",
  "redirect_uris": [
    "https://app.example.com/callback"
  ],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "scope": "read write"
}
```

When Advanced Identity Cloud processes a CIMD metadata document, it applies the following constraints:

* The `client_id` must be an HTTPS URL that exactly matches the URL where the document is hosted.

* The following secret-based authentication fields are rejected:

  * `client_secret`

  * `client_secret_expires_at`

  * `token_endpoint_auth_method` secret values (`client_secret_basic`, `client_secret_post`, `client_secret_jwt`)

* The document must not exceed 5 KB.

* The following fields support localization using locale tags, for example `client_name#en` or `client_name#fr`:

  * `client_name`

  * `client_uri`

  * `logo_uri`

  * `policy_uri`

  * `tos_uri`

Learn more about metadata document constraints in the [Limitations](#cimd-limitations) section.

The matching CIMD profile and the metadata document both contribute to the client's runtime configuration. For each metadata field, Advanced Identity Cloud resolves the value in the following order:

1. If the field is in the profile's metadata override denylist, the profile's value is used.

2. Otherwise, if the document specifies the field, the document's value overrides the profile's value.

3. If neither the document nor the profile specifies a value, Advanced Identity Cloud applies the following defaults:

| Field                        | Default                     |
| ---------------------------- | --------------------------- |
| `scope`                      | The realm's default scopes. |
| `grant_types`                | `authorization_code`        |
| `response_types`             | `code`                      |
| `token_endpoint_auth_method` | `none`                      |

|   |                                                                                                                                                                                                                       |
| - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   | Redirect URIs aren't required to share the same origin as the `client_id` URL. You can add `redirect_uri` to the override denylist to enforce that the requested redirect URI must be configured in the CIMD profile. |

### Grant types

The following grant types are available to CIMD clients:

* `authorization_code`

* `client_credentials`

* `refresh_token`

* `urn:ietf:params:oauth:grant-type:device_code`

* `urn:ietf:params:oauth:grant-type:jwt-bearer`

* `urn:ietf:params:oauth:grant-type:token-exchange`

A client's declared `grant_types` are filtered to the intersection of this list and the grant types enabled in the realm's OAuth 2.0 provider.

If a client declares grant types but none survive the filtering, Advanced Identity Cloud rejects the request. This prevents a client from accidentally proceeding with a misconfigured or entirely unsupported set of grant types.

### Authentication methods

The following token endpoint authentication methods are available to CIMD clients:

* `none`

* `private_key_jwt`

* `tls_client_auth`

* `self_signed_tls_client_auth`

|   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   | You can't set the client type. Advanced Identity Cloud derives it from the authentication method in the metadata document:* `private_key_jwt`, `tls_client_auth`, or `self_signed_tls_client_auth` produces a confidential client.

* Any other method produces a public client.CIMD clients are public by design but can authenticate confidentially using `private_key_jwt` or mTLS. This is what enables flows such as `client_credentials` for CIMD clients. |

## Limitations

The following features aren't supported for CIMD clients:

* UMA (User-Managed Access)

* CIBA (Client-Initiated Backchannel Authentication)

* Backchannel logout. Advanced Identity Cloud ignores `backchannel_logout_uri` and `backchannel_logout_session_required` in the metadata document.

* Wildcard ports in CIMD profile URL patterns, for example `https://app.example.com:*/`

* Client secrets and symmetric authentication methods

* Setting the client type (public or confidential). This is derived from the authentication method in the metadata document.

* Authorization response signing and encryption

The CIMD profile doesn't expose the following OAuth 2.0 client properties, and CIMD documents can't set them:

* JavaScript origins

* Access token endpoint override

* Software identity and version (`software_id` and `software_version`)

* Group

* Secret label identifier

Additionally, CIMD has the following constraints:

* If the matching profile requires pushed authorization requests, CIMD clients must use a [pushed authorization request (PAR)](oauth2-authz-grant-par.html).

  A direct authorization request without PAR is rejected.

* Advanced Identity Cloud doesn't advertise support for CIMD in its authorization server metadata yet, so clients can't tell whether a realm supports CIMD until they try a CIMD flow.

## Configure a CIMD profile

CIMD is controlled by *CIMD profiles*. Each profile defines a URL pattern that Advanced Identity Cloud matches against incoming `client_id` values, along with security settings for that pattern. You configure CIMD profiles per realm in the Advanced Identity Cloud admin console.

|   |                                                                                                                                                       |
| - | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
|   | You use CIMD profiles to allow or deny specific origins. If no CIMD profile matches the `client_id` URL, Advanced Identity Cloud rejects the request. |

1. Under Native Consoles > Access Management, go to Realms > *realm name* > Applications > OAuth 2.0 > CIMD Profiles.

2. Click Add CIMD Profile.

3. Enter a unique CIMD profile name that adheres to the following rules:

   * Must not start with the `#` or `"` characters.

   * Must not start or end with the space character.

   * Must not contain any of the following characters: `\/+;,%[]|?`.

   * Must not be `.` or `..`.

4. Enter a valid CIMD Client ID URL Pattern that starts with `https://`. Advanced Identity Cloud matches the URL pattern against incoming `client_id` values. For example, `https://app.example.com/*` allows all CIMD clients hosted under that origin.

5. Click Create.

6. Configure additional profile properties as required and save your changes.

   | Property                         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                          |
   | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | CIMD Client ID URL Patterns      | *Required*. One or more HTTPS URLs that the `client_id` value must match.Only `https://` patterns are accepted. Wildcard paths are accepted, for example `https://app.example.com/*` allows all CIMD clients hosted under that origin. An explicit port is allowed, for example `https://app.example.com:8443/*`, but wildcard ports aren't.                                                                                                         |
   | CIMD Metadata Override Deny List | *Optional*. A list of metadata field names that always use the profile value. Advanced Identity Cloud ignores the corresponding fields in CIMD documents matched by this profile. For example, select `scope` from the list to ensure the client can't override the scope in the profile with a different value in its metadata document.Use this to prevent clients from asserting sensitive metadata values that your realm policy doesn't permit. |
   | CIMD SSRF Protection Enabled     | When `true`, Advanced Identity Cloud blocks `client_id` URLs that resolve to special-use or loopback IP addresses, to prevent SSRF attacks.Only set to `false` in controlled test environments where the CIMD server runs on loopback.Default: `true`                                                                                                                                                                                                |

## Example authorization code flow

1. [Configure a CIMD profile](#cimd-configure) that allows the client to use its metadata document URL as the `client_id`.

   For test purposes, use the following values in the [example metadata document](#cimd-document-format) to create the profile:

   * CIMD Client ID URL Pattern

     `https://app.example.com/oauth/client.json`

   * CIMD Metadata Override Deny List

     `scope`

   * CIMD SSRF Protection Enabled

     `false`

2. Save the profile.

3. On the Core tab in the client profile, set Scope(s) to `openid` and save your changes.

4. [Get an authorization code](oauth2-authz-grant.html#proc-auth-code-browser) in a browser using the metadata document URL as the `client_id`:

   ```none
   https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/authorize
     ?client_id=https%3A%2F%2Fapp.example.com%2Foauth%2Fclient.json
     &response_type=code
     &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
     &scope=read
     &state=state
   ```

   |   |                                            |
   | - | ------------------------------------------ |
   |   | The URL is split for readability purposes. |

   Advanced Identity Cloud fetches and validates the metadata document, then proceeds with the standard flow.

5. [Exchange the authorization code for an access token](oauth2-authz-grant.html#proc-auth-code-token) using the same `client_id` URL:

   ```bash
   $ curl \
   --request POST \
   --data "grant_type=authorization_code" \
   --data "code=authorization-code" \
   --data "client_id=https://app.example.com/oauth/client.json" \
   --data "redirect_uri=https://app.example.com/callback" \
   'https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/access_token'
   {
     "access_token": "access-token",
     "refresh_token": "refresh-token",
     "scope":"openid",
     "id_token":"id-token",
     "token_type":"Bearer",
     "expires_in":3599
   }
   ```

   The `scope` in the access token is `openid`, which comes from the configured CIMD profile, not `read` from the authorization request, because the profile's metadata override denylist includes `scope`. The `id_token` is also returned.