From 9b1da5f0e3ba5edc7843ea0a971a3566bb358aef Mon Sep 17 00:00:00 2001 From: CI Date: Thu, 5 Mar 2026 10:17:41 +0000 Subject: [PATCH] chore: sync spec_next.yaml from new-api-doc [7bd8d1b1128f2c1d071d552de900f9b033e99318] --- spec_next.yaml | 2030 +++++++++++++++++++----------------------------- 1 file changed, 816 insertions(+), 1214 deletions(-) diff --git a/spec_next.yaml b/spec_next.yaml index 6ad9bb6..dd2d34a 100644 --- a/spec_next.yaml +++ b/spec_next.yaml @@ -2264,21 +2264,15 @@ paths: summary: Get Granted Scopes description: | Get the set of scopes that a user has granted to a client application. - + ### Description 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. - - ## 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. - - ## 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" ]` @@ -2460,7 +2454,7 @@ paths: summary: Delete Granted Scopes description: | Delete the set of scopes that an end-user has granted to a client application. - + ### Description Even if records about granted scopes are deleted by calling this API, existing access tokens are not deleted and scopes of existing access tokens are not changed. The subject parameter is required and must be provided as a query parameter. @@ -2582,7 +2576,7 @@ 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. - + ### Description This API is supposed to be called from within the implementation of the authorization endpoint of the service. The endpoint implementation must extract the request parameters from the authorization request from the client application and pass them as the value of parameters request parameter for @@ -2596,18 +2590,18 @@ paths: ```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) + @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. @@ -2615,205 +2609,158 @@ paths: 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 + **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} + {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 + **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} + {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 - + **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} + Location: {responseContent} Cache-Control: no-store Pragma: no-cache ``` - - ## FORM - + **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 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 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} + {responseContent} ``` - - ## NO_INTERACTION - - When the value of `action` is `NO_INTERACTION`, it means that the request from the client application + **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 + [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** - + [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` + 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** - + (i) Get the time at which the end-user was authenticated. that this value is not managed by Authlete, + meaning that it is expected that the service implementation manages the value. If the service implementation + does not manage authentication time of end-users, call Authlete's `/auth/authorization/fail` API + with `reason=MAX\_AGE\_NOT\_SUPPORTED` and use the API response to generate a response to the client + application. + (ii) Add the value of the maximum authentication age (which is represented in seconds) to the authentication + time. The calculated value is the expiration time. + (iii) Check whether the calculated value is equal to or greater than the current time. If this condition + is satisfied, go to the next step ([SUBJECT]). Otherwise, call Authlete's `/auth/authorization/fail` + API with `reason=EXCEEDS\_MAX\_AGE` and use the API response to generate a response to the client + application. + [3] SUBJECT Get the value of `subject` from the `/auth/authorization` API response. The value represents an end-user who the client application expects to grant authorization. If the value is `null`, go to the next step ([ACRs]). Otherwise, follow the sub steps described below. - - - (i) Compare the value of the requested subject to the current end-user. - - (ii) If they are equal, go to the next step ([ACRs]). If they are not equal, call Authlete's - `/auth/authorization/fail` API with `reason=DIFFERENT_SUBJECT` and use the response from the API - to generate a response to the client application. - - **[4] ACRs** - + (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 + 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 + 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** - + (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 + 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/*` + 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** - + [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 + 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/*` + 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** - + [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 + `/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** - + [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`, + 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. @@ -2829,16 +2776,16 @@ paths: 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 `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 + 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. + 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 @@ -2855,33 +2802,33 @@ paths: 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) + 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 + > 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) + 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) + 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 + 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) @@ -2898,13 +2845,13 @@ paths: 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 + 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 + 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. + 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 @@ -2912,42 +2859,32 @@ paths: 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 - + **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** - + [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). + 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** - + [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** - + [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** - + [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 @@ -2958,81 +2895,70 @@ paths: 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/*` + 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** - + [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** - + [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. + 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** - + [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) + 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** - + [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** - + (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. @@ -3045,9 +2971,9 @@ paths: 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 + 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`. + above in the description for the case of `action=NO\_INTERACTION`. parameters: - in: path name: serviceId @@ -3157,7 +3083,7 @@ paths: description: | This API generates a content of an error authorization response that the authorization server implementation returns to the client application. - + ### Description 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. @@ -3165,19 +3091,14 @@ paths: 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 + **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. ``` @@ -3185,23 +3106,18 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {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 + **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. ``` @@ -3209,39 +3125,29 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {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 - + **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} + Location: {responseContent} Cache-Control: no-store Pragma: no-cache ``` - - ## FORM - + **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`. + 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. ``` @@ -3249,7 +3155,7 @@ paths: Content-Type: text/html;charset=UTF-8 Cache-Control: no-store Pragma: no-cache - {responseContent} + {responseContent} ``` parameters: - in: path @@ -3331,29 +3237,24 @@ 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. - + ### Description 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`. + 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 + **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. ``` @@ -3361,14 +3262,12 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {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 + **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" @@ -3376,9 +3275,6 @@ paths: 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. ``` @@ -3386,40 +3282,30 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {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 - + **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} + Location: {responseContent} Cache-Control: no-store Pragma: no-cache ``` - - ## FORM - + **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`, + 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. ``` @@ -3427,7 +3313,7 @@ paths: Content-Type: text/html;charset=UTF-8 Cache-Control: no-store Pragma: no-cache - {responseContent} + {responseContent} ``` parameters: - in: path @@ -3593,7 +3479,7 @@ 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. - + ### Description 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. @@ -3607,11 +3493,11 @@ paths: the token request and client credentials from Authorization header. ```java @POST - @Consumes(MediaType.APPLICATION_FORM_URLENCODED) + @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); @@ -3623,16 +3509,14 @@ paths: : 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 + **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 @@ -3640,10 +3524,7 @@ paths: 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. - - --- - + 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. ``` @@ -3651,119 +3532,95 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {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. + **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. - - --- - + 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} + {responseContent} ``` - ``` HTTP/1.1 401 Unauthorized - WWW-Authenticate: {challenge} + WWW-Authenticate: {challenge} Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {responseContent} ``` - - ## BAD_REQUEST - - When the value of `action` is `BAD_REQUEST`, it means that the request from the client application + **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} + {responseContent} ``` - - ## PASSWORD - + **PASSWORD** When the value of `"action"` is `"PASSWORD"`, it means that - the request from the client application is valid and `grant_type` + 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 + 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 + 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 + 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) + 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 + 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()} + 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 + 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 - + **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. - - --- - + 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. ``` @@ -3771,46 +3628,43 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {responseContent} ``` - - ## TOKEN_EXCHANGE (Authlete 2.3 onwards) - - When the value of `"action"` is `"TOKEN_EXCHANGE"`, it means + **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 + 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 + 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 + 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 + 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 + `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` + 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 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 + the token exchange request when the {@link Service#isTokenExchangeEncryptedJwtRejected() - tokenExchangeEncryptedJwtRejected} flag of the service is `true` + 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" }. + { @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 @@ -3818,16 +3672,16 @@ paths: 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 + the token exchange request when the {@link Service#isTokenExchangeUnsignedJwtRejected() - tokenExchangeUnsignedJwtRejected} flag of the service is `true` + 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`\* + \*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 @@ -3835,7 +3689,7 @@ paths: `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`\* + \*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 @@ -3843,12 +3697,12 @@ paths: `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`\* + \*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 + reject the token exchange request when the {@link Service#isTokenExchangeEncryptedJwtRejected() - tokenExchangeEncryptedJwtRejected} flag of the service is `true` + 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 @@ -3856,7 +3710,7 @@ paths: 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"`. + `"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 @@ -3871,15 +3725,15 @@ paths: 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 + reject the token exchange request when the {@link Service#isTokenExchangeUnsignedJwtRejected() - tokenExchangeUnsignedJwtRejected} flag of the service is `true` + 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`. + `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 @@ -3896,36 +3750,34 @@ paths: 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 + 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} + WWW-Authenticate: {challenge} Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {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()})" - } + { + "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 + **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)) @@ -3935,8 +3787,8 @@ paths: 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) + 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 @@ -3947,8 +3799,8 @@ paths: 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()}) + 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. @@ -3957,8 +3809,8 @@ paths: 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) + 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 @@ -3970,12 +3822,12 @@ paths: 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()})" - } + { + "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 @@ -4084,7 +3936,7 @@ paths: description: | This API generates a content of an error token response that the authorization server implementation returns to the client application. - + ### Description 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 @@ -4093,19 +3945,14 @@ paths: 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 + **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. ``` @@ -4113,22 +3960,17 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {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 + **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. ``` @@ -4136,7 +3978,7 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {responseContent} ``` parameters: - in: path @@ -4215,7 +4057,7 @@ paths: description: | This API generates a content of a successful token response that the authorization server implementation returns to the client application. - + ### Description 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 @@ -4224,19 +4066,14 @@ paths: 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 + **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. ``` @@ -4244,22 +4081,17 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {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 - + **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. ``` @@ -4267,7 +4099,7 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {responseContent} ``` parameters: - in: path @@ -4363,7 +4195,7 @@ paths: summary: Process Introspection Request description: | This API gathers information about an access token. - + ### Description 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. @@ -4376,10 +4208,8 @@ paths: 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 + **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 @@ -4398,12 +4228,10 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {responseContent} ``` - - ## BAD_REQUEST - - When the value of `action` is `BAD_REQUEST`, it means that the request from the client application + **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 @@ -4417,13 +4245,11 @@ paths: The following is an example response which complies with RFC 6750. ``` HTTP/1.1 400 Bad Request - WWW-Authenticate: {responseContent} + WWW-Authenticate: {responseContent} Cache-Control: no-store Pragma: no-cache ``` - - ## UNAUTHORIZED - + **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 @@ -4435,13 +4261,11 @@ paths: The following is an example response which complies with RFC 6750. ``` HTTP/1.1 401 Unauthorized - WWW-Authenticate: {responseContent} + WWW-Authenticate: {responseContent} Cache-Control: no-store Pragma: no-cache ``` - - ## FORBIDDEN - + **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. @@ -4456,18 +4280,16 @@ paths: The following is an example response which complies with RFC 6750. ``` HTTP/1.1 403 Forbidden - WWW-Authenticate: {responseContent} + WWW-Authenticate: {responseContent} Cache-Control: no-store Pragma: no-cache ``` - - ## OK - + **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 + 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 @@ -4476,7 +4298,7 @@ paths: The following is an example error response which complies with RFC 6750. ``` HTTP/1.1 400 Bad Request - WWW-Authenticate: {responseContent} + WWW-Authenticate: {responseContent} Cache-Control: no-store Pragma: no-cache ``` @@ -4486,7 +4308,7 @@ paths: 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**_ + \_**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 @@ -4598,7 +4420,7 @@ 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). - + ### Description 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. @@ -4611,10 +4433,8 @@ paths: 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 + **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 @@ -4622,20 +4442,15 @@ paths: 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} + {responseContent} ``` - - ## BAD_REQUEST - - When the value of `action` is `BAD_REQUEST`, it means that the request from the client application + **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. @@ -4648,28 +4463,23 @@ paths: ``` HTTP/1.1 400 Bad Request Content-Type: application/json - {responseContent} + {responseContent} ``` - - ## OK - + **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. - - --- - + 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} + {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 + 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. @@ -4746,7 +4556,7 @@ paths: summary: Process Revocation Request description: | This API revokes access tokens and refresh tokens. - + ### Description 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. @@ -4754,19 +4564,14 @@ paths: 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 + **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. ``` @@ -4774,55 +4579,41 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {responseContent} ``` - - ## INVALID_CLIENT - - When the value of `action` is `INVALID_CLIENT`, it means that authentication of the client failed. + **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 + 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 + `invalid\_client` + > 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} + {responseContent} ``` - ``` HTTP/1.1 401 Unauthorized - WWW-Authenticate: {challenge} + WWW-Authenticate: {challenge} Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {responseContent} ``` - - ## BAD_REQUEST - - When the value of `action` is `BAD_REQUEST`, it means that the request from the client application + **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), @@ -4831,22 +4622,16 @@ paths: 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} + {responseContent} ``` - - ## OK - + **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. @@ -4862,7 +4647,7 @@ paths: Content-Type: application/javascript Cache-Control: no-store Pragma: no-cache - {responseContent} + {responseContent} ``` parameters: - in: path @@ -4938,18 +4723,16 @@ paths: summary: Process UserInfo Request description: | This API gathers information about a user. - - 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) + ### Description + 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 + **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 @@ -4959,17 +4742,15 @@ paths: 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. + Response](https://openid.net/specs/openid-connect-core-1\_0.html#UserInfoError) for details. ``` HTTP/1.1 500 Internal Server Error - WWW-Authenticate: {responseContent} + 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 + **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 @@ -4978,16 +4759,14 @@ paths: 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. + Response](https://openid.net/specs/openid-connect-core-1\_0.html#UserInfoError) for details. ``` HTTP/1.1 400 Bad Request - WWW-Authenticate: {responseContent} + WWW-Authenticate: {responseContent} Cache-Control: no-store Pragma: no-cache ``` - - ## UNAUTHORIZED - + **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 @@ -4996,16 +4775,14 @@ paths: 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. + Response](https://openid.net/specs/openid-connect-core-1\_0.html#UserInfoError) for details. ``` HTTP/1.1 401 Unauthorized - WWW-Authenticate: {responseContent} + WWW-Authenticate: {responseContent} Cache-Control: no-store Pragma: no-cache ``` - - ## FORBIDDEN - + **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) @@ -5013,16 +4790,14 @@ paths: 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. + Response](https://openid.net/specs/openid-connect-core-1\_0.html#UserInfoError) for details. ``` HTTP/1.1 403 Forbidden - WWW-Authenticate: {responseContent} + WWW-Authenticate: {responseContent} Cache-Control: no-store Pragma: no-cache ``` - - ## OK - + **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). @@ -5030,7 +4805,7 @@ paths: (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 + 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. @@ -5040,8 +4815,8 @@ paths: 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." + 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 ``` @@ -5049,8 +4824,8 @@ paths: 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." + 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 ``` @@ -5132,8 +4907,8 @@ paths: summary: Issue UserInfo Response description: | This API generates an ID token. - - 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) + ### Description + 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 @@ -5142,10 +4917,8 @@ paths: 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 + **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 @@ -5156,17 +4929,15 @@ paths: 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. + Response](https://openid.net/specs/openid-connect-core-1\_0.html#UserInfoError) for details. ``` HTTP/1.1 500 Internal Server Error - WWW-Authenticate: {responseContent} + 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 + **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 @@ -5175,16 +4946,14 @@ paths: 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. + Response](https://openid.net/specs/openid-connect-core-1\_0.html#UserInfoError) for details. ``` HTTP/1.1 400 Bad Request - WWW-Authenticate: {responseContent} + WWW-Authenticate: {responseContent} Cache-Control: no-store Pragma: no-cache ``` - - ## UNAUTHORIZED - + **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 @@ -5193,16 +4962,14 @@ paths: 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. + Response](https://openid.net/specs/openid-connect-core-1\_0.html#UserInfoError) for details. ``` HTTP/1.1 401 Unauthorized - WWW-Authenticate: {responseContent} + WWW-Authenticate: {responseContent} Cache-Control: no-store Pragma: no-cache ``` - - ## FORBIDDEN - + **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 @@ -5211,16 +4978,14 @@ paths: 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. + Response](https://openid.net/specs/openid-connect-core-1\_0.html#UserInfoError) for details. ``` HTTP/1.1 403 Forbidden - WWW-Authenticate: {responseContent} + WWW-Authenticate: {responseContent} Cache-Control: no-store Pragma: no-cache ``` - - ## JSON - + **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. @@ -5233,11 +4998,9 @@ paths: Cache-Control: no-store Pragma: no-cache Content-Type: application/json;charset=UTF-8 - {responseContent} + {responseContent} ``` - - ## JWT - + **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)). @@ -5251,7 +5014,7 @@ paths: Cache-Control: no-store Pragma: no-cache Content-Type: application/jwt - {responseContent} + {responseContent} ``` parameters: - in: path @@ -5408,12 +5171,12 @@ paths: description: | This API gathers JWK Set information for a service so that its client applications can verify signatures by the service and encrypt their requests to the service. - + ### Description This API is supposed to be called from within the implementation of the jwk set endpoint of the service where the service that supports OpenID Connect must expose its JWK Set information so that client applications can verify signatures by the service and encrypt their requests to the service. - The URI of the endpoint can be found as the value of `jwks_uri` in [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) - if the service supports [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html). + The URI of the endpoint can be found as the value of `jwks\_uri` in [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1\_0.html#ProviderMetadata) + if the service supports [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1\_0.html). parameters: - in: path name: serviceId @@ -5507,11 +5270,11 @@ paths: summary: Get Service Configuration description: | This API gathers configuration information about a service. - + ### Description This API is supposed to be called from within the implementation of the configuration endpoint of - the service where the service that supports OpenID Connect and [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) + the service where the service that supports OpenID Connect and [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1\_0.html) must expose its configuration information in a JSON format. Details about the format are described - in "[3. OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata)" + in "[3. OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1\_0.html#ProviderMetadata)" in OpenID Connect Discovery 1.0. parameters: - in: path @@ -5858,23 +5621,18 @@ 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). - + ### Description 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 + **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. ``` @@ -5882,21 +5640,16 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {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 + **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. ``` @@ -5904,19 +5657,14 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {responseContent} ``` - - ## CREATED - + **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. ``` @@ -5924,7 +5672,7 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {responseContent} ``` parameters: - in: path @@ -6026,23 +5774,18 @@ 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). - + ### Description 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 + **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. ``` @@ -6050,22 +5793,17 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {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 + **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. ``` @@ -6073,11 +5811,9 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {responseContent} ``` - - ## UNAUTHORIZED - + **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. @@ -6085,9 +5821,6 @@ paths: 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. ``` @@ -6095,20 +5828,15 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {responseContent} ``` NOTE: The `UNAUTHORIZED` value was added in October, 2021. See the description of `Service.unauthorizedOnClientConfigSupported` for details. - - ## OK - + **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. ``` @@ -6116,7 +5844,7 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {responseContent} ``` parameters: - in: path @@ -6222,23 +5950,18 @@ 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). - + ### Description 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 + **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. ``` @@ -6246,21 +5969,16 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {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 + **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. ``` @@ -6268,11 +5986,9 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {responseContent} ``` - - ## UNAUTHORIZED - + **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. @@ -6280,9 +5996,6 @@ paths: 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. ``` @@ -6290,21 +6003,16 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {responseContent} ``` NOTE: The `UNAUTHORIZED` value was added in October, 2021. See the description of `Service.unauthorizedOnClientConfigSupported` for details. - - ## UPDATED - + **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. ``` @@ -6312,7 +6020,7 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {responseContent} ``` parameters: - in: path @@ -6422,23 +6130,18 @@ 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). - + ### Description 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 + **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. ``` @@ -6446,21 +6149,16 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {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 + **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. ``` @@ -6468,11 +6166,9 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {responseContent} ``` - - ## UNAUTHORIZED - + **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. @@ -6480,9 +6176,6 @@ paths: 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. ``` @@ -6490,20 +6183,15 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {responseContent} ``` NOTE: The `UNAUTHORIZED` value was added in October, 2021. See the description of `Service.unauthorizedOnClientConfigSupported` for details. - - ## DELETED - + **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. ``` @@ -6587,12 +6275,12 @@ paths: post: summary: Process Backchannel Authentication Request 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) + 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. - + ### Description 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) + 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. @@ -6602,12 +6290,12 @@ paths: the backchannel authentication request. ```java @POST - @Consumes(MediaType.APPLICATION_FORM_URLENCODED) + @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. @@ -6615,19 +6303,14 @@ paths: 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 + **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. ``` @@ -6635,20 +6318,15 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {responseContent} ``` - - ## BAD_REQUEST - - When the value of `action` is `BAD_REQUEST`, it means that the request from the client application + **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. ``` @@ -6656,11 +6334,9 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {responseContent} ``` - - ## UNAUTHORIZED - + **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 @@ -6669,9 +6345,6 @@ paths: "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. ``` @@ -6680,178 +6353,162 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {responseContent} ``` - - ## USER_IDENTIFICATION - - When the value of `action` is `USER_IDENTIFICATION`, it means that the backchannel authentication + **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** - + [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** - + 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` + 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` + 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` + - `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 + 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` + 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` + - `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` + 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 + 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` + - `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 + 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` + - `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 + 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` + - `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 + 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` + 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` + 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** - + [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` + 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`). + 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` + - `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` + - `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** - + [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** - + 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** - + 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. + 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 @@ -6948,25 +6605,25 @@ paths: post: summary: Issue Backchannel Authentication Response 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) - + 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) + ### Description 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`. + 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) + @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. @@ -6974,19 +6631,14 @@ paths: 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 + **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. ``` @@ -6994,22 +6646,18 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {responseContent} ``` - - ## INVALID_TICKET - - When the value of `action` is `INVALID_TICKET`, it means that the ticket included in the API call + **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 - + 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 + 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 @@ -7019,7 +6667,7 @@ paths: Content-Type: text/html;charset=UTF-8 Cache-Control: no-store Pragma: no-cache - {responseContent} + {responseContent} ``` parameters: - in: path @@ -7097,33 +6745,27 @@ paths: summary: Fail Backchannel Authentication Request 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). - + 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). + ### Description 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) + 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 - - 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 + **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. - - ## BAD_REQUEST - - When the value of `action` is `BAD_REQUEST`, the authorization server implementation should return a + **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. - - ## 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 + 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 @@ -7200,9 +6842,9 @@ 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. - + ### Description 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 + `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 @@ -7218,56 +6860,50 @@ paths: 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 + 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` + 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`. + 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` + `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\_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 + 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 + 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 + **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 + `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 - + **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` + 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`, + 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. + 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 @@ -7279,11 +6915,11 @@ paths: 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} + POST {clientNotificationEndpoint} HTTP/1.1 + HOST: {The host of clientNotificationEndpoint} + Authorization: Bearer {notificationToken} Content-Type: application/json - {responseContent} + {responseContent} ``` parameters: - in: path @@ -7378,23 +7014,18 @@ 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. - + ### Description 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 + **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. ``` @@ -7402,20 +7033,15 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {responseContent} ``` - - ## BAD_REQUEST - - When the value of `action` is `BAD_REQUEST`, it means that the request from the client application + **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. ``` @@ -7423,20 +7049,15 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {responseContent} ``` - - ## UNAUTHORIZED - + **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. ``` @@ -7445,19 +7066,14 @@ paths: Content-Type: application/json Cache-Control: no-store Pragma: no-cache - {responseContent} + {responseContent} ``` - - ## OK - + **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: @@ -7561,7 +7177,7 @@ paths: summary: Process Device Verification Request description: | The API returns information associated with a user code. - + ### Description 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 @@ -7571,27 +7187,19 @@ paths: 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 - - When the value of `action` is `SERVER_ERROR`, it means that an error occurred on Authlete side. The + **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. - - ## NOT_EXIST - - When the value of `action` is `NOT_EXIST`, it means that the user code does not exist. The authorization + **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. - - ## 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. - - ## 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. @@ -7681,7 +7289,7 @@ 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. - + ### Description 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 @@ -7697,43 +7305,33 @@ paths: 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` + `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. + 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`. + 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 + **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 + **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 + **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, + **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 - + **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. @@ -8295,9 +7893,14 @@ paths: schema: $ref: '#/components/schemas/token_revoke_response' example: - resultCode: A312001 - resultMessage: Revoked 1 access token(s). - count: 1 + resultCode: A135001 + resultMessage: '[A135001] Updated the access token successfully.' + accessToken: Z5a40U6dWvw2gMoCOAFbZcM85q4HC0Z--0YKD9-Nf6Q + accessTokenExpiresAt: 1642048149000 + action: OK + scopes: + - history.read + tokenType: Bearer '400': $ref: '#/components/responses/400' '401': @@ -8316,26 +7919,28 @@ paths: curl -v -X POST https://us.authlete.com/api/21653835348762/auth/token/revoke \ -H 'Content-Type:application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ - -d '{ "accessTokenIdentifier": "Z5a40U6dWvw2gMoCOAFbZcM85q4HC0Z--0YKD9-Nf6Q" }' + -d '{ "accessToken": "Z5a40U6dWvw2gMoCOAFbZcM85q4HC0Z--0YKD9-Nf6Q", "scopes": [ "history.read" ] }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); - TokenRevokeRequest req = new TokenRevokeRequest(); - req.setAccessTokenIdentifier("Z5a40U6dWvw2gMoCOAFbZcM85q4HC0Z--0YKD9-Nf6Q"); + TokenUpdateRequest req = new TokenUpdateRequest(); + req.setAccessToken("JDGiiM9PuWT63FIwGjG9eYlGi-aZMq6CQ2IB475JUxs"); + req.setScopes({ "history.read" }); - api.tokenRevoke(req); + api.tokenUpdate(req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) - req = TokenRevokeRequest() - req.access_token_identifier = 'Z5a40U6dWvw2gMoCOAFbZcM85q4HC0Z--0YKD9-Nf6Q' + req = TokenUpdateRequest() + req.accessToken = 'JDGiiM9PuWT63FIwGjG9eYlGi-aZMq6CQ2IB475JUxs' + req.scopes = [ 'history.read' ] - api.token_revoke(req) + api.tokenUpdate(req) tags: - Token Operations /api/{serviceId}/jose/verify: @@ -8436,7 +8041,6 @@ paths: retrieve the value of the `action` response parameter from the API response and take the following steps according to the value. - ### `OK` When the value of the `action` response parameter is `OK`, it means that Authlete @@ -8456,7 +8060,6 @@ paths: (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 @@ -8478,7 +8081,6 @@ paths: (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 @@ -9479,7 +9081,7 @@ paths: implementation should retrieve the value of `action` from the response and take the following steps according to the value. - ## 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 @@ -9495,7 +9097,7 @@ paths: (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 @@ -9515,7 +9117,7 @@ paths: 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 @@ -9604,15 +9206,15 @@ paths: 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. - ## SERVER_ERROR + **SERVER_ERROR** 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`. @@ -10115,7 +9717,7 @@ components: 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 + **Requirements by Authlete** - Must consist of printable ASCII letters only. - Must not exceed 200 letters. @@ -10501,13 +10103,13 @@ components: description: | The digest algorithm that this client requests the server to use when it computes digest values of [external attachments](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#name-external-attachments), which may be referenced from within ID tokens - or userinfo responses (or any place that can have the `verified_claims` claim). + or userinfo responses (or any place that can have the `verified\_claims` claim). Possible values are listed in the [Hash Algorithm Registry](https://www.iana.org/assignments/named-information/named-information.xhtml#hash-alg) of IANA (Internet Assigned Numbers Authority), but the server does not necessarily support all the values there. When this property is omitted, `sha-256` is used as the default algorithm. - This property corresponds to the `digest_algorithm` client metadata + This property corresponds to the `digest\_algorithm` client metadata which was defined by the third implementer's draft of - [OpenID Connect for Identity Assurance 1.0](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html). + [OpenID Connect for Identity Assurance 1.0](https://openid.net/specs/openid-connect-4-identity-assurance-1\_0.html). singleAccessTokenPerSubject: type: boolean description: | @@ -11294,14 +10896,14 @@ components: The aliases will be embedded in the response from the discovery endpoint like the following. ```json - { + { ......, - "mtls_endpoint_aliases": { + "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 @@ -11599,7 +11201,7 @@ components: description: | The URI of the registration management endpoint. If dynamic client registration is supported, and this is set, this URI will be used as the basis of the client's management endpoint by appending - `/clientid}/` to it as a path element. If this is unset, the value of `registrationEndpoint` will + `/clientid}/` to it as a path element. If this is unset, the value of `registrationEndpoint` will be used as the URI base instead. format: uri policyUri: @@ -11697,7 +11299,7 @@ components: 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. @@ -12031,7 +11633,7 @@ components: [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 + > 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 @@ -12136,8 +11738,8 @@ components: items: $ref: '#/components/schemas/attachment_type' description: | - Supported attachment types. This property corresponds to the {@code - attachments_supported} server metadata which was added by the third + Supported attachment types. This property corresponds to the {@code + attachments_supported} server metadata which was added by the third implementer's draft of OpenID Connect for Identity Assurance 1.0. supportedDigestAlgorithms: type: array @@ -12175,7 +11777,7 @@ components: type: string description: | Document validation methods supported by this service. This property - corresponds to the `documents_validation_methods_supported` server + corresponds to the `documents\_validation\_methods\_supported` server metadata which was added by the third implementer's draft of supportedDocumentsVerificationMethods: type: array @@ -12604,11 +12206,11 @@ components: The value of the `credential_configuration_ids` property of the credential offer. ``` - { + { "credential_issuer": "...", "credential_configuration_ids": [ ... ], - "grants": { ... } - } + "grants": { ... } + } ``` txCode: type: string @@ -13556,18 +13158,18 @@ components: OpenID Connect defines some scope names which need to be treated specially. The table below lists the special scope names. | Name | Description | | --- | --- | - | `openid` | This scope must be contained in `scope` request parameter to promote an OAuth 2.0 authorization request to an OpenID Connect request. It is described in "[OpenID Connect Core 1.0, 3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest), scope". | - | `profile` | This scope is used to request some claims to be embedded in the ID token. The claims are `name`, `family_name`, `given_name`, `middle_name`, `nickname`, `preferred_username`, `profile`, `picture`, `website`, `gender`, `birthdate`, `zoneinfo`, `locale`, and `updated_at`. It is described in [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims). | - | `email` | This scope is used to request some claims to be embedded in the ID token. The claims are `email` and `email_verified`. It is described in [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims). | - | `address` | This scope is used to request `address` claim to be embedded in the ID token. It is described in [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims). - The format of `address` claim is not a simple string. It is described in [OpenID Connect Core 1.0, 5.1.1. Address Claim](https://openid.net/specs/openid-connect-core-1_0.html#AddressClaim). | - | `phone` | This scope is used to request some claims to be embedded in the ID token. The claims are `phone_number` and `phone_number_verified`. It is described in [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims). | - | `offline_access` | The following is an excerpt about this scope from [OpenID Connect Core 1.0, 11. Offline Access](https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess). + | `openid` | This scope must be contained in `scope` request parameter to promote an OAuth 2.0 authorization request to an OpenID Connect request. It is described in "[OpenID Connect Core 1.0, 3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1\_0.html#AuthRequest), scope". | + | `profile` | This scope is used to request some claims to be embedded in the ID token. The claims are `name`, `family\_name`, `given\_name`, `middle\_name`, `nickname`, `preferred\_username`, `profile`, `picture`, `website`, `gender`, `birthdate`, `zoneinfo`, `locale`, and `updated\_at`. It is described in [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1\_0.html#ScopeClaims). | + | `email` | This scope is used to request some claims to be embedded in the ID token. The claims are `email` and `email\_verified`. It is described in [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1\_0.html#ScopeClaims). | + | `address` | This scope is used to request `address` claim to be embedded in the ID token. It is described in [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1\_0.html#ScopeClaims). + The format of `address` claim is not a simple string. It is described in [OpenID Connect Core 1.0, 5.1.1. Address Claim](https://openid.net/specs/openid-connect-core-1\_0.html#AddressClaim). | + | `phone` | This scope is used to request some claims to be embedded in the ID token. The claims are `phone\_number` and `phone\_number\_verified`. It is described in [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1\_0.html#ScopeClaims). | + | `offline\_access` | The following is an excerpt about this scope from [OpenID Connect Core 1.0, 11. Offline Access](https://openid.net/specs/openid-connect-core-1\_0.html#OfflineAccess). > This scope value requests that an OAuth 2.0 Refresh Token be issued that can be used to obtain an Access Token that grants access to the end-user's userinfo endpoint even when the end-user is not present (not logged in). | - Note that, if `response_type` request parameter does not contain code, `offline_acccess` scope is removed from this list even - when scope request parameter contains `offline_access`. This behavior is a requirement written in - [OpenID Connect Core 1.0, 11. Offline Access](https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess). + Note that, if `response\_type` request parameter does not contain code, `offline\_acccess` scope is removed from this list even + when scope request parameter contains `offline\_access`. This behavior is a requirement written in + [OpenID Connect Core 1.0, 11. Offline Access](https://openid.net/specs/openid-connect-core-1\_0.html#OfflineAccess). uiLocales: type: array items: @@ -13660,32 +13262,32 @@ components: You can find `userinfo` and `id_token` are top-level properties. ```json - { + { "userinfo": - { - "given_name": { "essential": true }, + { + "given_name": { "essential": true }, "nickname": null, - "email": { "essential": true }, - "email_verified": { "essential": true }, + "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" ] } - } - } + { + "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" ] } - } + { + "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, @@ -13703,36 +13305,36 @@ components: 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 }, + { + "given_name": { "essential": true }, "nickname": null, - "email": { "essential": true }, - "email_verified": { "essential": true }, + "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" ] } - } - } + { + "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 }, + { + "given_name": { "essential": true }, "nickname": null, - "email": { "essential": true }, - "email_verified": { "essential": true }, + "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, @@ -13787,15 +13389,15 @@ components: type: string description: | The subject identifying the user who has given the grant identified - by the `grant_id` request parameter of the device authorization + by the `grant\_id` request parameter of the device authorization request. Authlete 2.3 and newer versions support [Grant Management - for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html). An authorization request may contain a `grant_id` + for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html). An authorization request may contain a `grant\_id` request parameter which is defined in the specification. If the value of - the request parameter is valid, {@link #getGrantSubject()} will return + the request parameter is valid, {@link #getGrantSubject()} will return the subject of the user who has given the grant to the client application. Authorization server implementations may use the value returned from - {@link #getGrantSubject()} in order to determine the user to authenticate. + {@link #getGrantSubject()} in order to determine the user to authenticate. The user your system will authenticate during the authorization process (or has already authenticated) may be different from the user of the grant. The first implementer's draft of "Grant Management for OAuth 2.0" @@ -13813,42 +13415,42 @@ components: A client application can request *"transformed claims"* by adding names of transformed claims in the `claims` request parameter. The following is an example of the `claims` request parameter - that requests a predefined transformed claim named `18_or_over` - and a transformed claim named `nationality_usa` to be embedded + that requests a predefined transformed claim named `18\_or\_over` + and a transformed claim named `nationality\_usa` to be embedded in the response from the userinfo endpoint. ```json - { - "transformed_claims": { - "nationality_usa": { + { + "transformed\_claims": { + "nationality\_usa": { "claim": "nationalities", "fn": [ [ "eq", "USA" ], "any" ] - } - }, - "userinfo": { - "::18_or_over": null, - ":nationality_usa": null - } - } + } + }, + "userinfo": { + "::18\_or\_over": null, + ":nationality\_usa": null + } + } ``` - The example above assumes that a transformed claim named `18_or_over` + The example above assumes that a transformed claim named `18\_or\_over` is predefined by the authorization server like below. ```json - { - "18_or_over": { + { + "18\_or\_over": { "claim": "birthdate", "fn": [ - "years_ago", + "years\_ago", [ "gte", 18 ] ] - } - } + } + } ``` In the example, the `nationalities` claim is requested indirectly - by the `nationality_usa` transformed claim. Likewise, the - `birthdate` claim is requested indirectly by the `18_or_over` + by the `nationality\_usa` transformed claim. Likewise, the + `birthdate` claim is requested indirectly by the `18\_or\_over` transformed claim. When the `claims` request parameter of an authorization request is like the example above, this `requestedClaimsForTx` property will @@ -13861,10 +13463,10 @@ components: request parameter when it calls the `/api/auth/userinfo/issue` API. The following is an example of the value of the `claimsForTx` request parameter. ```json - { + { "birthdate": "1970-01-23", "nationalities": [ "DEU", "USA" ] - } + } ``` requestedVerifiedClaimsForTx: type: array @@ -14101,7 +13703,7 @@ components: ``` [ - "{\"birthdate\":\"1970-01-23\",\"nationalities\":[\"DEU\",\"USA\"]}" + "{\"birthdate\":\"1970-01-23\",\"nationalities\":[\"DEU\",\"USA\"]}" ] ``` @@ -14109,29 +13711,29 @@ components: property in the claims request parameter of an authorization request can be an array like below. ``` - { - "transformed_claims": { - "nationality_usa": { + { + "transformed_claims": { + "nationality_usa": { "claim": "nationalities", "fn": [ [ "eq", "USA" ], "any" ] - } - }, - "id_token": { + } + }, + "id_token": { "verified_claims": [ - { - "verification": { "trust_framework": { "value": "gold" } }, - "claims": { "::18_or_above": null } - }, - { - "verification": { "trust_framework": { "value": "silver" } }, - "claims": { ":nationality_usa": null } - } + { + "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 @@ -14141,8 +13743,8 @@ components: ``` [ - "{\"birthdate\":\"1970-01-23\"}", - "{\"nationalities\":[\"DEU\",\"USA\"]}" + "{\"birthdate\":\"1970-01-23\"}", + "{\"nationalities\":[\"DEU\",\"USA\"]}" ] ``` authorization_ticket_info: @@ -15705,36 +15307,36 @@ components: 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 }, + { + "given_name": { "essential": true }, "nickname": null, - "email": { "essential": true }, - "email_verified": { "essential": true }, + "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" ] } - } - } + { + "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 }, + { + "given_name": { "essential": true }, "nickname": null, - "email": { "essential": true }, - "email_verified": { "essential": true }, + "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, @@ -15768,42 +15370,42 @@ components: A client application can request *"transformed claims"* by adding names of transformed claims in the `claims` request parameter. The following is an example of the `claims` request parameter - that requests a predefined transformed claim named `18_or_over` - and a transformed claim named `nationality_usa` to be embedded + that requests a predefined transformed claim named `18\_or\_over` + and a transformed claim named `nationality\_usa` to be embedded in the response from the userinfo endpoint. ```json - { - "transformed_claims": { - "nationality_usa": { + { + "transformed\_claims": { + "nationality\_usa": { "claim": "nationalities", "fn": [ [ "eq", "USA" ], "any" ] - } - }, - "userinfo": { - "::18_or_over": null, - ":nationality_usa": null - } - } + } + }, + "userinfo": { + "::18\_or\_over": null, + ":nationality\_usa": null + } + } ``` - The example above assumes that a transformed claim named `18_or_over` + The example above assumes that a transformed claim named `18\_or\_over` is predefined by the authorization server like below. ```json - { - "18_or_over": { + { + "18\_or\_over": { "claim": "birthdate", "fn": [ - "years_ago", + "years\_ago", [ "gte", 18 ] ] - } - } + } + } ``` In the example, the `nationalities` claim is requested indirectly - by the `nationality_usa` transformed claim. Likewise, the - `birthdate` claim is requested indirectly by the `18_or_over` + by the `nationality\_usa` transformed claim. Likewise, the + `birthdate` claim is requested indirectly by the `18\_or\_over` transformed claim. When the `claims` request parameter of an authorization request is like the example above, this `requestedClaimsForTx` property will @@ -15816,10 +15418,10 @@ components: request parameter when it calls the `/api/auth/userinfo/issue` API. The following is an example of the value of the `claimsForTx` request parameter. ```json - { + { "birthdate": "1970-01-23", "nationalities": [ "DEU", "USA" ] - } + } ``` requestedVerifiedClaimsForTx: type: array @@ -15917,7 +15519,7 @@ components: ``` [ - "{\"birthdate\":\"1970-01-23\",\"nationalities\":[\"DEU\",\"USA\"]}" + "{\"birthdate\":\"1970-01-23\",\"nationalities\":[\"DEU\",\"USA\"]}" ] ``` @@ -15925,29 +15527,29 @@ components: property in the claims request parameter of an authorization request can be an array like below. ``` - { - "transformed_claims": { - "nationality_usa": { + { + "transformed_claims": { + "nationality_usa": { "claim": "nationalities", "fn": [ [ "eq", "USA" ], "any" ] - } - }, - "userinfo": { + } + }, + "userinfo": { "verified_claims": [ - { - "verification": { "trust_framework": { "value": "gold" } }, - "claims": { "::18_or_above": null } - }, - { - "verification": { "trust_framework": { "value": "silver" } }, - "claims": { ":nationality_usa": null } - } + { + "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 @@ -15957,8 +15559,8 @@ components: ``` [ - "{\"birthdate\":\"1970-01-23\"}", - "{\"nationalities\":[\"DEU\",\"USA\"]}" + "{\"birthdate\":\"1970-01-23\"}", + "{\"nationalities\":[\"DEU\",\"USA\"]}" ] ``` userinfo_issue_response: @@ -16049,7 +15651,7 @@ components: This parameter is optional, and the default value on omission is "`array`". This parameter takes precedence over the `idTokenAudType` property - of {@link Service} (cf. {@link Service#getIdTokenAudType()}). + of {@link Service} (cf. {@link Service#getIdTokenAudType()}). idtoken_reissue_response: type: object properties: @@ -16459,15 +16061,15 @@ components: type: string description: | The subject identifying the user who has given the grant identified - by the `grant_id` request parameter of the device authorization + by the `grant\_id` request parameter of the device authorization request. Authlete 2.3 and newer versions support [Grant Management - for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html). An authorization request may contain a `grant_id` + for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html). An authorization request may contain a `grant\_id` request parameter which is defined in the specification. If the value of - the request parameter is valid, {@link #getGrantSubject()} will return + the request parameter is valid, {@link #getGrantSubject()} will return the subject of the user who has given the grant to the client application. Authorization server implementations may use the value returned from - {@link #getGrantSubject()} in order to determine the user to authenticate. + {@link #getGrantSubject()} in order to determine the user to authenticate. The user your system will authenticate during the authorization process (or has already authenticated) may be different from the user of the grant. The first implementer's draft of "Grant Management for OAuth 2.0" @@ -17082,15 +16684,15 @@ components: type: string description: | The subject identifying the user who has given the grant identified - by the `grant_id` request parameter of the device authorization + by the `grant\_id` request parameter of the device authorization request. Authlete 2.3 and newer versions support [Grant Management - for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html). An authorization request may contain a `grant_id` + for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html). An authorization request may contain a `grant\_id` request parameter which is defined in the specification. If the value of - the request parameter is valid, {@link #getGrantSubject()} will return + the request parameter is valid, {@link #getGrantSubject()} will return the subject of the user who has given the grant to the client application. Authorization server implementations may use the value returned from - {@link #getGrantSubject()} in order to determine the user to authenticate. + {@link #getGrantSubject()} in order to determine the user to authenticate. The user your system will authenticate during the authorization process (or has already authenticated) may be different from the user of the grant. The first implementer's draft of "Grant Management for OAuth 2.0" @@ -17241,15 +16843,15 @@ components: type: string description: | The subject identifying the user who has given the grant identified - by the `grant_id` request parameter of the device authorization + by the `grant\_id` request parameter of the device authorization request. Authlete 2.3 and newer versions support [Grant Management - for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html). An authorization request may contain a `grant_id` + for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html). An authorization request may contain a `grant\_id` request parameter which is defined in the specification. If the value of - the request parameter is valid, {@link #getGrantSubject()} will return + the request parameter is valid, {@link #getGrantSubject()} will return the subject of the user who has given the grant to the client application. Authorization server implementations may use the value returned from - {@link #getGrantSubject()} in order to determine the user to authenticate. + {@link #getGrantSubject()} in order to determine the user to authenticate. The user your system will authenticate during the authorization process (or has already authenticated) may be different from the user of the grant. The first implementer's draft of "Grant Management for OAuth 2.0" @@ -18435,11 +18037,11 @@ components: The value of the `credential_configuration_ids` array. ``` - { + { "credential_issuer": "...", "credential_configuration_ids": [ ... ], - "grants": { ... } - } + "grants": { ... } + } ``` This property is mandatory. @@ -18455,18 +18057,18 @@ components: the `tx_code` object. ``` - { + { "credential_issuer": "...", "credential_configuration_ids": [ ... ], - "grants": { - "urn:ietf:params:oauth:grant-type:pre-authorized_code": { + "grants": { + "urn:ietf:params:oauth:grant-type:pre-authorized_code": { "pre-authorized_code": "...", - "tx_code": { + "tx_code": { "length": length - } - } - } - } + } + } + } + } ``` txCodeInputMode: type: string @@ -18477,19 +18079,19 @@ components: object. ``` - { + { "credential_issuer": "...", "credential_configuration_ids": [ ... ], - "grants": { - "urn:ietf:params:oauth:grant-type:pre-authorized_code": { + "grants": { + "urn:ietf:params:oauth:grant-type:pre-authorized_code": { "pre-authorized_code": "...", - "tx_code": { + "tx_code": { "length": length, "input_mode": "..." - } - } - } - } + } + } + } + } ``` txCodeDescription: type: string @@ -18500,19 +18102,19 @@ components: object. ``` - { + { "credential_issuer": "...", "credential_configuration_ids": [ ... ], - "grants": { - "urn:ietf:params:oauth:grant-type:pre-authorized_code": { + "grants": { + "urn:ietf:params:oauth:grant-type:pre-authorized_code": { "pre-authorized_code": "...", - "tx_code": { + "tx_code": { "length": length, "description": "..." - } - } - } - } + } + } + } + } ``` vci_offer_create_response: type: object