Ephemeral Clients

They are one of the types of clients the Curity Identity Server supports.

Ephemeral clients are typically used by AI agents that need to interact with the Curity Identity Server without requiring long-term storage. They are created on-the-fly when an OAuth request is made, based on metadata that they publish in the form of Client ID Metadata Documents.

Ephemeral clients are disabled by default. They can be enabled in the OAuth Profile settings in the Admin UI:

Configuration#

The configuration of Ephemeral clients is divided into several sections:

General Settings#

• HTTP Client: An optional HTTP Client to use when fetching Client ID Metadata Documents and possibly other data (e.g. JWKS from a jwks_uri). If not set, the default HTTP Client is used. It may be desirable to use a custom HTTP Client if special TLS settings, timeout settings, etc. are needed.

• Localhost Allowed: Whether localhost URLs are allowed as client IDs for Ephemeral clients. This is useful for development and testing purposes, but should be disabled in production environments for security reasons.

• Cache: whether to cache Ephemeral client metadata once fetched. Caching improves performance and reduces latency, especially when the same Ephemeral clients are used frequently. After cache is enabled, additional settings are available to configure the cache behavior, such as Cache Duration and Cache Size.

Capabilities#

Ephemeral clients support a subset of the capabilities available to other client types. These capabilities can be enabled or disabled to control what OAuth flows Ephemeral clients can perform. The available capabilities are:

• Authorization Code
• Client Credentials
• OAuth Token Exchange

Client Authentication#

Ephemeral clients currently support only jwks_uri based client authentication (Asymmetrically Signed JWT), where the client publishes a JSON Web Key Set (JWKS) at a URL. The jwks_uri is published by clients in the Client ID Metadata Document.

Scopes#

Ephemeral clients can be restricted to specific scopes. There are two possible settings:

• all: Ephemeral clients can use all scopes defined on the Token Profile.
• selected: Ephemeral clients can only use a selected set of scopes.

Security#

• Access Token TTL: The Time-To-Live (TTL) for access tokens issued to Ephemeral clients. Defaults to 300 seconds (5 minutes).
• ID Token TTL: The Time-To-Live (TTL) for ID tokens issued to Ephemeral clients. Available only when OpenID Connect is enabled on the Token Profile.

Settings available only when the Code capability is enabled:

• Refresh Token TTL: The Time-To-Live (TTL) for refresh tokens issued to Ephemeral clients.
• Refresh Token Max Rolling Lifetime: The maximum rolling lifetime for refresh tokens issued to Ephemeral clients.
• Reuse Refresh Tokens: Whether refresh tokens issued to Ephemeral clients are created with every refresh or not.
• Require Request Object: Whether Ephemeral clients must use JWT-secured OAuth 2.0 authorization requests (JAR) when performing the authorization code flow.
• Require Pushed Authorization Requests: Whether Ephemeral clients must use pushed authorization requests (PAR) when performing the authorization code flow.
• Require Secured Authorization Response: Whether Ephemeral clients must use JWT Secured Authorization Response Mode (JARM) when performing the authorization code flow.

Client ID Restrictions#

This setting allows restricting which domains can be used in Ephemeral client IDs. There are two types of restrictions:

• allows-list: Only client IDs from the specified domains are allowed.
• deny-list: Only client IDs that are NOT in the specified domains are allowed.

Both lists support wildcard entries at the beginning of the domain, e.g. *.example.com to match any subdomain of example.com. Entries like these are not supported: sub.*.com or *example.com.

Authenticators#

Ephemeral clients can be restricted to use specific authenticators for user authentication during the authorization code flow. This setting is only available when the Code capability is enabled. There are two possible settings:

• all: Ephemeral clients can use all authenticators defined on the linked Authentication Profile.
• selected: Ephemeral clients can only use selected authenticators.

User Consent#

Ephemeral clients can be configured to require user consent before issuing tokens. When enabled, users will be prompted to consent to the scopes requested by the Ephemeral client during the authorization code flow.

The following settings are available:

• Allow Deselection: Whether users are allowed to deselect scopes during the consent process.
• Only Consentors: Whether only the defined consentors will be run, or if the user will also be shown a consent screen.
• Consentor: List of consentors to run for Ephemeral clients. If empty, then all consentors defined on the Token Profile are run.
• Show Client Logo: Whether to show the client logo (if available - it is taken from the Client ID Metadata Document’s logo_uri entry) on the consent screen. Defaults to false, as that is more secure. If disabled, the default logo is shown.

Client ID Metadata Documents (CIMDs)#

Ephemeral clients are supposed to publish a Client ID Metadata Document (CIMD) at a well-known URL (same as their client ID). This document is a JSON object containing metadata about the client, such as its redirect URIs, authentication methods and more. The document is specified in the Client ID Metadata Document specification (currently a draft).

When an Ephemeral client makes an OAuth request, the Curity Identity Server fetches the Client ID Metadata Document from the URL specified as the client ID. The metadata is then used to configure the client for the duration of the request. If caching is enabled, the metadata is cached for subsequent requests (for the configured cache duration).

The client metadata values are the values in CIMDs defined in the OAuth Dynamic Client Registration Metadata OAuth Parameters registry. Currently supported values include:

• redirect_uris
• token_endpoint_auth_method: only private_key_jwt is supported with combination of jwks_uri parameter
• grant_types
• client_name
• client_uri
• logo_uri
• scope
• tos_uri
• policy_uri
• jwks_uri
• client_id
• request_object_signing_alg
• token_endpoint_auth_signing_alg
• default_max_age
• default_acr_values
• request_uris
• require_pushed_authorization_requests
• frontchannel_logout_uri
• post_logout_redirect_uris
• application_url: a custom extension parameter to specify the application URL