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 and display metadata

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. The helper below explicitly enables portable-client behavior and resource indicators without requiring a host allowlist:

builder.AddSqlOS<AppDbContext>(options =>
{
    options.AuthServer.EnablePortableMcpClients();
});

You can also configure it directly:

builder.AddSqlOS<AppDbContext>(options =>
{
    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

SqlOS also:

• validates redirect URIs from the document, not the dashboard
• respects HTTP cache headers when possible
• uses a fallback TTL when needed
• records fetch and validation failures in audit events

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