> ## Documentation Index > Fetch the complete documentation index at: https://developers.authlete.com/llms.txt > Use this file to discover all available pages before exploring further. # Service Configurations > This page documents all the services settings available to configure Authlete service for your Authorization Server. Easily set and manage these configurations through the Authlete Management Console or directly via the Authlete APIs. # Service Settings * [Basic](#basic-settings) * [Endpoints](#endpoints-global-settings) * [Global Settings](#endpoints-global-settings) * [Authorization](#endpoints-authorization) * [Token](#endpoints-token) * [General](#endpoints-general) * [Federation](#endpoints-federation) * [Advanced](#endpoints-advanced) * [Token and Claims](#tokens-and-claims-access-token) * [Access Token](#tokens-and-claims-access-token) * [Refresh Token](#tokens-and-claims-refresh-token) * [ID Token](#tokens-and-claims-id-token) * [Claims](#tokens-and-claims-claims) * [Advanced](#tokens-and-claims-advanced) * [Key Management](#key-management-hsm) * [JWK Set](#key-management-jwk-set) * [HSM](#key-management-hsm) * [Metadata](#metadata) * [Verifiable Credentials](#verifiable-credentials) This page documents all the services settings available to configure Authlete service for your authorization server. You can manage these configurations through the [Authlete Management Console](https://console.authlete.com) or via the [Authlete APIs](https://docs.authlete.com/). ## Basic Settings ### Service Name A name of this service. Up to 100 Unicode characters. ### Service Description A description of this service. Up to 200 Unicode characters. ### Issuer Identifier An identifier of this service as an OpenID Provider. Authlete uses it as the value of the "iss" claim in [ID token](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) issued by this service. Additionally, if the Authorization Server implements a discovery endpoint (OpenID Connect Discovery 1.0, [4. Obtaining OpenID Provider Configuration Information](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig)) using Authlete's [Service Configuration API](/api-reference) (`GET /api/{serviceId}/service/configuration`), Authlete uses it as the value of the "issuer" property included in the response from the endpoint. The default value is "[https://authlete.com](https://authlete.com)." Change this value in a production environment. This must be an URL starting with "https\://" and excluding the query part and the fragment part. The URL of a discovery endpoint must be `{Token-Issuer-Identifier}/.well-known/openid-configuration`, so be careful when determining the value of the token issuer identifier if your service exposes a discovery endpoint. See OpenID Connect Discovery 1.0, [4. Obtaining OpenID Provider Configuration Information](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig) for details. ### Supported Custom Client Metadata Names of custom client metadata that this service supports. Some names, such as `client_name`, are reserved and not supported. ### Service Attributes Attributes of this service. You can associate arbitrary key-value pairs with the service for any purpose. The associated attributes are embedded in responses of some Authlete APIs (e.g., `/api/auth/introspection` API). In most cases, they are embedded as the value of `serviceAttributes`, but in cases where a response contains `service`, the attributes are embedded as the value of `attributes` in the `service` JSON object. The attributes are encrypted and stored in Authlete's database. ### Access Tokens This section allows you to generate Service Access Tokens with `use_service` permissions. These tokens grant you the necessary permissions to manage the service and its clients, as well as to call all essential endpoints required for implementing your Authorization Server. Use this access token alongside your Service ID and cluster URL in your Authorization Server implementation. ## Endpoints: Global Settings ### Supported Grant Types Grant types supported by this service. This configuration item indicates which flows defined in RFC 6749 are supported. If the Authorization Server implements a discovery endpoint with Authlete's `/api/service/configuration` API, the value of this configuration item is used as the value of the `grant_types_supported` property included in the response from the endpoint. Client applications can use only the flows enabled in this setting. Using an unsupported flow results in an error. **AUTHORIZATION\_CODE** is a flow to get issued an authorization code at the authorization endpoint and exchange it for an access token at the token endpoint. Details are described in RFC 6749, [4.1. Authorization Code Grant](https://tools.ietf.org/html/rfc6749?#section-4.1). This is the most common flow. **IMPLICIT** is a flow to get issued an access token directly at the authorization endpoint. Details are described in RFC 6749, [4.2. Implicit Grant](https://tools.ietf.org/html/rfc6749?#section-4.2). This flow is used, for example, to issue access tokens directly to JavaScript applications that run in web browsers. **PASSWORD** is a flow to get issued an access token by presenting a user's credentials (ID & password) at the token endpoint. Details are described in RFC 6749, [4.3. Resource Owner Password Credentials Grant](https://tools.ietf.org/html/rfc6749?#section-4.3). As stated in the specification, use this flow only when other flows cannot be used for some reason. If you don't have a clear reason, disable this flow in a commercial environment. **CLIENT\_CREDENTIALS** is a flow to get issued an access token by presenting a client application's credentials (client ID and client secret) at the token endpoint. Details are described in RFC 6749, [4.4. Client Credentials Grant](https://tools.ietf.org/html/rfc6749?#section-4.4). Access tokens issued by this flow are not associated with any user. If you don't have a clear reason to issue such access tokens, disable this flow in a commercial environment. **REFRESH\_TOKEN** is a flow to get a new access token by presenting a refresh token at the token endpoint. Details are described in RFC 6749, [6. Refreshing an Access Token](https://tools.ietf.org/html/rfc6749?#section-6). If this flow is disabled, refresh tokens are not issued. \[cf.] [Diagrams And Videos Of All The OAuth 2.0 Flows](https://medium.com/@darutk/diagrams-and-movies-of-all-the-oauth-2-0-flows-194f3c3ade85) **CIBA** (TBD) **DEVICE\_CODE** (TBD) **TOKEN\_EXCHANGE** (TBD) **JWT\_BEARER** (TBD) **PRE\_AUTHORIZED\_CODE** (TBD) ### Supported Response Types Supported combinations of tokens issued from the authorization endpoint. If the Authorization Server implements a discovery endpoint with Authlete's `/api/service/configuration` API, the value of this configuration item is used as the value of the `response_types_supported` property included in the response from the endpoint. In RFC 6749, what can be issued at a time at the authorization endpoint is either an authorization code or an access token, but the additional specification of [OAuth 2.0 Multiple Response Type Encoding Practices](https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html) has enabled issuing any combination of an authorization code, an access token, and an ID token. Also, an option to issue nothing (none) has been added. **NONE**, **CODE**, **TOKEN**, and **ID\_TOKEN** mean that "none", "code", "token", and "id\_token" can be independently specified as a value of the `response_type` parameter of an authorization request, respectively. **CODE\_TOKEN** means that the combination of "code" and "token" (in no particular order) can be specified as the value of the `response_type` parameter. Likewise, **CODE\_ID\_TOKEN** represents the combination of "code" and "id\_token", **ID\_TOKEN\_TOKEN** represents the combination of "id\_token" and "token", and **CODE\_ID\_TOKEN\_TOKEN** represents the combination of "code", "id\_token", and "token". Client applications cannot use combinations disabled here as the value of the `response_type` request parameter. If you don't have a clear reason, leave all the combinations enabled (it is up to you whether to enable or disable "none"). \[cf.] [Diagrams of All The OpenID Connect Flows](https://medium.com/@darutk/diagrams-of-all-the-openid-connect-flows-6968e3990660) ### Error Details ### Include Error Description If enabled, error responses from your authorization server will include the `error_description` response parameter. `error_description` is a standard response parameter defined in RFC 6749, but its content depends on each authorization server implementation. On error cases, Authlete sets an error description to the `error_description` response parameter. The content of the description may either be generic or Authlete-specific. In either case, it contains an Authlete-specific result code. If you want to hide the information in a production environment, disable this setting. However, note that in that case, error information returned to client applications will become very simple (e.g., "error=invalid\_request" only), so it may take longer for client application developers to find error causes. ### Include Error URI If enabled, error responses from your authorization server will include the `error_uri` response parameter. `error_uri` is a standard response parameter defined in RFC 6749, but its content depends on each authorization server implementation. On error cases, Authlete sets a URI to the `error_uri` response parameter, which points to the page that contains the list of error descriptions. The page exists on Authlete's website. If you want to hide the information in a production environment, disable this setting. ## Endpoints: Authorization ### Authorization Endpoint URL An URL of the authorization endpoint. If the Authorization Server implements a discovery endpoint with Authlete's `/api/service/configuration` API, the value of this configuration item is used as the value of the `authorization_endpoint` property included in the response from the endpoint. [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) states the `authorization_endpoint` property is REQUIRED. Therefore, if you want to comply with the specification completely, set a proper value to this configuration item. ### Proof Key for Code Exchange (PKCE) ### Require PKCE **\[Enabled recommended]** This configuration item determines whether to require the `code_challenge` request parameter as a mandatory parameter in the authorization code flow. If enabled, authorization requests using the authorization code flow without the `code_challenge` request parameter are all rejected. If disabled, the `code_challenge` request parameter becomes optional, but even in this case, if an authorization request includes the request parameter, it is handled as the specification defines. As a result, the token request that corresponds to the authorization request with the `code_challenge` request parameter has to include a `code_verifier` request parameter. The `code_challenge` is defined in [RFC 7636](https://tools.ietf.org/html/rfc7636) (Proof Key for Code Exchange by OAuth Public Clients). This specification is a countermeasure for the authorization code interception attack. If your system allows smartphone applications to use the authorization code flow, the `code_challenge` request parameter is almost mandatory from a security standpoint. If enabled, your system will become more secure. However, keep in mind that client application developers are required to do additional work. If you don't have a reason like "we have to support existing client applications that don't support PKCE," especially if you build a new service and develop a new client application, "Required" is recommended in a production environment. ### Require S256 for Code Challenge Method (TBD) \[cf.] [Proof Key for Code Exchange (RFC 7636)](https://www.authlete.com/documents/article/pkce) ### Authorization Response Duration The duration of authorization response [JWTs](https://tools.ietf.org/html/rfc7519) in seconds. [Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/openid-financial-api-jarm.html) defines the following new values for the `response_mode` request parameter: * `query.jwt` * `fragment.jwt` * `form_post.jwt` * `jwt` If one of these is specified as the response mode, response parameters from the authorization endpoint will be packed into a JWT. This value is used to compute the value of the `exp` claim of the JWT. The maximum value is 999999999999999 seconds (about 31.7 million years). ### Issuer Identification Response Parameter If **Suppress** is selected, the authorization server does not include the `iss` response parameter in authorization responses. "OAuth 2.0 Authorization Server Issuer Identifier in Authorization Response" has defined a new authorization response parameter, `iss`, as a countermeasure for a certain type of mix-up attacks. The specification requires that the `iss` response parameter always be included in authorization responses unless JARM (JWT Secured Authorization Response Mode) is used. By switching this configuration item, developers of client applications can experiment with the mix-up attack and the effect of the `iss` response parameter. Note that you should not select **Suppress** in a production environment unless there are special reasons for it. ### Loopback Redirection URI This is a flag indicating whether the port number component of redirection URIs can be variable when the host component denotes loopback. When **Variable** is selected, if the host component of a redirection URI specified in an authorization request denotes loopback (to be precise, when the host component is `localhost`, `127.0.0.1`, or `::1`), the port number component is ignored when the specified redirection URI is compared to pre-registered ones. This behavior is described in [7.3. Loopback Interface Redirection](https://www.rfc-editor.org/rfc/rfc8252.html#section-7.3) of [RFC 8252 OAuth 2.0 for Native Apps](https://www.rfc-editor.org/rfc/rfc8252.html). [3.1.2.3. Dynamic Configuration](https://www.rfc-editor.org/rfc/rfc6749.html#section-3.1.2.3) of [RFC 6749](https://www.rfc-editor.org/rfc/rfc6749.html) states: ***"If the client registration included the full redirection URI, the authorization server MUST compare the two URIs using simple string comparison as defined in \[RFC3986] Section 6.2.1."*** Also, the description of `redirect_uri` in [3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) of [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) states: ***"This URI MUST exactly match one of the Redirection URI values for the Client pre-registered at the OpenID Provider, with the matching performed as described in Section 6.2.1 of \[RFC3986] (Simple String Comparison)."*** These "Simple String Comparison" requirements are preceded by this flag. That is, even when the conditions described in RFC 6749 and OpenID Connect Core 1.0 are satisfied, the port number component of loopback redirection URIs can be variable when this flag is true (**Variable**). [8.3. Loopback Redirect Considerations](https://www.rfc-editor.org/rfc/rfc8252.html#section-8.3) of [RFC 8252](https://www.rfc-editor.org/rfc/rfc8252.html) states: > *`"While redirect URIs using localhost (i.e., http://localhost:{port}/{path}) function similarly to loopback IP redirects described in Section 7.3, the use of localhost is NOT RECOMMENDED. Specifying a redirect URI with the loopback IP literal rather than localhost avoids inadvertently listening on network interfaces other than the loopback interface. It is also less susceptible to client-side firewalls and misconfigured host name resolution on the user's device."`* However, Authlete allows the port number component to be variable in the case of `localhost`, too. It is left to client applications whether they use `localhost` or a literal loopback IP address (`127.0.0.1` for IPv4 or `::1` for IPv6). Section 7.3 and Section 8.3 of [RFC 8252](https://www.rfc-editor.org/rfc/rfc8252.html) state that loopback redirection URIs use the `http` scheme, but Authlete allows the port number component to be variable in other cases (e.g., in the case of the `https` scheme), too. Because FAPI 1.0 Part 1 [Section 7.5. Native Apps](https://openid.net/specs/openid-financial-api-part-1-1_0-final.html#native-apps) explicitly states: *"shall not support Loopback Interface Redirection"* the port number component of loopback redirection URIs cannot be variable in the context of FAPI, even if **Variable** is selected. ### Supported Locales A list of display languages supported on the authorization page of your authorization server. Technically, this is a list of [language tags](https://tools.ietf.org/html/rfc5646#section-2) ([RFC 5646](https://tools.ietf.org/html/rfc5646)) that the authorization endpoint recognizes as the value of the `ui_locales` parameter ([OpenID Connect Core 1.0, 3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)). If the Authorization Server implements a discovery endpoint with Authlete's `/api/service/configuration` API, the value of this configuration item is used as the value of the `ui_locales_supported` property included in the response from the endpoint. A client application may specify display languages for the authorization page by using the `ui_locales` request parameter. However, it is not assured that the authorization server honors the request parameter and changes the display language accordingly. Even if the authorization server completely ignores the `ui_locales` parameter, it is not a specification violation. Probably, most authorization server implementations recognize the Accept-Language HTTP header but don't recognize the `ui_locales` request parameter. The value of the `ui_locales` parameter in an authorization request is included in a response from Authlete's `/api/auth/authorization` API as the value of the `uiLocales` property. However, languages that are not listed in this configuration item will never be included in the `uiLocales`. For example, even if an authorization request includes `ui_locales=ja`, if "ja" is not listed in this configuration item, "ja" will not appear in the `uiLocales` property in the response from `/api/auth/authorization` API. If your authorization endpoint implementation ignores the `ui_locales` request parameter, you can leave this configuration item empty. ### Supported Display Types A list of display types supported on the authorization page of your authorization server. Technically, this is a list of valid values that the authorization endpoint recognizes as the value of the `display` parameter ([OpenID Connect Core 1.0, 3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)). If the Authorization Server implements a discovery endpoint with Authlete's `/api/service/configuration` API, the value of this configuration item is used as the value of the `display_values_supported` property included in the response from the endpoint. **PAGE** is the default value to request the entire drawing area of the user agent to be used. If this display type is checked, `display=page` can be included in an authorization request. If this display type is disabled, Authlete regards all authorization requests that don't include the `display` request parameter explicitly as invalid requests. Therefore, don't disable this display type. **POPUP** is the value to request a popup to be used. If this display type is checked, `display=popup` can be included in an authorization request. **TOUCH** is the value to request a page suitable for touch devices. If this display type is checked, `display=touch` can be included in an authorization request. **WAP** is the value to request a page suitable for feature phones. If this display type is checked, `display=wap` can be included in an authorization request. A client application may specify a display type for the authorization page by using the `display` request parameter. However, it is not assured that the authorization server honors the request parameter and changes the display type accordingly. Even if the authorization server completely ignores the `display` parameter, it is not a specification violation. If a value that is not checked in this configuration item is used as the value of the `display` request parameter, the authorization server returns an error. The value of the `display` parameter in an authorization request is included in a response from Authlete's `/api/auth/authorization` API as the value of the `display` property. If the authorization request does not include the `display` parameter, the value of the `display` property in the response from `/api/auth/authorization` API becomes the default value, **PAGE**. If you don't have a clear reason, leave all the display types checked. ### Supported Authentication Context Class References Authentication context class references supported for user authentication at the authorization endpoint. If the Authorization Server implements a discovery endpoint with Authlete's `/api/service/configuration` API, the value of this configuration item is used as the value of the `acr_values_supported` property included in the response from the endpoint. A client application may specify authentication contexts it wants to be satisfied when the authorization server processes an authorization request. The means to specify authentication contexts are (1) the `acr_values` request parameter ([OpenID Connect Core 1.0, 3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)), (2) the `acr` claim in the `claims` request parameter ([OpenID Connect Core 1.0, 5.5. Requesting Claims using the "claims" Request Parameter](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter)), and (3) the `default_acr_values` metadata ([OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata)) of the client application. Even if authentication contexts are specified by the means above, values not listed in this configuration item will be dropped on Authlete's side. For example, even if an authorization request includes `acr_values=my_acr`, `my_acr` won't be included in the `acrs` property in the response from Authlete's `/api/auth/authorization` API if `my_acr` is not included in this configuration item. If you do not plan to implement an authorization server that refers to the value of specified authentication contexts and changes its behavior accordingly, you can leave this configuration item empty. The [UK Open Banking](https://www.openbanking.org.uk/) defines at least two authentication contexts: "urn:openbanking:psd2:sca" and "urn:openbanking:psd2:ca". ### Request Object If **Require** is selected, authorization requests to this service must always specify a request object by using the `request` or `request_uri` parameter. If **Require** is selected here and **JAR compatible** is selected in **Request Object Processing**, this service behaves as if `require_signed_request_object` server metadata is `true`. See the specification of JAR (JWT Secured Authorization Request) for details about the server metadata. ### Request Object Processing If **Enable JAR Compatibility** is selected, request objects are processed based on the rules defined in JAR (JWT Secured Authorization Request). If not, the rules defined in OpenID Connect Core 1.0 apply for backward compatibility. Differences between JAR rules and OIDC Core 1.0 rules are as follows: 1. JAR requires that request objects be always signed. 2. JAR prohibits referring to request parameters outside the request object. As a result, when JAR rules apply, parameters outside the request object and parameters inside the request object are not merged. 3. OIDC Core 1.0 requires that the `response_type` query/form parameter be present outside the request object even when the request object contains `response_type`. On the contrary, when JAR rules apply, the `response_type` query/form parameter outside the request object is no longer mandatory. However, instead, it means JAR requires that `response_type` be always included in the request object. 4. OIDC Core 1.0 requires that an OIDC request come with the `scope` query/form parameter, including `openid`, even when the request object contains `scope`. On the contrary, when JAR rules apply, the `scope` query/form parameter outside the request object is no longer mandatory. Note that the request object must contain `scope` including `openid` so that the authorization request can be regarded as an OIDC request. If **Enable JAR Compatibility** is selected here and **Mandatory** is selected in **Request Object**, this service behaves as if `require_signed_request_object` server metadata is `true`. See the specification of JAR for details about the server metadata. ### nbf Claim This setting is intended to facilitate smooth migration from FAPI 1.0 ID2 to 1.0 Final without breaking live systems. If **Require** is off, even when an authorization request is regarded as a FAPI-Part2 request, the `nbf` claim in the request object used in the authorization request is treated as optional. > The final version of the Financial-grade API (FAPI) was approved in January 2021. Part 2 introduec a new requirement for request object lifetimes: they must contain an `nbf` claim, and the duration (`exp - nbf`) must not exceed 60 minutes. If an authorization request is treated as a FAPI-Part2 request, its request object must include an `nbf` claim; otherwise, the authorization server will reject it. This setting allows for backward compatibility when needed. ### Supported Authorization Details Types Supported values of the `type` field of each element in `authorization_details`. Details are defined in *OAuth 2.0 Rich Authorization Requests*. ### Encryption in Front Channel If **Require** is selected, encryption of request objects is required when the request object is passed through the front channel. The configuration of this property does not affect the processing of request objects at the Pushed Authorization Request Endpoint, which is defined in [OAuth 2.0 Pushed Authorization Requests](https://datatracker.ietf.org/doc/draft-ietf-oauth-par/). Unencrypted request objects are accepted at the endpoint even if this property is set to **Require**. Note that, even if **Require** is not selected, encryption of the request object is required if the client's **Request Object Encryption In Front Channel** is set to **Require**. ### Encryption Algorithm Match If **Require** is selected, the JWE `alg` of an encrypted request object must match the `request_object_encryption_alg` client metadata of the client that sent the request object. Note that, even if **Require** is not selected, the match is required if the client's **Request Object Encryption Algorithm Match** is set to **Require**. ### Encryption Encoding Algorithm Match If **Require** is selected, the JWE `enc` of an encrypted request object must match the `request_object_encryption_enc` client metadata of the client that sent the request object. Note that, even if **Require** is not selected, the match is required if the client's **Request Object Encryption Encoding Algorithm Match** is set to **Require**. ### Audience Validation If **Require** is selected, Authlete checks whether the `aud` claim of a request object matches the issuer identifier of this service and raises an error when they are different. On the other hand, if **Require** is not selected, Authlete does not check the value of the `aud` claim. Both [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) and [RFC 9101](https://www.rfc-editor.org/rfc/rfc9101.html) state that the `aud` claim should match or include the issuer identifier of the server. If you want to treat the statement as a mandatory requirement, please select **Require**. Depending on the category of the official conformance suite, **Require** has to be selected here. ## Endpoints: Token ### Token Endpoint URL An URL of the token endpoint. If the Authorization Server implements a discovery endpoint with Authlete's /api/service/configuration API, the value of this configuration item is used as the value of the "token\_endpoint" property included in the response from the endpoint. If a JWT-based client authentication method is used at the token endpoint (= if a token request includes "client\_assertion=JWT"), the value of the "aud" claim of the JWT is required to be the URL of the token endpoint. Therefore, set the correct value if the token endpoints supports CLIENT\_SECRET\_JWT and PRIVATE\_KEY\_JWT. ### Supported Client Authentication Methods Client authentication methods supported at the token endpoint. If the Authorization Server implements a discovery endpoint with Authlete's `/api/service/configuration` API, the value of this configuration item is used as the value of the `token_endpoint_auth_methods_supported` property included in the response from the endpoint. If there are client applications whose client type (RFC 6749, [2.1. Client Types](https://tools.ietf.org/html/rfc6749#section-2.1)) is "confidential," at least one client authentication method except NONE must be supported. **NONE** allows token requests without client authentication. If there are client applications whose client type is "public," NONE has to be supported. **CLIENT\_SECRET\_BASIC** is a client authentication method where a client ID and a client secret are embedded in the Authorization header in the format of Basic Authentication. This client authentication method is mentioned in RFC 6749. The specification says authorization servers must support this client authentication method. **CLIENT\_SECRET\_POST** is a client authentication method where a client ID and a client secret are embedded in the request body. This client authentication method is also mentioned in RFC 6749 in addition to CLIENT\_SECRET\_BASIC. As CLIENT\_SECRET\_BASIC is regarded as more secure than CLIENT\_SECRET\_POST, authorization servers may adopt a security policy that allows CLIENT\_SECRET\_BASIC but does not allow CLIENT\_SECRET\_POST. **CLIENT\_SECRET\_JWT** is a client authentication method defined in [RFC 7523](https://tools.ietf.org/html/rfc7523) that uses a JWT with a symmetric signature algorithm. See OpenID Connect Core 1.0, [9. Client Authentication](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication) for details. **PRIVATE\_KEY\_JWT** is a client authentication method defined in [RFC 7523](https://tools.ietf.org/html/rfc7523) that uses a JWT with an asymmetric signature algorithm. See OpenID Connect Core 1.0, [9. Client Authentication](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication) for details. **TLS\_CLIENT\_AUTH** is a client authentication method that uses a client certificate. Details are described in [OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens](https://datatracker.ietf.org/doc/draft-ietf-oauth-mtls/), 2.1. PKI Mutual TLS OAuth Client Authentication Method. **SELF\_SIGNED\_TLS\_CLIENT\_AUTH** is a client authentication method that uses a self-signed client certificate. Details are described in [OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens](https://datatracker.ietf.org/doc/draft-ietf-oauth-mtls/), 2.2. Self-Signed Certificate Mutual TLS OAuth Client Authentication Method. To support the TLS-based client authentication methods, the implementation of the token endpoint of the front-end authorization server must extract a client certificate from a token request and pass it to Authlete's `/api/auth/token` API as the value of the `clientCertificate` request parameter. **ATTEST\_JWT\_CLIENT\_AUTH** (TBD) ### OpenID on Refresh If **Require offline\_access** is selected, the `openid` scope is dropped from a new access token issued by the refresh token flow unless the presented refresh token contains the `offline_access` scope. ### Client ID Omission If **Allow** is selected, token requests without the `client_id` request parameter from public clients ([RFC 6749, Section 2.1](https://tools.ietf.org/html/rfc6749#section-2.1)) are allowed in the authorization code flow ([Section 4.1](https://tools.ietf.org/html/rfc6749#section-4.1)) and the refresh token flow ([Section 6](https://tools.ietf.org/html/rfc6749#section-6)). As a result, the token endpoint will try to identify the client from the value of the authorization code (`code`) or the refresh token (`refresh_token`) when the token request does not include the `client_id` request parameter. However, in normal cases, the authorization server should not attempt this even if it is possible. Therefore, don't select **Allow** unless you have a special reason to support public clients that make inappropriate token requests without the `client_id` request parameter. ### Client ID If **Require** is selected, the service rejects token requests that use the grant type `urn:ietf:params:oauth:grant-type:jwt-bearer` but contain no client identifier. [RFC 7523 JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants](https://www.rfc-editor.org/rfc/rfc7523.html) states: ***"JWT authorization grants may be used with or without client authentication or identification."*** Technically, **"identification"** in this context means that a token request contains no identifier of the client that made the request. Although RFC 7523 allows for this, it is risky to permit unidentifiable clients (API callers) to make token requests. However, there may be cases where token requests by unidentified clients are necessary, and the safety of the operation can be ensured in some way. In such cases, this switch can be turned **off**. ### Encrypted JWT If **Allow** is selected, Authlete skips the remaining validation steps on an input assertion when it detects that the JWT is encrypted. This means that your authorization server implementation must verify an encrypted JWT independently when one is used as an authorization grant. If **Allow** is not selected, the service rejects token requests that use an encrypted JWT as an authorization grant with the grant type `urn:ietf:params:oauth:grant-type:jwt-bearer` ([RFC 7523](https://www.rfc-editor.org/rfc/rfc7523.html)). See [JWT Authorization Grant](https://www.authlete.com/developers/jwt_authorization_grant/) on the Authlete website for details about the validation process performed by Authlete. ### Unsigned JWT If **Allow** is selected, Authlete skips the remaining validation steps on an input assertion when it detects that the JWT is unsigned. If **Allow** is not selected, the service rejects token requests that use an unsigned JWT as an authorization grant with the grant type `urn:ietf:params:oauth:grant-type:jwt-bearer` ([RFC 7523](https://www.rfc-editor.org/rfc/rfc7523.html)). See [JWT Authorization Grant](https://www.authlete.com/developers/jwt_authorization_grant/) on the Authlete website for details about the validation process performed by Authlete. ## Endpoints: General ### Revocation Endpoint URL An URL of the revocation endpoint ([RFC 7009](https://tools.ietf.org/html/rfc7009) ). If the Authorization Server implements a discovery endpoint with Authlete's /api/service/configuration API, the value of this configuration item is used as the value of the "revocation\_endpoint" property included in the response from the endpoint. An implementation of a revocation endpoint is not mandatory. Authlete's `/api/auth/revocation` API is an API which helps customers implement an RFC 7009 compliant revocation endpoint. The API itself is not an implementation of RFC 7009. ### Introspection Endpoint URL An URL of the introspection endpoint ([RFC 7662](https://tools.ietf.org/html/rfc7662) ). If the Authorization Server implements a discovery endpoint with Authlete's /api/service/configuration API, the value of this configuration item is used as the value of the "introspection\_endpoint" property included in the response from the endpoint. An implementation of an introspection endpoint is not mandatory. Authlete's `/api/auth/introspection/standard` API is an API which helps customers implement an RFC 7662 compliant introspection endpoint. The API itself is not an implementation of RFC 7662. Authlete's `/api/auth/introspection` API is an Authlete-specific custom introspection API. Unlike the standard specification (RFC 7662), `/api/auth/introspection` API not only returns information about an access token but also validates the access token and builds an RFC 6750 compliant error message as necessary. Also, the API returns information about arbitrary key-value pairs associated with the access token (Authlete's custom feature). Therefore, in normal cases, Web API implementations on resource servers use the Authlete's custom introspection API. ### Pushed Authorization Requests (PAR) ### Require PAR If **Require PAR** is selected, Authlete rejects an authorization request that doesn't employ PAR. ### PAR Endpoint URL An URL of the pushed authorization request endpoint. Client applications can register authorization requests at this endpoint in advance before sending the authorization requests to the authorization endpoint. The pushed authorization request endpoint issues a `request_uri` that represents the registered authorization request. The issued `request_uri` can be included in an authorization request. Technical details are defined in *OAuth 2.0 Pushed Authorization Requests*. The value of this property is used as the value of the `pushed_authorization_request_endpoint` metadata in the response from the discovery endpoint. ### PAR Endpoint Duration The default value of the duration of `request_uri`s issued from the pushed authorization request endpoint. The unit of time is seconds. If the value is 0, the default value determined by the Authlete server is used. If an authorization request being registered at the pushed authorization request endpoint includes information about its expiration (e.g., as the value of the `exp` claim), that information is considered. The smaller value between the specified expiration and the default value is chosen as the duration of the registered authorization request. Note that the specification, *OAuth 2.0 Pushed Authorization Requests*, states: *"The request URI lifetime is at the discretion of the AS."* Therefore, the behavior described here is specific to the Authlete implementation. ### UserInfo Endpoint URL An URL of the userinfo endpoint (OpenID Connect Core 1.0, [5.3. UserInfo Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) ). If the Authorization Server implements a discovery endpoint with Authlete's /api/service/configuration API, the value of this configuration item is used as the value of the "userinfo\_endpoint" property included in the response from the endpoint. An implementation of a userinfo endpoint is not mandatory. Authlete's /api/auth/userinfo API and /api/auth/userinfo/issue API are APIs that help customers implement their own userinfo endpoint. The Authlete APIs themselves are not a userinfo endpoint. ## Endpoints: Federation ### Federation Support A flag that indicates whether this service supports OpenID Federation 1.0. However, if the feature of OpenID Federation 1.0 is not enabled on the Authlete server hosting this service, functions related to OpenID Federation 1.0 are not usable regardless of the setting of this property. ### Client Registration Types client registration types supported by this service. This property corresponds to the `client_registration_types_supported` server metadata defined in OpenID Federation 1.0. If the `EXPLICIT` checkbox is checked, the **Registration Endpoint** must be set up properly. ### Registration Endpoint An URI of the federation registration endpoint. This property corresponds to the `federation_registration_endpoint` server metadata defined in OpenID Connect Federation 1.0. If the Authorization Server declares that it supports the client registration type `explicit`, this property must not be empty. ### Organization Name A human-readable name representing the organization that operates this service. This property corresponds to the `organization_name` server metadata defined in OpenID Connect Federation 1.0. If this property is not empty, the `organization_name` property appears in self-signed entity statements of this service. ### Authority Identifier Identifiers of authorities that can issue entity statements for this service. The format of the identifiers is a URL with either the `https` or `http` scheme. This property corresponds to the `authority_hints` property that appears in self-signed entity statements. OpenID providers participating in one or more federations are expected to have superior authorities. Only trust anchors with no superiors do not have superior authorities. Because the `authority_hints` property in self-signed entity statements is mandatory, if this setting is left empty, the configuration endpoint (`/.well-known/openid-federation`) cannot generate a valid entity statement. Therefore, to make OpenID Connect Federation 1.0 work, this property must be set up properly. ### Entity Configuration Duration Duration of the entity configuration in seconds. An OpenID provider that participates in an OpenID Connect federation must publish its entity configuration at `/.well-known/openid-federation` or at a variant location such as `/.well-known/openid-federation{path_part_of_issuer}`. An entity configuration is a kind of JWT. This property specifies the duration of the JWT in seconds. When the value of this property is 0, the default value determined by your Authlete server is used as the duration of the entity configuration. ### Trust Anchors Trust anchors referenced when this service resolves trust chains of relying parties. If this property is left empty, attempts of client registration will fail regardless of whether its type is `automatic` or `explicit`. Therefore, to make OpenID Connect Federation 1.0 work, this property must be set up properly. Each trust anchor has an entity ID and a JWK Set. The format of entity IDs is a URL with either the `https` or `http` scheme. JWK Sets are expected to contain public keys that this service can use to verify signatures of entity statements issued by trust anchors. The OpenID Connect Federation 1.0 specification does not define how to obtain JWK Sets of trust anchors. This is considered out of scope of the specification. ## Endpoints: Advanced ### Dynamic Client Registration (DCR) If **Supported** is selected, the service will allow access to the dynamic client registration protocol API. You probably want to supply both a **Registration Endpoint URI** and **Registration Management Endpoint base URI** value to support the protocol. If **Supported** is not selected, the registration API is not available for this service, though the usual client management APIs are still available. See [OpenID Connect Dynamic Registration 1.0](http://openid.net/specs/openid-connect-registration-1_0.html) for details about client registration. ### DCR's Scope Parameter This switch indicates whether the dynamic client registration/configuration endpoints of your authorization server recognize the `scope` parameter in client metadata. When **Enable** is selected, Authlete's `/api/client/registration` API and `/api/client/registration/update` API use the value of the `scope` parameter to limit the range of scopes that the client application can request. The limitation is achieved by registering the specified scopes as **requestable scopes** (cf. `ClientExtension.isRequestableScopesEnabled()`). The Authlete APIs will embed the `scope` parameter in the `responseContent` response parameter, representing a response from the dynamic client registration/configuration endpoints. If the switch is off, the Authlete APIs ignore the `scope` parameter in client metadata and do not embed the `scope` parameter in `responseContent`. This behavior is backward-compatible with previous Authlete versions. No limitation is imposed on the range of requestable scopes, so the client application can request any scopes that your authorization server supports. See [RFC 7591 OAuth 2.0 Dynamic Client Registration Protocol](https://www.rfc-editor.org/rfc/rfc7591.html) for technical details about the `scope` parameter. ### DCR with Duplicate Software ID A DCR (Dynamic Client Registration) request may contain the `software_id` client metadata, defined in [RFC 7591](https://www.rfc-editor.org/rfc/rfc7591.html). The client metadata is saved in Authlete's database together with other client metadata. If **Accept** is selected, Authlete does not check for duplication of `software_id`. If **Accept** is not selected, Authlete checks whether the value of the `software_id` client metadata included in a DCR request already exists in the database and rejects the DCR request if it does. ### Registration Endpoint URL An URL of an endpoint to register a client application dynamically ([OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html)). If the Authorization Server implements a discovery endpoint with Authlete's `/api/service/configuration` API, the value of this configuration item is used as the value of the `registration_endpoint` property included in the response from the endpoint. Note that a `registration_access_token` is returned from the dynamic client registration API response **only when this URI is configured**. If this URI is not set, the `registration_access_token` will not be included in the response. An implementation of a registration endpoint is not mandatory. ### Registration Management Endpoint Base URL An URL of the client registration endpoint of this service. ASCII characters only. 200 characters at most. The URL must start with `https://`. The value is used as the value of the `registration_endpoint` property in the [OpenID Provider Metadata](http://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) of this service. See [OpenID Connect Dynamic Registration 1.0](http://openid.net/specs/openid-connect-registration-1_0.html) for details about client registration. ### Client Configuration Error Behavior A flag to toggle the behavior of the `/api/client/registration` API in the error case of *401 Unauthorized*. If **Return Unauthorized** is selected, the API uses `UNAUTHORIZED` as a value of the `action` response parameter when appropriate. If **Return Unauthorized** is not selected, the API never uses `UNAUTHORIZED`. The `UNAUTHORIZED` enum value did not exist in the initial implementation of `ClientRegistrationResponse.Action` enum ([JavaDoc](https://authlete.github.io/authlete-java-common/com/authlete/common/dto/ClientRegistrationResponse.Action.html)). Therefore, implementations of the client configuration endpoint were not able to conform to [RFC 7592](https://www.rfc-editor.org/rfc/rfc7592.html) strictly. For backward compatibility (to avoid breaking running systems), the API does not use the `UNAUTHORIZED` action if this flag is **OFF**. The steps an existing implementation of the client configuration endpoint has to take in order to conform to the requirements related to *401 Unauthorized* are as follows: 1. Update the Authlete library (e.g., [authlete-java-common](https://github.com/authlete/authlete-java-common)) your system may be using. 2. Update your implementation of the client configuration endpoint so that it can handle the `UNAUTHORIZED` action. 3. Set **ON** to this flag. RFC 7592 requires that the client configuration endpoint return *401 Unauthorized* when the registration access token is invalid or the client does not exist (or is invalid). ### Grant Management ### Require Action This property corresponds to the `grant_management_action_required` server metadata defined in [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html). If **Require Action** is selected, the authorization server requires that every authorization request and any request serving as an authorization request (e.g., CIBA backchannel authentication request) include the `grant_management_action` request parameter. Note that selecting **Require Action** will result in rejecting all authorization requests from public clients because the specification does not allow public clients to utilize grant management. ### Endpoint URL An URL of the grant management endpoint. This property corresponds to the `grant_management_endpoint` server metadata defined in [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html). If this property is set, `query` and `revoke` are added to the `grant_management_actions_supported` server metadata advertised in the discovery document ([OIDC Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)) in addition to the default set (`create`, `replace`, and `merge`). Grant Management for OAuth 2.0 is supported from Authlete 2.3. The grant management endpoint can be implemented by using Authlete's `/api/gm` API. ### Device Authorization Endpoint URL An URL of the device authorization endpoint. This property corresponds to the `device_authorization_endpoint` metadata defined in OAuth 2.0 Device Authorization Grant (Device Flow). The value must consist of only ASCII characters and its length must not exceed 200. The scheme part must be `https`. This property is used as the value of `device_authorization_endpoint` in the response from the discovery endpoint. Also, if a JWT-based client authentication method (`client_secret_jwt` or `private_key_jwt`) is used, the `aud` claim in the client assertion (`client_assertion`) is compared to the value of this property. ### Verification URI A verification URI. This property is used as the value of the `verification_uri` parameter in responses from the device authorization endpoint. The value must consist of only ASCII characters and its length must not exceed 200. The scheme part must be `https`. This property must be set in advance to use Device Flow. Otherwise, an error is returned when `/api/device/authorization` API is called. ### Verification URI with Placeholder A verification URI with a placeholder for a user code. The value must consist of only ASCII characters and its length must not exceed 200. The scheme part must be `https`. If this property is set and its value includes a fixed string `USER_CODE` (e.g., `https://example.com/verification?user_code=USER_CODE`), it is used to generate the value of the `verification_uri_complete` parameter in responses from the device authorization endpoint. Authlete replaces the fixed string with an actual user code. If the value of this property is not set or does not include the fixed string, the `verification_uri_complete` parameter will not be embedded in responses from the device authorization endpoint. ### Verification Code Duration Duration of device verification codes (`device_code`) and end-user verification codes (`user_code`) in seconds. The value is used as the value of the `expires_in` parameter in responses from the device authorization endpoint. A positive number must be set to this property in advance to use Device Flow. Otherwise, an error is returned when `/api/device/authorization` API is called. ### Polling Interval A minimum interval between polling requests to the token endpoint in seconds. The value must be between 0 and 65,535. The value is used as the value of the `interval` parameter in responses from the device authorization endpoint unless it is zero. If the value is set to zero, the `interval` parameter will not be included in the response from the device authorization endpoint. ### User Code Character Set A character set for user codes (`user_code`). If `BASE20` is selected, user codes will consist of BCDFGHJKLMNPQRSTVWXZ (20 upper-case non-vowel characters) (e.g., `WDJBMJHT`). If `NUMERIC` is selected, 0123456789 are used (e.g., `019450730`). If this property is not set, `BASE20` is used as the default value. Note that user codes generated by Authlete do not include dashes and other punctuation. ### User Code Length The length of user codes (`user_code`). The value must be between 0 and 255. If the value is 0, the length of user codes will be 8 when using the character set `BASE20` (the entropy is 20^8) and 9 when using the character set `NUMERIC` (the entropy is 10^9). The value of this property directly affects the entropy of user codes. Setting the value too low may cause frequent database errors due to the UNIQUE constraint. Conversely, setting the value too high may demotivate end-users from entering the user codes. Therefore, it is advised not to set an extreme value. ### Mutual TLS Authentication ### Validate PKI Certificate Chain If **Validate PKI Certificate Chain** is selected, Authlete server checks whether client certificates used for TLS\_CLIENT\_AUTH client authentication can be reached from root certificates which have been registered in advance. If **Validate PKI Certificate Chain** is not selected, Authlete server does not perform the validation. Therefore, the validation needs to be done in the implementation of your front-end authorization server. You can register trusted root certificates at the configuration item, "Trusted Root Certificates for Mutual TLS Authentication". #### Trusted Root Certificate List of trusted root certificates used when validating client certificate chains in Mutual TLS PKI authentication. If the configuration item above, "Validate PKI Certificate Chain " is enabled, Authlete server checks whether client certificates used for TLS\_CLIENT\_AUTH can be reached from root certificates registered here. ### MTLS Endpoint Aliases This property corresponds to the `mtls_endpoint_aliases` metadata defined in "5. Metadata for Mutual TLS Endpoint Aliases" of [OAuth 2.0 Mutual TLS Client Authentication and Certificate-Bound Access Tokens](https://datatracker.ietf.org/doc/rfc8705/). ### FAPI ### Supported Service Profiles **\[IMPORTANT]** Supported additional features on top of the base OAuth 2.0 and OpenID Connect. Note that if these features are not enabled in your Authlete server environment, you can't use them even if they are marked as enabled in the Console. Please contact [sales@authlete.com](mailto:sales@authlete.com) for details. **FAPI** is a set of security profiles defined by the [FAPI Working Group](https://openid.net/wg/fapi/) under the [OpenID Foundation](https://openid.net/). **OPEN\_BANKING** represents the Open Banking Security Profile defined by Open Banking Implementation Entity in the UK. This feature works on top of FAPI. ### FAPI 1.0 Modes (TBD) ### FAPI 2.0 Modes (TBD) ### Backchannel Authentication Endpoint URL An URL of the backchannel authentication endpoint. This property corresponds to the `backchannel_authentication_endpoint` metadata. ### Supported Backchannel Token Delivery Modes Select token delivery modes to support. `POLL` means a backchannel token delivery mode where a client polls the token endpoint until it gets tokens. `PING` means a backchannel token delivery mode where a client is notified via its client notification endpoint and then retrieves tokens from the token endpoint. `PUSH` means a backchannel token delivery mode where a client receives tokens directly at its client notification endpoint. ### Backchannel Auth Req ID Duration Specify the duration of `auth_req_id` issued from the backchannel authentication endpoint in seconds. This is used as the value of the `expires_in` property in responses from the backchannel authentication endpoint. ### Backchannel Polling Interval Specify the minimum interval between polling requests to the token endpoint from client applications in seconds. This is used as the value of the `interval` property in responses from the backchannel authentication endpoint. The maximum value is 65535 seconds. ### Backchannel User Code Parameter If **Supported** is selected, the `user_code` request parameter is supported at the backchannel authentication endpoint. This property corresponds to the `backchannel_user_code_parameter_supported` metadata. ### Binding Message in FAPI Context If **Require** is selected, the `binding_message` request parameter is always required when a backchannel authentication request is judged as a request for Financial-grade API (FAPI). The FAPI-CIBA profile requires that the authorization server *`shall ensure a unique authorization context exists in the authorization request or require a binding_message in the authentication request`* (FAPI-CIBA, 5.2.2, 2). The simplest way to fulfill this requirement is to select **Require** here. If you don't select **Require**, the `binding_message` request parameter remains optional even in the FAPI context, but in exchange, your authorization server must implement a custom mechanism that ensures each backchannel authentication request has a unique context. ## Tokens and Claims: Access Token ### Access Token ### Type The type of access tokens issued from the service. The value of this configuration item is used as the value of the `token_type` response parameter which is included together with an access token in a response from your authorization server. If Web APIs on resource servers receive access tokens by the means defined in [RFC 6750](https://tools.ietf.org/html/rfc6750) , set `Bearer` (case-insensitive). In general, Web API implementations comply with RFC 6750 unless they have a clear reason to avoid it. ### Duration Duration of access tokens in seconds. This value is used to calculate the value of `expires_in` response parameter which is returned together with an access token. The appropriate value for access token duration varies depending on characteristics of respective services. It may be 1 hour, 1 day, 1 year and even 100 years. The value set to this configuration item is applied to all access tokens issued by this service. However, it is possible to change the expiration date of an access token independently by calling `/api/auth/token/update` API with the `accessTokenExpiresAt` request parameter. Also, `/api/auth/token/create` API (which is used to create an access token manually) provides an optional request parameter, `accessTokenDuration`, to specify the duration for a newly created access token. In addition, there is a mechanism to control access token duration using "scope attributes". See the description about scopes for details. ### Enable TLS Client Certificate Bound Configuration item to control whether or not this service supports certificate-bound access tokens defined in [OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens](https://www.rfc-editor.org/rfc/rfc8705.html#name-mutual-tls-client-certifica). If **Enable** is selected, a discovery endpoint implemented using Authlete's `/api/service/configuration` API will include `"tls_client_certificate_bound_access_tokens":true`. If this feature is enabled, the client certificate used in a token request is associated with the access token issued by the token request. When a client application accesses Web APIs with the access token, the client application has to use the same client certificate that was used in the token request. Otherwise, accesses would be rejected. If an access token is associated with a client certificate, it becomes difficult to abuse the access token even when the access token is leaked. It is because one won't succeed in using Web APIs with the access token unless he has the same client certificate at hand which was used when the access token was issued. To use this feature, implementations of a token endpoint and Web APIs must extract a client certificate from a request and pass it to an Authlete API as the value of the `clientCertificate` request parameter. `/api/auth/token` API (which a token endpoint implementation calls) and `/api/auth/introspection` API (which Web API implementations call) have the `clientCertificate` request parameter. Associating client certificates with access tokens will make your system securer. However, note that additional development work will be required for an authorization server, resource servers and client applications. Even if **Enable** is selected here on the server side (Service Owner Console), if "TLS Client Certificate Bound Access Tokens" on the client side (Developer Console) is not enabled, access tokens issued to the client application won't be associated with client certificates. #### Single Token per Subject Configuration item to control whether to allow at most one access token only per combination of a subject (= end-user identifier) and a client application, or to allow multiple access tokens to be issued for each combination. If this switch is turned **on**, an attempt to issue a new access token invalidates existing access tokens that are associated with the combination of the same subject and the same client. Note that, however, attempts by Client Credentials flow do not invalidate existing access tokens because access tokens issued by the flow are not associated with any end-user's subject. Also note that an attempt by Refresh Token flow invalidates the coupled access token only and this invalidation is always performed regardless of whether the value of this configuration item is Enabled or Disabled. ### Signature Algorithm The algorithm used for signing access tokens. If this property is set, access tokens issued by this service are [JWTs](https://tools.ietf.org/html/rfc7519). If not, access tokens issued by this service are random strings. ### Signature Key ID A key ID to identify the [JWK](https://tools.ietf.org/html/rfc7517) (JSON Web Key) used for signing access tokens (This property is only used when JWT-based access tokens are generated by this service). If there is only one applicable JWK, then there is no problem. However, if there are multiple candidates, a [key ID](https://tools.ietf.org/html/rfc7517#section-4.5) needs to be specified so that the Authlete Server can select the correct one. If this setting has a value, it is interpreted as a key ID. Authlete Server uses this key ID to select a JWK when signing access tokens. Even if there are multiple candidate JWKs and this setting is left empty, Authlete Server will try its best to choose one. However, there are cases where Authlete Server cannot choose one (e.g., there are multiple candidate JWKs but none of them has a key ID). In such cases, Authlete Server fails to generate an access token. ## Tokens and Claims: Refresh Token ### Refresh Token Duration ### Duration Duration of refresh tokens in seconds. There is a mechanism to control refresh token duration using "scope attributes". See the description about scopes for details. ### Enable Duration Reset This flag indicates whether duration of refresh tokens are reset when they are used even if **Token Rotation** is enabled. ### Refresh Token Rotation ### Enable Token Rotation Configuration item to control whether to keep a refresh token valid after its use or invalidate the used refresh token and issue a new one. If a refresh token remain valid after its use and a new one is not issued, the refresh token will eventually expire. At the timing, authorization process is required again. On the other hand, if a refresh token is invalidated when it is used and if a new one is issued, authorization process is not required again while you continue to use a refresh token to get a new access token before the refresh token expires. ### Enable Idempotency If the switch is turned **on**, refresh token requests using the same refresh token can be made multiple times in quick succession, and they will obtain the same renewed refresh token within a short period. If the switch is turned **off**, each refresh token request will receive a different renewed refresh token, even if the requests are made in a short period. ### Enable Duration Takeover If the switch is turned **on**, the remaining duration of the used refresh token is carried over to the newly issued one. This setting applies only when token rotation is enabled. ### Enable Token Expiration If the switch is turned **on**, the expiration date of the access token will never exceed the expiration date of the corresponding refresh token, regardless of the calculated duration based on other settings. ## Tokens and Claims: ID Token ### ID Token Duration ### Duration Duration of ID tokens in seconds. The value set to this configuration item is used to compute the value of the "exp" claim of ID tokens. ### Allowable Clock Skew Specify the allowable clock skew between this service and clients in seconds. This value is taken into consideration when time-related claims in a JWT (e.g., `exp`, `iat`, `nbf`) are verified. ### Enable Reissuable This switch controls whether to enable the ID token reissuance feature in the refresh token flow. If the switch is turned **on**, the `action` parameter in a response from the `/auth/token` API becomes `ID_TOKEN_REISSUABLE` when the following conditions are all met: 1. The flow of the token request is the refresh token flow. 2. The scope set after processing the token request still contains the `openid` scope. 3. The access token is associated with the subject of a user. 4. The access token is associated with a client application. When receiving `ID_TOKEN_REISSUABLE`, the implementation of the token endpoint can take either of the following actions: 1. Execute the same steps as for the `OK` action. This will result in the token endpoint behaving as before, and no ID token is reissued. 2. Call the `/idtoken/reissue` API to reissue an ID token and let the API prepare a token response including a new ID token, along with a new access token and a refresh token. See the [`JavaDoc of the TokenResponse class`](https://authlete.github.io/authlete-java-common/com/authlete/common/dto/TokenResponse.html) for details. ### Audience Claim Format This setting allows you to select the type of the `aud` claim in ID tokens. The options are: * **Unspecified**: When this option is chosen, the type of the `aud` claim remains the same as before. If backward compatibility is important, this option should be selected. Because examples in standard specifications are inconsistent in terms of the type of the `aud` claim, Authlete's implementation is also inconsistent. For example, the `aud` claim of ID tokens issued by the authorization code flow is an *array*, whereas the `aud` claim of ID tokens issued by CIBA flows is a *string*. * **Array**: When this option is selected, the type of the `aud` claim in ID tokens always becomes an *array*. From the viewpoint of the JWT specification ([RFC 7519](https://www.rfc-editor.org/rfc/rfc7519.html)), this behavior is the general case. [Section 4.1.3](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.3) of the specification states as follows: > *In the general case, the "aud" value is an array of case-sensitive strings, each containing a StringOrURI value. In the special case when the JWT has one audience, the "aud" value MAY be a single case-sensitive string containing a StringOrURI value.* * **String**: When this option is selected, the type of the `aud` claim in ID tokens always becomes a *string*. Some Authlete APIs, such as `/auth/authorization/issue`, have the `idTokenAudType` request parameter. If the request parameter is given and its value is either `array` or `string`, the request parameter takes precedence over this service property (`Service.idTokenAudType`). ## Tokens and Claims: Claims ### Claims ### Supported Claims A list of claims supported by this service. If the Authorization Server implements a discovery endpoint with Authlete's `/api/service/configuration` API, the value of this configuration item is used as the value of the `claims_supported` property included in the response from the endpoint. "Supported" here means that this service can provide values of the claims directly or indirectly. On service creation, 20 standard claims defined in [OpenID Connect Core 1.0, 5.1. Standard Claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) are set as the initial value. The names of claims requested by an authorization request are included in a response from Authlete's `/api/auth/authorization` API as the value of the `claims` property. However, claims that are not listed in this configuration item will never be included in the `claims`. For example, even if the `scope` parameter of an authorization request includes `email` and `phone` (which are expanded to 4 claims: `email`, `email_verified`, `phone_number`, and `phone_number_verified`), if `email_verified` and `phone_number_verified` are not listed in this configuration item, `email_verified` and `phone_number_verified` will not appear in the `claims` property in the response from `/api/auth/authorization` API. ### Supported Claim Locales A list of claim languages supported by this service. Technically, this is a list of [language tags](https://tools.ietf.org/html/rfc5646#section-2) ([RFC 5646](https://tools.ietf.org/html/rfc5646)) which the authorization endpoint recognizes as the value of the `claims_locales` parameter ([OpenID Connect Core 1.0, 3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)). If the Authorization Server implements a discovery endpoint with Authlete's `/api/service/configuration` API, the value of this configuration item is used as the value of the `claims_locales_supported` property included in the response from the endpoint. A client application may specify languages of claim values that are embedded in an ID token by using the `claims_locales` request parameter. For example, by including `claims_locales=ja` in an authorization request, a client application can tell the authorization server that it wishes the value of the `family_name` claim to be written in Japanese. See [OpenID Connect Core 1.0, 5.2. Claims Languages and Scripts](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsLanguagesAndScripts) for details. However, it is not assured that the authorization server honors the request parameter and changes the claim language accordingly. Even if the authorization server completely ignores the `claims_locales` parameter, it is not a spec violation. The value of the `claims_locales` parameter in an authorization request is included in a response from Authlete's `/api/auth/authorization` API as the value of the `claimsLocales` property. However, languages that are not listed in this configuration item will never be included in the `claimsLocales`. For example, even if an authorization request includes `claims_locales=ja`, if `ja` is not listed in this configuration item, `ja` will not appear in the `claimsLocales` property in the response from `/api/auth/authorization` API. If your authorization endpoint implementation ignores the `claims_locales` request parameter, you can leave this configuration item empty. ### Supported Types Claim types supported by this service. If the Authorization Server implements a discovery endpoint with Authlete's `/api/service/configuration` API, the value of this configuration item is used as the value of the `claim_types_supported` property included in the response from the endpoint. **NORMAL** means that this service (OpenID Provider) itself provides claim values directly. On service creation, this claim type is enabled by default. **AGGREGATED** means that providers of claim values exist separately, and this service collects claim values from such providers and returns aggregated information to client applications. **DISTRIBUTED** means that providers of claim values exist separately, and this service just returns pointers to the providers to client applications. See [OpenID Connect Core 1.0, 5.6. Claim Types](https://openid.net/specs/openid-connect-core-1_0.html#ClaimTypes) for details about claim types. *Note*: If you want to support AGGREGATED and DISTRIBUTED in your service, you have to format information as described in [5.6.2. Aggregated and Distributed Claims](https://openid.net/specs/openid-connect-core-1_0.html#AggregatedDistributedClaims) and pass it to Authlete's `/api/auth/authorization/issue` API. Authlete itself does not support AGGREGATED and DISTRIBUTED directly. #### Restrict Shortcut If the switch is on, claims specified by shortcut scopes (e.g. `profile`) are included in an ID token only when no access token is issued (only when `response_type` is `id_token`). On the other hand, if **Restrict Shortcut** is not selected, the claims are always included in an ID token regardless of whether an access token is issued or not. To strictly conform to the description in OpenID Connect Core 1.0 Section 5.4, choose **Restrict Shortcut**. If backward compatibility with Authlete 2.1 and older versions is important, don't choose **Restrict Shortcut**. From a programmer's point of view, the choice here affects the following response parameters only: * `claims` in `/api/auth/authorization` API responses * `claimNames` in `/api/backchannel/authentication` API responses * `claimNames` in `/api/device/authorization` API responses If the implementation of your authorization server ignores the response parameters above, in other words, if the implementation does not change its behavior according to the values of the response parameters, the choice here has no meaning. ### Trust Frameworks Trust frameworks supported by this service. Pre-defined values listed in [11.1. Trust Frameworks](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#rfc.section.11.1) of [OpenID Connect for Identity Assurance 1.0](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html) are as follows: * `de_aml` * `eidas_ial_substantial` * `eidas_ial_high` * `nist_800_63A_ial_2` * `nist_800_63A_ial_3` * `jp_aml` * `jp_mpiupa` Trust frameworks listed here are used as values of the `trust_frameworks_supported` metadata in the discovery document. See [7. OP Metadata](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#rfc.section.7) for details. ### Identity Evidence Types of identity evidence supported by this service. Pre-defined values listed in [4.1.1. Evidence](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#rfc.section.4.1.1) of [OpenID Connect for Identity Assurance 1.0](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html) are as follows: * `id_document` * `utility_bill` * `qes` Identity evidence listed here are used as values of the `evidence_supported` metadata in the discovery document. See [7. OP Metadata](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#rfc.section.7) for details. ### Supported Identity Documents Types of identity documents supported by this service. Pre-defined values listed in [11.2. Identity Documents](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#rfc.section.11.2) of [OpenID Connect for Identity Assurance 1.0](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html) are as follows: * `idcard` * `passport` * `driving_permit` * `de_idcard_foreigners` * `de_emergency_idcard` * `de_erp` * `de_erp_replacement_idcard` * `de_idcard_refugees` * `de_idcard_apatrids` * `de_certificate_of_suspension_of_deportation` * `de_permission_to_reside` * `de_replacement_idcard` * `jp_drivers_license` * `jp_residency_card_for_foreigner` * `jp_individual_number_card` * `jp_permanent_residency_card_for_foreigner` * `jp_health_insurance_card` * `jp_residency_card` Identity document types listed here are used as values of the `id_documents_supported` metadata in the discovery document. See [7. OP Metadata](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#rfc.section.7) for details. ### Supported Verification Methods Types of identity document verification methods supported by this service. Pre-defined values listed in [11.3. Verification Methods](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#rfc.section.11.3) of [OpenID Connect for Identity Assurance 1.0](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html) are as follows: * `pipp` * `sripp` * `eid` * `uripp` Verification methods listed here are used as values of the `id_documents_verification_methods_supported` metadata in the discovery document. See [7. OP Metadata](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#rfc.section.7) for details. ### Supported Verified Claims Names of verified claims supported by this service. For example, `given_name` and `family_name`. See [3.1. Additional Claims about End-Users](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#rfc.section.3.1) and [4.2. claims Element](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#rfc.section.4.2) in [OpenID Connect for Identity Assurance 1.0](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html) for more examples. Claim names listed here are used as values of the `claims_in_verified_claims_supported` metadata in the discovery document. See [7. OP Metadata](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#rfc.section.7) for details. ### Predefined Transformed Claims Predefined **transformed claims**. The format is JSON. This property corresponds to the `transformed_claims_predefined` server metadata, which is defined in "OpenID Connect Advanced Syntax for Claims (ASC) 1.0". ### Document Types Document types supported by this service. This property corresponds to the `documents_supported` server metadata, which was added by the third implementer's draft of [OpenID Connect for Identity Assurance 1.0](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html). Examples of predefined values are `idcard` and `passport`. See the [identifiers](https://bitbucket.org/openid/ekyc-ida/wiki/identifiers) page maintained by the [eKYC-IDA WG](https://openid.net/wg/ekyc-ida/) for the complete list of predefined values. ### Document Check Methods (TBD) ### Electronic Record Types (TBD) ### Attachment Types Attachment types supported by this service. The check boxes correspond to `embedded` and `external`, which are predefined values for the `attachments_supported` server metadata added by the third implementer's draft of [OpenID Connect for Identity Assurance 1.0](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html). ### Supported Digest Algorithms Supported algorithms that can be used to compute digest values of external attachments. This property corresponds to the `digest_algorithms_supported` server metadata, which was added by the third implementer's draft of [OpenID Connect for Identity Assurance 1.0](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html). Possible values are listed in the [Hash Algorithm Registry](https://www.iana.org/assignments/named-information/named-information.xhtml#hash-alg) of IANA (Internet Assigned Numbers Authority). If the Authorization Server supports *external attachments*, this property must include at least `sha-256`. Client applications can specify a digest algorithm by setting the `digestAlgorithm` property (which corresponds to the `digest_algorithm` client metadata). When the client property is not set, the service must use `sha-256` as the default algorithm. ### Access Token for External Attachments If **Embed Automatically** is selected, Authlete generates access tokens for external attachments and embeds them in ID tokens and userinfo responses. The `claims` request parameter of `/auth/authorization/issue` and `/auth/userinfo/issue` APIs may contain `verified_claims` (as defined in [OpenID Connect for Identity Assurance 1.0](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html)). The `verified_claims` may contain `attachments`, which is a JSON array of JSON objects. Each element in the `attachments` array represents either an embedded attachment or an external attachment. A JSON object that represents an external attachment contains a `url` property pointing to the location of the content of the attachment and may optionally contain an `access_token` property, which is an access token the client application should use when accessing the URL. If **Embed Automatically** is selected, when Authlete finds a JSON object representing an external attachment that does not contain the `access_token` property, Authlete generates an access token and embeds it in the JSON object as the value of the `access_token` property. In this case, Authlete also embeds an `expires_in` property. See [OpenID Connect for Identity Assurance 1.0](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html) for details about external attachments. ### Validation Schema Set Choice of the validation schema set that is used to validate the content of `'verified_claims'`. Since version 2.3, Authlete validates the content of `'verified_claims'` based on the JSON schema files that accompany the specification ([OpenID Connect for Identity Assurance 1.0](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html)). These files are found in the [/schema/](https://bitbucket.org/openid/ekyc-ida/src/master/schema/) folder of the Git repository of the specification. Usually, Authlete uses the legitimate JSON schema files that conform to the specification. However, it is possible to make Authlete use a different set of JSON schema files by specifying a name of validation schema set through this property (`Service.verifiedClaimsValidationSchemaSet`). Authlete recognizes the following names of validation schema sets: * **null**: Same as `'standard'`. * `'standard'`: The set of the legitimate JSON schema files. * `'standard+id_document'`: A set of customized JSON schema files that mostly conform to the standard but additionally accept `'id_document'` as a valid name of evidence. This is for backward compatibility. Note that `'id_document'` was deprecated by Implementer's Draft 4 (cf. [eKYC-IDA PR 152](https://bitbucket.org/openid/ekyc-ida/pull-requests/152)). ## Tokens and Claims: Advanced ### Requests Without Scope Parameter When a request has no `scope` parameter (or none of the given scopes is valid) and the service's pre-defined default scope set is empty, the authorization server considers that the request is made with no scope. If the **Reject** switch is turned **on**, such requests are rejected. The last paragraph in RFC 6749 Section 3.3 does not explicitly mention the case where the default scope set is empty. However, if you interpret the state *"the default scope set exists but is empty"* as *"the default scope set does not exist"* and want to strictly conform to the requirement in RFC 6749 Section 3.3, turn the **Reject** switch **on**. When the **Reject** switch is **on**, it ensures that every access token issued by the authorization server has at least one scope, unless you create access tokens without a scope using the `/api/auth/token/create` API. If backward compatibility with Authlete 2.1 and older versions is important, leave the **Reject** switch **off**. ### Supported Scopes A list the scopes that this service recognizes. Each scope name must consist of only printable ASCII characters, excluding spaces, double quotation marks, and backslashes (RFC 6749, [3.3. Access Token Scope](https://tools.ietf.org/html/rfc6749#section-3.3)). Additionally, the length of each scope name must not exceed 200 characters. OpenID Connect has defined some standard scope names. `openid` is the most important scope. If the `openid` scope is not included in a request to the authorization endpoint, the request is not considered an OpenID Connect request ([3.1.2.1. Authentication Request](http://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)). `profile`, `email`, `address`, and `phone` are scopes that can be used to request specific claims to be included in an ID token ([5.4. Requesting Claims using Scope Values](http://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims)). `offline_scope` is a scope to request that an OAuth 2.0 Refresh Token be issued, which can be used to obtain an Access Token that grants access to the End-User's UserInfo Endpoint even when the End-User is not present (not logged in) ([11. Offline Access](http://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess)). If the Authorization Server implements a discovery endpoint with Authlete's `/api/service/configuration` API, the value of this configuration item is used as the value of the `"scopes_supported"` property included in the response from the endpoint. Values listed here are recognized as valid values for the `"scope"` parameter in authorization requests. Authlete silently ignores unknown scopes that are not listed here, even if they are included in the `"scope"` parameter. The reason Authlete does not raise an error for unknown scopes is that OpenID Connect Core 1.0, [3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest), states: *"Scope values used that are not understood by an implementation SHOULD be ignored."* **Note:** if you do not list `openid`, this service will stop providing OpenID Connect functionalities. Each scope has configuration items such as name, default entry (boolean), description, and attributes. * **Scope Name**: A string used as the value of the `"scope"` parameter. Usable characters are printable ASCII characters except space, double quote, and backslash. * **Default Entry**: A boolean flag which is referenced when an authorization request does not include the `"scope"` parameter. If the `"scope"` parameter is missing, scopes whose default entry is `true` are used as if they were specified in the `"scope"` parameter. * **Description**: Although not required by the specification, Authlete manages this data. Note that descriptions of the standard scopes defined in OpenID Connect Core 1.0 (`openid`, `profile`, `email`, `address`, `phone`, and `offline_access`) cannot be changed. * **Attributes**: Arbitrary key-value pairs. The functionality to attach arbitrary key-value pairs to scopes is a custom mechanism provided by Authlete. Note that some scope attributes listed below are interpreted in a special way by Authlete. | AttributeName | AttributeValue | Description | | ------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | fapi | r | This means "Financial-grade API Read-Only". An authorization request that includes at least one scope with this attribute is regarded as a request for an access token for Read-Only API. As a result, Authlete checks whether the authorization request satisfies the constraints imposed by [Financial-grade API - Part 1: Read-Only API Security Profile](https://bitbucket.org/openid/fapi/src/master/Financial_API_WD_001.md). For example, when the flow of the authorization request is "authorization code flow", Authlete checks whether the request includes `"code_challenge"` and `"code_challenge_method=S256"`. | | fapi | rw | This means "Financial-grade API Read-Write". An authorization request that includes at least one scope with this attribute is regarded as a request for an access token for Read-Write API. As a result, Authlete checks whether the authorization request satisfies the constraints imposed by [Financial-grade API - Part 2: Read and Write API Security Profile](https://bitbucket.org/openid/fapi/src/master/Financial_API_WD_002.md). For example, Authlete checks whether the request includes either `"request"` or `"request_uri"`. If both `fapi=r` and `fapi=rw` exist in a request, `fapi=rw` takes precedence. | On service creation, standard scopes defined in OpenID Connect Core 1.0 are set as the initial values. | Scope Name | Description | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | openid | The most important scope. If an authorization request does not include this scope, it is not regarded as an OpenID Connect request. Do not remove this scope unless you have a clear reason, as OpenID Connect won't work without it. See [3.1.2.1. Authentication Request](http://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) for details. | | profile | The scope to request claims related to the user's profile ("name", etc.) be included in an ID token. See [5.4. Requesting Claims using Scope Values](http://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) for details. | | email | The scope to request claims related to email ("email" and "email\_verified") be included in an ID token. See [5.4. Requesting Claims using Scope Values](http://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) for details. | | address | The scope to request claims related to the address ("address") be included in an ID token. See [5.4. Requesting Claims using Scope Values](http://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) for details. | | phone | The scope to request claims related to the phone ("phone\_number" and "phone\_number\_verified") be included in an ID token. See [5.4. Requesting Claims using Scope Values](http://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) for details. | | offline\_access | The scope to request a refresh token that can be used to obtain an access token that grants permission to access the [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) even if the user is not logged in. See [11. Offline Access](http://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess) for details. | There is no fixed rule for the granularity of scopes; it depends on your service's needs. If managing many fine-grained scopes is challenging, consider attaching additional metadata to access tokens instead. Authlete allows you to attach arbitrary key-value pairs to access tokens, simplifying scope management. For more information, see the [Extra Properties](https://www.authlete.com/documents/definitive_guide/extra_properties) documentation. ### DPoP Token ### Require Nonce When this switch is turned **on**, Authlete will require a `nonce` in DPoP Proof tokens. If the `nonce` is missing, the Authlete server will return a `use_dpop_nonce` error, and the client must repeat the previous request with a `nonce` claim included. The `nonce` may be supplied by the Authlete server in the HTTP `DPoP-Nonce` response header. If not, the client must generate the `nonce` itself. ### Nonce Duration This setting controls how long a `dpop-nonce` value can be reused in proof tokens. To ensure proper validation, save the `dpop-nonce` value from the token response header and refresh it at the specified duration interval. ### Token Exchange ### Enable Identifiable Clients Only If this switch is on, this service rejects **token exchange requests** that contain no client identifier. Section 2.1 of [RFC 8693 OAuth 2.0 Token Exchange](https://www.rfc-editor.org/rfc/rfc8693.html) states: ***"The supported methods of client authentication and whether or not to allow unauthenticated or unidentified clients are deployment decisions that are at the discretion of the authorization server."*** Technically, "**unidentified**" in this context means that a token exchange request contains no identifier of the client that made the request. Although [A.1.1 of RFC 8693](https://www.rfc-editor.org/rfc/rfc8693.html#section-a.1.1) shows an example of a token exchange request that contains no client identifier, it is risky to allow unidentifiable clients (API callers) to make token exchange requests. However, there may be cases where token exchanges by unidentified clients are necessary, and the safety of the operation can be ensured in some way. In such cases, this option can be unchecked. ### Enable Confidential Clients Only If this switch is on, this service rejects **token exchange requests** from **public** clients. Section 2.1 of [RFC 8693 OAuth 2.0 Token Exchange](https://www.rfc-editor.org/rfc/rfc8693.html) states: ***"The supported methods of client authentication and whether or not to allow unauthenticated or unidentified clients are deployment decisions that are at the discretion of the authorization server."*** Technically, "**unauthenticated**" in this context means that the client making a token exchange request is a public client and therefore [client authentication](https://darutk.medium.com/oauth-2-0-client-authentication-4b5f929305d4) for the client is not required at the token endpoint. To accept token exchange requests from public clients as well as those from confidential clients, uncheck this option. ### Enable Permitted Clients Only If this switch is on, this service rejects **token exchange requests** from clients that have no explicit permission for token exchange. An administrator can grant a client explicit permission to make token exchange requests by checking the checkbox for "Explicit Permission for Token Exchange" in the "Extension" tab of the Web console for client application management. See [RFC 8693 OAuth 2.0 Token Exchange](https://www.rfc-editor.org/rfc/rfc8693.html) for details about token exchange. ### Reject Encrypted JWT If this switch is on, this service rejects **token exchange requests** that use encrypted JWTs as input tokens with the token type `urn:ietf:params:oauth:token-type:jwt` or the token type `urn:ietf:params:oauth:token-type:id_token`. If this checkbox is not checked, Authlete skips the remaining validation steps on an input token when it detects that it is an encrypted JWT. This means that your authorization server implementation must verify an encrypted JWT by itself when one is used as an input token. See [RFC 8693 OAuth 2.0 Token Exchange](https://www.authlete.com/developers/token_exchange/) on the Authlete website for details about the validation process performed by Authlete. ### Reject Unsigned JWT If this switch is on, this service rejects **token exchange requests** that use unsigned JWTs as input tokens with the token type `urn:ietf:params:oauth:token-type:jwt` or the token type `urn:ietf:params:oauth:token-type:id_token`. If this checkbox is not checked, Authlete skips the remaining validation steps on an input token when it detects that it is an unsigned JWT. See [RFC 8693 OAuth 2.0 Token Exchange](https://www.authlete.com/developers/token_exchange/) on the Authlete website for details about the validation process performed by Authlete. ## Key Management: JWK Set ### JWK Set Content Content of the JWK Set document ([RFC 7517](https://tools.ietf.org/html/rfc7517)) of this service. If the Authorization Server supports asymmetric algorithms for signing [ID tokens](https://openid.net/specs/openid-connect-core-1_0.html), [UserInfo Endpoint](https://openid.net/specs/openid-connect-core-1_0.html) responses, and authorization responses ([JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/openid-financial-api-jarm.html)) and for encrypting [request objects](https://openid.net/specs/openid-connect-core-1_0.html), a JWK Set must be registered. The JWK Set must contain pairs of public and private keys for the algorithms that the Authorization Server wants to support. Algorithms that can be used as JWS ([RFC 7515](https://tools.ietf.org/html/rfc7515)) "alg" are listed in [3.1. "alg" (Algorithm) Header Parameter Values for JWS](https://tools.ietf.org/html/rfc7518#section-3.1) of JWA ([RFC 7518](https://tools.ietf.org/html/rfc7518)). Among them, algorithms whose names start with "RS", "PS", or "ES" are asymmetric algorithms. Algorithms that can be used as JWE ([RFC 7516](https://tools.ietf.org/html/rfc7516)) "alg" are listed in [4.1. "alg" (Algorithm) Header Parameter Values for JWE](https://tools.ietf.org/html/rfc7518#section-4.1) of JWA ([RFC 7518](https://tools.ietf.org/html/rfc7518)). Among them, algorithms whose names start with "RSA" or "ECDH" are asymmetric algorithms. FYI: There exists an online service that generates JWK and JWK Set at [mkjwk.org](https://mkjwk.org/). Try it if you are not familiar with JWK. ### JWK Set Endpoint URI An URL of the JWK Set document ([RFC 7517](https://tools.ietf.org/html/rfc7517)) for this service. If the Authorization Server implements a discovery endpoint using Authlete's `/api/service/configuration` API, the value of this configuration item is used as the value of the `"jwks_uri"` property included in the response from the endpoint. If the configuration item "JWK Set Content" is empty, Authlete attempts to fetch a JWK Set from the URI specified here as needed. However, Authlete will never attempt to fetch an external JWK Set for secret keys of asymmetric algorithms. Therefore, if there are processes that use secret keys of asymmetric algorithms—such as signing ID tokens with asymmetric algorithms—the secret keys for those algorithms need to be registered as part of the "JWK Set Content". If the Authorization Server supports asymmetric algorithms for signing [ID tokens](https://openid.net/specs/openid-connect-core-1_0.html#IDToken), [UserInfo Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) responses, and authorization responses ([JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/openid-financial-api-jarm.html)), as well as for encrypting [request objects](https://openid.net/specs/openid-connect-core-1_0.html#JWTRequests), the Authorization Server must implement a JWK Set endpoint (unless the JWK Set is distributed to client application developers offline). Authlete's `/api/service/jwks/get` API is available to help customers implement their own JWK Set endpoint. ### ID Token Signature Key ID A key ID to identify the JWK ([RFC 7517](https://tools.ietf.org/html/rfc7517)) used for signing ID tokens. When the algorithm for ID token signature is asymmetric (e.g., RS256), a JWK representing a private key of the algorithm needs to be selected from the registered JWK Set. If there is only one applicable JWK, then there is no issue. However, if there are multiple candidates, a [key ID](https://tools.ietf.org/html/rfc7517#section-4.5) needs to be specified so that the Authlete server can select the correct one. Even if there are multiple candidate JWKs but this configuration item is left empty, the Authlete server will attempt to choose one. However, there are situations where the Authlete server may fail (e.g., there are multiple candidate JWKs but none of them has a key ID). In such cases, the Authlete server may fail to generate an ID token. ### UserInfo Signature Key ID A key ID to identify the JWK ([RFC 7517](https://tools.ietf.org/html/rfc7517)) used for signing responses from the [UserInfo Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo). When the algorithm for signing responses from the UserInfo Endpoint is asymmetric (e.g., RS256), a JWK representing a private key of the algorithm needs to be selected from the registered JWK Set. If there is only one applicable JWK, then there is no issue. However, if there are multiple candidates, a [key ID](https://tools.ietf.org/html/rfc7517#section-4.5) needs to be specified so that the Authlete server can select the correct one. Even if there are multiple candidate JWKs, but this configuration item is left empty, the Authlete server will attempt to choose one. However, there are situations where the Authlete server may fail (e.g., there are multiple candidate JWKs but none of them has a key ID). In such cases, the Authlete server may fail to generate a response from the UserInfo Endpoint. ### Authorization Signature Key ID A key ID to identify the JWK ([RFC 7517](https://tools.ietf.org/html/rfc7517)) used for signing authorization responses ([JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/openid-financial-api-jarm.html)). When the algorithm for signing authorization responses is asymmetric (e.g., RS256), a JWK representing a private key of the algorithm needs to be selected from the registered JWK Set. If there is only one applicable JWK, then there is no issue. However, if there are multiple candidates, a [key ID](https://tools.ietf.org/html/rfc7517#section-4.5) needs to be specified so that the Authlete server can select the correct one. Even if there are multiple candidate JWKs, but this configuration item is left empty, the Authlete server will attempt to choose one. However, there are situations where the Authlete server may fail (e.g., there are multiple candidate JWKs but none of them has a key ID). In such cases, the Authlete server will fail to generate an authorization response JWT, resulting in an error response being returned in the format defined in RFC 6749. ## Key Management: HSM ### Hardware Security Modules (HSM) This option enables support for HSM (Hardware Security Modules). When disabled, keys managed in HSMs are not used even if they exist. Additionally, `/api/hsk/*` APIs reject all requests. Even if enabled, HSM-related features will not function if the configuration of the Authlete server you are using does not support HSM. *Note: Only supported in Dedicated Cloud.* ### HSK (Hardware Security Keys) This setting displays details for Hardware-Secured Keys when the HSM feature is enabled and active. *Note: Only supported in Dedicated Cloud.* ### Federation JWK Set Content A JWK Set containing private keys that are used when this service signs (1) self-signed entity statements and (2) responses from the endpoint that returns this service's JWK Set in the JWT format; the URI of the endpoint is specified by the `signed_jwks_uri` server metadata. If this property is left empty, this service cannot generate a valid self-signed entity statement. Therefore, to make OpenID Connect Federation 1.0 work, this property must be set up properly. Note that this JWK Set is different from the one used for normal OpenID Connect operations, such as signing ID tokens. ### Federation Signed JWK Set URI An URI of the endpoint that returns this service's JWK Set in the JWT format. This property corresponds to the `signed_jwks_uri` server metadata defined in OpenID Connect Federation 1.0. The JWT returned from the endpoint is signed with a private key in the JWK Set specified in the **JWK Set** field. Therefore, if the **JWK Set** field is not set up properly, the endpoint will not be able to return a valid response. ### Federation Signature Key ID A key ID to identify a JWK that should be used to sign the entity configuration and the signed JWK Set. The entity configuration is a kind of JWT and is published at `/.well-known/openid-federation` or at a variant location such as `/.well-known/openid-federation{path_part_of_issuer}`. The signed JWK Set is also a kind of JWT and is published at the URL designated by the `signed_jwks_uri` server metadata. When this property is specified, Authlete will use the JWK with the specified key ID when signing the entity configuration and the signed JWK Set. If this property is omitted, there is no guarantee as to which JWK Authlete will choose. ### VCI JWK Set A JWK Set document containing private keys used to sign verifiable credentials. Some Authlete APIs, such as the `/vci/single/issue` and `/vci/batch/issue` APIs, may issue one or more verifiable credentials. The content of this property is utilized by these APIs. Authlete APIs that issue verifiable credentials recognize a request parameter that can specify the key ID of a private key for signing. For instance, a request to the `/vci/single/issue` API includes an `order` object with a `signingKeyId` parameter that can specify the key ID of a private key to be used for signing. If no key ID is specified, Authlete will automatically select a private key. If the JWKs in the JWK Set do not contain the `kid` property ([RFC 7517, Section 4.5](https://datatracker.ietf.org/doc/html/rfc7517#section-4.5)) when this `credentialJwks` property is updated, Authlete will automatically insert the `kid` property into such JWKs. The JWK thumbprint ([RFC 7638](https://datatracker.ietf.org/doc/html/rfc7638)) computed with the SHA-256 hash algorithm is used as the value of the `kid` property. ### VCI JWK Set URI An URL where the JWK Set document of the credential issuer is exposed. This URL is used as the value of the `jwks_uri` property in the JWT issuer metadata. The metadata is published at `/.well-known/jwt-issuer`. For more details about the JWT issuer metadata, refer to the SD-JWT-based Verifiable Credentials (SD-JWT VC) specification. ## Metadata ### Service Data Policy An URL of the document describing how the data provided by this service can be used. If the Authorization Server implements a discovery endpoint with Authlete's /api/service/configuration API, the value of this configuration item is used as the value of the "op\_policy\_uri" property included in the response from the endpoint. ### Terms of Service An URL of this service's Terms Of Service for client application developers. If the Authorization Server implements a discovery endpoint with Authlete's /api/service/configuration API, the value of this configuration item is used as the value of the "op\_tos\_uri" property included in the response from the endpoint. ### Service Documentation for Developers An URL of the documentation about this service for developers. If the Authorization Server implements a discovery endpoint with Authlete's /api/service/configuration API, the value of this configuration item is used as the value of the "service\_documentation" property included in the response from the endpoint. ## Verifiable Credentials ### Verifiable Credentials Feature This flag controls availability of features related to Verifiable Credentials such as support of the OID4VCI specification. ### Credential Offer Duration Duration for credential offers issued by the Credential Issuer. If the Wallet does not specify a duration or specifies a duration of `0` or less (`<= 0`) in the credential offer request, this default value will be applied. ### Transaction Duration Duration, in seconds, for which transaction IDs remain valid when issued as a result of a credential request or a batch credential request. If this property is set to 0 or a negative value, the default duration configured in this setting will be applied. ### Credential Duration Duration, in seconds, for which verifiable credentials remain valid. This duration applies to credentials issued by Authlete APIs such as the `/vci/single/issue` and `/vci/batch/issue` APIs. A value of 0 indicates that verifiable credentials will not expire, meaning they won't include an expiration property. For example, JWT-based verifiable credentials will not contain the `exp` claim ([RFC 7519, Section 4.1.4](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4)). Authlete APIs that issue verifiable credentials also support request parameters that can override this default duration. For instance, a request to the `/vci/single/issue` API includes an `order` object with a `credentialDuration` parameter that can specify a different duration. ### Anonymous Access Indicates whether token requests using the pre-authorized code flow by unidentifiable client applications are allowed. This property corresponds to the `pre-authorized_grant_anonymous_access_supported` metadata defined in the [OID4VCI specification](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html). ### Credential Nonce Duration (c\_nonce) Duration, in seconds, for which a `c_nonce` remains valid. When the token endpoint of the authorization server issues an access token for verifiable credential issuance, it also issues a `c_nonce` alongside the access token. Additionally, the credential endpoint and batch credential endpoint of the credential issuer will issue a new `c_nonce` if the presented one has already expired. This property determines the lifetime of these `c_nonces`. If this property is set to 0 or a negative value, the default duration configured on the Authlete server will be applied. ### Authorization Servers An identifiers of the authorization servers that the credential issuer relies on for authorization when this service acts as a credential issuer. This property corresponds to the `authorization_servers` metadata defined in the [OID4VCI specification](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html). The values must be HTTP-accessible URLs. ### JWE alg Algorithms A list of supported JWE encryption algorithms ([RFC7516](https://datatracker.ietf.org/doc/html/rfc7516)), `alg` values defined in [RFC7518](https://datatracker.ietf.org/doc/html/rfc7518), supported by the Credential and Batch Credential Endpoint to encode the Credential or Batch Credential Response in a JWT. These algorithms are typically used to encrypt the content encryption key (CEK). ### JWE enc Algorithms A list of supported JWE encryption algorithms ([RFC7516](https://datatracker.ietf.org/doc/html/rfc7516)), `enc` values defined in [RFC7518](https://datatracker.ietf.org/doc/html/rfc7518), used by the Credential Endpoint to encode the Credential Response in a JWT ([RFC7519](https://datatracker.ietf.org/doc/html/rfc7519)). These algorithms are typically used to encrypt the content. ### Credential Response Encryption If **Require** is selected, the Credential Issuer mandates additional encryption on top of TLS for every Credential Response. In this case, the Wallet **MUST** provide encryption keys in the Credential Request. If **Require** is off, the Wallet may choose whether it provides encryption keys or not. ### Credential Issuer Identifier An identifier of the credential issuer when this service acts as a credential issuer. This property corresponds to the `credential_issuer` metadata defined in the [OID4VCI specification](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html). The value must be a valid URL with the `https` scheme, and it must not include a query part or fragment. Additionally, Authlete restricts this value to ASCII characters only and enforces a maximum length of 200 characters. This property must be set for the Authorization Server to function as a credential issuer. ### Credential Endpoint An URL of the credential endpoint when this service acts as a credential issuer. This property corresponds to the `credential_endpoint` metadata defined in the [OID4VCI specification](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html). The value must be a valid URL with the `https` scheme and must not include a fragment part. Additionally, Authlete restricts this value to ASCII characters only and enforces a maximum length of 200 characters. This property must be set for the service to function as a credential issuer. ### Batch Credential Endpoint An URL of the batch credential endpoint when this service acts as a credential issuer. This property corresponds to the `batch_credential_endpoint` metadata defined in the [OID4VCI specification](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html). The value must be a valid URL with the `https` scheme and must not include a fragment part. Additionally, Authlete restricts this value to ASCII characters only and enforces a maximum length of 200 characters. Implementing the batch credential endpoint is optional. ### Deferred Credential Endpoint An URL of the deferred credential endpoint when this service acts as a credential issuer. This property corresponds to the `deferred_credential_endpoint` metadata defined in the [OID4VCI specification](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html). The value must be a valid URL with the `https` scheme and must not include a fragment part. Additionally, Authlete restricts this value to ASCII characters only and enforces a maximum length of 200 characters. If the credential endpoint and/or the batch credential endpoint of your credential issuer may issue transaction IDs, you must implement the deferred credential endpoint. ### Supported Credentials Credentials supported by the credential issuer when this service acts as a credential issuer. This property corresponds to the `credential_configurations_supported` metadata defined in the [OID4VCI specification](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html). The value must be a JSON object. While non-ASCII characters are allowed, Authlete enforces a maximum length of 16,383 characters. This property must be set for the service to function as a credential issuer. For backward compatibility, the name of this property remains `credentialsSupported` and will not be renamed to `credentialConfigurationsSupported`.