fastmcp.server.auth.cimd

CIMD (Client ID Metadata Document) support for FastMCP.

.. warning:: Beta Feature: CIMD support is currently in beta. The API may change in future releases. Please report any issues you encounter.

CIMD is a simpler alternative to Dynamic Client Registration where clients host a static JSON document at an HTTPS URL, and that URL becomes their client_id. See the IETF draft: draft-parecki-oauth-client-id-metadata-document

This module provides:

• CIMDDocument: Pydantic model for CIMD document validation
• CIMDFetcher: Fetch and validate CIMD documents with SSRF protection
• CIMDClientManager: Manages CIMD client operations

Classes

CIMDDocument ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L45" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

CIMD document per draft-parecki-oauth-client-id-metadata-document.

The client metadata document is a JSON document containing OAuth client metadata. The client_id property MUST match the URL where this document is hosted.

Key constraint: token_endpoint_auth_method MUST NOT use shared secrets (client_secret_post, client_secret_basic, client_secret_jwt).

redirect_uris is required and must contain at least one entry.

Methods:

validate_auth_method ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L125" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

validate_auth_method(cls, v: str) -> str

Ensure no shared-secret auth methods are used.

validate_redirect_uris ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

validate_redirect_uris(cls, v: list[str]) -> list[str]

Ensure redirect_uris is non-empty and each entry is a valid URI.

CIMDValidationError ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L154" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Raised when CIMD document validation fails.

CIMDFetchError ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L158" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Raised when CIMD document fetching fails.

CIMDFetcher ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L186" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Fetch and validate CIMD documents with SSRF protection.

Delegates HTTP fetching to ssrf_safe_fetch_response, which provides DNS pinning, IP validation, size limits, and timeout enforcement. Documents are cached using HTTP caching semantics (Cache-Control/ETag/Last-Modified), with a TTL fallback when response headers do not define caching behavior.

Methods:

is_cimd_client_id ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L270" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

is_cimd_client_id(self, client_id: str) -> bool

Check if a client_id looks like a CIMD URL.

CIMD URLs must be HTTPS with a host and non-root path.

fetch ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L287" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

fetch(self, client_id_url: str) -> CIMDDocument

Fetch and validate a CIMD document with SSRF protection.

Uses ssrf_safe_fetch_response for the HTTP layer, which provides:

• HTTPS only, DNS resolution with IP validation
• DNS pinning (connects to validated IP directly)
• Blocks private/loopback/link-local/multicast IPs
• Response size limit and timeout enforcement
• Redirects disabled

Args:

• client_id_url: The URL to fetch (also the expected client_id)

Returns:

• Validated CIMDDocument

Raises:

• CIMDValidationError: If document is invalid or URL blocked
• CIMDFetchError: If document cannot be fetched

validate_redirect_uri ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L422" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

validate_redirect_uri(self, doc: CIMDDocument, redirect_uri: str) -> bool

Validate that a redirect_uri is allowed by the CIMD document.

Uses component-level matching (scheme, host, port, path) which correctly handles RFC 8252 §7.3 loopback port flexibility and wildcard patterns.

Args:

• doc: The CIMD document
• redirect_uri: The redirect URI to validate

Returns:

• True if valid, False otherwise

CIMDAssertionValidator ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L450" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Validates JWT assertions for private_key_jwt CIMD clients.

Implements RFC 7523 (JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants) for CIMD client authentication.

JTI replay protection uses TTL-based caching to ensure proper security:

• JTIs are cached with expiration matching the JWT's exp claim
• Expired JTIs are automatically cleaned up
• Maximum assertion lifetime is enforced (5 minutes)

Methods:

validate_assertion ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L493" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

validate_assertion(self, assertion: str, client_id: str, token_endpoint: str, cimd_doc: CIMDDocument) -> bool

Validate JWT assertion from client.

Args:

• assertion: The JWT assertion string
• client_id: Expected client_id (must match iss and sub claims)
• token_endpoint: Token endpoint URL (must match aud claim)
• cimd_doc: CIMD document containing JWKS for key verification

Returns:

• True if valid

Raises:

• ValueError: If validation fails

CIMDClientManager ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L675" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Manages all CIMD client operations for OAuth proxy.

This class encapsulates:

• CIMD client detection
• Document fetching and validation
• Synthetic OAuth client creation
• Private key JWT assertion validation

This allows the OAuth proxy to delegate all CIMD-specific logic to a single, focused manager class.

Methods:

is_cimd_client_id ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L709" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

is_cimd_client_id(self, client_id: str) -> bool

Check if client_id is a CIMD URL.

Args:

• client_id: Client ID to check

Returns:

• True if client_id is an HTTPS URL (CIMD format)

get_client ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L720" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

get_client(self, client_id_url: str)

Fetch CIMD document and create synthetic OAuth client.

Args:

• client_id_url: HTTPS URL pointing to CIMD document

Returns:

• OAuthProxyClient with CIMD document attached, or None if fetch fails

validate_private_key_jwt ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L769" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

validate_private_key_jwt(self, assertion: str, client, token_endpoint: str) -> bool

Validate JWT assertion for private_key_jwt auth.

Args:

• assertion: JWT assertion string from client
• client: OAuth proxy client (must have cimd_document)
• token_endpoint: Token endpoint URL for aud validation

Returns:

• True if assertion is valid

Raises:

• ValueError: If client doesn't have CIMD document or validation fails