OAuth Client ID Metadata Document
On this page
What is the Client ID Metadata Document?
OAuth Client ID Metadata Document (CIMD) refers to a draft specification that defines the client ID as an HTTPS URL that points to a JSON document, the client metadata document. This semantic definition of the client ID implies that each client gets a globally unique identifier that is connected to its client metadata.
The client metadata in OAuth describes the details about the client that are relevant for an OAuth integration. It includes information such as the client's supported grant types, redirect URIs and public keys. The client needs to register this metadata with the OAuth authorization server to get integrated and establish the trust.
Traditionally, the authorization server generates the client ID as part of the client registration. With the OAuth Client ID Metadata Document, there is no need to register the metadata with the authorization server upfront and maintain server-specific client IDs. Instead, the client can reuse the same client ID across authorization servers. Authorization servers retrieve the metadata from the client ID and establish the trust at runtime.
The client metadata document is tightly coupled to Dynamic Client Registration in the sense that it contains the same values, that is values from the IANA registry for OAuth Client Registration Metadata OAuth Parameters.
How Does It Work?
The first request in an OAuth flow is the authorization request. Among other parameters, it includes the client ID based on which the authorization server can identify the client, compare the request with the registered metadata, and apply its policies. Using Client ID Metadata Document, the client ID is an HTTPS URL, and the authorization server fetches the metadata from that URL instead of its internal registry.
The following figure illustrates a code flow with the Client ID Metadata Document. It starts with the authorization request that includes the client ID with the metadata endpoint. Upon receiving the request, the authorization server gets the metadata document from the endpoint, validates the metadata and applies its policies. The flow then continues as usual with user authentication and consent, and the authorization response with the authorization code to the client's redirect URI.
When the client redeems the authorization code, it sends a token request with the client ID that, again, contains the URL to the client metadata document. The client may also authenticate with its credentials that match the entries in the metadata. The authorization server gets the metadata from the endpoint, and validates it together with the client credentials. To avoid having to call the remote URL for the client metadata for every request that the client sends, the authorization server should cache the data.
The authorization server validates the metadata according to its policy. For example, it may restrict redirect URIs, logos and other URLs in the metadata to be the same origin as the client metadata URL. In addition, the authorization server may only trust certain clients to make use of a client ID metadata document and could restrict the domains from which it will attempt to get the metadata document.
Example of Client ID Metadata Document
The following sections showcase a subset of client metadata values for different use cases. Note that the client ID in the client metadata document is always the URL of the metadata document.
Public Client Using Code Flow
The following example lists the client metadata document of a public client that runs the code flow (grant_types includes authorization_code). Public clients are clients that cannot authenticate (token_endpoint_auth_method=none). The code flow requires the client to add redirect_uris so that the authorization server can return its response to the client.
{"client_id": "https://public.client.example/metadata.json","client_name": "Public Client (Example)","scope": "openid email read write","grant_types": ["authorization_code"],"redirect_uris": ["https://public.client.example/callback"],"token_endpoint_auth_method": "none"}
Confidential Client with Device Flow
The following snippet shows the client metadata for a confidential client that runs the device flow (grant_types includes urn:ietf:params:oauth:grant-type:device_code). Confidential clients that rely on Client ID Metadata Document must not use a token endpoint authentication method that is based on a shared secret (such as client_secret_post, client_secret_basic, or client_secret_jwt). It can use other authentication methods such as private_key_jwt or attest_jwt_client_auth.
{"client_id": "https://client.example/metadata.json","client_name": "Client (Example)","scope": "openid email read write","grant_types": ["urn:ietf:params:oauth:grant-type:device_code"],"token_endpoint_auth_method": "private_key_jwt","jwks_uri": "https://client.example/jwks"}
When to Make Use of Client ID Metadata Document
The Client ID Metadata Document is suitable for decentralized use cases
- where there are potentially many clients and authorization servers that do not have a prior relationship,
- where there is no authority that governs the ecosystem and
- where discovery is important.
Examples for such use cases are decentralized social media networks like Mastodon, or identity protocols like IndieAuth, as well as AI agents that connect to multiple tools in multiple trust domains. Consequently, the IndieAuth and MCP specification, for example, make use of the Client ID Metadata Document.
Judith Kahrer
Product Marketing Engineer at Curity
Join our Newsletter
Get the latest on identity management, API Security and authentication straight to your inbox.
Start Free Trial
Try the Curity Identity Server for Free. Get up and running in 10 minutes.
Start Free TrialWas this helpful?
