Table of Contents
Services can be configured using Service Owner Console. This document explains configuration items of a service.
Some items are not available in the Service Owner Console (so.authlete.com) for the shared Authlete server (api.authlete.com) whose version is 1.x.
The name which identifies this service. This is used in the list of services in Service Owner Console and the login page of Developer Console. Also, it is used in the authorization page shown by the direct authorization endpoint.
As commercial use of the direct authorization endpoint is not recommended, the service name set here won’t be used in a commercial environment unless you make Developer Console accessible for third-party developers.
[IMPORTANT] The technical identifier of this service. This is used as the value of the “iss” claim in ID token s issued by this service. Also, if this service implements a discovery endpoint (OpenID Connect Discovery 1.0, 4. Obtaining OpenID Provider Configuration Information ) with Authlete’s /api/service/configuration API, it is used as the value of the “issuer” property included in the response from the endpoint.
The initial value on service creation is “https://authlete.com”, but make sure to change the value before commercial use. Set a URL which starts “https://” without the query part and the fragment part.
The URL of a discovery endpoint must be “{Token-Issuer-Identifer}/.well-known/openid-configuration”, so be careful when you determine 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.
The description of this service. This is used in the authorization page shown by the direct authorization endpoint.
As commercial use of the direct authorization endpoint is not recommended, the service description set here won’t be used in a commercial environment. Also, the service description is not required by specifications.
The maximum number of client applications that a developer is allowed to create. The default value is 0 which means no limit.
If you implement a developer authentication callback endpoint and register information about it to this service, developers can login Developer Console with their own login ID and password that are different from the service API key and the service API secret. If a service allows multiple developers to login Developer Console by utilizing the mechanism, this configuration item can control the maximum number of client applications that each developer can register.
You don’t have to care about this configuration item unless you are thinking of making Developer Console open to an unspecified large number of developers.
Select “Enabled” if you allow client applications to use client ID aliases in addition to numeric client IDs which are assigned by Authlete on client creation. If this is not enabled on the service side, Client ID Alias feature won’t work even if the configuration item with the same name in Developer Console is enabled.
If you have to continue to use existing client IDs which were assigned by your previous system, this Client ID Alias feature can be used for the requirement. If there is no such requirement, you can leave this setting item disabled.
“Authentication Callback Endpoint”, “Authentication Callback API Key” and “Authentication Callback API Secret” are information about the endpoint to which you delegate user authentication conducted in the authorization page shown by the direct authorization endpoint and in Resource Owner Password Credentials flow at the direct token endpoint.
An authentication callback endpoint is a Web API you implement. The specification of the endpoint is described in the JavaDoc of AuthenticationCallbackRequest and AuthenticationCallbackResponse classes in authlete-java-common library.
If an authentication callback API key and an authentication callback API secret are set, they are used as the user ID and the password of Basic Authentication when Authlete calls the authentication callback endpoint.
As commercial use of the direct authorization endpoint and the direct token endpoint is not recommended, You don’t have to fill in these configuration items for a commercial environment.
Configuration items related to user authentication options with external SNSes presented in the authorization page shown by the direct authorization endpoint.
As this feature is deprecated and use of the direct authorization endpoint is not recommended, you don’t have to fill in the configuration items.
Authentication context class references supported for the 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 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 have no plan to implement an authorization server which refers to the value of specified authentication contexts and changes its behavior accordingly, you can leave this configuration item empty.
FYI: The UK Open Banking defines at least two authentication contexts, “urn:openbanking:psd2:sca” and “urn:openbaning:psd2:ca”.
“Developer Authentication Callback Endpoint”, “Developer Authentication Callback API Key” and “Developer Authentication Callback API Secret” are information about the endpoint to which you delegate developer authentication conducted in the login page of Developer Console.
By default, you can login Developer Console with the service API key and the service API secret. If you want developers to login with their own ID and password, you need to fill in configuration items related to developer authentication.
A developer authentication callback endpoint is a Web API you implement. The specification of the endpoint is described in the JavaDoc of DeveloperAuthenticationCallbackRequest and DeveloperAuthenticationCallbackResponse classes in authlete-java-common library.
If a developer authentication callback API key and a developer authentication callback API secret are set, they are used as the user ID and the password of Basic Authentication when Authlete calls the developer authentication callback endpoint.
Configuration items related to developer authentication options with external SNSes presented in the login page of Developer Console.
As this feature is deprecated and its implementation has not been completed, this feature cannot be used.
[IMPORTANT] Grant types supported 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 flows enabled here. If an unsupported flow is used, it will cause an error.
AUTHORIZATION_CODE is a flow to get issued an authorization code at the authorization endpoint and exchange it with 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 at the authorization endpoint directly. Details are described in RFC 6749, 4.2. Implicit Grant . This flow is used, for example, to issue access tokens directly to JavaScript applications which 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 reasons. 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 token are not issued.
[cf.] Diagrams And Movies Of All The OAuth 2.0 Flows
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 to issue 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 can not 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”).
Note that the specification of Financial-grade API (FAPI) states that an authorization request must use either “code id_token” or “code id_token token” as the value of the “response_type” parameter for Read-Write API. Therefore, if you plan to support “Financial-grade API - Part 2: Read and Write API Security Profile “, don’t disable CODE_ID_TOKEN and CODE_ID_TOKEN_TOKEN. If both were disabled, authorization requests for FAPI Read-Write API would all fail.
[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 when your Authlete server is deployed, they cannot be used even if they are marked as enabled in Service Owner Console. Please contact sales@authlete.com for details.
FAPI represents “Financial-grade API” defined by the Financial-grade API Working Group of OpenID Foundation . For actual specifications, please refer to Read-Only API Security Profile and Read and Write API Security Profile .
OPEN_BANKING represents the Open Banking Security Profile defined by Open Banking Implementation Entity in the UK. This feature works on top of FAPI. Authlete, Inc. is one of the platform vendors that have passed the official conformance test suite of the security profile (cf. Open Banking Security Profile Conformance ).
If “Omitted” is selected, error responses from your authorization server won’t include the “error_description” response parameter.
“error_description” is a standard response parameter defined in RFC 6749, but its content is dependent 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 be generic or Authlete-specific. In either case, it contains an Authlete-specific result code. If you want to hide the information from client applications, select “Omitted”.
If you completely hide Authlete in a commercial environment, select “Omitted”. However, note that in that case error information returned to client applications will become very simple (e.g. “error=invalid_request” only), so it will take long time for client application developers to find error causes.
If “Omitted” is selected, error responses from your authorization server won’t include the “error_uri” response parameter.
“error_uri” is a standard response parameter defined in RFC 6749, but its content is dependent 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 from client applications, select “Omitted”.
If you completely hide Authlete in a commercial environment, select “Omitted”.
The 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.
["Disabled" recommended] The direct authorization endpoint is a simple implementation of an authorization endpoint which is directly hosted on the Authlete server. The endpoint is exposed at /api/auth/authorization/direct/{Service-API-Key}. This configuration item controls the accessibility of the endpoint.
The architecture of Authlete assumes that customers implement an authorization endpoint by themselves. However, it takes time. A problem here is that customers cannot try Authlete until they finish implementing an authorization endpoint. As a workaround for the problem, the direct endpoint was developed, but note that the main purpose of the direct endpoint is experiment and demonstration.
The initial value on service creation is “Enabled”, but change it to “Disabled” for commercial use.
The list of display languages supported in the authorization page of your authorization server. Technically, this is a list of language tags (RFC 5646 ) which 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 of 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 spec violation. Probably, most authorization server implementations recognize 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.
The list of display types supported in the authorization page of your authorization server. Technically, this is a list of valid values which 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 implementation regards all authorization requests which 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 of 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 spec violation.
If a value which 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.
["Enabled" recommended] This configuration item determines whether to require the “code_challenge” request parameter as a mandatory parameter in the authorization code flow.
If “Required” is selected, authorization requests using the authorization code flow without the “code_challenge” request parameter are all rejected.
If “Not Required” is selected, the “code_challenge” request parameter becomes optional, but even in the case, if an authorization request includes the request parameter, it is handled as the specification defines. As a result, the token request that corresponds the authorization request with the “code_challenge” request parameter has to include a “code_verifier” request parameter.
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 viewpoint of security.
By selecting “Required”, your system will become securer. 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 for commercial use.
[cf.] Proof Key for Code Exchange (RFC 7636)
The 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.
["Disabled" recommended] The direct token endpoint is an implementation of a token endpoint which is directly hosted on the Authlete server. The endpoint is exposed at /api/auth/token/direct/{Service-API-Key}. This configuration item controls the accessibility of the endpoint.
The architecture of Authlete assumes that customers implement a token endpoint by themselves. However, it takes time. A problem here is that customers cannot try Authlete until they finish implementing a token endpoint. As a workaround for the problem, the direct endpoint was developed, but note that the main purpose of the direct endpoint is experiment and demonstration.
The initial value on service creation is “Enabled”, but change it to “Disabled” for commercial use.
[IMPORTANT] 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 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 securer than CLIENT_SECRET_POST, authorization servers may adopt a security policy which allows CLIENT_SECRET_BASIC but does not allow CLIENT_SECRET_POST.
CLIENT_SECRET_JWT is a client authentication method defined in RFC 7523 which 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 which uses a JWT with an asymmetric signature algorithm. See OpenID Connect Core 1.0, 9. Client Authentication for details.
CLIENT_SECRET_JWT and PRIVATE_KEY_JWT have been listed here since before, but customers had to implement these client authentication methods by themselves if they want to support them because Authlete 1.x did not have any implementation for them.
Since Authlete 2.x, the JWT-based client authentication methods are supported on Authlete side, so customers don’t have to implement them by themselves.
TLS_CLIENT_AUTH is a client authentication method which 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 which 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.
Client authentication methods allowed for token requests for FAPI Read-Only API are the following four.1. TLS_CLIENT_AUTH 2. SELF_SIGNED_TLS_CLIENT_AUTH 3. CLIENT_SECRET_JWT 4. PRIVATE_KEY_JWT
Client authentication methods allowed for token requests for FAPI Read-Write API are the following three.1. TLS_CLIENT_AUTH 2. SELF_SIGNED_TLS_CLIENT_AUTH 3. PRIVATE_KEY_JWT
Therefore, to comply with FAPI, other client authentication methods than NONE, CLIENT_SECRET_BASIC and CLIENT_SECRET_POST must be supported.
If “Enabled” 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 “Disabled” is 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”.
If the configuration item above, “Validate PKI Certificate Chain for Mutual TLS Authentication” is enabled, Authlete server checks whether client certificates used for TLS_CLIENT_AUTH can be reached from root certificates registered here.
The 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.
["Disabled" recommended] The direct revocation endpoint is an implementation of a revocation endpoint which is directly hosted on the Authlete server. The endpoint is exposed at /api/auth/revocation/direct/{Service-API-Key}. This configuration item controls the accessibility of the endpoint.
The initial value on service creation is “Enabled”, but change it to “Disabled” for commercial use.
The 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.
["Disabled" recommended] The direct introspection endpoint is an implementation of an introspection endpoint which is directly hosted on the Authlete server. The endpoint is exposed at /api/auth/introspection/standard/direct. This configuration item controls the accessibility of the endpoint.
The initial value on service creation is “Enabled”, but change it to “Disabled” for commercial use.
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.
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 , 3. Mutual TLS Client Certificate Bound Access Tokens. If “Supported” 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 “Supported” 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.
In Financial-grade API, authorization codes, access tokens and refresh tokens for Read-Write APIs must be associated with a client certificate. Therefore, if you have a plan to support Read and Write API Security Profile , select “Supported” here.
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.
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.
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.
[IMPORTANT] List of scopes 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 “scopes_supported” property included in the response from the endpoint.
Values listed here are recognized as the values of the “scope” parameter of authorization requests. Authlete silently ignores unknown scope 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 says “Scope values used that are not understood by an implementation SHOULD be ignored.”
Each scope has configuration items such as name, default entry (boolean), description and attributes.
“Scope Name” is a string used as the value of the “scope” parameter. Usable characters are printable ASCII characters except space, double quote and backslash.
“Default Entry” is a boolean flag which is referred to when an authorization request does not have the “scope” parameter. If the “scope” parameter is missing, scopes whose default entry is true are used as if they were specified by the “scope” parameter.
“Description” is not required by the specification, but Authlete manages the data. Note that descriptions of the standard scopes defined in OpenID Connect Core 1.0 (openid, profile, email, address, phone and offline_access) cannot be changed.
“Attributes” are arbitrary key-value pairs. The functionality to attach arbitrary key-value pairs to scopes is a custom mechanism provided by Authlete.
Note that 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 which includes at least one scope having this scope 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 which includes at least one scope having this scope 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 and the authorization request is regarded as a request for access token for Read-Write API. |
On service creation, standard scopes defined in OpenID Connect Core 1.0 are set as the initial value.
| 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. Don’t remove this scope unless you have a clear reason because OpenID Connection won’t work without the scope. See 3.1.2.1. Authentication Request for details. |
| profile | The scope to request claims related to 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 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 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 be issued which can be used to get an access token which has a permission to access the userinfo endpoint even if the user does not logged in. See 11. Offline Access for details. |
There is no rule about the granularity of scopes. There is no single answer.
If you are almost losing control because of too many fine-grained scope definitions, a better approach may be to attach information per access token. Authlete provides a mechanism to attach arbitrary key-value pairs to an access token, so consider using it (cf. Extra Properties ).
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.
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 only enabled.
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.
The 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 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.
The 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.
The URL of the JWK Set document (RFC 7517 ) of 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 “jwks_uri” property included in the response from the endpoint.
If the configuration item, “JWK Set Content” is empty, Authlete tries to fetch a JWK Set from the URI set here as necessary. However, Authlete will never try to fetch an external JWK Set for secret keys of asymmetric algorithms. Therefore, if there exist processes that use secret keys of asymmetric algorithms, for example, if ID tokens are signed with asymmetric algorithms, the secret keys of the algorithms need to be registered as parts of “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) ) and for encrypting request objects , this service must implement a JWK Set endpoint (unless this service passes its JWK set to client application developers offline).
Authlete’s /api/service/jwks/get API is an API that helps customers implement their own JWK Set endpoint.
["Disabled" recommended] The direct JWK Set endpoint is an implementation of a JWK Set endpoint (RFC 7517 ) which is directly hosted on the Authlete server. The endpoint is exposed at /api/service/jwks/get/direct/{Service-API-Key}. This configuration item controls the accessibility of the endpoint.
The initial value on service creation is “Enabled”, but change it to “Disabled” for commercial use.
The 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 key and private key for 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 name starts 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 name starts 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.
The 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 applicable JWK, then there is no problem. On the other hand, if there are multiple candidates, a key ID needs to be specified so that Authlete Server can select the correct one.
Even if there are multiple candidate JWKs but this configuration item is left empty, Authlete Server will try its best to choose one. However, there are cases where Authlete Server fails (e.g. there are multiple candidate JWKs but none of them has a key ID). In this case, Authlete Server fails to generate an ID token.
The key ID to identify the JWK (RFC 7517 ) used for signing responses from UserInfo Endpoint .
When the algorithm for signing responses from 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 applicable JWK, then there is no problem. On the other hand, if there are multiple candidates, a key ID needs to be specified so that Authlete Server can select the correct one.
Even if there are multiple candidate JWKs but this configuration item is left empty, Authlete Server will try its best to choose one. However, there are cases where Authlete Server fails (e.g. there are multiple candidate JWKs but none of them has a key ID). In this case, Authlete Server fails to generate a response from UserInfo Endpoint.
The 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 applicable JWK, then there is no problem. On the other hand, if there are multiple candidates, a key ID needs to be specified so that Authlete Server can select the correct one.
Even if there are multiple candidate JWKs but this configuration item is left empty, Authlete Server will try its best to choose one. However, there are cases where Authlete Server fails (e.g. there are multiple candidate JWKs but none of them has a key ID). In this case, Authlete Server fails to generate an authorization response JWT. As a result, an error response is returned in the format defined in RFC 6749.
The URIL 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.
["Disabled" recommended] The direct userinfo endpoint is an implementation of a userinfo endpoint which is directly hosted on the Authlete server. This configuration item controls the accessibility of the endpoint.
The initial value on service creation is “Enabled”, but change it to “Disabled” for commercial use.
Note: The direct userinfo endpoint has not been implemented. Therefore, the endpoint is not usable regardless of whether this configuration item is enabled or disabled.
The 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 which complies with OpenID Connect Dynamic Client Registration 1.0. However, customers can register clients dynamically by using /api/service/create API.
The 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.
The 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.
The 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.