OAuth Client ID Metadata Document (CIMD)

Introduction

In authorization requests defined in RFC 6749: The OAuth 2.0 Authorization Framework, the client application (“client” hereafter) must specify its identifier (“client ID” hereafter) using the client_id request parameter. In addition, the authorization server must verify that the redirect_uri specified in the request is one that has been registered for the client (i.e., that the redirect URI is included in the client’s redirect_uris metadata). Given these requirements, it follows that before the client sends a request to the authorization server, the client’s identifier and metadata must already be registered with the authorization server. There are several standard specifications for pre-registering clients, such as OpenID Connect Dynamic Client Registration 1.0 (DCR), RFC 7591 OAuth 2.0 Dynamic Client Registration Protocol (DCR), and Explicit Registration of OpenID Federation 1.0 (explanatory document). Support for these specifications by an authorization server is optional.

Even when an authorization server supports the standards mentioned above, it is common for its implementation to provide proprietary client registration methods as well, such as static configuration files or a web console. Authlete also supports client registration through its web console and the /client/create API, in addition to these standard specifications.

Because an authorization request requires it, an application must retain the client ID assigned by the authorization server. If the application functions as a client of multiple authorization servers, it must manage a different client ID for each server it communicates with. This situation is by no means uncommon. As described in “Current Architecture of Ecosystems” in the GAIN PoC Interim Report (Spring 2023), ecosystems modeled after the UK’s Open Banking generally operate in this manner.

Although this DCR-based approach works, it requires applications to use different client IDs for each authorization server. As the number of authorization servers increases, managing these identifiers becomes cumbersome. From an application’s perspective, it would be ideal to reuse a single client ID across all authorization servers whenever possible. In fact, a mechanism that allows a client ID to be shared across all authorization servers has already been realized in the OpenID Federation 1.0 specification. In this specification, a client ID is a globally unique URL starting with https://. The client’s metadata is then provided at the location obtained by appending /.well-known/openid-federation to that URL (the figure below is an excerpt from the explanatory document).

Authorization servers that support OpenID Federation 1.0 will, when they receive an authorization request whose client_id parameter refers to an unregistered client and that identifier is a URL starting with https://, automatically fetch the client metadata from the location obtained by appending /.well-known/openid-federation to that URL and register the client (this is called Automatic Registration). After that, the authorization server simply continues processing the authorization request as if nothing unusual had happened.

Because trust chain verification and metadata policy enforcement are involved, the process of deriving client metadata is actually quite complex. Please refer to the explanatory document for details.

A new specification called the OAuth Client ID Metadata Document (CIMD) has been proposed in a landscape where a prior specification already exists. In this specification as well, the client ID is a URL starting with https://, and the client metadata is provided from the location indicated by that URL. Compared to OpenID Federation 1.0, CIMD is a much simpler specification. This simplicity makes implementation easier for both clients and servers. However, in exchange for that simplicity, the CIMD specification does not define any method for verifying whether a client is a trustworthy communication partner. As a result, unless an authorization server’s implementation imposes some kind of proprietary restriction, anyone can freely register a client with an authorization server that supports CIMD. This stands in stark contrast to OpenID Federation 1.0, which clearly defines how to build trust relationships between entities using trust chains. In this article, we describe the CIMD specification and Authlete-specific features that complement it.

Specification

Overview

Put simply, the CIMD specification says: “Use a URL beginning with https:// as the client identifier. Retrieve the client metadata from the location pointed to by that URL.” Let’s walk through the flow. First, the client sends an authorization request to the authorization server. The authorization request includes the client_id request parameter, and the value of that parameter is a URL beginning with https://.

The authorization server parses the received authorization request. It then recognizes that the client ID begins with https://.

If the client corresponding to that client ID is not yet registered, the authorization server accesses the location pointed to by that URL.

The location being accessed returns the client metadata in JSON format.

The authorization server registers the client with itself based on the client metadata and continues processing the authorization request.

Client ID Requirements

The scheme must be https
A path component is required
The path must not contain path segments . or ..
A fragment component must not be included
A username or password must not be included
A query component should not be included

Client Metadata Restriction

The URL of the metadata and the client_id value in the metadata must match.
Symmetric key client authentication methods such as client_secret_basic, client_secret_post, and client_secret_jwt must not be specified in token_endpoint_auth_method.
client_secret and client_secret_expires_at must not be used.

Service Settings

Authlete has supported CIMD since version 3.0.22. In this section, we introduce the properties added to the Service to support CIMD, as well as the related API request parameters.

clientIdMetadataDocumentSupported Property

A new boolean property, clientIdMetadataDocumentSupported, has been added to the Service to indicate whether CIMD is supported. The default value of this property is false, so if you want to use CIMD, you need to explicitly set it to true.

{
  "clientIdMetadataDocumentSupported": true
}

The clientIdMetadataDocumentSupported property corresponds to the client_id_metadata_document_supported server metadata defined in the CIMD specification. When clientIdMetadataDocumentSupported is set to true, the discovery document (OpenID Connect Discovery 1.0) generated by Authlete’s /service/configuration API will include the following entry:

{
  "client_id_metadata_document_supported": true
}

Metadata Policy

A configuration that controls how client metadata retrieved via CIMD (Client ID Metadata Document) is processed and validated before being used. When enabled, the policy defined here is applied to metadata fetched from the client ID URI, and the resulting metadata is stored as the client registration. This feature is enabled by setting the cimdMetadataPolicyEnabled property to true and providing a JSON policy definition in the cimdMetadataPolicy property. The metadata policy follows the OpenID Federation 1.0 specification (Section 6.1 – Metadata Policy) and supports operators such as add, subset_of, superset_of, one_of, default, value, and essential.

Example configuration

{
  "cimdMetadataPolicyEnabled": true,
  "cimdMetadataPolicy": {
    "id_token_signed_response_alg": {
      "default": "ES256",
      "one_of": ["ES256", "ES384", "ES512"]
    },
    "redirect_uris": {
      "add": [
        "http://localhost:12345/redirect"
      ]
    }
  }
}

Service API payload example

When the Metadata Policy is enabled, the Service API payload contains the policy as a JSON-encoded string.

{
  "cimdMetadataPolicyEnabled": true,
  "cimdMetadataPolicy": "{\"redirect_uris\":{\"add\":[\"http://localhost:12345/redirect\"]},\"id_token_signed_response_alg\":{\"default\":\"ES256\",\"one_of\":[\"ES256\",\"ES384\",\"ES512\"]}}"
}

Behavior

When cimdMetadataPolicyEnabled is set to true, Authlete applies the defined policy to metadata obtained through CIMD before storing it as the client registration. The policy can add values, restrict options, set defaults, or validate metadata fields according to the OpenID Federation 1.0 metadata policy grammar. If the policy is disabled, retrieved client metadata is stored without modification.

Allowlist

You can restrict the URLs allowed as client IDs using an allowlist. The allowlist is specified in the Service’s cimdAllowlist property. To enable restriction based on the allowlist, set the cimdAllowlistEnabled property to true.

{
  "cimdAllowlistEnabled": true,
  "cimdAllowlist": [
    "https://example.com/a/b"
  ]
}

If the cimdAllowlistEnabled property remains false, anyone can freely register clients without restriction.

The value of the cimdAllowlist property is an array of strings, and each element must be a valid URL. A client ID is considered valid if it matches any one of the URLs in the allowlist. The match is not determined by a simple string comparison, but is performed according to the following rules:

	Component	Comparison
1	Scheme	The schemes must match.
2	Authority	The authorities must match (simple string comparison; the default port is not considered).
3	Path	The path of the client ID must fully include the path of the URL in the allowlist.
4	Query	If the URL in the allowlist includes a query component, the query components must match.

The path comparison is performed on a segment-by-segment basis. For example, if the allowlist contains https://example.com/a/b, then https://example.com/a/b/c is considered a valid client ID, whereas https://example.com/a or https://example.com/a/bb are considered invalid.

Always Retrieved

The authorization server caches the retrieved client metadata for a certain period. Until that period expires, it does not re-retrieve the metadata and continues to reference the cached version. This behavior is generally desirable, but there are times when you may want the authorization server to re-retrieve the client metadata before the cache expires — for example, when the client metadata is being changed frequently during client application development. If you have experience in web content creation, you may have found the browser’s Super Reload feature useful. The forced re-retrieval functionality for client metadata is, in a sense, like a Super Reload. In OpenID Federation 1.0, the trust_chain request parameter allows you to prompt the authorization server to update the client metadata before the cache expires. CIMD, on the other hand, does not provide such a mechanism. Therefore, I proposed standardizing a way to prompt the re-retrieval of client metadata (CIMD ISSUE 59). However, since there was little chance of gaining consensus, I decided to implement an Authlete-specific mechanism. If the Service’s cimdAlwaysRetrieved property is set to true, Authlete will always re-retrieve the client metadata. More precisely, the re-retrieval occurs in the initiating request of an authorization flow. “Initiating request of an authorization flow” refers to the following cases:

In the authorization code flow (and other flows initiated at the authorization endpoint), re-retrieval is performed during the authorization request, but not during the subsequent token request.
In client credentials flow (and other flows initiated at the token endpoint), the token request itself is the initiating request, so re-retrieval occurs at the time of the token request.
In the CIBA flow (CIBA Core), re-retrieval is performed during the backchannel authentication request, but not during the subsequent token request.
In the device flow (RFC 8628), re-retrieval is performed during the device authorization request, but not during the subsequent token request.

The “always retrieved” feature is useful during development. However, once the system is running stably and client metadata rarely changes, always re-retrieving is excessive. Therefore, once the system stabilizes, you would typically set the cimdAlwaysRetrieved property to false. That said, there may still be circumstances where you want to force a re-retrieval even after the system has stabilized. To accommodate this, several Authlete APIs —specifically the ones listed below— accept the request parameter cimdOptions.alwaysRetrieved. If this parameter is set to true, the client metadata will be re-retrieved regardless of the cache status, even if the Service’s cimdAlwaysRetrieved setting is false.

API	Description
`/api/{service-id}/auth/authorization`	Processes authorization requests
`/api/{service-id}/auth/token`	Processes token requests
`/api/{service-id}/backchannel/authentication`	Processes backchannel authentication requests
`/api/{service-id}/device/authorization`	Processes device authorization requests

Using this runtime feature, an authorization server can implement its own forced client metadata re-retrieval functionality.

HTTP Permitted

In the CIMD specification, the scheme of the URL representing the client ID must be https. However, if the Service’s cimdHttpPermitted flag is set to true, Authlete will also allow the http scheme. Enabling this feature allows you to use a web server without TLS protection as a server hosting client metadata. This feature is intended for use during development. Just as the cimdOptions.alwaysRetrieved request parameter corresponds to the cimdAlwaysRetrieved property, there is also a cimdOptions.httpPermitted request parameter corresponding to the cimdHttpPermitted property.

Query Permitted

In the CIMD specification, the URL representing the client ID SHOULD NOT have a query component. By default, Authlete does not accept URLs with a query component as CIMD client IDs. To allow Authlete to accept URLs with a query component as CIMD client IDs, you need to set the Service’s cimdQueryPermitted property to true. This property also has a corresponding request parameter: cimdOptions.queryPermitted.

HTTP Alias Prohibited

Authlete internally assigns a numeric identifier to each client. In addition, there is a feature called “Client ID Alias”, which allows developers to assign an arbitrary name to a client. Until Authlete 2.3, this feature could be turned on or off, but due to historical reasons, in Authlete 3.0 the feature is always enabled and cannot be disabled. Since arbitrary names can be assigned, for example, a URL with an https scheme can be set as a client identifier. However, such a client identifier, while appearing similar to a client ID in OpenID Federation 1.0 or CIMD, is actually just an alias and does not trigger the automatic client metadata update process. To prevent potential confusion, Authlete has introduced a new Service property, httpAliasProhibited, which prevents strings starting with https:// or http:// from being set as aliases. For backward compatibility, the default value of this httpAliasProhibited property is false, but it is recommended to set it to true whenever possible.

When Authlete searches for a client corresponding to a client ID included in an authorization request (or other standard protocol messages), it does so in the following order of priority: numeric internal identifier → alias → OpenID Federation 1.0 entity ID → CIMD client metadata document URL.Therefore, if the client ID matches an alias, the CIMD functionality will not be triggered for that client ID.

Metadata Policy

Authlete provides a feature that applies a metadata policy to retrieved client metadata and adjusts it before storing the metadata in the database. This feature applies the metadata policy defined in Section 6.1, “Metadata Policy,” of OpenID Federation 1.0 to CIMD.

For example, suppose that the client metadata obtained from the URL indicated by the client ID is as follows:

{
  "client_name": "Example Client",
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ],
  "response_types": [
    "code"
  ],
  "token_endpoint_auth_method": "none",
  "client_id": "https://example.com/client.json",
  "redirect_uris": [
    "https://example.com/redirect"
  ]
}

When the following metadata policy is applied to this client metadata,

{
  "id_token_signed_response_alg": {
    "default": "ES256",
    "one_of": ["ES256", "ES384", "ES512"]
  },
  "redirect_uris": {
    "add": [
      "http://localhost:12345/redirect"
    ]
  }
}

the resulting client metadata will look like the following. Note that http://localhost:12345/redirect has been added to redirect_uris, and that a new id_token_signed_response_alg property with the value ES256 has been added.

{
  "client_name": "Example Client",
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ],
  "response_types": [
    "code"
  ],
  "token_endpoint_auth_method": "none",
  "client_id": "https://example.com/client.json",
  "redirect_uris": [
    "https://example.com/redirect",
    "http://localhost:12345/redirect"
  ],
  "id_token_signed_response_alg": "ES256"
}

The OpenID Connect Dynamic Client Registration 1.0 specification defines the default value of the id_token_signed_response_alg property as RS256. Therefore, if this property is not explicitly included, its value defaults to RS256, and as a result, the ID token is signed using RS256.However, if a metadata policy like the one shown above is prepared and applied, the value of this property becomes ES256, and consequently, the ID token is signed using ES256.

To use this feature, set the Service’s cimdMetadataPolicyEnabled property to true and configure the metadata policy in the cimdMetadataPolicy property.

{
  "cimdMetadataPolicyEnabled": true,
  "cimdMetadataPolicy": "{\"redirect_uris\":{\"add\":\"http://localhost:12345/redirect\"},\"id_token_signed_response_alg\":{\"default\":\"ES256\",\"one_of\":[\"ES256\",\"ES384\",\"ES512\"]}}"
}

Client Properties

When Authlete communicates client information outside of Authlete via the Authlete APIs, it uses a data structure called Client. To support CIMD, the following properties have been added to this data structure:

Property	Description
`metadataDocumentLocation`	The location of client metadata
`metadataDocumentExpiresAt`	The expiration time of client metadata (in milliseconds elapsed since the Unix epoch)
`metadataDocumentUpdatedAt`	The last update time of client metadata (in milliseconds elapsed since the Unix epoch)
`discoveredByMetadataDocument`	The boolean flag indicating whether the client has been registered using CIMD

As mentioned in the CIMD specification, Authlete calculates the validity period of client metadata using existing HTTP mechanisms (see: RFC 9111 HTTP Caching). The metadataDocumentExpiresAt property indicates the time when this validity period expires. If the web server hosting the client metadata forgets to set cache-related parameters such as max-age, or sets an excessively long lifetime, the calculated validity period of the client metadata could far exceed the expected client metadata update interval. If such an unexpectedly long validity period is applied, updates to the client metadata may not be detected at the appropriate intervals. To prevent this, the current Authlete implementation caps the validity period at 86,400 seconds (1 day), regardless of the calculated value.

For special cases where customers using the on-premises version of Authlete or Authlete’s internal developers run both the Authlete server and the web server hosting client metadata on the same local machine during development, the maximum validity period of client metadata is set to 600 seconds (10 minutes) if the host part of the client ID points to the local machine — specifically, in any of the following cases. Note that this behavior may change in the future.localhost 127.0.0.1 ::1 host.docker.internal host.minikube.internal

The following are the properties related to the client identifier.

Property	Type	Specification	Description
`clientId`	Number		The numeric client identifier
`clientIdAlias`	String		The client ID alias
`clientIdAliasEnabled`	Boolean		Whether the Client ID Alias feature is enabled (Always `true` in Authlete 3.0)
`dynamicallyRegistered`	Boolean	DCR	Whether the client has been registered using DCR
`entityId`	String	OIDFED	The entity ID
`automaticallyRegistered`	Boolean	OIDFED	Whether the client has been registered using Automatic Registration
`explicitlyRegistered`	Boolean	OIDFED	Whether the client has been registered using Explicit Registration
`metadataDocumentLocation`	String	CIMD	The location of client metadata
`metadataDocumentExpiresAt`	Number	CIMD	The expiration time of client metadata
`metadataDocumentUpdatedAt`	Number	CIMD	The last update time of client metadata
`discoveredByMetadataDocument`	Boolean	CIMD	Whether the client has been registered using CIMD

Due to historical reasons, there are multiple boolean flags indicating the origin of a client —namely, dynamicallyRegistered, automaticallyRegistered, explicitlyRegistered, and discoveredByMetadataDocument. These flags are mutually exclusive, meaning that more than one flag cannot be true at the same time. Having separate mutually exclusive flags is cumbersome, so starting from Authlete version 3.0.22, the Authlete API responses also include a string property called clientSource in addition to these flags. This property can take the following values:

Value	Description
`DYNAMIC_REGISTRATION`	Registration using DCR
`AUTOMATIC_REGISTRATION`	Registration using OpenID Federation 1.0’s Automatic Registration
`EXPLICIT_REGISTRATION`	Registration using OpenID Federation 1.0’s Explicit Registration
`METADATA_DOCUMENT`	Registration using CIMD
`STATIC_REGISTRATION`	Others (static registration)

Response Parameters

The responses of several Authlete APIs, such as /api/{service-id}/auth/authorization, include information about the origin of the client ID used in the request.

Parameter	Type	Specification	Description
`clientIdAliasUsed`	Boolean		The alias was used as the client ID
`clientIdAlias`	String		The alias
`clientEntityIdUsed`	Boolean	OIDFED	The entity ID was used as the client ID
`clientEntityId`	String	OIDFED	The entity ID
`metadataDocumentUsed`	Boolean	CIMD	The location of client metadata was used as the client ID
`metadataDocumentLocation`	String	CIMD	The location of client metadata

Conclusion

In the 2025-11-25 edition of the MCP (Model Context Protocol) specification, CIMD was incorporated as part of the standard (MCP 2025-11-25 Authorization). Authlete completed the implementation of the CIMD specification in November 2025, and as introduced in this article, also implemented the following Authlete-specific features:

Allowlist (cimdAllowlist, cimdAllowlistEnabled)
Always Retrieved (cimdAlwaysRetrieved | cimdOptions.alwaysRetrieved)
HTTP Permitted (cimdHttpPermitted | cimdOptions.httpPermitted)
Query Permitted (cimdQueryPermitted | cimdOptions.queryPermitted)
Metadata Policy (cimdMetadataPolicy, cimdMetadataPolicyEnabled)

CIMD is a specification that is still under development and is expected to continue evolving. Additionally, industry experience with implementing and operating CIMD is just beginning to accumulate. Authlete plans to add features as needed in response to updates to the specification and industry feedback. If you have any feature requests, please contact us via the contact form.

Flows and Features

Implementation Details

Going Live

Integration

OAuth Client ID Metadata Document (CIMD)

Introduction

Specification

Overview

Client ID Requirements

Client Metadata Restriction

Service Settings

clientIdMetadataDocumentSupported Property

Metadata Policy

Example configuration

Service API payload example

Behavior

Allowlist

Always Retrieved

HTTP Permitted

Query Permitted

HTTP Alias Prohibited

Metadata Policy

Client Properties

Response Parameters

Conclusion

Flows and Features

Implementation Details

Going Live

Integration

​Introduction

​Specification

​Overview

​Client ID Requirements

​Client Metadata Restriction

​Service Settings

​clientIdMetadataDocumentSupported Property

​Metadata Policy

​Example configuration

​Service API payload example

​Behavior

​Allowlist

​Always Retrieved

​HTTP Permitted

​Query Permitted

​HTTP Alias Prohibited

​Metadata Policy

​Client Properties

​Response Parameters

​Conclusion

Introduction

Specification

Overview

Client ID Requirements

Client Metadata Restriction

Service Settings

clientIdMetadataDocumentSupported Property

Metadata Policy

Example configuration

Service API payload example

Behavior

Allowlist

Always Retrieved

HTTP Permitted

Query Permitted

HTTP Alias Prohibited

Metadata Policy

Client Properties

Response Parameters

Conclusion