PingFederate Server

Client ID metadata documents (CIMD)

PingFederate supports Client ID Metadata Documents (CIMD) to allow OAuth clients to provide client metadata dynamically during runtime transactions. With CIMD, the client_id identifies the location of a metadata document that PingFederate retrieves and validates during the authorization flow. This model reduces the need to pre-register and manage each client individually.

Learn more in the CIMD specification.

CIMD changes the client registration model in the following ways:

  • Decentralized: Clients host and manage their own metadata instead of relying only on pre-registered metadata in PingFederate.

  • Just-in-time: PingFederate creates clients when it receives the initial authorization endpoint request, before user authentication on the sign-on page.

  • Ephemeral: CIMD clients exist only as long as they are needed for transaction processing and policy enforcement.

CIMD is an evolving draft specification. Because of the draft nature of the specification, future CIMD changes might not be backward compatible.

How CIMD works

When PingFederate receives a CIMD request, it first checks whether the CIMD feature is enabled. If CIMD is enabled, PingFederate evaluates the client_id value as the location of the client metadata document. PingFederate then performs the following processing:

  • Evaluates the request against enabled CIMD policies

  • Retrieves the client metadata document

  • Validates the metadata

  • Creates the client if the request is allowed

  • Applies the default settings defined by the matching CIMD policy

PingFederate rejects the request if no enabled CIMD policy matches the request or if the metadata document contains problems or inconsistencies.

CIMD design principles

CIMD balances client-managed metadata with administrator-defined controls.

The client metadata document is the source of truth for core client configuration. PingFederate administrators control CIMD processing through two layers: global CIMD settings, which define runtime limits such as caching and metadata retrieval behavior, and CIMD policies, which define allowed metadata document locations and default client settings.

PingFederate respects supported cache-control header values from metadata responses while still enforcing administrator-defined cache limits.

PingFederate does not remove CIMD clients immediately. If an existing CIMD client is expired or no longer matches an enabled CIMD policy, PingFederate removes the client when it encounters the client during a later CIMD request.

Troubleshooting and logging

Use the PingFederate logs to troubleshoot CIMD runtime behavior.

server.log

Configure PingFederate logging at the DEBUG level to review CIMD metadata retrieval activity, policy matching, missing policy results, and client deletion activity.

audit.log

Use the audit.log file to review standard runtime access activity for CIMD clients.