Client ID Metadata Document (CIMD)

The Client ID Metadata Document (CIMD) enables identity administrators and application developers to admit OAuth clients that use an HTTPS metadata URL as their client_id, in order to onboard MCP hosts, partner tools, and similar clients without pre-creating an application for every URL — while still controlling which hosts are trusted and which OAuth settings they may use.

Use case: Dynamically admit approved metadata hosts under one tenant policy (host allow/deny rules, ceilings, and defaults), instead of registering each client application manually.

When a client sends an HTTPS URL as its client_id, cidaas evaluates it against your tenant policy:

1. Is CIMD enabled?
2. Does a host rule allow the metadata URL?
3. Can the metadata document be fetched, and is it valid?
4. Do the client settings fit the ceilings?
5. Which defaults fill the settings a metadata document cannot carry?

If every check passes, cidaas continues the normal OAuth flow for that client.

Availability

CIMD must be enabled for your tenant. Contact cidaas support if it is not available yet.

---

Prerequisites

Before configuring CIMD, ensure you have:

1. CIMD enabled for your tenant.
2. An administrator account with the ADMIN or SECONDARY_ADMIN role, and the cidaas:apps_read (view) and cidaas:apps_write (save) scopes.
3. Access to Trustdesk for your tenant.
4. The list of metadata hosts (or host patterns) you intend to allow or deny — for example mcp.example.com or *.partner.example.com.
5. Agreement on ceilings (allowed scopes, grant types, token lifetimes, and related limits) and on defaults for the settings a metadata document cannot carry.

---

Configuration Steps

Step 1: Open the CIMD policy

1. Sign in to Trustdesk as an administrator.
2. Navigate to Integrations → App Management Policies.
3. Open the CIMD policy. When CIMD is enabled, cidaas creates a default policy for your tenant, so there is nothing to create.

The default policy is enabled but has no host rules, so it admits no client until you add an allow rule in Step 2. It starts with these values:

Setting	Default
Allowed scopes	openid, email, profile
Allowed grant types	authorization_code, refresh_token
Allowed response types	code
Allowed auth methods	none
Max redirect URIs	10
Max token lifetime / Max refresh token lifetime	4 hours / 24 hours
Token / Refresh token / Authorization code lifetime	4 hours / 24 hours / 10 minutes

Step 2: Configure host rules

Host rules decide which metadata URLs may be admitted. Rules are evaluated in order; the first match wins. A URL that matches no rule is refused, so an empty list admits no metadata host.

For each rule, set:

• Host: An exact host (for example mcp.example.com) or a wildcard such as *.example.com. Hosts are compared case-insensitively.
• Path prefix (optional): The URL path must start with this value. Leave it empty to match every path on the host.
• Effect: Allow or deny.

Wildcards

*.example.com matches a.example.com and a.b.example.com, but not example.com itself. To admit both, add one rule for each.

1. Click Add rule.
2. Enter the host, optional path prefix, and effect, then confirm with Add rule.
3. Repeat for every trusted host or pattern. Place each deny rule above the allow rule it makes an exception to; otherwise the allow rule matches first.

Examples:

• Allow a partner domain: host *.partner.example.com, effect allow.
• Allow one path on a shared host: host pages.example.com, path prefix /team-a/, effect allow.
• Deny one subdomain of an allowed pattern: host untrusted.partner.example.com, effect deny, placed before the *.partner.example.com allow rule.

Security

Prefer explicit allow rules for known hosts. Do not open broad wildcards unless you intend to trust every matching metadata URL under that pattern. On shared hosting (for example GitHub Pages), always set a path prefix; otherwise any user of that host can publish a document you admit.

Step 3: Configure ceilings and defaults

Ceilings limit what a CIMD client may use. How a value outside the ceilings is treated depends on the setting:

Setting outside the ceiling	Result
Grant type, response type, or auth method	The client is refused (invalid_client_metadata)
Redirect URI, or more redirect URIs than Max redirect URIs	The client is refused (invalid_redirect_uri)
Scope	The scope is removed; the client is admitted with the remaining scopes. openid is always allowed
refresh_token on a public client (auth method none)	The grant is removed, unless the policy allows refresh tokens for public clients

The only auth methods a CIMD client can use are none and private_key_jwt. Client secrets are never allowed.

Defaults fill the settings that a metadata document cannot carry: token, refresh token, and authorization code lifetimes, hosted pages layout, and user setup. Lifetime defaults are capped by the matching ceiling. A lifetime ceiling of 0 means the tenant's default lifetime applies as both default and cap. DPoP-bound access tokens applies only when the metadata document does not set dpop_bound_access_tokens.

1. In the Ceilings section, set the scopes, grant types, response types, auth methods, redirect URI limit, and lifetime limits CIMD clients may use.
2. In the Defaults section, set the lifetimes and setup values applied to admitted clients.

Step 4: Save

1. Leave CIMD enabled on. Turn it off only to stop admitting CIMD clients; your host rules, ceilings, and defaults are kept.
2. Click Save.

A saved policy applies to each client the next time it is used. You do not need to re-register clients or clear anything.

---

Publishing a metadata document

These rules apply to the developer who publishes the metadata document. A document that breaks them is refused, whatever the host rules say.

The URL (client_id):

• Uses https, with a path below / (for example https://mcp.example.com/client.json).
• Has no query, fragment, user info, or . / .. path segments.
• Has a DNS host name: not an IP address, localhost, .local, or .internal, and not on your cidaas tenant's own domain.
• Is at most 512 characters long.

The response:

• Answers 200 directly. Redirects are not followed, so link the exact file, not a folder.
• Has Content-Type: application/json, is at most 16 KiB, and arrives within 3 seconds.

The document:

• client_id is exactly the URL it is served from, character for character.
• token_endpoint_auth_method is set to none or private_key_jwt. If it is missing, it defaults to client_secret_basic, which CIMD never allows.
• private_key_jwt requires exactly one of jwks or jwks_uri.
• redirect_uris never use localhost. Native and CLI clients use 127.0.0.1 or [::1] instead; plain http is allowed only for these loopback addresses.

Example:

{
  "client_id": "https://mcp.example.com/client.json",
  "client_name": "Example MCP client",
  "redirect_uris": ["http://127.0.0.1:9000/oauth/callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

Caching

cidaas reuses a fetched document for as long as its Cache-Control (max-age) or Expires header allows, at least 5 minutes and at most 24 hours; without either header, for 1 hour. A change to the document may take up to that long to apply.

---

Verification

To verify that the configuration is working:

1. Open the CIMD policy again in Trustdesk.

2. Confirm your host rules, ceilings, defaults, and CIMD enabled state match what you saved.

3. From a client that publishes a metadata document at an allowed host, start a normal OAuth authorization (for example Authorization Code with PKCE) using that HTTPS URL as client_id.

4. Confirm the flow proceeds when the host is allowed and CIMD is enabled.

5. Confirm the flow is refused when:

   • CIMD is disabled, or
   • the metadata host does not match an allow rule (or matches a deny rule first).

---

Troubleshooting

Symptom	Root cause	Remediation
CIMD policy is not available in Trustdesk	CIMD is not enabled for the tenant	Contact cidaas support to enable CIMD
Metadata clients are never admitted	Host rules are empty, or no allow rule matches	Add an allow rule for the metadata host or pattern
A host you expected to allow is denied	A deny rule matches first, or the host or path prefix does not match	Re-order or correct host rules; check the path prefix
*.example.com does not admit https://example.com/...	A wildcard never matches the bare domain	Add a separate rule for example.com
Client is refused although the host is allowed	The document cannot be fetched: not 200, a redirect, wrong content type, larger than 16 KiB, or slower than 3 seconds	Serve the exact file URL over HTTPS as application/json (see Publishing a metadata document)
Client is refused although the document is reachable	client_id in the document differs from its URL	Set client_id to the exact URL, character for character
Client is refused with invalid_client_metadata	token_endpoint_auth_method is missing or not allowed, or a grant or response type is outside the ceilings	Set token_endpoint_auth_method to an allowed method; widen the ceilings or change the document
Client is refused with invalid_redirect_uri	A redirect URI uses localhost, uses http on a non-loopback host, or there are more URIs than the ceiling allows	Use 127.0.0.1 or [::1] for local callbacks and https elsewhere; raise Max redirect URIs
Tokens lack some requested scopes	Scopes outside the ceilings are removed	Add the scopes to Allowed scopes
A public client gets no refresh token	refresh_token is removed for public clients unless the policy allows it	Use private_key_jwt, or contact cidaas support to allow refresh tokens for public clients
A document change does not take effect	The previous document is still cached	Wait for the cache lifetime to pass (at most 24 hours); lower max-age on the document

---

Explore related topics

• App management — registering and configuring applications
• Standards & Security Extensions — choosing OAuth extensions
• Authorization Code and PKCE — interactive flows often used with CIMD clients

info

Need Support?

Contact cidaas support or [email protected].