Table of Contents
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 or via the Authlete APIs.
A name of this service. Up to 100 Unicode characters.
A description of this service. Up to 200 Unicode characters.
An identifier of this service as an OpenID Provider. Authlete uses it as the value of the “iss” claim in ID token issued by this service. Additionally, if this service implements a discovery endpoint (OpenID Connect Discovery 1.0, 4. Obtaining OpenID Provider Configuration Information) using Authlete’s /api/service/configuration API, Authlete uses it as the value of the “issuer” property included in the response from the endpoint.
The default value is “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 for details.
Names of custom client metadata that this service supports. Some names, such as client_name, are reserved and not supported.
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.
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.
Grant types supported by this service. This configuration item indicates which flows defined in RFC 6749 are supported. If this service 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. 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. 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. 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. 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. If this flow is disabled, refresh tokens are not issued.
[cf.] Diagrams And Videos Of All The OAuth 2.0 Flows
CIBA (TBD)
DEVICE_CODE (TBD)
TOKEN_EXCHANGE (TBD)
JWT_BEARER (TBD)
PRE_AUTHORIZED_CODE (TBD)
Supported combinations of tokens issued from the authorization endpoint. If this service 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 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
[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 for details.
FAPI is a set of security profiles defined by the FAPI Working Group under the OpenID Foundation.
OPEN_BANKING represents the Open Banking Security Profile defined by Open Banking Implementation Entity in the UK. This feature works on top of FAPI.
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.
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.
An URL of the authorization endpoint. If this service 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 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.
[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 (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.
(TBD)
[cf.] Proof Key for Code Exchange (RFC 7636)
The duration of authorization response JWTs in seconds.
Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM) defines the following new values for the response_mode request parameter:
query.jwtfragment.jwtform_post.jwtjwtIf 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).
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.
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 of RFC 8252 OAuth 2.0 for Native Apps.
3.1.2.3. Dynamic Configuration of RFC 6749 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 of OpenID Connect Core 1.0 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 of RFC 8252 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 oflocalhostis NOT RECOMMENDED. Specifying a redirect URI with the loopback IP literal rather thanlocalhostavoids 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 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 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.
A list of display languages supported on the authorization page of your authorization server. Technically, this is a list of language tags (RFC 5646) that the authorization endpoint recognizes as the value of the ui_locales parameter (OpenID Connect Core 1.0, 3.1.2.1. Authentication Request). If this service 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.
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). If this service 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.
Authentication context class references supported for user authentication at the authorization endpoint. If this service 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), (2) the acr claim in the claims request parameter (OpenID Connect Core 1.0, 5.5. Requesting Claims using the “claims” Request Parameter), and (3) the default_acr_values metadata (OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata) 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 defines at least two authentication contexts: “urn:openbanking:psd2:sca” and “urn:openbanking:psd2:ca”.
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.
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:
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.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.
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
nbfclaim, 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 annbfclaim; otherwise, the authorization server will reject it. This setting allows for backward compatibility when needed.
Supported values of the type field of each element in authorization_details. Details are defined in OAuth 2.0 Rich Authorization Requests.
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. 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.
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.
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.
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 and RFC 9101 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.
An URL of the token endpoint. If this service 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.
Client authentication methods supported at the token endpoint. If this service 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) 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 that uses a JWT with a symmetric signature algorithm. See OpenID Connect Core 1.0, 9. Client Authentication for details.
PRIVATE_KEY_JWT is a client authentication method defined in RFC 7523 that uses a JWT with an asymmetric signature algorithm. See OpenID Connect Core 1.0, 9. Client Authentication 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, 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, 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)
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.
If Allow is selected, token requests without the client_id request parameter from public clients (RFC 6749, Section 2.1) are allowed in the authorization code flow (Section 4.1) and the refresh token flow (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.
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 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.
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).
See JWT Authorization Grant on the Authlete website for details about the validation process performed by Authlete.
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).
See JWT Authorization Grant on the Authlete website for details about the validation process performed by Authlete.
An URL of the revocation endpoint (RFC 7009 ). If this service 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.
An URL of the introspection endpoint (RFC 7662 ). If this service 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.
If Require PAR is selected, Authlete rejects an authorization request that doesn’t employ PAR.
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.
The default value of the duration of request_uris 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.
An URL of the userinfo endpoint (OpenID Connect Core 1.0, 5.3. UserInfo Endpoint ). If this service 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.
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 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.
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 this service declares that it supports the client registration type explicit, this property must not be empty.
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.
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.
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 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.
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 for details about client registration.
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 for technical details about the scope parameter.
A DCR (Dynamic Client Registration) request may contain the software_id client metadata, defined in RFC 7591. 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.
An URL of an endpoint to register a client application dynamically (OpenID Connect Dynamic Client Registration 1.0). If this service 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.
An implementation of a registration endpoint is not mandatory.
Currently, Authlete does not provide any API that helps customers implement an API that complies with OpenID Connect Dynamic Client Registration 1.0. However, customers can register clients dynamically by using /api/service/create API.
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 of this service.
See OpenID Connect Dynamic Registration 1.0 for details about client registration.
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). Therefore, implementations of the client configuration endpoint were not able to conform to RFC 7592 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:
UNAUTHORIZED action.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).
This property corresponds to the grant_management_action_required server metadata defined in Grant Management for OAuth 2.0. 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.
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. 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) 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.
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.
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.
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.
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.
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.
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.
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.
If Validate 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 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”.
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.
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.
An URL of the backchannel authentication endpoint. This property corresponds to the backchannel_authentication_endpoint metadata.
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.
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.
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.
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.
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.
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
, set Bearer (case-insensitive).
In general, Web API implementations comply with RFC 6750 unless they have a clear reason to avoid it.
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.
The algorithm used for signing access tokens. If this property is set, access tokens issued by this service are JWTs. If not, access tokens issued by this service are random strings.
A key ID to identify the JWK (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 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.
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. 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.
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 “Enabled” is selected, 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.
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.
This flag indicates whether duration of refresh tokens are reset when they are used even if Token Rotation is enabled.
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.
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.
If the switch is turned on, the remaining duration of the used refresh token is carried over to the newly issued one. This setting has no effect when Token Rotation is enabled.
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.
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.
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.
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:
openid scope.When receiving ID_TOKEN_REISSUABLE, the implementation of the token endpoint can take either of the following actions:
OK action. This will result in the token endpoint behaving as before, and no ID token is reissued./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 for details.
Trust frameworks supported by this service. Pre-defined values listed in 11.1. Trust Frameworks of OpenID Connect for Identity Assurance 1.0 are as follows:
de_amleidas_ial_substantialeidas_ial_highnist_800_63A_ial_2nist_800_63A_ial_3jp_amljp_mpiupaTrust frameworks listed here are used as values of the trust_frameworks_supported metadata in the discovery document. See 7. OP Metadata for details.
Types of identity evidence supported by this service. Pre-defined values listed in 4.1.1. Evidence of OpenID Connect for Identity Assurance 1.0 are as follows:
id_documentutility_billqesIdentity evidence listed here are used as values of the evidence_supported metadata in the discovery document. See 7. OP Metadata for details.
Types of identity documents supported by this service. Pre-defined values listed in 11.2. Identity Documents of OpenID Connect for Identity Assurance 1.0 are as follows:
idcardpassportdriving_permitde_idcard_foreignersde_emergency_idcardde_erpde_erp_replacement_idcardde_idcard_refugeesde_idcard_apatridsde_certificate_of_suspension_of_deportationde_permission_to_residede_replacement_idcardjp_drivers_licensejp_residency_card_for_foreignerjp_individual_number_cardjp_permanent_residency_card_for_foreignerjp_health_insurance_cardjp_residency_cardIdentity document types listed here are used as values of the id_documents_supported metadata in the discovery document. See 7. OP Metadata for details.
Types of identity document verification methods supported by this service. Pre-defined values listed in 11.3. Verification Methods of OpenID Connect for Identity Assurance 1.0 are as follows:
pippsrippeidurippVerification methods listed here are used as values of the id_documents_verification_methods_supported metadata in the discovery document. See 7. OP Metadata for details.
Names of verified claims supported by this service. For example, given_name and family_name. See 3.1. Additional Claims about End-Users and 4.2. claims Element in OpenID Connect for Identity Assurance 1.0 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 for details.
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 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. Examples of predefined values are idcard and passport. See the identifiers page maintained by the eKYC-IDA WG for the complete list of predefined values.
(TBD)
(TBD)
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.
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.
Possible values are listed in the Hash Algorithm Registry of IANA (Internet Assigned Numbers Authority). If this service 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.
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). 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 for details about external attachments.
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). These files are found in the /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:
'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).A list of claims supported by this service. If this service 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 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.
A list of claim languages supported by this service. Technically, this is a list of language tags (RFC 5646) which the authorization endpoint recognizes as the value of the claims_locales parameter (OpenID Connect Core 1.0, 3.1.2.1. Authentication Request). If this service 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 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.
Claim types supported by this service. If this service 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 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 and pass it to Authlete’s /api/auth/authorization/issue API. Authlete itself does not support AGGREGATED and DISTRIBUTED directly.
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 responsesclaimNames in /api/backchannel/authentication API responsesclaimNames in /api/device/authorization API responsesIf 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.
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), this behavior is the general case. 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).
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.
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.
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.
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). 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). 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). 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).
If this service 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, 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" parameter. Usable characters are printable ASCII characters except space, double quote, and backslash."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.openid, profile, email, address, phone, and offline_access) cannot be changed.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. 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. 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 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 for details. |
| 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 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 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 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 even if the user is not logged in. See 11. Offline Access 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 documentation.
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 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 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.
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 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 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.
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 for details about token exchange.
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 on the Authlete website for details about the validation process performed by Authlete.
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 on the Authlete website for details about the validation process performed by Authlete.
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.
This setting displays details for Hardware-Secured Keys when the HSM feature is enabled and active.
Note: Only supported in Dedicated Cloud.
Content of the JWK Set document (RFC 7517) of this service.
If this service supports asymmetric algorithms for signing ID tokens, UserInfo Endpoint responses, and authorization responses (JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)) and for encrypting request objects, a JWK Set must be registered. The JWK Set must contain pairs of public and private keys for the algorithms that this service wants to support.
Algorithms that can be used as JWS (RFC 7515) “alg” are listed in 3.1. “alg” (Algorithm) Header Parameter Values for JWS of JWA (RFC 7518). Among them, algorithms whose names start with “RS”, “PS”, or “ES” are asymmetric algorithms.
Algorithms that can be used as JWE (RFC 7516) “alg” are listed in 4.1. “alg” (Algorithm) Header Parameter Values for JWE of JWA (RFC 7518). 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. Try it if you are not familiar with JWK.
An URL of the JWK Set document (RFC 7517) for this service. If this service 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 this service supports asymmetric algorithms for signing ID tokens, UserInfo Endpoint responses, and authorization responses (JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)), as well as for encrypting request objects, this service 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.
A key ID to identify the JWK (RFC 7517) 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 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.
A key ID to identify the JWK (RFC 7517) used for signing responses from the UserInfo Endpoint.
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 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.
A key ID to identify the JWK (RFC 7517) used for signing authorization responses (JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)).
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 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.
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.
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.
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.
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) when this credentialJwks property is updated, Authlete will automatically insert the kid property into such JWKs. The JWK thumbprint (RFC 7638) computed with the SHA-256 hash algorithm is used as the value of the kid property.
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.
An URL of the document describing how the data provided by this service can be used. If this service 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.
An URL of this service’s Terms Of Service for client application developers. If this service 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.
An URL of the documentation about this service for developers. If this service 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.
This flag controls availability of features related to Verifiable Credentials such as support of the OID4VCI specification.
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.
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.
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).
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.
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.
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.
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.
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 service to function as a credential issuer.
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.
The values must be HTTP-accessible URLs.
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.
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.
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.
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.
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.
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.
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.
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.
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.
A list of supported JWE encryption algorithms (RFC7516), alg values defined in 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).
A list of supported JWE encryption algorithms (RFC7516), enc values defined in RFC7518, used by the Credential Endpoint to encode the Credential Response in a JWT (RFC7519). These algorithms are typically used to encrypt the content.