From 99407fa9ad3ed2337d355458e6dbd9290f9e4d5d Mon Sep 17 00:00:00 2001 From: shariq Date: Thu, 5 Mar 2026 17:01:12 +0500 Subject: [PATCH] Add Mintlify accordion components to long API descriptions Wrap long endpoint descriptions in x-mint Accordion components so they are collapsible in the Mintlify API reference. Made-with: Cursor --- spec_next.yaml | 7946 +++++++++++++++++++++++++----------------------- 1 file changed, 4161 insertions(+), 3785 deletions(-) diff --git a/spec_next.yaml b/spec_next.yaml index 6ad9bb6..3abf630 100644 --- a/spec_next.yaml +++ b/spec_next.yaml @@ -2264,25 +2264,31 @@ paths: summary: Get Granted Scopes description: | Get the set of scopes that a user has granted to a client application. + x-mint: + metadata: + description: "Get the set of scopes that a user has granted to a client application." + content: | + + Possible values for `requestableScopes` parameter in the response from this API are as follows. - Possible values for `requestableScopes` parameter in the response from this API are as follows. + ## null - ## null + The user has not granted authorization to the client application in the past, or records about the + combination of the user and the client application have been deleted from Authlete's DB. - The user has not granted authorization to the client application in the past, or records about the - combination of the user and the client application have been deleted from Authlete's DB. + ## An empty set - ## An empty set + The user has granted authorization to the client application in the past, but no scopes are associated + with the authorization. - The user has granted authorization to the client application in the past, but no scopes are associated - with the authorization. + ## A set with at least one element - ## A set with at least one element + The user has granted authorization to the client application in the past and some scopes are associated + with the authorization. These scopes are returned. + Example: `[ "profile", "email" ]` + The subject parameter is required and must be provided as a query parameter. + - The user has granted authorization to the client application in the past and some scopes are associated - with the authorization. These scopes are returned. - Example: `[ "profile", "email" ]` - The subject parameter is required and must be provided as a query parameter. parameters: - in: path name: serviceId @@ -2582,472 +2588,478 @@ paths: description: | This API parses request parameters of an authorization request and returns necessary data for the authorization server implementation to process the authorization request further. - - 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. - ```java - @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](https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html). - 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. Note 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 sales@authlete.com - 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](https://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes) 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. - ```json + x-mint: + metadata: + description: "This API parses request parameters of an authorization request and returns necessary data for the authorization server implementation to process the authorization request further." + content: | + + 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. + ```java + @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) { - "name": "John Smith", - "email": "john@example.com", - "birthdate": "1974-05-06" + // 'parameters' is the entity body of the authorization request. + ...... } ``` - `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](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsLanguagesAndScripts) - 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](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) - 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](https://openid.net/specs/openid-connect-core-1_0.html#AdditionalClaims)) - and (2) that claim names may be followed by a language tag ([5.2. Claims Languages and Scripts](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsLanguagesAndScripts)). - Read the specification of [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) - 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](https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess)). - 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](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). - 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. + 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. - **[2] UI LOCALE** + ## INTERNAL_SERVER_ERROR - 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. + 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. - **[3] CLIENT INFORMATION** + 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 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. + --- + + 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](https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html). + 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. Note 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 sales@authlete.com + 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](https://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes) 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. + ```json + { + "name": "John Smith", + "email": "john@example.com", + "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](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsLanguagesAndScripts) + 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](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) + 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](https://openid.net/specs/openid-connect-core-1_0.html#AdditionalClaims)) + and (2) that claim names may be followed by a language tag ([5.2. Claims Languages and Scripts](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsLanguagesAndScripts)). + Read the specification of [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) + 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](https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess)). + 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](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). + 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 sales@authlete.com 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](https://authlete.github.io/authlete-java-common/com/authlete/common/dto/DynamicScope.html) + 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](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html). + See [8. Transaction-specific Purpose](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#rfc.section.8) + 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](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) 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`. + - **[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 sales@authlete.com 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](https://authlete.github.io/authlete-java-common/com/authlete/common/dto/DynamicScope.html) - 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](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html). - See [8. Transaction-specific Purpose](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#rfc.section.8) - 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](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) 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`. parameters: - in: path name: serviceId @@ -3157,100 +3169,106 @@ paths: description: | This API generates a content of an error authorization response that the authorization server implementation returns to the client application. + x-mint: + metadata: + description: "This API generates a content of an error authorization response that the authorization server implementation returns to the client application." + content: | + + This API is supposed to be called from within the implementation of the authorization endpoint of the service + in order to generate an error response to the client application. + The description of the `/auth/authorization` API describes the timing when this API should be called. + The response from `/auth/authorization/fail` API has some 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 authorization server 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. + 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 ticket is no longer valid (deleted + or expired) and that the reason of the invalidity was probably due to the end-user's too-delayed + response to the authorization UI. + 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. + 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 response to the client application must + be "302 Found" with Location header. + The parameter responseContent contains a redirect URI with (1) an authorization code, an ID token + and/or an access token (on success) or (2) an error code (on failure), 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 response to the client application must be 200 OK + with an HTML which triggers redirection by JavaScript. + This happens when the authorization request from the client application contained `response_mode=form_post`. + 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} + ``` + - This API is supposed to be called from within the implementation of the authorization endpoint of the service - in order to generate an error response to the client application. - The description of the `/auth/authorization` API describes the timing when this API should be called. - The response from `/auth/authorization/fail` API has some 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 authorization server 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. - 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 ticket is no longer valid (deleted - or expired) and that the reason of the invalidity was probably due to the end-user's too-delayed - response to the authorization UI. - 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. - 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 response to the client application must - be "302 Found" with Location header. - The parameter responseContent contains a redirect URI with (1) an authorization code, an ID token - and/or an access token (on success) or (2) an error code (on failure), 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 response to the client application must be 200 OK - with an HTML which triggers redirection by JavaScript. - This happens when the authorization request from the client application contained `response_mode=form_post`. - 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} - ``` parameters: - in: path name: serviceId @@ -3331,104 +3349,110 @@ paths: description: | This API parses request parameters of an authorization request and returns necessary data for the authorization server implementation to process the authorization request further. + x-mint: + metadata: + description: "This API parses request parameters of an authorization request and returns necessary data for the authorization server implementation to process the authorization request further." + content: | + + This API is supposed to be called from within the implementation of the authorization endpoint of + the service in order to generate a successful response to the client application. + The description of the `/auth/authorization` API describes the timing when this API should be called + and the meaning of request parameters. See [ISSUE] in `NO_INTERACTION`. + The response from `/auth/authorization/issue` API has some 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 authorization server 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". + 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 ticket is no longer valid (deleted + or expired) and that the reason of the invalidity was probably due to the end-user's too-delayed + response to the authorization UI. + The HTTP status of the response returned to the client application should be "400 Bad Request" + and the content type should be `application/json` although OAuth 2.0 specification does not mention + the format of the error response. + 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 response to the client application + should be "302 Found" with `Location` header. + The value of `responseContent` is a redirect URI which contains (1) an authorization code, an ID + token and/or an access token (on success) or (2) an error code (on failure), 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 response to the client application should + be "200 OK" with an HTML which triggers redirection by JavaScript. This happens when the authorization + request from the client contains `response_mode=form_post` request parameter. + The value of `responseContent` is an HTML which satisfies the requirements of `response_mode=form_post`, + 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 200 OK + Content-Type: text/html;charset=UTF-8 + Cache-Control: no-store + Pragma: no-cache + {responseContent} + ``` + - This API is supposed to be called from within the implementation of the authorization endpoint of - the service in order to generate a successful response to the client application. - The description of the `/auth/authorization` API describes the timing when this API should be called - and the meaning of request parameters. See [ISSUE] in `NO_INTERACTION`. - The response from `/auth/authorization/issue` API has some 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 authorization server 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". - 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 ticket is no longer valid (deleted - or expired) and that the reason of the invalidity was probably due to the end-user's too-delayed - response to the authorization UI. - The HTTP status of the response returned to the client application should be "400 Bad Request" - and the content type should be `application/json` although OAuth 2.0 specification does not mention - the format of the error response. - 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 response to the client application - should be "302 Found" with `Location` header. - The value of `responseContent` is a redirect URI which contains (1) an authorization code, an ID - token and/or an access token (on success) or (2) an error code (on failure), 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 response to the client application should - be "200 OK" with an HTML which triggers redirection by JavaScript. This happens when the authorization - request from the client contains `response_mode=form_post` request parameter. - The value of `responseContent` is an HTML which satisfies the requirements of `response_mode=form_post`, - 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 200 OK - Content-Type: text/html;charset=UTF-8 - Cache-Control: no-store - Pragma: no-cache - {responseContent} - ``` parameters: - in: path name: serviceId @@ -3593,393 +3617,399 @@ paths: description: | This API parses request parameters of an authorization request and returns necessary data for the authorization server implementation to process the authorization request further. + x-mint: + metadata: + description: "This API parses request parameters of an authorization request and returns necessary data for the authorization server implementation to process the authorization request further." + content: | + + This API is supposed to be called from with the implementation of the token endpoint of the service. + The endpoint implementation must extract the request parameters from the token request from the + client application and pass them as the value of parameters request parameter to Authlete's `/auth/token` API. + The value of parameters is the entire entity body (which is formatted in `application/x-www-form-urlencoded`) + of the token request. + In addition, if the token endpoint of the authorization server implementation supports basic authentication + as a means of [client authentication](https://datatracker.ietf.org/doc/html/rfc6749#section-2.3), + the client credentials must be extracted from `Authorization` header and they must be passed as + `clientId` request parameter and `clientSecret` request parameter to Authlete's `/auth/token` API. + The following code snippet is an example in JAX-RS showing how to extract request parameters from + the token request and client credentials from Authorization header. + ```java + @POST + @Consumes(MediaType.APPLICATION_FORM_URLENCODED) + public Response post( + @HeaderParam(HttpHeaders.AUTHORIZATION) String auth, + String parameters) + { + // Convert the value of Authorization header (credentials of + // the client application), if any, into BasicCredentials. + BasicCredentials credentials = BasicCredentials.parse(auth); + // The credentials of the client application extracted from + // 'Authorization' header. These may be null. + String clientId = credentials == null ? null + : credentials.getUserId(); + String clientSecret = credentials == null ? null + : credentials.getPassword(); + // Process the given parameters. + return process(parameters, clientId, clientSecret); + } + ``` + The response from `/auth/token` API has some parameters. Among them, it is action parameter that + the service implementation should check first because it denotes the next action that the authorization + server implementation should take. According to the value of action, the authorization server + 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. + + ## INVALID_CLIENT + + When the value of `action` is `INVALID_CLIENT`, it means that authentication of the client failed. + In this case, the HTTP status of the response to the client application is either "400 Bad Request" + or "401 Unauthorized". This requirement comes from [RFC 6749, 5.2. Error Response](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2). + The description about `invalid_client` shown below is an excerpt from RFC 6749. + + --- + + Client authentication failed (e.g., unknown client, no client authentication included, or unsupported + authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code + to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate + via the `Authorization` request header field, the authorization server MUST respond with an HTTP + 401 (Unauthorized) status code and include the `WWW-Authenticate` response header field matching + the authentication scheme used by the client. + + --- + + In either case, the value of `responseContent` is a JSON string which can be used as the entity + body of the response to the client application. + + --- + + The following illustrate responses which the service implementation must 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} + ``` + + ``` + HTTP/1.1 401 Unauthorized + WWW-Authenticate: {challenge} + Content-Type: application/json + Cache-Control: no-store + Pragma: no-cache + {responseContent} + ``` + + ## 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" must be returned to the client application and + the content type must be `application/json`. + 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} + ``` + + ## PASSWORD + + When the value of `"action"` is `"PASSWORD"`, it means that + the request from the client application is valid and `grant_type` + is `"password"`. That is, the flow is + ["Resource Owner + Password Credentials"](https://www.rfc-editor.org/rfc/rfc6749.html#section-4.3). + In this case, {@link #getUsername()} returns the value of `"username"` + request parameter and {@link #getPassword()} returns the value of {@code + "password"} request parameter which were contained in the token request + from the client application. The service implementation must validate the + credentials of the resource owner (= end-user) and take either of the + actions below according to the validation result. + 1. When the credentials are valid, call Authlete's /auth/token/issue} API to generate an access token for the client + application. The API requires `"ticket"` request parameter and + `"subject"` request parameter. + Use the value returned from {@link #getTicket()} method as the value + for `"ticket"` parameter. + 2. The response from `/auth/token/issue` API ({@link + TokenIssueResponse}) contains data (an access token and others) + which should be returned to the client application. Use the data + to generate a response to the client application. + 3. When the credentials are invalid, call Authlete's {@code + /auth/token/fail} API with `reason=`{@link + TokenFailRequest.Reason#INVALID_RESOURCE_OWNER_CREDENTIALS + INVALID_RESOURCE_OWNER_CREDENTIALS} to generate an error response + for the client application. The API requires `"ticket"` + request parameter. Use the value returned from {@link #getTicket()} + method as the value for `"ticket"` parameter. + 4. The response from `/auth/token/fail` API ({@link + TokenFailResponse}) contains error information which should be + returned to the client application. Use it to generate a response + to the client application. + + ## OK + + When the value of `action` is `OK`, it means that the request from the client application is valid + and an access token, and optionally an ID token, is ready to be issued. + The HTTP status of the response returned to the client application must be "200 OK" and the content + type must be `application/json`. + The value of `responseContent` is a JSON string which contains an access token (and optionally + an ID token), so it 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: application/json + Cache-Control: no-store + Pragma: no-cache + {responseContent} + ``` + + ## TOKEN_EXCHANGE (Authlete 2.3 onwards) + + When the value of `"action"` is `"TOKEN_EXCHANGE"`, it means + that the request from the client application is a valid token exchange + request (cf. [RFC + 8693 OAuth 2.0 Token Exchange](https://www.rfc-editor.org/rfc/rfc8693.html)) and that the request has already passed + the following validation steps. + 1. Confirm that the value of the `requested_token_type` request parameter + is one of the registered token type identifiers if the request parameter is + given and its value is not empty. + 2. Confirm that the `subject_token` request parameter is given and its + value is not empty. + 3. Confirm that the `subject_token_type` request parameter is given and + its value is one of the registered token type identifiers. + 4. Confirm that the `actor_token_type` request parameter is given and + its value is one of the registered token type identifiers if the + `actor_token` request parameter is given and its value is not empty. + 5. Confirm that the `actor_token_type` request parameter is not given + or its value is empty when the `actor_token` request parameter is + not given or its value is empty. + Furthermore, Authlete performs additional validation on the tokens specified + by the `subject_token` request parameter and the `actor_token` + request parameter according to their respective token types as shown below. + + ## Token Validation Steps + \*Token Type: `urn:ietf:params:oauth:token-type:jwt`\* + 1. Confirm that the format conforms to the JWT specification [RFC 7519][https://www.rfc-editor.org/rfc/rfc7519.html]. + 2. Check if the JWT is encrypted and if it is encrypted, then (a) reject + the token exchange request when the {@link + Service#isTokenExchangeEncryptedJwtRejected() + tokenExchangeEncryptedJwtRejected} flag of the service is `true` + or (b) skip remaining validation steps when the flag is `false`. + Note that Authlete does not verify an encrypted JWT because there is + no standard way to obtain the key to decrypt the JWT with. This means + that you must verify an encrypted JWT by yourself when one is used as + an input token with the token type + { @code "urn:ietf:params:oauth:token-type:jwt" }. + 3. Confirm that the current time has not reached the time indicated by + the `exp` claim if the JWT contains the claim. + 4. Confirm that the current time is equal to or after the time indicated + by the `iat` claim if the JWT contains the claim. + 5.Confirm that the current time is equal to or after the time indicated + by the `nbf` claim if the JWT contains the claim. + 6. Check if the JWT is signed and if it is not signed, then (a) reject + the token exchange request when the {@link + Service#isTokenExchangeUnsignedJwtRejected() + tokenExchangeUnsignedJwtRejected} flag of the service is `true` + or (b) finish validation on the input token. Note that Authlete does + not verify the signature of the JWT because there is no standard way + to obtain the key to verify the signature of a JWT with. This means + that you must verify the signature by yourself when a signed JWT is + used as an input token with the token type + `"urn:ietf:params:oauth:token-type:jwt"`. + \*Token Type: `urn:ietf:params:oauth:token-type:access_token`\* + 1. Confirm that the token is an access token that has been issued by + the Authlete server of your service. This implies that access + tokens issued by other systems cannot be used as a subject token + or an actor token with the token type + `urn:ietf:params:oauth:token-type:access_token`. + 2. Confirm that the access token has not expired. + 3. Confirm that the access token belongs to the service. + \*Token Type: `urn:ietf:params:oauth:token-type:refresh_token`\* + 1. Confirm that the token is a refresh token that has been issued by + the Authlete server of your service. This implies that refresh + tokens issued by other systems cannot be used as a subject token + or an actor token with the token type + `urn:ietf:params:oauth:token-type:refresh_token`. + 2. Confirm that the refresh token has not expired. + 3. Confirm that the refresh token belongs to the service. + \*Token Type: `urn:ietf:params:oauth:token-type:id_token`\* + 1. Confirm that the format conforms to the JWT specification ([RFC 7519](https://www.rfc-editor.org/rfc/rfc7519.html)). + 2. Check if the ID Token is encrypted and if it is encrypted, then (a) + reject the token exchange request when the {@link + Service#isTokenExchangeEncryptedJwtRejected() + tokenExchangeEncryptedJwtRejected} flag of the service is `true` + or (b) skip remaining validation steps when the flag is `false`. + Note that Authlete does not verify an encrypted ID Token because + there is no standard way to obtain the key to decrypt the ID Token + with in the context of token exchange where the client ID for the + encrypted ID Token cannot be determined. This means that you must + verify an encrypted ID Token by yourself when one is used as an + input token with the token type + `"urn:ietf:params:oauth:token-type:id_token"`. + 3. Confirm that the ID Token contains the `exp` claim and the + current time has not reached the time indicated by the claim. + 4. Confirm that the ID Token contains the `iat` claim and the + current time is equal to or after the time indicated by the claim. + 5. Confirm that the current time is equal to or after the time indicated + by the `nbf` claim if the ID Token contains the claim. + 6. Confirm that the ID Token contains the `iss` claim and the + value is a valid URI. In addition, confirm that the URI has the + `https` scheme, no query component and no fragment component. + 7. Confirm that the ID Token contains the `aud` claim and its + value is a JSON string or an array of JSON strings. + 8. Confirm that the value of the `nonce` claim is a JSON string + if the ID Token contains the claim. + 9. Check if the ID Token is signed and if it is not signed, then (a) + reject the token exchange request when the {@link + Service#isTokenExchangeUnsignedJwtRejected() + tokenExchangeUnsignedJwtRejected} flag of the service is `true` + or (b) finish validation on the input token. + 10. Confirm that the signature algorithm is asymmetric. This implies that + ID Tokens whose signature algorithm is symmetric (`HS256`, + `HS384` or `HS512`) cannot be used as a subject token or + an actor token with the token type + `urn:ietf:params:oauth:token-type:id_token`. + 11. Verify the signature of the ID Token. Signature verification is + performed even in the case where the issuer of the ID Token is not + your service. But in that case, the issuer must support the discovery + endpoint defined in [OpenID + Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html). Otherwise, signature verification fails. + \*Token Type: `urn:ietf:params:oauth:token-type:saml1`\* + (Authlete does not perform any validation for this token type.) + \*Token Type: `urn:ietf:params:oauth:token-type:saml2`\* + (Authlete does not perform any validation for this token type.) + The specification of Token Exchange ([RFC 8693](https://www.rfc-editor.org/rfc/rfc8693.html)) is very + flexible. In other words, the specification has abandoned the task of + determining details. Therefore, for secure token exchange, you have + to complement the specification with your own rules. For that purpose, + Authlete provides some configuration options as listed below. + Authorization server implementers may utilize them and/or implement + their own rules. + In the case of {@link Action#TOKEN_EXCHANGE TOKEN_EXCHANGE}, the {@link + #getResponseContent()} method returns `null`. You have to construct + the token response by yourself. + For example, you may generate an access token by calling Authlete's + `/api/auth/token/create` API and construct a token response like + below. + ``` + HTTP/1.1 401 Unauthorized + WWW-Authenticate: {challenge} + Content-Type: application/json + Cache-Control: no-store + Pragma: no-cache + {responseContent} + ``` + ``` + HTTP/1.1 200 OK + Content-Type: application/json + Cache-Control: no-cache, no-store + { + "access_token": "{@link TokenCreateResponse#getAccessToken()}", + "issued_token_type": "urn:ietf:params:oauth:token-type:access_token", + "token_type": "Bearer", + "expires_in": { @link TokenCreateResponse#getExpiresIn() }, + "scope": "String.join(" ", {@link TokenCreateResponse#getScopes()})" + } + ``` + + ## JWT_BEARER JWT_BEARER (Authlete 2.3 onwards) + + When the value of `"action"` is `"JWT_BEARER"`, it means that + the request from the client application is a valid token request with the + grant type `"urn:ietf:params:oauth:grant-type:jwt-bearer"` ([RFC 7523 JSON Web Token (JWT) + Profile for OAuth 2.0 Client Authentication and Authorization Grants](https://www.rfc-editor.org/rfc/rfc7523.html)) + and that the request has already passed the following validation steps. + 1. Confirm that the `assertion` request parameter is given and its value + is not empty. + 2. Confirm that the format of the assertion conforms to the JWT specification + ([RFC 7519](https://www.rfc-editor.org/rfc/rfc7519.html)). + 3. Check if the JWT is encrypted and if it is encrypted, then (a) reject the + token request when the {@link Service#isJwtGrantEncryptedJwtRejected() + jwtGrantEncryptedJwtRejected} flag of the service is `true` or (b) + skip remaining validation steps when the flag is `false`. Note that + Authlete does not verify an encrypted JWT because there is no standard way + to obtain the key to decrypt the JWT with. This means that you must verify + an encrypted JWT by yourself. + 4. Confirm that the JWT contains the `iss` claim and its value is a + JSON string. + 5. Confirm that the JWT contains the `sub` claim and its value is a + JSON string. + 6. Confirm that the JWT contains the `aud` claim and its value is + either a JSON string or an array of JSON strings. + 7. Confirm that the issuer identifier of the service (cf. {@link Service#getIssuer()}) + or the URL of the token endpoint (cf. {@link Service#getTokenEndpoint()}) + is listed as audience in the `aud` claim. + 8. Confirm that the JWT contains the `exp` claim and the current time + has not reached the time indicated by the claim. + 9. Confirm that the current time is equal to or after the time indicated by + by the `iat` claim if the JWT contains the claim. + 10. Confirm that the current time is equal to or after the time indicated by + by the `nbf` claim if the JWT contains the claim. + 11. Check if the JWT is signed and if it is not signed, then (a) reject the + token request when the {@link Service#isJwtGrantUnsignedJwtRejected() + jwtGrantUnsignedJwtRejected} flag of the service is `true` or (b) + finish validation on the JWT. Note that Authlete does not verify the + signature of the JWT because there is no standard way to obtain the key + to verify the signature of a JWT with. This means that you must verify + the signature by yourself. + Authlete provides some configuration options for the grant type as listed + below. Authorization server implementers may utilize them and/or implement + their own rules. + ``` + HTTP/1.1 200 OK + Content-Type: application/json + Cache-Control: no-cache, no-store + { + "access_token": "{@link TokenCreateResponse#getAccessToken()}", + "token_type": "Bearer", + "expires_in": {@link TokenCreateResponse#getExpiresIn()}, + "scope": "String.join(" ", {@link TokenCreateResponse#getScopes()})" + } + ``` + Finally, note again that Authlete does not verify the signature of the JWT + specified by the `assertion` request parameter. You must verify the + signature by yourself. + - This API is supposed to be called from with the implementation of the token endpoint of the service. - The endpoint implementation must extract the request parameters from the token request from the - client application and pass them as the value of parameters request parameter to Authlete's `/auth/token` API. - The value of parameters is the entire entity body (which is formatted in `application/x-www-form-urlencoded`) - of the token request. - In addition, if the token endpoint of the authorization server implementation supports basic authentication - as a means of [client authentication](https://datatracker.ietf.org/doc/html/rfc6749#section-2.3), - the client credentials must be extracted from `Authorization` header and they must be passed as - `clientId` request parameter and `clientSecret` request parameter to Authlete's `/auth/token` API. - The following code snippet is an example in JAX-RS showing how to extract request parameters from - the token request and client credentials from Authorization header. - ```java - @POST - @Consumes(MediaType.APPLICATION_FORM_URLENCODED) - public Response post( - @HeaderParam(HttpHeaders.AUTHORIZATION) String auth, - String parameters) - { - // Convert the value of Authorization header (credentials of - // the client application), if any, into BasicCredentials. - BasicCredentials credentials = BasicCredentials.parse(auth); - // The credentials of the client application extracted from - // 'Authorization' header. These may be null. - String clientId = credentials == null ? null - : credentials.getUserId(); - String clientSecret = credentials == null ? null - : credentials.getPassword(); - // Process the given parameters. - return process(parameters, clientId, clientSecret); - } - ``` - The response from `/auth/token` API has some parameters. Among them, it is action parameter that - the service implementation should check first because it denotes the next action that the authorization - server implementation should take. According to the value of action, the authorization server - 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. - - ## INVALID_CLIENT - - When the value of `action` is `INVALID_CLIENT`, it means that authentication of the client failed. - In this case, the HTTP status of the response to the client application is either "400 Bad Request" - or "401 Unauthorized". This requirement comes from [RFC 6749, 5.2. Error Response](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2). - The description about `invalid_client` shown below is an excerpt from RFC 6749. - - --- - - Client authentication failed (e.g., unknown client, no client authentication included, or unsupported - authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code - to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate - via the `Authorization` request header field, the authorization server MUST respond with an HTTP - 401 (Unauthorized) status code and include the `WWW-Authenticate` response header field matching - the authentication scheme used by the client. - - --- - - In either case, the value of `responseContent` is a JSON string which can be used as the entity - body of the response to the client application. - - --- - - The following illustrate responses which the service implementation must 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} - ``` - - ``` - HTTP/1.1 401 Unauthorized - WWW-Authenticate: {challenge} - Content-Type: application/json - Cache-Control: no-store - Pragma: no-cache - {responseContent} - ``` - - ## 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" must be returned to the client application and - the content type must be `application/json`. - 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} - ``` - - ## PASSWORD - - When the value of `"action"` is `"PASSWORD"`, it means that - the request from the client application is valid and `grant_type` - is `"password"`. That is, the flow is - ["Resource Owner - Password Credentials"](https://www.rfc-editor.org/rfc/rfc6749.html#section-4.3). - In this case, {@link #getUsername()} returns the value of `"username"` - request parameter and {@link #getPassword()} returns the value of {@code - "password"} request parameter which were contained in the token request - from the client application. The service implementation must validate the - credentials of the resource owner (= end-user) and take either of the - actions below according to the validation result. - 1. When the credentials are valid, call Authlete's /auth/token/issue} API to generate an access token for the client - application. The API requires `"ticket"` request parameter and - `"subject"` request parameter. - Use the value returned from {@link #getTicket()} method as the value - for `"ticket"` parameter. - 2. The response from `/auth/token/issue` API ({@link - TokenIssueResponse}) contains data (an access token and others) - which should be returned to the client application. Use the data - to generate a response to the client application. - 3. When the credentials are invalid, call Authlete's {@code - /auth/token/fail} API with `reason=`{@link - TokenFailRequest.Reason#INVALID_RESOURCE_OWNER_CREDENTIALS - INVALID_RESOURCE_OWNER_CREDENTIALS} to generate an error response - for the client application. The API requires `"ticket"` - request parameter. Use the value returned from {@link #getTicket()} - method as the value for `"ticket"` parameter. - 4. The response from `/auth/token/fail` API ({@link - TokenFailResponse}) contains error information which should be - returned to the client application. Use it to generate a response - to the client application. - - ## OK - - When the value of `action` is `OK`, it means that the request from the client application is valid - and an access token, and optionally an ID token, is ready to be issued. - The HTTP status of the response returned to the client application must be "200 OK" and the content - type must be `application/json`. - The value of `responseContent` is a JSON string which contains an access token (and optionally - an ID token), so it 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: application/json - Cache-Control: no-store - Pragma: no-cache - {responseContent} - ``` - - ## TOKEN_EXCHANGE (Authlete 2.3 onwards) - - When the value of `"action"` is `"TOKEN_EXCHANGE"`, it means - that the request from the client application is a valid token exchange - request (cf. [RFC - 8693 OAuth 2.0 Token Exchange](https://www.rfc-editor.org/rfc/rfc8693.html)) and that the request has already passed - the following validation steps. - 1. Confirm that the value of the `requested_token_type` request parameter - is one of the registered token type identifiers if the request parameter is - given and its value is not empty. - 2. Confirm that the `subject_token` request parameter is given and its - value is not empty. - 3. Confirm that the `subject_token_type` request parameter is given and - its value is one of the registered token type identifiers. - 4. Confirm that the `actor_token_type` request parameter is given and - its value is one of the registered token type identifiers if the - `actor_token` request parameter is given and its value is not empty. - 5. Confirm that the `actor_token_type` request parameter is not given - or its value is empty when the `actor_token` request parameter is - not given or its value is empty. - Furthermore, Authlete performs additional validation on the tokens specified - by the `subject_token` request parameter and the `actor_token` - request parameter according to their respective token types as shown below. - - ## Token Validation Steps - \*Token Type: `urn:ietf:params:oauth:token-type:jwt`\* - 1. Confirm that the format conforms to the JWT specification [RFC 7519][https://www.rfc-editor.org/rfc/rfc7519.html]. - 2. Check if the JWT is encrypted and if it is encrypted, then (a) reject - the token exchange request when the {@link - Service#isTokenExchangeEncryptedJwtRejected() - tokenExchangeEncryptedJwtRejected} flag of the service is `true` - or (b) skip remaining validation steps when the flag is `false`. - Note that Authlete does not verify an encrypted JWT because there is - no standard way to obtain the key to decrypt the JWT with. This means - that you must verify an encrypted JWT by yourself when one is used as - an input token with the token type - { @code "urn:ietf:params:oauth:token-type:jwt" }. - 3. Confirm that the current time has not reached the time indicated by - the `exp` claim if the JWT contains the claim. - 4. Confirm that the current time is equal to or after the time indicated - by the `iat` claim if the JWT contains the claim. - 5.Confirm that the current time is equal to or after the time indicated - by the `nbf` claim if the JWT contains the claim. - 6. Check if the JWT is signed and if it is not signed, then (a) reject - the token exchange request when the {@link - Service#isTokenExchangeUnsignedJwtRejected() - tokenExchangeUnsignedJwtRejected} flag of the service is `true` - or (b) finish validation on the input token. Note that Authlete does - not verify the signature of the JWT because there is no standard way - to obtain the key to verify the signature of a JWT with. This means - that you must verify the signature by yourself when a signed JWT is - used as an input token with the token type - `"urn:ietf:params:oauth:token-type:jwt"`. - \*Token Type: `urn:ietf:params:oauth:token-type:access_token`\* - 1. Confirm that the token is an access token that has been issued by - the Authlete server of your service. This implies that access - tokens issued by other systems cannot be used as a subject token - or an actor token with the token type - `urn:ietf:params:oauth:token-type:access_token`. - 2. Confirm that the access token has not expired. - 3. Confirm that the access token belongs to the service. - \*Token Type: `urn:ietf:params:oauth:token-type:refresh_token`\* - 1. Confirm that the token is a refresh token that has been issued by - the Authlete server of your service. This implies that refresh - tokens issued by other systems cannot be used as a subject token - or an actor token with the token type - `urn:ietf:params:oauth:token-type:refresh_token`. - 2. Confirm that the refresh token has not expired. - 3. Confirm that the refresh token belongs to the service. - \*Token Type: `urn:ietf:params:oauth:token-type:id_token`\* - 1. Confirm that the format conforms to the JWT specification ([RFC 7519](https://www.rfc-editor.org/rfc/rfc7519.html)). - 2. Check if the ID Token is encrypted and if it is encrypted, then (a) - reject the token exchange request when the {@link - Service#isTokenExchangeEncryptedJwtRejected() - tokenExchangeEncryptedJwtRejected} flag of the service is `true` - or (b) skip remaining validation steps when the flag is `false`. - Note that Authlete does not verify an encrypted ID Token because - there is no standard way to obtain the key to decrypt the ID Token - with in the context of token exchange where the client ID for the - encrypted ID Token cannot be determined. This means that you must - verify an encrypted ID Token by yourself when one is used as an - input token with the token type - `"urn:ietf:params:oauth:token-type:id_token"`. - 3. Confirm that the ID Token contains the `exp` claim and the - current time has not reached the time indicated by the claim. - 4. Confirm that the ID Token contains the `iat` claim and the - current time is equal to or after the time indicated by the claim. - 5. Confirm that the current time is equal to or after the time indicated - by the `nbf` claim if the ID Token contains the claim. - 6. Confirm that the ID Token contains the `iss` claim and the - value is a valid URI. In addition, confirm that the URI has the - `https` scheme, no query component and no fragment component. - 7. Confirm that the ID Token contains the `aud` claim and its - value is a JSON string or an array of JSON strings. - 8. Confirm that the value of the `nonce` claim is a JSON string - if the ID Token contains the claim. - 9. Check if the ID Token is signed and if it is not signed, then (a) - reject the token exchange request when the {@link - Service#isTokenExchangeUnsignedJwtRejected() - tokenExchangeUnsignedJwtRejected} flag of the service is `true` - or (b) finish validation on the input token. - 10. Confirm that the signature algorithm is asymmetric. This implies that - ID Tokens whose signature algorithm is symmetric (`HS256`, - `HS384` or `HS512`) cannot be used as a subject token or - an actor token with the token type - `urn:ietf:params:oauth:token-type:id_token`. - 11. Verify the signature of the ID Token. Signature verification is - performed even in the case where the issuer of the ID Token is not - your service. But in that case, the issuer must support the discovery - endpoint defined in [OpenID - Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html). Otherwise, signature verification fails. - \*Token Type: `urn:ietf:params:oauth:token-type:saml1`\* - (Authlete does not perform any validation for this token type.) - \*Token Type: `urn:ietf:params:oauth:token-type:saml2`\* - (Authlete does not perform any validation for this token type.) - The specification of Token Exchange ([RFC 8693](https://www.rfc-editor.org/rfc/rfc8693.html)) is very - flexible. In other words, the specification has abandoned the task of - determining details. Therefore, for secure token exchange, you have - to complement the specification with your own rules. For that purpose, - Authlete provides some configuration options as listed below. - Authorization server implementers may utilize them and/or implement - their own rules. - In the case of {@link Action#TOKEN_EXCHANGE TOKEN_EXCHANGE}, the {@link - #getResponseContent()} method returns `null`. You have to construct - the token response by yourself. - For example, you may generate an access token by calling Authlete's - `/api/auth/token/create` API and construct a token response like - below. - ``` - HTTP/1.1 401 Unauthorized - WWW-Authenticate: {challenge} - Content-Type: application/json - Cache-Control: no-store - Pragma: no-cache - {responseContent} - ``` - ``` - HTTP/1.1 200 OK - Content-Type: application/json - Cache-Control: no-cache, no-store - { - "access_token": "{@link TokenCreateResponse#getAccessToken()}", - "issued_token_type": "urn:ietf:params:oauth:token-type:access_token", - "token_type": "Bearer", - "expires_in": { @link TokenCreateResponse#getExpiresIn() }, - "scope": "String.join(" ", {@link TokenCreateResponse#getScopes()})" - } - ``` - - ## JWT_BEARER JWT_BEARER (Authlete 2.3 onwards) - - When the value of `"action"` is `"JWT_BEARER"`, it means that - the request from the client application is a valid token request with the - grant type `"urn:ietf:params:oauth:grant-type:jwt-bearer"` ([RFC 7523 JSON Web Token (JWT) - Profile for OAuth 2.0 Client Authentication and Authorization Grants](https://www.rfc-editor.org/rfc/rfc7523.html)) - and that the request has already passed the following validation steps. - 1. Confirm that the `assertion` request parameter is given and its value - is not empty. - 2. Confirm that the format of the assertion conforms to the JWT specification - ([RFC 7519](https://www.rfc-editor.org/rfc/rfc7519.html)). - 3. Check if the JWT is encrypted and if it is encrypted, then (a) reject the - token request when the {@link Service#isJwtGrantEncryptedJwtRejected() - jwtGrantEncryptedJwtRejected} flag of the service is `true` or (b) - skip remaining validation steps when the flag is `false`. Note that - Authlete does not verify an encrypted JWT because there is no standard way - to obtain the key to decrypt the JWT with. This means that you must verify - an encrypted JWT by yourself. - 4. Confirm that the JWT contains the `iss` claim and its value is a - JSON string. - 5. Confirm that the JWT contains the `sub` claim and its value is a - JSON string. - 6. Confirm that the JWT contains the `aud` claim and its value is - either a JSON string or an array of JSON strings. - 7. Confirm that the issuer identifier of the service (cf. {@link Service#getIssuer()}) - or the URL of the token endpoint (cf. {@link Service#getTokenEndpoint()}) - is listed as audience in the `aud` claim. - 8. Confirm that the JWT contains the `exp` claim and the current time - has not reached the time indicated by the claim. - 9. Confirm that the current time is equal to or after the time indicated by - by the `iat` claim if the JWT contains the claim. - 10. Confirm that the current time is equal to or after the time indicated by - by the `nbf` claim if the JWT contains the claim. - 11. Check if the JWT is signed and if it is not signed, then (a) reject the - token request when the {@link Service#isJwtGrantUnsignedJwtRejected() - jwtGrantUnsignedJwtRejected} flag of the service is `true` or (b) - finish validation on the JWT. Note that Authlete does not verify the - signature of the JWT because there is no standard way to obtain the key - to verify the signature of a JWT with. This means that you must verify - the signature by yourself. - Authlete provides some configuration options for the grant type as listed - below. Authorization server implementers may utilize them and/or implement - their own rules. - ``` - HTTP/1.1 200 OK - Content-Type: application/json - Cache-Control: no-cache, no-store - { - "access_token": "{@link TokenCreateResponse#getAccessToken()}", - "token_type": "Bearer", - "expires_in": {@link TokenCreateResponse#getExpiresIn()}, - "scope": "String.join(" ", {@link TokenCreateResponse#getScopes()})" - } - ``` - Finally, note again that Authlete does not verify the signature of the JWT - specified by the `assertion` request parameter. You must verify the - signature by yourself. parameters: - in: path name: serviceId @@ -4084,60 +4114,66 @@ paths: description: | This API generates a content of an error token response that the authorization server implementation returns to the client application. + x-mint: + metadata: + description: "This API generates a content of an error token response that the authorization server implementation returns to the client application." + content: | + + This API is supposed to be called from within the implementation of the token endpoint of the service + in order to generate an error response to the client application. + The description of the `/auth/token` API describes the timing when this API should be called. See + the description for the case of `action=PASSWORD`. + The response from `/auth/token/fail` API has some 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 + authorization server 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". + 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 Authlete's `/auth/token/fail` API successfully + generated an error response for the client application. + The HTTP status of the response returned to the client application must be "400 Bad Request" and + the content type must be `application/json`. + 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} + ``` + - This API is supposed to be called from within the implementation of the token endpoint of the service - in order to generate an error response to the client application. - The description of the `/auth/token` API describes the timing when this API should be called. See - the description for the case of `action=PASSWORD`. - The response from `/auth/token/fail` API has some 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 - authorization server 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". - 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 Authlete's `/auth/token/fail` API successfully - generated an error response for the client application. - The HTTP status of the response returned to the client application must be "400 Bad Request" and - the content type must be `application/json`. - 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} - ``` parameters: - in: path name: serviceId @@ -4215,60 +4251,66 @@ paths: description: | This API generates a content of a successful token response that the authorization server implementation returns to the client application. + x-mint: + metadata: + description: "This API generates a content of a successful token response that the authorization server implementation returns to the client application." + content: | + + This API is supposed to be called from within the implementation of the token endpoint of the service + in order to generate a successful response to the client application. + The description of the `/auth/token` API describes the timing when this API should be called. See + the description for the case of `action=PASSWORD`. + The response from `/auth/token/issue` API has some 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 + authorization server 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". + 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. + + ## OK + + When the value of `action` is `OK`, it means that Authlete's `/auth/token/issue` API successfully + generated an access token. + The HTTP status of the response returned to the client application must be "200 OK" and the content + type must be`application/json`. + The value of `responseContent` is a JSON string which contains an access token, so it 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: application/json + Cache-Control: no-store + Pragma: no-cache + {responseContent} + ``` + - This API is supposed to be called from within the implementation of the token endpoint of the service - in order to generate a successful response to the client application. - The description of the `/auth/token` API describes the timing when this API should be called. See - the description for the case of `action=PASSWORD`. - The response from `/auth/token/issue` API has some 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 - authorization server 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". - 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. - - ## OK - - When the value of `action` is `OK`, it means that Authlete's `/auth/token/issue` API successfully - generated an access token. - The HTTP status of the response returned to the client application must be "200 OK" and the content - type must be`application/json`. - The value of `responseContent` is a JSON string which contains an access token, so it 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: application/json - Cache-Control: no-store - Pragma: no-cache - {responseContent} - ``` parameters: - in: path name: serviceId @@ -4363,139 +4405,145 @@ paths: summary: Process Introspection Request description: | This API gathers information about an access token. + x-mint: + metadata: + description: "This API gathers information about an access token." + content: | + + This API is supposed to be called from within the implementations of protected resource endpoints + of the authorization server implementation in order to get information about the access token which + was presented by the client application. + In general, a client application accesses a protected resource endpoint of a service with an access + token, and the implementation of the endpoint checks whether the presented access token has enough + privileges (= scopes) to access the protected resource before returning the protected resource to + the client application. To achieve this flow, the endpoint implementation has to know detailed + information about the access token. Authlete `/auth/introspection` API can be used to get such information. + The response from `/auth/introspection` API has some 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 + authorization server 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 string which describes the error in the format of + [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage), so if + the protected resource of the service implementation wants to return an error response to the client + application in the way that complies with RFC 6750 (in other words, if `accessTokenType` configuration + parameter of the service is Bearer), the value of `responseContent` can be used as the value of + `WWW-Authenticate` header. + The following is an example response which complies with RFC 6750. + ``` + HTTP/1.1 500 Internal Server Error + Content-Type: application/json + Cache-Control: no-store + Pragma: no-cache + {responseContent} + ``` + + ## BAD_REQUEST + + When the value of `action` is `BAD_REQUEST`, it means that the request from the client application + does not contain an access token (= the request from the authorization server implementation to + Authlete does not contain `token` request parameter). + A response with HTTP status of "400 Bad Request" must be returned to the client application and + the content type must be `application/json`. + The value of `responseContent` is a string which describes the error in the format of [RFC + 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage), so if the + protected resource of the service implementation wants to return an error response to the client + application in the way that complies with RFC 6750 (in other words, if `accessTokenType` configuration + parameter of the service is `Bearer`), the value of `responseContent` can be used as the value of + `WWW-Authenticate` header. + The following is an example response which complies with RFC 6750. + ``` + HTTP/1.1 400 Bad Request + WWW-Authenticate: {responseContent} + Cache-Control: no-store + Pragma: no-cache + ``` + + ## UNAUTHORIZED + + When the value of `action` is `UNAUTHORIZED`, it means that the access token does not exist or has + expired. + The value of `responseContent` is a string which describes the error in the format of RFC + 6750 (OAuth 2.0 Bearer Token Usage), so if the protected resource of the service implementation + wants to return an error response to the client application in the way that complies with [RFC + 6750](https://datatracker.ietf.org/doc/html/rfc6750) (in other words, if `accessTokenType` configuration + parameter of the service is `Bearer`), the value of `responseContent` can be used as the value of + `WWW-Authenticate` header. + The following is an example response which complies with RFC 6750. + ``` + HTTP/1.1 401 Unauthorized + WWW-Authenticate: {responseContent} + Cache-Control: no-store + Pragma: no-cache + ``` + + ## FORBIDDEN + + When the value of `action` is `FORBIDDEN`, it means that the access token does not cover the required + scopes or that the subject associated with the access token is different from the subject contained + in the request. + A response with HTTP status of "400 Bad Request" must be returned to the client application and + the content type must be `application/json`. + The value of `responseContent` is a string which describes the error in the format of [RFC + 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage), so if the + protected resource of the service implementation wants to return an error response to the client + application in the way that complies with RFC 6750 (in other words, if `accessTokenType` configuration + parameter of the service is Bearer), the value of `responseContent` can be used as the value of + `WWW-Authenticate` header. + The following is an example response which complies with RFC 6750. + ``` + HTTP/1.1 403 Forbidden + WWW-Authenticate: {responseContent} + Cache-Control: no-store + Pragma: no-cache + ``` + + ## OK + + When the value of `action` is `OK`, it means that the access token which the client application + presented is valid (= exists and has not expired). + The implementation of the protected resource endpoint is supposed to return the protected resource + to the client application. + When action is `OK`, the value of `responseContent` is `"Bearer error=\"invalid_request\""`. This + is the simplest string which can be used as the value of `WWW-Authenticate` header to indicate + "400 Bad Request". The implementation of the protected resource endpoint may use this string to + tell the client application that the request was bad (e.g. in case necessary request parameters + for the protected resource endpoint are missing). However, in such a case, the implementation + should generate a more informative error message to help developers of client applications. + The following is an example error response which complies with RFC 6750. + ``` + HTTP/1.1 400 Bad Request + WWW-Authenticate: {responseContent} + Cache-Control: no-store + Pragma: no-cache + ``` + Basically, The value of `responseContent` is a string which describes the error in the format of + [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage). So, if + the service has selected `Bearer` as the value of `accessTokenType` configuration parameter, the + value of `responseContent` can be used directly as the value of `WWW-Authenticate` header. However, + if the service has selected another different token type, the service has to generate error messages + for itself. + _**JWT-based access token**_ + Since version 2.1, Authlete provides a feature to issue access tokens in JWT format. This feature + can be enabled by setting a non-null value to the `accessTokenSignAlg` property of the service + (see the description of the Service class for details). `/api/auth/introspection` API can accept + access tokens in JWT format. However, note that the API does not return information contained in + a given JWT-based access token but returns information stored in the database record which corresponds + to the given JWT-based access token. Because attributes of the database record can be modified + after the access token is issued (for example, by using `/api/auth/token/update` API), information + returned by `/api/auth/introspection` API and information the given JWT-based access token holds + may be different. + - This API is supposed to be called from within the implementations of protected resource endpoints - of the authorization server implementation in order to get information about the access token which - was presented by the client application. - In general, a client application accesses a protected resource endpoint of a service with an access - token, and the implementation of the endpoint checks whether the presented access token has enough - privileges (= scopes) to access the protected resource before returning the protected resource to - the client application. To achieve this flow, the endpoint implementation has to know detailed - information about the access token. Authlete `/auth/introspection` API can be used to get such information. - The response from `/auth/introspection` API has some 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 - authorization server 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 string which describes the error in the format of - [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage), so if - the protected resource of the service implementation wants to return an error response to the client - application in the way that complies with RFC 6750 (in other words, if `accessTokenType` configuration - parameter of the service is Bearer), the value of `responseContent` can be used as the value of - `WWW-Authenticate` header. - The following is an example response which complies with RFC 6750. - ``` - HTTP/1.1 500 Internal Server Error - Content-Type: application/json - Cache-Control: no-store - Pragma: no-cache - {responseContent} - ``` - - ## BAD_REQUEST - - When the value of `action` is `BAD_REQUEST`, it means that the request from the client application - does not contain an access token (= the request from the authorization server implementation to - Authlete does not contain `token` request parameter). - A response with HTTP status of "400 Bad Request" must be returned to the client application and - the content type must be `application/json`. - The value of `responseContent` is a string which describes the error in the format of [RFC - 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage), so if the - protected resource of the service implementation wants to return an error response to the client - application in the way that complies with RFC 6750 (in other words, if `accessTokenType` configuration - parameter of the service is `Bearer`), the value of `responseContent` can be used as the value of - `WWW-Authenticate` header. - The following is an example response which complies with RFC 6750. - ``` - HTTP/1.1 400 Bad Request - WWW-Authenticate: {responseContent} - Cache-Control: no-store - Pragma: no-cache - ``` - - ## UNAUTHORIZED - - When the value of `action` is `UNAUTHORIZED`, it means that the access token does not exist or has - expired. - The value of `responseContent` is a string which describes the error in the format of RFC - 6750 (OAuth 2.0 Bearer Token Usage), so if the protected resource of the service implementation - wants to return an error response to the client application in the way that complies with [RFC - 6750](https://datatracker.ietf.org/doc/html/rfc6750) (in other words, if `accessTokenType` configuration - parameter of the service is `Bearer`), the value of `responseContent` can be used as the value of - `WWW-Authenticate` header. - The following is an example response which complies with RFC 6750. - ``` - HTTP/1.1 401 Unauthorized - WWW-Authenticate: {responseContent} - Cache-Control: no-store - Pragma: no-cache - ``` - - ## FORBIDDEN - - When the value of `action` is `FORBIDDEN`, it means that the access token does not cover the required - scopes or that the subject associated with the access token is different from the subject contained - in the request. - A response with HTTP status of "400 Bad Request" must be returned to the client application and - the content type must be `application/json`. - The value of `responseContent` is a string which describes the error in the format of [RFC - 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage), so if the - protected resource of the service implementation wants to return an error response to the client - application in the way that complies with RFC 6750 (in other words, if `accessTokenType` configuration - parameter of the service is Bearer), the value of `responseContent` can be used as the value of - `WWW-Authenticate` header. - The following is an example response which complies with RFC 6750. - ``` - HTTP/1.1 403 Forbidden - WWW-Authenticate: {responseContent} - Cache-Control: no-store - Pragma: no-cache - ``` - - ## OK - - When the value of `action` is `OK`, it means that the access token which the client application - presented is valid (= exists and has not expired). - The implementation of the protected resource endpoint is supposed to return the protected resource - to the client application. - When action is `OK`, the value of `responseContent` is `"Bearer error=\"invalid_request\""`. This - is the simplest string which can be used as the value of `WWW-Authenticate` header to indicate - "400 Bad Request". The implementation of the protected resource endpoint may use this string to - tell the client application that the request was bad (e.g. in case necessary request parameters - for the protected resource endpoint are missing). However, in such a case, the implementation - should generate a more informative error message to help developers of client applications. - The following is an example error response which complies with RFC 6750. - ``` - HTTP/1.1 400 Bad Request - WWW-Authenticate: {responseContent} - Cache-Control: no-store - Pragma: no-cache - ``` - Basically, The value of `responseContent` is a string which describes the error in the format of - [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage). So, if - the service has selected `Bearer` as the value of `accessTokenType` configuration parameter, the - value of `responseContent` can be used directly as the value of `WWW-Authenticate` header. However, - if the service has selected another different token type, the service has to generate error messages - for itself. - _**JWT-based access token**_ - Since version 2.1, Authlete provides a feature to issue access tokens in JWT format. This feature - can be enabled by setting a non-null value to the `accessTokenSignAlg` property of the service - (see the description of the Service class for details). `/api/auth/introspection` API can accept - access tokens in JWT format. However, note that the API does not return information contained in - a given JWT-based access token but returns information stored in the database record which corresponds - to the given JWT-based access token. Because attributes of the database record can be modified - after the access token is issued (for example, by using `/api/auth/token/update` API), information - returned by `/api/auth/introspection` API and information the given JWT-based access token holds - may be different. parameters: - in: path name: serviceId @@ -4598,81 +4646,87 @@ paths: description: | This API exists to help your authorization server provide its own introspection API which complies with [RFC 7662](https://tools.ietf.org/html/rfc7662) (OAuth 2.0 Token Introspection). + x-mint: + metadata: + description: "This API exists to help your authorization server provide its own introspection API which complies with [RFC 7662](https://tools.ietf.org/html/rfc7662) (OAuth 2.0 Token Introspection)." + content: | + + This API is supposed to be called from within the implementations of the introspection endpoint + of your service. The authorization server implementation should retrieve the value of `action` from + the response and take the following steps according to the value. + In general, a client application accesses a protected resource endpoint of a service with an access + token, and the implementation of the endpoint checks whether the presented access token has enough + privileges (= scopes) to access the protected resource before returning the protected resource to + the client application. To achieve this flow, the endpoint implementation has to know detailed + information about the access token. Authlete `/auth/introspection` API can be used to get such information. + The response from `/auth/introspection` API has some 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 + authorization server 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". + The value of `responseContent` is a JSON string which describes the error, so it can be used + as the entity body of the response if you want. Note that, however, [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662) does not mention anything about the response + body of error responses. + + --- + + The following illustrates an example response which the introspection endpoint of the authorization + server implementation generates and returns to the client application. + ``` + HTTP/1.1 500 Internal Server Error + Content-Type: application/json + {responseContent} + ``` + + ## BAD_REQUEST + + When the value of `action` is `BAD_REQUEST`, it means that the request from the client application + is invalid. This happens when the request from the client did not include the token request parameter. + See "[2.1. Introspection Request](https://datatracker.ietf.org/doc/html/rfc7662#section-2.1)" in + RFC 7662 for details about requirements for introspection requests. + The HTTP status of the response returned to the client application should be "400 Bad Request". + The value of `responseContent` is a JSON string which describes the error, so it can be used + as the entity body of the response if you want. Note that, however, [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662) + does not mention anything about the response body of error responses. + The following illustrates an example response which the introspection endpoint of the authorization + server implementation generates and returns to the client application. + ``` + HTTP/1.1 400 Bad Request + Content-Type: application/json + {responseContent} + ``` + + ## OK + + When the value of `action` is `OK`, the request from the client application is valid. + The HTTP status of the response returned to the client application must be "200 OK" and its content + type must be `application/json`. + The value of `responseContent` is a JSON string which complies with the introspection response + defined in "2.2. Introspection Response" in RFC7662. + + --- + + The following illustrates the response which the introspection endpoint of your authorization server + implementation should generate and return to the client application. + ``` + HTTP/1.1 200 OK + Content-Type: application/json + {responseContent} + ``` + Note that RFC 7662 says _"To prevent token scanning attacks, **the endpoint MUST also require some + form of authorization to access this endpoint**"_. This means that you have to protect your introspection + endpoint in some way or other. Authlete does not care about how your introspection endpoint is protected. + In most cases, as mentioned in RFC 7662, "401 Unauthorized" is a proper response when an introspection + request does not satisfy authorization requirements imposed by your introspection endpoint. + - This API is supposed to be called from within the implementations of the introspection endpoint - of your service. The authorization server implementation should retrieve the value of `action` from - the response and take the following steps according to the value. - In general, a client application accesses a protected resource endpoint of a service with an access - token, and the implementation of the endpoint checks whether the presented access token has enough - privileges (= scopes) to access the protected resource before returning the protected resource to - the client application. To achieve this flow, the endpoint implementation has to know detailed - information about the access token. Authlete `/auth/introspection` API can be used to get such information. - The response from `/auth/introspection` API has some 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 - authorization server 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". - The value of `responseContent` is a JSON string which describes the error, so it can be used - as the entity body of the response if you want. Note that, however, [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662) does not mention anything about the response - body of error responses. - - --- - - The following illustrates an example response which the introspection endpoint of the authorization - server implementation generates and returns to the client application. - ``` - HTTP/1.1 500 Internal Server Error - Content-Type: application/json - {responseContent} - ``` - - ## BAD_REQUEST - - When the value of `action` is `BAD_REQUEST`, it means that the request from the client application - is invalid. This happens when the request from the client did not include the token request parameter. - See "[2.1. Introspection Request](https://datatracker.ietf.org/doc/html/rfc7662#section-2.1)" in - RFC 7662 for details about requirements for introspection requests. - The HTTP status of the response returned to the client application should be "400 Bad Request". - The value of `responseContent` is a JSON string which describes the error, so it can be used - as the entity body of the response if you want. Note that, however, [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662) - does not mention anything about the response body of error responses. - The following illustrates an example response which the introspection endpoint of the authorization - server implementation generates and returns to the client application. - ``` - HTTP/1.1 400 Bad Request - Content-Type: application/json - {responseContent} - ``` - - ## OK - - When the value of `action` is `OK`, the request from the client application is valid. - The HTTP status of the response returned to the client application must be "200 OK" and its content - type must be `application/json`. - The value of `responseContent` is a JSON string which complies with the introspection response - defined in "2.2. Introspection Response" in RFC7662. - - --- - - The following illustrates the response which the introspection endpoint of your authorization server - implementation should generate and return to the client application. - ``` - HTTP/1.1 200 OK - Content-Type: application/json - {responseContent} - ``` - Note that RFC 7662 says _"To prevent token scanning attacks, **the endpoint MUST also require some - form of authorization to access this endpoint**"_. This means that you have to protect your introspection - endpoint in some way or other. Authlete does not care about how your introspection endpoint is protected. - In most cases, as mentioned in RFC 7662, "401 Unauthorized" is a proper response when an introspection - request does not satisfy authorization requirements imposed by your introspection endpoint. parameters: - in: path name: serviceId @@ -4746,124 +4800,130 @@ paths: summary: Process Revocation Request description: | This API revokes access tokens and refresh tokens. + x-mint: + metadata: + description: "This API revokes access tokens and refresh tokens." + content: | + + This API is supposed to be called from within the implementation of the revocation endpoint ([RFC + 7009](tools.ietf.org/html/rfc7009)) of the authorization server implementation in order to revoke + access tokens and refresh tokens. + The response from `/auth/revocation` API has some 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 + authorization server 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". + 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} + ``` + + ## INVALID_CLIENT + + When the value of `action` is `INVALID_CLIENT`, it means that authentication of the client failed. + In this case, the HTTP status of the response to the client application is either "400 Bad Request" + or "401 Unauthorized". The description about `invalid_client` shown below is an excerpt from [RFC + 6749](https://datatracker.ietf.org/doc/html/rfc6749). + + --- + + Client authentication failed (e.g., unknown client, no client authentication included, or unsupported + authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code + to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate + via the `Authorization` request header field, the authorization server MUST respond with an HTTP + 401 (Unauthorized) status code and include the `WWW-Authenticate` response header field matching + the authentication scheme used by the client. + + --- + + In either case, the value of `responseContent` is a JSON string which can be used as the entity + body of the response to the client application. + + --- + + 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} + ``` + + ``` + HTTP/1.1 401 Unauthorized + WWW-Authenticate: {challenge} + Content-Type: application/json + Cache-Control: no-store + Pragma: no-cache + {responseContent} + ``` + + ## BAD_REQUEST + + When the value of `action` is `BAD_REQUEST`, it means that the request from the client application + is invalid. + The HTTP status of the response returned to the client application must be "400 Bad Request" and + the content type must be `application/json`. [RFC 7009](https://datatracker.ietf.org/doc/html/rfc7009), + [2.2.1. Error Respons](https://datatracker.ietf.org/doc/html/rfc7009#section-2.2.1) states "The + error presentation conforms to the definition in [Section 5.2](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2) + of [[RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749)]." + 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 authorization server 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} + ``` + + ## OK + + When the value of `action` is `OK`, it means that the request from the client application is valid + and the presented token has been revoked successfully or if the client submitted an invalid token. + Note that invalid tokens do not cause an error. See [2.2. Revocation Response](https://datatracker.ietf.org/doc/html/rfc7009#section-2.2) for details. + The HTTP status of the response returned to the client application must be 200 OK. + If the original request from the client application contains callback request parameter and its + value is not empty, the content type should be `application/javascript` and the content should be + a JavaScript snippet for JSONP. + The value of `responseContent` is JavaScript snippet if the original request from the client application + contains callback request parameter and its value is not empty. Otherwise, the value of `responseContent` + is `null`. + ``` + HTTP/1.1 200 OK + Content-Type: application/javascript + Cache-Control: no-store + Pragma: no-cache + {responseContent} + ``` + - This API is supposed to be called from within the implementation of the revocation endpoint ([RFC - 7009](tools.ietf.org/html/rfc7009)) of the authorization server implementation in order to revoke - access tokens and refresh tokens. - The response from `/auth/revocation` API has some 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 - authorization server 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". - 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} - ``` - - ## INVALID_CLIENT - - When the value of `action` is `INVALID_CLIENT`, it means that authentication of the client failed. - In this case, the HTTP status of the response to the client application is either "400 Bad Request" - or "401 Unauthorized". The description about `invalid_client` shown below is an excerpt from [RFC - 6749](https://datatracker.ietf.org/doc/html/rfc6749). - - --- - - Client authentication failed (e.g., unknown client, no client authentication included, or unsupported - authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code - to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate - via the `Authorization` request header field, the authorization server MUST respond with an HTTP - 401 (Unauthorized) status code and include the `WWW-Authenticate` response header field matching - the authentication scheme used by the client. - - --- - - In either case, the value of `responseContent` is a JSON string which can be used as the entity - body of the response to the client application. - - --- - - 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} - ``` - - ``` - HTTP/1.1 401 Unauthorized - WWW-Authenticate: {challenge} - Content-Type: application/json - Cache-Control: no-store - Pragma: no-cache - {responseContent} - ``` - - ## BAD_REQUEST - - When the value of `action` is `BAD_REQUEST`, it means that the request from the client application - is invalid. - The HTTP status of the response returned to the client application must be "400 Bad Request" and - the content type must be `application/json`. [RFC 7009](https://datatracker.ietf.org/doc/html/rfc7009), - [2.2.1. Error Respons](https://datatracker.ietf.org/doc/html/rfc7009#section-2.2.1) states "The - error presentation conforms to the definition in [Section 5.2](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2) - of [[RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749)]." - 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 authorization server 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} - ``` - - ## OK - - When the value of `action` is `OK`, it means that the request from the client application is valid - and the presented token has been revoked successfully or if the client submitted an invalid token. - Note that invalid tokens do not cause an error. See [2.2. Revocation Response](https://datatracker.ietf.org/doc/html/rfc7009#section-2.2) for details. - The HTTP status of the response returned to the client application must be 200 OK. - If the original request from the client application contains callback request parameter and its - value is not empty, the content type should be `application/javascript` and the content should be - a JavaScript snippet for JSONP. - The value of `responseContent` is JavaScript snippet if the original request from the client application - contains callback request parameter and its value is not empty. Otherwise, the value of `responseContent` - is `null`. - ``` - HTTP/1.1 200 OK - Content-Type: application/javascript - Cache-Control: no-store - Pragma: no-cache - {responseContent} - ``` parameters: - in: path name: serviceId @@ -4938,122 +4998,128 @@ paths: summary: Process UserInfo Request description: | This API gathers information about a user. + x-mint: + metadata: + description: "This API gathers information about a user." + content: | + + This API is supposed to be called from within the implementation of the [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) + of the authorization server in order to get information about the user that is associated with + an access token. + The response from `/auth/userinfo` 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". + The value of `responseContent` is a string which describes the error in the format of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) + (OAuth 2.0 Bearer Token Usage) so the userinfo endpoint implementation can use the value of `responseContent` + as the value of`WWW-Authenticate` header. + The following is an example response which complies with RFC 6750. Note that OpenID Connect Core + 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo + Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details. + ``` + HTTP/1.1 500 Internal Server Error + WWW-Authenticate: {responseContent} + Cache-Control: no-store + Pragma: no-cache + ``` + + ## BAD_REQUEST + + When the value of `action` is `BAD_REQUEST`, it means that the request from the client application + does not contain an access token (= the request from the authorization server implementation to + Authlete does not contain `token` parameter). + The value of `responseContent` is a string which describes the error in the format + of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the + userinfo endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate` + header. + The following is an example response which complies with RFC 6750. Note that OpenID Connect Core + 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo + Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details. + ``` + HTTP/1.1 400 Bad Request + WWW-Authenticate: {responseContent} + Cache-Control: no-store + Pragma: no-cache + ``` + + ## UNAUTHORIZED + + When the value of `action` is `UNAUTHORIZED`, it means that the access token does not exist, has + expired, or is not associated with any subject (= any user account). + The value of `responseContent` is a string which describes the error in the format of [RFC + 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo + endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate` + header. + The following is an example response which complies with RFC 6750. Note that OpenID Connect Core + 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo + Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details. + ``` + HTTP/1.1 401 Unauthorized + WWW-Authenticate: {responseContent} + Cache-Control: no-store + Pragma: no-cache + ``` + + ## FORBIDDEN + + When the value of `action` is `FORBIDDEN`, it means that the access token does not include the + `openid` scope. + The value of `responseContent` is a string which describes the error in the format of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) + (OAuth 2.0 Bearer Token Usage) so the userinfo endpoint implementation can use the value of `responseContent` + as the value of`WWW-Authenticate` header. + The following is an example response which complies with RFC 6750. Note that OpenID Connect Core + 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo + Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details. + ``` + HTTP/1.1 403 Forbidden + WWW-Authenticate: {responseContent} + Cache-Control: no-store + Pragma: no-cache + ``` + + ## OK + + When the value of `action` is `OK`, it means that the access token which the client application + presented is valid. To be concrete, it means that the access token exists, has not expired, includes + the openid scope, and is associated with a subject (= a user account). + What the userinfo endpoint implementation should do next is to collect information about the subject + (user) from your database. The value of the `subject` is contained in the subject parameter in the + response from this API and the names of data, i.e., the claims names are contained in the claims + parameter in the response. For example, if the `subject` parameter is `joe123` and the claims + parameter is `[ "given_name", "email" ]`, you need to extract information about joe123's given name + and email from your database. + Then, call Authlete's `/auth/userinfo/issue` API with the collected information and the access token + in order to make Authlete generate an ID token. + If an error occurred during the above steps, generate an error response to the client. The response + should comply with [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750). For example, if the + subject associated with the access token does not exist in your database any longer, you may feel + like generating a response like below. + ``` + HTTP/1.1 400 Bad Request + WWW-Authenticate: Bearer error="invalid_token", + error_description="The subject associated with the access token does not exist." + Cache-Control: no-store + Pragma: no-cache + ``` + Also, an error might occur on database access. If you treat the error as an internal server error, + then the response would be like the following. + ``` + HTTP/1.1 500 Internal Server Error + WWW-Authenticate: Bearer error="server_error", + error_description="Failed to extract information about the subject from the database." + Cache-Control: no-store + Pragma: no-cache + ``` + - This API is supposed to be called from within the implementation of the [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) - of the authorization server in order to get information about the user that is associated with - an access token. - The response from `/auth/userinfo` 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". - The value of `responseContent` is a string which describes the error in the format of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) - (OAuth 2.0 Bearer Token Usage) so the userinfo endpoint implementation can use the value of `responseContent` - as the value of`WWW-Authenticate` header. - The following is an example response which complies with RFC 6750. Note that OpenID Connect Core - 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo - Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details. - ``` - HTTP/1.1 500 Internal Server Error - WWW-Authenticate: {responseContent} - Cache-Control: no-store - Pragma: no-cache - ``` - - ## BAD_REQUEST - - When the value of `action` is `BAD_REQUEST`, it means that the request from the client application - does not contain an access token (= the request from the authorization server implementation to - Authlete does not contain `token` parameter). - The value of `responseContent` is a string which describes the error in the format - of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the - userinfo endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate` - header. - The following is an example response which complies with RFC 6750. Note that OpenID Connect Core - 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo - Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details. - ``` - HTTP/1.1 400 Bad Request - WWW-Authenticate: {responseContent} - Cache-Control: no-store - Pragma: no-cache - ``` - - ## UNAUTHORIZED - - When the value of `action` is `UNAUTHORIZED`, it means that the access token does not exist, has - expired, or is not associated with any subject (= any user account). - The value of `responseContent` is a string which describes the error in the format of [RFC - 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo - endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate` - header. - The following is an example response which complies with RFC 6750. Note that OpenID Connect Core - 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo - Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details. - ``` - HTTP/1.1 401 Unauthorized - WWW-Authenticate: {responseContent} - Cache-Control: no-store - Pragma: no-cache - ``` - - ## FORBIDDEN - - When the value of `action` is `FORBIDDEN`, it means that the access token does not include the - `openid` scope. - The value of `responseContent` is a string which describes the error in the format of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) - (OAuth 2.0 Bearer Token Usage) so the userinfo endpoint implementation can use the value of `responseContent` - as the value of`WWW-Authenticate` header. - The following is an example response which complies with RFC 6750. Note that OpenID Connect Core - 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo - Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details. - ``` - HTTP/1.1 403 Forbidden - WWW-Authenticate: {responseContent} - Cache-Control: no-store - Pragma: no-cache - ``` - - ## OK - - When the value of `action` is `OK`, it means that the access token which the client application - presented is valid. To be concrete, it means that the access token exists, has not expired, includes - the openid scope, and is associated with a subject (= a user account). - What the userinfo endpoint implementation should do next is to collect information about the subject - (user) from your database. The value of the `subject` is contained in the subject parameter in the - response from this API and the names of data, i.e., the claims names are contained in the claims - parameter in the response. For example, if the `subject` parameter is `joe123` and the claims - parameter is `[ "given_name", "email" ]`, you need to extract information about joe123's given name - and email from your database. - Then, call Authlete's `/auth/userinfo/issue` API with the collected information and the access token - in order to make Authlete generate an ID token. - If an error occurred during the above steps, generate an error response to the client. The response - should comply with [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750). For example, if the - subject associated with the access token does not exist in your database any longer, you may feel - like generating a response like below. - ``` - HTTP/1.1 400 Bad Request - WWW-Authenticate: Bearer error="invalid_token", - error_description="The subject associated with the access token does not exist." - Cache-Control: no-store - Pragma: no-cache - ``` - Also, an error might occur on database access. If you treat the error as an internal server error, - then the response would be like the following. - ``` - HTTP/1.1 500 Internal Server Error - WWW-Authenticate: Bearer error="server_error", - error_description="Failed to extract information about the subject from the database." - Cache-Control: no-store - Pragma: no-cache - ``` parameters: - in: path name: serviceId @@ -5132,127 +5198,133 @@ paths: summary: Issue UserInfo Response description: | This API generates an ID token. + x-mint: + metadata: + description: "This API generates an ID token." + content: | + + This API is supposed to be called from within the implementation of the [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) + of the authorization server in order to generate an ID token. Before calling this API, a valid + response from `/auth/userinfo` API must be obtained. Then, call this API with the access token + contained in the response and the claims values of the user (subject) associated with the access + token. See **OK** written in the description of `/auth/userinfo` API for details. + The response from `/auth/userinfo/issue` 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". + The parameter `responseContent` returns a string which describes the error in the format of [RFC + 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo + endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate` + header. + The following is an example response which complies with RFC 6750. Note that OpenID Connect Core + 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo + Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details. + ``` + HTTP/1.1 500 Internal Server Error + WWW-Authenticate: {responseContent} + Cache-Control: no-store + Pragma: no-cache + ``` + + ## BAD_REQUEST + + When the value of `action` is `BAD_REQUEST`, it means that the request from the client application + does not contain an access token (= the request from the authorization server implementation to + Authlete does not contain `token` parameter). + The parameter `responseContent` returns a string which describes the error in the format of [RFC + 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo + endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate` + header. + The following is an example response which complies with RFC 6750. Note that OpenID Connect Core + 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo + Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details. + ``` + HTTP/1.1 400 Bad Request + WWW-Authenticate: {responseContent} + Cache-Control: no-store + Pragma: no-cache + ``` + + ## UNAUTHORIZED + + When the value of `action` is `UNAUTHORIZED`, it means that the access token does not exist, has + expired, or is not associated with any subject (= any user account). + The parameter `responseContent` returns a string which describes the error in the format of [RFC + 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo + endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate` + header. + The following is an example response which complies with RFC 6750. Note that OpenID Connect Core + 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo + Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details. + ``` + HTTP/1.1 401 Unauthorized + WWW-Authenticate: {responseContent} + Cache-Control: no-store + Pragma: no-cache + ``` + + ## FORBIDDEN + + When the value of `action` is `FORBIDDEN`, it means that the access token does not include the + `openid` scope. + The parameter `responseContent` returns a string which describes the error in the format of [RFC + 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo + endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate` + header. + The following is an example response which complies with RFC 6750. Note that OpenID Connect Core + 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo + Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details. + ``` + HTTP/1.1 403 Forbidden + WWW-Authenticate: {responseContent} + Cache-Control: no-store + Pragma: no-cache + ``` + + ## JSON + + When the value of `action` is `JSON`, it means that the access token which the client application + presented is valid and an ID token was successfully generated in the format of JSON. + The userinfo endpoint implementation is expected to generate a response to the client application. + The content type of the response must be `application/json` and the response body must be an ID + token in JSON format. + The value of `responseContent` is the ID token in JSON format when `action` is `JSON`, so + a response to the client can be built like below. + ``` + HTTP/1.1 200 OK + Cache-Control: no-store + Pragma: no-cache + Content-Type: application/json;charset=UTF-8 + {responseContent} + ``` + + ## JWT + + When the value of `action` is `JWT`, it means that the access token which the client application + presented is valid and an ID token was successfully generated in the format of JWT (JSON Web Token) + ([RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519)). + The userinfo endpoint implementation is expected to generate a response to the client application. + The content type of the response must be `application/jwt` and the response body must be an ID + token in JWT format. + The value of `responseContent` is the ID token in JSON format when `action` is `JWT`, so a response + to the client can be built like below. + ``` + HTTP/1.1 200 OK + Cache-Control: no-store + Pragma: no-cache + Content-Type: application/jwt + {responseContent} + ``` + - This API is supposed to be called from within the implementation of the [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) - of the authorization server in order to generate an ID token. Before calling this API, a valid - response from `/auth/userinfo` API must be obtained. Then, call this API with the access token - contained in the response and the claims values of the user (subject) associated with the access - token. See **OK** written in the description of `/auth/userinfo` API for details. - The response from `/auth/userinfo/issue` 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". - The parameter `responseContent` returns a string which describes the error in the format of [RFC - 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo - endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate` - header. - The following is an example response which complies with RFC 6750. Note that OpenID Connect Core - 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo - Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details. - ``` - HTTP/1.1 500 Internal Server Error - WWW-Authenticate: {responseContent} - Cache-Control: no-store - Pragma: no-cache - ``` - - ## BAD_REQUEST - - When the value of `action` is `BAD_REQUEST`, it means that the request from the client application - does not contain an access token (= the request from the authorization server implementation to - Authlete does not contain `token` parameter). - The parameter `responseContent` returns a string which describes the error in the format of [RFC - 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo - endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate` - header. - The following is an example response which complies with RFC 6750. Note that OpenID Connect Core - 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo - Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details. - ``` - HTTP/1.1 400 Bad Request - WWW-Authenticate: {responseContent} - Cache-Control: no-store - Pragma: no-cache - ``` - - ## UNAUTHORIZED - - When the value of `action` is `UNAUTHORIZED`, it means that the access token does not exist, has - expired, or is not associated with any subject (= any user account). - The parameter `responseContent` returns a string which describes the error in the format of [RFC - 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo - endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate` - header. - The following is an example response which complies with RFC 6750. Note that OpenID Connect Core - 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo - Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details. - ``` - HTTP/1.1 401 Unauthorized - WWW-Authenticate: {responseContent} - Cache-Control: no-store - Pragma: no-cache - ``` - - ## FORBIDDEN - - When the value of `action` is `FORBIDDEN`, it means that the access token does not include the - `openid` scope. - The parameter `responseContent` returns a string which describes the error in the format of [RFC - 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo - endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate` - header. - The following is an example response which complies with RFC 6750. Note that OpenID Connect Core - 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo - Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details. - ``` - HTTP/1.1 403 Forbidden - WWW-Authenticate: {responseContent} - Cache-Control: no-store - Pragma: no-cache - ``` - - ## JSON - - When the value of `action` is `JSON`, it means that the access token which the client application - presented is valid and an ID token was successfully generated in the format of JSON. - The userinfo endpoint implementation is expected to generate a response to the client application. - The content type of the response must be `application/json` and the response body must be an ID - token in JSON format. - The value of `responseContent` is the ID token in JSON format when `action` is `JSON`, so - a response to the client can be built like below. - ``` - HTTP/1.1 200 OK - Cache-Control: no-store - Pragma: no-cache - Content-Type: application/json;charset=UTF-8 - {responseContent} - ``` - - ## JWT - - When the value of `action` is `JWT`, it means that the access token which the client application - presented is valid and an ID token was successfully generated in the format of JWT (JSON Web Token) - ([RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519)). - The userinfo endpoint implementation is expected to generate a response to the client application. - The content type of the response must be `application/jwt` and the response body must be an ID - token in JWT format. - The value of `responseContent` is the ID token in JSON format when `action` is `JWT`, so a response - to the client can be built like below. - ``` - HTTP/1.1 200 OK - Cache-Control: no-store - Pragma: no-cache - Content-Type: application/jwt - {responseContent} - ``` parameters: - in: path name: serviceId @@ -5858,74 +5930,80 @@ paths: Register a client. This API is supposed to be used to implement a client registration endpoint that complies with [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591) (OAuth 2.0 Dynamic Client Registration Protocol). + x-mint: + metadata: + description: "Register a client. This API is supposed to be used to implement a client registration endpoint that complies with [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591) (OAuth 2.0 Dynamic Client Registration Protocol)." + content: | + + This API is supposed to be called from the within the implementation of the client registration + endpoint of the authorization server. The authorization server implementation should retrieve + the value of `action` from the response and take the following steps according to the value. + + ## INTERNAL_SERVER_ERROR + + When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the API call from the authorization + server implementation was wrong or that an error occurred in Authlete. + In either case, from a viewpoint of the client or developer, it is an error on the server side. + Therefore, the authorization server implementation should generate a response with "500 Internal + Server Error"s and `application/json`. + 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 authorization server implementation should generate + and return to the client or developer. + ``` + 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 or developer since + "500 Internal Server Error" is not required by the specification. + + ## BAD_REQUEST + + When the value of `action` is `BAD_REQUEST`, it means that the request from the client or developer + was wrong. + The authorization server implementation should generate a response with "400 Bad Request" and `application/json`. + 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 authorization server implementation should generate + and return to the client or developer. + ``` + HTTP/1.1 400 Bad Request + Content-Type: application/json + Cache-Control: no-store + Pragma: no-cache + {responseContent} + ``` + + ## CREATED + + When the value of `action` is `CREATED`, it means that the request from the client or developer is + valid. + The authorization server implementation should generate a response to the client or developer with + "201 CREATED" and `application/json`. + The `responseContent` a JSON string which can be used as the entity body of the response. + + --- + + The following illustrates the response which the authorization server implementation should generate + and return to the client or developer. + ``` + HTTP/1.1 201 CREATED + Content-Type: application/json + Cache-Control: no-store + Pragma: no-cache + {responseContent} + ``` + - This API is supposed to be called from the within the implementation of the client registration - endpoint of the authorization server. The authorization server implementation should retrieve - the value of `action` from the response and take the following steps according to the value. - - ## INTERNAL_SERVER_ERROR - - When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the API call from the authorization - server implementation was wrong or that an error occurred in Authlete. - In either case, from a viewpoint of the client or developer, it is an error on the server side. - Therefore, the authorization server implementation should generate a response with "500 Internal - Server Error"s and `application/json`. - 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 authorization server implementation should generate - and return to the client or developer. - ``` - 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 or developer since - "500 Internal Server Error" is not required by the specification. - - ## BAD_REQUEST - - When the value of `action` is `BAD_REQUEST`, it means that the request from the client or developer - was wrong. - The authorization server implementation should generate a response with "400 Bad Request" and `application/json`. - 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 authorization server implementation should generate - and return to the client or developer. - ``` - HTTP/1.1 400 Bad Request - Content-Type: application/json - Cache-Control: no-store - Pragma: no-cache - {responseContent} - ``` - - ## CREATED - - When the value of `action` is `CREATED`, it means that the request from the client or developer is - valid. - The authorization server implementation should generate a response to the client or developer with - "201 CREATED" and `application/json`. - The `responseContent` a JSON string which can be used as the entity body of the response. - - --- - - The following illustrates the response which the authorization server implementation should generate - and return to the client or developer. - ``` - HTTP/1.1 201 CREATED - Content-Type: application/json - Cache-Control: no-store - Pragma: no-cache - {responseContent} - ``` parameters: - in: path name: serviceId @@ -6026,98 +6104,104 @@ paths: Get a dynamically registered client. This API is supposed to be used to implement a client registration management endpoint that complies with [RFC 7592](https://datatracker.ietf.org/doc/html/rfc7592) (OAuth 2.0 Dynamic Registration Management). + x-mint: + metadata: + description: "Get a dynamically registered client. This API is supposed to be used to implement a client registration management endpoint that complies with [RFC 7592](https://datatracker.ietf.org/doc/html/rfc7592) (OAuth 2.0 Dynamic Registration Management)." + content: | + + This API is supposed to be called from the within the implementation of the client registration + management endpoint of the authorization server. The authorization server implementation should + retrieve the value of `action` from the response and take the following steps according to the value. + + ## INTERNAL_SERVER_ERROR + + When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the API call from the authorization + server implementation was wrong or that an error occurred in Authlete. + In either case, from a viewpoint of the client or developer, it is an error on the server side. + Therefore, the authorization server implementation should generate a response to the client or developer + with "500 Internal Server Error"s and `application/json`. + 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 authorization server implementation should generate + and return to the client or developer. + ``` + 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 or developer since + "500 Internal Server Error" is not required by the specification. + + ## BAD_REQUEST + + When the value of `action` is `BAD_REQUEST`, it means that the request from the client or developer + was wrong. + The authorization server implementation should generate a response to the client or developer with + "400 Bad Request" and `application/json`. + 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 authorization server implementation should generate + and return to the client or developer. + ``` + HTTP/1.1 400 Bad Request + Content-Type: application/json + Cache-Control: no-store + Pragma: no-cache + {responseContent} + ``` + + ## UNAUTHORIZED + + When the value of `action` is `UNAUTHORIZED`, it means that the registration access token used by + the client configuration request (RFC 7592) is invalid, or the client application which the token + is tied to does not exist any longer or is invalid. + The HTTP status of the response returned to the client application must be "401 Unauthorized" and + the content type must be `application/json`. + 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 endpoint implementation should generate and return + to the client application. + ``` + HTTP/1.1 401 Unauthorized + Content-Type: application/json + Cache-Control: no-store + Pragma: no-cache + {responseContent} + ``` + NOTE: The `UNAUTHORIZED` value was added in October, 2021. See the description of + `Service.unauthorizedOnClientConfigSupported` for details. + + ## OK + + When the value of `action` is `OK`, it means that the request from the client or developer is valid. + The authorization server implementation should generate a response to the client or developer with + "200 OK" and `application/json`. + The `responseContent` a JSON string which can be used as the entity body of the response. + + --- + + The following illustrates the response which the authorization server implementation should generate + and return to the client or developer. + ``` + HTTP/1.1 200 OK + Content-Type: application/json + Cache-Control: no-store + Pragma: no-cache + {responseContent} + ``` + - This API is supposed to be called from the within the implementation of the client registration - management endpoint of the authorization server. The authorization server implementation should - retrieve the value of `action` from the response and take the following steps according to the value. - - ## INTERNAL_SERVER_ERROR - - When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the API call from the authorization - server implementation was wrong or that an error occurred in Authlete. - In either case, from a viewpoint of the client or developer, it is an error on the server side. - Therefore, the authorization server implementation should generate a response to the client or developer - with "500 Internal Server Error"s and `application/json`. - 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 authorization server implementation should generate - and return to the client or developer. - ``` - 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 or developer since - "500 Internal Server Error" is not required by the specification. - - ## BAD_REQUEST - - When the value of `action` is `BAD_REQUEST`, it means that the request from the client or developer - was wrong. - The authorization server implementation should generate a response to the client or developer with - "400 Bad Request" and `application/json`. - 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 authorization server implementation should generate - and return to the client or developer. - ``` - HTTP/1.1 400 Bad Request - Content-Type: application/json - Cache-Control: no-store - Pragma: no-cache - {responseContent} - ``` - - ## UNAUTHORIZED - - When the value of `action` is `UNAUTHORIZED`, it means that the registration access token used by - the client configuration request (RFC 7592) is invalid, or the client application which the token - is tied to does not exist any longer or is invalid. - The HTTP status of the response returned to the client application must be "401 Unauthorized" and - the content type must be `application/json`. - 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 endpoint implementation should generate and return - to the client application. - ``` - HTTP/1.1 401 Unauthorized - Content-Type: application/json - Cache-Control: no-store - Pragma: no-cache - {responseContent} - ``` - NOTE: The `UNAUTHORIZED` value was added in October, 2021. See the description of - `Service.unauthorizedOnClientConfigSupported` for details. - - ## OK - - When the value of `action` is `OK`, it means that the request from the client or developer is valid. - The authorization server implementation should generate a response to the client or developer with - "200 OK" and `application/json`. - The `responseContent` a JSON string which can be used as the entity body of the response. - - --- - - The following illustrates the response which the authorization server implementation should generate - and return to the client or developer. - ``` - HTTP/1.1 200 OK - Content-Type: application/json - Cache-Control: no-store - Pragma: no-cache - {responseContent} - ``` parameters: - in: path name: serviceId @@ -6222,98 +6306,104 @@ paths: Update a dynamically registered client. This API is supposed to be used to implement a client registration management endpoint that complies with [RFC 7592](https://datatracker.ietf.org/doc/html/rfc7592) (OAuth 2.0 Dynamic Registration Management). + x-mint: + metadata: + description: "Update a dynamically registered client. This API is supposed to be used to implement a client registration management endpoint that complies with [RFC 7592](https://datatracker.ietf.org/doc/html/rfc7592) (OAuth 2.0 Dynamic Registration Management)." + content: | + + This API is supposed to be called from the within the implementation of the client registration + management endpoint of the authorization server. The authorization server implementation should + retrieve the value of `action` from the response and take the following steps according to the value. + + ## INTERNAL_SERVER_ERROR + + When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the API call from the authorization + server implementation was wrong or that an error occurred in Authlete. + In either case, from a viewpoint of the client or developer, it is an error on the server side. + Therefore, the authorization server implementation should generate a response with "500 Internal + Server Error"s and `application/json`. + 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 authorization server implementation should generate + and return to the client or developer. + ``` + 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 or developer since + "500 Internal Server Error" is not required by the specification. + + ## BAD_REQUEST + + When the value of `action` is `BAD_REQUEST`, it means that the request from the client or developer + was wrong. + The authorization server implementation should generate a response with "400 Bad Request" and `application/json`. + 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 authorization server implementation should generate + and return to the client or developer. + ``` + HTTP/1.1 400 Bad Request + Content-Type: application/json + Cache-Control: no-store + Pragma: no-cache + {responseContent} + ``` + + ## UNAUTHORIZED + + When the value of `action` is `UNAUTHORIZED`, it means that the registration access token used by + the client configuration request (RFC 7592) is invalid, or the client application which the token + is tied to does not exist any longer or is invalid. + The HTTP status of the response returned to the client application must be "401 Unauthorized" and + the content type must be `application/json`. + 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 endpoint implementation should generate and return + to the client application. + ``` + HTTP/1.1 401 Unauthorized + Content-Type: application/json + Cache-Control: no-store + Pragma: no-cache + {responseContent} + ``` + NOTE: The `UNAUTHORIZED` value was added in October, 2021. See the description of + `Service.unauthorizedOnClientConfigSupported` for details. + + ## UPDATED + + When the value of `action` is `UPDATED`, it means that the request from the client or developer is + valid. + The authorization server implementation should generate a response to the client or developer with + "200 OK" and `application/json`. + The `responseContent` a JSON string which can be used as the entity body of the response. + + --- + + The following illustrates the response which the authorization server implementation should generate + and return to the client or developer. + ``` + HTTP/1.1 200 OK + Content-Type: application/json + Cache-Control: no-store + Pragma: no-cache + {responseContent} + ``` + - This API is supposed to be called from the within the implementation of the client registration - management endpoint of the authorization server. The authorization server implementation should - retrieve the value of `action` from the response and take the following steps according to the value. - - ## INTERNAL_SERVER_ERROR - - When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the API call from the authorization - server implementation was wrong or that an error occurred in Authlete. - In either case, from a viewpoint of the client or developer, it is an error on the server side. - Therefore, the authorization server implementation should generate a response with "500 Internal - Server Error"s and `application/json`. - 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 authorization server implementation should generate - and return to the client or developer. - ``` - 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 or developer since - "500 Internal Server Error" is not required by the specification. - - ## BAD_REQUEST - - When the value of `action` is `BAD_REQUEST`, it means that the request from the client or developer - was wrong. - The authorization server implementation should generate a response with "400 Bad Request" and `application/json`. - 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 authorization server implementation should generate - and return to the client or developer. - ``` - HTTP/1.1 400 Bad Request - Content-Type: application/json - Cache-Control: no-store - Pragma: no-cache - {responseContent} - ``` - - ## UNAUTHORIZED - - When the value of `action` is `UNAUTHORIZED`, it means that the registration access token used by - the client configuration request (RFC 7592) is invalid, or the client application which the token - is tied to does not exist any longer or is invalid. - The HTTP status of the response returned to the client application must be "401 Unauthorized" and - the content type must be `application/json`. - 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 endpoint implementation should generate and return - to the client application. - ``` - HTTP/1.1 401 Unauthorized - Content-Type: application/json - Cache-Control: no-store - Pragma: no-cache - {responseContent} - ``` - NOTE: The `UNAUTHORIZED` value was added in October, 2021. See the description of - `Service.unauthorizedOnClientConfigSupported` for details. - - ## UPDATED - - When the value of `action` is `UPDATED`, it means that the request from the client or developer is - valid. - The authorization server implementation should generate a response to the client or developer with - "200 OK" and `application/json`. - The `responseContent` a JSON string which can be used as the entity body of the response. - - --- - - The following illustrates the response which the authorization server implementation should generate - and return to the client or developer. - ``` - HTTP/1.1 200 OK - Content-Type: application/json - Cache-Control: no-store - Pragma: no-cache - {responseContent} - ``` parameters: - in: path name: serviceId @@ -6422,95 +6512,101 @@ paths: Delete a dynamically registered client. This API is supposed to be used to implement a client registration management endpoint that complies with [RFC 7592](https://datatracker.ietf.org/doc/html/rfc7592) (OAuth 2.0 Dynamic Registration Management). + x-mint: + metadata: + description: "Delete a dynamically registered client. This API is supposed to be used to implement a client registration management endpoint that complies with [RFC 7592](https://datatracker.ietf.org/doc/html/rfc7592) (OAuth 2.0 Dynamic Registration Management)." + content: | + + This API is supposed to be called from the within the implementation of the client registration + management endpoint of the authorization server. The authorization server implementation should + retrieve the value of `action` from the response and take the following steps according to the value. + + ## INTERNAL_SERVER_ERROR + + When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the API call from the authorization + server implementation was wrong or that an error occurred in Authlete. + In either case, from a viewpoint of the client or developer, it is an error on the server side. + Therefore, the authorization server implementation should generate a response with "500 Internal + Server Error"s and `application/json`. + 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 authorization server implementation should generate + and return to the client or developer. + ``` + 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 or developer since + "500 Internal Server Error" is not required by the specification. + + ## BAD_REQUEST + + When the value of `action` is `BAD_REQUEST`, it means that the request from the client or developer + was wrong. + The authorization server implementation should generate a response with "400 Bad Request" and `application/json`. + 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 authorization server implementation should generate + and return to the client or developer. + ``` + HTTP/1.1 400 Bad Request + Content-Type: application/json + Cache-Control: no-store + Pragma: no-cache + {responseContent} + ``` + + ## UNAUTHORIZED + + When the value of `action` is `UNAUTHORIZED`, it means that the registration access token used by + the client configuration request (RFC 7592) is invalid, or the client application which the token + is tied to does not exist any longer or is invalid. + The HTTP status of the response returned to the client application must be "401 Unauthorized" and + the content type must be `application/json`. + 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 endpoint implementation should generate and return + to the client application. + ``` + HTTP/1.1 401 Unauthorized + Content-Type: application/json + Cache-Control: no-store + Pragma: no-cache + {responseContent} + ``` + NOTE: The `UNAUTHORIZED` value was added in October, 2021. See the description of + `Service.unauthorizedOnClientConfigSupported` for details. + + ## DELETED + + When the value of `action` is `DELETED`, it means that the request from the client or developer is + valid. + The authorization server implementation should generate a response to the client or developer with + "204 No Content". + + --- + + The following illustrates the response which the authorization server implementation should generate + and return to the client or developer. + ``` + HTTP/1.1 204 No Content + Cache-Control: no-store + Pragma: no-cache + ``` + - This API is supposed to be called from the within the implementation of the client registration - management endpoint of the authorization server. The authorization server implementation should - retrieve the value of `action` from the response and take the following steps according to the value. - - ## INTERNAL_SERVER_ERROR - - When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the API call from the authorization - server implementation was wrong or that an error occurred in Authlete. - In either case, from a viewpoint of the client or developer, it is an error on the server side. - Therefore, the authorization server implementation should generate a response with "500 Internal - Server Error"s and `application/json`. - 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 authorization server implementation should generate - and return to the client or developer. - ``` - 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 or developer since - "500 Internal Server Error" is not required by the specification. - - ## BAD_REQUEST - - When the value of `action` is `BAD_REQUEST`, it means that the request from the client or developer - was wrong. - The authorization server implementation should generate a response with "400 Bad Request" and `application/json`. - 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 authorization server implementation should generate - and return to the client or developer. - ``` - HTTP/1.1 400 Bad Request - Content-Type: application/json - Cache-Control: no-store - Pragma: no-cache - {responseContent} - ``` - - ## UNAUTHORIZED - - When the value of `action` is `UNAUTHORIZED`, it means that the registration access token used by - the client configuration request (RFC 7592) is invalid, or the client application which the token - is tied to does not exist any longer or is invalid. - The HTTP status of the response returned to the client application must be "401 Unauthorized" and - the content type must be `application/json`. - 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 endpoint implementation should generate and return - to the client application. - ``` - HTTP/1.1 401 Unauthorized - Content-Type: application/json - Cache-Control: no-store - Pragma: no-cache - {responseContent} - ``` - NOTE: The `UNAUTHORIZED` value was added in October, 2021. See the description of - `Service.unauthorizedOnClientConfigSupported` for details. - - ## DELETED - - When the value of `action` is `DELETED`, it means that the request from the client or developer is - valid. - The authorization server implementation should generate a response to the client or developer with - "204 No Content". - - --- - - The following illustrates the response which the authorization server implementation should generate - and return to the client or developer. - ``` - HTTP/1.1 204 No Content - Cache-Control: no-store - Pragma: no-cache - ``` parameters: - in: path name: serviceId @@ -6590,268 +6686,274 @@ paths: This API parses request parameters of a [backchannel authentication request](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_request) and returns necessary data for the authorization server implementation to process the backchannel authentication request further. + x-mint: + metadata: + description: "This API parses request parameters of a [backchannel authentication request](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_request) and returns necessary data for the authorization server implementation to process the backchannel authentication request further." + content: | + + This API is supposed to be called from within the implementation of the [backchannel authentication + endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_endpoint) + of the service. The endpoint implementation must extract the request parameters from the + backchannel authentication request from the client application and pass them as the value of parameters + request parameter for Authlete's `/backchannel/authentication` API. + The value of parameters is the entire entity body (which is formatted in `application/x-www-form-urlencoded`) + of the request from the client application. + The following code snippet is an example in JAX-RS showing how to extract request parameters from + the backchannel authentication request. + ```java + @POST + @Consumes(MediaType.APPLICATION_FORM_URLENCODED) + public Response post(String parameters) + { + // 'parameters' is the entity body of the backchannel authentication request. + ...... + } + ``` + The endpoint implementation does not have to parse the request parameters from the client application + because Authlete's `/backchannel/authentication` API does it. + The response from `/backchannel/authentication` 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" and `application/json`. + 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} + ``` - This API is supposed to be called from within the implementation of the [backchannel authentication - endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_endpoint) - of the service. The endpoint implementation must extract the request parameters from the - backchannel authentication request from the client application and pass them as the value of parameters - request parameter for Authlete's `/backchannel/authentication` API. - The value of parameters is the entire entity body (which is formatted in `application/x-www-form-urlencoded`) - of the request from the client application. - The following code snippet is an example in JAX-RS showing how to extract request parameters from - the backchannel authentication request. - ```java - @POST - @Consumes(MediaType.APPLICATION_FORM_URLENCODED) - public Response post(String parameters) - { - // 'parameters' is the entity body of the backchannel authentication request. - ...... - } - ``` - The endpoint implementation does not have to parse the request parameters from the client application - because Authlete's `/backchannel/authentication` API does it. - The response from `/backchannel/authentication` 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" and `application/json`. - 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} - ``` - - ## BAD_REQUEST - - When the value of `action` is `BAD_REQUEST`, it means that the request from the client application - is invalid. - The authorization server implementation should generate a response to the client application with - "400 Bad Request" and `application/json`. - 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} - ``` - - ## UNAUTHORIZED - - When the value of `action` is `UNAUTHORIZED`, it means that client authentication of the backchannel - authentication request failed. Note that client authentication is always required at the backchannel - authentication endpoint. This implies that public clients are not allowed to use the backchannel - authentication endpoint. - The authorization server implementation should generate a response to the client application with - "401 Unauthorized" and `application/json`. - 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 must generate and return - to the client application. - ``` - HTTP/1.1 401 Unauthorized - WWW-Authenticate: (challenge) - Content-Type: application/json - Cache-Control: no-store - Pragma: no-cache - {responseContent} - ``` - - ## USER_IDENTIFICATION - - When the value of `action` is `USER_IDENTIFICATION`, it means that the backchannel authentication - request from the client application is valid. The authorization server implementation has to follow - the steps below. - - **[1] END-USER IDENTIFICATION** - - The first step is to determine the subject (= unique identifier) of the end-user from whom the - client application wants to get authorization. - According to the CIBA specification, a backchannel authentication request contains one (and only - one) of the `login_hint_token`, `id_token_hint` and `login_hint` request parameters as a hint - by which the authorization server identifies the subject of an end-user. - The authorization server implementation can know which hint is included in the backchannel authentication - request by the `hintType` parameter. For example, when the value of the parameter `LOGIN_HINT`, - it means that the backchannel authentication request contains the `login_hint` request parameter - as a hint. - The value of the `hint` parameter is the value of the hint. For example, when the value of the - `hintType` parameter is `LOGIN_HINT`, The value of the `hint` parameter is the value of the `login_hint` - request parameter. - It is up to the authorization server implementation how to determine the subject of the end-user - from the hint. Only when the `id_token_hint` request parameter is used, authorization server - implementation can use the sub response parameter, which holds the value of the sub claim in the - `id_token_hint` request parameter. + ## BAD_REQUEST - **[2] END-USER IDENTIFICATION ERROR** + When the value of `action` is `BAD_REQUEST`, it means that the request from the client application + is invalid. + The authorization server implementation should generate a response to the client application with + "400 Bad Request" and `application/json`. + 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} + ``` + + ## UNAUTHORIZED + + When the value of `action` is `UNAUTHORIZED`, it means that client authentication of the backchannel + authentication request failed. Note that client authentication is always required at the backchannel + authentication endpoint. This implies that public clients are not allowed to use the backchannel + authentication endpoint. + The authorization server implementation should generate a response to the client application with + "401 Unauthorized" and `application/json`. + 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 must generate and return + to the client application. + ``` + HTTP/1.1 401 Unauthorized + WWW-Authenticate: (challenge) + Content-Type: application/json + Cache-Control: no-store + Pragma: no-cache + {responseContent} + ``` + + ## USER_IDENTIFICATION + + When the value of `action` is `USER_IDENTIFICATION`, it means that the backchannel authentication + request from the client application is valid. The authorization server implementation has to follow + the steps below. + + **[1] END-USER IDENTIFICATION** + + The first step is to determine the subject (= unique identifier) of the end-user from whom the + client application wants to get authorization. + According to the CIBA specification, a backchannel authentication request contains one (and only + one) of the `login_hint_token`, `id_token_hint` and `login_hint` request parameters as a hint + by which the authorization server identifies the subject of an end-user. + The authorization server implementation can know which hint is included in the backchannel authentication + request by the `hintType` parameter. For example, when the value of the parameter `LOGIN_HINT`, + it means that the backchannel authentication request contains the `login_hint` request parameter + as a hint. + The value of the `hint` parameter is the value of the hint. For example, when the value of the + `hintType` parameter is `LOGIN_HINT`, The value of the `hint` parameter is the value of the `login_hint` + request parameter. + It is up to the authorization server implementation how to determine the subject of the end-user + from the hint. Only when the `id_token_hint` request parameter is used, authorization server + implementation can use the sub response parameter, which holds the value of the sub claim in the + `id_token_hint` request parameter. + + **[2] END-USER IDENTIFICATION ERROR** + + There are some cases where the authorization server implementation encounters an error during + the user identification process. In any error case, the service implementation has to return an + HTTP response with the error response parameter to the client application. The following is an + example of such error responses. + ``` + HTTP/1.1 400 Bad Request + Content-Type: application/json + Cache-Control: no-store + Pragma: no-cache + { "error":"unknown_user_id" } + ``` + Authlete provides `/backchannel/authentication/fail` API that builds the response body (JSON) + of an error response. However, because it is easy to build an error response manually, you may + choose not to call the API. One good thing in using the API is that the API call can trigger + deletion of the ticket which has been issued from Authlete's `/backchannel/authentication` API. + If you don't call `/backchannel/authentication/fail` API, the ticket will continue to exist in + the database until it is cleaned up by the batch program after the ticket expires. + Possible error cases that the authorization server implementation itself has to handle are as + follows. Other error cases have already been covered by `/backchannel/authentication` API. + - `expired_login_hint_token` + The authorization server implementation detected that the hint presented by the `login_hint_token` + request parameter has expired. + Note that the format of `login_hint_token` is not described in the CIBA Core spec at all and + so there is no consensus on how to detect expiration of `login_hint_token`. Interpretation + of `login_hint_token` is left to each authorization server implementation. + - `unknown_user_id` + The authorization server implementation could not determine the subject of the end-user by + the presented hint. + - `unauthorized_client` + The authorization server implementation has custom rules to reject backchannel authentication + requests from some particular clients and found that the client which has made the backchannel + authentication request is one of the particular clients. + Note that `/backchannel/authentication` API does not return `action=USER_IDENTIFICATION` in + cases where the client does not exist or client authentication has failed. Therefore, the + authorization server implementation will never have to use the error code `unauthorized_client` + unless the server has intentionally implemented custom rules to reject backchannel authentication + requests based on clients. + - `missing_user_code` + The authorization server implementation has custom rules to require that a backchannel authentication + request include a user code for some particular users and found that the user identified by + the hint is one of the particular users. + Note that `/backchannel/authentication` API does not return `action=USER_IDENTIFICATION` when + both the `backchannel_user_code_parameter_supported` metadata of the server and the + `backchannel_user_code_parameter` metadata of the client are true and the backchannel authentication + request does not include the user_code request parameter. In this case, `/backchannel/authentication` + API returns action=BAD_REQUEST with JSON containing `"error":"missing_user_code"`. Therefore, + the authorization server implementation will never have to use the error code `missing_user_code` + unless the server has intentionally implemented custom rules to require a user code based + on users even in the case where the `backchannel_user_code_parameter` metadata of the client + which has made the backchannel authentication request is `false`. + - `invalid_user_code` + The authorization server implementation detected that the presented user code is invalid. + Note that the format of user_code is not described in the CIBA Core spec at all and so there + is no consensus on how to judge whether a user code is valid or not. It is up to each authorization + server implementation how to handle user codes. + - `invalid_binding_message` + The authorization server implementation detected that the presented binding message is invalid. + Note that the format of binding_message is not described in the CIBA Core spec at all and + so there is no consensus on how to judge whether a binding message is valid or not. It is + up to each authorization server implementation how to handle binding messages. + - `invalid_target` + The authorization server implementation rejects the requested target resources. + The error code invalid_target is from "Resource Indicators for OAuth 2.0". The specification + defines the resource request parameter. By using the parameter, client applications can request + target resources that should be bound to the access token being issued. If the authorization + server wants to reject the request, call `/backchannel/authentication/fail` API with `INVALID_TARGET`. + - `access_denined` + The authorization server implementation has custom rules to reject backchannel authentication + requests without asking the end-user and respond to the client as if the end-user had rejected + the request in some particular cases and found that the backchannel authentication request + is one of the particular cases. + The authorization server implementation will never have to use the error code `access_denied` + at this timing unless the server has intentionally implemented custom rules to reject backchannel + authentication requests without asking the end-user and respond to the client as if the end-user + had rejected the request. + + **[3] AUTH_REQ_ID ISSUE** + + If the authorization server implementation has successfully determined the subject of the end-user, + the next action is to return an HTTP response to the client application which contains `auth_req_id`. + Authlete provides `/backchannel/authentication/issue` API which generates a JSON containing `auth_req_id`, + so, your next action is (1) call the API, (2) receive the response from the API, (3) build a response + to the client application using the content of the API response, and (4) return the response to + the client application. See the description of `/backchannel/authentication/issue` API for details. + + **[4] END-USER AUTHENTICATION AND AUTHORIZATION** + + After sending a JSON containing `auth_req_id` back to the client application, the service implementation + starts to communicate with an authentication device of the end-user. It is assumed that end-user + authentication is performed on the authentication device and the end-user confirms the content of + the backchannel authentication request and grants authorization to the client application if everything + is okay. The authorization server implementation must be able to receive the result of the end-user + authentication and authorization from the authentication device. + How to communicate with an authentication device and achieve end-user authentication and authorization + is up to each authorization server implementation, but the following request parameters of the backchannel + authentication request should be taken into consideration in any implementation. + - `acr_values` + A backchannel authentication request may contain an array of ACRs (Authentication Context Class + References) in preference order. If multiple authentication devices are registered for the end-user, + the authorization server implementation should take the ACRs into consideration when selecting + the best authentication device. + - `scope` + A backchannel authentication request always contains a list of scopes. At least, `openid` is + included in the list (otherwise `/backchannel/authentication` API returns `action=BAD_REQUEST`). + It would be better to show the requested scopes to the end-user on the authentication device + or somewhere appropriate. + If the scope request parameter contains `address`, `email`, `phone` and/or `profile`, they are + interpreted as defined in "5.4. Requesting Claims using Scope Values of OpenID Connect Core 1.0". + That is, they are expanded into a list of claim names. The claimNames parameter returns the expanded + result. + - `binding_message` + A backchannel authentication request may contain a binding message. It is a human readable identifier + or message intended to be displayed on both the consumption device (client application) and the + authentication device. + - `user_code` + A backchannel authentication request may contain a user code. It is a secret code, such as password + or pin, known only to the end-user but verifiable by the authorization server. The user code should + be used to authorize sending a request to the authentication device. + + **[5] END-USER AUTHENTICATION AND AUTHORIZATION COMPLETION** + + After receiving the result of end-user authentication and authorization, the authorization server + implementation must call Authlete's `/backchannel/authentication/complete` API to tell Authlete + the result and pass necessary data so that Authlete can generate an ID token, an access token and + optionally a refresh token. See the description of the API for details. + + **[6] CLIENT NOTIFICATION** + + When the backchannel token delivery mode is either `ping` or `push`, the authorization server implementation + must send a notification to the pre-registered notification endpoint of the client after the end-user + authentication and authorization. In this case, the `action` parameter in a response from `/backchannel/authentication/complete` + API is `NOTIFICATION`. See the description of `/backchannel/authentication/complete` API for details. + + **[7] TOKEN REQUEST** + + When the backchannel token delivery mode is either `ping` or `poll`, the client application will make + a token request to the token endpoint to get an ID token, an access token and optionally a refresh + token. + A token request that corresponds to a backchannel authentication request uses `urn:openid:params:grant-type:ciba` + as the value of the `grant_type` request parameter. Authlete's `/auth/token` API recognizes the + grant type automatically and behaves properly, so the existing token endpoint implementation does + not have to be changed to support CIBA. + - There are some cases where the authorization server implementation encounters an error during - the user identification process. In any error case, the service implementation has to return an - HTTP response with the error response parameter to the client application. The following is an - example of such error responses. - ``` - HTTP/1.1 400 Bad Request - Content-Type: application/json - Cache-Control: no-store - Pragma: no-cache - { "error":"unknown_user_id" } - ``` - Authlete provides `/backchannel/authentication/fail` API that builds the response body (JSON) - of an error response. However, because it is easy to build an error response manually, you may - choose not to call the API. One good thing in using the API is that the API call can trigger - deletion of the ticket which has been issued from Authlete's `/backchannel/authentication` API. - If you don't call `/backchannel/authentication/fail` API, the ticket will continue to exist in - the database until it is cleaned up by the batch program after the ticket expires. - Possible error cases that the authorization server implementation itself has to handle are as - follows. Other error cases have already been covered by `/backchannel/authentication` API. - - `expired_login_hint_token` - The authorization server implementation detected that the hint presented by the `login_hint_token` - request parameter has expired. - Note that the format of `login_hint_token` is not described in the CIBA Core spec at all and - so there is no consensus on how to detect expiration of `login_hint_token`. Interpretation - of `login_hint_token` is left to each authorization server implementation. - - `unknown_user_id` - The authorization server implementation could not determine the subject of the end-user by - the presented hint. - - `unauthorized_client` - The authorization server implementation has custom rules to reject backchannel authentication - requests from some particular clients and found that the client which has made the backchannel - authentication request is one of the particular clients. - Note that `/backchannel/authentication` API does not return `action=USER_IDENTIFICATION` in - cases where the client does not exist or client authentication has failed. Therefore, the - authorization server implementation will never have to use the error code `unauthorized_client` - unless the server has intentionally implemented custom rules to reject backchannel authentication - requests based on clients. - - `missing_user_code` - The authorization server implementation has custom rules to require that a backchannel authentication - request include a user code for some particular users and found that the user identified by - the hint is one of the particular users. - Note that `/backchannel/authentication` API does not return `action=USER_IDENTIFICATION` when - both the `backchannel_user_code_parameter_supported` metadata of the server and the - `backchannel_user_code_parameter` metadata of the client are true and the backchannel authentication - request does not include the user_code request parameter. In this case, `/backchannel/authentication` - API returns action=BAD_REQUEST with JSON containing `"error":"missing_user_code"`. Therefore, - the authorization server implementation will never have to use the error code `missing_user_code` - unless the server has intentionally implemented custom rules to require a user code based - on users even in the case where the `backchannel_user_code_parameter` metadata of the client - which has made the backchannel authentication request is `false`. - - `invalid_user_code` - The authorization server implementation detected that the presented user code is invalid. - Note that the format of user_code is not described in the CIBA Core spec at all and so there - is no consensus on how to judge whether a user code is valid or not. It is up to each authorization - server implementation how to handle user codes. - - `invalid_binding_message` - The authorization server implementation detected that the presented binding message is invalid. - Note that the format of binding_message is not described in the CIBA Core spec at all and - so there is no consensus on how to judge whether a binding message is valid or not. It is - up to each authorization server implementation how to handle binding messages. - - `invalid_target` - The authorization server implementation rejects the requested target resources. - The error code invalid_target is from "Resource Indicators for OAuth 2.0". The specification - defines the resource request parameter. By using the parameter, client applications can request - target resources that should be bound to the access token being issued. If the authorization - server wants to reject the request, call `/backchannel/authentication/fail` API with `INVALID_TARGET`. - - `access_denined` - The authorization server implementation has custom rules to reject backchannel authentication - requests without asking the end-user and respond to the client as if the end-user had rejected - the request in some particular cases and found that the backchannel authentication request - is one of the particular cases. - The authorization server implementation will never have to use the error code `access_denied` - at this timing unless the server has intentionally implemented custom rules to reject backchannel - authentication requests without asking the end-user and respond to the client as if the end-user - had rejected the request. - - **[3] AUTH_REQ_ID ISSUE** - - If the authorization server implementation has successfully determined the subject of the end-user, - the next action is to return an HTTP response to the client application which contains `auth_req_id`. - Authlete provides `/backchannel/authentication/issue` API which generates a JSON containing `auth_req_id`, - so, your next action is (1) call the API, (2) receive the response from the API, (3) build a response - to the client application using the content of the API response, and (4) return the response to - the client application. See the description of `/backchannel/authentication/issue` API for details. - - **[4] END-USER AUTHENTICATION AND AUTHORIZATION** - - After sending a JSON containing `auth_req_id` back to the client application, the service implementation - starts to communicate with an authentication device of the end-user. It is assumed that end-user - authentication is performed on the authentication device and the end-user confirms the content of - the backchannel authentication request and grants authorization to the client application if everything - is okay. The authorization server implementation must be able to receive the result of the end-user - authentication and authorization from the authentication device. - How to communicate with an authentication device and achieve end-user authentication and authorization - is up to each authorization server implementation, but the following request parameters of the backchannel - authentication request should be taken into consideration in any implementation. - - `acr_values` - A backchannel authentication request may contain an array of ACRs (Authentication Context Class - References) in preference order. If multiple authentication devices are registered for the end-user, - the authorization server implementation should take the ACRs into consideration when selecting - the best authentication device. - - `scope` - A backchannel authentication request always contains a list of scopes. At least, `openid` is - included in the list (otherwise `/backchannel/authentication` API returns `action=BAD_REQUEST`). - It would be better to show the requested scopes to the end-user on the authentication device - or somewhere appropriate. - If the scope request parameter contains `address`, `email`, `phone` and/or `profile`, they are - interpreted as defined in "5.4. Requesting Claims using Scope Values of OpenID Connect Core 1.0". - That is, they are expanded into a list of claim names. The claimNames parameter returns the expanded - result. - - `binding_message` - A backchannel authentication request may contain a binding message. It is a human readable identifier - or message intended to be displayed on both the consumption device (client application) and the - authentication device. - - `user_code` - A backchannel authentication request may contain a user code. It is a secret code, such as password - or pin, known only to the end-user but verifiable by the authorization server. The user code should - be used to authorize sending a request to the authentication device. - - **[5] END-USER AUTHENTICATION AND AUTHORIZATION COMPLETION** - - After receiving the result of end-user authentication and authorization, the authorization server - implementation must call Authlete's `/backchannel/authentication/complete` API to tell Authlete - the result and pass necessary data so that Authlete can generate an ID token, an access token and - optionally a refresh token. See the description of the API for details. - - **[6] CLIENT NOTIFICATION** - - When the backchannel token delivery mode is either `ping` or `push`, the authorization server implementation - must send a notification to the pre-registered notification endpoint of the client after the end-user - authentication and authorization. In this case, the `action` parameter in a response from `/backchannel/authentication/complete` - API is `NOTIFICATION`. See the description of `/backchannel/authentication/complete` API for details. - - **[7] TOKEN REQUEST** - - When the backchannel token delivery mode is either `ping` or `poll`, the client application will make - a token request to the token endpoint to get an ID token, an access token and optionally a refresh - token. - A token request that corresponds to a backchannel authentication request uses `urn:openid:params:grant-type:ciba` - as the value of the `grant_type` request parameter. Authlete's `/auth/token` API recognizes the - grant type automatically and behaves properly, so the existing token endpoint implementation does - not have to be changed to support CIBA. parameters: - in: path name: serviceId @@ -6950,77 +7052,83 @@ paths: description: | This API prepares JSON that contains an `auth_req_id`. The JSON should be used as the response body of the response which is returned to the client from the [backchannel authentication endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_endpoint) + x-mint: + metadata: + description: "This API prepares JSON that contains an `auth_req_id`. The JSON should be used as the response body of the response which is returned to the client from the [backchannel authentication endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_endpoint)" + content: | + + This API is supposed to be called from within the implementation of the backchannel authentication + endpoint of the service in order to generate a successful response to the client application. + The description of the `/backchannel/authentication` API describes the timing when this API should + be called and the meaning of request parameters. See [AUTH_REQ_ID ISSUE] in `USER_IDENTIFICATION`. + The response from `/backchannel/authentication/issue` API has some 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 authorization server implementation must take the steps described below. + ```java + @POST + @Consumes(MediaType.APPLICATION_FORM_URLENCODED) + public Response post(String parameters) + { + // 'parameters' is the entity body of the backchannel authentication request. + ...... + } + ``` + The endpoint implementation does not have to parse the request parameters from the client application + because Authlete's `/backchannel/authentication` API does it. + The response from `/backchannel/authentication` 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" and `application/json`. + 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} + ``` + + ## INVALID_TICKET + + When the value of `action` is `INVALID_TICKET`, it means that the ticket included in the API call + was invalid. For example, it does not exist or has expired. + From a viewpoint of the client application, this is an error on the server side. Therefore, the + authorization server implementation should generate a response to the client application with + "500 Internal Server Error" and `application/json`. + You can build an error response in the same way as shown in the description for the case of `INTERNAL_SERVER_ERROR`. + + ## OK + + When the value of `action` is `OK`, it means that Authlete has succeeded in preparing JSON that + contains an `auth_req_id`. The JSON should be used as the response body of the response that is + returned to the client from the backchannel authentication endpoint. `responseContent` contains + the JSON. + The following illustrates the response which the authorization server implementation should 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} + ``` + - This API is supposed to be called from within the implementation of the backchannel authentication - endpoint of the service in order to generate a successful response to the client application. - The description of the `/backchannel/authentication` API describes the timing when this API should - be called and the meaning of request parameters. See [AUTH_REQ_ID ISSUE] in `USER_IDENTIFICATION`. - The response from `/backchannel/authentication/issue` API has some 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 authorization server implementation must take the steps described below. - ```java - @POST - @Consumes(MediaType.APPLICATION_FORM_URLENCODED) - public Response post(String parameters) - { - // 'parameters' is the entity body of the backchannel authentication request. - ...... - } - ``` - The endpoint implementation does not have to parse the request parameters from the client application - because Authlete's `/backchannel/authentication` API does it. - The response from `/backchannel/authentication` 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" and `application/json`. - 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} - ``` - - ## INVALID_TICKET - - When the value of `action` is `INVALID_TICKET`, it means that the ticket included in the API call - was invalid. For example, it does not exist or has expired. - From a viewpoint of the client application, this is an error on the server side. Therefore, the - authorization server implementation should generate a response to the client application with - "500 Internal Server Error" and `application/json`. - You can build an error response in the same way as shown in the description for the case of `INTERNAL_SERVER_ERROR`. - - ## OK - - When the value of `action` is `OK`, it means that Authlete has succeeded in preparing JSON that - contains an `auth_req_id`. The JSON should be used as the response body of the response that is - returned to the client from the backchannel authentication endpoint. `responseContent` contains - the JSON. - The following illustrates the response which the authorization server implementation should 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} - ``` parameters: - in: path name: serviceId @@ -7098,33 +7206,39 @@ paths: description: | The API prepares JSON that contains an error. The JSON should be used as the response body of the response which is returned to the client from the [backchannel authentication endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_endpoint). + x-mint: + metadata: + description: "The API prepares JSON that contains an error. The JSON should be used as the response body of the response which is returned to the client from the [backchannel authentication endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_endpoint)." + content: | + + This API is supposed to be called from within the implementation of the [backchannel authentication + endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_endpoint) + of the service in order to generate an error response to the client application. + The response from `/backchannel/authentication/fails` API has some 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 authorization server implementation must take the steps described below. - This API is supposed to be called from within the implementation of the [backchannel authentication - endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_endpoint) - of the service in order to generate an error response to the client application. - The response from `/backchannel/authentication/fails` API has some 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 authorization server implementation must take the steps described below. + ## INTERNAL_SERVER_ERROR - ## INTERNAL_SERVER_ERROR + When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that (1) the `reason` request parameter + of the API call was `SERVER_ERROR`, (2) an error occurred on Authlete side, or (3) the request parameters + of the API call were wrong. In this case, the authorization server implementation should return + a "500 Internal Server Error" response to the client application. However, in most cases, commercial + implementations prefer to use other HTTP status code than 5xx. - When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that (1) the `reason` request parameter - of the API call was `SERVER_ERROR`, (2) an error occurred on Authlete side, or (3) the request parameters - of the API call were wrong. In this case, the authorization server implementation should return - a "500 Internal Server Error" response to the client application. However, in most cases, commercial - implementations prefer to use other HTTP status code than 5xx. + ## BAD_REQUEST - ## BAD_REQUEST + When the value of `action` is `BAD_REQUEST`, the authorization server implementation should return a + "400 Bad Request" response to the client application. - When the value of `action` is `BAD_REQUEST`, the authorization server implementation should return a - "400 Bad Request" response to the client application. + ## FORBIDDEN - ## FORBIDDEN + When the value of `action` is `FORBIDDEN`, it means that the `reason` request parameter of the API call + was `ACCESS_DENIED`. In this case, the backchannel authentication endpoint of the authorization + server implementation should return a "403 Forbidden" response to the client application. + - When the value of `action` is `FORBIDDEN`, it means that the `reason` request parameter of the API call - was `ACCESS_DENIED`. In this case, the backchannel authentication endpoint of the authorization - server implementation should return a "403 Forbidden" response to the client application. parameters: - in: path name: serviceId @@ -7200,91 +7314,97 @@ paths: This API returns information about what action the authorization server should take after it receives the result of end-user's decision about whether the end-user has approved or rejected a client application's request on the authentication device. + x-mint: + metadata: + description: "This API returns information about what action the authorization server should take after it receives the result of end-user's decision about whether the end-user has approved or rejected a client application's request on the authentication device." + content: | + + After the implementation of the backchannel authentication endpoint returns JSON containing an + `auth_req_id` to the client, the authorization server starts a background process that communicates + with the authentication device of the end-user. On the authentication device, end-user authentication + is performed and the end-user is asked whether they give authorization to the client or not. The + authorization server will receive the result of end-user authentication and authorization from + the authentication device. + After the authorization server receives the result from the authentication device, or even in the + case where the server gave up receiving a response from the authentication device for some reasons, + the server should call the `/backchannel/authentication/complete` API to tell Authlete the result. + When the end-user was authenticated and authorization was granted to the client by the end-user, + the authorization server should call the API with `result=AUTHORIZED`. In this successful case, + the `subject` request parameter is mandatory. If the token delivery mode is `push`, the API will generate + an access token, an ID token and optionally a refresh token. On the other hand, if the token delivery + mode is `poll` or `ping`, the API will just update the database record so that `/auth/token` API + can generate tokens later. + When the authorization server received the decision of the end-user from the authentication device + and it indicates that the end-user has rejected to give authorization to the client, the authorization + server should call the API with `result=ACCESS_DENIED`. In this case, if the token delivery mode + is `push`, the API will generate an error response that contains the error response parameter and + optionally the `error_description` and error_uri response parameters (if the `errorDescription` + and `errorUri` request parameters have been given). On the other hand, if the token delivery mode + is `poll` or `ping`, the API will just update the database record so that `/auth/token` API can + generate an error response later. In any token delivery mode, the value of the error parameter will + become `access_denied`. + When the authorization server could not get the result of end-user authentication and authorization + from the authentication device for some reasons, the authorization server should call the API with + `result=TRANSACTION_FAILED`. In this error case, the API will behave in the same way as in the case + of `ACCESS_DENIED`. The only difference is that `expired_token` is used as the value of the `error` + parameter. + The response from `/backchannel/authentication/complete` 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. + + ## SERVER_ERROR + + When the value of `action` is `SERVER_ERROR`, it means either (1) that the request from the authorization + server to Authlete was wrong, or (2) that an error occurred on Authlete side. + When the backchannel token delivery mode is `ping` or `push`, `SERVER_ERROR` is used only when + an error is detected before the record of the ticket (which is included in the API call to `/backchannel/authentication/complete`) + is retrieved from the database successfully. If an error is detected after the record of the ticket + is retrieved from the database, `NOTIFICATION` is used instead of `SERVER_ERROR`. + When the backchannel token delivery mode is `poll`, `SERVER_ERROR` is used regardless of whether + it is before or after the record of the ticket is retrieved from the database. + + ## NO_ACTION + + When the value of `action` is `NO_ACTION`, it means that the authorization server does not have + to take any immediate action. + `NO_ACTION` is returned when the backchannel token delivery mode is `poll`. In this case, the client + will receive the final result at the token endpoint. + + ## NOTIFICATION + + When the value of `action` is `NOTIFICATION`, it means that the authorization server must send a + notification to the client notification endpoint. + According to the CIBA Core specification, the notification is an HTTP POST request whose request + body is JSON and whose `Authorization` header contains the client notification token, which was + included in the backchannel authentication request as the value of the `client_notification_token` + request parameter, as a bearer token. + When the backchannel token delivery mode is `ping`, the request body of the notification is JSON + which contains the `auth_req_id` property only. When the backchannel token delivery mode is `push`, + the request body will additionally contain an access token, an ID token and other properties. Note + that when the backchannel token delivery mode is `poll`, a notification does not have to be sent + to the client notification endpoint. + In error cases, in the ping mode, however, the content of a notification is not different from the + content in successful cases. That is, the notification contains the `auth_req_id` property only. + The client will know the error when it accesses the token endpoint. On the other hand, in the + `push` mode, in error cases, the content of a notification will include the `error` property instead + of an access token and an ID token. The client will know the error by detecting that error is included + in the notification. + In any case, the value of `responseContent` is JSON which can be used as the request body of the + notification. + The client notification endpoint that the notification should be sent to the value of the `clientNotificationEndpoint` + parameter. Likewise, the client notification token that the notification should include as a bearer + token is the `clientNotificationToken` parameter. With these methods, the notification can be built + like the following. + ``` + POST {clientNotificationEndpoint} HTTP/1.1 + HOST: {The host of clientNotificationEndpoint} + Authorization: Bearer {notificationToken} + Content-Type: application/json + {responseContent} + ``` + - After the implementation of the backchannel authentication endpoint returns JSON containing an - `auth_req_id` to the client, the authorization server starts a background process that communicates - with the authentication device of the end-user. On the authentication device, end-user authentication - is performed and the end-user is asked whether they give authorization to the client or not. The - authorization server will receive the result of end-user authentication and authorization from - the authentication device. - After the authorization server receives the result from the authentication device, or even in the - case where the server gave up receiving a response from the authentication device for some reasons, - the server should call the `/backchannel/authentication/complete` API to tell Authlete the result. - When the end-user was authenticated and authorization was granted to the client by the end-user, - the authorization server should call the API with `result=AUTHORIZED`. In this successful case, - the `subject` request parameter is mandatory. If the token delivery mode is `push`, the API will generate - an access token, an ID token and optionally a refresh token. On the other hand, if the token delivery - mode is `poll` or `ping`, the API will just update the database record so that `/auth/token` API - can generate tokens later. - When the authorization server received the decision of the end-user from the authentication device - and it indicates that the end-user has rejected to give authorization to the client, the authorization - server should call the API with `result=ACCESS_DENIED`. In this case, if the token delivery mode - is `push`, the API will generate an error response that contains the error response parameter and - optionally the `error_description` and error_uri response parameters (if the `errorDescription` - and `errorUri` request parameters have been given). On the other hand, if the token delivery mode - is `poll` or `ping`, the API will just update the database record so that `/auth/token` API can - generate an error response later. In any token delivery mode, the value of the error parameter will - become `access_denied`. - When the authorization server could not get the result of end-user authentication and authorization - from the authentication device for some reasons, the authorization server should call the API with - `result=TRANSACTION_FAILED`. In this error case, the API will behave in the same way as in the case - of `ACCESS_DENIED`. The only difference is that `expired_token` is used as the value of the `error` - parameter. - The response from `/backchannel/authentication/complete` 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. - - ## SERVER_ERROR - - When the value of `action` is `SERVER_ERROR`, it means either (1) that the request from the authorization - server to Authlete was wrong, or (2) that an error occurred on Authlete side. - When the backchannel token delivery mode is `ping` or `push`, `SERVER_ERROR` is used only when - an error is detected before the record of the ticket (which is included in the API call to `/backchannel/authentication/complete`) - is retrieved from the database successfully. If an error is detected after the record of the ticket - is retrieved from the database, `NOTIFICATION` is used instead of `SERVER_ERROR`. - When the backchannel token delivery mode is `poll`, `SERVER_ERROR` is used regardless of whether - it is before or after the record of the ticket is retrieved from the database. - - ## NO_ACTION - - When the value of `action` is `NO_ACTION`, it means that the authorization server does not have - to take any immediate action. - `NO_ACTION` is returned when the backchannel token delivery mode is `poll`. In this case, the client - will receive the final result at the token endpoint. - - ## NOTIFICATION - - When the value of `action` is `NOTIFICATION`, it means that the authorization server must send a - notification to the client notification endpoint. - According to the CIBA Core specification, the notification is an HTTP POST request whose request - body is JSON and whose `Authorization` header contains the client notification token, which was - included in the backchannel authentication request as the value of the `client_notification_token` - request parameter, as a bearer token. - When the backchannel token delivery mode is `ping`, the request body of the notification is JSON - which contains the `auth_req_id` property only. When the backchannel token delivery mode is `push`, - the request body will additionally contain an access token, an ID token and other properties. Note - that when the backchannel token delivery mode is `poll`, a notification does not have to be sent - to the client notification endpoint. - In error cases, in the ping mode, however, the content of a notification is not different from the - content in successful cases. That is, the notification contains the `auth_req_id` property only. - The client will know the error when it accesses the token endpoint. On the other hand, in the - `push` mode, in error cases, the content of a notification will include the `error` property instead - of an access token and an ID token. The client will know the error by detecting that error is included - in the notification. - In any case, the value of `responseContent` is JSON which can be used as the request body of the - notification. - The client notification endpoint that the notification should be sent to the value of the `clientNotificationEndpoint` - parameter. Likewise, the client notification token that the notification should include as a bearer - token is the `clientNotificationToken` parameter. With these methods, the notification can be built - like the following. - ``` - POST {clientNotificationEndpoint} HTTP/1.1 - HOST: {The host of clientNotificationEndpoint} - Authorization: Bearer {notificationToken} - Content-Type: application/json - {responseContent} - ``` parameters: - in: path name: serviceId @@ -7378,88 +7498,94 @@ paths: This API parses request parameters of a [device authorization request](https://datatracker.ietf.org/doc/html/rfc8628#section-3.1) and returns necessary data for the authorization server implementation to process the device authorization request further. + x-mint: + metadata: + description: "This API parses request parameters of a [device authorization request](https://datatracker.ietf.org/doc/html/rfc8628#section-3.1) and returns necessary data for the authorization server implementation to process the device authorization request further." + content: | + + This API is supposed to be called from the within the implementation of the device authorization + endpoint of the service. The service implementation should retrieve the value of `action` from the + response and take the following steps according to the value. + + ## INTERNAL_SERVER_ERROR + + When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the API call from the authorization + server implementation was wrong or that an error occurred in Authlete. + In either case, from a viewpoint of the client application, it is an error on the server side. + Therefore, the authorization server implementation should generate a response to the client application + with "500 Internal Server Error"s and `application/json`. + The value of `responseContent` is a JSON string which describes t he error, so it can be + used as the entity body of the response. + + --- + + The following illustrates the response which the authorization server 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} + ``` + + ## BAD_REQUEST + + When the value of `action` is `BAD_REQUEST`, it means that the request from the client application + is wrong. + The authorization server implementation should generate a response to the client application with + "400 Bad Request" and `application/json`. + 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} + ``` + + ## UNAUTHORIZED + + When the value of `action` is `UNAUTHORIZED`, it means that client authentication of the device authorization + request failed. + The authorization server implementation should generate a response to the client application with + "401 Unauthorized" and `application/json`. + 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 must generate and return + to the client application. + ``` + HTTP/1.1 401 Unauthorized + WWW-Authenticate: (challenge) + Content-Type: application/json + Cache-Control: no-store + Pragma: no-cache + {responseContent} + ``` + + ## OK + + When the value of `action` is `OK`, it means that the device authorization request from the client + application is valid. + The authorization server implementation should generate a response to the client application with + "200 OK" and `application/json`. + The `responseContent` is a JSON string which can be used as the entity body of the response. + + --- + + The following illustrates the response which the authorization server implementation should generate + and return to the client application. + - This API is supposed to be called from the within the implementation of the device authorization - endpoint of the service. The service implementation should retrieve the value of `action` from the - response and take the following steps according to the value. - - ## INTERNAL_SERVER_ERROR - - When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the API call from the authorization - server implementation was wrong or that an error occurred in Authlete. - In either case, from a viewpoint of the client application, it is an error on the server side. - Therefore, the authorization server implementation should generate a response to the client application - with "500 Internal Server Error"s and `application/json`. - The value of `responseContent` is a JSON string which describes t he error, so it can be - used as the entity body of the response. - - --- - - The following illustrates the response which the authorization server 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} - ``` - - ## BAD_REQUEST - - When the value of `action` is `BAD_REQUEST`, it means that the request from the client application - is wrong. - The authorization server implementation should generate a response to the client application with - "400 Bad Request" and `application/json`. - 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} - ``` - - ## UNAUTHORIZED - - When the value of `action` is `UNAUTHORIZED`, it means that client authentication of the device authorization - request failed. - The authorization server implementation should generate a response to the client application with - "401 Unauthorized" and `application/json`. - 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 must generate and return - to the client application. - ``` - HTTP/1.1 401 Unauthorized - WWW-Authenticate: (challenge) - Content-Type: application/json - Cache-Control: no-store - Pragma: no-cache - {responseContent} - ``` - - ## OK - - When the value of `action` is `OK`, it means that the device authorization request from the client - application is valid. - The authorization server implementation should generate a response to the client application with - "200 OK" and `application/json`. - The `responseContent` is a JSON string which can be used as the entity body of the response. - - --- - - The following illustrates the response which the authorization server implementation should generate - and return to the client application. parameters: - in: path name: serviceId @@ -7561,40 +7687,46 @@ paths: summary: Process Device Verification Request description: | The API returns information associated with a user code. + x-mint: + metadata: + description: "The API returns information associated with a user code." + content: | + + After receiving a response from the device authorization endpoint of the authorization server, + the client application shows the end-user the user code and the verification URI which are included + in the device authorization response. Then, the end-user will access the verification URI using + a web browser on another device (typically, a smart phone). In normal implementations, the verification + endpoint will return an HTML page with an input form where the end-user inputs a user code. The + authorization server will receive a user code from the form. + After receiving a user code, the authorization server should call Authlete's `/device/verification` + API with the user code. And then, the authorization server implementation should retrieve the value + of `action` parameter from the API response and take the following steps according to the value. - After receiving a response from the device authorization endpoint of the authorization server, - the client application shows the end-user the user code and the verification URI which are included - in the device authorization response. Then, the end-user will access the verification URI using - a web browser on another device (typically, a smart phone). In normal implementations, the verification - endpoint will return an HTML page with an input form where the end-user inputs a user code. The - authorization server will receive a user code from the form. - After receiving a user code, the authorization server should call Authlete's `/device/verification` - API with the user code. And then, the authorization server implementation should retrieve the value - of `action` parameter from the API response and take the following steps according to the value. + ## SERVER_ERROR - ## SERVER_ERROR + When the value of `action` is `SERVER_ERROR`, it means that an error occurred on Authlete side. The + authorization server implementation should tell the end-user that something wrong happened and + urge her to re-initiate a device flow. - When the value of `action` is `SERVER_ERROR`, it means that an error occurred on Authlete side. The - authorization server implementation should tell the end-user that something wrong happened and - urge her to re-initiate a device flow. + ## NOT_EXIST - ## NOT_EXIST + When the value of `action` is `NOT_EXIST`, it means that the user code does not exist. The authorization + server implementation should tell the end-user that the user code is invalid and urge her to retry + to input a valid user code. - When the value of `action` is `NOT_EXIST`, it means that the user code does not exist. The authorization - server implementation should tell the end-user that the user code is invalid and urge her to retry - to input a valid user code. + ## EXPIRED - ## EXPIRED + When the value of `action` is `EXPIRED`, it means that the user code has expired. The authorization + server implementation should tell the end-user that the user code has expired and urge her to + re-initiate a device flow. - When the value of `action` is `EXPIRED`, it means that the user code has expired. The authorization - server implementation should tell the end-user that the user code has expired and urge her to - re-initiate a device flow. + ## VALID - ## VALID + When the value of `action` is `VALID`, it means that the user code exists, has not expired, and + belongs to the service. The authorization server implementation should interact with the end-user + to ask whether she approves or rejects the authorization request from the device. + - When the value of `action` is `VALID`, it means that the user code exists, has not expired, and - belongs to the service. The authorization server implementation should interact with the end-user - to ask whether she approves or rejects the authorization request from the device. parameters: - in: path name: serviceId @@ -7681,62 +7813,68 @@ paths: This API returns information about what action the authorization server should take after it receives the result of end-user's decision about whether the end-user has approved or rejected a client application's request. + x-mint: + metadata: + description: "This API returns information about what action the authorization server should take after it receives the result of end-user's decision about whether the end-user has approved or rejected a client application's request." + content: | + + In the device flow, an end-user accesses the verification endpoint of the authorization server where + she interacts with the verification endpoint and inputs a user code. The verification endpoint checks + if the user code is valid and then asks the end-user whether she approves or rejects the authorization + request which the user code represents. + After the authorization server receives the decision of the end-user, it should call Authlete's + `/device/complete` API to tell Authlete the decision. + When the end-user was authenticated and authorization was granted to the client by the end-user, + the authorization server should call the API with `result=AUTHORIZED`. In this successful case, + the subject request parameter is mandatory. The API will update the database record so that `/auth/token` + API can generate an access token later. + If the `scope` parameter of the device authorization request included the openid scope, an ID token + is generated. In this case, `sub`, `authTime`, `acr` and `claims` request parameters in the API + call to `/device/complete` affect the ID token. + When the authorization server receives the decision of the end-user and it indicates that she has + rejected to give authorization to the client, the authorization server should call the API with + `result=ACCESS_DENIED`. In this case, the API will update the database record so that the `/auth/token` + API can generate an error response later. If `errorDescription` and `errorUri` request parameters + are given to the `/device/complete` API, they will be used as the values of `error_description` + and `error_uri` response parameters in the error response from the token endpoint. + When the authorization server could not get decision from the end-user for some reasons, the authorization + server should call the API with `result=TRANSACTION_FAILED`. In this error case, the API will behave + in the same way as in the case of `ACCESS_DENIED`. The only difference is that `expired_token` is + used as the value of the `error` response parameter instead of `access_denied`. + After receiving a response from the `/device/complete` API, the implementation of the authorization + server should retrieve the value of `action` from the response and take the following steps according + to the value. + + ## SERVER_ERROR + + When the value of `action` is `SERVER_ERROR`, it means that an error occurred on Authlete side. The + authorization server implementation should tell the end-user that something wrong happened and + urge her to re-initiate a device flow. + + ## USER_CODE_NOT_EXIST + + When the value of `action` is `USER_CODE_NOT_EXIST`, it means that the user code included in the API + call does not exist. The authorization server implementation should tell the end-user that the user + code has been invalidated and urge her to re-initiate a device flow. + + ## USER_CODE_EXPIRED + + When the value of `action` is `USER_CODE_EXPIRED`, it means that the user code included in the API + call has expired. The authorization server implementation should tell the end-user that the user + code has expired and urge her to re-initiate a device flow. + + ## INVALID_REQUEST + + When the value of `action` is `INVALID_REQUEST`, it means that the API call is invalid. Probably, + the authorization server implementation has some bugs. + + ## SUCCESS + + When the value of `action` is `SUCCESS`, it means that the API call has been processed successfully. + The authorization server should return a successful response to the web browser the end-user is + using. + - In the device flow, an end-user accesses the verification endpoint of the authorization server where - she interacts with the verification endpoint and inputs a user code. The verification endpoint checks - if the user code is valid and then asks the end-user whether she approves or rejects the authorization - request which the user code represents. - After the authorization server receives the decision of the end-user, it should call Authlete's - `/device/complete` API to tell Authlete the decision. - When the end-user was authenticated and authorization was granted to the client by the end-user, - the authorization server should call the API with `result=AUTHORIZED`. In this successful case, - the subject request parameter is mandatory. The API will update the database record so that `/auth/token` - API can generate an access token later. - If the `scope` parameter of the device authorization request included the openid scope, an ID token - is generated. In this case, `sub`, `authTime`, `acr` and `claims` request parameters in the API - call to `/device/complete` affect the ID token. - When the authorization server receives the decision of the end-user and it indicates that she has - rejected to give authorization to the client, the authorization server should call the API with - `result=ACCESS_DENIED`. In this case, the API will update the database record so that the `/auth/token` - API can generate an error response later. If `errorDescription` and `errorUri` request parameters - are given to the `/device/complete` API, they will be used as the values of `error_description` - and `error_uri` response parameters in the error response from the token endpoint. - When the authorization server could not get decision from the end-user for some reasons, the authorization - server should call the API with `result=TRANSACTION_FAILED`. In this error case, the API will behave - in the same way as in the case of `ACCESS_DENIED`. The only difference is that `expired_token` is - used as the value of the `error` response parameter instead of `access_denied`. - After receiving a response from the `/device/complete` API, the implementation of the authorization - server should retrieve the value of `action` from the response and take the following steps according - to the value. - - ## SERVER_ERROR - - When the value of `action` is `SERVER_ERROR`, it means that an error occurred on Authlete side. The - authorization server implementation should tell the end-user that something wrong happened and - urge her to re-initiate a device flow. - - ## USER_CODE_NOT_EXIST - - When the value of `action` is `USER_CODE_NOT_EXIST`, it means that the user code included in the API - call does not exist. The authorization server implementation should tell the end-user that the user - code has been invalidated and urge her to re-initiate a device flow. - - ## USER_CODE_EXPIRED - - When the value of `action` is `USER_CODE_EXPIRED`, it means that the user code included in the API - call has expired. The authorization server implementation should tell the end-user that the user - code has expired and urge her to re-initiate a device flow. - - ## INVALID_REQUEST - - When the value of `action` is `INVALID_REQUEST`, it means that the API call is invalid. Probably, - the authorization server implementation has some bugs. - - ## SUCCESS - - When the value of `action` is `SUCCESS`, it means that the API call has been processed successfully. - The authorization server should return a successful response to the web browser the end-user is - using. parameters: - in: path name: serviceId @@ -8039,88 +8177,6 @@ paths: api.tokenCreate(req) tags: - Token Operations - /api/{serviceId}/auth/token/create/batch: - post: - summary: Create Access Tokens in Batch - description: | - Create access tokens in batch. - parameters: - - in: path - name: serviceId - description: A service ID. - required: true - schema: - type: string - - in: query - name: dryRun - description: | - If `true`, the request is processed but access tokens are not actually created. - required: false - schema: - type: boolean - requestBody: - required: true - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/token_create_request' - responses: - '200': - description: Batch request accepted - content: - application/json: - schema: - $ref: '#/components/schemas/token_create_batch_response' - '400': - $ref: '#/components/responses/400' - '401': - $ref: '#/components/responses/401' - '403': - $ref: '#/components/responses/403' - '500': - $ref: '#/components/responses/500' - operationId: auth_token_create_batch_api - tags: - - Token Operations - /api/{serviceId}/auth/token/create/batch/status/{tokenBatchRequestId}: - get: - summary: Get Batch Token Creation Status - description: | - Get the status of a batch token creation request. - parameters: - - in: path - name: serviceId - description: A service ID. - required: true - schema: - type: string - - in: path - name: tokenBatchRequestId - description: | - A token batch request ID. - required: true - schema: - type: string - responses: - '200': - description: Successfully retrieved the status - content: - application/json: - schema: - $ref: '#/components/schemas/token_create_batch_status_response' - '400': - $ref: '#/components/responses/400' - '401': - $ref: '#/components/responses/401' - '403': - $ref: '#/components/responses/403' - '500': - $ref: '#/components/responses/500' - operationId: auth_token_create_batch_status_api - tags: - - Token Operations /api/{serviceId}/auth/token/update: post: summary: Update Access Token @@ -8436,66 +8492,72 @@ paths: retrieve the value of the `action` response parameter from the API response and take the following steps according to the value. + x-mint: + metadata: + description: "This API gathers the federation configuration about a service. The authorization server implementation should retrieve the value of the `action` response parameter from the API response and take the following steps according to the value." + content: | + + ### `OK` + When the value of the `action` response + parameter is `OK`, it means that Authlete + could prepare an entity configuration successfully. + In this case, the implementation of the entity configuration endpoint of the + authorization server should return an HTTP response to the client application + with the HTTP status code "`200 OK`" and the content type + "`application/entity-statement+jwt`". The message body (= an entity + configuration in the JWT format) of the response has been prepared by + Authlete's `/federation/configuration` API and it is available as the + `responseContent` response parameter. + The implementation of the entity configuration endpoint can construct an + HTTP response by doing like below. + ``` + 200 OK + Content-Type: application/entity-statement+jwt + (Other HTTP headers) + (the value of the responseContent response parameter) + ``` + + ### `NOT_FOUND` + When the value of the `action` response + parameter is `NOT_FOUND`, it means that + the service configuration has not enabled the feature of [OpenID Connect + Federation 1.0](https://openid.net/specs/openid-connect-federation-1_0.html) and so the client application should have not access the + entity configuration endpoint. + In this case, the implementation of the entity configuration endpoint of the + authorization server should return an HTTP response to the client application + with the HTTP status code "`404 Not Found`" and the content type + "`application/json`". The message body (= error information in the JSON + format) of the response has been prepared by Authlete's + `/federation/configuration` API and it is available as the + `responseContent` response parameter. + The implementation of the entity configuration endpoint can construct an + HTTP response by doing like below. + ``` + 404 Not Found + Content-Type: application/json + (Other HTTP headers) + (the value of the responseContent response parameter) + ``` + + ### `INTERNAL_SERVER_ERROR` + could prepare an entity configuration successfully. + In this case, the implementation of the entity configuration endpoint of the + authorization server should return an HTTP response to the client application + with the HTTP status code "`200 OK`" and the content type + "`application/entity-statement+jwt`". The message body (= an entity + configuration in the JWT format) of the response has been prepared by + Authlete's `/federation/configuration` API and it is available as the + `responseContent` response parameter. + The implementation of the entity configuration endpoint can construct an + HTTP response by doing like below. + ``` + 200 OK + Content-Type: application/entity-statement+jwt + (Other HTTP headers) + (the value of the responseContent response parameter) + ``` + - ### `OK` - When the value of the `action` response - parameter is `OK`, it means that Authlete - could prepare an entity configuration successfully. - In this case, the implementation of the entity configuration endpoint of the - authorization server should return an HTTP response to the client application - with the HTTP status code "`200 OK`" and the content type - "`application/entity-statement+jwt`". The message body (= an entity - configuration in the JWT format) of the response has been prepared by - Authlete's `/federation/configuration` API and it is available as the - `responseContent` response parameter. - The implementation of the entity configuration endpoint can construct an - HTTP response by doing like below. - ``` - 200 OK - Content-Type: application/entity-statement+jwt - (Other HTTP headers) - (the value of the responseContent response parameter) - ``` - - ### `NOT_FOUND` - When the value of the `action` response - parameter is `NOT_FOUND`, it means that - the service configuration has not enabled the feature of [OpenID Connect - Federation 1.0](https://openid.net/specs/openid-connect-federation-1_0.html) and so the client application should have not access the - entity configuration endpoint. - In this case, the implementation of the entity configuration endpoint of the - authorization server should return an HTTP response to the client application - with the HTTP status code "`404 Not Found`" and the content type - "`application/json`". The message body (= error information in the JSON - format) of the response has been prepared by Authlete's - `/federation/configuration` API and it is available as the - `responseContent` response parameter. - The implementation of the entity configuration endpoint can construct an - HTTP response by doing like below. - ``` - 404 Not Found - Content-Type: application/json - (Other HTTP headers) - (the value of the responseContent response parameter) - ``` - - ### `INTERNAL_SERVER_ERROR` - could prepare an entity configuration successfully. - In this case, the implementation of the entity configuration endpoint of the - authorization server should return an HTTP response to the client application - with the HTTP status code "`200 OK`" and the content type - "`application/entity-statement+jwt`". The message body (= an entity - configuration in the JWT format) of the response has been prepared by - Authlete's `/federation/configuration` API and it is available as the - `responseContent` response parameter. - The implementation of the entity configuration endpoint can construct an - HTTP response by doing like below. - ``` - 200 OK - Content-Type: application/entity-statement+jwt - (Other HTTP headers) - (the value of the responseContent response parameter) - ``` parameters: - in: path name: serviceId @@ -9478,50 +9540,56 @@ paths: the session id and verify or generate the device secret as required by the flow). The token endpoint implementation should retrieve the value of `action` from the response and take the following steps according to the value. + x-mint: + metadata: + description: "This API should be called by the implementation of a token endpoint to generate the ID token and token response that comply with [OpenID Connect Native SSO for Mobile Apps 1.0](https://openid.net/specs/openid-connect-native-sso-1_0.html) (Native SSO) when Authlete’s `/auth/token` response indicates `action = NATIVE_SSO` (after you validate the session id and verify or generate the device secret as required by the flow). The token endpoint implementation should retrieve the value of `action` from the response and take the following steps according to the value." + content: | + + ## OK - ## OK + When the action is `OK`, it indicates that the `/nativesso` API processing has successfully completed. + In this case, the token endpoint implementation should return a successful response (`200 OK`) to + the client. The value of the responseContent property in the `/nativesso` API response can be used + directly as the message body of the token response. Therefore, the success response can be constructed + as follows: - When the action is `OK`, it indicates that the `/nativesso` API processing has successfully completed. - In this case, the token endpoint implementation should return a successful response (`200 OK`) to - the client. The value of the responseContent property in the `/nativesso` API response can be used - directly as the message body of the token response. Therefore, the success response can be constructed - as follows: + ``` + HTTP/1.1 200 OK + Content-Type: application/json + Cache-Control: no-store - ``` - HTTP/1.1 200 OK - Content-Type: application/json - Cache-Control: no-store + (Embed the value of responseContent here.) + ``` - (Embed the value of responseContent here.) - ``` + ## INTERNAL_SERVER_ERROR - ## INTERNAL_SERVER_ERROR + When the action is `INTERNAL_SERVER_ERROR`, it indicates that something has gone wrong on the Authlete + side. For example, an issue such as a database error might have occurred when retrieving the access + token specified by the accessToken parameter from the database. - When the action is `INTERNAL_SERVER_ERROR`, it indicates that something has gone wrong on the Authlete - side. For example, an issue such as a database error might have occurred when retrieving the access - token specified by the accessToken parameter from the database. + In such cases, the token endpoint implementation should return an error response to the client. + The simplest implementation would be to return a `500 Internal Server Error`. - In such cases, the token endpoint implementation should return an error response to the client. - The simplest implementation would be to return a `500 Internal Server Error`. + ``` + HTTP/1.1 500 Internal Server Error + Content-Type: application/json + Cache-Control: no-store - ``` - HTTP/1.1 500 Internal Server Error - Content-Type: application/json - Cache-Control: no-store + (Embed the value of responseContent here.) + ``` - (Embed the value of responseContent here.) - ``` + However, in a production environment, it may be better to return a more abstract error (one that + does not directly describe the nature of the issue), rather than a `500` error. - However, in a production environment, it may be better to return a more abstract error (one that - does not directly describe the nature of the issue), rather than a `500` error. + ## CALLER_ERROR - ## CALLER_ERROR + When the action is `CALLER_ERROR`, it indicates that the issue lies with the caller of the API + (i.e., the implementation of the OpenID Provider). For example, this could be due to missing a + required parameter such as accessToken. - When the action is `CALLER_ERROR`, it indicates that the issue lies with the caller of the API - (i.e., the implementation of the OpenID Provider). For example, this could be due to missing a - required parameter such as accessToken. + If `CALLER_ERROR` is returned, please review the implementation of your OpenID Provider. + - If `CALLER_ERROR` is returned, please review the implementation of your OpenID Provider. parameters: - in: path name: serviceId @@ -9600,22 +9668,28 @@ paths: (Native SSO). This is accomplished by deleting access/refresh token records associated with the specified session ID. In Authlete's implementation, access/refresh token records can be associated with a session ID only through the mechanism introduced by Native SSO. + x-mint: + metadata: + description: "The `/nativesso/logout` API is supposed to be used to support the concept of \"logout from all applications\" in the context of [OpenID Connect Native SSO for Mobile Apps 1.0](https://openid.net/specs/openid-connect-native-sso-1_0.html) (Native SSO). This is accomplished by deleting access/refresh token records associated with the specified session ID. In Authlete's implementation, access/refresh token records can be associated with a session ID only through the mechanism introduced by Native SSO." + content: | + + A response from the `/nativesso/logout` API contains `action` response parameter. The possible values + are: - A response from the `/nativesso/logout` API contains `action` response parameter. The possible values - are: + ## OK - ## OK + When the action is `OK`, it indicates that the `/nativesso/logout` API call completed successfully. - When the action is `OK`, it indicates that the `/nativesso/logout` API call completed successfully. + ## SERVER_ERROR - ## SERVER_ERROR + When the action is `SERVER_ERROR`, it indicates that something has gone wrong on the Authlete side. - When the action is `SERVER_ERROR`, it indicates that something has gone wrong on the Authlete side. + ## CALLER_ERROR - ## CALLER_ERROR + When the action is `CALLER_ERROR`, it indicates that the `/nativesso/logout` API call contained a + problem. For example, the call may have been missing the required request parameter `sessionId`. + - When the action is `CALLER_ERROR`, it indicates that the `/nativesso/logout` API call contained a - problem. For example, the call may have been missing the required request parameter `sessionId`. parameters: - in: path name: serviceId @@ -9866,16 +9940,22 @@ components: description: | The set of scopes that the client application is allowed to request. This paramter will be one of the following. + x-mint: + metadata: + description: "The set of scopes that the client application is allowed to request. This paramter will be one of the following." + content: | + + - `null` + - an empty set + - a set with at least one element + + When the value of this parameter is `null`, it means that the set of scopes that the client + application is allowed to request is the set of the scopes that the service supports. When the + value of this parameter is an empty set, it means that the client application is not allowed to + request any scopes. When the value of this parameter is a set with at least one element, it means + that the set is the set of scopes that the client application is allowed to request. + - - `null` - - an empty set - - a set with at least one element - - When the value of this parameter is `null`, it means that the set of scopes that the client - application is allowed to request is the set of the scopes that the service supports. When the - value of this parameter is an empty set, it means that the client application is not allowed to - request any scopes. When the value of this parameter is a set with at least one element, it means - that the set is the set of scopes that the client application is allowed to request. requestableScopesEnabled: type: boolean description: | @@ -9986,16 +10066,22 @@ components: description: | The client secret. A random 512-bit value encoded by base64url (86 letters). The value of this property is assigned by Authlete. + x-mint: + metadata: + description: "The client secret. A random 512-bit value encoded by base64url (86 letters). The value of this property is assigned by Authlete." + content: | + + Note that Authlete issues a client secret even to a "public" client application, but the client + application should not use the client secret unless it changes its client type to "confidential". + That is, a public client application should behave as if it had not been issued a client secret. + To be specific, a token request from a public client of Authlete should not come along with a + client secret although [RFC 6749, 3.2.1. Client Authentication](https://datatracker.ietf.org/doc/html/rfc6749#section-3.2.1) + says as follows. + + > Confidential clients or other clients issued client credentials MUST authenticate with the + authorization server as described in Section 2.3 when making requests to the token endpoint. + - Note that Authlete issues a client secret even to a "public" client application, but the client - application should not use the client secret unless it changes its client type to "confidential". - That is, a public client application should behave as if it had not been issued a client secret. - To be specific, a token request from a public client of Authlete should not come along with a - client secret although [RFC 6749, 3.2.1. Client Authentication](https://datatracker.ietf.org/doc/html/rfc6749#section-3.2.1) - says as follows. - - > Confidential clients or other clients issued client credentials MUST authenticate with the - authorization server as described in Section 2.3 when making requests to the token endpoint. clientIdAlias: type: string description: | @@ -10096,45 +10182,51 @@ components: type: string description: | Redirect URIs that the client application uses to receive a response from the authorization endpoint. - Requirements for a redirect URI are as follows. - - **Requirements by RFC 6749** (From [RFC 6749, 3.1.2. Redirection Endpoint](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2)) - - - Must be an absolute URI. - - Must not have a fragment component. - - **Requirements by OpenID Connect** (From "[OpenID Connect Dynamic Client Registration 1.0, 2. - Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata), - application_type") - - - The scheme of the redirect URI used for Implicit Grant by a client application whose application - is `web` must be `https`. This is checked at runtime by Authlete. - - The hostname of the redirect URI used for Implicit Grant by a client application whose application - type is `web` must not be `localhost`. This is checked at runtime by Authlete. - - The scheme of the redirect URI used by a client application whose application type is `native` - must be either (1) a custom scheme or (2) `http`, which is allowed only when the hostname part - is `localhost`. This is checked at runtime by Authlete. - - ## Requirements by Authlete - - - Must consist of printable ASCII letters only. - - Must not exceed 200 letters. - - Note that Authlete allows the application type to be `null`. In other words, a client application - does not have to choose `web` or `native` as its application type. - If the application type is `null`, the requirements by OpenID Connect are not checked at runtime. - - An authorization request from a client application which has not registered any redirect URI - fails unless at least all the following conditions are satisfied. - - - The client type of the client application is `confidential`. - - The value of `response_type` request parameter is `code`. - - The authorization request has the `redirect_uri` request parameter. - - The value of `scope` request parameter does not contain `openid`. + Requirements for a redirect URI are as follows. + x-mint: + metadata: + description: "Redirect URIs that the client application uses to receive a response from the authorization endpoint. Requirements for a redirect URI are as follows." + content: | + + **Requirements by RFC 6749** (From [RFC 6749, 3.1.2. Redirection Endpoint](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2)) + + - Must be an absolute URI. + - Must not have a fragment component. + + **Requirements by OpenID Connect** (From "[OpenID Connect Dynamic Client Registration 1.0, 2. + Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata), + application_type") + + - The scheme of the redirect URI used for Implicit Grant by a client application whose application + is `web` must be `https`. This is checked at runtime by Authlete. + - The hostname of the redirect URI used for Implicit Grant by a client application whose application + type is `web` must not be `localhost`. This is checked at runtime by Authlete. + - The scheme of the redirect URI used by a client application whose application type is `native` + must be either (1) a custom scheme or (2) `http`, which is allowed only when the hostname part + is `localhost`. This is checked at runtime by Authlete. + + ## Requirements by Authlete + + - Must consist of printable ASCII letters only. + - Must not exceed 200 letters. + + Note that Authlete allows the application type to be `null`. In other words, a client application + does not have to choose `web` or `native` as its application type. + If the application type is `null`, the requirements by OpenID Connect are not checked at runtime. + + An authorization request from a client application which has not registered any redirect URI + fails unless at least all the following conditions are satisfied. + + - The client type of the client application is `confidential`. + - The value of `response_type` request parameter is `code`. + - The authorization request has the `redirect_uri` request parameter. + - The value of `scope` request parameter does not contain `openid`. + + RFC 6749 allows partial match of redirect URI under some conditions (see [RFC 6749, 3.1.2.2. + Registration Requirements](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2.2) for + details), but OpenID Connect requires exact match. + - RFC 6749 allows partial match of redirect URI under some conditions (see [RFC 6749, 3.1.2.2. - Registration Requirements](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2.2) for - details), but OpenID Connect requires exact match. authorizationSignAlg: $ref: '#/components/schemas/jws_alg' authorizationEncryptionAlg: @@ -10271,19 +10363,25 @@ components: The content pointed to by the URL is JSON which complies with the format described in [JSON Web Key (JWK), 5. JWK Set Format](https://datatracker.ietf.org/doc/html/rfc7517#section-5). The JWK Set must not include private keys of the client application. + x-mint: + metadata: + description: "The URL pointing to the JWK Set of the client application. The content pointed to by the URL is JSON which complies with the format described in [JSON Web Key (JWK), 5. JWK Set Format](https://datatracker.ietf.org/doc/html/rfc7517#section-5). The JWK Set must not include private keys of the client application." + content: | + + If the client application requests encryption for ID tokens (from the authorization/token/userinfo endpoints) + and/or signs request objects, it must make available its JWK Set containing public keys for the + encryption and/or the signature at the URL of `jwksUri`. The service (Authlete) fetches the JWK + Set from the URL as necessary. + + [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) + says that `jwks` must not be used when the client can use `jwks_uri`, but Authlete allows both + properties to be registered at the same time. However, Authlete does not use the content of `jwks` + when `jwksUri` is registered. + + This property corresponds to `jwks_uri` in [OpenID Connect Dynamic Client Registration 1.0, 2. + Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). + - If the client application requests encryption for ID tokens (from the authorization/token/userinfo endpoints) - and/or signs request objects, it must make available its JWK Set containing public keys for the - encryption and/or the signature at the URL of `jwksUri`. The service (Authlete) fetches the JWK - Set from the URL as necessary. - - [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) - says that `jwks` must not be used when the client can use `jwks_uri`, but Authlete allows both - properties to be registered at the same time. However, Authlete does not use the content of `jwks` - when `jwksUri` is registered. - - This property corresponds to `jwks_uri` in [OpenID Connect Dynamic Client Registration 1.0, 2. - Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). jwks: type: string description: | @@ -10291,14 +10389,20 @@ components: The format is described in [JSON Web Key (JWK), 5. JWK Set Format](https://datatracker.ietf.org/doc/html/rfc7517#section-5). The JWK Set must not include private keys of the client application. + x-mint: + metadata: + description: "The content of the JWK Set of the client application. The format is described in [JSON Web Key (JWK), 5. JWK Set Format](https://datatracker.ietf.org/doc/html/rfc7517#section-5). The JWK Set must not include private keys of the client application." + content: | + + [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) + says that `jwks` must not be used when the client can use `jwks_uri`, but Authlete allows both + properties to be registered at the same time. However, Authlete does not use the content of `jwks` + when `jwksUri` is registered. + + This property corresponds to `jwks_uri` in [OpenID Connect Dynamic Client Registration 1.0, 2. + Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). + - [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) - says that `jwks` must not be used when the client can use `jwks_uri`, but Authlete allows both - properties to be registered at the same time. However, Authlete does not use the content of `jwks` - when `jwksUri` is registered. - - This property corresponds to `jwks_uri` in [OpenID Connect Dynamic Client Registration 1.0, 2. - Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). userInfoSignAlg: nullable: true $ref: '#/components/schemas/jws_alg' @@ -10410,92 +10514,116 @@ components: type: string description: | The custom client metadata in JSON format. + x-mint: + metadata: + description: "The custom client metadata in JSON format." + content: | + + Standard specifications define client metadata as necessary. The following are such examples. + + * [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) + * [RFC 7591 OAuth 2.0 Dynamic Client Registration Protocol](https://www.rfc-editor.org/rfc/rfc7591.html) + * [RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens](https://www.rfc-editor.org/rfc/rfc8705.html) + * [OpenID Connect Client-Initiated Backchannel Authentication Flow - Core 1.0](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html) + * [The OAuth 2.0 Authorization Framework: JWT Secured Authorization Request (JAR)](https://datatracker.ietf.org/doc/draft-ietf-oauth-jwsreq/) + * [Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/openid-financial-api-jarm.html) + * [OAuth 2.0 Pushed Authorization Requests (PAR)](https://datatracker.ietf.org/doc/rfc9126/) + * [OAuth 2.0 Rich Authorization Requests (RAR)](https://datatracker.ietf.org/doc/draft-ietf-oauth-rar/) + + Standard client metadata included in Client Registration Request and Client Update Request (cf. + [OIDC DynReg](https://openid.net/specs/openid-connect-registration-1_0.html), [RFC 7591](https://www.rfc-editor.org/rfc/rfc7591.html) + and [RFC 7592](https://www.rfc-editor.org/rfc/rfc7592.html)) are, if supported by Authlete, set + to corresponding properties of the client application. For example, the value of the `client_name` + client metadata in Client Registration/Update Request is set to the clientName property. On the + other hand, unrecognized client metadata are discarded. + + By listing up custom client metadata in advance by using the `supportedCustomClientMetadata` property + of Service, Authlete can recognize them and stores their values into the database. The stored + custom client metadata values can be referenced by this property. + - Standard specifications define client metadata as necessary. The following are such examples. - - * [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) - * [RFC 7591 OAuth 2.0 Dynamic Client Registration Protocol](https://www.rfc-editor.org/rfc/rfc7591.html) - * [RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens](https://www.rfc-editor.org/rfc/rfc8705.html) - * [OpenID Connect Client-Initiated Backchannel Authentication Flow - Core 1.0](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html) - * [The OAuth 2.0 Authorization Framework: JWT Secured Authorization Request (JAR)](https://datatracker.ietf.org/doc/draft-ietf-oauth-jwsreq/) - * [Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/openid-financial-api-jarm.html) - * [OAuth 2.0 Pushed Authorization Requests (PAR)](https://datatracker.ietf.org/doc/rfc9126/) - * [OAuth 2.0 Rich Authorization Requests (RAR)](https://datatracker.ietf.org/doc/draft-ietf-oauth-rar/) - - Standard client metadata included in Client Registration Request and Client Update Request (cf. - [OIDC DynReg](https://openid.net/specs/openid-connect-registration-1_0.html), [RFC 7591](https://www.rfc-editor.org/rfc/rfc7591.html) - and [RFC 7592](https://www.rfc-editor.org/rfc/rfc7592.html)) are, if supported by Authlete, set - to corresponding properties of the client application. For example, the value of the `client_name` - client metadata in Client Registration/Update Request is set to the clientName property. On the - other hand, unrecognized client metadata are discarded. - - By listing up custom client metadata in advance by using the `supportedCustomClientMetadata` property - of Service, Authlete can recognize them and stores their values into the database. The stored - custom client metadata values can be referenced by this property. frontChannelRequestObjectEncryptionRequired: type: boolean description: | The flag indicating whether encryption of request object is required when the request object is passed through the front channel. + x-mint: + metadata: + description: "The flag indicating whether encryption of request object is required when the request object is passed through the front channel." + content: | + + 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](https://datatracker.ietf.org/doc/rfc9126/). + 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. + + Even if this flag is `false`, encryption of request object is required if the `frontChannelRequestObjectEncryptionRequired` + flag of the service is `true`. + - 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](https://datatracker.ietf.org/doc/rfc9126/). - 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. - - Even if this flag is `false`, encryption of request object is required if the `frontChannelRequestObjectEncryptionRequired` - flag of the service is `true`. requestObjectEncryptionAlgMatchRequired: type: boolean description: | The flag indicating whether the JWE alg of encrypted request object must match the `request_object_encryption_alg` client metadata. + x-mint: + metadata: + description: "The flag indicating whether the JWE alg of encrypted request object must match the `request_object_encryption_alg` client metadata." + content: | + + The `request_object_encryption_alg` client metadata itself is defined in [OpenID Connect Dynamic + Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) 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 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 service is `true`. + - The `request_object_encryption_alg` client metadata itself is defined in [OpenID Connect Dynamic - Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) 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 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 service is `true`. requestObjectEncryptionEncMatchRequired: type: boolean description: | The flag indicating whether the JWE enc of encrypted request object must match the `request_object_encryption_enc` client metadata. + x-mint: + metadata: + description: "The flag indicating whether the JWE enc of encrypted request object must match the `request_object_encryption_enc` client metadata." + content: | + + The `request_object_encryption_enc` client metadata itself is defined in [OpenID Connect Dynamic + Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) 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 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 of the service is `true`. + - The `request_object_encryption_enc` client metadata itself is defined in [OpenID Connect Dynamic - Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) 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 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 of the service is `true`. digestAlgorithm: type: string description: | @@ -10612,15 +10740,21 @@ components: $ref: '#/components/schemas/fapi_mode' description: | The FAPI modes for this client. + x-mint: + metadata: + description: "The FAPI modes for this client." + content: | + + When the value of this property is not `null`, Authlete always processes requests from this client + based on the specified FAPI modes if the FAPI feature is enabled in Authlete, the FAPI profile + is supported by the service, and the FAPI modes for the service are set to `null`. + + For instance, when this property is set to an array containing `FAPI1_ADVANCED` only, Authlete + always processes requests from this client based on "Financial-grade API Security Profile 1.0 - + Part 2: Advanced" if the FAPI feature is enabled in Authlete, the FAPI profile is supported by + the service, and the FAPI modes for the service are set to `null`. + - When the value of this property is not `null`, Authlete always processes requests from this client - based on the specified FAPI modes if the FAPI feature is enabled in Authlete, the FAPI profile - is supported by the service, and the FAPI modes for the service are set to `null`. - - For instance, when this property is set to an array containing `FAPI1_ADVANCED` only, Authlete - always processes requests from this client based on "Financial-grade API Security Profile 1.0 - - Part 2: Advanced" if the FAPI feature is enabled in Authlete, the FAPI profile is supported by - the service, and the FAPI modes for the service are set to `null`. responseModes: type: array items: @@ -11225,15 +11359,21 @@ components: format: int64 description: | The duration of pushed authorization requests in seconds. + x-mint: + metadata: + description: "The duration of pushed authorization requests in seconds." + content: | + + [OAuth 2.0 Pushed Authorization Requests](https://tools.ietf.org/html/draft-lodderstedt-oauth-par) + 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. + - [OAuth 2.0 Pushed Authorization Requests](https://tools.ietf.org/html/draft-lodderstedt-oauth-par) - 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: type: boolean description: | @@ -11259,19 +11399,25 @@ components: The flag to indicate whether a request object is processed based on rules defined in [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) or JAR (JWT Secured Authorization Request). + x-mint: + metadata: + description: "The flag to indicate whether a request object is processed based on rules defined in [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) or JAR (JWT Secured Authorization Request)." + content: | + + 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. + - 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: type: boolean description: | @@ -11288,21 +11434,27 @@ components: $ref: '#/components/schemas/named_uri' description: | The MTLS endpoint aliases. + x-mint: + metadata: + description: "The MTLS endpoint aliases." + content: | + + This property corresponds to the mtls_endpoint_aliases metadata defined in "5. Metadata for Mutual TLS Endpoint Aliases" of [OAuth 2.0 Mutual TLS Client Authentication and Certificate-Bound Access Tokens](https://datatracker.ietf.org/doc/rfc8705/). - This property corresponds to the mtls_endpoint_aliases metadata defined in "5. Metadata for Mutual TLS Endpoint Aliases" of [OAuth 2.0 Mutual TLS Client Authentication and Certificate-Bound Access Tokens](https://datatracker.ietf.org/doc/rfc8705/). + The aliases will be embedded in the response from the discovery endpoint like the following. - The aliases will be embedded in the response from the discovery endpoint like the following. - - ```json - { - ......, - "mtls_endpoint_aliases": { - "token_endpoint": "https://mtls.example.com/token", - "revocation_endpoint": "https://mtls.example.com/revo", - "introspection_endpoint": "https://mtls.example.com/introspect" + ```json + { + ......, + "mtls_endpoint_aliases": { + "token_endpoint": "https://mtls.example.com/token", + "revocation_endpoint": "https://mtls.example.com/revo", + "introspection_endpoint": "https://mtls.example.com/introspect" + } } - } - ``` + ``` + + accessTokenType: type: string description: | @@ -11378,36 +11530,48 @@ components: $ref: '#/components/schemas/scope' description: | Scopes supported by the service. + x-mint: + metadata: + description: "Scopes supported by the service." + content: | + + 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](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). 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](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) 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](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) 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](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) and [5.1.1. Address Claim](https://openid.net/specs/openid-connect-core-1_0.html#AddressClaim) 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](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) 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](https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess) for details. | - Authlete strongly recommends that the service register at least the following scopes. + The value of this property is used as `scopes_supported` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). + - | 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](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). 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](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) 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](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) 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](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) and [5.1.1. Address Claim](https://openid.net/specs/openid-connect-core-1_0.html#AddressClaim) 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](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) 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](https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess) for details. | - - The value of this property is used as `scopes_supported` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). scopeRequired: type: boolean description: | The flag to indicate whether requests that request no scope are rejected or not. + x-mint: + metadata: + description: "The flag to indicate whether requests that request no scope are rejected or not." + content: | + + 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. - 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](https://tools.ietf.org/html/rfc6749#section-3.3) + does not explicitly mention the case where the default scope set is empty. - The requirement below excerpted from [RFC 6749 Section 3.3](https://tools.ietf.org/html/rfc6749#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. - > 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`. + - 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: type: integer format: int64 @@ -11450,46 +11614,58 @@ components: Claim names that the service supports. The standard claim names listed in [OpenID Connect Core 1.0, 5.1. Standard Claim](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) should be supported. The following is the list of standard claims. + x-mint: + metadata: + description: "Claim names that the service supports. The standard claim names listed in [OpenID Connect Core 1.0, 5.1. Standard Claim](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) should be supported. The following is the list of standard claims." + content: | + + - `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](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). + + The service may support its original claim names. See [OpenID Connect Core 1.0, 5.1.2. Additional + Claims](https://openid.net/specs/openid-connect-core-1_0.html#AdditionalClaims). + - - `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](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). - - The service may support its original claim names. See [OpenID Connect Core 1.0, 5.1.2. Additional - Claims](https://openid.net/specs/openid-connect-core-1_0.html#AdditionalClaims). claimShortcutRestrictive: type: boolean description: | 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. + x-mint: + metadata: + description: "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." + content: | + + To strictly conform to the description below excerpted from [OpenID Connect Core 1.0 Section + 5.4](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims), 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. + - To strictly conform to the description below excerpted from [OpenID Connect Core 1.0 Section - 5.4](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims), 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: type: string format: uri @@ -11522,52 +11698,70 @@ components: type: string description: | The key ID to identify a JWK used for ID token signature using an asymmetric key. + x-mint: + metadata: + description: "The key ID to identify a JWK used for ID token signature using an asymmetric key." + content: | + + A JWK Set can be registered as a property of a Service. A JWK Set can contain 0 or more JWKs + (See [RFC 7517](https://tools.ietf.org/html/rfc7517) 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](https://tools.ietf.org/html/rfc7517#section-4.5) 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](http://openid.net/specs/openid-connect-core-1_0.html#RotateSigKeys)), + this mechanism is needed. + - A JWK Set can be registered as a property of a Service. A JWK Set can contain 0 or more JWKs - (See [RFC 7517](https://tools.ietf.org/html/rfc7517) 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](https://tools.ietf.org/html/rfc7517#section-4.5) 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](http://openid.net/specs/openid-connect-core-1_0.html#RotateSigKeys)), - this mechanism is needed. userInfoSignatureKeyId: type: string description: | The key ID to identify a JWK used for user info signature using an asymmetric key. + x-mint: + metadata: + description: "The key ID to identify a JWK used for user info signature using an asymmetric key." + content: | + + A JWK Set can be registered as a property of a Service. A JWK Set can contain 0 or more JWKs + (See [RFC 7517](https://tools.ietf.org/html/rfc7517) 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](http://openid.net/specs/openid-connect-core-1_0.html#UserInfo)) + 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](https://tools.ietf.org/html/rfc7517#section-4.5) + 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](http://openid.net/specs/openid-connect-core-1_0.html#RotateSigKeys)), + this mechanism is needed. + - A JWK Set can be registered as a property of a Service. A JWK Set can contain 0 or more JWKs - (See [RFC 7517](https://tools.ietf.org/html/rfc7517) 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](http://openid.net/specs/openid-connect-core-1_0.html#UserInfo)) - 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](https://tools.ietf.org/html/rfc7517#section-4.5) - 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](http://openid.net/specs/openid-connect-core-1_0.html#RotateSigKeys)), - this mechanism is needed. authorizationSignatureKeyId: type: string description: | The key ID to identify a JWK used for signing authorization responses using an asymmetric key. + x-mint: + metadata: + description: "The key ID to identify a JWK used for signing authorization responses using an asymmetric key." + content: | + + [Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/openid-financial-api-jarm.html) + 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. + + 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. + - [Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/openid-financial-api-jarm.html) - 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. - - 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: type: string description: | @@ -11664,15 +11858,21 @@ components: description: | 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. + x-mint: + metadata: + description: "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." + content: | + + 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. + - 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: type: string format: uri @@ -11693,17 +11893,23 @@ components: 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. + x-mint: + metadata: + description: "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." + content: | + + 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. - 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` - `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. - 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. + - If this URI is not set, the `verification_uri_complete` parameter won't appear in device authorization - responses. deviceFlowCodeDuration: type: integer format: int32 @@ -11775,154 +11981,196 @@ components: description: | 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. + x-mint: + metadata: + description: "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." + content: | + + 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. + - 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: type: boolean description: | The flag indicating whether generation of the iss response parameter is suppressed. + x-mint: + metadata: + description: "The flag indicating whether generation of the iss response parameter is suppressed." + content: | + + "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. - "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. - 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. - 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. + - Note that this flag should not be `true` in production environment unless there are special - reasons for it. supportedCustomClientMetadata: type: array items: type: string description: | custom client metadata supported by this service. + x-mint: + metadata: + description: "custom client metadata supported by this service." + content: | + + Standard specifications define client metadata as necessary. The following are such examples. + + * [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) + * [RFC 7591 OAuth 2.0 Dynamic Client Registration Protocol](https://www.rfc-editor.org/rfc/rfc7591.html) + * [RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens](https://www.rfc-editor.org/rfc/rfc8705.html) + * [OpenID Connect Client-Initiated Backchannel Authentication Flow - Core 1.0](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html) + * [The OAuth 2.0 Authorization Framework: JWT Secured Authorization Request (JAR)](https://datatracker.ietf.org/doc/draft-ietf-oauth-jwsreq/) + * [Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/openid-financial-api-jarm.html) + * [OAuth 2.0 Pushed Authorization Requests (PAR)](https://datatracker.ietf.org/doc/rfc9126/) + * [OAuth 2.0 Rich Authorization Requests (RAR)](https://datatracker.ietf.org/doc/draft-ietf-oauth-rar/) + + Standard client metadata included in Client Registration Request and Client Update Request (cf. + [OIDC DynReg](https://openid.net/specs/openid-connect-registration-1_0.html), [RFC 7591](https://www.rfc-editor.org/rfc/rfc7591.html) + and [RFC 7592](https://www.rfc-editor.org/rfc/rfc7592.html)) 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`. + - Standard specifications define client metadata as necessary. The following are such examples. - - * [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) - * [RFC 7591 OAuth 2.0 Dynamic Client Registration Protocol](https://www.rfc-editor.org/rfc/rfc7591.html) - * [RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens](https://www.rfc-editor.org/rfc/rfc8705.html) - * [OpenID Connect Client-Initiated Backchannel Authentication Flow - Core 1.0](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html) - * [The OAuth 2.0 Authorization Framework: JWT Secured Authorization Request (JAR)](https://datatracker.ietf.org/doc/draft-ietf-oauth-jwsreq/) - * [Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/openid-financial-api-jarm.html) - * [OAuth 2.0 Pushed Authorization Requests (PAR)](https://datatracker.ietf.org/doc/rfc9126/) - * [OAuth 2.0 Rich Authorization Requests (RAR)](https://datatracker.ietf.org/doc/draft-ietf-oauth-rar/) - - Standard client metadata included in Client Registration Request and Client Update Request (cf. - [OIDC DynReg](https://openid.net/specs/openid-connect-registration-1_0.html), [RFC 7591](https://www.rfc-editor.org/rfc/rfc7591.html) - and [RFC 7592](https://www.rfc-editor.org/rfc/rfc7592.html)) 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: type: boolean description: | The flag indicating whether the expiration date of an access token never exceeds that of the corresponding refresh token. + x-mint: + metadata: + description: "The flag indicating whether the expiration date of an access token never exceeds that of the corresponding refresh token." + content: | + + 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. + - 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: type: boolean description: | The flag indicating whether encryption of request object is required when the request object is passed through the front channel. + x-mint: + metadata: + description: "The flag indicating whether encryption of request object is required when the request object is passed through the front channel." + content: | + + 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](https://datatracker.ietf.org/doc/rfc9126/). + 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`. + - 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](https://datatracker.ietf.org/doc/rfc9126/). - 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: type: boolean description: | 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. + x-mint: + metadata: + description: "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." + content: | + + The request_object_encryption_alg client metadata itself is defined in [OpenID Connect Dynamic + Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) 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`. + - The request_object_encryption_alg client metadata itself is defined in [OpenID Connect Dynamic - Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) 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: type: boolean description: | 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. + x-mint: + metadata: + description: "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." + content: | + + The `request_object_encryption_enc` client metadata itself is defined in [OpenID Connect Dynamic + Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) 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 `request_object_encryption_enc` client metadata itself is defined in [OpenID Connect Dynamic - Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) 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. - 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`. + - Even if this flag is false, the match is required if the `requestObjectEncryptionEncMatchRequired` - flag is `true`. hsmEnabled: type: boolean description: | @@ -11953,34 +12201,46 @@ components: 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. + x-mint: + metadata: + description: "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." + content: | + + This property corresponds to the `grant_management_action_required` server metadata defined + in [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html). + + 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. + - This property corresponds to the `grant_management_action_required` server metadata defined - in [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html). - - 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: type: boolean description: | The flag indicating whether Authlete's `/api/client/registration` API uses `UNAUTHORIZED` as a value of the `action` response parameter when appropriate. + x-mint: + metadata: + description: "The flag indicating whether Authlete's `/api/client/registration` API uses `UNAUTHORIZED` as a value of the `action` response parameter when appropriate." + content: | + + 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](https://www.rfc-editor.org/rfc/rfc7592.html) + 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. + + 1. Update the Authlete library (e.g. authlete-java-common) your system is using. + 2. Update your implementation of client configuration endpoint so that it can handle the + `UNAUTHORIZED` action. + 3. Turn on this `unauthorizedOnClientConfigSupported` flag. + - 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](https://www.rfc-editor.org/rfc/rfc7592.html) - 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. - - 1. Update the Authlete library (e.g. authlete-java-common) your system is using. - 2. Update your implementation of client configuration endpoint so that it can handle the - `UNAUTHORIZED` action. - 3. Turn on this `unauthorizedOnClientConfigSupported` flag. dcrScopeUsedAsRequestable: type: boolean description: | @@ -12007,65 +12267,77 @@ components: description: | The flag indicating whether the port number component of redirection URIs can be variable when the host component indicates loopback. + x-mint: + metadata: + description: "The flag indicating whether the port number component of redirection URIs can be variable when the host component indicates loopback." + content: | + + 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]( + https://www.rfc-editor.org/rfc/rfc8252.html#section-7.3) of [RFC 8252 OAuth 2.0](https://www.rfc-editor.org/rfc/rfc8252.html) + for Native Apps. + + [3.1.2.3. Dynamic Configuration](https://www.rfc-editor.org/rfc/rfc6749.html#section-3.1.2.3) + of [RFC 6749](https://www.rfc-editor.org/rfc/rfc6749.html) states _"If the client registration + included the full redirection URI, the authorization server MUST compare the two URIs using + simple string comparison as defined in [RFC3986] Section 6.2.1."_ Also, the description of + `redirect_uri` in [3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) + of [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) states + _"This URI MUST exactly match one of the Redirection URI values for the Client pre-registered + at the OpenID Provider, with the matching performed as described in Section 6.2.1 of [RFC3986] + (**Simple String Comparison**)."_ These "Simple String Comparison" requirements are preceded + by this flag. That is, even when the conditions described in RFC 6749 and OpenID Connect Core 1.0 + are satisfied, the port number component of loopback redirection URIs can be variable when this + flag is `true`. + + [8.3. Loopback Redirect Considerations](https://www.rfc-editor.org/rfc/rfc8252.html#section-8.3) + of [RFC 8252](https://www.rfc-editor.org/rfc/rfc8252.html) states 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](https://www.rfc-editor.org/rfc/rfc8252.html) state + that loopback redirection URIs use the `"http"` scheme, but Authlete allows the port number + component to be variable in other cases (e.g. in the case of the `"https"` scheme), too. + - 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]( - https://www.rfc-editor.org/rfc/rfc8252.html#section-7.3) of [RFC 8252 OAuth 2.0](https://www.rfc-editor.org/rfc/rfc8252.html) - for Native Apps. - - [3.1.2.3. Dynamic Configuration](https://www.rfc-editor.org/rfc/rfc6749.html#section-3.1.2.3) - of [RFC 6749](https://www.rfc-editor.org/rfc/rfc6749.html) states _"If the client registration - included the full redirection URI, the authorization server MUST compare the two URIs using - simple string comparison as defined in [RFC3986] Section 6.2.1."_ Also, the description of - `redirect_uri` in [3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) - of [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) states - _"This URI MUST exactly match one of the Redirection URI values for the Client pre-registered - at the OpenID Provider, with the matching performed as described in Section 6.2.1 of [RFC3986] - (**Simple String Comparison**)."_ These "Simple String Comparison" requirements are preceded - by this flag. That is, even when the conditions described in RFC 6749 and OpenID Connect Core 1.0 - are satisfied, the port number component of loopback redirection URIs can be variable when this - flag is `true`. - - [8.3. Loopback Redirect Considerations](https://www.rfc-editor.org/rfc/rfc8252.html#section-8.3) - of [RFC 8252](https://www.rfc-editor.org/rfc/rfc8252.html) states 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](https://www.rfc-editor.org/rfc/rfc8252.html) state - that loopback redirection URIs use the `"http"` scheme, but Authlete allows the port number - component to be variable in other cases (e.g. in the case of the `"https"` scheme), too. requestObjectAudienceChecked: type: boolean description: | The flag indicating whether Authlete checks whether the `aud` claim of request objects matches the issuer identifier of this service. + x-mint: + metadata: + description: "The flag indicating whether Authlete checks whether the `aud` claim of request objects matches the issuer identifier of this service." + content: | + + [Section 6.1. Passing a Request Object by Value](https://openid.net/specs/openid-connect-core-1_0.html#JWTRequests) + of [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) has the following + statement. - [Section 6.1. Passing a Request Object by Value](https://openid.net/specs/openid-connect-core-1_0.html#JWTRequests) - of [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) has the following - statement. + > The `aud` value SHOULD be or include the OP's Issuer Identifier URL. - > The `aud` value SHOULD be or include the OP's Issuer Identifier URL. + Likewise, [Section 4. Request Object](https://www.rfc-editor.org/rfc/rfc9101.html#section-4) of + [RFC 9101](https://www.rfc-editor.org/rfc/rfc9101.html) (The OAuth 2.0 Authorization Framework: + JWT-Secured Authorization Request (JAR)) has the following statement. - Likewise, [Section 4. Request Object](https://www.rfc-editor.org/rfc/rfc9101.html#section-4) of - [RFC 9101](https://www.rfc-editor.org/rfc/rfc9101.html) (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](https://www.rfc-editor.org/rfc/rfc8414.html). - > The value of aud should be the value of the authorization server (AS) issuer, as defined in - [RFC 8414](https://www.rfc-editor.org/rfc/rfc8414.html). + 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. + - 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: type: boolean description: | @@ -12602,14 +12874,20 @@ components: type: string description: | The value of the `credential_configuration_ids` property of the credential offer. + x-mint: + metadata: + description: "The value of the `credential_configuration_ids` property of the credential offer." + content: | + + ``` + { + "credential_issuer": "...", + "credential_configuration_ids": [ ... ], + "grants": { ... } + } + ``` + - ``` - { - "credential_issuer": "...", - "credential_configuration_ids": [ ... ], - "grants": { ... } - } - ``` txCode: type: string description: | @@ -13300,65 +13578,83 @@ components: description: | The flag indicating whether encryption of request object is required when the request object is passed through the front channel. + x-mint: + metadata: + description: "The flag indicating whether encryption of request object is required when the request object is passed through the front channel." + content: | + + 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](https://datatracker.ietf.org/doc/rfc9126/). + 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. + + Even if this flag is `false`, encryption of request object is required if the `frontChannelRequestObjectEncryptionRequired` + flag of the service is `true`. + - 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](https://datatracker.ietf.org/doc/rfc9126/). - 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. - - Even if this flag is `false`, encryption of request object is required if the `frontChannelRequestObjectEncryptionRequired` - flag of the service is `true`. requestObjectEncryptionAlgMatchRequired: type: boolean description: | The flag indicating whether the JWE alg of encrypted request object must match the `request_object_encryption_alg` client metadata. + x-mint: + metadata: + description: "The flag indicating whether the JWE alg of encrypted request object must match the `request_object_encryption_alg` client metadata." + content: | + + The `request_object_encryption_alg` client metadata itself is defined in [OpenID Connect Dynamic + Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) 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 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 service is `true`. + - The `request_object_encryption_alg` client metadata itself is defined in [OpenID Connect Dynamic - Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) 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 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 service is `true`. requestObjectEncryptionEncMatchRequired: type: boolean description: | The flag indicating whether the JWE enc of encrypted request object must match the `request_object_encryption_enc` client metadata. + x-mint: + metadata: + description: "The flag indicating whether the JWE enc of encrypted request object must match the `request_object_encryption_enc` client metadata." + content: | + + The `request_object_encryption_enc` client metadata itself is defined in [OpenID Connect Dynamic + Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) 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 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 of the service is `true`. + - The `request_object_encryption_enc` client metadata itself is defined in [OpenID Connect Dynamic - Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) 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 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 of the service is `true`. singleAccessTokenPerSubject: type: boolean description: | @@ -13650,61 +13946,91 @@ components: type: string description: | The value of the `id_token` property in the claims request parameter or in the claims property in a request object. + x-mint: + metadata: + description: "The value of the `id_token` property in the claims request parameter or in the claims property in a request object." + content: | + + A client application may request certain claims be embedded in an ID token or in a response from the userInfo endpoint. + There are several ways. Including the `claims` request parameter and including the `claims` property in a request object are such examples. + In both the cases, the value of the `claims` parameter/property is JSON. Its format is described in [5.5. Requesting Claims using the "claims" + Request Parameter](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter). + + The following is an excerpt from the specification. + You can find `userinfo` and `id_token` are top-level properties. + + ```json + { + "userinfo": + { + "given_name": { "essential": true }, + "nickname": null, + "email": { "essential": true }, + "email_verified": { "essential": true }, + "picture": null, + "http://example.info/claims/groups": null + }, + "id_token": + { + "auth_time": { "essential": true }, + "acr": { "values": [ "urn:mace:incommon:iap:silver" ] } + } + } + ``` - A client application may request certain claims be embedded in an ID token or in a response from the userInfo endpoint. - There are several ways. Including the `claims` request parameter and including the `claims` property in a request object are such examples. - In both the cases, the value of the `claims` parameter/property is JSON. Its format is described in [5.5. Requesting Claims using the "claims" - Request Parameter](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter). - - The following is an excerpt from the specification. - You can find `userinfo` and `id_token` are top-level properties. + This value of this property is the value of the `id_token` property in JSON format. + For example, if the JSON above is included in an authorization request, this property holds JSON equivalent to the following. - ```json - { - "userinfo": - { - "given_name": { "essential": true }, - "nickname": null, - "email": { "essential": true }, - "email_verified": { "essential": true }, - "picture": null, - "http://example.info/claims/groups": null - }, - "id_token": + ```json { "auth_time": { "essential": true }, "acr": { "values": [ "urn:mace:incommon:iap:silver" ] } } - } - ``` - - This value of this property is the value of the `id_token` property in JSON format. - For example, if the JSON above is included in an authorization request, this property holds JSON equivalent to the following. + ``` - ```json - { - "auth_time": { "essential": true }, - "acr": { "values": [ "urn:mace:incommon:iap:silver" ] } - } - ``` + Note that if a request object is given and it contains the `claims` property and if the `claims` request parameter is also given, + this property holds the former value. + - Note that if a request object is given and it contains the `claims` property and if the `claims` request parameter is also given, - this property holds the former value. userInfoClaims: type: string description: | The value of the `userinfo` property in the `claims` request parameter or in the `claims` property in a request object. + x-mint: + metadata: + description: "The value of the `userinfo` property in the `claims` request parameter or in the `claims` property in a request object." + content: | + + A client application may request certain claims be embedded in an ID token or in a response from the userInfo endpoint. + There are several ways. Including the `claims` request parameter and including the `claims` property in a request object are such examples. + In both the cases, the value of the `claims` parameter/property is JSON. Its format is described in [5.5. Requesting Claims using the "claims" + Request Parameter](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter). + + The following is an excerpt from the specification. You can find `userinfo` and `id_token` are top-level properties. + + ```json + { + "userinfo": + { + "given_name": { "essential": true }, + "nickname": null, + "email": { "essential": true }, + "email_verified": { "essential": true }, + "picture": null, + "http://example.info/claims/groups": null + }, + "id_token": + { + "auth_time": { "essential": true }, + "acr": { "values": [ "urn:mace:incommon:iap:silver" ] } + } + } + ```` - A client application may request certain claims be embedded in an ID token or in a response from the userInfo endpoint. - There are several ways. Including the `claims` request parameter and including the `claims` property in a request object are such examples. - In both the cases, the value of the `claims` parameter/property is JSON. Its format is described in [5.5. Requesting Claims using the "claims" - Request Parameter](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter). - - The following is an excerpt from the specification. You can find `userinfo` and `id_token` are top-level properties. + The value of this property is the value of the `userinfo` property in JSON format. + For example, if the JSON above is included in an authorization request, this property holds JSON equivalent to the following. - ```json - { - "userinfo": + ```json { "given_name": { "essential": true }, "nickname": null, @@ -13712,31 +14038,13 @@ components: "email_verified": { "essential": true }, "picture": null, "http://example.info/claims/groups": null - }, - "id_token": - { - "auth_time": { "essential": true }, - "acr": { "values": [ "urn:mace:incommon:iap:silver" ] } } - } - ```` + ``` - The value of this property is the value of the `userinfo` property in JSON format. - For example, if the JSON above is included in an authorization request, this property holds JSON equivalent to the following. - - ```json - { - "given_name": { "essential": true }, - "nickname": null, - "email": { "essential": true }, - "email_verified": { "essential": true }, - "picture": null, - "http://example.info/claims/groups": null - } - ``` + Note that if a request object is given and it contains the `claims` property and if the `claims` request parameter is also given, + the value of this property holds the former value. + - Note that if a request object is given and it contains the `claims` property and if the `claims` request parameter is also given, - the value of this property holds the former value. resources: type: array items: @@ -13906,15 +14214,21 @@ components: description: | Flag which indicates whether [Native SSO](https://openid.net/specs/openid-connect-native-sso-1_0.html) is requested. This property should be set to `true` when all the following conditions are satisfied: + x-mint: + metadata: + description: "Flag which indicates whether [Native SSO](https://openid.net/specs/openid-connect-native-sso-1_0.html) is requested. This property should be set to `true` when all the following conditions are satisfied:" + content: | + + - The service supports Native SSO (see `nativeSsoSupported` property of Service). + - The service supports the `openid` and `device_sso` scopes. + - The client is allowed to request the `openid` and `device_sso` scopes. + - The authorization request includes the `openid` and `device_sso` scopes. + - The authorization request's `response_type` includes `code`. + + NOTE: If this property is set to `true`, the `sessionId` request parameter must be provided + to the `/auth/authorization/issue` API. + - - The service supports Native SSO (see `nativeSsoSupported` property of Service). - - The service supports the `openid` and `device_sso` scopes. - - The client is allowed to request the `openid` and `device_sso` scopes. - - The authorization request includes the `openid` and `device_sso` scopes. - - The authorization request's `response_type` includes `code`. - - NOTE: If this property is set to `true`, the `sessionId` request parameter must be provided - to the `/auth/authorization/issue` API. metadataDocumentUsed: type: boolean description: | @@ -14063,10 +14377,16 @@ components: to support the [OpenID Connect Native SSO for Mobile Apps 1.0](https://openid.net/specs/openid-connect-native-sso-1_0.html) specification (a.k.a. "Native SSO"). To enable support for the Native SSO specification, the `nativeSsoSupported` property of your service must be set to `true`. + x-mint: + metadata: + description: "The session ID of the user's authentication session. The specified value will be embedded in the ID token as the value of the `sid` claim. This parameter needs to be provided only if you want to support the [OpenID Connect Native SSO for Mobile Apps 1.0](https://openid.net/specs/openid-connect-native-sso-1_0.html) specification (a.k.a. \"Native SSO\"). To enable support for the Native SSO specification, the `nativeSsoSupported` property of your service must be set to `true`." + content: | + + NOTE: When the response from the `/auth/authorization` API contains the `nativeSsoRequested` + property with a value of `true`, the `sessionId` request parameter must be provided to the + `/auth/authorization/issue` API. + - NOTE: When the response from the `/auth/authorization` API contains the `nativeSsoRequested` - property with a value of `true`, the `sessionId` request parameter must be provided to the - `/auth/authorization/issue` API. idTokenAudType: type: string description: | @@ -14085,66 +14405,72 @@ components: type: string description: | Values of verified claims requested indirectly by "transformed claims". - - A client application may request "transformed claims". Each of transformed claims uses an existing - claim as input. As a result, to compute the value of a transformed claim, the value of the referenced - existing claim is needed. This `verifiedClaimsForTx` request parameter has to be used to provide - values of existing claims for computation of transformed claims. - - A response from the `/auth/authorization` API may include the `requestedVerifiedClaimsForTx` response - parameter which is a list of verified claims that are referenced indirectly by transformed claims - (cf. `requestedVerifiedClaimsForTx` in `/auth/authorization` API response). The authorization - server implementation should prepare values of the verified claims listed in `requestedVerifiedClaimsForTx` - and pass them as the value of this `verifiedClaimsForTx` request parameter. - - The following is an example of the value of this request parameter. - - ``` - [ - "{\"birthdate\":\"1970-01-23\",\"nationalities\":[\"DEU\",\"USA\"]}" - ] - ``` - - The reason that this `verifiedClaimsForTx` property is an array is that the `"verified_claims"` - property in the claims request parameter of an authorization request can be an array like below. - - ``` - { - "transformed_claims": { - "nationality_usa": { - "claim": "nationalities", - "fn": [ - [ "eq", "USA" ], - "any" + x-mint: + metadata: + description: "Values of verified claims requested indirectly by \"transformed claims\"." + content: | + + A client application may request "transformed claims". Each of transformed claims uses an existing + claim as input. As a result, to compute the value of a transformed claim, the value of the referenced + existing claim is needed. This `verifiedClaimsForTx` request parameter has to be used to provide + values of existing claims for computation of transformed claims. + + A response from the `/auth/authorization` API may include the `requestedVerifiedClaimsForTx` response + parameter which is a list of verified claims that are referenced indirectly by transformed claims + (cf. `requestedVerifiedClaimsForTx` in `/auth/authorization` API response). The authorization + server implementation should prepare values of the verified claims listed in `requestedVerifiedClaimsForTx` + and pass them as the value of this `verifiedClaimsForTx` request parameter. + + The following is an example of the value of this request parameter. + + ``` + [ + "{\"birthdate\":\"1970-01-23\",\"nationalities\":[\"DEU\",\"USA\"]}" + ] + ``` + + The reason that this `verifiedClaimsForTx` property is an array is that the `"verified_claims"` + property in the claims request parameter of an authorization request can be an array like below. + + ``` + { + "transformed_claims": { + "nationality_usa": { + "claim": "nationalities", + "fn": [ + [ "eq", "USA" ], + "any" + ] + } + }, + "id_token": { + "verified_claims": [ + { + "verification": { "trust_framework": { "value": "gold" } }, + "claims": { "::18_or_above": null } + }, + { + "verification": { "trust_framework": { "value": "silver" } }, + "claims": { ":nationality_usa": null } + } ] } - }, - "id_token": { - "verified_claims": [ - { - "verification": { "trust_framework": { "value": "gold" } }, - "claims": { "::18_or_above": null } - }, - { - "verification": { "trust_framework": { "value": "silver" } }, - "claims": { ":nationality_usa": null } - } - ] } - } - ``` + ``` - For the example above, the value of this `verifiedClaimsForTx` property should be an array of - size 2 and look like below. The first element is JSON including claims which have been verified - under the trust framework `"gold"`, and the second element is JSON including claims which have - been verified under the trust framework `"silver"`. + For the example above, the value of this `verifiedClaimsForTx` property should be an array of + size 2 and look like below. The first element is JSON including claims which have been verified + under the trust framework `"gold"`, and the second element is JSON including claims which have + been verified under the trust framework `"silver"`. + + ``` + [ + "{\"birthdate\":\"1970-01-23\"}", + "{\"nationalities\":[\"DEU\",\"USA\"]}" + ] + ``` + - ``` - [ - "{\"birthdate\":\"1970-01-23\"}", - "{\"nationalities\":[\"DEU\",\"USA\"]}" - ] - ``` authorization_ticket_info: type: object properties: @@ -14750,24 +15076,36 @@ components: be used as the value of this `deviceSecret` request parameter to the `/nativesso` API. The authorization server may choose to issue a new device secret; in that case, it is free to generate a new device secret and specify the new value. + x-mint: + metadata: + description: "If the response from the `/auth/token` API contains the `deviceSecret` parameter, its value should be used as the value of this `deviceSecret` request parameter to the `/nativesso` API. The authorization server may choose to issue a new device secret; in that case, it is free to generate a new device secret and specify the new value." + content: | + + If the response from the `/auth/token` API does not contain the `deviceSecret` parameter, or + if its value is invalid, the authorization server must generate a new device secret and specify + it in the deviceSecret parameter to the `/nativesso` API. + + The specified value is used as the value of the `device_secret` property in the token response. + - If the response from the `/auth/token` API does not contain the `deviceSecret` parameter, or - if its value is invalid, the authorization server must generate a new device secret and specify - it in the deviceSecret parameter to the `/nativesso` API. - - The specified value is used as the value of the `device_secret` property in the token response. deviceSecretHash: type: string description: | The authorization server should compute the hash value of the device secret based on its own logic and specify the computed hash as the value of this `deviceSecretHash` request parameter to the `/nativesso` API. + x-mint: + metadata: + description: "The authorization server should compute the hash value of the device secret based on its own logic and specify the computed hash as the value of this `deviceSecretHash` request parameter to the `/nativesso` API." + content: | + + When the `deviceSecretHash` parameter is omitted, the implementation of the `/nativesso` API + generates the device secret hash by computing the SHA-256 hash of the device secret and encoding + it with base64url. Note that this hash computation logic is not a rule defined in the Native SSO + specification; rather, it is Authlete-specific fallback logic used when the `deviceSecretHash` + parameter is omitted. + - When the `deviceSecretHash` parameter is omitted, the implementation of the `/nativesso` API - generates the device secret hash by computing the SHA-256 hash of the device secret and encoding - it with base64url. Note that this hash computation logic is not a rule defined in the Native SSO - specification; rather, it is Authlete-specific fallback logic used when the `deviceSecretHash` - parameter is omitted. metadataDocumentLocation: type: string format: uri @@ -15100,22 +15438,28 @@ components: type: string description: | The target URI of the resource request, including the query part, if any. + x-mint: + metadata: + description: "The target URI of the resource request, including the query part, if any." + content: | + + This parameter is used as the value of the @target-uri derived component for HTTP message signatures + [RFC 9421 HTTP Message Signatures, Section 2.2.2. Target URI](https://www.rfc-editor.org/rfc/rfc9421.html#section-2.2.2)). + Additionally, other derived components such as `@authority`, `@scheme`, `@path`, `@query` and + `@query-param` are computed from this parameter. + + When this parameter is omitted, the value of the `htu` parameter is used. The `htu` parameter + represents the URL of the resource endpoint, which is identical to the target URI of the resource + request as long as the request does not include a query component. Conversely, if the resource + request includes a query component, the value of the `htu` parameter will not match the target + URI, and in that case, the HTTP message signature verification will fail. + + If neither this `targetUri` parameter nor the `htu` parameter is specified, the target URI is + considered unavailable. If HTTP message signing requires the target-uri derived component or + other derived components computed based on the target URI, the HTTP message signature verification + will fail. + - This parameter is used as the value of the @target-uri derived component for HTTP message signatures - [RFC 9421 HTTP Message Signatures, Section 2.2.2. Target URI](https://www.rfc-editor.org/rfc/rfc9421.html#section-2.2.2)). - Additionally, other derived components such as `@authority`, `@scheme`, `@path`, `@query` and - `@query-param` are computed from this parameter. - - When this parameter is omitted, the value of the `htu` parameter is used. The `htu` parameter - represents the URL of the resource endpoint, which is identical to the target URI of the resource - request as long as the request does not include a query component. Conversely, if the resource - request includes a query component, the value of the `htu` parameter will not match the target - URI, and in that case, the HTTP message signature verification will fail. - - If neither this `targetUri` parameter nor the `htu` parameter is specified, the target URI is - considered unavailable. If HTTP message signing requires the target-uri derived component or - other derived components computed based on the target URI, the HTTP message signature verification - will fail. dpopNonceRequired: type: boolean description: | @@ -15232,15 +15576,21 @@ components: type: string description: | The target resources this proeprty holds may be the same as or different from the ones `resource` property holds. + x-mint: + metadata: + description: "The target resources this proeprty holds may be the same as or different from the ones `resource` property holds." + content: | + + In some flows, the initial request and the subsequent token request are sent to different endpoints. + Example flows are the Authorization Code Flow, the Refresh Token Flow, the CIBA Ping Mode, the CIBA Poll Mode and the Device Flow. + In these flows, not only the initial request but also the subsequent token request can include the `resource` request parameters. + The purpose of the `resource` request parameters in the token request is to narrow the range of the target resources from the original + set of target resources requested by the preceding initial request. If narrowing down is performed, the target resources holded by the + `resource` proeprty and the ones holded by this property are different. This property holds the narrowed set of target resources. + + See "Resource Indicators for OAuth 2.0" for details. + - In some flows, the initial request and the subsequent token request are sent to different endpoints. - Example flows are the Authorization Code Flow, the Refresh Token Flow, the CIBA Ping Mode, the CIBA Poll Mode and the Device Flow. - In these flows, not only the initial request but also the subsequent token request can include the `resource` request parameters. - The purpose of the `resource` request parameters in the token request is to narrow the range of the target resources from the original - set of target resources requested by the preceding initial request. If narrowing down is performed, the target resources holded by the - `resource` proeprty and the ones holded by this property are different. This property holds the narrowed set of target resources. - - See "Resource Indicators for OAuth 2.0" for details. authorizationDetails: $ref: '#/components/schemas/authz_details' serviceAttributes: @@ -15591,20 +15941,26 @@ components: type: string description: | The target URI of the userinfo request, including the query part, if any. + x-mint: + metadata: + description: "The target URI of the userinfo request, including the query part, if any." + content: | + + This parameter is used as the value of the `@target-uri` derived component for HTTP message signatures + ([RFC 9421 HTTP Message Signatures, Section 2.2.2. Target URI](https://www.rfc-editor.org/rfc/rfc9421.html#section-2.2.2)). + Additionally, other derived components such as `@authority`, `@scheme`, `@path`, `@query` and + `@query-param` are computed from this parameter. + + When this parameter is omitted, the value of the `htu` parameter is used. The `htu` parameter + represents the URL of the userinfo endpoint, which usually serves as the target URI of the userinfo request. + The only exception is when the access token is specified as a query parameter, as defined in + [RFC 6750 Section 2.3](https://www.rfc-editor.org/rfc/rfc6750.html#section-2.3). However, RFC 6750 + states that this method "SHOULD NOT be used" unless other methods are not viable. + + If neither this `targetUri` parameter nor the `htu` parameter is specified, the `userInfoEndpoint` + property of the service is used as a fallback. + - This parameter is used as the value of the `@target-uri` derived component for HTTP message signatures - ([RFC 9421 HTTP Message Signatures, Section 2.2.2. Target URI](https://www.rfc-editor.org/rfc/rfc9421.html#section-2.2.2)). - Additionally, other derived components such as `@authority`, `@scheme`, `@path`, `@query` and - `@query-param` are computed from this parameter. - - When this parameter is omitted, the value of the `htu` parameter is used. The `htu` parameter - represents the URL of the userinfo endpoint, which usually serves as the target URI of the userinfo request. - The only exception is when the access token is specified as a query parameter, as defined in - [RFC 6750 Section 2.3](https://www.rfc-editor.org/rfc/rfc6750.html#section-2.3). However, RFC 6750 - states that this method "SHOULD NOT be used" unless other methods are not viable. - - If neither this `targetUri` parameter nor the `htu` parameter is specified, the `userInfoEndpoint` - property of the service is used as a fallback. dpopNonceRequired: type: boolean description: | @@ -15618,17 +15974,23 @@ components: type: boolean description: | The flag indicating whether the userinfo request contains a request body. + x-mint: + metadata: + description: "The flag indicating whether the userinfo request contains a request body." + content: | + + When the userinfo request must comply with the HTTP message signing requirements defined in the + FAPI 2.0 Message Signing specification, the `"content-digest"` component identifier must be included + in the signature base of the HTTP message signature (see [RFC 9421 HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421.html)) + if the userinfo request contains a request body. + + When this `requestBodyContained` parameter is set to `true`, Authlete checks whether `"content-digest"` + is included in the signature base, if the FAPI profile applies to the userinfo request. + + NOTE: The FAPI 2.0 Message Signing specification is not applied to the userinfo endpoint until + its necessity is agreed upon by the industry (cf. [FAPI Issue 723](https://bitbucket.org/openid/fapi/issues/723)). + - When the userinfo request must comply with the HTTP message signing requirements defined in the - FAPI 2.0 Message Signing specification, the `"content-digest"` component identifier must be included - in the signature base of the HTTP message signature (see [RFC 9421 HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421.html)) - if the userinfo request contains a request body. - - When this `requestBodyContained` parameter is set to `true`, Authlete checks whether `"content-digest"` - is included in the signature base, if the FAPI profile applies to the userinfo request. - - NOTE: The FAPI 2.0 Message Signing specification is not applied to the userinfo endpoint until - its necessity is agreed upon by the industry (cf. [FAPI Issue 723](https://bitbucket.org/openid/fapi/issues/723)). userinfo_response: type: object properties: @@ -15696,17 +16058,41 @@ components: type: string description: | The value of the `userinfo` property in the `claims` request parameter or in the `claims` property in an authorization request object. + x-mint: + metadata: + description: "The value of the `userinfo` property in the `claims` request parameter or in the `claims` property in an authorization request object." + content: | + + A client application may request certain claims be embedded in an ID token or in a response from the userInfo endpoint. + There are several ways. Including the `claims` request parameter and including the `claims` property in a request object are such examples. + In both cases, the value of the `claims` parameter/property is JSON. Its format is described in [5.5. Requesting Claims using the "claims" + Request Parameter](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter). + + The following is an excerpt from the specification. You can find `userinfo` and `id_token` are top-level properties. + + ```json + { + "userinfo": + { + "given_name": { "essential": true }, + "nickname": null, + "email": { "essential": true }, + "email_verified": { "essential": true }, + "picture": null, + "http://example.info/claims/groups": null + }, + "id_token": + { + "auth_time": { "essential": true }, + "acr": { "values": [ "urn:mace:incommon:iap:silver" ] } + } + } + ```` - A client application may request certain claims be embedded in an ID token or in a response from the userInfo endpoint. - There are several ways. Including the `claims` request parameter and including the `claims` property in a request object are such examples. - In both cases, the value of the `claims` parameter/property is JSON. Its format is described in [5.5. Requesting Claims using the "claims" - Request Parameter](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter). - - The following is an excerpt from the specification. You can find `userinfo` and `id_token` are top-level properties. + The value of this property is the value of the `userinfo` property in JSON format. + For example, if the JSON above is included in an authorization request, this property holds JSON equivalent to the following. - ```json - { - "userinfo": + ```json { "given_name": { "essential": true }, "nickname": null, @@ -15714,31 +16100,13 @@ components: "email_verified": { "essential": true }, "picture": null, "http://example.info/claims/groups": null - }, - "id_token": - { - "auth_time": { "essential": true }, - "acr": { "values": [ "urn:mace:incommon:iap:silver" ] } } - } - ```` + ``` - The value of this property is the value of the `userinfo` property in JSON format. - For example, if the JSON above is included in an authorization request, this property holds JSON equivalent to the following. - - ```json - { - "given_name": { "essential": true }, - "nickname": null, - "email": { "essential": true }, - "email_verified": { "essential": true }, - "picture": null, - "http://example.info/claims/groups": null - } - ``` + Note that if a request object is given and it contains the `claims` property and if the `claims` request parameter is also given, + the value of this property holds the former value. + - Note that if a request object is given and it contains the `claims` property and if the `claims` request parameter is also given, - the value of this property holds the former value. serviceAttributes: type: array items: @@ -15901,66 +16269,72 @@ components: type: string description: | Values of verified claims requested indirectly by "transformed claims". - - A client application may request "transformed claims". Each of transformed claims uses an existing - claim as input. As a result, to compute the value of a transformed claim, the value of the referenced - existing claim is needed. This `verifiedClaimsForTx` request parameter has to be used to provide - values of existing claims for computation of transformed claims. - - A response from the `/auth/userinfo` API may include the `requestedVerifiedClaimsForTx` response - parameter which is a list of verified claims that are referenced indirectly by transformed claims - (cf. `requestedVerifiedClaimsForTx` in `/auth/userinfo` API response). The authorization server - implementation should prepare values of the verified claims listed in `requestedVerifiedClaimsForTx` - and pass them as the value of this `verifiedClaimsForTx` request parameter. - - The following is an example of the value of this request parameter. - - ``` - [ - "{\"birthdate\":\"1970-01-23\",\"nationalities\":[\"DEU\",\"USA\"]}" - ] - ``` - - The reason that this `verifiedClaimsForTx` property is an array is that the `"verified_claims"` - property in the claims request parameter of an authorization request can be an array like below. - - ``` - { - "transformed_claims": { - "nationality_usa": { - "claim": "nationalities", - "fn": [ - [ "eq", "USA" ], - "any" + x-mint: + metadata: + description: "Values of verified claims requested indirectly by \"transformed claims\"." + content: | + + A client application may request "transformed claims". Each of transformed claims uses an existing + claim as input. As a result, to compute the value of a transformed claim, the value of the referenced + existing claim is needed. This `verifiedClaimsForTx` request parameter has to be used to provide + values of existing claims for computation of transformed claims. + + A response from the `/auth/userinfo` API may include the `requestedVerifiedClaimsForTx` response + parameter which is a list of verified claims that are referenced indirectly by transformed claims + (cf. `requestedVerifiedClaimsForTx` in `/auth/userinfo` API response). The authorization server + implementation should prepare values of the verified claims listed in `requestedVerifiedClaimsForTx` + and pass them as the value of this `verifiedClaimsForTx` request parameter. + + The following is an example of the value of this request parameter. + + ``` + [ + "{\"birthdate\":\"1970-01-23\",\"nationalities\":[\"DEU\",\"USA\"]}" + ] + ``` + + The reason that this `verifiedClaimsForTx` property is an array is that the `"verified_claims"` + property in the claims request parameter of an authorization request can be an array like below. + + ``` + { + "transformed_claims": { + "nationality_usa": { + "claim": "nationalities", + "fn": [ + [ "eq", "USA" ], + "any" + ] + } + }, + "userinfo": { + "verified_claims": [ + { + "verification": { "trust_framework": { "value": "gold" } }, + "claims": { "::18_or_above": null } + }, + { + "verification": { "trust_framework": { "value": "silver" } }, + "claims": { ":nationality_usa": null } + } ] } - }, - "userinfo": { - "verified_claims": [ - { - "verification": { "trust_framework": { "value": "gold" } }, - "claims": { "::18_or_above": null } - }, - { - "verification": { "trust_framework": { "value": "silver" } }, - "claims": { ":nationality_usa": null } - } - ] } - } - ``` + ``` - For the example above, the value of this `verifiedClaimsForTx` property should be an array of - size 2 and look like below. The first element is JSON including claims which have been verified - under the trust framework `"gold"`, and the second element is JSON including claims which have - been verified under the trust framework `"silver"`. + For the example above, the value of this `verifiedClaimsForTx` property should be an array of + size 2 and look like below. The first element is JSON including claims which have been verified + under the trust framework `"gold"`, and the second element is JSON including claims which have + been verified under the trust framework `"silver"`. + + ``` + [ + "{\"birthdate\":\"1970-01-23\"}", + "{\"nationalities\":[\"DEU\",\"USA\"]}" + ] + ``` + - ``` - [ - "{\"birthdate\":\"1970-01-23\"}", - "{\"nationalities\":[\"DEU\",\"USA\"]}" - ] - ``` userinfo_issue_response: type: object properties: @@ -16323,15 +16697,21 @@ components: $ref: '#/components/schemas/scope' description: | The scopes requested by the backchannel authentication request. + x-mint: + metadata: + description: "The scopes requested by the backchannel authentication request." + content: | + + Basically, this property holds the value of the `scope` request parameter in the backchannel + authentication request. However, because unregistered scopes are dropped on Authlete side, + if the `scope` request parameter contains unknown scopes, the list returned by this + property becomes different from the value of the `scope` request parameter. + + Note that `description` property and `descriptions` property of each `scope` object + in the array contained in this property is always null even if descriptions of the scopes + are registered. + - Basically, this property holds the value of the `scope` request parameter in the backchannel - authentication request. However, because unregistered scopes are dropped on Authlete side, - if the `scope` request parameter contains unknown scopes, the list returned by this - property becomes different from the value of the `scope` request parameter. - - Note that `description` property and `descriptions` property of each `scope` object - in the array contained in this property is always null even if descriptions of the scopes - are registered. claimNames: type: array items: @@ -16971,15 +17351,21 @@ components: $ref: '#/components/schemas/scope' description: | The scopes requested by the device authorization request. + x-mint: + metadata: + description: "The scopes requested by the device authorization request." + content: | + + Basically, this property holds the value of the scope request parameter in the device + authorization request. However, because unregistered scopes are dropped on Authlete + side, if the `scope` request parameter contains unknown scopes, the list returned by + this property becomes different from the value of the `scope` request parameter. + + Note that `description` property and `descriptions` property of each scope object in the + array contained in this property is always `null` even if descriptions of the scopes + are registered. + - Basically, this property holds the value of the scope request parameter in the device - authorization request. However, because unregistered scopes are dropped on Authlete - side, if the `scope` request parameter contains unknown scopes, the list returned by - this property becomes different from the value of the `scope` request parameter. - - Note that `description` property and `descriptions` property of each scope object in the - array contained in this property is always `null` even if descriptions of the scopes - are registered. claimNames: type: array items: @@ -17492,46 +17878,64 @@ components: description: | A boolean request parameter which indicates whether to emulate that the client ID alias is used instead of the original numeric client ID when a new access token is created. + x-mint: + metadata: + description: "A boolean request parameter which indicates whether to emulate that the client ID alias is used instead of the original numeric client ID when a new access token is created." + content: | + + This has an effect only on the value of the aud claim in a response from [UserInfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo). + When you access the UserInfo endpoint (which is expected to be implemented using Authlete's + `/api/auth/userinfo` API and `/api/auth/userinfo/issue` API) with an access token which has been + created using Authlete's `/api/auth/token/create` API with this property (`clientIdAliasUsed`) + `true`, the client ID alias is used as the value of the aud claim in a response from the UserInfo + endpoint. + + Note that if a client ID alias is not assigned to the client when Authlete's `/api/auth/token/create` + API is called, this property (`clientIdAliasUsed`) has no effect (it is always regarded as `false`). + - This has an effect only on the value of the aud claim in a response from [UserInfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo). - When you access the UserInfo endpoint (which is expected to be implemented using Authlete's - `/api/auth/userinfo` API and `/api/auth/userinfo/issue` API) with an access token which has been - created using Authlete's `/api/auth/token/create` API with this property (`clientIdAliasUsed`) - `true`, the client ID alias is used as the value of the aud claim in a response from the UserInfo - endpoint. - - Note that if a client ID alias is not assigned to the client when Authlete's `/api/auth/token/create` - API is called, this property (`clientIdAliasUsed`) has no effect (it is always regarded as `false`). accessToken: type: string description: | The value of the new access token. + x-mint: + metadata: + description: "The value of the new access token." + content: | + + The `/api/auth/token/create` API generates an access token. Therefore, callers of the API do not + have to specify values of newly created access tokens. However, in some cases, for example, if + you want to migrate existing access tokens from an old system to Authlete, you may want to specify + values of access tokens. In such a case, you can specify the value of a newly created access token + by passing a non-null value as the value of accessToken request parameter. The implementation + of the `/api/auth/token/create` uses the value of the accessToken request parameter instead of + generating a new value when the request parameter holds a non-null value. + + Note that if the hash value of the specified access token already exists in Authlete's database, + the access token cannot be inserted and the `/api/auth/token/create` API will report an error. + - The `/api/auth/token/create` API generates an access token. Therefore, callers of the API do not - have to specify values of newly created access tokens. However, in some cases, for example, if - you want to migrate existing access tokens from an old system to Authlete, you may want to specify - values of access tokens. In such a case, you can specify the value of a newly created access token - by passing a non-null value as the value of accessToken request parameter. The implementation - of the `/api/auth/token/create` uses the value of the accessToken request parameter instead of - generating a new value when the request parameter holds a non-null value. - - Note that if the hash value of the specified access token already exists in Authlete's database, - the access token cannot be inserted and the `/api/auth/token/create` API will report an error. refreshToken: type: string description: | The value of the new refresh token. + x-mint: + metadata: + description: "The value of the new refresh token." + content: | + + The `/api/auth/token/create` API may generate a refresh token. Therefore, callers of the API do + not have to specify values of newly created refresh tokens. However, in some cases, for example, + if you want to migrate existing refresh tokens from an old system to Authlete, you may want to + specify values of refresh tokens. In such a case, you can specify the value of a newly created + refresh token by passing a non-null value as the value of refreshToken request parameter. The + implementation of the `/api/auth/token/create` uses the value of the refreshToken request parameter + instead of generating a new value when the request parameter holds a non-null value. + + Note that if the hash value of the specified refresh token already exists in Authlete's database, + the refresh token cannot be inserted and the `/api/auth/token/create` API will report an error. + - The `/api/auth/token/create` API may generate a refresh token. Therefore, callers of the API do - not have to specify values of newly created refresh tokens. However, in some cases, for example, - if you want to migrate existing refresh tokens from an old system to Authlete, you may want to - specify values of refresh tokens. In such a case, you can specify the value of a newly created - refresh token by passing a non-null value as the value of refreshToken request parameter. The - implementation of the `/api/auth/token/create` uses the value of the refreshToken request parameter - instead of generating a new value when the request parameter holds a non-null value. - - Note that if the hash value of the specified refresh token already exists in Authlete's database, - the refresh token cannot be inserted and the `/api/auth/token/create` API will report an error. accessTokenPersistent: type: boolean description: | @@ -17701,70 +18105,6 @@ components: NOTE: A refresh token must be associated with a session ID, which is the ID of the user's authentication session, in order to be used to obtain a [Native SSO](https://openid.net/specs/openid-connect-native-sso-1_0.html)-compliant ID token in the refresh token flow. - token_create_batch_response: - type: object - description: | - Response from a token create batch request. - properties: - resultCode: - type: string - description: The result code of the request. - resultMessage: - type: string - description: The result message of the request. - requestId: - type: string - description: The ID of the issued token batch request. - token_batch_status: - type: object - description: | - Status of a token batch operation. - properties: - batchKind: - type: string - enum: - - CREATE - description: The kind of batch operation. - requestId: - type: string - description: The request ID. - result: - type: string - enum: - - SUCCEEDED - - FAILED - description: The result of the batch operation. - errorCode: - type: string - description: The error code if the operation failed. - errorDescription: - type: string - description: The error description if the operation failed. - tokenCount: - type: integer - format: int64 - description: The number of tokens processed. - createdAt: - type: integer - format: int64 - description: The time at which the batch operation was created (timestamp). - modifiedAt: - type: integer - format: int64 - description: The time at which the batch operation was last modified (timestamp). - token_create_batch_status_response: - type: object - description: | - Response from a token create batch status request. - properties: - resultCode: - type: string - description: The result code of the request. - resultMessage: - type: string - description: The result message of the request. - status: - $ref: '#/components/schemas/token_batch_status' token_update_request: type: object properties: @@ -18433,87 +18773,111 @@ components: type: string description: | The value of the `credential_configuration_ids` array. + x-mint: + metadata: + description: "The value of the `credential_configuration_ids` array." + content: | + + ``` + { + "credential_issuer": "...", + "credential_configuration_ids": [ ... ], + "grants": { ... } + } + ``` - ``` - { - "credential_issuer": "...", - "credential_configuration_ids": [ ... ], - "grants": { ... } - } - ``` + This property is mandatory. + - This property is mandatory. txCode: type: string description: | The transaction code that should be associated with the credential offer. - - If this parameter is not empty and the `preAuthorizedCodeGrantIncluded` parameter is `true`, the - `urn:ietf:params:oauth:grant-type:pre-authorized_code` object will include the `tx_code` object. - - The length of the value of this parameter will be used as the value of the `length` property in - the `tx_code` object. - - ``` - { - "credential_issuer": "...", - "credential_configuration_ids": [ ... ], - "grants": { - "urn:ietf:params:oauth:grant-type:pre-authorized_code": { - "pre-authorized_code": "...", - "tx_code": { - "length": length + x-mint: + metadata: + description: "The transaction code that should be associated with the credential offer." + content: | + + If this parameter is not empty and the `preAuthorizedCodeGrantIncluded` parameter is `true`, the + `urn:ietf:params:oauth:grant-type:pre-authorized_code` object will include the `tx_code` object. + + The length of the value of this parameter will be used as the value of the `length` property in + the `tx_code` object. + + ``` + { + "credential_issuer": "...", + "credential_configuration_ids": [ ... ], + "grants": { + "urn:ietf:params:oauth:grant-type:pre-authorized_code": { + "pre-authorized_code": "...", + "tx_code": { + "length": length + } } } } - } - ``` + ``` + + txCodeInputMode: type: string description: | The input mode of the transaction code. - - The value of this property will be used as the value of the `input_mode` property in the `tx_code` - object. - - ``` - { - "credential_issuer": "...", - "credential_configuration_ids": [ ... ], - "grants": { - "urn:ietf:params:oauth:grant-type:pre-authorized_code": { - "pre-authorized_code": "...", - "tx_code": { - "length": length, - "input_mode": "..." + x-mint: + metadata: + description: "The input mode of the transaction code." + content: | + + The value of this property will be used as the value of the `input_mode` property in the `tx_code` + object. + + ``` + { + "credential_issuer": "...", + "credential_configuration_ids": [ ... ], + "grants": { + "urn:ietf:params:oauth:grant-type:pre-authorized_code": { + "pre-authorized_code": "...", + "tx_code": { + "length": length, + "input_mode": "..." + } } } } - } - ``` + ``` + + txCodeDescription: type: string description: | The description of the transaction code. - - The value of this property will be used as the value of the `description` property in the `tx_code` - object. - - ``` - { - "credential_issuer": "...", - "credential_configuration_ids": [ ... ], - "grants": { - "urn:ietf:params:oauth:grant-type:pre-authorized_code": { - "pre-authorized_code": "...", - "tx_code": { - "length": length, - "description": "..." + x-mint: + metadata: + description: "The description of the transaction code." + content: | + + The value of this property will be used as the value of the `description` property in the `tx_code` + object. + + ``` + { + "credential_issuer": "...", + "credential_configuration_ids": [ ... ], + "grants": { + "urn:ietf:params:oauth:grant-type:pre-authorized_code": { + "pre-authorized_code": "...", + "tx_code": { + "length": length, + "description": "..." + } } } } - } - ``` + ``` + + vci_offer_create_response: type: object properties: @@ -18862,28 +19226,40 @@ components: description: | The type of the `aud` claim of the ID token being issued. Valid values of this parameter are as follows: + x-mint: + metadata: + description: "The type of the `aud` claim of the ID token being issued. Valid values of this parameter are as follows:" + content: | + + - `"array"` + The type of the `aud` claim becomes an array of strings. - - `"array"` - The type of the `aud` claim becomes an array of strings. + - `"string"` + The type of the `aud` claim becomes a single string. - - `"string"` - The type of the `aud` claim becomes a single string. + This parameter is optional, and the default value when omitted is `"array"`. This parameter takes + precedence over the `idTokenAudType` property of `Service`. + - This parameter is optional, and the default value when omitted is `"array"`. This parameter takes - precedence over the `idTokenAudType` property of `Service`. deviceSecret: type: string description: | The device secret. The value of this parameter should be the value of the `deviceSecret` parameter in the response from the `/auth/token` API, if the parameter is present. Otherwise, the authorization server should generate a new device secret and specify it as the value of this parameter. + x-mint: + metadata: + description: "The device secret. The value of this parameter should be the value of the `deviceSecret` parameter in the response from the `/auth/token` API, if the parameter is present. Otherwise, the authorization server should generate a new device secret and specify it as the value of this parameter." + content: | + + The specified device secret is included as the value of the `device_secret` property in the token + response prepared by the `/nativesso` API. + + Additionally, if the `deviceSecretHash` request parameter is omitted, the device secret is used + to compute the value of the `ds_hash` claim. In this case, the `ds_hash` claim will be the + base64url-encoded SHA-256 hash of the device secret. + - The specified device secret is included as the value of the `device_secret` property in the token - response prepared by the `/nativesso` API. - - Additionally, if the `deviceSecretHash` request parameter is omitted, the device secret is used - to compute the value of the `ds_hash` claim. In this case, the `ds_hash` claim will be the - base64url-encoded SHA-256 hash of the device secret. deviceSecretHash: type: string description: |