Client ID Metadata Documents

CIMD is the portable-client path in SqlOS.

Instead of creating a local client first, the client uses a stable HTTPS client_id. SqlOS fetches that URL, validates the JSON, and caches the metadata in the existing client store.

When to use it#

Use CIMD when:

• a client should work across many auth-server deployments
• the client already has a stable HTTPS home
• you want the client to own its redirect URIs, display metadata, and self-declared scope

Do not start here if you are just wiring your own first-party web app. Seed a client first and keep the first version simple.

Turn it on#

CIMD is disabled by default. With UseSingleApplication or ConfigureApplication, app.Mcp = "/mcp" turns it on together with resource indicators, because portable clients that speak MCP need both. On a host that does not declare Mcp, set the flags:

builder.AddSqlOS<AppDbContext>(
    db => db.UseSqlServer(connectionString),
    options =>
    {
        options.ConfigureApplication("Acme", app =>
        {
            app.Origin = "https://auth.example.com";
        });
        options.AuthServer.ClientRegistration.Cimd.Enabled = true;
        options.AuthServer.ClientRegistration.Cimd.DefaultCacheTtl = TimeSpan.FromHours(12);
        options.AuthServer.ClientRegistration.Cimd.TrustedHosts.Add("clients.example.com");
    });

Disable it explicitly when the host accepts only seeded or dashboard-managed clients:

options.AuthServer.ClientRegistration.Cimd.Enabled = false;

What SqlOS validates#

SqlOS expects:

• an HTTPS client_id with a path
• JSON whose client_id exactly matches the URL used
• client_name
• redirect_uris
• token_endpoint_auth_method=none in v1
• optional scope, stored as the client's registered allow-list

SqlOS also:

• validates redirect URIs from the document, not the dashboard
• matches loopback IP-literal redirects (http://127.0.0.1/..., http://[::1]/...) port-insensitively per RFC 8252 §7.3, so native clients like Codex can register a portless loopback redirect and bind an ephemeral port at login; scheme, address, path, and query must still match exactly, and localhost or HTTPS redirects always require an exact match
• accepts the document's self-declared scope as registered metadata (there is no separate CIMD ceiling; later grants still intersect requested scopes with that stored allow-list)
• treats a republished document that changes scope as a security-sensitive metadata change, the same as a redirect, grant-type, response-type, or token-endpoint auth-method change: active sessions are revoked and SqlOS records client.cimd.metadata-changed
• respects HTTP cache headers when possible
• uses a fallback TTL when needed
• records fetch and validation failures in audit events

openid in a CIMD document is an ordinary allow-listed string, and the document's scope behaves like any other allowlist: with OpenID Provider mode enabled (the default), declaring openid there makes the client OIDC-capable, and a grant that includes openid receives an id_token.

Trust policy#

TrustedHosts is checked before the network request. Use TrustPolicy when you also need to inspect parsed metadata after retrieval:

builder.AddSqlOS<AppDbContext>(options =>
{
    options.AuthServer.ClientRegistration.Cimd.TrustPolicy = async (context, cancellationToken) =>
    {
        if (!context.ClientIdUri.Host.EndsWith(".example.com", StringComparison.OrdinalIgnoreCase))
        {
            return SqlOSClientRegistrationPolicyDecision.Deny("Only example.com metadata hosts are allowed.");
        }
 
        return SqlOSClientRegistrationPolicyDecision.Allow();
    };
});

That is the right place for:

• host allowlists
• deny lists
• environment-specific trust decisions

Dashboard behavior#

CIMD clients appear in the normal client list with source and cache details.

Operators can:

• inspect the cached metadata
• disable the client
• revoke active sessions
• filter by source

Related guides#

• Preregistration vs CIMD vs DCR
• Dynamic Client Registration
• Todo Sample