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.

• JWKS URI Same Origin: Whether the jwks_uri claim in the Client ID Metadata Document must have the same origin (scheme, host, and port) as the client ID. Defaults to true. Disabling this lets Ephemeral clients host their JWKS on a different origin (for example, a separate CDN), but weakens the trust binding between the client_id and the keys used for client authentication. Keep the default unless you have a specific reason to relax it.

• 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 support two values for token_endpoint_auth_method in the Client ID Metadata Document:

• private_key_jwt — the client authenticates with an asymmetrically-signed JWT (Asymmetrically Signed JWT). The client publishes its public keys either via a jwks_uri URL or inline in the jwks metadata field; exactly one of the two must be set. Allowed signing algorithms are configured in this section and must also be allowed at the OAuth Profile level.
• none — the client is a public client and does not authenticate to the token endpoint. Available only when the Authorization Code capability is enabled.

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:

• allow-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).

How the Server Fetches CIMDs#

When an Ephemeral client makes an OAuth request, the Curity Identity Server performs a single HTTP GET against the URL specified as the client ID, with Accept: application/json. Also:

• The server does not follow HTTP redirects when retrieving the document.
• Only an HTTP 200 OK response is accepted. Any other status (including 3xx) results in the OAuth request being rejected with invalid_client.

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 those defined in the IANA OAuth Dynamic Client Registration Metadata 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
• jwks: inline JSON Web Key Set, as an alternative to jwks_uri. Only one of the two may be set.
• 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
• authorization_signed_response_alg: signing algorithm for JARM responses
• id_token_encrypted_response_alg, id_token_encrypted_response_enc: ID token encryption settings, available when OpenID Connect and ID-token encryption are enabled on the Token Profile
• application_url: a Curity-specific extension to the spec, used to advertise the application’s primary URL on the consent screen

The following CIMD properties are not allowed and the request will be rejected with invalid_client_metadata if present:

• client_secret
• client_secret_expires_at