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.

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.

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
}

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"
  ]
}

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:

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.

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.

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"
}

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:

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.

The following are the properties related to the client identifier.

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:

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.

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.