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:
- OAuth authorization server metadata, see RFC 8414
- Resource indicators, see RFC 8707
- CIMD, see OAuth Client ID Metadata Document
- The identity assertion authorization grant, see OAuth Identity Assertion Authorization Grant
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:
- The client publisher hosts the metadata document at a stable HTTPS location.
- The identity domain administrator configures the metadata location as trusted.
- The client uses the metadata document URL as its
client_id. - The identity domain retrieves and validates the metadata when processing the OAuth request.
- If the client requests access to a protected resource, the resource application must explicitly authorize the CIMD client.
- 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:
- Publish the permitted loopback redirect URI in the CIMD metadata.
- Use the authorization code flow.
- Use PKCE.
- Include the required PKCE parameters in the authorization request.
- Send the corresponding
code_verifierwhen 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:
- Set the client's token endpoint authentication method to
private_key_jwt. - Provide a valid
jwks_uriin the client metadata. - Publish the client's public keys through the referenced JSON Web Key Set (JWKS) endpoint.
- Sign the client assertion with the corresponding private key.
- 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:
- The administrator enables CIMD support for the domain.
- The administrator configures the client's metadata location as trusted.
- The client uses the same HTTPS metadata URL as its
client_id. - The identity domain retrieves and validates the client metadata.
- 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 validjwks_urithat 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.
-
Request a protected resource. The MCP client requests a protected resource from the MCP server.
-
Receive authorization requirements. If the request doesn't contain valid credentials, the MCP server returns
401 Unauthorized. TheWWW-Authenticateheader includes aresource_metadataparameter 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" -
Retrieve the PRM document. The client fetches the PRM document from the URL in the
resource_metadataparameter. The document identifies the authorization server.{ "resource": "https://mcp.example.com", "authorization_servers": ["https://auth.example.com"] } -
Discover authorization server metadata. The client uses the
authorization_serversvalue to locate the authorization server and requests its metadata endpoint.https://auth.example.com/.well-known/oauth-authorization-server -
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 } -
Determine the client registration method. If
client_id_metadata_document_supportedistrue, the client can use CIMD. -
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_jwtfor 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:
-
Receive the authorization request. The client sends a
client_idthat contains the CIMD URL and includes the remaining authorization parameters. -
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.
-
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.
-
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:
-
Extract the
client_id. IAM with identity domains identifies the CIMD URL from the token request. -
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_jwtauthentication. -
Authenticate a
private_key_jwtclient. For a CIMD document that specifiestoken_endpoint_auth_methodasprivate_key_jwt, IAM with identity domains validates the client assertion.- Verify that the
issclaim in the JSON Web Token (JWT) matches theclient_idURL. - Locate the
jwks_urivalue in the CIMD document. - Retrieve or reuse the JWKS.
- Verify the
client_assertionJWT with a key from the JWKS. - Issue tokens only after all required signatures and claims pass validation.
- Verify that the
-
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_idmust 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.
References
For more information, see these public references:
OAuth Client ID Metadata Document
Related Topics
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"
}
]
}
]
}
Related Topics
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_urismetadata. - 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.
Related Topics
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.
| 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. |