Skip to content

cimdoptions.md

Latest commit

 

History

History
22 lines (14 loc) · 30.6 KB

cimdoptions.md

File metadata and controls

22 lines (14 loc) · 30.6 KB
Raw

CimdOptions

Options for OAuth Client ID Metadata Document (CIMD).

These options allow per-request control over CIMD behavior, taking precedence over service-level configuration when provided.

Example Usage

import { CimdOptions } from "@authlete/typescript-sdk/models";

let value: CimdOptions = {};

Fields

Field Type Required Description
alwaysRetrieved boolean ➖ Whether to always retrieve client metadata in the CIMD context regardless of the cache's validity.

Under normal circumstances, client metadata retrieved from the location referenced by the client ID is stored in the database with an expiration time calculated using HTTP caching mechanisms (see RFC 9111 HTTP Caching). Until that expiration time is reached, Authlete does not attempt to retrieve the client metadata again.

When this flag is set to true, Authlete retrieves the client metadata regardless of the cache's validity.

If this flag is included in an Authlete API call and its value is true, it takes precedence over the corresponding service configuration (see Service.cimdAlwaysRetrieved).

This flag is effective only when the service supports CIMD (see Service.clientIdMetadataDocumentSupported) and CIMD is actually used to resolve client metadata. For example, if the client ID in a request does not appear to be a valid URI, CIMD will not be used even if the service is configured to support it. In such cases, this flag has no effect.

Client metadata retrieval is performed only in the initiating request of an authorization flow, and not in any subsequent requests. For example, in the authorization code flow, metadata may be retrieved during the authorization request, but not during the subsequent token request. In contrast, in the client credentials flow, metadata retrieval may occur because the token request itself is the initiating request in the flow.
httpPermitted boolean ➖ Whether to allow the http scheme in client IDs in the CIMD context.

The specification requires the https scheme, but if this flag is set to true, Authlete also allows the http scheme. The main purpose of this option is to make development easier for developers who run CIMD-enabled servers and a web server publishing client metadata on their local machines without TLS.

Given this purpose, it is not recommended to enable this option in production environments unless an allowlist is used (see Service.cimdAllowlistEnabled).

If this flag is included in an Authlete API call and its value is true, it takes precedence over the corresponding service configuration (see Service.cimdHttpPermitted).
queryPermitted boolean ➖ Whether to allow a query component in client IDs in the CIMD context.

Although the specification states that a client ID "SHOULD NOT include a query string component," it does technically allow it. However, query components are prone to misuse. Therefore, Authlete does not allow them by default. Setting this flag to true relaxes that restriction.

If this flag is included in an Authlete API call and its value is true, it takes precedence over the corresponding service configuration (see Service.cimdQueryPermitted).