curl

curl -v -X POST https://us.authlete.com/api/21653835348762/auth/authorization \
-H 'Content-Type: application/json' \
-u 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \
-d '{ "parameters": "response_type=code&client_id=26478243745571&redirect_uri=https%3A%2F%2Fmy-client.example.com%2Fcb1&scope=timeline.read+history.read&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256" }'

{
  "resultCode": "A004001",
  "resultMessage": "[A004001] Authlete has successfully issued a ticket to the service (API Key = 21653835348762) for the authorization request from the client (ID = 26478243745571). [response_type=code, openid=false]",
  "acrEssential": false,
  "action": "INTERACTION",
  "client": {
    "clientId": 26478243745571,
    "clientIdAlias": "my-client",
    "clientIdAliasEnabled": true,
    "clientName": "My updated client",
    "logo_uri": "https://my-client.example.com/logo.png",
    "number": 6164
  },
  "clientIdAliasUsed": false,
  "display": "PAGE",
  "maxAge": 0,
  "scopes": [
    {
      "defaultEntry": false,
      "description": "A permission to read your history.",
      "name": "history.read"
    },
    {
      "defaultEntry": false,
      "description": "A permission to read your timeline.",
      "name": "timeline.read"
    }
  ],
  "service": {
    "apiKey": 21653835348762,
    "clientIdAliasEnabled": true,
    "number": 5041,
    "serviceName": "My updated service"
  },
  "ticket": "hXoY87t_t23enrVHWxpXNP5FfVDhDypD3T6H6lt4IPA"
}

Authorization Endpoint

Process Authorization Request

This API parses request parameters of an authorization request and returns necessary data for the authorization server implementation to process the authorization request further.

Description

This API is supposed to be called from within the implementation of the authorization endpoint of the service. The endpoint implementation must extract the request parameters from the authorization request from the client application and pass them as the value of parameters request parameter for Authlete’s /auth/authorization API. The value of parameters is either (1) the entire query string when the HTTP method of the request from the client application is GET or (2) the entire entity body (which is formatted in application/x-www-form-urlencoded) when the HTTP method of the request from the client application is POST. The following code snippet is an example in JAX-RS showing how to extract request parameters from the authorization request.

@GET
public Response get(@Context UriInfo uriInfo)
{
    // The query parameters of the authorization request.
    String parameters = uriInfo.getRequestUri().getQuery();
    ......
}
@POST
@Consumes(MediaType.APPLICATION\_FORM\_URLENCODED)
public Response post(String parameters)
{
    // 'parameters' is the entity body of the authorization request.
    ......
}

The endpoint implementation does not have to parse the request parameters from the client application because Authlete’s /auth/authorization API does it. The response from /auth/authorization API has various parameters. Among them, it is action parameter that the authorization server implementation should check first because it denotes the next action that the authorization server implementation should take. According to the value of action, the service implementation must take the steps described below. INTERNAL_SERVER_ERROR When the value of action is INTERNAL\_SERVER\_ERROR, it means that the request from the authorization server implementation was wrong or that an error occurred in Authlete. In either case, from the viewpoint of the client application, it is an error on the server side. Therefore, the service implementation should generate a response to the client application with HTTP status of “500 Internal Server Error”. Authlete recommends application/json as the content type although OAuth 2.0 specification does not mention the format of the error response when the redirect URI is not usable. The value of responseContent is a JSON string which describes the error, so it can be used as the entity body of the response. The following illustrates the response which the service implementation should generate and return to the client application.

HTTP/1.1 500 Internal Server Error
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{responseContent}

The endpoint implementation may return another different response to the client application since “500 Internal Server Error” is not required by OAuth 2.0. BAD_REQUEST When the value of action is BAD\_REQUEST, it means that the request from the client application is invalid. A response with HTTP status of “400 Bad Request” should be returned to the client application and Authlete recommends application/json as the content type although OAuth 2.0 specification does not mention the format of the error response when the redirect URI is not usable. The value of responseContent is a JSON string which describes the error, so it can be used as the entity body of the response. The following illustrates the response which the service implementation should generate and return to the client application.

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{responseContent}

The endpoint implementation may return another different response to the client application since “400 Bad Request” is not required by OAuth 2.0. LOCATION When the value of action is LOCATION, it means that the request from the client application is invalid but the redirect URI to which the error should be reported has been determined. A response with HTTP status of “302 Found” must be returned to the client application with Location header which has a redirect URI with error parameter. The value of responseContent is a redirect URI with error parameter, so it can be used as the value of Location header. The following illustrates the response which the service implementation must generate and return to the client application.

HTTP/1.1 302 Found
Location: {responseContent}
Cache-Control: no-store
Pragma: no-cache

FORM When the value of action is FORM, it means that the request from the client application is invalid but the redirect URI to which the error should be reported has been determined, and that the authorization request contains response\_mode=form\_post as is defined in OAuth 2.0 Form Post Response Mode. The HTTP status of the response returned to the client application should be “200 OK” and the content type should be text/html;charset=UTF-8. The value of responseContent is an HTML which can be used as the entity body of the response. The following illustrates the response which the service implementation must generate and return to the client application.

HTTP/1.1 200 OK
Content-Type: text/html;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{responseContent}

NO_INTERACTION When the value of action is NO\_INTERACTION, it means that the request from the client application has no problem and requires the service to process the request without displaying any user interface pages for authentication or consent. This case happens when the authorization request contains prompt=none. The service must follow the steps described below. [1] END-USER AUTHENTICATION Check whether an end-user has already logged in. If an end-user has logged in, go to the next step ([MAX_AGE]). Otherwise, call Authlete’s /auth/authorization/fail API with reason=NOT\_LOGGED\_IN and use the response from the API to generate a response to the client application. [2] MAX AGE Get the value of maxAge parameter from the /auth/authorization API response. The value represents the maximum authentication age which has come from max\_age request parameter or defaultMaxAge configuration parameter of the client application. If the value is 0, go to the next step ([SUBJECT]). Otherwise, follow the sub steps described below. (i) Get the time at which the end-user was authenticated. that this value is not managed by Authlete, meaning that it is expected that the service implementation manages the value. If the service implementation does not manage authentication time of end-users, call Authlete’s /auth/authorization/fail API with reason=MAX\_AGE\_NOT\_SUPPORTED and use the API response to generate a response to the client application. (ii) Add the value of the maximum authentication age (which is represented in seconds) to the authentication time. The calculated value is the expiration time. (iii) Check whether the calculated value is equal to or greater than the current time. If this condition is satisfied, go to the next step ([SUBJECT]). Otherwise, call Authlete’s /auth/authorization/fail API with reason=EXCEEDS\_MAX\_AGE and use the API response to generate a response to the client application. [3] SUBJECT Get the value of subject from the /auth/authorization API response. The value represents an end-user who the client application expects to grant authorization. If the value is null, go to the next step ([ACRs]). Otherwise, follow the sub steps described below. (i) Compare the value of the requested subject to the current end-user. (ii) If they are equal, go to the next step ([ACRs]). If they are not equal, call Authlete’s /auth/authorization/fail API with reason=DIFFERENT\_SUBJECT and use the response from the API to generate a response to the client application. [4] ACRs Get the value of acrs from the /auth/authorization API response. The value represents a list of ACRs (Authentication Context Class References) and comes from (1) acr claim in claims request parameter, (2) acr\_values request parameter, or (3) default\_acr\_values configuration parameter of the client application. It is ensured that all the ACRs in acrs are supported by the authorization server implementation. In other words, it is ensured that all the ACRs are listed in acr\_values\_supported configuration parameter of the authorization server. If the value of ACRs is null, go to the next step ([ISSUE]). Otherwise, follow the sub steps described below. (i) Get the ACR performed for the authentication of the current end-user. Note that this value is managed not by Authlete but by the authorization server implementation. (If the authorization server implementation cannot handle ACRs, it should not have listed ACRs as acr\_values\_supported.) (ii) Compare the ACR value obtained in the above step to each element in the ACR array (acrs) in the listed order. (iii) If the ACR value was found in the array, (= the ACR performed for the authentication of the current end-user did not match any one of the ACRs requested by the client application), check whether one of the requested ACRs must be satisfied or not using acrEssential parameter in the /auth/authorization API response. If the value of acrEssential parameter is true, call Authlete’s /auth/authorization/fail API with reason=ACR\_NOT\_SATISFIED and use the response from the API to generate a response to the client application. Otherwise, go to the next step ([SCOPES]). [5] SCOPES Get the value of scopes from the /auth/authorization API response. If the array contains a scope which has not been granted to the client application by the end-user in the past, call Authlete’s /auth/authorization/fail API with reason=CONSENT\_REQUIRED and use the response from the API to generate a response to the client application. Otherwise, go to the next step ([RESOURCES]). Note that Authlete provides APIs to manage records of granted scopes (/api/client/granted\_scopes/\* APIs), which is only available in a dedicated/onpremise Authlete server (contact [email protected] for details). [6] DYNAMIC SCOPES Get the value of dynamicScopes from the /auth/authorization API response. If the array contains a scope which has not been granted to the client application by the end-user in the past, call Authlete’s /auth/authorization/fail API with reason=CONSENT\_REQUIRED and use the response from the API to generate a response to the client application. Otherwise, go to the next step ([RESOURCES]). Note that Authlete provides APIs to manage records of granted scopes (/api/client/granted\_scopes/\* APIs) but dynamic scopes are not remembered as granted scopes. [7] RESOURCES Get the value of resources from the /auth/authorization API response. The array represents the values of the resource request parameters. If you want to reject the request, call Authlete’s /auth/authorization/fail API with reason=INVALID\_TARGET and use the response from the API to generate a response to the client application. Otherwise, go to the next step ([ISSUE]). See “Resource Indicators for OAuth 2.0” for details. [8] ISSUE If all the above steps succeeded, the last step is to issue an authorization code, an ID token and/or an access token. (There is a special case, though. In the case of response\_type=none, nothing is issued.) It can be performed by calling Authlete’s /auth/authorization/issue API. The API requires the following parameters. Prepare these parameters and call /auth/authorization/issue API and use the response to generate a response to the client application.

ticket (required) This parameter represents a ticket which is exchanged with tokens at /auth/authorization/issue. Use the value of ticket contained in the /auth/authorization API response.
subject (required) This parameter represents the unique identifier of the current end-user. It is often called “user ID” and it may or may not be visible to the user. In any case, it is a number or a string assigned to an end-user by the authorization server implementation. Authlete does not care about the format of the value of subject, but it must consist of only ASCII letters and its length must not exceed 100. When the value of subject parameter in the /auth/authorization API response is not null, it is necessarily identical to the value of subject parameter in the /auth/authorization/issue API request. The value of this parameter will be embedded in an ID token as the value of sub claim. When the value of subject\_type configuration parameter of the client application is PAIRWISE, the value of sub claim is different from the value specified by this parameter, See 8. Subject Identifier Types of OpenID Connect Core 1.0 for details about subject types. You can use the sub request parameter to adjust the value of the sub claim in an ID token. See the description of the sub request parameter for details.
authTime (optional) This parameter represents the time when the end-user authentication occurred. Its value is the number of seconds from 1970-01-01. The value of this parameter will be embedded in an ID token as the value of auth\_time claim.
acr (optional) This parameter represents the ACR (Authentication Context Class Reference) which the authentication of the end-user satisfies. When acrs in the /auth/authorization API response is a non-empty array and the value of acrEssential is true, the value of this parameter must be one of the array elements. Otherwise, even null is allowed. The value of this parameter will be embedded in an ID token as the value of acr claim.
claims (optional) This parameter represents claims of the end-user. “Claims” here are pieces of information about the end-user such as "name", "email" and "birthdate". The authorization server implementation is required to gather claims of the end-user, format the claim values into JSON and set the JSON string as the value of this parameter. The claims which the authorization server implementation is required to gather are listed in claims parameter in the /auth/authorization API response. For example, if claims parameter lists "name", "email" and "birthdate", the value of this parameter should look like the following.
```
{
  "name": "John Smith",
  "email": "[email protected]",
  "birthdate": "1974-05-06"
}
```
claimsLocales parameter in the /auth/authorization API response lists the end-user’s preferred languages and scripts, ordered by preference. When claimsLocales parameter is a non-empty array, its elements should be taken into account when the authorization server implementation gathers claim values. Especially, note the excerpt below from 5.2. Claims Languages and Scripts of OpenID Connect Core 1.0.

When the OP determines, either through the claims\_locales parameter, or by other means, that the End-User and Client are requesting Claims in only one set of languages and scripts, it is RECOMMENDED that OPs return Claims without language tags when they employ this language and script. It is also RECOMMENDED that Clients be written in a manner that they can handle and utilize Claims using language tags. If claims parameter in the /auth/authorization API response is null or an empty array, the value of this parameter should be null. See 5.1. Standard Claims of OpenID Connect core 1.0 for claim names and their value formats. Note (1) that the authorization server implementation support its special claims (5.1.2. Additional Claims) and (2) that claim names may be followed by a language tag (5.2. Claims Languages and Scripts). Read the specification of OpenID Connect Core 1.0 for details. The claim values in this parameter will be embedded in an ID token. Note that idTokenClaims parameter is available in the /auth/authorization API response. The parameter has the value of the "id\_token" property in the claims request parameter or in the "claims" property in a request object. The value of this parameter should be considered when you prepare claim values.

properties (optional) Extra properties to associate with an access token and/or an authorization code that may be issued by this request. Note that properties parameter is accepted only when Content-Type of the request is application/json, so don’t use application/x-www-form-urlencoded for details.
scopes (optional) Scopes to associate with an access token and/or an authorization code. If this parameter is null, the scopes specified in the original authorization request from the client application are used. In other cases, including the case of an empty array, the specified scopes will replace the original scopes contained in the original authorization request. Even scopes that are not included in the original authorization request can be specified. However, as an exception, openid scope is ignored on the server side if it is not included in the original request. It is because the existence of openid scope considerably changes the validation steps and because adding openid triggers generation of an ID token (although the client application has not requested it) and the behavior is a major violation against the specification. If you add offline\_access scope although it is not included in the original request, keep in mind that the specification requires explicit consent from the user for the scope (OpenID Connect Core 1.0, 11. Offline Access). When offline\_access is included in the original request, the current implementation of Authlete’s /auth/authorization API checks whether the request has come along with prompt request parameter and the value includes consent. However, note that the implementation of Authlete’s /auth/authorization/issue API does not perform such checking if offline\_access scope is added via this scopes parameter.
sub (optional) The value of the sub claim in an ID token. If the value of this request parameter is not empty, it is used as the value of the sub claim. Otherwise, the value of the subject request parameter is used as the value of the sub claim. The main purpose of this parameter is to hide the actual value of the subject from client applications. Note that even if this sub parameter is not empty, the value of the subject request parameter is used as the value of the subject which is associated with the access token. INTERACTION When the value of action is INTERACTION, it means that the request from the client application has no problem and requires the service to process the request with user interaction by an HTML form. The purpose of the UI displayed to the end-user is to ask the end-user to grant authorization to the client application. The items described below are some points which the service implementation should take into account when it builds the UI. [1] DISPLAY MODE The response from /auth/authorization API has display parameter. It is one of PAGE (default), POPUP, TOUCH and WAP The meanings of the values are described in 3.1.2.1. Authentication Request of OpenID Connect Core 1.0. Basically, the authorization server implementation should display the UI which is suitable for the display mode, but it is okay for the authorization server implementation to “attempt to detect the capabilities of the User Agent and present an appropriate display”. It is ensured that the value of display is one of the supported display modes which are specified by supportedDisplays configuration parameter of the service. [2] UI LOCALE The response from /auth/authorization API has uiLocales parameter. It it is not null, it lists language tag values (such as fr-CA, ja-JP and en) ordered by preference. The service implementation should display the UI in one of the language listed in the parameter when possible. It is ensured that language tags listed in uiLocales are contained in the list of supported UI locales which are specified by supportedUiLocales configuration parameter of the service. [3] CLIENT INFORMATION The authorization server implementation should show information about the client application to the end-user. The information is embedded in client parameter in the response from /auth/authorization API. [4] SCOPES A client application requires authorization for specific permissions. In OAuth 2.0 specification, “scope” is a technical term which represents a permission. scopes parameter in the response from /auth/authorization API is a list of scopes requested by the client application. The service implementation should show the end-user the scopes. The authorization server implementation may choose not to show scopes to which the end-user has given consent in the past. To put it the other way around, the authorization server implementation may show only the scopes to which the end-user has not given consent yet. However, if the value of prompts response parameter contains CONSENT, the authorization server implementation has to obtain explicit consent from the end-user even if the end-user has given consent to all the requested scopes in the past. Note that Authlete provides APIs to manage records of granted scopes (/api/client/granted\_scopes/\* APIs), but the APIs work only in the case the Authlete server you use is a dedicated Authlete server (contact [email protected] for details). In other words, the APIs of the shared Authlete server are disabled intentionally (in order to prevent garbage data from being accumulated) and they return 403 Forbidden. It is ensured that the values in scopes parameter are contained in the list of supported scopes which are specified by supportedScopes configuration parameter of the service. [5] DYNAMIC SCOPES The authorization request may include dynamic scopes. The list of recognized dynamic scopes are accessible by getDynamicScopes() method. See the description of the DynamicScope class for details about dynamic scopes. [6] AUTHORIZATION DETAILS The authorization server implementation should show the end-user “authorization details” if the request includes it. The value of authorization\_details parameter in the response is the content of the authorization\_details request parameter. See “OAuth 2.0 Rich Authorization Requests” for details. [7] PURPOSE The authorization server implementation must show the value of the purpose request parameter if it supports OpenID Connect for Identity Assurance 1.0. See 8. Transaction-specific Purpose in the specification for details. Note that the value of purpose response parameter is the value of the purpose request parameter. [7] END-USER AUTHENTICATION Necessarily, the end-user must be authenticated (= must login the service) before granting authorization to the client application. Simply put, a login form is expected to be displayed for end-user authentication. The service implementation must follow the steps described below to comply with OpenID Connect. (Or just always show a login form if it’s too much of a bother.) (i) Get the value of prompts response parameter. It corresponds to the value of the prompt request parameter. Details of the request parameter are described in 3.1.2.1. Authentication Request of OpenID Connect Core 1.0. (ii) If the value of prompts parameter is SELECT\_ACCOUNT display a form to let the end-user select on of his/her accounts for login. If subject response parameter is not null, it is the end-user ID that the client application expects, so the value should be used to determine the value of the login ID. Note that a subject and a login ID are not necessarily equal. If the value of subject response parameter is null, the value of loginHint response parameter should be referred to as a hint to determine the value of the login ID. The value of loginHint response parameter is simply the value of the login\_hint request parameter. (iii) If the value of prompts response parameter contains LOGIN, display a form to urge the end-user to login even if the end-user has already logged in. If the value of subject response parameter is not null, it is the end-user ID that the client application expects, so the value should be used to determine the value of the login ID. Note that a subject and a login ID are not necessarily equal. If the value of subject response parameter is null, the value of loginHint response parameter should be referred to as a hint to determine the value of the login ID. The value of loginHint response parameter is simply the value of the login\_hint request parameter. (iv) If the value of prompts response parameter does not contain LOGIN, the authorization server implementation does not have to authenticate the end-user if all the conditions described below are satisfied. If any one of the conditions is not satisfied, show a login form to authenticate the end-user.
An end-user has already logged in the service.
The login ID of the current end-user matches the value of subject response parameter. This check is required only when the value of subject response parameter is a non-null value.
The max age, which is the number of seconds contained in maxAge response parameter, has not passed since the current end-user logged in your service. This check is required only when the value of maxAge response parameter is a non-zero value.
If the authorization server implementation does not manage authentication time of end-users (= if the authorization server implementation cannot know when end-users logged in) and if the value of maxAge response parameter is a non-zero value, a login form should be displayed.
The ACR (Authentication Context Class Reference) of the authentication performed for the current end-user satisfies one of the ACRs listed in acrs response parameter. This check is required only when the value of acrs response parameter is a non-empty array. In every case, the end-user authentication must satisfy one of the ACRs listed in acrs response parameter when the value of acrs response parameter is a non-empty array and acrEssential response parameter is true. [9] GRANT/DENY BUTTONS The end-user is supposed to choose either (1) to grant authorization to the client application or (2) to deny the authorization request. The UI must have UI components to accept the judgment by the user. Usually, a button to grant authorization and a button to deny the request are provided. When the value of subject response parameter is not null, the end-user authentication must be performed for the subject, meaning that the authorization server implementation should repeatedly show a login form until the subject is successfully authenticated. The end-user will choose either (1) to grant authorization to the client application or (2) to deny the authorization request. When the end-user chose to deny the authorization request, call Authlete’s /auth/authorization/fail API with reason=DENIED and use the response from the API to generate a response to the client application. When the end-user chose to grant authorization to the client application, the authorization server implementation has to issue an authorization code, an ID token, and/or an access token to the client application. (There is a special case. When response\_type=none, nothing is issued.) Issuing the tokens can be performed by calling Authlete’s /auth/authorization/issue API. Read [ISSUE] written above in the description for the case of action=NO\_INTERACTION.

POST

api

{serviceId}

auth

authorization

curl

curl -v -X POST https://us.authlete.com/api/21653835348762/auth/authorization \
-H 'Content-Type: application/json' \
-u 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \
-d '{ "parameters": "response_type=code&client_id=26478243745571&redirect_uri=https%3A%2F%2Fmy-client.example.com%2Fcb1&scope=timeline.read+history.read&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256" }'

{
  "resultCode": "A004001",
  "resultMessage": "[A004001] Authlete has successfully issued a ticket to the service (API Key = 21653835348762) for the authorization request from the client (ID = 26478243745571). [response_type=code, openid=false]",
  "acrEssential": false,
  "action": "INTERACTION",
  "client": {
    "clientId": 26478243745571,
    "clientIdAlias": "my-client",
    "clientIdAliasEnabled": true,
    "clientName": "My updated client",
    "logo_uri": "https://my-client.example.com/logo.png",
    "number": 6164
  },
  "clientIdAliasUsed": false,
  "display": "PAGE",
  "maxAge": 0,
  "scopes": [
    {
      "defaultEntry": false,
      "description": "A permission to read your history.",
      "name": "history.read"
    },
    {
      "defaultEntry": false,
      "description": "A permission to read your timeline.",
      "name": "timeline.read"
    }
  ],
  "service": {
    "apiKey": 21653835348762,
    "clientIdAliasEnabled": true,
    "number": 5041,
    "serviceName": "My updated service"
  },
  "ticket": "hXoY87t_t23enrVHWxpXNP5FfVDhDypD3T6H6lt4IPA"
}

Authorizations

Authorization

string

header

required

Click the Get Token button below to log in with your Authlete account and retrieve an access token for API access.

Path Parameters

serviceId

string

required

A service ID.

Body

parameters

string

required

OAuth 2.0 authorization request parameters which are the request parameters that the OAuth 2.0 authorization endpoint of the authorization server implementation received from the client application.

The value of parameters is either (1) the entire query string when the HTTP method of the request from the client application is GET or (2) the entire entity body (which is formatted in application/x-www-form-urlencoded) when the HTTP method of the request from the client application is POST.

context

string

The arbitrary text to be attached to the ticket that will be issued from the /auth/authorization API.

The text can be retrieved later by the /auth/authorization/ticket/info API and can be updated by the /auth/authorization/ticket/update API.

The text will be compressed and encrypted when it is saved in the Authlete database.

Response

number

integer<int32>

The sequential number of the service. The value of this property is assigned by Authlete.

serviceName

string

The name of this service.

issuer

string

The issuer identifier of the service.

A URL that starts with https:// and has no query or fragment component.

The value of this property is used as iss claim in an ID token and issuer property in the OpenID Provider Metadata.

description

string

The description about the service.

apiKey

integer<int64>

The service ID used in Authlete API calls. The value of this property is assigned by Authlete.

clientIdAliasEnabled

boolean

Deprecated. Always true.

metadata

object[]

The metadata of the service. The content of the returned array depends on contexts. The predefined service metadata is listed in the following table.

Key	Description
`clientCount`	The number of client applications which belong to this service.

Show child attributes

createdAt

integer<int64>

The time at which this service was created. The value is represented as milliseconds since the UNIX epoch (1970-01-01).

modifiedAt

integer<int64>

The time at which this service was last modified. The value is represented as milliseconds since the UNIX epoch (1970-01-01).

authenticationCallbackEndpoint

string<uri>

A Web API endpoint for user authentication which is to be prepared on the service side.

The endpoint must be implemented if you do not implement the UI at the authorization endpoint but use the one provided by Authlete.

The user authentication at the authorization endpoint provided by Authlete is performed by making a POST request to this endpoint.

authenticationCallbackApiKey

string

API key for basic authentication at the authentication callback endpoint.

If the value is not empty, Authlete generates Authorization header for Basic authentication when making a request to the authentication callback endpoint.

authenticationCallbackApiSecret

string

API secret for basic authentication at the authentication callback endpoint.

supportedAcrs

string[]

Values of acrs (authentication context class references) that the service supports.

The value of this property is used as acr_values_supported property in the OpenID Provider Metadata.

supportedGrantTypes

enum<string>[]

Values of grant_type request parameter that the service supports.

The value of this property is used as grant_types_supported property in the OpenID Provider Metadata.

The grant type of the access token when the access token was created.

Available options:

AUTHORIZATION_CODE,

IMPLICIT,

PASSWORD,

CLIENT_CREDENTIALS,

REFRESH_TOKEN,

CIBA,

DEVICE_CODE,

TOKEN_EXCHANGE,

JWT_BEARER

supportedResponseTypes

enum<string>[]

Values of response_type request parameter that the service supports. Valid values are listed in Response Type.

The value of this property is used as response_types_supported property in the OpenID Provider Metadata.

Available options:

NONE,

CODE,

TOKEN,

ID_TOKEN,

CODE_TOKEN,

CODE_ID_TOKEN,

ID_TOKEN_TOKEN,

CODE_ID_TOKEN_TOKEN

supportedAuthorizationDetailsTypes

string[]

The supported data types that can be used as values of the type field in authorization_details.

This property corresponds to the authorization_details_types_supported metadata. See "OAuth 2.0 Rich Authorization Requests" (RAR) for details.

supportedServiceProfiles

enum<string>[]

The profiles that this service supports.

Available options:

FAPI,

OPEN_BANKING

errorDescriptionOmitted

boolean

The flag to indicate whether the error_description response parameter is omitted.

According to RFC 6749, an authorization server may include the error_description response parameter in error responses.

If true, Authlete does not embed the error_description response parameter in error responses.

errorUriOmitted

boolean

The flag to indicate whether the error_uri response parameter is omitted.

According to RFC 6749, an authorization server may include the error_uri response parameter in error responses.

If true, Authlete does not embed the error_uri response parameter in error responses.

authorizationEndpoint

string<uri>

The authorization endpoint of the service.

A URL that starts with https:// and has no fragment component. For example, https://example.com/auth/authorization.

The value of this property is used as authorization_endpoint property in the OpenID Provider Metadata.

directAuthorizationEndpointEnabled

boolean

The flag to indicate whether the direct authorization endpoint is enabled or not.

The path of the endpoint is /api/auth/authorization/direct/service-api-key.

supportedUiLocales

string[]

UI locales that the service supports.

Each element is a language tag defined in RFC 5646. For example, en-US and ja-JP.

The value of this property is used as ui_locales_supported property in the OpenID Provider Metadata.

supportedDisplays

enum<string>[]

Values of display request parameter that service supports.

The value of this property is used as display_values_supported property in the Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

The display mode which the client application requests by display request parameter. When the authorization request does not have display request parameter, PAGE is set as the default value.

It is ensured that the value of display is one of the supported display modes which are specified by supportedDisplays configuration parameter of the service. If the display mode specified by the authorization request is not supported, an error is raised.

Values for this property correspond to the values listed in "OpenID Connect Core 1.0, 3.1.2.1. Authentication Request, display".

Available options:

PAGE,

POPUP,

TOUCH,

WAP

pkceRequired

boolean

The flag to indicate whether the use of Proof Key for Code Exchange (PKCE) is always required for authorization requests by Authorization Code Flow.

If true, code_challenge request parameter is always required for authorization requests using Authorization Code Flow.

See RFC 7636 (Proof Key for Code Exchange by OAuth Public Clients) for details about code_challenge request parameter.

pkceS256Required

boolean

The flag to indicate whether S256 is always required as the code challenge method whenever PKCE (RFC 7636) is used.

If this flag is set to true, code_challenge_method=S256 must be included in the authorization request whenever it includes the code_challenge request parameter. Neither omission of the code_challenge_method request parameter nor use of plain (code_challenge_method=plain) is allowed.

authorizationResponseDuration

integer<int64>

The duration of authorization response JWTs in seconds.

Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM) defines new values for the response_mode request parameter. They are query.jwt, fragment.jwt, form_post.jwt and jwt. If one of them is specified as the response mode, response parameters from the authorization endpoint will be packed into a JWT. This property is used to compute the value of the exp claim of the JWT.

tokenEndpoint

string<uri>

The token endpoint of the service.

A URL that starts with https:// and has not fragment component. For example, https://example.com/auth/token.

The value of this property is used as token_endpoint property in the OpenID Provider Metadata.

directTokenEndpointEnabled

boolean

The flag to indicate whether the direct token endpoint is enabled or not. The path of the endpoint is /api/auth/token/direct/service-api-key.

supportedTokenAuthMethods

enum<string>[]

Client authentication methods supported by the token endpoint of the service.

The value of this property is used as token_endpoint_auth_methods_supports property in the OpenID Provider Metadata.

The client authentication method that the client application declares that it uses at the token endpoint. This property corresponds to token_endpoint_auth_method in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

Available options:

NONE,

CLIENT_SECRET_BASIC,

CLIENT_SECRET_POST,

CLIENT_SECRET_JWT,

PRIVATE_KEY_JWT,

TLS_CLIENT_AUTH,

SELF_SIGNED_TLS_CLIENT_AUTH

missingClientIdAllowed

boolean

The flag to indicate token requests from public clients without the client_id request parameter are allowed when the client can be guessed from authorization_code or refresh_token.

This flag should not be set unless you have special reasons.

revocationEndpoint

string<uri>

The revocation endpoint of the service.

A URL that starts with https://. For example, https://example.com/auth/revocation.

directRevocationEndpointEnabled

boolean

The flag to indicate whether the direct revocation endpoint is enabled or not. The URL of the endpoint is /api/auth/revocation/direct/service-api-key.

supportedRevocationAuthMethods

enum<string>[]

Client authentication methods supported at the revocation endpoint.

Available options:

NONE,

CLIENT_SECRET_BASIC,

CLIENT_SECRET_POST,

CLIENT_SECRET_JWT,

PRIVATE_KEY_JWT,

TLS_CLIENT_AUTH,

SELF_SIGNED_TLS_CLIENT_AUTH

introspectionEndpoint

string<uri>

The URI of the introspection endpoint.

directIntrospectionEndpointEnabled

boolean

The flag to indicate whether the direct userinfo endpoint is enabled or not. The path of the endpoint is /api/auth/userinfo/direct/{serviceApiKey}.

supportedIntrospectionAuthMethods

enum<string>[]

Client authentication methods supported at the introspection endpoint.

Available options:

NONE,

CLIENT_SECRET_BASIC,

CLIENT_SECRET_POST,

CLIENT_SECRET_JWT,

PRIVATE_KEY_JWT,

TLS_CLIENT_AUTH,

SELF_SIGNED_TLS_CLIENT_AUTH

pushedAuthReqEndpoint

string<uri>

The URI of the pushed authorization request endpoint.

This property corresponds to the pushed_authorization_request_endpoint metadata defined in "5. Authorization Server Metadata" of OAuth 2.0 Pushed Authorization Requests.

pushedAuthReqDuration

integer<int64>

The duration of pushed authorization requests in seconds.

OAuth 2.0 Pushed Authorization Requests defines an endpoint (called "pushed authorization request endpoint") which client applications can register authorization requests into and get corresponding URIs (called "request URIs") from. The issued URIs represent the registered authorization requests. The client applications can use the URIs as the value of the request_uri request parameter in an authorization request.

The property represents the duration of registered authorization requests and is used as the value of the expires_in parameter in responses from the pushed authorization request endpoint.

parRequired

boolean

The flag to indicate whether this service requires that clients use the pushed authorization request endpoint.

This property corresponds to the require_pushed_authorization_requests server metadata defined in OAuth 2.0 Pushed Authorization Requests.

requestObjectRequired

boolean

The flag to indicate whether this service requires that authorization requests always utilize a request object by using either request or request_uri request parameter.

If this flag is set to true and the value of traditionalRequestObjectProcessingApplied is false, the value of require_signed_request_object server metadata of this service is reported as true in the discovery document. The metadata is defined in JAR (JWT Secured Authorization Request). That require_signed_request_object is true means that authorization requests which don't conform to the JAR specification are rejected.

traditionalRequestObjectProcessingApplied

boolean

The flag to indicate whether a request object is processed based on rules defined in OpenID Connect Core 1.0 or JAR (JWT Secured Authorization Request).

Differences between rules in OpenID Connect Core 1.0 and ones in JAR are as follows.

JAR requires that a request object be always -signed.
JAR does not allow request parameters outside a request object to be referred to.
OIDC Core 1.0 requires that response_type request parameter exist outside a request object even if the request object includes the request parameter.
OIDC Core 1.0 requires that scope request parameter exist outside a request object if the authorization request is an
OIDC request even if the request object includes the request parameter.

If this flag is set to false and the value of requestObjectRequired is true, the value of require_signed_request_object server metadata of this service is reported as true in the discovery document. The metadata is defined in JAR (JWT Secured Authorization Request). That require_signed_request_object is true means that authorization requests which don't conform to the JAR specification are rejected.

mutualTlsValidatePkiCertChain

boolean

The flag to indicate whether this service validates certificate chains during PKI-based client mutual TLS authentication.

trustedRootCertificates

string[]

The list of root certificates trusted by this service for PKI-based client mutual TLS authentication.

mtlsEndpointAliases

object[]

The MTLS endpoint aliases.

This property corresponds to the mtls_endpoint_aliases metadata defined in "5. Metadata for Mutual TLS Endpoint Aliases" of OAuth 2.0 Mutual TLS Client Authentication and Certificate-Bound Access Tokens.

The aliases will be embedded in the response from the discovery endpoint like the following.

{
  ......,
  "mtls_endpoint_aliases": {
    "token_endpoint":         "https://mtls.example.com/token",
    "revocation_endpoint":    "https://mtls.example.com/revo",
    "introspection_endpoint": "https://mtls.example.com/introspect"
  }
}

Show child attributes

accessTokenType

string

The access token type.

This value is used as the value of token_type property in access token responses. If this service complies with RFC 6750, the value of this property should be Bearer.

See RFC 6749 (OAuth 2.0), 7.1. Access Token Types for details.

tlsClientCertificateBoundAccessTokens

boolean

The flag to indicate whether this service supports issuing TLS client certificate bound access tokens.

accessTokenDuration

integer<int64>

The duration of access tokens in seconds. This value is used as the value of expires_in property in access token responses. expires_in is defined RFC 6749, 5.1. Successful Response.

singleAccessTokenPerSubject

boolean

The flag to indicate whether the number of access tokens per subject (and per client) is at most one or can be more.

If true, an attempt to issue a new access token invalidates existing access tokens that are associated with 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 Client Credentials 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 setting item is true or false.

accessTokenSignAlg

enum<string>

The signature algorithm for JWT. This value is represented on 'alg' attribute of the header of JWT.

it's semantics depends upon where is this defined, for instance:

as service accessTokenSignAlg value, it defines that access token are JWT and the algorithm used to sign it. Check your KB article.
as client authorizationSignAlg value, it represents the signature algorithm used when creating a JARM response.
or as client requestSignAlg value, it specifies which is the expected signature used by client on a Request Object.

Available options:

NONE,

HS256,

HS384,

HS512,

RS256,

RS384,

RS512,

ES256,

ES384,

ES512,

PS256,

PS384,

PS512,

ES256K,

EdDSA

accessTokenSignatureKeyId

string

The key ID to identify a JWK used for signing access tokens.

A JWK Set can be registered as a property of a service. A JWK Set can contain 0 or more JWKs. Authlete Server has to pick up one JWK for signing from the JWK Set when it generates a JWT-based access token. Authlete Server searches the registered JWK Set for a JWK which satisfies conditions for access token signature. If the number of JWK candidates which satisfy the conditions is 1, there is no problem. On the other hand, if there exist multiple candidates, a Key ID is needed to be specified so that Authlete Server can pick up one JWK from among the JWK candidates.

refreshTokenDuration

integer<int64>

The duration of refresh tokens in seconds. The related specifications have no requirements on refresh token duration, but Authlete sets expiration for refresh tokens.

refreshTokenDurationKept

boolean

The flag to indicate whether the remaining duration of the used refresh token is taken over to the newly issued refresh token.

refreshTokenDurationReset

boolean

The flag which indicates whether duration of refresh tokens are reset when they are used even if the refreshTokenKept property of this service set to is true (= even if "Refresh Token Continuous Use" is "Kept").

This flag has no effect when the refreshTokenKept property is set to false. In other words, if this service issues a new refresh token on every refresh token request, the refresh token will have fresh duration (unless refreshTokenDurationKept is set to true) and this refreshTokenDurationReset property is not referenced.

refreshTokenKept

boolean

The flag to indicate whether a refresh token remains unchanged or gets renewed after its use.

If true, a refresh token used to get a new access token remains valid after its use. Otherwise, if false, a refresh token is invalidated after its use and a new refresh token is issued.

See RFC 6749 6. Refreshing an Access Token, as to how to get a new access token using a refresh token.

supportedScopes

object[]

Scopes supported by the service.

Authlete strongly recommends that the service register at least the following scopes.

Name	Description
openid	A permission to get an ID token of an end-user. The `openid` scope appears in OpenID Connect Core 1.0, 3.1.2.1. Authentication Request, scope. Without this scope, Authlete does not allow `response_type` request parameter to have values other than code and token.
profile	A permission to get information about `name`, `family_name`, `given_name`, `middle_name`, `nickname`, `preferred_username`, `profile`, `picture`, `website`, `gender`, `birthdate`, `zoneinfo`, `locale` and `updated_at` from the user info endpoint. See OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values for details.
email	A permission to get information about `email` and `email_verified` from the user info endpoint. See OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values for details.
address	A permission to get information about address from the user info endpoint. See OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values and 5.1.1. Address Claim for details.
phone	A permission to get information about `phone_number` and `phone_number_verified` from the user info endpoint. See OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values for details.
offline_access	A permission to get information from the user info endpoint even when the end-user is not present. See OpenID Connect Core 1.0, 11. Offline Access for details.

The value of this property is used as scopes_supported property in the OpenID Provider Metadata.

Show child attributes

scopeRequired

boolean

The flag to indicate whether requests that request no scope are rejected or not.

When a request has no explicit scope parameter and the service's pre-defined default scope set is empty, the authorization server regards the request requests no scope. When this flag is set to true, requests that request no scope are rejected.

The requirement below excerpted from RFC 6749 Section 3.3 does not explicitly mention the case where the default scope set is empty.

If the client omits the scope parameter when requesting authorization, the authorization server MUST either process the request using a pre-defined default value or fail the request indicating an invalid scope.

However, if you interpret "the default scope set exists but is empty" as "the default scope set does not exist" and want to strictly conform to the requirement above, this flag has to be true.

idTokenDuration

integer<int64>

'The duration of ID tokens in seconds. This value is used to calculate the value of exp claim in an ID token.'

allowableClockSkew

integer<int32>

The allowable clock skew between the server and clients in seconds.

The clock skew is taken into consideration when time-related claims in a JWT (e.g. exp, iat, nbf) are verified.

supportedClaimTypes

enum<string>[]

Claim types supported by the service. Valid values are listed in Claim Type. Note that Authlete currently doesn't provide any API to help implementations for AGGREGATED and DISTRIBUTED.

The value of this property is used as claim_types_supported property in the OpenID Provider Metadata.

Available options:

NORMAL,

AGGREGATED,

DISTRIBUTED

supportedClaimLocales

string[]

Claim locales that the service supports. Each element is a language tag defined in RFC 5646. For example, en-US and ja-JP. See OpenID Connect Core 1.0, 5.2. Languages and Scripts for details.

The value of this property is used as claims_locales_supported property in the OpenID Provider Metadata.

supportedClaims

string[]

Claim names that the service supports. The standard claim names listed in OpenID Connect Core 1.0, 5.1. Standard Claim should be supported. The following is the list of standard claims.

sub
name
given_name
family_name
middle_name
nickname
preferred_username
profile
picture
website
email
email_verified
gender
birthdate
zoneinfo
locale
phone_number
phone_number_verified
address
updated_at

The value of this property is used as claims_supported property in the OpenID Provider Metadata.

The service may support its original claim names. See OpenID Connect Core 1.0, 5.1.2. Additional Claims.

claimShortcutRestrictive

boolean

The flag indicating whether claims specified by shortcut scopes (e.g. profile) are included in the issued ID token only when no access token is issued.

To strictly conform to the description below excerpted from OpenID Connect Core 1.0 Section 5.4, this flag has to be true.

The Claims requested by the profile, email, address, and phone scope values are returned from the UserInfo Endpoint, as described in Section 5.3.2, when a response_type value is used that results in an Access Token being issued. However, when no Access Token is issued (which is the case for the response_type value id_token), the resulting Claims are returned in the ID Token.

jwksUri

string<uri>

The URL of the service's JSON Web Key Set document. For example, http://example.com/auth/jwks.

Client applications accesses this URL (1) to get the public key of the service to validate the signature of an ID token issued by the service and (2) to get the public key of the service to encrypt an request object of the client application. See OpenID Connect Core 1.0, 10. Signatures and Encryption for details.

The value of this property is used as jwks_uri property in the OpenID Provider Metadata.

directJwksEndpointEnabled

boolean

'The flag to indicate whether the direct jwks endpoint is enabled or not. The path of the endpoint is /api/service/jwks/get/direct/service-api-key. '

jwks

string

The content of the service's JSON Web Key Set document.

If this property is not null in a /service/create request or a /service/update request, Authlete hosts the content in the database. This property must not be null and must contain pairs of public/private keys if the service wants to support asymmetric signatures for ID tokens and asymmetric encryption for request objects. See OpenID Connect Core 1.0, 10. Signatures and Encryption for details.

idTokenSignatureKeyId

string

The key ID to identify a JWK used for ID token signature using an asymmetric key.

A JWK Set can be registered as a property of a Service. A JWK Set can contain 0 or more JWKs (See RFC 7517 for details about JWK). Authlete Server has to pick up one JWK for signature from the JWK Set when it generates an ID token and signature using an asymmetric key is required. Authlete Server searches the registered JWK Set for a JWK which satisfies conditions for ID token signature. If the number of JWK candidates which satisfy the conditions is 1, there is no problem. On the other hand, if there exist multiple candidates, a Key ID is needed to be specified so that Authlete Server can pick up one JWK from among the JWK candidates.

This idTokenSignatureKeyId property exists for the purpose described above. For key rotation (OpenID Connect Core 1.0, 10.1.1. Rotation of Asymmetric Signing Keys), this mechanism is needed.

userInfoSignatureKeyId

string

The key ID to identify a JWK used for user info signature using an asymmetric key.

A JWK Set can be registered as a property of a Service. A JWK Set can contain 0 or more JWKs (See RFC 7517 for details about JWK). Authlete Server has to pick up one JWK for signature from the JWK Set when it is required to sign user info (which is returned from userinfo endpoint) using an asymmetric key. Authlete Server searches the registered JWK Set for a JWK which satisfies conditions for user info signature. If the number of JWK candidates which satisfy the conditions is 1, there is no problem. On the other hand, if there exist multiple candidates, a Key ID is needed to be specified so that Authlete Server can pick up one JWK from among the JWK candidates.

This userInfoSignatureKeyId property exists for the purpose described above. For key rotation (OpenID Connect Core 1.0, 10.1.1. Rotation of Asymmetric Signing Keys), this mechanism is needed.

authorizationSignatureKeyId

string

The key ID to identify a JWK used for signing authorization responses using an asymmetric key.

Authlete Server searches the JWK Set for a JWK which satisfies conditions for authorization response signature. If the number of JWK candidates which satisfy the conditions is 1, there is no problem. On the other hand, if there exist multiple candidates, a Key ID is needed to be specified so that Authlete Server can pick up one JWK from among the JWK candidates. This property exists to specify the key ID.

userInfoEndpoint

string<uri>

The user info endpoint of the service. A URL that starts with https://. For example, https://example.com/auth/userinfo.

The value of this property is used as userinfo_endpoint property in the OpenID Provider Metadata.

directUserInfoEndpointEnabled

boolean

The flag to indicate whether the direct userinfo endpoint is enabled or not. The path of the endpoint is /api/auth/userinfo/direct/service-api-key.

dynamicRegistrationSupported

boolean

The boolean flag which indicates whether the OAuth 2.0 Dynamic Client Registration Protocol is supported.

registrationEndpoint

string<uri>

The registration endpoint of the service. A URL that starts with https://. For example, https://example.com/auth/registration.

The value of this property is used as registration_endpoint property in the OpenID Provider Metadata.

registrationManagementEndpoint

string<uri>

The URI of the registration management endpoint. If dynamic client registration is supported, and this is set, this URI will be used as the basis of the client's management endpoint by appending /clientid}/ to it as a path element. If this is unset, the value of registrationEndpoint will be used as the URI base instead.

policyUri

string<uri>

The URL of the "Policy" of the service.

The value of this property is used as op_policy_uri property in the OpenID Provider Metadata.

tosUri

string<uri>

The URL of the "Terms Of Service" of the service.

The value of this property is used as op_tos_uri property in the OpenID Provider Metadata.

serviceDocumentation

string<uri>

The URL of a page where documents for developers can be found.

The value of this property is used as service_documentation property in the OpenID Provider Metadata.

backchannelAuthenticationEndpoint

string<uri>

The URI of backchannel authentication endpoint, which is defined in the specification of CIBA (Client Initiated Backchannel Authentication).

supportedBackchannelTokenDeliveryModes

enum<string>[]

The supported backchannel token delivery modes. This property corresponds to the backchannel_token_delivery_modes_supported metadata.

Backchannel token delivery modes are defined in the specification of CIBA (Client Initiated Backchannel Authentication).

Available options:

PING,

POLL,

PUSH

backchannelAuthReqIdDuration

integer<int32>

The duration of backchannel authentication request IDs 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.

backchannelPollingInterval

integer<int32>

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.

backchannelUserCodeParameterSupported

boolean

The boolean flag which indicates whether the user_code request parameter is supported at the backchannel authentication endpoint. This property corresponds to the backchannel_user_code_parameter_supported metadata.

backchannelBindingMessageRequiredInFapi

boolean

The flag to indicate whether the binding_message request parameter is always required whenever a backchannel authentication request is judged as a request for Financial-grade API.

The FAPI-CIBA profile requires that the authorization server "shall ensure unique authorization context exists in the authorization request or require a binding_message in the authorization request" (FAPI-CIBA, 5.2.2, 2). The simplest way to fulfill this requirement is to set this property to true.

If this property is set to false, the binding_message request parameter remains optional even in FAPI context, but in exchange, your authorization server must implement a custom mechanism that ensures each backchannel authentication request has unique context.

deviceAuthorizationEndpoint

string<uri>

The URI of the device authorization endpoint.

Device authorization endpoint is defined in the specification of OAuth 2.0 Device Authorization Grant.

deviceVerificationUri

string<uri>

The verification URI for the device flow. This URI is used as the value of the verification_uri parameter in responses from the device authorization endpoint.

deviceVerificationUriComplete

string<uri>

The verification URI for the device flow with a placeholder for a user code. This URI is used to build the value of the verification_uri_complete parameter in responses from the device authorization endpoint.

It is expected that the URI contains a fixed string USER_CODE somewhere as a placeholder for a user code. For example, like the following.

https://example.com/device?user\_code=USER\_CODE

The fixed string is replaced with an actual user code when Authlete builds a verification URI with a user code for the verification_uri_complete parameter.

If this URI is not set, the verification_uri_complete parameter won't appear in device authorization responses.

deviceFlowCodeDuration

integer<int32>

The duration of device verification codes and end-user verification codes issued from the device authorization endpoint in seconds. This is used as the value of the expires_in property in responses from the device authorization endpoint.

deviceFlowPollingInterval

integer<int32>

The minimum interval between polling requests to the token endpoint from client applications in seconds in device flow. This is used as the value of the interval property in responses from the device authorization endpoint.

userCodeCharset

enum<string>

The character set for end-user verification codes (user_code) for Device Flow.

Available options:

BASE20,

NUMERIC

userCodeLength

integer<int32>

The length of end-user verification codes (user_code) for Device Flow.

supportedTrustFrameworks

string[]

Trust frameworks supported by this service. This corresponds to the trust_frameworks_supported metadata.

supportedEvidence

string[]

Evidence supported by this service. This corresponds to the evidence_supported metadata.

supportedIdentityDocuments

string[]

Identity documents supported by this service. This corresponds to the id_documents_supported metadata.

supportedVerificationMethods

string[]

Verification methods supported by this service. This corresponds to the id_documents_verification_methods_supported metadata.

supportedVerifiedClaims

string[]

Verified claims supported by this service. This corresponds to the claims_in_verified_claims_supported metadata.

verifiedClaimsValidationSchemaSet

enum<string>

OIDC4IDA / verifiedClaimsValidationSchemaSet

Available options:

standard,

standard+id_document

attributes

object[]

The attributes of this service.

Show child attributes

nbfOptional

boolean

The flag indicating whether the nbf claim in the request object is optional even when the authorization request is regarded as a FAPI-Part2 request.

The final version of Financial-grade API was approved in January, 2021. The Part 2 of the final version has new requirements on lifetime of request objects. They require that request objects contain an nbf claim and the lifetime computed by exp - nbf be no longer than 60 minutes.

Therefore, when an authorization request is regarded as a FAPI-Part2 request, the request object used in the authorization request must contain an nbf claim. Otherwise, the authorization server rejects the authorization request.

When this flag is true, the nbf claim is treated as an optional claim even when the authorization request is regarded as a FAPI-Part2 request. That is, the authorization server does not perform the validation on lifetime of the request object.

Skipping the validation is a violation of the FAPI specification. The reason why this flag has been prepared nevertheless is that the new requirements (which do not exist in the Implementer's Draft 2 released in October, 2018) have big impacts on deployed implementations of client applications and Authlete thinks there should be a mechanism whereby to make the migration from ID2 to Final smooth without breaking live systems.

issSuppressed

boolean

The flag indicating whether generation of the iss response parameter is suppressed.

"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.

When this flag is true, the authorization server does not include the iss response parameter in authorization responses. By turning this flag on and off, developers of client applications can experiment the mix-up attack and the effect of the iss response parameter.

Note that this flag should not be true in production environment unless there are special reasons for it.

supportedCustomClientMetadata

string[]

custom client metadata supported by this service.

Standard specifications define client metadata as necessary. The following are such examples.

Standard client metadata included in Client Registration Request and Client Update Request (cf. OIDC DynReg, RFC 7591 and RFC 7592) are, if supported by Authlete, stored into Authlete database. On the other hand, unrecognized client metadata are discarded.

By listing up custom client metadata in advance by using this property (supportedCustomClientMetadata), Authlete can recognize them and stores their values into the database. The stored custom client metadata values can be referenced by customMetadata.

tokenExpirationLinked

boolean

The flag indicating whether the expiration date of an access token never exceeds that of the corresponding refresh token.

When a new access token is issued by a refresh token request (= a token request with grant_type=refresh_token), the expiration date of the access token may exceed the expiration date of the corresponding refresh token. This behavior itself is not wrong and may happen when refreshTokenKept is true and/or when refreshTokenDurationKept is true.

When this flag is true, the expiration date of an access token never exceeds that of the corresponding refresh token regardless of the calculated duration based on other settings such as accessTokenDuration, accessTokenDuration in extension and access_token.duration scope attribute.

It is technically possible to set a value which is bigger than the duration of refresh tokens as the duration of access tokens although it is strange. In the case, the duration of an access token becomes longer than the duration of the refresh token which is issued together with the access token. Even if the duration values are configured so, if this flag is true, the expiration date of the access token does not exceed that of the refresh token. That is, the duration of the access token will be shortened, and as a result, the access token and the refresh token will have the same expiration date.

frontChannelRequestObjectEncryptionRequired

boolean

The flag indicating whether encryption of request object is required when the request object is passed through the front channel.

This flag does not affect the processing of request objects at the Pushed Authorization Request Endpoint, which is defined in OAuth 2.0 Pushed Authorization Requests. Unecrypted request objects are accepted at the endpoint even if this flag is true.

This flag does not indicate whether a request object is always required. There is a different flag, requestObjectRequired, for the purpose. See the description of requestObjectRequired for details.

Even if this flag is false, encryption of request object is required if the frontChannelRequestObjectEncryptionRequired flag of the client is true.

requestObjectEncryptionAlgMatchRequired

boolean

The flag indicating whether the JWE alg of encrypted request object must match the request_object_encryption_alg client metadata of the client that has sent the request object.

The request_object_encryption_alg client metadata itself is defined in OpenID Connect Dynamic Client Registration 1.0 as follows.

request_object_encryption_alg

OPTIONAL. JWE [JWE] alg algorithm [JWA] the RP is declaring that it may use for encrypting Request Objects sent to the OP. This parameter SHOULD be included when symmetric encryption will be used, since this signals to the OP that a client_secret value needs to be returned from which the symmetric key will be derived, that might not otherwise be returned. The RP MAY still use other supported encryption algorithms or send unencrypted Request Objects, even when this parameter is present. If both signing and encryption are requested, the Request Object will be signed then encrypted, with the result being a Nested JWT, as defined in [JWT]. The default, if omitted, is that the RP is not declaring whether it might encrypt any Request Objects.

The point here is "The RP MAY still use other supported encryption algorithms or send unencrypted Request Objects, even when this parameter is present."

The Client's property that represents the client metadata is requestEncryptionAlg. See the description of requestEncryptionAlg for details.

Even if this flag is false, the match is required if the requestObjectEncryptionAlgMatchRequired flag of the client is true.

requestObjectEncryptionEncMatchRequired

boolean

The flag indicating whether the JWE enc of encrypted request object must match the request_object_encryption_enc client metadata of the client that has sent the request object.

The request_object_encryption_enc client metadata itself is defined in OpenID Connect Dynamic Client Registration 1.0 as follows.

request_object_encryption_enc

OPTIONAL. JWE enc algorithm [JWA] the RP is declaring that it may use for encrypting Request Objects sent to the OP. If request_object_encryption_alg is specified, the default for this value is A128CBC-HS256. When request_object_encryption_enc is included, request_object_encryption_alg MUST also be provided.

The Client's property that represents the client metadata is requestEncryptionEnc. See the description of requestEncryptionEnc for details.

Even if this flag is false, the match is required if the requestObjectEncryptionEncMatchRequired flag is true.

hsmEnabled

boolean

The flag indicating whether HSM (Hardware Security Module) support is enabled for this service.

When this flag is false, keys managed in HSMs are not used even if they exist. In addition, /api/hsk/* APIs reject all requests.

Even if this flag is true, HSM-related features do not work if the configuration of the Authlete server you are using does not support HSM.

hsks

object[]

The information about keys managed on HSMs (Hardware Security Modules).

This hsks property is output only, meaning that hsks in requests to /api/service/create API and /api/service/update API do not have any effect. The contents of this property is controlled only by /api/hsk/* APIs.

Show child attributes

grantManagementEndpoint

string

The URL of the grant management endpoint.

grantManagementActionRequired

boolean

The flag indicating whether every authorization request (and any request serving as an authorization request such as CIBA backchannel authentication request and device authorization request) must include the grant_management_action request parameter.

This property corresponds to the grant_management_action_required server metadata defined in Grant Management for OAuth 2.0.

Note that setting true to this property will result in blocking all public clients because the specification requires that grant management be usable only by confidential clients for security reasons.

unauthorizedOnClientConfigSupported

boolean

The flag indicating whether Authlete's /api/client/registration API uses UNAUTHORIZED as a value of the action response parameter when appropriate.

The UNAUTHORIZED enum value was initially not defined as a possible value of the action parameter in an /api/client/registration API response. This means that implementations of client configuration endpoint were not able to conform to RFC 7592 strictly.

For backward compatibility (to avoid breaking running systems), Authlete's /api/client/registration API does not return the UNAUTHORIZED enum value if this flag is not turned on.

The steps an existing implementation of client configuration endpoint has to do in order to conform to the requirement related to "401 Unauthorized" are as follows.

Update the Authlete library (e.g. authlete-java-common) your system is using.
Update your implementation of client configuration endpoint so that it can handle the UNAUTHORIZED action.
Turn on this unauthorizedOnClientConfigSupported flag.

dcrScopeUsedAsRequestable

boolean

The flag indicating whether the scope request parameter in dynamic client registration and update requests (RFC 7591 and RFC 7592) is used as scopes that the client can request.

Limiting the range of scopes that a client can request is achieved by listing scopes in the client.extension.requestableScopes property and setting the client.extension.requestableScopesEnabled property to true. This feature is called "requestable scopes".

This property affects behaviors of /api/client/registration and other family APIs.

endSessionEndpoint

string<uri>

The endpoint for clients ending the sessions.

A URL that starts with https:// and has no fragment component. For example, https://example.com/auth/endSession.

The value of this property is used as end_session_endpoint property in the OpenID Provider Metadata.

loopbackRedirectionUriVariable

boolean

The flag indicating whether the port number component of redirection URIs can be variable when the host component indicates loopback.

When this flag is true, if the host component of a redirection URI specified in an authorization request indicates 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.

8.3. Loopback Redirect Considerations of RFC 8252 states as follows.

While redirect URIs using localhost (i.e., "http://localhost:{port}/{path}") function similarly to loopback IP redirects described in Section 7.3, the use of localhost is NOT RECOMMENDED. Specifying a redirect URI with the loopback IP literal rather than localhost avoids inadvertently listening on network interfaces other than the loopback interface. It is also less susceptible to client-side firewalls and misconfigured host name resolution on the user's device.

However, Authlete allows the port number component to be variable in the case of localhost, too. It is left to client applications whether they use localhost or a literal loopback IP address (127.0.0.1 for IPv4 or ::1 for IPv6).

Section 7.3 and Section 8.3 of RFC 8252 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.

requestObjectAudienceChecked

boolean

The flag indicating whether Authlete checks whether the aud claim of request objects matches the issuer identifier of this service.

Section 6.1. Passing a Request Object by Value of OpenID Connect Core 1.0 has the following statement.

The aud value SHOULD be or include the OP's Issuer Identifier URL.

Likewise, Section 4. Request Object of RFC 9101 (The OAuth 2.0 Authorization Framework: JWT-Secured Authorization Request (JAR)) has the following statement.

The value of aud should be the value of the authorization server (AS) issuer, as defined in RFC 8414.

As excerpted above, validation on the aud claim of request objects is optional. However, if this flag is turned on, Authlete checks whether the aud claim of request objects matches the issuer identifier of this service and raises an error if they are different.

accessTokenForExternalAttachmentEmbedded

boolean

The flag indicating whether Authlete generates access tokens for external attachments and embeds them in ID tokens and userinfo responses.

authorityHints

string[]

Identifiers of entities that can issue entity statements for this service. This property corresponds to the authority_hints property that appears in a self-signed entity statement that is defined in OpenID Connect Federation 1.0.

federationEnabled

boolean

flag indicating whether this service supports OpenID Connect Federation 1

federationJwks

string

JWK Set document containing keys that are used to sign (1) self-signed entity statement of this service and (2) the response from signed_jwks_uri.

federationSignatureKeyId

string

A key ID to identify a JWK used to sign the entity configuration and the signed JWK Set.

federationConfigurationDuration

integer

The duration of the entity configuration in seconds.

federationRegistrationEndpoint

string

The URI of the federation registration endpoint. This property corresponds to the federation_registration_endpoint server metadata that is defined in OpenID Connect Federation 1.0.

organizationName

string

The human-readable name representing the organization that operates this service. This property corresponds to the organization_name server metadata that is defined in OpenID Connect Federation 1.0.

predefinedTransformedClaims

string

The transformed claims predefined by this service in JSON format. This property corresponds to the transformed_claims_predefined server metadata.

refreshTokenIdempotent

boolean

flag indicating whether refresh token requests with the same refresh token can be made multiple times in quick succession and they can obtain the same renewed refresh token within the short period.

signedJwksUri

string

The URI of the endpoint that returns this service's JWK Set document in the JWT format. This property corresponds to the signed_jwks_uri server metadata defined in OpenID Connect Federation 1.0.

supportedAttachments

enum<string>[]

Supported attachment types. This property corresponds to the {@code attachments_supported} server metadata which was added by the third implementer's draft of OpenID Connect for Identity Assurance 1.0.

Supported attachment types. This property corresponds to the attachments_supported server metadata which was added by the third implementer's draft of OpenID Connect for Identity Assurance 1.0.

Available options:

EMBEDDED,

EXTERNAL

supportedDigestAlgorithms

string[]

Supported algorithms 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.

supportedDocuments

string[]

Document types supported by this service. This property corresponds to the documents_supported server metadata.

supportedDocumentsMethods

string[]

validation and verification processes supported by this service. This property corresponds to the documents_methods_supported server metadata.

The third implementer's draft of OpenID Connect for Identity Assurance 1.0 renamed the id_documents_verification_methods_supported server metadata to documents_methods_supported.

supportedDocumentsValidationMethods

string[]

Document validation methods supported by this service. This property corresponds to the documents_validation_methods_supported server metadata which was added by the third implementer's draft of <a href= OpenID Connect for Identity Assurance 1.0

supportedDocumentsVerificationMethods

string[]

Document verification methods supported by this service. This property corresponds to the documents_verification_methods_supported server metadata which was added by the third implementer's draft of OpenID Connect for Identity Assurance 1.0

supportedElectronicRecords

string[]

Electronic record types supported by this service. This property corresponds to the electronic_records_supported server metadata which was added by the third implementer's draft of OpenID Connect for Identity Assurance 1.0

supportedClientRegistrationTypes

enum<string>[]

Values for the client_registration_types RP metadata and the client_registration_types_supported OP metadata that are defined in OpenID Connect Federation 1.0.

Available options:

AUTOMATIC,

EXPLICIT

tokenExchangeByIdentifiableClientsOnly

boolean

The flag indicating whether to prohibit unidentifiable clients from making token exchange requests.

tokenExchangeByConfidentialClientsOnly

boolean

The flag indicating whether to prohibit public clients from making token exchange requests.

tokenExchangeByPermittedClientsOnly

boolean

The flag indicating whether to prohibit clients that have no explicit permission from making token exchange requests.

tokenExchangeEncryptedJwtRejected

boolean

The flag indicating whether to reject token exchange requests which use encrypted JWTs as input tokens.

tokenExchangeUnsignedJwtRejected

boolean

The flag indicating whether to reject token exchange requests which use unsigned JWTs as input tokens.

jwtGrantByIdentifiableClientsOnly

boolean

The flag indicating whether to prohibit unidentifiable clients from using the grant type "urn:ietf:params:oauth:grant-type:jwt-bearer".

jwtGrantEncryptedJwtRejected

boolean

The flag indicating whether to reject token requests that use an encrypted JWT as an authorization grant with the grant type "urn:ietf:params:oauth:grant-type:jwt-bearer".

jwtGrantUnsignedJwtRejected

boolean

The flag indicating whether to reject token requests that use an unsigned JWT as an authorization grant with the grant type "urn:ietf:params:oauth:grant-type:jwt-bearer".

dcrDuplicateSoftwareIdBlocked

boolean

The flag indicating whether to block DCR (Dynamic Client Registration) requests whose "software_id" has already been used previously.

trustAnchors

object[]

The trust anchors that are referenced when this service resolves trust chains of relying parties.

If this property is empty, client registration fails regardless of whether its type is automatic or explicit. It means that OpenID Connect Federation 1.0 does not work.

Show child attributes

openidDroppedOnRefreshWithoutOfflineAccess

boolean

The flag indicating whether the openid scope should be dropped from scopes list assigned to access token issued when a refresh token grant is used.

supportedDocumentsCheckMethods

string[]

Supported document check methods. This property corresponds to the documents_check_methods_supported server metadata which was added by the fourth implementer's draft of OpenID Connect for Identity Assurance 1.0.

rsResponseSigned

boolean

The flag indicating whether this service signs responses from the resource server.

cnonceDuration

integer<int64>

The duration of c_nonce.

dpopNonceRequired

boolean

Whether to require DPoP proof JWTs to include the nonce claim whenever they are presented.

verifiableCredentialsEnabled

boolean

Get the flag indicating whether the feature of Verifiable Credentials for this service is enabled or not.

credentialJwksUri

string

The URL at which the JWK Set document of the credential issuer is exposed.

credentialOfferDuration

integer<int64>

The default duration of credential offers in seconds.

dpopNonceDuration

integer<int64>

The duration of nonce values for DPoP proof JWTs in seconds.

preAuthorizedGrantAnonymousAccessSupported

boolean

The flag indicating whether token requests using the pre-authorized code grant flow by unidentifiable clients are allowed.

credentialTransactionDuration

integer<int64>

The duration of transaction ID in seconds that may be issued as a result of a credential request or a batch credential request.

introspectionSignatureKeyId

string

The key ID of the key for signing introspection responses.

resourceSignatureKeyId

string

The key ID of the key for signing introspection responses.

userPinLength

integer<int32>

The default length of user PINs.

supportedPromptValues

enum<string>[]

The supported prompt values.

The prompt that the UI displayed to the end-user must satisfy as the minimum level. This value comes from prompt request parameter.

When the authorization request does not contain prompt request parameter, CONSENT is used as the default value.

See "OpenID Connect Core 1.0, 3.1.2.1. Authentication Request, prompt" for prompt request parameter.

Available options:

NONE,

LOGIN,

CONSENT,

SELECT_ACCOUNT

idTokenReissuable

boolean

The flag indicating whether to enable the feature of ID token reissuance in the refresh token flow.

credentialJwks

string

The JWK Set document containing private keys that are used to sign verifiable credentials.

fapiModes

enum<string>[]

FAPI modes for this service.

When the value of this property is not null, Authlete always processes requests to this service based on the specified FAPI modes if the FAPI feature is enabled in Authlete and the FAPI profile is supported by this service.

For instance, when this property is set to an array containing FAPI1_ADVANCED only, Authlete always processes requests to this service based on "Financial-grade API Security Profile 1.0 - Part 2: Advanced" if the FAPI feature is enabled in Authlete and the FAPI profile is supported by this service.

Available options:

FAPI1_ADVANCED,

FAPI1_BASELINE,

FAPI2_MESSAGE_SIGNING_AUTH_REQ,

FAPI2_MESSAGE_SIGNING_AUTH_RES,

FAPI2_MESSAGE_SIGNING_INTROSPECTION_RES,

FAPI2_SECURITY

credentialDuration

integer<int64>

The default duration of verifiable credentials in seconds.

credentialIssuerMetadata

object

Show child attributes

idTokenAudType

string

The type of the aud claim in ID tokens.

nativeSsoSupported

boolean

The flag to determine to support the OpenID Connect Native SSO for Mobile Apps 1.0 specification (a.k.a. "Native SSO").

If this property is not set to true, Native SSO-specific parameters will be ignored or treated as errors. For example, the device_sso scope will have no special meaning (Authlete will not embed the sid claim in the ID token), and the urn:openid:params:token-type:device-secret token type will be treated as unknown, resulting in an error.

This property corresponds to the native_sso_supported server metadata. If this property is set to true, "native_sso_supported":true will appear in the server metadata document (see OpenID Connect Discovery 1.0, Section 3. OpenID Provider Metadata; RFC 8414: OAuth 2.0 Authorization Server Metadata, Section 2. Authorization Server Metadata).

Delete requestable scopes Fail Authorization Request

⌘I

Guides

Authelte APIs

Process Authorization Request

Description

Authorizations

Path Parameters

Body

Response