Client ID Metadata Documents

Learn how Client ID Metadata Documents (CIMD) work with IAM with identity domains, including discovery, Model Context Protocol (MCP) authorization, supported OAuth flows, validation, and security constraints.

Overview of CIMD Support

IAM with identity domains supports standards and protocol features that MCP clients use during OAuth authorization. The relevant capabilities include:

  • OAuth authorization server metadata through /.well-known/oauth-authorization-server.
  • Resource indicator support for OAuth token requests.
  • Client ID Metadata Document (CIMD) support.
  • Cross-application access through enhanced token exchange.

A Client ID Metadata Document (CIMD) enables an OAuth client to use the HTTPS URL of a client-hosted metadata document as its client_id. The metadata document describes the client and its OAuth configuration, including its redirect URIs, supported grant types, response types, and token endpoint authentication method.

With CIMD, a client doesn't need a persistent OAuth client registration in every identity domain that it uses. Instead, the client publishes a metadata document at a stable HTTPS URL. When the client starts an OAuth flow, it supplies that URL as its client_id.

The identity domain continues to control whether the client can participate in OAuth flows. Before accepting a CIMD client, the identity domain verifies that the metadata location is trusted and validates the retrieved client metadata. Access to a protected resource is also explicitly controlled by the resource application.

Standard OAuth security requirements continue to apply. Depending on the client type and grant, these requirements include Proof Key for Code Exchange (PKCE), redirect URI validation, client authentication, user consent, scope validation, and token validation.

For more information about these standards and specifications, see the following resources:

Supported Use Cases

When to Use CIMD

Consider CIMD when an OAuth client must operate across identity domains and maintaining a persistent client registration in every domain would create unnecessary administrative overhead.

CIMD is particularly useful for the following clients:

  • Clients that are distributed to many users or environments
  • Clients that are updated frequently
  • Clients that are discovered or instantiated dynamically
  • Clients that run locally and require loopback redirect URIs
  • Clients that need to authenticate without using a shared client secret
  • Clients that need to use the same client identity across multiple identity domains

A CIMD client must publish its metadata at a stable HTTPS URL. The URL used to retrieve the metadata is also the client's OAuth client_id.

AI Agents and MCP Clients

AI agents and Model Context Protocol (MCP) clients can be distributed broadly, updated frequently, or discovered dynamically. Registering each client separately in every identity domain can make deployment and administration difficult.

With CIMD, an AI agent or MCP client can publish one client metadata document and use its HTTPS URL as the OAuth client_id.

For example:

https://client.example.com/oauth/client-metadata.json

The client uses that same value in its OAuth authorization and token requests.

For this use case, complete the following steps:

  1. The client publisher hosts the metadata document at a stable HTTPS location.
  2. The identity domain administrator configures the metadata location as trusted.
  3. The client uses the metadata document URL as its client_id.
  4. The identity domain retrieves and validates the metadata when processing the OAuth request.
  5. If the client requests access to a protected resource, the resource application must explicitly authorize the CIMD client.
  6. Normal OAuth authorization, consent, scope, and token processing continues to apply.

Trusting a metadata location doesn't automatically grant access to protected resources. Trust establishes that the identity domain can process the client metadata. Resource authorization separately determines which protected resources the client can access.

Developer and Desktop Applications

Developer tools and desktop applications commonly use a web browser for authorization but receive the authorization response through a local application listener.

These clients can use loopback redirect URIs such as:

http://127.0.0.1/callback

or:

http://localhost/callback

The client can then start a local listener on an available port, for example:

http://localhost:8000/callback

CIMD supports this scenario without requiring a separate persistent client registration in every identity domain.

For public developer or desktop clients, complete the following steps:

  1. Publish the permitted loopback redirect URI in the CIMD metadata.
  2. Use the authorization code flow.
  3. Use PKCE.
  4. Include the required PKCE parameters in the authorization request.
  5. Send the corresponding code_verifier when exchanging the authorization code for tokens.

Redirect URI validation remains strict. Each permitted redirect must be declared in the client's metadata. HTTP redirects are intended only for supported loopback addresses. For an approved loopback redirect, the port can vary so that a locally running application can select an available port.

For example, client metadata can declare:

{
  "redirect_uris": [
    "http://localhost/callback",
    "http://127.0.0.1/callback"
  ]
}

A supported authorization request can then use a dynamically selected loopback port:

http://localhost:8000/callback

The identity domain validates that the redirect follows the supported loopback redirect rules before completing the authorization request.

Confidential Clients

CIMD can also be used by confidential clients that authenticate with private_key_jwt.

This model enables a client to authenticate using an asymmetric key instead of a shared client secret. The client signs a client assertion with its private key, and its metadata provides the information required to locate the corresponding public keys.

For this use case, complete the following steps:

  1. Set the client's token endpoint authentication method to private_key_jwt.
  2. Provide a valid jwks_uri in the client metadata.
  3. Publish the client's public keys through the referenced JSON Web Key Set (JWKS) endpoint.
  4. Sign the client assertion with the corresponding private key.
  5. Use the CIMD URL as the client identifier in the token request.

During client authentication, the identity domain validates the relationship between the client assertion and the CIMD client identity and verifies the assertion using the client's published public key.

The following excerpt shows the metadata used for private_key_jwt authentication. A complete CIMD metadata document must also include all fields listed in Client Metadata Requirements.

{
  "client_id": "https://client.example.com/oauth/client-metadata.json",
  "client_name": "Example Confidential Client",
  "grant_types": [
    "client_credentials"
  ],
  "token_endpoint_auth_method": "private_key_jwt",
  "jwks_uri": "https://client.example.com/.well-known/jwks.json"
}

The client_id value in the metadata must match the metadata document URL that the client uses as its OAuth client_id.

Cross-Domain Client Adoption

CIMD enables a client publisher to make the same OAuth client available to multiple identity domains without creating a separate persistent client registration in every domain.

The client publishes a single metadata document at a stable HTTPS URL. Each participating identity domain can independently decide whether to trust that client.

For each identity domain, complete the following steps:

  1. The administrator enables CIMD support for the domain.
  2. The administrator configures the client's metadata location as trusted.
  3. The client uses the same HTTPS metadata URL as its client_id.
  4. The identity domain retrieves and validates the client metadata.
  5. Each protected resource independently authorizes the CIMD client when access is required.

For example, the same client identifier can be used with multiple identity domains:

https://client.example.com/oauth/client-metadata.json

Configuration in one identity domain doesn't automatically establish trust in another identity domain. Each domain administrator controls whether the client is trusted, and each resource application controls whether that client can access its protected resources.

Key Concepts

The following terms describe the identity, OAuth, and security concepts used in the CIMD flow.

  • IAM: Identity and Access Management.

  • IDCS: Oracle Identity Cloud Service.

  • MCP: An open protocol that standardizes how AI applications connect to external tools, data sources, and services. In this document, Model Context Protocol (MCP) clients use OAuth to access protected MCP resources.

  • IDCS/IAM domain: Oracle Identity Cloud Service or an OCI IAM identity domain providing OAuth and identity services.

  • CIMD: Client ID Metadata Document. A standards-aligned model where a client uses the HTTPS URL of its metadata document as its OAuth client_id.

  • Metadata document: Publisher-hosted JSON document that declares the required client metadata fields: client_id, client_name, redirect_uris, grant_types, response_types, and token_endpoint_auth_method.

  • CIMD client: Short-lived IAM-domain-scoped client identity created from a validated CIMD document for authorization, consent, token, audit, and authorization processing.

  • Trusted metadata origin: Metadata URL origin explicitly trusted by the IAM domain before IDCS/IAM fetches CIMD content.

  • PKCE: Proof Key for Code Exchange. Required for public CIMD authorization-code requests.

  • JWKS: JSON Web Key Set. Used to publish public keys when a CIMD client uses private_key_jwt.

  • SSRF: Server-side request forgery. CIMD metadata and key retrieval must apply SSRF-aware URL, DNS, redirect, timeout, proxy, and payload-size controls.

Client ID Metadata Document Model

A CIMD lets an OAuth client identify itself to an authorization server by using a URL as the client_id. The URL points to a JSON document that contains client metadata.

The client hosts the metadata instead of requiring the authorization server to store a permanent client registration. For MCP and agentic AI workloads, IAM with identity domains verifies the document source, metadata, redirect URIs, and the client's authorization to access a protected resource.

Client Metadata Requirements

A CIMD metadata document must include these required fields:

  • client_id
  • client_name
  • redirect_uris
  • grant_types
  • response_types
  • token_endpoint_auth_method

The client_id value in the metadata document must exactly match the HTTPS metadata document URL that the client uses as its OAuth client_id.

For CIMD clients, the supported token_endpoint_auth_method values are none and private_key_jwt.

  • none: Use this method for a public client that uses the authorization code flow. The authorization code flow requires PKCE.
  • private_key_jwt: Use this method for an authenticated confidential client. The metadata document must include a valid jwks_uri that provides the asymmetric public-key information used to validate the client assertion.

The client credentials grant is supported for an authenticated CIMD client that uses private_key_jwt. An unauthenticated client-credentials request is not supported.

MCP Client-Initiated Authorization

During MCP client-initiated authorization, the /.well-known/oauth-authorization-server endpoint helps the client discover authorization server metadata and determine whether the server supports CIMD.

  1. Request a protected resource. The MCP client requests a protected resource from the MCP server.

  2. Receive authorization requirements. If the request doesn't contain valid credentials, the MCP server returns 401 Unauthorized. The WWW-Authenticate header includes a resource_metadata parameter that points to the server's Protected Resource Metadata (PRM) document.

    HTTP/1.1 401 Unauthorized
    WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource"
  3. Retrieve the PRM document. The client fetches the PRM document from the URL in the resource_metadata parameter. The document identifies the authorization server.

    {
      "resource": "https://mcp.example.com",
      "authorization_servers": ["https://auth.example.com"]
    }
  4. Discover authorization server metadata. The client uses the authorization_servers value to locate the authorization server and requests its metadata endpoint.

    https://auth.example.com/.well-known/oauth-authorization-server
  5. Retrieve authorization server metadata. The metadata describes authorization endpoints, token endpoints, and CIMD support.

    {
      "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
    }
  6. Determine the client registration method. If client_id_metadata_document_supported is true, the client can use CIMD.

  7. Proceed with CIMD. The client uses the URL of its hosted metadata document as the client_id.

Supported OAuth Flows

IAM with identity domains supports these OAuth flows for CIMD clients:

  • Authorization code flow with PKCE for public clients, including refresh token support.
  • Client credentials grant with private_key_jwt for key-authenticated CIMD clients.

The authorization server discovery fields grant_types_supported and response_types_supported describe the authorization server's general OAuth capabilities. They don't override the CIMD-specific flow restrictions listed here.

CIMD Constraints

The CIMD flow has these constraints:

  • Authentication: Add each CIMD metadata location to the IAM with identity domains domain allowlist before the client can sign in through the IAM authorization server.
  • Authorization: Add each CIMD client to the OAuth resource application allowlist before the client can access a customer-defined resource application.
  • Caching: IAM with identity domains caches CIMD documents according to standard HTTP caching semantics, including Cache-Control, to determine when to reuse or retrieve metadata.

CIMD Request Processing

IAM with identity domains validates CIMD metadata during authorization and token processing. Validation includes domain trust checks, URL binding, secure metadata and key retrieval, response validation, caching controls, and protection against server-side request forgery (SSRF).

Login Request Processing

IAM with identity domains processes a CIMD authorization request in these stages:

  1. Receive the authorization request. The client sends a client_id that contains the CIMD URL and includes the remaining authorization parameters.

  2. Verify domain trust before retrieval. IAM with identity domains checks the CIMD identifier against the identity domain trust configuration before retrieving the metadata document. If the metadata source isn't trusted, the request is rejected before remote retrieval.

  3. Validate and retrieve the CIMD document. IAM with identity domains validates the HTTPS metadata URL, retrieves the JSON document using protected network access, validates URL binding, and applies the retrieval security controls described in CIMD Retrieval Security Considerations.

  4. Enforce PKCE for public clients. For a public client, IAM with identity domains requires PKCE for the authorization code flow.

Token Request Processing

When a client calls the token endpoint with grant_type = authorization_code, IAM with identity domains processes the request as follows:

  1. Extract the client_id. IAM with identity domains identifies the CIMD URL from the token request.

  2. Retrieve or reuse the CIMD document. IAM with identity domains securely retrieves the metadata or reuses validated cached metadata according to the applicable cache policy. The same network and response protections apply when the service retrieves a JWKS for private_key_jwt authentication.

  3. Authenticate a private_key_jwt client. For a CIMD document that specifies token_endpoint_auth_method as private_key_jwt, IAM with identity domains validates the client assertion.

    • Verify that the iss claim in the JSON Web Token (JWT) matches the client_id URL.
    • Locate the jwks_uri value in the CIMD document.
    • Retrieve or reuse the JWKS.
    • Verify the client_assertion JWT with a key from the JWKS.
    • Issue tokens only after all required signatures and claims pass validation.
  4. Process public clients. For a public client that uses the authorization code flow, IAM with identity domains applies its existing authorization code token processing.

CIMD Retrieval Security Considerations

IAM with identity domains applies the following controls when retrieving CIMD metadata and, when required for private_key_jwt, JWKS key information:

  • Trust before retrieval. The metadata source must pass the identity domain trust check before remote metadata retrieval. An untrusted CIMD identifier is rejected before the service retrieves its metadata.

  • HTTPS and URL validation. A CIMD client_id must be a valid HTTPS metadata URL and must pass URL safety validation before retrieval.

  • DNS and network destination protection. DNS and network address checks protect against DNS rebinding and prevent retrieval from unsafe network destinations.

  • Redirect protection. Remote metadata and key retrieval doesn't automatically follow redirects, preventing a retrieval request from being redirected to an unsafe destination.

  • Bounded retrieval. Metadata and JWKS retrieval is bounded so that remote hosts can't cause unbounded waits or return unbounded response content.

  • Fail-closed response handling. Failed, malformed, unreadable, oversized, or untrusted metadata and JWKS responses are rejected and aren't cached.

  • Bounded caching. Only validated CIMD metadata is eligible for reuse. Caching is time-bounded and follows relevant HTTP caching directives, including directives that require the service to revalidate or avoid reusing cached content.

Summary of CIMD Discovery

An MCP client requests OAuth authorization server metadata after it receives a 401 Unauthorized response and retrieves the PRM document. The authorization server metadata indicates whether CIMD is supported.

When CIMD is supported, the client uses its metadata URL as the client_id. IAM with identity domains validates the metadata location and client metadata before it completes authorization or token processing.

Configure CIMD for an Identity Domain

Configure IAM with identity domains to enable CIMD support for the identity domain, advertise CIMD support to clients, and configure the HTTPS client metadata sources that the identity domain can trust.

Before You Begin

CIMD support must be enabled for the identity domain before the domain can process CIMD clients. Add each CIMD client metadata URI to the IAM with identity domains domain allowlist before the client can sign in through the IAM authorization server.

Authorization Server Metadata

When CIMD support is enabled for the identity domain, the authorization server metadata advertises CIMD support by including client_id_metadata_document_supported with a value of true. The identity domain advertises this property only when CIMD support is enabled.

{
  "issuer": "https://identity.oraclecloud.com/",
  "authorization_endpoint": "https://<idcs-stripe-url>/oauth2/v1/authorize",
  "token_endpoint": "https://<idcs-stripe-url>/oauth2/v1/token",
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "private_key_jwt",
    "client_secret_post",
    "none"
  ],
  "token_endpoint_auth_signing_alg_values_supported": ["RS256"],
  "jwks_uri": "https://<idcs-stripe-url>/admin/v1/SigningCert/jwk",
  "scopes_supported": [
    "openid",
    "profile",
    "offline_access",
    "email",
    "address",
    "phone",
    "groups",
    "get_groups",
    "approles",
    "get_approles"
  ],
  "response_types_supported": [
    "code",
    "token",
    "id_token",
    "code token",
    "code id_token",
    "token id_token",
    "code token id_token"
  ],
  "ui_locales_supported": ["en"],
  "revocation_endpoint": "https://<idcs-stripe-url>/oauth2/v1/revoke",
  "introspection_endpoint": "https://<idcs-stripe-url>/oauth2/v1/introspect",
  "code_challenge_methods_supported": ["S256"],
  "secure_authorization_endpoint": "https://<idcs-stripe-regional-url>/oauth2/v1/authorize",
  "secure_token_endpoint": "https://<idcs-stripe-regional-url>/oauth2/v1/token",
  "secure_userinfo_endpoint": "https://<idcs-stripe-regional-url>/oauth2/v1/userinfo",
  "secure_revocation_endpoint": "https://<idcs-stripe-regional-url>/oauth2/v1/revoke",
  "secure_introspection_endpoint": "https://<idcs-stripe-regional-url>/oauth2/v1/introspect",
  "secure_jwks_uri": "https://<idcs-stripe-regional-url>/admin/v1/SigningCert/jwk",
  "grant_types_supported": [
    "client_credentials",
    "password",
    "refresh_token",
    "authorization_code",
    "urn:ietf:params:oauth:grant-type:jwt-bearer",
    "tls_cert_auth"
  ],
  "userinfo_endpoint": "https://<idcs-stripe-url>/oauth2/v1/userinfo",
  "client_id_metadata_document_supported": true
}

The grant type, response type, and token endpoint authentication method values in this authorization server metadata describe the identity domain's general OAuth capabilities. They don't override the CIMD-specific restrictions. For CIMD clients, use only the OAuth flows and authentication methods documented in Supported OAuth Flows and Client Metadata Requirements.

Configure the CIMD Domain Allowlist

Configure the IAM with identity domains domain allowlist with the HTTPS client metadata URIs that the identity domain can trust for CIMD. Use full HTTPS metadata document URLs for the domainUri values, as shown in the example.

Before retrieving a CIMD metadata document, the identity domain verifies that the CIMD client_id is trusted by the domain configuration. If the client identifier isn't trusted, the identity domain rejects the CIMD request before retrieving the metadata document.

PATCH https://<idcs-stripe-url>/admin/v1/Settings/Settings
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "add",
      "path": "allowedCimdDomains",
      "value": [
        {
          "domainUri": "https://client.example.com/oauth/client-metadata.json"
        },
        {
          "domainUri": "https://developer.example.net/oauth/client-metadata.json"
        }
      ]
    }
  ]
}

Configure an Application to Allow CIMD Clients

Configure a protected resource application so that approved CIMD clients can access the resource through IAM with identity domains. Resource authorization applies to the full HTTPS CIMD client identifier, which is the client metadata document URL used as the OAuth client_id.

Before You Begin

Add the client metadata location to the IAM with identity domains domain allowlist before adding the CIMD client to the protected resource application allowlist.

CIMD clients can access customer-defined OAuth resource applications only when the full HTTPS CIMD client identifier is authorized for the resource. CIMD clients can't request internal IAM administrative resources or receive IAM roles.

Configure the Resource Application Allowlist

For a resource application that IAM with identity domains protects, configure the CIMD client allowlist with each full HTTPS CIMD client identifier that can access the resource. The identifier is the client metadata document URL used as the OAuth client_id.

PATCH https://<idcs-stripe-url>/admin/v1/Apps/<app-guid>
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "add",
      "path": "cimdClientsAllowlist",
      "value": [
        "https://client.example.com/oauth/client-metadata.json",
        "https://developer.example.net/oauth/client-metadata.json"
      ]
    }
  ]
}

Redirect URI Requirements

CIMD authorization requests must use redirect URIs that meet the following requirements:

  • Declare every redirect URI in the CIMD redirect_uris metadata.
  • For HTTPS redirect URIs, the requested redirect URI must exactly match a declared URI.
  • Redirect URIs can't contain user information, fragments, or wildcards.
  • HTTP redirect URIs are supported only for recognized loopback hosts.
  • For a loopback redirect URI, only the port can vary from the URI declared in redirect_uris.

For example, if the CIMD metadata declares http://localhost/callback, a request can use http://localhost:8000/callback. The port can vary for a loopback redirect, but the rest of the redirect URI must match the declared URI.

CIMD Authorization and Token Examples

Use these examples to understand CIMD client metadata, authorization requests, token requests, and representative token claims.

CIMD Metadata Example

The following sample shows a public CIMD client that uses the authorization code flow with PKCE and supports refresh tokens:

{
  "client_id": "https://client.example.com/oauth/client-metadata.json",
  "client_name": "Example MCP Client",
  "client_uri": "https://client.example.com",
  "redirect_uris": [
    "http://localhost/callback",
    "http://127.0.0.1/callback"
  ],
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ],
  "response_types": [
    "code"
  ],
  "token_endpoint_auth_method": "none"
}

This example includes all required CIMD metadata fields. Because token_endpoint_auth_method is none, the public client must use PKCE with the authorization code flow.

After the identity domain is configured to trust this CIMD client and the required resource application authorizes the client, the client can use the metadata URL as its client_id in the OAuth authorization flow.

Authorization Request Example

The following sample authorization request uses a CIMD URL as the client_id. The metadata example declares http://localhost/callback, while this request uses http://localhost:8000/callback. The request redirect URI is valid for a loopback redirect because only the port differs:

https://<idcs-stripe-url>/oauth2/v1/authorize?response_type=code&client_id=https%3A%2F%2Fclient.example.com%2Foauth%2Fclient-metadata.json&redirect_uri=http%3A%2F%2Flocalhost%3A8000%2Fcallback&scope=openid+offline_access&code_challenge=<pkce-code-challenge>&code_challenge_method=S256&state=<state-value>

Token Request Example

The following sample exchanges an authorization code for tokens:

curl --location 'https://<idcs-stripe-url>/oauth2/v1/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'code=<authorization-code>' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'redirect_uri=http://localhost:8000/callback' \
  --data-urlencode 'client_id=https://client.example.com/oauth/client-metadata.json' \
  --data-urlencode 'code_verifier=<pkce-code-verifier>'

Token Response Example

The following sample shows representative access-token claims. Values that identify a user, tenant, domain, region, client, or environment use placeholders.

{
  "sub": "<user-identifier>",
  "iss": "https://identity.oraclecloud.com/",
  "scope": "openid offline_access",
  "client_id": "https://client.example.com/oauth/client-metadata.json",
  "user_ocid": "ocid1.user.<realm>..<user-unique-id>",
  "client_tenantname": "idcs-<tenant-ocid>",
  "region_name": "<region-name>",
  "exp": <expiration-time>,
  "iat": <issued-at-time>,
  "client_guid": "<client-guid>",
  "client_name": "Example MCP Client",
  "aud": "https://<tenant-hostname>"
}

CIMD Errors

This table describes common customer-facing Client ID Metadata Document (CIMD) error scenarios, their expected behavior, and the configuration checks needed to resolve them.

Common Client ID Metadata Error Scenarios
Scenario Observed behavior Recommended check
Public client omits PKCE parameters. 400 invalid_request; required PKCE parameters are missing. Include code_challenge and code_challenge_method, using S256.
The metadata client_id differs from the authorization-request client_id. Authorization fails with a client-ID binding error. Ensure that the metadata document's client_id exactly matches its HTTPS URL used in the request.
CIMD domain isn't allowlisted. Authorization is rejected during trust validation. Add the metadata document's domain to the identity-domain allowlist.
Metadata URL fails HTTPS or network-security checks. The metadata document can't be fetched. Host the document at a public HTTPS endpoint. Don't use private or internal IP destinations.