Package com.authlete.common.dto

Class CimdOptions

java.lang.Object

com.authlete.common.dto.CimdOptions

All Implemented Interfaces:

Serializable

public class CimdOptions
extends Object
implements Serializable

Options for OAuth Client ID Metadata Document (CIMD).

Since:

4.30, Authlete 3.0.22

See Also:

OAuth Client ID Metadata Document, Serialized Form

Constructor Summary

Constructors

Constructor	Description
CimdOptions()

Method Summary

Modifier and Type	Method	Description
boolean	isAlwaysRetrieved()	Get the flag that indicates whether Authlete should always fetch the client metadata from the location specified by the client ID, regardless of whether a cached copy already exists and has not yet expired.
boolean	isHttpPermitted()	Get the flag that indicates whether the http scheme in the client ID is permitted.
boolean	isQueryPermitted()	Get the flag that indicates whether a query component in the client ID is permitted.
CimdOptions	setAlwaysRetrieved(boolean always)	Set the flag that indicates whether Authlete should always fetch the client metadata from the location specified by the client ID, regardless of whether a cached copy already exists and has not yet expired.
CimdOptions	setHttpPermitted(boolean permitted)	Set the flag that indicates whether the http scheme in the client ID is permitted.
CimdOptions	setQueryPermitted(boolean permitted)	Set the flag that indicates whether a query component in the client ID is permitted.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CimdOptions

public CimdOptions()

Method Detail

isAlwaysRetrieved

public boolean isAlwaysRetrieved()

Get the flag that indicates whether Authlete should always fetch the client metadata from the location specified by the client ID, regardless of whether a cached copy already exists and has not yet expired.

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.isCimdAlwaysRetrieved()).

This flag is effective only when the service supports CIMD (see Service.isClientIdMetadataDocumentSupported()) 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.

Returns:

true if Authlete attempts to retrieve client metadata regardless of the cache's validity.

setAlwaysRetrieved

public CimdOptions setAlwaysRetrieved(boolean always)

Set the flag that indicates whether Authlete should always fetch the client metadata from the location specified by the client ID, regardless of whether a cached copy already exists and has not yet expired.

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.isCimdAlwaysRetrieved()).

This flag is effective only when the service supports CIMD (see Service.isClientIdMetadataDocumentSupported()) 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.

Parameters:

always - true to instruct Authlete to retrieve client metadata regardless of the cache's validity.

Returns:

this object.

isHttpPermitted

public boolean isHttpPermitted()

Get the flag that indicates whether the http scheme in the client ID is permitted.

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 a whitelist is used (see Service.isCimdWhitelistEnabled()).

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.isCimdHttpPermitted()).

Returns:

true if the http scheme in the client ID is permitted.

setHttpPermitted

public CimdOptions setHttpPermitted(boolean permitted)

Set the flag that indicates whether the http scheme in the client ID is permitted.

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 a whitelist is used (see Service.isCimdWhitelistEnabled()).

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.isCimdHttpPermitted()).

Parameters:

permitted - true to permit the http scheme in the client ID.

Returns:

this object.

isQueryPermitted

public boolean isQueryPermitted()

Get the flag that indicates whether a query component in the client ID is permitted.

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.isCimdQueryPermitted()).

Returns:

true if a query component in the client ID is permitted.

setQueryPermitted

public CimdOptions setQueryPermitted(boolean permitted)

Set the flag that indicates whether a query component in the client ID is permitted.

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.isCimdQueryPermitted()).

Parameters:

permitted - true to permit a query component in the client ID.

Returns:

this object.