Skip to main content

Documentation Index

Fetch the complete documentation index at: https://auth0.com/ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

Register an MCP client in Auth0 by importing its externally hosted Client ID Metadata Document (CIMD) from a URL. A CIMD is a JSON file containing client metadata hosted on your domain (e.g., https://example-client.com/mcp-metadata.json). The CIMD URL serves as the application’s client ID and proves domain ownership, ensuring only trusted tenant administrators can register applications. With CIMD, you only need to register your MCP server once per deployment. All instances of that deployment use the same CIMD URL as their client ID. Whether you’re running one instance or hundreds across multiple regions, they all share the same registration credentials. This eliminates the need to manage separate client IDs and secrets for each instance, simplifying credential management at scale. You can only register third-party applications using manual CIMD, which are subject to enhanced security controls. Once registered, configure the API access policy and promote your connections to the domain level, which are required for third-party applications in Auth0.

​
Key benefits

Manual CIMD registration has the following benefits:
  1. MCP clients only need to be registered with CIMD once per deployment. All instances of that deployment use the same registration credentials.
  2. Uses asymmetric cryptography (public/private keys) instead of shared symmetric secrets that can be leaked.
  3. Application owners manage client metadata directly in the CIMD; Auth0 automatically maps these properties to its internal configuration during registration.
  4. The CIMD URL acts as a human-readable identifier in audit logs, making it easy to verify the origin of requests from specific MCP tool servers or hosts.

​
Example CIMD

The following is an example CIMD for a public MCP client:
https://example-client.com/mcp-metadata.json
{
  "client_id": "https://example-client.com/mcp-metadata.json",
  "client_name": "Example MCP Tool Server",
  "description": "MCP server providing tools for data analysis",
  "logo_uri": "https://example-client.com/logo.png",
  "application_type": "web",
  "grant_types": ["authorization_code", "refresh_token"],
  "redirect_uris": [
    "https://example-client.com/callback"
  ],
  "token_endpoint_auth_method": "none",
  "response_types": ["code"]
}
When you import an MCP client from its CIMD URL, Auth0 fetches, validates, and persists the metadata to register it as a CIMD client. While Auth0 maintains a record of these settings, the hosted CIMD remains the source of truth; metadata updates are synchronized through manual refreshes.

​
How it works

The following diagram shows the end-to-end manual CIMD registration flow: During manual CIMD registration, a tenant admin registers the application by importing its externally hosted CIMD to Auth0:
  1. Application creation: The tenant admin creates a CIMD app in Auth0 by:
    • Selecting Import from URL in the Auth0 Dashboard
    • Making a POST request to the /register endpoint, providing the external_client_id
  2. Metadata fetch: Auth0 makes a GET request to the client’s domain to retrieve the CIMD (client.json).
  3. Security validation: Auth0 maps and validates the CIMD URL against the CIMD URL validation rules and the CIMD against the CIMD JSON validation rules, verifying that the external_client_id matches the CIMD URL, among other checks.
  4. Persistence: Once validated, Auth0 stores the client metadata in the database.
  5. Confirmation: Auth0 returns a success response; the application has been successfully registered as a CIMD client in Auth0.

​
Prerequisites

Before registering an application with manual CIMD, make sure your tenant and application meet the following requirements:

​
Tenant configuration

  • Enable CIMD support: Enable the Client ID Metadata Document Registration toggle in your tenant settings to indicate CIMD support in the Auth0 Authorization Server metadata, allowing MCP clients to automatically discover this capability when connecting.
    • Navigate to Settings > Advanced and scroll down to the Settings section.
    • Toggle on Client ID Metadata Document Registration.
  • Resource Parameter Compatibility Profile (Optional): For MCP clients, we recommend enabling this profile in your tenant settings. This allows the authorization server to handle resource-specific requests (RFC 8707) by checking the resource parameter if the audience is not provided.

​
Supported client types

You can register the following client types with manual CIMD in Auth0:

​
Supported authentication methods

CIMD clients cannot use authentication methods based on shared symmetric secrets, such as client_secret_post, client_secret_basic, or client_secret_jwt. Depending on whether the client is public or confidential, Auth0 supports the following authentication methods for CIMD clients:
  • Public clients:
    • No client authentication required at the token endpoint; set token_endpoint_auth_method to none in client metadata
    • Must use Proof Key for Code Exchange (PKCE) for authorization flows
  • Confidential clients:
    • Only Private Key JWT authentication is supported; set token_endpoint_auth_method to private_key_jwt in client metadata
    • Provide a jwks_uri to host public keys. The jwks_uri must share the exact same origin (scheme, host, and port) as the CIMD URL. To learn more, read CIMD JSON validation rules.
Private Key JWT authentication is available only for Enterprise customers. To learn more about Enterprise plans, review Pricing or contact Auth0 Sales.
CIMD clients that use Private Key JWT authentication must implement key rotation by generating a new key pair with a new, unique kid.

​
Register applications with manual CIMD in Auth0

To register an application with manual CIMD using the Auth0 Dashboard:
  1. Navigate to Applications > Applications.
  2. Select Create Application > Import from URL.
  3. Enter the CIMD URL. Then, select Preview. Auth0 validates the CIMD URL against the CIMD URL validation rules.
  4. If your CIMD URL is valid, Auth0 loads the CIMD and validates it against the CIMD JSON validation rules. Preview your client metadata and troubleshoot it for any validation errors.
  5. To register your application as a CIMD client, select Create.

​
Configure API access policy

Third-party applications, including CIMD clients, require client grants for user-delegated and client access to APIs. You can configure: When both exist for the same API, the per-application grant takes precedence over the default third-party grant. To learn more about configuring the API access policies for third-party applications, read Configure Third-Party Applications.

​
Per-application grant

To create a per-application grant using the Auth0 Dashboard:
  1. Navigate to Applications > APIs and select the API.
  2. Go to the Settings tab.
  3. Scroll to Application Access Policy and set User-Delegated Access and Client Access to Per-app authorization.
  4. Select Save.
To authorize API access for the CIMD client using the Auth0 Dashboard:
  1. Navigate to Applications > APIs and select the API.
  2. Go to the Application Access tab.
  3. Scroll to the CIMD client, select Edit, and then Grant Access for User-Delegated Access and/or Client Access. Then, select your desired permissions.
  4. Select Save.

​
Default third-party grant

To create a default third-party grant using the Auth0 Dashboard:
  1. Navigate to Applications > APIs and select the API.
  2. Go to the Settings tab.
  3. Scroll to Default Permissions for Third-Party Applications.
  4. Select Authorized or All for User-Delegated Access or Client Access. If you selected Authorized, select the scopes to grant.
  5. Select Save.

​
Promote connections to domain level

Third-party applications, including CIMD clients, can only use domain-level connections. You can promote any connection type (Database, Social, Enterprise, or Passwordless) to the domain level. To promote a connection to the domain level using the Auth0 Dashboard:
  1. Navigate to Authentication and select the connection type (e.g., Database, Social, Enterprise).
  2. Create a new connection or select an existing one to configure.
  3. Under the Settings tab, scroll down to the Promote Connection to Domain Level setting, which is typically in the Advanced section.
  4. Enable the toggle switch.
  5. Select Save.

​
Refresh client metadata

Once you’ve registered the CIMD client, you can manually refresh client metadata. Auth0 fetches fresh client metadata from the CIMD, which you can preview and save. When you refresh client metadata, Auth0 updates the app_type and grant_types to match the values in the hosted CIMD. To learn more about CIMD fields, read CIMD JSON validation rules. In the Auth0 Dashboard:
  1. Navigate to Applications > Applications and select your CIMD client.
  2. At the top-right corner, select Refresh Client Metadata.
  3. Select Refresh Preview to preview the latest client metadata in the CIMD. Review any validation warnings or errors.
  4. Select Save.

​
Learn more