CIMD Domains

Client ID Metadata Documents (CIMD) is an OAuth extension, described by draft-ietf-oauth-client-id-metadata-document, in which the client_id is itself an HTTPS URL. That URL hosts a JSON document describing the client: its name, its redirect URIs, and the rest of its metadata.

When a client presents such a client_id, FusionAuth fetches the document, validates it, caches it, and registers the client just-in-time. Once you've configured a CIMD domain for that origin, neither you nor the client's developer has to register each individual client ahead of time.

CIMD addresses a trust issue with Model Context Protocol (MCP) clients: clients (e.g. claude.ai) cannot preregister with every MCP server. CIMD provides a way to dynamically register MCP clients with your MCP server. Dynamic Client Registration (DCR) previously solved the same problem, but CIMD involves less state and complexity.

CIMD Domains#

CIMD configuration starts with a CIMD domain, which names one origin that clients may register from (e.g. https://claude.ai). You configure CIMD domains at the Tenant level.

CIMD domains do not support:

• paths, query strings, or fragments
• wildcards (e.g. https://*.example.com)
• bare IP addresses
• localhost
• loopback addresses.

To register a client from any origin, specify a CIMD domain with the wildcard *. Since the wildcard matches any domain, you cannot specify specific domains in addition to the wildcard. However, you can use a registration Lambda to filter clients even when you allow any domain with the wildcard.

FusionAuth also validates the Client Ids provided in client metadata. Client Ids must:

• use HTTPS
• include a path
• contain no fragment and no userinfo component
• be no longer than 2048 characters
• match one of the tenant's CIMD domains (or the wildcard)

Fixed OAuth Behavior#

FusionAuth's implementation of the CIMD standard requires the following security measures and has the following limitations:

• Clients must implement PKCE.
• Clients can only use the authorization_code and refresh_token grants.
• Redirect URLs must exactly match the redirect URIs specified in the client's metadata document. The only exception is the port of an http loopback redirect URI, which can differ, as described in RFC 8252.
• Clients can only request scopes enabled on the domain, or the OAuth request will fail. Optional scopes the user declines on the consent screen are left out of the grant.
• Clients must send exactly one resource parameter, and it must be one of the domain's Authorized resource URIs.
• CIMD clients cannot use roles, SAML, the one-time password authentication method, WebAuthn, and self-service registration.
• A client's MFA trust only comes from logins through the same CIMD domain.
• Many CIMD clients are public, so client authentication is not required.

Identity Providers#

Users can log in to CIMD clients with a subset of identity providers. Each CIMD domain appears in the identity provider's application list as CIMD: <domain>, such as CIMD: https://claude.ai. Enable the identity provider for that entry to offer it to the domain's clients. When using the API, use the CIMD domain's Id as the application Id in the identity provider's applicationConfiguration.

The following restrictions apply:

• An identity provider can't create user registrations for a CIMD domain. FusionAuth ignores createRegistration for a CIMD domain, and the admin UI disables it.
• A SAML v2 identity provider with IdP-initiated login enabled can't be enabled for a CIMD domain. FusionAuth rejects the configuration with a validation error. The SAML v2 IdP Initiated identity provider doesn't list CIMD domains.

Hosted Login Pages#

CIMD clients log in through the FusionAuth hosted login pages, with these differences:

• Users are not registered for CIMD clients. The userState returned to the client is always AuthenticatedNotRegistered.
• Every OAuth request must include the Tenant Id, because the client_id URL does not identify a Tenant. Use the Tenant's endpoints, such as /oauth2/authorize/{tenantId}.
• Users cannot log in with a magic link or a passkey. The login page does not show these options.
• FusionAuth prompts for consent even when the client requests no scopes. The prompt shows the client's name and where its metadata document is hosted. See Consent Prompt.
• You can enable identity providers for the CIMD clients of a domain, except for IdP-initiated SAML.

Managing CIMD Domains#

Click CIMD Domains in the left navigation to see every CIMD domain in the tenants you can administer.

local.fusionauth.io

From here you can see each domain's name, origin, and consent mode, search by name or Id, and filter by Tenant. When you have more than one Tenant, the list also shows each domain's Tenant. You can also:

• Create a new CIMD domain.
• Edit a previously created CIMD domain.
• Manage scopes for a previously created CIMD domain.
• View a previously created CIMD domain.
• Delete a previously created CIMD domain.

Managing CIMD domains requires the admin or cimd_domain_manager role. Deleting a CIMD domain requires the admin or cimd_domain_deleter role. To manage CIMD domains via the API, an API key needs permission for the relevant CIMD Domain APIs endpoints.

Create and Edit a CIMD Domain#

Click CIMD Domains in the left navigation, then click the Add button at the top of the page.

When creating a new CIMD domain, you will see the following form:

local.fusionauth.io

Editing a saved CIMD domain presents the same form, with two differences: the Domain and Tenant values are read-only, and custom scopes can now be added through the Manage scopes action.

Here is what you can expect when updating an existing CIMD domain:

local.fusionauth.io

Form Fields#

General Tab#

Scopes Tab#

Custom scopes beyond the standard ones are managed separately, through the Manage scopes action on a saved domain, or through the CIMD Domain OAuth Scopes API. They are available to every client that registers through the domain.

Lambdas Tab#

View a CIMD Domain#

Additional details about a particular CIMD domain, including its scopes, can be viewed by clicking the action:

local.fusionauth.io

Remove a CIMD Domain#

When a CIMD domain is no longer needed, it can be removed by clicking the action:

local.fusionauth.io

When you add, update, or delete a CIMD domain in the admin UI, FusionAuth records the change in the Audit Log. It does the same when you add, update, or delete one of the domain's custom scopes.

Manage CIMD Domain Scopes#

Click the action on a CIMD domain to add and manage its custom OAuth scopes. These scopes are available to every client that registers through the domain, in addition to the standard OpenID Connect scopes enabled on the Scopes tab.

local.fusionauth.io

Click the Add button to create a new custom scope:

local.fusionauth.io

Editing a saved scope presents a similar form that also shows the scope's Id. The Id and Name values are read-only:

local.fusionauth.io

A custom scope can also be removed from the same row's action menu. This cannot be reversed. A client that registers after the removal fails if it requests the removed scope, because a CIMD domain always rejects unknown scopes.

FusionAuth saves a copy of the domain's scope settings in each client's registration, so changes to scopes, provided scopes, or authorized resource URIs don't apply to an already-registered client until FusionAuth fetches its document again. See CIMD Registration Caching And Lifecycle for when that happens.

Form Fields#

Configure CIMD Domains With the API#

Everything on this page can also be configured through the API:

• Use the CIMD Domain API to create, retrieve, update, search, and delete CIMD domains.
• Use the CIMD Domain OAuth Scopes API to manage a domain's custom OAuth scopes.
• Use the CIMD Client Registration API to retrieve, search for, and delete the clients registered through a domain. The admin UI doesn't show these registrations.