diff --git a/spec_next.yaml b/spec_next.yaml
index 6ad9bb6..3abf630 100644
--- a/spec_next.yaml
+++ b/spec_next.yaml
@@ -2264,25 +2264,31 @@ paths:
summary: Get Granted Scopes
description: |
Get the set of scopes that a user has granted to a client application.
+ x-mint:
+ metadata:
+ description: "Get the set of scopes that a user has granted to a client application."
+ content: |
+
+ Possible values for `requestableScopes` parameter in the response from this API are as follows.
- Possible values for `requestableScopes` parameter in the response from this API are as follows.
+ ## null
- ## null
+ The user has not granted authorization to the client application in the past, or records about the
+ combination of the user and the client application have been deleted from Authlete's DB.
- The user has not granted authorization to the client application in the past, or records about the
- combination of the user and the client application have been deleted from Authlete's DB.
+ ## An empty set
- ## An empty set
+ The user has granted authorization to the client application in the past, but no scopes are associated
+ with the authorization.
- The user has granted authorization to the client application in the past, but no scopes are associated
- with the authorization.
+ ## A set with at least one element
- ## A set with at least one element
+ The user has granted authorization to the client application in the past and some scopes are associated
+ with the authorization. These scopes are returned.
+ Example: `[ "profile", "email" ]`
+ The subject parameter is required and must be provided as a query parameter.
+
- The user has granted authorization to the client application in the past and some scopes are associated
- with the authorization. These scopes are returned.
- Example: `[ "profile", "email" ]`
- The subject parameter is required and must be provided as a query parameter.
parameters:
- in: path
name: serviceId
@@ -2582,472 +2588,478 @@ paths:
description: |
This API parses request parameters of an authorization request and returns necessary data for the authorization server
implementation to process the authorization request further.
-
- This API is supposed to be called from within the implementation of the authorization endpoint of
- the service. The endpoint implementation must extract the request parameters from the authorization
- request from the client application and pass them as the value of parameters request parameter for
- Authlete's `/auth/authorization` API.
- The value of `parameters` is either (1) the entire query string when the HTTP method of the request
- from the client application is `GET` or (2) the entire entity body (which is formatted in
- `application/x-www-form-urlencoded`) when the HTTP method of the request from the client application
- is `POST`.
- The following code snippet is an example in JAX-RS showing how to extract request parameters from
- the authorization request.
- ```java
- @GET
- public Response get(@Context UriInfo uriInfo)
- {
- // The query parameters of the authorization request.
- String parameters = uriInfo.getRequestUri().getQuery();
- ......
- }
- @POST
- @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
- public Response post(String parameters)
- {
- // 'parameters' is the entity body of the authorization request.
- ......
- }
- ```
- The endpoint implementation does not have to parse the request parameters from the client application
- because Authlete's `/auth/authorization` API does it.
- The response from `/auth/authorization` API has various parameters. Among them, it is `action`
- parameter that the authorization server implementation should check first because it denotes the
- next action that the authorization server implementation should take. According to the value of
- `action`, the service implementation must take the steps described below.
-
- ## INTERNAL_SERVER_ERROR
-
- When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization
- server implementation was wrong or that an error occurred in Authlete.
- In either case, from the viewpoint of the client application, it is an error on the server side.
- Therefore, the service implementation should generate a response to the client application with
- HTTP status of "500 Internal Server Error". Authlete recommends `application/json` as the content
- type although OAuth 2.0 specification does not mention the format of the error response when the
- redirect URI is not usable.
-
- The value of `responseContent` is a JSON string which describes the error, so it can be used as
- the entity body of the response.
-
- ---
-
- The following illustrates the response which the service implementation should generate and return
- to the client application.
-
- ```
- HTTP/1.1 500 Internal Server Error
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
- The endpoint implementation may return another different response to the client application
- since "500 Internal Server Error" is not required by OAuth 2.0.
-
- ## BAD_REQUEST
-
- When the value of `action` is `BAD_REQUEST`, it means that the request from the client application
- is invalid.
- A response with HTTP status of "400 Bad Request" should be returned to the client application and
- Authlete recommends `application/json` as the content type although OAuth 2.0 specification does
- not mention the format of the error response when the redirect URI is not usable.
-
- The value of `responseContent` is a JSON string which describes the error, so it can be used as
- the entity body of the response.
-
- ---
-
- The following illustrates the response which the service implementation should generate and return
- to the client application.
-
- ```
- HTTP/1.1 400 Bad Request
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
- The endpoint implementation may return another different response to the client application since
- "400 Bad Request" is not required by OAuth 2.0.
-
- ## LOCATION
-
- When the value of `action` is `LOCATION`, it means that the request from the client application
- is invalid but the redirect URI
- to which the error should be reported has been determined.
- A response with HTTP status of "302 Found" must be returned to the client application with `Location`
- header which has a redirect URI with error parameter.
-
- The value of `responseContent` is a redirect URI with `error` parameter, so it can be used as the
- value of `Location` header.
-
- The following illustrates the response which the service implementation must generate and return
- to the client application.
-
- ```
- HTTP/1.1 302 Found
- Location: {responseContent}
- Cache-Control: no-store
- Pragma: no-cache
- ```
-
- ## FORM
-
- When the value of `action` is `FORM`, it means that the request from the client application is
- invalid but the redirect URI to which the error should be reported has been determined, and that
- the authorization request contains `response_mode=form_post` as is defined in [OAuth 2.0 Form Post
- Response Mode](https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html).
- The HTTP status of the response returned to the client application should be "200 OK" and the
- content type should be `text/html;charset=UTF-8`.
-
- The value of `responseContent` is an HTML which can be used as the entity body of the response.
-
- ---
-
- The following illustrates the response which the service implementation must generate and return
- to the client application.
-
- ```
- HTTP/1.1 200 OK
- Content-Type: text/html;charset=UTF-8
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
-
- ## NO_INTERACTION
-
- When the value of `action` is `NO_INTERACTION`, it means that the request from the client application
- has no problem and requires the service to process the request without displaying any user interface
- pages for authentication or consent. This case happens when the authorization request contains
- `prompt=none`.
- The service must follow the steps described below.
-
- **[1] END-USER AUTHENTICATION**
-
- Check whether an end-user has already logged in. If an end-user has logged in, go to the next step ([MAX_AGE]).
- Otherwise, call Authlete's `/auth/authorization/fail` API with `reason=NOT_LOGGED_IN` and use the response from
- the API to generate a response to the client application.
-
- **[2] MAX AGE**
-
- Get the value of `maxAge` parameter from the `/auth/authorization` API response. The value represents
- the maximum authentication age which has come from `max_age` request parameter or `defaultMaxAge`
- configuration parameter of the client application. If the value is `0`, go to the next step ([SUBJECT]).
- Otherwise, follow the sub steps described below.
-
- - (i) Get the time at which the end-user was authenticated. Note that this value is not managed by Authlete,
- meaning that it is expected that the service implementation manages the value. If the service implementation
- does not manage authentication time of end-users, call Authlete's `/auth/authorization/fail` API
- with `reason=MAX_AGE_NOT_SUPPORTED` and use the API response to generate a response to the client
- application.
- - (ii) Add the value of the maximum authentication age (which is represented in seconds) to the authentication
- time. The calculated value is the expiration time.
- - (iii) Check whether the calculated value is equal to or greater than the current time. If this condition
- is satisfied, go to the next step ([SUBJECT]). Otherwise, call Authlete's `/auth/authorization/fail`
- API with `reason=EXCEEDS_MAX_AGE` and use the API response to generate a response to the client
- application.
-
- **[3] SUBJECT**
-
- Get the value of `subject` from the `/auth/authorization` API response. The value represents an
- end-user who the client application expects to grant authorization. If the value is `null`, go to
- the next step ([ACRs]). Otherwise, follow the sub steps described below.
-
- - (i) Compare the value of the requested subject to the current end-user.
- - (ii) If they are equal, go to the next step ([ACRs]). If they are not equal, call Authlete's
- `/auth/authorization/fail` API with `reason=DIFFERENT_SUBJECT` and use the response from the API
- to generate a response to the client application.
-
- **[4] ACRs**
-
- Get the value of `acrs` from the `/auth/authorization` API response. The value represents a list
- of ACRs (Authentication Context Class References) and comes from (1) acr claim in `claims` request
- parameter, (2) `acr_values` request parameter, or (3) `default_acr_values` configuration parameter
- of the client application.
- It is ensured that all the ACRs in acrs are supported by the authorization server implementation.
- In other words, it is ensured that all the ACRs are listed in `acr_values_supported` configuration
- parameter of the authorization server.
- If the value of ACRs is `null`, go to the next step ([ISSUE]). Otherwise, follow the sub steps
- described below.
-
- - (i) Get the ACR performed for the authentication of the current end-user. Note that this value is
- managed not by Authlete but by the authorization server implementation. (If the authorization server
- implementation cannot handle ACRs, it should not have listed ACRs as `acr_values_supported`.)
- - (ii) Compare the ACR value obtained in the above step to each element in the ACR array (`acrs`)
- in the listed order.
- - (iii) If the ACR value was found in the array, (= the ACR performed for the authentication of the
- current end-user did not match any one of the ACRs requested by the client application), check
- whether one of the requested ACRs must be satisfied or not using `acrEssential` parameter in the
- `/auth/authorization` API response. If the value of `acrEssential` parameter is `true`, call Authlete's
- `/auth/authorization/fail` API with `reason=ACR_NOT_SATISFIED` and use the response from the API
- to generate a response to the client application. Otherwise, go to the next step ([SCOPES]).
-
- **[5] SCOPES**
-
- Get the value of `scopes` from the `/auth/authorization` API response. If the array contains a
- scope which has not been granted to the client application by the end-user in the past, call
- Authlete's `/auth/authorization/fail` API with `reason=CONSENT_REQUIRED` and use the response from
- the API to generate a response to the client application. Otherwise, go to the next step ([RESOURCES]).
- Note that Authlete provides APIs to manage records of granted scopes (`/api/client/granted_scopes/*`
- APIs), which is only available in a dedicated/onpremise Authlete server (contact sales@authlete.com
- for details).
-
- **[6] DYNAMIC SCOPES**
-
- Get the value of `dynamicScopes` from the `/auth/authorization` API response. If the array contains
- a scope which has not been granted to the client application by the end-user in the past, call
- Authlete's `/auth/authorization/fail` API with `reason=CONSENT_REQUIRED` and use the response from
- the API to generate a response to the client application. Otherwise, go to the next step ([RESOURCES]).
- Note that Authlete provides APIs to manage records of granted scopes (`/api/client/granted_scopes/*`
- APIs) but dynamic scopes are not remembered as granted scopes.
-
- **[7] RESOURCES**
-
- Get the value of `resources` from the `/auth/authorization` API response. The array represents
- the values of the `resource` request parameters. If you want to reject the request, call Authlete's
- `/auth/authorization/fail` API with `reason=INVALID_TARGET` and use the response from the API to
- generate a response to the client application. Otherwise, go to the next step ([ISSUE]).
- See "Resource Indicators for OAuth 2.0" for details.
-
- **[8] ISSUE**
-
- If all the above steps succeeded, the last step is to issue an authorization code, an ID token
- and/or an access token. (There is a special case, though. In the case of `response_type=none`,
- nothing is issued.) It can be performed by calling Authlete's `/auth/authorization/issue` API.
- The API requires the following parameters. Prepare these parameters and call `/auth/authorization/issue`
- API and use the response to generate a response to the client application.
- - `ticket` (required)
- This parameter represents a ticket which is exchanged with tokens at `/auth/authorization/issue`.
- Use the value of `ticket` contained in the `/auth/authorization` API response.
- - `subject` (required)
- This parameter represents the unique identifier of the current end-user. It is often called "user ID"
- and it may or may not be visible to the user. In any case, it is a number or a string assigned
- to an end-user by the authorization server implementation. Authlete does not care about the format
- of the value of subject, but it must consist of only ASCII letters and its length must not exceed 100.
- When the value of `subject` parameter in the /auth/authorization API response is not `null`,
- it is necessarily identical to the value of `subject` parameter in the `/auth/authorization/issue`
- API request.
- The value of this parameter will be embedded in an ID token as the value of `sub` claim. When
- the value of `subject_type` configuration parameter of the client application is `PAIRWISE`,
- the value of sub claim is different from the value specified by this parameter, See [8. Subject
- Identifier Types](https://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes) of OpenID
- Connect Core 1.0 for details about subject types.
- You can use the `sub` request parameter to adjust the value of the `sub` claim in an ID token.
- See the description of the `sub` request parameter for details.
- - `authTime` (optional)
- This parameter represents the time when the end-user authentication occurred. Its value is the
- number of seconds from `1970-01-01`. The value of this parameter will be embedded in an ID token
- as the value of `auth_time` claim.
- - `acr` (optional)
- This parameter represents the ACR (Authentication Context Class Reference) which the authentication
- of the end-user satisfies. When `acrs` in the `/auth/authorization` API response is a non-empty
- array and the value of `acrEssential` is `true`, the value of this parameter must be one of the
- array elements. Otherwise, even `null` is allowed. The value of this parameter will be embedded
- in an ID token as the value of `acr` claim.
- - `claims` (optional)
- This parameter represents claims of the end-user. "Claims" here are pieces of information about
- the end-user such as `"name"`, `"email"` and `"birthdate"`. The authorization server implementation
- is required to gather claims of the end-user, format the claim values into JSON and set the JSON
- string as the value of this parameter.
- The claims which the authorization server implementation is required to gather are listed in
- `claims` parameter in the `/auth/authorization` API response.
- For example, if claims parameter lists `"name"`, `"email"` and `"birthdate"`, the value of this
- parameter should look like the following.
- ```json
+ x-mint:
+ metadata:
+ description: "This API parses request parameters of an authorization request and returns necessary data for the authorization server implementation to process the authorization request further."
+ content: |
+
+ This API is supposed to be called from within the implementation of the authorization endpoint of
+ the service. The endpoint implementation must extract the request parameters from the authorization
+ request from the client application and pass them as the value of parameters request parameter for
+ Authlete's `/auth/authorization` API.
+ The value of `parameters` is either (1) the entire query string when the HTTP method of the request
+ from the client application is `GET` or (2) the entire entity body (which is formatted in
+ `application/x-www-form-urlencoded`) when the HTTP method of the request from the client application
+ is `POST`.
+ The following code snippet is an example in JAX-RS showing how to extract request parameters from
+ the authorization request.
+ ```java
+ @GET
+ public Response get(@Context UriInfo uriInfo)
+ {
+ // The query parameters of the authorization request.
+ String parameters = uriInfo.getRequestUri().getQuery();
+ ......
+ }
+ @POST
+ @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
+ public Response post(String parameters)
{
- "name": "John Smith",
- "email": "john@example.com",
- "birthdate": "1974-05-06"
+ // 'parameters' is the entity body of the authorization request.
+ ......
}
```
- `claimsLocales` parameter in the `/auth/authorization` API response lists the end-user's preferred
- languages and scripts, ordered by preference. When `claimsLocales` parameter is a non-empty array,
- its elements should be taken into account when the authorization server implementation gathers
- claim values. Especially, note the excerpt below from [5.2. Claims Languages and Scripts](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsLanguagesAndScripts)
- of OpenID Connect Core 1.0.
- > When the OP determines, either through the `claims_locales` parameter, or by other means, that
- the End-User and Client are requesting Claims in only one set of languages and scripts, it is
- RECOMMENDED that OPs return Claims without language tags when they employ this language and script.
- It is also RECOMMENDED that Clients be written in a manner that they can handle and utilize Claims
- using language tags.
- If `claims` parameter in the `/auth/authorization` API response is `null` or an empty array,
- the value of this parameter should be `null`.
- See [5.1. Standard Claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims)
- of OpenID Connect core 1.0 for claim names and their value formats. Note (1) that the authorization
- server implementation support its special claims ([5.1.2. Additional Claims](https://openid.net/specs/openid-connect-core-1_0.html#AdditionalClaims))
- and (2) that claim names may be followed by a language tag ([5.2. Claims Languages and Scripts](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsLanguagesAndScripts)).
- Read the specification of [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)
- for details.
- The claim values in this parameter will be embedded in an ID token.
- Note that `idTokenClaims` parameter is available in the `/auth/authorization` API response.
- The parameter has the value of the `"id_token"` property in the `claims` request parameter or
- in the `"claims"` property in a request object. The value of this parameter should be considered
- when you prepare claim values.
- - `properties` (optional)
- Extra properties to associate with an access token and/or an authorization code that may be issued
- by this request. Note that `properties` parameter is accepted only when `Content-Type` of the
- request is `application/json`, so don't use `application/x-www-form-urlencoded` for details.
- - `scopes` (optional)
- Scopes to associate with an access token and/or an authorization code. If this parameter is `null`,
- the scopes specified in the original authorization request from the client application are used.
- In other cases, including the case of an empty array, the specified scopes will replace the original
- scopes contained in the original authorization request.
- Even scopes that are not included in the original authorization request can be specified. However,
- as an exception, `openid` scope is ignored on the server side if it is not included in the original
- request. It is because the existence of `openid` scope considerably changes the validation steps
- and because adding `openid` triggers generation of an ID token (although the client application
- has not requested it) and the behavior is a major violation against the specification.
- If you add `offline_access` scope although it is not included in the original request, keep in
- mind that the specification requires explicit consent from the user for the scope ([OpenID Connect
- Core 1.0, 11. Offline Access](https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess)).
- When `offline_access` is included in the original request, the current implementation of Authlete's
- `/auth/authorization` API checks whether the request has come along with `prompt` request parameter
- and the value includes consent. However, note that the implementation of Authlete's `/auth/authorization/issue`
- API does not perform such checking if `offline_access` scope is added via this `scopes` parameter.
- - `sub` (optional)
- The value of the `sub` claim in an ID token. If the value of this request parameter is not empty,
- it is used as the value of the `sub` claim. Otherwise, the value of the `subject` request parameter
- is used as the value of the `sub` claim. The main purpose of this parameter is to hide the actual
- value of the subject from client applications.
- Note that even if this `sub` parameter is not empty, the value of the subject request parameter
- is used as the value of the subject which is associated with the access token.
-
- ## INTERACTION
-
- When the value of `action` is `INTERACTION`, it means that the request from the client application
- has no problem and requires the service to process the request with user interaction by an HTML form.
- The purpose of the UI displayed to the end-user is to ask the end-user to grant authorization to
- the client application. The items described below are some points which the service implementation
- should take into account when it builds the UI.
-
- **[1] DISPLAY MODE**
-
- The response from `/auth/authorization` API has `display` parameter. It is one of `PAGE` (default),
- `POPUP`, `TOUCH` and `WAP` The meanings of the values are described in [3.1.2.1. Authentication
- Request of OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).
- Basically, the authorization server implementation should display the UI which is suitable for the
- display mode, but it is okay for the authorization server implementation to "attempt to detect the
- capabilities of the User Agent and present an appropriate display".
- It is ensured that the value of `display` is one of the supported display modes which are specified
- by `supportedDisplays` configuration parameter of the service.
+ The endpoint implementation does not have to parse the request parameters from the client application
+ because Authlete's `/auth/authorization` API does it.
+ The response from `/auth/authorization` API has various parameters. Among them, it is `action`
+ parameter that the authorization server implementation should check first because it denotes the
+ next action that the authorization server implementation should take. According to the value of
+ `action`, the service implementation must take the steps described below.
- **[2] UI LOCALE**
+ ## INTERNAL_SERVER_ERROR
- The response from `/auth/authorization` API has `uiLocales` parameter. It it is not `null`, it lists
- language tag values (such as `fr-CA`, `ja-JP` and `en`) ordered by preference. The service implementation
- should display the UI in one of the language listed in the parameter when possible. It is ensured
- that language tags listed in `uiLocales` are contained in the list of supported UI locales which
- are specified by `supportedUiLocales` configuration parameter of the service.
+ When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization
+ server implementation was wrong or that an error occurred in Authlete.
+ In either case, from the viewpoint of the client application, it is an error on the server side.
+ Therefore, the service implementation should generate a response to the client application with
+ HTTP status of "500 Internal Server Error". Authlete recommends `application/json` as the content
+ type although OAuth 2.0 specification does not mention the format of the error response when the
+ redirect URI is not usable.
- **[3] CLIENT INFORMATION**
+ The value of `responseContent` is a JSON string which describes the error, so it can be used as
+ the entity body of the response.
- The authorization server implementation should show information about the client application to
- the end-user. The information is embedded in `client` parameter in the response from `/auth/authorization`
- API.
+ ---
+
+ The following illustrates the response which the service implementation should generate and return
+ to the client application.
+
+ ```
+ HTTP/1.1 500 Internal Server Error
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+ The endpoint implementation may return another different response to the client application
+ since "500 Internal Server Error" is not required by OAuth 2.0.
+
+ ## BAD_REQUEST
+
+ When the value of `action` is `BAD_REQUEST`, it means that the request from the client application
+ is invalid.
+ A response with HTTP status of "400 Bad Request" should be returned to the client application and
+ Authlete recommends `application/json` as the content type although OAuth 2.0 specification does
+ not mention the format of the error response when the redirect URI is not usable.
+
+ The value of `responseContent` is a JSON string which describes the error, so it can be used as
+ the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the service implementation should generate and return
+ to the client application.
+
+ ```
+ HTTP/1.1 400 Bad Request
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+ The endpoint implementation may return another different response to the client application since
+ "400 Bad Request" is not required by OAuth 2.0.
+
+ ## LOCATION
+
+ When the value of `action` is `LOCATION`, it means that the request from the client application
+ is invalid but the redirect URI
+ to which the error should be reported has been determined.
+ A response with HTTP status of "302 Found" must be returned to the client application with `Location`
+ header which has a redirect URI with error parameter.
+
+ The value of `responseContent` is a redirect URI with `error` parameter, so it can be used as the
+ value of `Location` header.
+
+ The following illustrates the response which the service implementation must generate and return
+ to the client application.
+
+ ```
+ HTTP/1.1 302 Found
+ Location: {responseContent}
+ Cache-Control: no-store
+ Pragma: no-cache
+ ```
+
+ ## FORM
+
+ When the value of `action` is `FORM`, it means that the request from the client application is
+ invalid but the redirect URI to which the error should be reported has been determined, and that
+ the authorization request contains `response_mode=form_post` as is defined in [OAuth 2.0 Form Post
+ Response Mode](https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html).
+ The HTTP status of the response returned to the client application should be "200 OK" and the
+ content type should be `text/html;charset=UTF-8`.
+
+ The value of `responseContent` is an HTML which can be used as the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the service implementation must generate and return
+ to the client application.
+
+ ```
+ HTTP/1.1 200 OK
+ Content-Type: text/html;charset=UTF-8
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
+ ## NO_INTERACTION
+
+ When the value of `action` is `NO_INTERACTION`, it means that the request from the client application
+ has no problem and requires the service to process the request without displaying any user interface
+ pages for authentication or consent. This case happens when the authorization request contains
+ `prompt=none`.
+ The service must follow the steps described below.
+
+ **[1] END-USER AUTHENTICATION**
+
+ Check whether an end-user has already logged in. If an end-user has logged in, go to the next step ([MAX_AGE]).
+ Otherwise, call Authlete's `/auth/authorization/fail` API with `reason=NOT_LOGGED_IN` and use the response from
+ the API to generate a response to the client application.
+
+ **[2] MAX AGE**
+
+ Get the value of `maxAge` parameter from the `/auth/authorization` API response. The value represents
+ the maximum authentication age which has come from `max_age` request parameter or `defaultMaxAge`
+ configuration parameter of the client application. If the value is `0`, go to the next step ([SUBJECT]).
+ Otherwise, follow the sub steps described below.
+
+ - (i) Get the time at which the end-user was authenticated. Note that this value is not managed by Authlete,
+ meaning that it is expected that the service implementation manages the value. If the service implementation
+ does not manage authentication time of end-users, call Authlete's `/auth/authorization/fail` API
+ with `reason=MAX_AGE_NOT_SUPPORTED` and use the API response to generate a response to the client
+ application.
+ - (ii) Add the value of the maximum authentication age (which is represented in seconds) to the authentication
+ time. The calculated value is the expiration time.
+ - (iii) Check whether the calculated value is equal to or greater than the current time. If this condition
+ is satisfied, go to the next step ([SUBJECT]). Otherwise, call Authlete's `/auth/authorization/fail`
+ API with `reason=EXCEEDS_MAX_AGE` and use the API response to generate a response to the client
+ application.
+
+ **[3] SUBJECT**
+
+ Get the value of `subject` from the `/auth/authorization` API response. The value represents an
+ end-user who the client application expects to grant authorization. If the value is `null`, go to
+ the next step ([ACRs]). Otherwise, follow the sub steps described below.
+
+ - (i) Compare the value of the requested subject to the current end-user.
+ - (ii) If they are equal, go to the next step ([ACRs]). If they are not equal, call Authlete's
+ `/auth/authorization/fail` API with `reason=DIFFERENT_SUBJECT` and use the response from the API
+ to generate a response to the client application.
+
+ **[4] ACRs**
+
+ Get the value of `acrs` from the `/auth/authorization` API response. The value represents a list
+ of ACRs (Authentication Context Class References) and comes from (1) acr claim in `claims` request
+ parameter, (2) `acr_values` request parameter, or (3) `default_acr_values` configuration parameter
+ of the client application.
+ It is ensured that all the ACRs in acrs are supported by the authorization server implementation.
+ In other words, it is ensured that all the ACRs are listed in `acr_values_supported` configuration
+ parameter of the authorization server.
+ If the value of ACRs is `null`, go to the next step ([ISSUE]). Otherwise, follow the sub steps
+ described below.
+
+ - (i) Get the ACR performed for the authentication of the current end-user. Note that this value is
+ managed not by Authlete but by the authorization server implementation. (If the authorization server
+ implementation cannot handle ACRs, it should not have listed ACRs as `acr_values_supported`.)
+ - (ii) Compare the ACR value obtained in the above step to each element in the ACR array (`acrs`)
+ in the listed order.
+ - (iii) If the ACR value was found in the array, (= the ACR performed for the authentication of the
+ current end-user did not match any one of the ACRs requested by the client application), check
+ whether one of the requested ACRs must be satisfied or not using `acrEssential` parameter in the
+ `/auth/authorization` API response. If the value of `acrEssential` parameter is `true`, call Authlete's
+ `/auth/authorization/fail` API with `reason=ACR_NOT_SATISFIED` and use the response from the API
+ to generate a response to the client application. Otherwise, go to the next step ([SCOPES]).
+
+ **[5] SCOPES**
+
+ Get the value of `scopes` from the `/auth/authorization` API response. If the array contains a
+ scope which has not been granted to the client application by the end-user in the past, call
+ Authlete's `/auth/authorization/fail` API with `reason=CONSENT_REQUIRED` and use the response from
+ the API to generate a response to the client application. Otherwise, go to the next step ([RESOURCES]).
+ Note that Authlete provides APIs to manage records of granted scopes (`/api/client/granted_scopes/*`
+ APIs), which is only available in a dedicated/onpremise Authlete server (contact sales@authlete.com
+ for details).
+
+ **[6] DYNAMIC SCOPES**
+
+ Get the value of `dynamicScopes` from the `/auth/authorization` API response. If the array contains
+ a scope which has not been granted to the client application by the end-user in the past, call
+ Authlete's `/auth/authorization/fail` API with `reason=CONSENT_REQUIRED` and use the response from
+ the API to generate a response to the client application. Otherwise, go to the next step ([RESOURCES]).
+ Note that Authlete provides APIs to manage records of granted scopes (`/api/client/granted_scopes/*`
+ APIs) but dynamic scopes are not remembered as granted scopes.
+
+ **[7] RESOURCES**
+
+ Get the value of `resources` from the `/auth/authorization` API response. The array represents
+ the values of the `resource` request parameters. If you want to reject the request, call Authlete's
+ `/auth/authorization/fail` API with `reason=INVALID_TARGET` and use the response from the API to
+ generate a response to the client application. Otherwise, go to the next step ([ISSUE]).
+ See "Resource Indicators for OAuth 2.0" for details.
+
+ **[8] ISSUE**
+
+ If all the above steps succeeded, the last step is to issue an authorization code, an ID token
+ and/or an access token. (There is a special case, though. In the case of `response_type=none`,
+ nothing is issued.) It can be performed by calling Authlete's `/auth/authorization/issue` API.
+ The API requires the following parameters. Prepare these parameters and call `/auth/authorization/issue`
+ API and use the response to generate a response to the client application.
+ - `ticket` (required)
+ This parameter represents a ticket which is exchanged with tokens at `/auth/authorization/issue`.
+ Use the value of `ticket` contained in the `/auth/authorization` API response.
+ - `subject` (required)
+ This parameter represents the unique identifier of the current end-user. It is often called "user ID"
+ and it may or may not be visible to the user. In any case, it is a number or a string assigned
+ to an end-user by the authorization server implementation. Authlete does not care about the format
+ of the value of subject, but it must consist of only ASCII letters and its length must not exceed 100.
+ When the value of `subject` parameter in the /auth/authorization API response is not `null`,
+ it is necessarily identical to the value of `subject` parameter in the `/auth/authorization/issue`
+ API request.
+ The value of this parameter will be embedded in an ID token as the value of `sub` claim. When
+ the value of `subject_type` configuration parameter of the client application is `PAIRWISE`,
+ the value of sub claim is different from the value specified by this parameter, See [8. Subject
+ Identifier Types](https://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes) of OpenID
+ Connect Core 1.0 for details about subject types.
+ You can use the `sub` request parameter to adjust the value of the `sub` claim in an ID token.
+ See the description of the `sub` request parameter for details.
+ - `authTime` (optional)
+ This parameter represents the time when the end-user authentication occurred. Its value is the
+ number of seconds from `1970-01-01`. The value of this parameter will be embedded in an ID token
+ as the value of `auth_time` claim.
+ - `acr` (optional)
+ This parameter represents the ACR (Authentication Context Class Reference) which the authentication
+ of the end-user satisfies. When `acrs` in the `/auth/authorization` API response is a non-empty
+ array and the value of `acrEssential` is `true`, the value of this parameter must be one of the
+ array elements. Otherwise, even `null` is allowed. The value of this parameter will be embedded
+ in an ID token as the value of `acr` claim.
+ - `claims` (optional)
+ This parameter represents claims of the end-user. "Claims" here are pieces of information about
+ the end-user such as `"name"`, `"email"` and `"birthdate"`. The authorization server implementation
+ is required to gather claims of the end-user, format the claim values into JSON and set the JSON
+ string as the value of this parameter.
+ The claims which the authorization server implementation is required to gather are listed in
+ `claims` parameter in the `/auth/authorization` API response.
+ For example, if claims parameter lists `"name"`, `"email"` and `"birthdate"`, the value of this
+ parameter should look like the following.
+ ```json
+ {
+ "name": "John Smith",
+ "email": "john@example.com",
+ "birthdate": "1974-05-06"
+ }
+ ```
+ `claimsLocales` parameter in the `/auth/authorization` API response lists the end-user's preferred
+ languages and scripts, ordered by preference. When `claimsLocales` parameter is a non-empty array,
+ its elements should be taken into account when the authorization server implementation gathers
+ claim values. Especially, note the excerpt below from [5.2. Claims Languages and Scripts](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsLanguagesAndScripts)
+ of OpenID Connect Core 1.0.
+ > When the OP determines, either through the `claims_locales` parameter, or by other means, that
+ the End-User and Client are requesting Claims in only one set of languages and scripts, it is
+ RECOMMENDED that OPs return Claims without language tags when they employ this language and script.
+ It is also RECOMMENDED that Clients be written in a manner that they can handle and utilize Claims
+ using language tags.
+ If `claims` parameter in the `/auth/authorization` API response is `null` or an empty array,
+ the value of this parameter should be `null`.
+ See [5.1. Standard Claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims)
+ of OpenID Connect core 1.0 for claim names and their value formats. Note (1) that the authorization
+ server implementation support its special claims ([5.1.2. Additional Claims](https://openid.net/specs/openid-connect-core-1_0.html#AdditionalClaims))
+ and (2) that claim names may be followed by a language tag ([5.2. Claims Languages and Scripts](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsLanguagesAndScripts)).
+ Read the specification of [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)
+ for details.
+ The claim values in this parameter will be embedded in an ID token.
+ Note that `idTokenClaims` parameter is available in the `/auth/authorization` API response.
+ The parameter has the value of the `"id_token"` property in the `claims` request parameter or
+ in the `"claims"` property in a request object. The value of this parameter should be considered
+ when you prepare claim values.
+ - `properties` (optional)
+ Extra properties to associate with an access token and/or an authorization code that may be issued
+ by this request. Note that `properties` parameter is accepted only when `Content-Type` of the
+ request is `application/json`, so don't use `application/x-www-form-urlencoded` for details.
+ - `scopes` (optional)
+ Scopes to associate with an access token and/or an authorization code. If this parameter is `null`,
+ the scopes specified in the original authorization request from the client application are used.
+ In other cases, including the case of an empty array, the specified scopes will replace the original
+ scopes contained in the original authorization request.
+ Even scopes that are not included in the original authorization request can be specified. However,
+ as an exception, `openid` scope is ignored on the server side if it is not included in the original
+ request. It is because the existence of `openid` scope considerably changes the validation steps
+ and because adding `openid` triggers generation of an ID token (although the client application
+ has not requested it) and the behavior is a major violation against the specification.
+ If you add `offline_access` scope although it is not included in the original request, keep in
+ mind that the specification requires explicit consent from the user for the scope ([OpenID Connect
+ Core 1.0, 11. Offline Access](https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess)).
+ When `offline_access` is included in the original request, the current implementation of Authlete's
+ `/auth/authorization` API checks whether the request has come along with `prompt` request parameter
+ and the value includes consent. However, note that the implementation of Authlete's `/auth/authorization/issue`
+ API does not perform such checking if `offline_access` scope is added via this `scopes` parameter.
+ - `sub` (optional)
+ The value of the `sub` claim in an ID token. If the value of this request parameter is not empty,
+ it is used as the value of the `sub` claim. Otherwise, the value of the `subject` request parameter
+ is used as the value of the `sub` claim. The main purpose of this parameter is to hide the actual
+ value of the subject from client applications.
+ Note that even if this `sub` parameter is not empty, the value of the subject request parameter
+ is used as the value of the subject which is associated with the access token.
+
+ ## INTERACTION
+
+ When the value of `action` is `INTERACTION`, it means that the request from the client application
+ has no problem and requires the service to process the request with user interaction by an HTML form.
+ The purpose of the UI displayed to the end-user is to ask the end-user to grant authorization to
+ the client application. The items described below are some points which the service implementation
+ should take into account when it builds the UI.
+
+ **[1] DISPLAY MODE**
+
+ The response from `/auth/authorization` API has `display` parameter. It is one of `PAGE` (default),
+ `POPUP`, `TOUCH` and `WAP` The meanings of the values are described in [3.1.2.1. Authentication
+ Request of OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).
+ Basically, the authorization server implementation should display the UI which is suitable for the
+ display mode, but it is okay for the authorization server implementation to "attempt to detect the
+ capabilities of the User Agent and present an appropriate display".
+ It is ensured that the value of `display` is one of the supported display modes which are specified
+ by `supportedDisplays` configuration parameter of the service.
+
+ **[2] UI LOCALE**
+
+ The response from `/auth/authorization` API has `uiLocales` parameter. It it is not `null`, it lists
+ language tag values (such as `fr-CA`, `ja-JP` and `en`) ordered by preference. The service implementation
+ should display the UI in one of the language listed in the parameter when possible. It is ensured
+ that language tags listed in `uiLocales` are contained in the list of supported UI locales which
+ are specified by `supportedUiLocales` configuration parameter of the service.
+
+ **[3] CLIENT INFORMATION**
+
+ The authorization server implementation should show information about the client application to
+ the end-user. The information is embedded in `client` parameter in the response from `/auth/authorization`
+ API.
+
+ **[4] SCOPES**
+
+ A client application requires authorization for specific permissions. In OAuth 2.0 specification,
+ "scope" is a technical term which represents a permission. `scopes` parameter in the response
+ from `/auth/authorization` API is a list of scopes requested by the client application. The service
+ implementation should show the end-user the scopes.
+ The authorization server implementation may choose not to show scopes to which the end-user has
+ given consent in the past. To put it the other way around, the authorization server implementation
+ may show only the scopes to which the end-user has not given consent yet. However, if the value
+ of `prompts` response parameter contains `CONSENT`, the authorization server implementation has
+ to obtain explicit consent from the end-user even if the end-user has given consent to all the
+ requested scopes in the past.
+ Note that Authlete provides APIs to manage records of granted scopes (`/api/client/granted_scopes/*`
+ APIs), but the APIs work only in the case the Authlete server you use is a dedicated Authlete server
+ (contact sales@authlete.com for details). In other words, the APIs of the shared Authlete server
+ are disabled intentionally (in order to prevent garbage data from being accumulated) and they
+ return 403 Forbidden.
+ It is ensured that the values in `scopes` parameter are contained in the list of supported scopes
+ which are specified by `supportedScopes` configuration parameter of the service.
+
+ **[5] DYNAMIC SCOPES**
+
+ The authorization request may include dynamic scopes. The list of recognized dynamic scopes are
+ accessible by getDynamicScopes() method. See the description of the [DynamicScope](https://authlete.github.io/authlete-java-common/com/authlete/common/dto/DynamicScope.html)
+ class for details about dynamic scopes.
+
+ **[6] AUTHORIZATION DETAILS**
+
+ The authorization server implementation should show the end-user "authorization details" if the
+ request includes it. The value of `authorization_details` parameter in the response is the content
+ of the `authorization_details` request parameter.
+ See "OAuth 2.0 Rich Authorization Requests" for details.
+
+ **[7] PURPOSE**
+
+ The authorization server implementation must show the value of the `purpose` request parameter if
+ it supports [OpenID Connect for Identity Assurance 1.0](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html).
+ See [8. Transaction-specific Purpose](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#rfc.section.8)
+ in the specification for details.
+ Note that the value of `purpose` response parameter is the value of the purpose request parameter.
+
+ **[7] END-USER AUTHENTICATION**
+
+ Necessarily, the end-user must be authenticated (= must login the service) before granting authorization
+ to the client application. Simply put, a login form is expected to be displayed for end-user authentication.
+ The service implementation must follow the steps described below to comply with OpenID Connect.
+ (Or just always show a login form if it's too much of a bother.)
+
+ - (i) Get the value of `prompts` response parameter. It corresponds to the value of the `prompt`
+ request parameter. Details of the request parameter are described in [3.1.2.1. Authentication
+ Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) of OpenID Connect Core 1.0.
+ - (ii) If the value of `prompts` parameter is `SELECT_ACCOUNT` display a form to let the end-user
+ select on of his/her accounts for login. If `subject` response parameter is not `null`, it is the
+ end-user ID that the client application expects, so the value should be used to determine the value
+ of the login ID. Note that a subject and a login ID are not necessarily equal. If the value of
+ `subject` response parameter is `null`, the value of `loginHint` response parameter should be referred
+ to as a hint to determine the value of the login ID. The value of `loginHint` response parameter
+ is simply the value of the `login_hint` request parameter.
+ - (iii) If the value of `prompts` response parameter contains `LOGIN`, display a form to urge the
+ end-user to login even if the end-user has already logged in. If the value of `subject` response
+ parameter is not `null`, it is the end-user ID that the client application expects, so the value
+ should be used to determine the value of the login ID. Note that a subject and a login ID are not
+ necessarily equal. If the value of `subject` response parameter is `null`, the value of `loginHint`
+ response parameter should be referred to as a hint to determine the value of the login ID. The value
+ of `loginHint` response parameter is simply the value of the `login_hint` request parameter.
+ - (iv) If the value of `prompts` response parameter does not contain `LOGIN`, the authorization server
+ implementation does not have to authenticate the end-user if all the conditions described below
+ are satisfied. If any one of the conditions is not satisfied, show a login form to authenticate
+ the end-user.
+ - An end-user has already logged in the service.
+ - The login ID of the current end-user matches the value of `subject` response parameter.
+ This check is required only when the value of `subject` response parameter is a non-null value.
+ - The max age, which is the number of seconds contained in `maxAge` response parameter,
+ has not passed since the current end-user logged in your service. This check is required only when
+ the value of `maxAge` response parameter is a non-zero value.
+ - If the authorization server implementation does not manage authentication time of end-users
+ (= if the authorization server implementation cannot know when end-users logged in) and if the
+ value of `maxAge` response parameter is a non-zero value, a login form should be displayed.
+ - The ACR (Authentication Context Class Reference) of the authentication performed for
+ the current end-user satisfies one of the ACRs listed in `acrs` response parameter. This check is
+ required only when the value of `acrs` response parameter is a non-empty array.
+ In every case, the end-user authentication must satisfy one of the ACRs listed in `acrs` response
+ parameter when the value of `acrs` response parameter is a non-empty array and `acrEssential`
+ response parameter is `true`.
+
+ **[9] GRANT/DENY BUTTONS**
+
+ The end-user is supposed to choose either (1) to grant authorization to the client application or
+ (2) to deny the authorization request. The UI must have UI components to accept the judgment by
+ the user. Usually, a button to grant authorization and a button to deny the request are provided.
+ When the value of `subject` response parameter is not `null`, the end-user authentication must be
+ performed for the subject, meaning that the authorization server implementation should repeatedly
+ show a login form until the subject is successfully authenticated.
+ The end-user will choose either (1) to grant authorization to the client application or (2) to
+ deny the authorization request. When the end-user chose to deny the authorization request, call
+ Authlete's `/auth/authorization/fail` API with `reason=DENIED` and use the response from the API
+ to generate a response to the client application.
+ When the end-user chose to grant authorization to the client application, the authorization server
+ implementation has to issue an authorization code, an ID token, and/or an access token to the client
+ application. (There is a special case. When `response_type=none`, nothing is issued.) Issuing the
+ tokens can be performed by calling Authlete's `/auth/authorization/issue` API. Read [ISSUE] written
+ above in the description for the case of `action=NO_INTERACTION`.
+
- **[4] SCOPES**
-
- A client application requires authorization for specific permissions. In OAuth 2.0 specification,
- "scope" is a technical term which represents a permission. `scopes` parameter in the response
- from `/auth/authorization` API is a list of scopes requested by the client application. The service
- implementation should show the end-user the scopes.
- The authorization server implementation may choose not to show scopes to which the end-user has
- given consent in the past. To put it the other way around, the authorization server implementation
- may show only the scopes to which the end-user has not given consent yet. However, if the value
- of `prompts` response parameter contains `CONSENT`, the authorization server implementation has
- to obtain explicit consent from the end-user even if the end-user has given consent to all the
- requested scopes in the past.
- Note that Authlete provides APIs to manage records of granted scopes (`/api/client/granted_scopes/*`
- APIs), but the APIs work only in the case the Authlete server you use is a dedicated Authlete server
- (contact sales@authlete.com for details). In other words, the APIs of the shared Authlete server
- are disabled intentionally (in order to prevent garbage data from being accumulated) and they
- return 403 Forbidden.
- It is ensured that the values in `scopes` parameter are contained in the list of supported scopes
- which are specified by `supportedScopes` configuration parameter of the service.
-
- **[5] DYNAMIC SCOPES**
-
- The authorization request may include dynamic scopes. The list of recognized dynamic scopes are
- accessible by getDynamicScopes() method. See the description of the [DynamicScope](https://authlete.github.io/authlete-java-common/com/authlete/common/dto/DynamicScope.html)
- class for details about dynamic scopes.
-
- **[6] AUTHORIZATION DETAILS**
-
- The authorization server implementation should show the end-user "authorization details" if the
- request includes it. The value of `authorization_details` parameter in the response is the content
- of the `authorization_details` request parameter.
- See "OAuth 2.0 Rich Authorization Requests" for details.
-
- **[7] PURPOSE**
-
- The authorization server implementation must show the value of the `purpose` request parameter if
- it supports [OpenID Connect for Identity Assurance 1.0](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html).
- See [8. Transaction-specific Purpose](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#rfc.section.8)
- in the specification for details.
- Note that the value of `purpose` response parameter is the value of the purpose request parameter.
-
- **[7] END-USER AUTHENTICATION**
-
- Necessarily, the end-user must be authenticated (= must login the service) before granting authorization
- to the client application. Simply put, a login form is expected to be displayed for end-user authentication.
- The service implementation must follow the steps described below to comply with OpenID Connect.
- (Or just always show a login form if it's too much of a bother.)
-
- - (i) Get the value of `prompts` response parameter. It corresponds to the value of the `prompt`
- request parameter. Details of the request parameter are described in [3.1.2.1. Authentication
- Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) of OpenID Connect Core 1.0.
- - (ii) If the value of `prompts` parameter is `SELECT_ACCOUNT` display a form to let the end-user
- select on of his/her accounts for login. If `subject` response parameter is not `null`, it is the
- end-user ID that the client application expects, so the value should be used to determine the value
- of the login ID. Note that a subject and a login ID are not necessarily equal. If the value of
- `subject` response parameter is `null`, the value of `loginHint` response parameter should be referred
- to as a hint to determine the value of the login ID. The value of `loginHint` response parameter
- is simply the value of the `login_hint` request parameter.
- - (iii) If the value of `prompts` response parameter contains `LOGIN`, display a form to urge the
- end-user to login even if the end-user has already logged in. If the value of `subject` response
- parameter is not `null`, it is the end-user ID that the client application expects, so the value
- should be used to determine the value of the login ID. Note that a subject and a login ID are not
- necessarily equal. If the value of `subject` response parameter is `null`, the value of `loginHint`
- response parameter should be referred to as a hint to determine the value of the login ID. The value
- of `loginHint` response parameter is simply the value of the `login_hint` request parameter.
- - (iv) If the value of `prompts` response parameter does not contain `LOGIN`, the authorization server
- implementation does not have to authenticate the end-user if all the conditions described below
- are satisfied. If any one of the conditions is not satisfied, show a login form to authenticate
- the end-user.
- - An end-user has already logged in the service.
- - The login ID of the current end-user matches the value of `subject` response parameter.
- This check is required only when the value of `subject` response parameter is a non-null value.
- - The max age, which is the number of seconds contained in `maxAge` response parameter,
- has not passed since the current end-user logged in your service. This check is required only when
- the value of `maxAge` response parameter is a non-zero value.
- - If the authorization server implementation does not manage authentication time of end-users
- (= if the authorization server implementation cannot know when end-users logged in) and if the
- value of `maxAge` response parameter is a non-zero value, a login form should be displayed.
- - The ACR (Authentication Context Class Reference) of the authentication performed for
- the current end-user satisfies one of the ACRs listed in `acrs` response parameter. This check is
- required only when the value of `acrs` response parameter is a non-empty array.
- In every case, the end-user authentication must satisfy one of the ACRs listed in `acrs` response
- parameter when the value of `acrs` response parameter is a non-empty array and `acrEssential`
- response parameter is `true`.
-
- **[9] GRANT/DENY BUTTONS**
-
- The end-user is supposed to choose either (1) to grant authorization to the client application or
- (2) to deny the authorization request. The UI must have UI components to accept the judgment by
- the user. Usually, a button to grant authorization and a button to deny the request are provided.
- When the value of `subject` response parameter is not `null`, the end-user authentication must be
- performed for the subject, meaning that the authorization server implementation should repeatedly
- show a login form until the subject is successfully authenticated.
- The end-user will choose either (1) to grant authorization to the client application or (2) to
- deny the authorization request. When the end-user chose to deny the authorization request, call
- Authlete's `/auth/authorization/fail` API with `reason=DENIED` and use the response from the API
- to generate a response to the client application.
- When the end-user chose to grant authorization to the client application, the authorization server
- implementation has to issue an authorization code, an ID token, and/or an access token to the client
- application. (There is a special case. When `response_type=none`, nothing is issued.) Issuing the
- tokens can be performed by calling Authlete's `/auth/authorization/issue` API. Read [ISSUE] written
- above in the description for the case of `action=NO_INTERACTION`.
parameters:
- in: path
name: serviceId
@@ -3157,100 +3169,106 @@ paths:
description: |
This API generates a content of an error authorization response that the authorization server implementation
returns to the client application.
+ x-mint:
+ metadata:
+ description: "This API generates a content of an error authorization response that the authorization server implementation returns to the client application."
+ content: |
+
+ This API is supposed to be called from within the implementation of the authorization endpoint of the service
+ in order to generate an error response to the client application.
+ The description of the `/auth/authorization` API describes the timing when this API should be called.
+ The response from `/auth/authorization/fail` API has some parameters.
+ Among them, it is `action` parameter that the authorization server implementation should check first because
+ it denotes the next action that the authorization server implementation should take.
+ According to the value of `action`, the authorization server implementation must take the steps described below.
+
+ ## INTERNAL_SERVER_ERROR
+
+ When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization
+ server implementation was wrong or that an error occurred in Authlete.
+ In either case, from the viewpoint of the client application, it is an error on the server side.
+ Therefore, the service implementation should generate a response to the client application with
+ HTTP status of "500 Internal Server Error". Authlete recommends `application/json` as the content type.
+ The value of `responseContent` is a JSON string which describes the error, so it can be used
+ as the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the service implementation should generate and return
+ to the client application.
+ ```
+ HTTP/1.1 500 Internal Server Error
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+ The endpoint implementation may return another different response to the client application since
+ "500 Internal Server Error" is not required by OAuth 2.0.
+
+ ## BAD_REQUEST
+
+ When the value of `action` is `BAD_REQUEST`, it means that the ticket is no longer valid (deleted
+ or expired) and that the reason of the invalidity was probably due to the end-user's too-delayed
+ response to the authorization UI.
+ A response with HTTP status of "400 Bad Request" should be returned to the client application and
+ Authlete recommends `application/json` as the content type.
+ The value of `responseContent` is a JSON string which describes the error, so it can be used
+ as the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the service implementation should generate and return
+ to the client application.
+ ```
+ HTTP/1.1 400 Bad Request
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+ The endpoint implementation may return another different response to the client application since
+ "400 Bad Request" is not required by OAuth 2.0.
+
+ ## LOCATION
+
+ When the value of `action` is `LOCATION`, it means that the response to the client application must
+ be "302 Found" with Location header.
+ The parameter responseContent contains a redirect URI with (1) an authorization code, an ID token
+ and/or an access token (on success) or (2) an error code (on failure), so it can be used as the
+ value of `Location` header.
+
+ ---
+
+ The following illustrates the response which the service implementation must generate and return
+ to the client application.
+ ```
+ HTTP/1.1 302 Found
+ Location: {responseContent}
+ Cache-Control: no-store
+ Pragma: no-cache
+ ```
+
+ ## FORM
+
+ When the value of `action` is `FORM`, it means that the response to the client application must be 200 OK
+ with an HTML which triggers redirection by JavaScript.
+ This happens when the authorization request from the client application contained `response_mode=form_post`.
+ The value of `responseContent` is an HTML which can be used as the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the service implementation must generate and return
+ to the client application.
+ ```
+ HTTP/1.1 200 OK
+ Content-Type: text/html;charset=UTF-8
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
- This API is supposed to be called from within the implementation of the authorization endpoint of the service
- in order to generate an error response to the client application.
- The description of the `/auth/authorization` API describes the timing when this API should be called.
- The response from `/auth/authorization/fail` API has some parameters.
- Among them, it is `action` parameter that the authorization server implementation should check first because
- it denotes the next action that the authorization server implementation should take.
- According to the value of `action`, the authorization server implementation must take the steps described below.
-
- ## INTERNAL_SERVER_ERROR
-
- When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization
- server implementation was wrong or that an error occurred in Authlete.
- In either case, from the viewpoint of the client application, it is an error on the server side.
- Therefore, the service implementation should generate a response to the client application with
- HTTP status of "500 Internal Server Error". Authlete recommends `application/json` as the content type.
- The value of `responseContent` is a JSON string which describes the error, so it can be used
- as the entity body of the response.
-
- ---
-
- The following illustrates the response which the service implementation should generate and return
- to the client application.
- ```
- HTTP/1.1 500 Internal Server Error
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
- The endpoint implementation may return another different response to the client application since
- "500 Internal Server Error" is not required by OAuth 2.0.
-
- ## BAD_REQUEST
-
- When the value of `action` is `BAD_REQUEST`, it means that the ticket is no longer valid (deleted
- or expired) and that the reason of the invalidity was probably due to the end-user's too-delayed
- response to the authorization UI.
- A response with HTTP status of "400 Bad Request" should be returned to the client application and
- Authlete recommends `application/json` as the content type.
- The value of `responseContent` is a JSON string which describes the error, so it can be used
- as the entity body of the response.
-
- ---
-
- The following illustrates the response which the service implementation should generate and return
- to the client application.
- ```
- HTTP/1.1 400 Bad Request
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
- The endpoint implementation may return another different response to the client application since
- "400 Bad Request" is not required by OAuth 2.0.
-
- ## LOCATION
-
- When the value of `action` is `LOCATION`, it means that the response to the client application must
- be "302 Found" with Location header.
- The parameter responseContent contains a redirect URI with (1) an authorization code, an ID token
- and/or an access token (on success) or (2) an error code (on failure), so it can be used as the
- value of `Location` header.
-
- ---
-
- The following illustrates the response which the service implementation must generate and return
- to the client application.
- ```
- HTTP/1.1 302 Found
- Location: {responseContent}
- Cache-Control: no-store
- Pragma: no-cache
- ```
-
- ## FORM
-
- When the value of `action` is `FORM`, it means that the response to the client application must be 200 OK
- with an HTML which triggers redirection by JavaScript.
- This happens when the authorization request from the client application contained `response_mode=form_post`.
- The value of `responseContent` is an HTML which can be used as the entity body of the response.
-
- ---
-
- The following illustrates the response which the service implementation must generate and return
- to the client application.
- ```
- HTTP/1.1 200 OK
- Content-Type: text/html;charset=UTF-8
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
parameters:
- in: path
name: serviceId
@@ -3331,104 +3349,110 @@ paths:
description: |
This API parses request parameters of an authorization request and returns necessary data for the
authorization server implementation to process the authorization request further.
+ x-mint:
+ metadata:
+ description: "This API parses request parameters of an authorization request and returns necessary data for the authorization server implementation to process the authorization request further."
+ content: |
+
+ This API is supposed to be called from within the implementation of the authorization endpoint of
+ the service in order to generate a successful response to the client application.
+ The description of the `/auth/authorization` API describes the timing when this API should be called
+ and the meaning of request parameters. See [ISSUE] in `NO_INTERACTION`.
+ The response from `/auth/authorization/issue` API has some parameters.
+ Among them, it is `action` parameter that the authorization server implementation should check first
+ because it denotes the next action that the authorization server implementation should take.
+ According to the value of `action`, the authorization server implementation must take the steps
+ described below.
+
+ ## INTERNAL_SERVER_ERROR
+
+ When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization
+ server implementation was wrong or that an error occurred in Authlete.
+ In either case, from the viewpoint of the client application, it is an error on the server side.
+ Therefore, the service implementation should generate a response to the client application with
+ HTTP status of "500 Internal Server Error".
+ The value of `responseContent` is a JSON string which describes the error, so it can be used as
+ the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the service implementation should generate and return
+ to the client application.
+ ```
+ HTTP/1.1 500 Internal Server Error
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+ The endpoint implementation may return another different response to the client application since
+ "500 Internal Server Error" is not required by OAuth 2.0.
+
+ ## BAD_REQUEST
+
+ When the value of "action" is `BAD_REQUEST`, it means that the ticket is no longer valid (deleted
+ or expired) and that the reason of the invalidity was probably due to the end-user's too-delayed
+ response to the authorization UI.
+ The HTTP status of the response returned to the client application should be "400 Bad Request"
+ and the content type should be `application/json` although OAuth 2.0 specification does not mention
+ the format of the error response.
+ The value of `responseContent` is a JSON string which describes the error, so it can be used as
+ the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the service implementation should generate and return
+ to the client application.
+ ```
+ HTTP/1.1 400 Bad Request
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+ The endpoint implementation may return another different response to the client application since
+ "400 Bad Request" is not required by OAuth 2.0.
+
+ ## LOCATION
+
+ When the value of `action` is `LOCATION`, it means that the response to the client application
+ should be "302 Found" with `Location` header.
+ The value of `responseContent` is a redirect URI which contains (1) an authorization code, an ID
+ token and/or an access token (on success) or (2) an error code (on failure), so it can be used as
+ the value of `Location` header.
+
+ ---
+
+ The following illustrates the response which the service implementation must generate and return
+ to the client application.
+ ```
+ HTTP/1.1 302 Found
+ Location: {responseContent}
+ Cache-Control: no-store
+ Pragma: no-cache
+ ```
+
+ ## FORM
+
+ When the value of `action` is `FORM`, it means that the response to the client application should
+ be "200 OK" with an HTML which triggers redirection by JavaScript. This happens when the authorization
+ request from the client contains `response_mode=form_post` request parameter.
+ The value of `responseContent` is an HTML which satisfies the requirements of `response_mode=form_post`,
+ so it can be used as the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the service implementation should generate and return
+ to the client application.
+ ```
+ HTTP/1.1 200 OK
+ Content-Type: text/html;charset=UTF-8
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
- This API is supposed to be called from within the implementation of the authorization endpoint of
- the service in order to generate a successful response to the client application.
- The description of the `/auth/authorization` API describes the timing when this API should be called
- and the meaning of request parameters. See [ISSUE] in `NO_INTERACTION`.
- The response from `/auth/authorization/issue` API has some parameters.
- Among them, it is `action` parameter that the authorization server implementation should check first
- because it denotes the next action that the authorization server implementation should take.
- According to the value of `action`, the authorization server implementation must take the steps
- described below.
-
- ## INTERNAL_SERVER_ERROR
-
- When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization
- server implementation was wrong or that an error occurred in Authlete.
- In either case, from the viewpoint of the client application, it is an error on the server side.
- Therefore, the service implementation should generate a response to the client application with
- HTTP status of "500 Internal Server Error".
- The value of `responseContent` is a JSON string which describes the error, so it can be used as
- the entity body of the response.
-
- ---
-
- The following illustrates the response which the service implementation should generate and return
- to the client application.
- ```
- HTTP/1.1 500 Internal Server Error
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
- The endpoint implementation may return another different response to the client application since
- "500 Internal Server Error" is not required by OAuth 2.0.
-
- ## BAD_REQUEST
-
- When the value of "action" is `BAD_REQUEST`, it means that the ticket is no longer valid (deleted
- or expired) and that the reason of the invalidity was probably due to the end-user's too-delayed
- response to the authorization UI.
- The HTTP status of the response returned to the client application should be "400 Bad Request"
- and the content type should be `application/json` although OAuth 2.0 specification does not mention
- the format of the error response.
- The value of `responseContent` is a JSON string which describes the error, so it can be used as
- the entity body of the response.
-
- ---
-
- The following illustrates the response which the service implementation should generate and return
- to the client application.
- ```
- HTTP/1.1 400 Bad Request
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
- The endpoint implementation may return another different response to the client application since
- "400 Bad Request" is not required by OAuth 2.0.
-
- ## LOCATION
-
- When the value of `action` is `LOCATION`, it means that the response to the client application
- should be "302 Found" with `Location` header.
- The value of `responseContent` is a redirect URI which contains (1) an authorization code, an ID
- token and/or an access token (on success) or (2) an error code (on failure), so it can be used as
- the value of `Location` header.
-
- ---
-
- The following illustrates the response which the service implementation must generate and return
- to the client application.
- ```
- HTTP/1.1 302 Found
- Location: {responseContent}
- Cache-Control: no-store
- Pragma: no-cache
- ```
-
- ## FORM
-
- When the value of `action` is `FORM`, it means that the response to the client application should
- be "200 OK" with an HTML which triggers redirection by JavaScript. This happens when the authorization
- request from the client contains `response_mode=form_post` request parameter.
- The value of `responseContent` is an HTML which satisfies the requirements of `response_mode=form_post`,
- so it can be used as the entity body of the response.
-
- ---
-
- The following illustrates the response which the service implementation should generate and return
- to the client application.
- ```
- HTTP/1.1 200 OK
- Content-Type: text/html;charset=UTF-8
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
parameters:
- in: path
name: serviceId
@@ -3593,393 +3617,399 @@ paths:
description: |
This API parses request parameters of an authorization request and returns necessary data for the
authorization server implementation to process the authorization request further.
+ x-mint:
+ metadata:
+ description: "This API parses request parameters of an authorization request and returns necessary data for the authorization server implementation to process the authorization request further."
+ content: |
+
+ This API is supposed to be called from with the implementation of the token endpoint of the service.
+ The endpoint implementation must extract the request parameters from the token request from the
+ client application and pass them as the value of parameters request parameter to Authlete's `/auth/token` API.
+ The value of parameters is the entire entity body (which is formatted in `application/x-www-form-urlencoded`)
+ of the token request.
+ In addition, if the token endpoint of the authorization server implementation supports basic authentication
+ as a means of [client authentication](https://datatracker.ietf.org/doc/html/rfc6749#section-2.3),
+ the client credentials must be extracted from `Authorization` header and they must be passed as
+ `clientId` request parameter and `clientSecret` request parameter to Authlete's `/auth/token` API.
+ The following code snippet is an example in JAX-RS showing how to extract request parameters from
+ the token request and client credentials from Authorization header.
+ ```java
+ @POST
+ @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
+ public Response post(
+ @HeaderParam(HttpHeaders.AUTHORIZATION) String auth,
+ String parameters)
+ {
+ // Convert the value of Authorization header (credentials of
+ // the client application), if any, into BasicCredentials.
+ BasicCredentials credentials = BasicCredentials.parse(auth);
+ // The credentials of the client application extracted from
+ // 'Authorization' header. These may be null.
+ String clientId = credentials == null ? null
+ : credentials.getUserId();
+ String clientSecret = credentials == null ? null
+ : credentials.getPassword();
+ // Process the given parameters.
+ return process(parameters, clientId, clientSecret);
+ }
+ ```
+ The response from `/auth/token` API has some parameters. Among them, it is action parameter that
+ the service implementation should check first because it denotes the next action that the authorization
+ server implementation should take. According to the value of action, the authorization server
+ implementation must take the steps described below.
+
+ ## INTERNAL_SERVER_ERROR
+
+ When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization
+ server implementation was wrong or that an error occurred in Authlete.
+ In either case, from the viewpoint of the client application, it is an error on the server side.
+ Therefore, the service implementation should generate a response to the client application with
+ HTTP status of "500 Internal Server Error". Authlete recommends `application/json` as the content
+ type although OAuth 2.0 specification does not mention the format of the error response when the
+ redirect URI is not usable.
+ The value of `responseContent` is a JSON string which describes the error, so it can be
+ used as the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the service implementation should generate and return
+ to the client application.
+ ```
+ HTTP/1.1 500 Internal Server Error
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+ The endpoint implementation may return another different response to the client application
+ since "500 Internal Server Error" is not required by OAuth 2.0.
+
+ ## INVALID_CLIENT
+
+ When the value of `action` is `INVALID_CLIENT`, it means that authentication of the client failed.
+ In this case, the HTTP status of the response to the client application is either "400 Bad Request"
+ or "401 Unauthorized". This requirement comes from [RFC 6749, 5.2. Error Response](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2).
+ The description about `invalid_client` shown below is an excerpt from RFC 6749.
+
+ ---
+
+ Client authentication failed (e.g., unknown client, no client authentication included, or unsupported
+ authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code
+ to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate
+ via the `Authorization` request header field, the authorization server MUST respond with an HTTP
+ 401 (Unauthorized) status code and include the `WWW-Authenticate` response header field matching
+ the authentication scheme used by the client.
+
+ ---
+
+ In either case, the value of `responseContent` is a JSON string which can be used as the entity
+ body of the response to the client application.
+
+ ---
+
+ The following illustrate responses which the service implementation must generate and return to
+ the client application.
+
+ ```
+ HTTP/1.1 400 Bad Request
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
+ ```
+ HTTP/1.1 401 Unauthorized
+ WWW-Authenticate: {challenge}
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
+ ## BAD_REQUEST
+
+ When the value of `action` is `BAD_REQUEST`, it means that the request from the client application
+ is invalid.
+ A response with HTTP status of "400 Bad Request" must be returned to the client application and
+ the content type must be `application/json`.
+ The value of `responseContent` is a JSON string which describes the error, so it can be used as
+ the entity body of the response.
+
+ The following illustrates the response which the service implementation should generate and return
+ to the client application.
+
+ ```
+ HTTP/1.1 400 Bad Request
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
+ ## PASSWORD
+
+ When the value of `"action"` is `"PASSWORD"`, it means that
+ the request from the client application is valid and `grant_type`
+ is `"password"`. That is, the flow is
+ ["Resource Owner
+ Password Credentials"](https://www.rfc-editor.org/rfc/rfc6749.html#section-4.3).
+ In this case, {@link #getUsername()} returns the value of `"username"`
+ request parameter and {@link #getPassword()} returns the value of {@code
+ "password"} request parameter which were contained in the token request
+ from the client application. The service implementation must validate the
+ credentials of the resource owner (= end-user) and take either of the
+ actions below according to the validation result.
+ 1. When the credentials are valid, call Authlete's /auth/token/issue} API to generate an access token for the client
+ application. The API requires `"ticket"` request parameter and
+ `"subject"` request parameter.
+ Use the value returned from {@link #getTicket()} method as the value
+ for `"ticket"` parameter.
+ 2. The response from `/auth/token/issue` API ({@link
+ TokenIssueResponse}) contains data (an access token and others)
+ which should be returned to the client application. Use the data
+ to generate a response to the client application.
+ 3. When the credentials are invalid, call Authlete's {@code
+ /auth/token/fail} API with `reason=`{@link
+ TokenFailRequest.Reason#INVALID_RESOURCE_OWNER_CREDENTIALS
+ INVALID_RESOURCE_OWNER_CREDENTIALS} to generate an error response
+ for the client application. The API requires `"ticket"`
+ request parameter. Use the value returned from {@link #getTicket()}
+ method as the value for `"ticket"` parameter.
+ 4. The response from `/auth/token/fail` API ({@link
+ TokenFailResponse}) contains error information which should be
+ returned to the client application. Use it to generate a response
+ to the client application.
+
+ ## OK
+
+ When the value of `action` is `OK`, it means that the request from the client application is valid
+ and an access token, and optionally an ID token, is ready to be issued.
+ The HTTP status of the response returned to the client application must be "200 OK" and the content
+ type must be `application/json`.
+ The value of `responseContent` is a JSON string which contains an access token (and optionally
+ an ID token), so it can be used as the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the service implementation must generate and return
+ to the client application.
+ ```
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
+ ## TOKEN_EXCHANGE (Authlete 2.3 onwards)
+
+ When the value of `"action"` is `"TOKEN_EXCHANGE"`, it means
+ that the request from the client application is a valid token exchange
+ request (cf. [RFC
+ 8693 OAuth 2.0 Token Exchange](https://www.rfc-editor.org/rfc/rfc8693.html)) and that the request has already passed
+ the following validation steps.
+ 1. Confirm that the value of the `requested_token_type` request parameter
+ is one of the registered token type identifiers if the request parameter is
+ given and its value is not empty.
+ 2. Confirm that the `subject_token` request parameter is given and its
+ value is not empty.
+ 3. Confirm that the `subject_token_type` request parameter is given and
+ its value is one of the registered token type identifiers.
+ 4. Confirm that the `actor_token_type` request parameter is given and
+ its value is one of the registered token type identifiers if the
+ `actor_token` request parameter is given and its value is not empty.
+ 5. Confirm that the `actor_token_type` request parameter is not given
+ or its value is empty when the `actor_token` request parameter is
+ not given or its value is empty.
+ Furthermore, Authlete performs additional validation on the tokens specified
+ by the `subject_token` request parameter and the `actor_token`
+ request parameter according to their respective token types as shown below.
+
+ ## Token Validation Steps
+ \*Token Type: `urn:ietf:params:oauth:token-type:jwt`\*
+ 1. Confirm that the format conforms to the JWT specification [RFC 7519][https://www.rfc-editor.org/rfc/rfc7519.html].
+ 2. Check if the JWT is encrypted and if it is encrypted, then (a) reject
+ the token exchange request when the {@link
+ Service#isTokenExchangeEncryptedJwtRejected()
+ tokenExchangeEncryptedJwtRejected} flag of the service is `true`
+ or (b) skip remaining validation steps when the flag is `false`.
+ Note that Authlete does not verify an encrypted JWT because there is
+ no standard way to obtain the key to decrypt the JWT with. This means
+ that you must verify an encrypted JWT by yourself when one is used as
+ an input token with the token type
+ { @code "urn:ietf:params:oauth:token-type:jwt" }.
+ 3. Confirm that the current time has not reached the time indicated by
+ the `exp` claim if the JWT contains the claim.
+ 4. Confirm that the current time is equal to or after the time indicated
+ by the `iat` claim if the JWT contains the claim.
+ 5.Confirm that the current time is equal to or after the time indicated
+ by the `nbf` claim if the JWT contains the claim.
+ 6. Check if the JWT is signed and if it is not signed, then (a) reject
+ the token exchange request when the {@link
+ Service#isTokenExchangeUnsignedJwtRejected()
+ tokenExchangeUnsignedJwtRejected} flag of the service is `true`
+ or (b) finish validation on the input token. Note that Authlete does
+ not verify the signature of the JWT because there is no standard way
+ to obtain the key to verify the signature of a JWT with. This means
+ that you must verify the signature by yourself when a signed JWT is
+ used as an input token with the token type
+ `"urn:ietf:params:oauth:token-type:jwt"`.
+ \*Token Type: `urn:ietf:params:oauth:token-type:access_token`\*
+ 1. Confirm that the token is an access token that has been issued by
+ the Authlete server of your service. This implies that access
+ tokens issued by other systems cannot be used as a subject token
+ or an actor token with the token type
+ `urn:ietf:params:oauth:token-type:access_token`.
+ 2. Confirm that the access token has not expired.
+ 3. Confirm that the access token belongs to the service.
+ \*Token Type: `urn:ietf:params:oauth:token-type:refresh_token`\*
+ 1. Confirm that the token is a refresh token that has been issued by
+ the Authlete server of your service. This implies that refresh
+ tokens issued by other systems cannot be used as a subject token
+ or an actor token with the token type
+ `urn:ietf:params:oauth:token-type:refresh_token`.
+ 2. Confirm that the refresh token has not expired.
+ 3. Confirm that the refresh token belongs to the service.
+ \*Token Type: `urn:ietf:params:oauth:token-type:id_token`\*
+ 1. Confirm that the format conforms to the JWT specification ([RFC 7519](https://www.rfc-editor.org/rfc/rfc7519.html)).
+ 2. Check if the ID Token is encrypted and if it is encrypted, then (a)
+ reject the token exchange request when the {@link
+ Service#isTokenExchangeEncryptedJwtRejected()
+ tokenExchangeEncryptedJwtRejected} flag of the service is `true`
+ or (b) skip remaining validation steps when the flag is `false`.
+ Note that Authlete does not verify an encrypted ID Token because
+ there is no standard way to obtain the key to decrypt the ID Token
+ with in the context of token exchange where the client ID for the
+ encrypted ID Token cannot be determined. This means that you must
+ verify an encrypted ID Token by yourself when one is used as an
+ input token with the token type
+ `"urn:ietf:params:oauth:token-type:id_token"`.
+ 3. Confirm that the ID Token contains the `exp` claim and the
+ current time has not reached the time indicated by the claim.
+ 4. Confirm that the ID Token contains the `iat` claim and the
+ current time is equal to or after the time indicated by the claim.
+ 5. Confirm that the current time is equal to or after the time indicated
+ by the `nbf` claim if the ID Token contains the claim.
+ 6. Confirm that the ID Token contains the `iss` claim and the
+ value is a valid URI. In addition, confirm that the URI has the
+ `https` scheme, no query component and no fragment component.
+ 7. Confirm that the ID Token contains the `aud` claim and its
+ value is a JSON string or an array of JSON strings.
+ 8. Confirm that the value of the `nonce` claim is a JSON string
+ if the ID Token contains the claim.
+ 9. Check if the ID Token is signed and if it is not signed, then (a)
+ reject the token exchange request when the {@link
+ Service#isTokenExchangeUnsignedJwtRejected()
+ tokenExchangeUnsignedJwtRejected} flag of the service is `true`
+ or (b) finish validation on the input token.
+ 10. Confirm that the signature algorithm is asymmetric. This implies that
+ ID Tokens whose signature algorithm is symmetric (`HS256`,
+ `HS384` or `HS512`) cannot be used as a subject token or
+ an actor token with the token type
+ `urn:ietf:params:oauth:token-type:id_token`.
+ 11. Verify the signature of the ID Token. Signature verification is
+ performed even in the case where the issuer of the ID Token is not
+ your service. But in that case, the issuer must support the discovery
+ endpoint defined in [OpenID
+ Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html). Otherwise, signature verification fails.
+ \*Token Type: `urn:ietf:params:oauth:token-type:saml1`\*
+ (Authlete does not perform any validation for this token type.)
+ \*Token Type: `urn:ietf:params:oauth:token-type:saml2`\*
+ (Authlete does not perform any validation for this token type.)
+ The specification of Token Exchange ([RFC 8693](https://www.rfc-editor.org/rfc/rfc8693.html)) is very
+ flexible. In other words, the specification has abandoned the task of
+ determining details. Therefore, for secure token exchange, you have
+ to complement the specification with your own rules. For that purpose,
+ Authlete provides some configuration options as listed below.
+ Authorization server implementers may utilize them and/or implement
+ their own rules.
+ In the case of {@link Action#TOKEN_EXCHANGE TOKEN_EXCHANGE}, the {@link
+ #getResponseContent()} method returns `null`. You have to construct
+ the token response by yourself.
+ For example, you may generate an access token by calling Authlete's
+ `/api/auth/token/create` API and construct a token response like
+ below.
+ ```
+ HTTP/1.1 401 Unauthorized
+ WWW-Authenticate: {challenge}
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+ ```
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+ Cache-Control: no-cache, no-store
+ {
+ "access_token": "{@link TokenCreateResponse#getAccessToken()}",
+ "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
+ "token_type": "Bearer",
+ "expires_in": { @link TokenCreateResponse#getExpiresIn() },
+ "scope": "String.join(" ", {@link TokenCreateResponse#getScopes()})"
+ }
+ ```
+
+ ## JWT_BEARER JWT_BEARER (Authlete 2.3 onwards)
+
+ When the value of `"action"` is `"JWT_BEARER"`, it means that
+ the request from the client application is a valid token request with the
+ grant type `"urn:ietf:params:oauth:grant-type:jwt-bearer"` ([RFC 7523 JSON Web Token (JWT)
+ Profile for OAuth 2.0 Client Authentication and Authorization Grants](https://www.rfc-editor.org/rfc/rfc7523.html))
+ and that the request has already passed the following validation steps.
+ 1. Confirm that the `assertion` request parameter is given and its value
+ is not empty.
+ 2. Confirm that the format of the assertion conforms to the JWT specification
+ ([RFC 7519](https://www.rfc-editor.org/rfc/rfc7519.html)).
+ 3. Check if the JWT is encrypted and if it is encrypted, then (a) reject the
+ token request when the {@link Service#isJwtGrantEncryptedJwtRejected()
+ jwtGrantEncryptedJwtRejected} flag of the service is `true` or (b)
+ skip remaining validation steps when the flag is `false`. Note that
+ Authlete does not verify an encrypted JWT because there is no standard way
+ to obtain the key to decrypt the JWT with. This means that you must verify
+ an encrypted JWT by yourself.
+ 4. Confirm that the JWT contains the `iss` claim and its value is a
+ JSON string.
+ 5. Confirm that the JWT contains the `sub` claim and its value is a
+ JSON string.
+ 6. Confirm that the JWT contains the `aud` claim and its value is
+ either a JSON string or an array of JSON strings.
+ 7. Confirm that the issuer identifier of the service (cf. {@link Service#getIssuer()})
+ or the URL of the token endpoint (cf. {@link Service#getTokenEndpoint()})
+ is listed as audience in the `aud` claim.
+ 8. Confirm that the JWT contains the `exp` claim and the current time
+ has not reached the time indicated by the claim.
+ 9. Confirm that the current time is equal to or after the time indicated by
+ by the `iat` claim if the JWT contains the claim.
+ 10. Confirm that the current time is equal to or after the time indicated by
+ by the `nbf` claim if the JWT contains the claim.
+ 11. Check if the JWT is signed and if it is not signed, then (a) reject the
+ token request when the {@link Service#isJwtGrantUnsignedJwtRejected()
+ jwtGrantUnsignedJwtRejected} flag of the service is `true` or (b)
+ finish validation on the JWT. Note that Authlete does not verify the
+ signature of the JWT because there is no standard way to obtain the key
+ to verify the signature of a JWT with. This means that you must verify
+ the signature by yourself.
+ Authlete provides some configuration options for the grant type as listed
+ below. Authorization server implementers may utilize them and/or implement
+ their own rules.
+ ```
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+ Cache-Control: no-cache, no-store
+ {
+ "access_token": "{@link TokenCreateResponse#getAccessToken()}",
+ "token_type": "Bearer",
+ "expires_in": {@link TokenCreateResponse#getExpiresIn()},
+ "scope": "String.join(" ", {@link TokenCreateResponse#getScopes()})"
+ }
+ ```
+ Finally, note again that Authlete does not verify the signature of the JWT
+ specified by the `assertion` request parameter. You must verify the
+ signature by yourself.
+
- This API is supposed to be called from with the implementation of the token endpoint of the service.
- The endpoint implementation must extract the request parameters from the token request from the
- client application and pass them as the value of parameters request parameter to Authlete's `/auth/token` API.
- The value of parameters is the entire entity body (which is formatted in `application/x-www-form-urlencoded`)
- of the token request.
- In addition, if the token endpoint of the authorization server implementation supports basic authentication
- as a means of [client authentication](https://datatracker.ietf.org/doc/html/rfc6749#section-2.3),
- the client credentials must be extracted from `Authorization` header and they must be passed as
- `clientId` request parameter and `clientSecret` request parameter to Authlete's `/auth/token` API.
- The following code snippet is an example in JAX-RS showing how to extract request parameters from
- the token request and client credentials from Authorization header.
- ```java
- @POST
- @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
- public Response post(
- @HeaderParam(HttpHeaders.AUTHORIZATION) String auth,
- String parameters)
- {
- // Convert the value of Authorization header (credentials of
- // the client application), if any, into BasicCredentials.
- BasicCredentials credentials = BasicCredentials.parse(auth);
- // The credentials of the client application extracted from
- // 'Authorization' header. These may be null.
- String clientId = credentials == null ? null
- : credentials.getUserId();
- String clientSecret = credentials == null ? null
- : credentials.getPassword();
- // Process the given parameters.
- return process(parameters, clientId, clientSecret);
- }
- ```
- The response from `/auth/token` API has some parameters. Among them, it is action parameter that
- the service implementation should check first because it denotes the next action that the authorization
- server implementation should take. According to the value of action, the authorization server
- implementation must take the steps described below.
-
- ## INTERNAL_SERVER_ERROR
-
- When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization
- server implementation was wrong or that an error occurred in Authlete.
- In either case, from the viewpoint of the client application, it is an error on the server side.
- Therefore, the service implementation should generate a response to the client application with
- HTTP status of "500 Internal Server Error". Authlete recommends `application/json` as the content
- type although OAuth 2.0 specification does not mention the format of the error response when the
- redirect URI is not usable.
- The value of `responseContent` is a JSON string which describes the error, so it can be
- used as the entity body of the response.
-
- ---
-
- The following illustrates the response which the service implementation should generate and return
- to the client application.
- ```
- HTTP/1.1 500 Internal Server Error
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
- The endpoint implementation may return another different response to the client application
- since "500 Internal Server Error" is not required by OAuth 2.0.
-
- ## INVALID_CLIENT
-
- When the value of `action` is `INVALID_CLIENT`, it means that authentication of the client failed.
- In this case, the HTTP status of the response to the client application is either "400 Bad Request"
- or "401 Unauthorized". This requirement comes from [RFC 6749, 5.2. Error Response](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2).
- The description about `invalid_client` shown below is an excerpt from RFC 6749.
-
- ---
-
- Client authentication failed (e.g., unknown client, no client authentication included, or unsupported
- authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code
- to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate
- via the `Authorization` request header field, the authorization server MUST respond with an HTTP
- 401 (Unauthorized) status code and include the `WWW-Authenticate` response header field matching
- the authentication scheme used by the client.
-
- ---
-
- In either case, the value of `responseContent` is a JSON string which can be used as the entity
- body of the response to the client application.
-
- ---
-
- The following illustrate responses which the service implementation must generate and return to
- the client application.
-
- ```
- HTTP/1.1 400 Bad Request
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
-
- ```
- HTTP/1.1 401 Unauthorized
- WWW-Authenticate: {challenge}
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
-
- ## BAD_REQUEST
-
- When the value of `action` is `BAD_REQUEST`, it means that the request from the client application
- is invalid.
- A response with HTTP status of "400 Bad Request" must be returned to the client application and
- the content type must be `application/json`.
- The value of `responseContent` is a JSON string which describes the error, so it can be used as
- the entity body of the response.
-
- The following illustrates the response which the service implementation should generate and return
- to the client application.
-
- ```
- HTTP/1.1 400 Bad Request
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
-
- ## PASSWORD
-
- When the value of `"action"` is `"PASSWORD"`, it means that
- the request from the client application is valid and `grant_type`
- is `"password"`. That is, the flow is
- ["Resource Owner
- Password Credentials"](https://www.rfc-editor.org/rfc/rfc6749.html#section-4.3).
- In this case, {@link #getUsername()} returns the value of `"username"`
- request parameter and {@link #getPassword()} returns the value of {@code
- "password"} request parameter which were contained in the token request
- from the client application. The service implementation must validate the
- credentials of the resource owner (= end-user) and take either of the
- actions below according to the validation result.
- 1. When the credentials are valid, call Authlete's /auth/token/issue} API to generate an access token for the client
- application. The API requires `"ticket"` request parameter and
- `"subject"` request parameter.
- Use the value returned from {@link #getTicket()} method as the value
- for `"ticket"` parameter.
- 2. The response from `/auth/token/issue` API ({@link
- TokenIssueResponse}) contains data (an access token and others)
- which should be returned to the client application. Use the data
- to generate a response to the client application.
- 3. When the credentials are invalid, call Authlete's {@code
- /auth/token/fail} API with `reason=`{@link
- TokenFailRequest.Reason#INVALID_RESOURCE_OWNER_CREDENTIALS
- INVALID_RESOURCE_OWNER_CREDENTIALS} to generate an error response
- for the client application. The API requires `"ticket"`
- request parameter. Use the value returned from {@link #getTicket()}
- method as the value for `"ticket"` parameter.
- 4. The response from `/auth/token/fail` API ({@link
- TokenFailResponse}) contains error information which should be
- returned to the client application. Use it to generate a response
- to the client application.
-
- ## OK
-
- When the value of `action` is `OK`, it means that the request from the client application is valid
- and an access token, and optionally an ID token, is ready to be issued.
- The HTTP status of the response returned to the client application must be "200 OK" and the content
- type must be `application/json`.
- The value of `responseContent` is a JSON string which contains an access token (and optionally
- an ID token), so it can be used as the entity body of the response.
-
- ---
-
- The following illustrates the response which the service implementation must generate and return
- to the client application.
- ```
- HTTP/1.1 200 OK
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
-
- ## TOKEN_EXCHANGE (Authlete 2.3 onwards)
-
- When the value of `"action"` is `"TOKEN_EXCHANGE"`, it means
- that the request from the client application is a valid token exchange
- request (cf. [RFC
- 8693 OAuth 2.0 Token Exchange](https://www.rfc-editor.org/rfc/rfc8693.html)) and that the request has already passed
- the following validation steps.
- 1. Confirm that the value of the `requested_token_type` request parameter
- is one of the registered token type identifiers if the request parameter is
- given and its value is not empty.
- 2. Confirm that the `subject_token` request parameter is given and its
- value is not empty.
- 3. Confirm that the `subject_token_type` request parameter is given and
- its value is one of the registered token type identifiers.
- 4. Confirm that the `actor_token_type` request parameter is given and
- its value is one of the registered token type identifiers if the
- `actor_token` request parameter is given and its value is not empty.
- 5. Confirm that the `actor_token_type` request parameter is not given
- or its value is empty when the `actor_token` request parameter is
- not given or its value is empty.
- Furthermore, Authlete performs additional validation on the tokens specified
- by the `subject_token` request parameter and the `actor_token`
- request parameter according to their respective token types as shown below.
-
- ## Token Validation Steps
- \*Token Type: `urn:ietf:params:oauth:token-type:jwt`\*
- 1. Confirm that the format conforms to the JWT specification [RFC 7519][https://www.rfc-editor.org/rfc/rfc7519.html].
- 2. Check if the JWT is encrypted and if it is encrypted, then (a) reject
- the token exchange request when the {@link
- Service#isTokenExchangeEncryptedJwtRejected()
- tokenExchangeEncryptedJwtRejected} flag of the service is `true`
- or (b) skip remaining validation steps when the flag is `false`.
- Note that Authlete does not verify an encrypted JWT because there is
- no standard way to obtain the key to decrypt the JWT with. This means
- that you must verify an encrypted JWT by yourself when one is used as
- an input token with the token type
- { @code "urn:ietf:params:oauth:token-type:jwt" }.
- 3. Confirm that the current time has not reached the time indicated by
- the `exp` claim if the JWT contains the claim.
- 4. Confirm that the current time is equal to or after the time indicated
- by the `iat` claim if the JWT contains the claim.
- 5.Confirm that the current time is equal to or after the time indicated
- by the `nbf` claim if the JWT contains the claim.
- 6. Check if the JWT is signed and if it is not signed, then (a) reject
- the token exchange request when the {@link
- Service#isTokenExchangeUnsignedJwtRejected()
- tokenExchangeUnsignedJwtRejected} flag of the service is `true`
- or (b) finish validation on the input token. Note that Authlete does
- not verify the signature of the JWT because there is no standard way
- to obtain the key to verify the signature of a JWT with. This means
- that you must verify the signature by yourself when a signed JWT is
- used as an input token with the token type
- `"urn:ietf:params:oauth:token-type:jwt"`.
- \*Token Type: `urn:ietf:params:oauth:token-type:access_token`\*
- 1. Confirm that the token is an access token that has been issued by
- the Authlete server of your service. This implies that access
- tokens issued by other systems cannot be used as a subject token
- or an actor token with the token type
- `urn:ietf:params:oauth:token-type:access_token`.
- 2. Confirm that the access token has not expired.
- 3. Confirm that the access token belongs to the service.
- \*Token Type: `urn:ietf:params:oauth:token-type:refresh_token`\*
- 1. Confirm that the token is a refresh token that has been issued by
- the Authlete server of your service. This implies that refresh
- tokens issued by other systems cannot be used as a subject token
- or an actor token with the token type
- `urn:ietf:params:oauth:token-type:refresh_token`.
- 2. Confirm that the refresh token has not expired.
- 3. Confirm that the refresh token belongs to the service.
- \*Token Type: `urn:ietf:params:oauth:token-type:id_token`\*
- 1. Confirm that the format conforms to the JWT specification ([RFC 7519](https://www.rfc-editor.org/rfc/rfc7519.html)).
- 2. Check if the ID Token is encrypted and if it is encrypted, then (a)
- reject the token exchange request when the {@link
- Service#isTokenExchangeEncryptedJwtRejected()
- tokenExchangeEncryptedJwtRejected} flag of the service is `true`
- or (b) skip remaining validation steps when the flag is `false`.
- Note that Authlete does not verify an encrypted ID Token because
- there is no standard way to obtain the key to decrypt the ID Token
- with in the context of token exchange where the client ID for the
- encrypted ID Token cannot be determined. This means that you must
- verify an encrypted ID Token by yourself when one is used as an
- input token with the token type
- `"urn:ietf:params:oauth:token-type:id_token"`.
- 3. Confirm that the ID Token contains the `exp` claim and the
- current time has not reached the time indicated by the claim.
- 4. Confirm that the ID Token contains the `iat` claim and the
- current time is equal to or after the time indicated by the claim.
- 5. Confirm that the current time is equal to or after the time indicated
- by the `nbf` claim if the ID Token contains the claim.
- 6. Confirm that the ID Token contains the `iss` claim and the
- value is a valid URI. In addition, confirm that the URI has the
- `https` scheme, no query component and no fragment component.
- 7. Confirm that the ID Token contains the `aud` claim and its
- value is a JSON string or an array of JSON strings.
- 8. Confirm that the value of the `nonce` claim is a JSON string
- if the ID Token contains the claim.
- 9. Check if the ID Token is signed and if it is not signed, then (a)
- reject the token exchange request when the {@link
- Service#isTokenExchangeUnsignedJwtRejected()
- tokenExchangeUnsignedJwtRejected} flag of the service is `true`
- or (b) finish validation on the input token.
- 10. Confirm that the signature algorithm is asymmetric. This implies that
- ID Tokens whose signature algorithm is symmetric (`HS256`,
- `HS384` or `HS512`) cannot be used as a subject token or
- an actor token with the token type
- `urn:ietf:params:oauth:token-type:id_token`.
- 11. Verify the signature of the ID Token. Signature verification is
- performed even in the case where the issuer of the ID Token is not
- your service. But in that case, the issuer must support the discovery
- endpoint defined in [OpenID
- Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html). Otherwise, signature verification fails.
- \*Token Type: `urn:ietf:params:oauth:token-type:saml1`\*
- (Authlete does not perform any validation for this token type.)
- \*Token Type: `urn:ietf:params:oauth:token-type:saml2`\*
- (Authlete does not perform any validation for this token type.)
- The specification of Token Exchange ([RFC 8693](https://www.rfc-editor.org/rfc/rfc8693.html)) is very
- flexible. In other words, the specification has abandoned the task of
- determining details. Therefore, for secure token exchange, you have
- to complement the specification with your own rules. For that purpose,
- Authlete provides some configuration options as listed below.
- Authorization server implementers may utilize them and/or implement
- their own rules.
- In the case of {@link Action#TOKEN_EXCHANGE TOKEN_EXCHANGE}, the {@link
- #getResponseContent()} method returns `null`. You have to construct
- the token response by yourself.
- For example, you may generate an access token by calling Authlete's
- `/api/auth/token/create` API and construct a token response like
- below.
- ```
- HTTP/1.1 401 Unauthorized
- WWW-Authenticate: {challenge}
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
- ```
- HTTP/1.1 200 OK
- Content-Type: application/json
- Cache-Control: no-cache, no-store
- {
- "access_token": "{@link TokenCreateResponse#getAccessToken()}",
- "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
- "token_type": "Bearer",
- "expires_in": { @link TokenCreateResponse#getExpiresIn() },
- "scope": "String.join(" ", {@link TokenCreateResponse#getScopes()})"
- }
- ```
-
- ## JWT_BEARER JWT_BEARER (Authlete 2.3 onwards)
-
- When the value of `"action"` is `"JWT_BEARER"`, it means that
- the request from the client application is a valid token request with the
- grant type `"urn:ietf:params:oauth:grant-type:jwt-bearer"` ([RFC 7523 JSON Web Token (JWT)
- Profile for OAuth 2.0 Client Authentication and Authorization Grants](https://www.rfc-editor.org/rfc/rfc7523.html))
- and that the request has already passed the following validation steps.
- 1. Confirm that the `assertion` request parameter is given and its value
- is not empty.
- 2. Confirm that the format of the assertion conforms to the JWT specification
- ([RFC 7519](https://www.rfc-editor.org/rfc/rfc7519.html)).
- 3. Check if the JWT is encrypted and if it is encrypted, then (a) reject the
- token request when the {@link Service#isJwtGrantEncryptedJwtRejected()
- jwtGrantEncryptedJwtRejected} flag of the service is `true` or (b)
- skip remaining validation steps when the flag is `false`. Note that
- Authlete does not verify an encrypted JWT because there is no standard way
- to obtain the key to decrypt the JWT with. This means that you must verify
- an encrypted JWT by yourself.
- 4. Confirm that the JWT contains the `iss` claim and its value is a
- JSON string.
- 5. Confirm that the JWT contains the `sub` claim and its value is a
- JSON string.
- 6. Confirm that the JWT contains the `aud` claim and its value is
- either a JSON string or an array of JSON strings.
- 7. Confirm that the issuer identifier of the service (cf. {@link Service#getIssuer()})
- or the URL of the token endpoint (cf. {@link Service#getTokenEndpoint()})
- is listed as audience in the `aud` claim.
- 8. Confirm that the JWT contains the `exp` claim and the current time
- has not reached the time indicated by the claim.
- 9. Confirm that the current time is equal to or after the time indicated by
- by the `iat` claim if the JWT contains the claim.
- 10. Confirm that the current time is equal to or after the time indicated by
- by the `nbf` claim if the JWT contains the claim.
- 11. Check if the JWT is signed and if it is not signed, then (a) reject the
- token request when the {@link Service#isJwtGrantUnsignedJwtRejected()
- jwtGrantUnsignedJwtRejected} flag of the service is `true` or (b)
- finish validation on the JWT. Note that Authlete does not verify the
- signature of the JWT because there is no standard way to obtain the key
- to verify the signature of a JWT with. This means that you must verify
- the signature by yourself.
- Authlete provides some configuration options for the grant type as listed
- below. Authorization server implementers may utilize them and/or implement
- their own rules.
- ```
- HTTP/1.1 200 OK
- Content-Type: application/json
- Cache-Control: no-cache, no-store
- {
- "access_token": "{@link TokenCreateResponse#getAccessToken()}",
- "token_type": "Bearer",
- "expires_in": {@link TokenCreateResponse#getExpiresIn()},
- "scope": "String.join(" ", {@link TokenCreateResponse#getScopes()})"
- }
- ```
- Finally, note again that Authlete does not verify the signature of the JWT
- specified by the `assertion` request parameter. You must verify the
- signature by yourself.
parameters:
- in: path
name: serviceId
@@ -4084,60 +4114,66 @@ paths:
description: |
This API generates a content of an error token response that the authorization server implementation
returns to the client application.
+ x-mint:
+ metadata:
+ description: "This API generates a content of an error token response that the authorization server implementation returns to the client application."
+ content: |
+
+ This API is supposed to be called from within the implementation of the token endpoint of the service
+ in order to generate an error response to the client application.
+ The description of the `/auth/token` API describes the timing when this API should be called. See
+ the description for the case of `action=PASSWORD`.
+ The response from `/auth/token/fail` API has some parameters. Among them, it is `action` parameter
+ that the authorization server implementation should check first because it denotes the next action
+ that the authorization server implementation should take. According to the value of `action`, the
+ authorization server implementation must take the steps described below.
+
+ ## INTERNAL_SERVER_ERROR
+
+ When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization
+ server implementation was wrong or that an error occurred in Authlete.
+ In either case, from the viewpoint of the client application, it is an error on the server side.
+ Therefore, the service implementation should generate a response to the client application with
+ HTTP status of "500 Internal Server Error".
+ The value of `responseContent` is a JSON string which describes the error, so it can be used
+ as the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the service implementation should generate and return
+ to the client application.
+ ```
+ HTTP/1.1 500 Internal Server Error
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+ The endpoint implementation may return another different response to the client application
+ since "500 Internal Server Error" is not required by OAuth 2.0.
+
+ ## BAD_REQUEST
+
+ When the value of `action` is `BAD_REQUEST`, it means that Authlete's `/auth/token/fail` API successfully
+ generated an error response for the client application.
+ The HTTP status of the response returned to the client application must be "400 Bad Request" and
+ the content type must be `application/json`.
+ The value of `responseContent` is a JSON string which describes the error, so it can be used
+ as the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the service implementation should generate and return
+ to the client application.
+ ```
+ HTTP/1.1 400 Bad Request
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
- This API is supposed to be called from within the implementation of the token endpoint of the service
- in order to generate an error response to the client application.
- The description of the `/auth/token` API describes the timing when this API should be called. See
- the description for the case of `action=PASSWORD`.
- The response from `/auth/token/fail` API has some parameters. Among them, it is `action` parameter
- that the authorization server implementation should check first because it denotes the next action
- that the authorization server implementation should take. According to the value of `action`, the
- authorization server implementation must take the steps described below.
-
- ## INTERNAL_SERVER_ERROR
-
- When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization
- server implementation was wrong or that an error occurred in Authlete.
- In either case, from the viewpoint of the client application, it is an error on the server side.
- Therefore, the service implementation should generate a response to the client application with
- HTTP status of "500 Internal Server Error".
- The value of `responseContent` is a JSON string which describes the error, so it can be used
- as the entity body of the response.
-
- ---
-
- The following illustrates the response which the service implementation should generate and return
- to the client application.
- ```
- HTTP/1.1 500 Internal Server Error
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
- The endpoint implementation may return another different response to the client application
- since "500 Internal Server Error" is not required by OAuth 2.0.
-
- ## BAD_REQUEST
-
- When the value of `action` is `BAD_REQUEST`, it means that Authlete's `/auth/token/fail` API successfully
- generated an error response for the client application.
- The HTTP status of the response returned to the client application must be "400 Bad Request" and
- the content type must be `application/json`.
- The value of `responseContent` is a JSON string which describes the error, so it can be used
- as the entity body of the response.
-
- ---
-
- The following illustrates the response which the service implementation should generate and return
- to the client application.
- ```
- HTTP/1.1 400 Bad Request
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
parameters:
- in: path
name: serviceId
@@ -4215,60 +4251,66 @@ paths:
description: |
This API generates a content of a successful token response that the authorization server implementation
returns to the client application.
+ x-mint:
+ metadata:
+ description: "This API generates a content of a successful token response that the authorization server implementation returns to the client application."
+ content: |
+
+ This API is supposed to be called from within the implementation of the token endpoint of the service
+ in order to generate a successful response to the client application.
+ The description of the `/auth/token` API describes the timing when this API should be called. See
+ the description for the case of `action=PASSWORD`.
+ The response from `/auth/token/issue` API has some parameters. Among them, it is `action` parameter
+ that the authorization server implementation should check first because it denotes the next action
+ that the authorization server implementation should take. According to the value of `action`, the
+ authorization server implementation must take the steps described below.
+
+ ## INTERNAL_SERVER_ERROR
+
+ When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization
+ server implementation was wrong or that an error occurred in Authlete.
+ In either case, from the viewpoint of the client application, it is an error on the server side.
+ Therefore, the service implementation should generate a response to the client application with
+ HTTP status of "500 Internal Server Error".
+ The value of `responseContent` is a JSON string which describes the error, so it can be used
+ as the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the service implementation should generate and return
+ to the client application.
+ ```
+ HTTP/1.1 500 Internal Server Error
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+ The endpoint implementation may return another different response to the client application
+ since "500 Internal Server Error" is not required by OAuth 2.0.
+
+ ## OK
+
+ When the value of `action` is `OK`, it means that Authlete's `/auth/token/issue` API successfully
+ generated an access token.
+ The HTTP status of the response returned to the client application must be "200 OK" and the content
+ type must be`application/json`.
+ The value of `responseContent` is a JSON string which contains an access token, so it can be used
+ as the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the service implementation must generate and return
+ to the client application.
+ ```
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
- This API is supposed to be called from within the implementation of the token endpoint of the service
- in order to generate a successful response to the client application.
- The description of the `/auth/token` API describes the timing when this API should be called. See
- the description for the case of `action=PASSWORD`.
- The response from `/auth/token/issue` API has some parameters. Among them, it is `action` parameter
- that the authorization server implementation should check first because it denotes the next action
- that the authorization server implementation should take. According to the value of `action`, the
- authorization server implementation must take the steps described below.
-
- ## INTERNAL_SERVER_ERROR
-
- When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization
- server implementation was wrong or that an error occurred in Authlete.
- In either case, from the viewpoint of the client application, it is an error on the server side.
- Therefore, the service implementation should generate a response to the client application with
- HTTP status of "500 Internal Server Error".
- The value of `responseContent` is a JSON string which describes the error, so it can be used
- as the entity body of the response.
-
- ---
-
- The following illustrates the response which the service implementation should generate and return
- to the client application.
- ```
- HTTP/1.1 500 Internal Server Error
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
- The endpoint implementation may return another different response to the client application
- since "500 Internal Server Error" is not required by OAuth 2.0.
-
- ## OK
-
- When the value of `action` is `OK`, it means that Authlete's `/auth/token/issue` API successfully
- generated an access token.
- The HTTP status of the response returned to the client application must be "200 OK" and the content
- type must be`application/json`.
- The value of `responseContent` is a JSON string which contains an access token, so it can be used
- as the entity body of the response.
-
- ---
-
- The following illustrates the response which the service implementation must generate and return
- to the client application.
- ```
- HTTP/1.1 200 OK
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
parameters:
- in: path
name: serviceId
@@ -4363,139 +4405,145 @@ paths:
summary: Process Introspection Request
description: |
This API gathers information about an access token.
+ x-mint:
+ metadata:
+ description: "This API gathers information about an access token."
+ content: |
+
+ This API is supposed to be called from within the implementations of protected resource endpoints
+ of the authorization server implementation in order to get information about the access token which
+ was presented by the client application.
+ In general, a client application accesses a protected resource endpoint of a service with an access
+ token, and the implementation of the endpoint checks whether the presented access token has enough
+ privileges (= scopes) to access the protected resource before returning the protected resource to
+ the client application. To achieve this flow, the endpoint implementation has to know detailed
+ information about the access token. Authlete `/auth/introspection` API can be used to get such information.
+ The response from `/auth/introspection` API has some parameters. Among them, it is `action` parameter
+ that the authorization server implementation should check first because it denotes the next action
+ that the authorization server implementation should take. According to the value of `action`, the
+ authorization server implementation must take the steps described below.
+
+ ## INTERNAL_SERVER_ERROR
+
+ When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization
+ server implementation was wrong or that an error occurred in Authlete.
+ In either case, from the viewpoint of the client application, it is an error on the server side.
+ Therefore, the service implementation should generate a response to the client application with
+ HTTP status of "500 Internal Server Error". Authlete recommends `application/json` as the content
+ type although OAuth 2.0 specification does not mention the format of the error response when the
+ redirect URI is not usable.
+ The value of `responseContent` is a string which describes the error in the format of
+ [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage), so if
+ the protected resource of the service implementation wants to return an error response to the client
+ application in the way that complies with RFC 6750 (in other words, if `accessTokenType` configuration
+ parameter of the service is Bearer), the value of `responseContent` can be used as the value of
+ `WWW-Authenticate` header.
+ The following is an example response which complies with RFC 6750.
+ ```
+ HTTP/1.1 500 Internal Server Error
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
+ ## BAD_REQUEST
+
+ When the value of `action` is `BAD_REQUEST`, it means that the request from the client application
+ does not contain an access token (= the request from the authorization server implementation to
+ Authlete does not contain `token` request parameter).
+ A response with HTTP status of "400 Bad Request" must be returned to the client application and
+ the content type must be `application/json`.
+ The value of `responseContent` is a string which describes the error in the format of [RFC
+ 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage), so if the
+ protected resource of the service implementation wants to return an error response to the client
+ application in the way that complies with RFC 6750 (in other words, if `accessTokenType` configuration
+ parameter of the service is `Bearer`), the value of `responseContent` can be used as the value of
+ `WWW-Authenticate` header.
+ The following is an example response which complies with RFC 6750.
+ ```
+ HTTP/1.1 400 Bad Request
+ WWW-Authenticate: {responseContent}
+ Cache-Control: no-store
+ Pragma: no-cache
+ ```
+
+ ## UNAUTHORIZED
+
+ When the value of `action` is `UNAUTHORIZED`, it means that the access token does not exist or has
+ expired.
+ The value of `responseContent` is a string which describes the error in the format of RFC
+ 6750 (OAuth 2.0 Bearer Token Usage), so if the protected resource of the service implementation
+ wants to return an error response to the client application in the way that complies with [RFC
+ 6750](https://datatracker.ietf.org/doc/html/rfc6750) (in other words, if `accessTokenType` configuration
+ parameter of the service is `Bearer`), the value of `responseContent` can be used as the value of
+ `WWW-Authenticate` header.
+ The following is an example response which complies with RFC 6750.
+ ```
+ HTTP/1.1 401 Unauthorized
+ WWW-Authenticate: {responseContent}
+ Cache-Control: no-store
+ Pragma: no-cache
+ ```
+
+ ## FORBIDDEN
+
+ When the value of `action` is `FORBIDDEN`, it means that the access token does not cover the required
+ scopes or that the subject associated with the access token is different from the subject contained
+ in the request.
+ A response with HTTP status of "400 Bad Request" must be returned to the client application and
+ the content type must be `application/json`.
+ The value of `responseContent` is a string which describes the error in the format of [RFC
+ 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage), so if the
+ protected resource of the service implementation wants to return an error response to the client
+ application in the way that complies with RFC 6750 (in other words, if `accessTokenType` configuration
+ parameter of the service is Bearer), the value of `responseContent` can be used as the value of
+ `WWW-Authenticate` header.
+ The following is an example response which complies with RFC 6750.
+ ```
+ HTTP/1.1 403 Forbidden
+ WWW-Authenticate: {responseContent}
+ Cache-Control: no-store
+ Pragma: no-cache
+ ```
+
+ ## OK
+
+ When the value of `action` is `OK`, it means that the access token which the client application
+ presented is valid (= exists and has not expired).
+ The implementation of the protected resource endpoint is supposed to return the protected resource
+ to the client application.
+ When action is `OK`, the value of `responseContent` is `"Bearer error=\"invalid_request\""`. This
+ is the simplest string which can be used as the value of `WWW-Authenticate` header to indicate
+ "400 Bad Request". The implementation of the protected resource endpoint may use this string to
+ tell the client application that the request was bad (e.g. in case necessary request parameters
+ for the protected resource endpoint are missing). However, in such a case, the implementation
+ should generate a more informative error message to help developers of client applications.
+ The following is an example error response which complies with RFC 6750.
+ ```
+ HTTP/1.1 400 Bad Request
+ WWW-Authenticate: {responseContent}
+ Cache-Control: no-store
+ Pragma: no-cache
+ ```
+ Basically, The value of `responseContent` is a string which describes the error in the format of
+ [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage). So, if
+ the service has selected `Bearer` as the value of `accessTokenType` configuration parameter, the
+ value of `responseContent` can be used directly as the value of `WWW-Authenticate` header. However,
+ if the service has selected another different token type, the service has to generate error messages
+ for itself.
+ _**JWT-based access token**_
+ Since version 2.1, Authlete provides a feature to issue access tokens in JWT format. This feature
+ can be enabled by setting a non-null value to the `accessTokenSignAlg` property of the service
+ (see the description of the Service class for details). `/api/auth/introspection` API can accept
+ access tokens in JWT format. However, note that the API does not return information contained in
+ a given JWT-based access token but returns information stored in the database record which corresponds
+ to the given JWT-based access token. Because attributes of the database record can be modified
+ after the access token is issued (for example, by using `/api/auth/token/update` API), information
+ returned by `/api/auth/introspection` API and information the given JWT-based access token holds
+ may be different.
+
- This API is supposed to be called from within the implementations of protected resource endpoints
- of the authorization server implementation in order to get information about the access token which
- was presented by the client application.
- In general, a client application accesses a protected resource endpoint of a service with an access
- token, and the implementation of the endpoint checks whether the presented access token has enough
- privileges (= scopes) to access the protected resource before returning the protected resource to
- the client application. To achieve this flow, the endpoint implementation has to know detailed
- information about the access token. Authlete `/auth/introspection` API can be used to get such information.
- The response from `/auth/introspection` API has some parameters. Among them, it is `action` parameter
- that the authorization server implementation should check first because it denotes the next action
- that the authorization server implementation should take. According to the value of `action`, the
- authorization server implementation must take the steps described below.
-
- ## INTERNAL_SERVER_ERROR
-
- When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization
- server implementation was wrong or that an error occurred in Authlete.
- In either case, from the viewpoint of the client application, it is an error on the server side.
- Therefore, the service implementation should generate a response to the client application with
- HTTP status of "500 Internal Server Error". Authlete recommends `application/json` as the content
- type although OAuth 2.0 specification does not mention the format of the error response when the
- redirect URI is not usable.
- The value of `responseContent` is a string which describes the error in the format of
- [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage), so if
- the protected resource of the service implementation wants to return an error response to the client
- application in the way that complies with RFC 6750 (in other words, if `accessTokenType` configuration
- parameter of the service is Bearer), the value of `responseContent` can be used as the value of
- `WWW-Authenticate` header.
- The following is an example response which complies with RFC 6750.
- ```
- HTTP/1.1 500 Internal Server Error
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
-
- ## BAD_REQUEST
-
- When the value of `action` is `BAD_REQUEST`, it means that the request from the client application
- does not contain an access token (= the request from the authorization server implementation to
- Authlete does not contain `token` request parameter).
- A response with HTTP status of "400 Bad Request" must be returned to the client application and
- the content type must be `application/json`.
- The value of `responseContent` is a string which describes the error in the format of [RFC
- 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage), so if the
- protected resource of the service implementation wants to return an error response to the client
- application in the way that complies with RFC 6750 (in other words, if `accessTokenType` configuration
- parameter of the service is `Bearer`), the value of `responseContent` can be used as the value of
- `WWW-Authenticate` header.
- The following is an example response which complies with RFC 6750.
- ```
- HTTP/1.1 400 Bad Request
- WWW-Authenticate: {responseContent}
- Cache-Control: no-store
- Pragma: no-cache
- ```
-
- ## UNAUTHORIZED
-
- When the value of `action` is `UNAUTHORIZED`, it means that the access token does not exist or has
- expired.
- The value of `responseContent` is a string which describes the error in the format of RFC
- 6750 (OAuth 2.0 Bearer Token Usage), so if the protected resource of the service implementation
- wants to return an error response to the client application in the way that complies with [RFC
- 6750](https://datatracker.ietf.org/doc/html/rfc6750) (in other words, if `accessTokenType` configuration
- parameter of the service is `Bearer`), the value of `responseContent` can be used as the value of
- `WWW-Authenticate` header.
- The following is an example response which complies with RFC 6750.
- ```
- HTTP/1.1 401 Unauthorized
- WWW-Authenticate: {responseContent}
- Cache-Control: no-store
- Pragma: no-cache
- ```
-
- ## FORBIDDEN
-
- When the value of `action` is `FORBIDDEN`, it means that the access token does not cover the required
- scopes or that the subject associated with the access token is different from the subject contained
- in the request.
- A response with HTTP status of "400 Bad Request" must be returned to the client application and
- the content type must be `application/json`.
- The value of `responseContent` is a string which describes the error in the format of [RFC
- 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage), so if the
- protected resource of the service implementation wants to return an error response to the client
- application in the way that complies with RFC 6750 (in other words, if `accessTokenType` configuration
- parameter of the service is Bearer), the value of `responseContent` can be used as the value of
- `WWW-Authenticate` header.
- The following is an example response which complies with RFC 6750.
- ```
- HTTP/1.1 403 Forbidden
- WWW-Authenticate: {responseContent}
- Cache-Control: no-store
- Pragma: no-cache
- ```
-
- ## OK
-
- When the value of `action` is `OK`, it means that the access token which the client application
- presented is valid (= exists and has not expired).
- The implementation of the protected resource endpoint is supposed to return the protected resource
- to the client application.
- When action is `OK`, the value of `responseContent` is `"Bearer error=\"invalid_request\""`. This
- is the simplest string which can be used as the value of `WWW-Authenticate` header to indicate
- "400 Bad Request". The implementation of the protected resource endpoint may use this string to
- tell the client application that the request was bad (e.g. in case necessary request parameters
- for the protected resource endpoint are missing). However, in such a case, the implementation
- should generate a more informative error message to help developers of client applications.
- The following is an example error response which complies with RFC 6750.
- ```
- HTTP/1.1 400 Bad Request
- WWW-Authenticate: {responseContent}
- Cache-Control: no-store
- Pragma: no-cache
- ```
- Basically, The value of `responseContent` is a string which describes the error in the format of
- [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage). So, if
- the service has selected `Bearer` as the value of `accessTokenType` configuration parameter, the
- value of `responseContent` can be used directly as the value of `WWW-Authenticate` header. However,
- if the service has selected another different token type, the service has to generate error messages
- for itself.
- _**JWT-based access token**_
- Since version 2.1, Authlete provides a feature to issue access tokens in JWT format. This feature
- can be enabled by setting a non-null value to the `accessTokenSignAlg` property of the service
- (see the description of the Service class for details). `/api/auth/introspection` API can accept
- access tokens in JWT format. However, note that the API does not return information contained in
- a given JWT-based access token but returns information stored in the database record which corresponds
- to the given JWT-based access token. Because attributes of the database record can be modified
- after the access token is issued (for example, by using `/api/auth/token/update` API), information
- returned by `/api/auth/introspection` API and information the given JWT-based access token holds
- may be different.
parameters:
- in: path
name: serviceId
@@ -4598,81 +4646,87 @@ paths:
description: |
This API exists to help your authorization server provide its own introspection API which complies
with [RFC 7662](https://tools.ietf.org/html/rfc7662) (OAuth 2.0 Token Introspection).
+ x-mint:
+ metadata:
+ description: "This API exists to help your authorization server provide its own introspection API which complies with [RFC 7662](https://tools.ietf.org/html/rfc7662) (OAuth 2.0 Token Introspection)."
+ content: |
+
+ This API is supposed to be called from within the implementations of the introspection endpoint
+ of your service. The authorization server implementation should retrieve the value of `action` from
+ the response and take the following steps according to the value.
+ In general, a client application accesses a protected resource endpoint of a service with an access
+ token, and the implementation of the endpoint checks whether the presented access token has enough
+ privileges (= scopes) to access the protected resource before returning the protected resource to
+ the client application. To achieve this flow, the endpoint implementation has to know detailed
+ information about the access token. Authlete `/auth/introspection` API can be used to get such information.
+ The response from `/auth/introspection` API has some parameters. Among them, it is `action` parameter
+ that the authorization server implementation should check first because it denotes the next action
+ that the authorization server implementation should take. According to the value of `action`, the
+ authorization server implementation must take the steps described below.
+
+ ## INTERNAL_SERVER_ERROR
+
+ When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization
+ server implementation was wrong or that an error occurred in Authlete.
+ In either case, from the viewpoint of the client application, it is an error on the server side.
+ Therefore, the service implementation should generate a response to the client application with
+ HTTP status of "500 Internal Server Error".
+ The value of `responseContent` is a JSON string which describes the error, so it can be used
+ as the entity body of the response if you want. Note that, however, [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662) does not mention anything about the response
+ body of error responses.
+
+ ---
+
+ The following illustrates an example response which the introspection endpoint of the authorization
+ server implementation generates and returns to the client application.
+ ```
+ HTTP/1.1 500 Internal Server Error
+ Content-Type: application/json
+ {responseContent}
+ ```
+
+ ## BAD_REQUEST
+
+ When the value of `action` is `BAD_REQUEST`, it means that the request from the client application
+ is invalid. This happens when the request from the client did not include the token request parameter.
+ See "[2.1. Introspection Request](https://datatracker.ietf.org/doc/html/rfc7662#section-2.1)" in
+ RFC 7662 for details about requirements for introspection requests.
+ The HTTP status of the response returned to the client application should be "400 Bad Request".
+ The value of `responseContent` is a JSON string which describes the error, so it can be used
+ as the entity body of the response if you want. Note that, however, [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662)
+ does not mention anything about the response body of error responses.
+ The following illustrates an example response which the introspection endpoint of the authorization
+ server implementation generates and returns to the client application.
+ ```
+ HTTP/1.1 400 Bad Request
+ Content-Type: application/json
+ {responseContent}
+ ```
+
+ ## OK
+
+ When the value of `action` is `OK`, the request from the client application is valid.
+ The HTTP status of the response returned to the client application must be "200 OK" and its content
+ type must be `application/json`.
+ The value of `responseContent` is a JSON string which complies with the introspection response
+ defined in "2.2. Introspection Response" in RFC7662.
+
+ ---
+
+ The following illustrates the response which the introspection endpoint of your authorization server
+ implementation should generate and return to the client application.
+ ```
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+ {responseContent}
+ ```
+ Note that RFC 7662 says _"To prevent token scanning attacks, **the endpoint MUST also require some
+ form of authorization to access this endpoint**"_. This means that you have to protect your introspection
+ endpoint in some way or other. Authlete does not care about how your introspection endpoint is protected.
+ In most cases, as mentioned in RFC 7662, "401 Unauthorized" is a proper response when an introspection
+ request does not satisfy authorization requirements imposed by your introspection endpoint.
+
- This API is supposed to be called from within the implementations of the introspection endpoint
- of your service. The authorization server implementation should retrieve the value of `action` from
- the response and take the following steps according to the value.
- In general, a client application accesses a protected resource endpoint of a service with an access
- token, and the implementation of the endpoint checks whether the presented access token has enough
- privileges (= scopes) to access the protected resource before returning the protected resource to
- the client application. To achieve this flow, the endpoint implementation has to know detailed
- information about the access token. Authlete `/auth/introspection` API can be used to get such information.
- The response from `/auth/introspection` API has some parameters. Among them, it is `action` parameter
- that the authorization server implementation should check first because it denotes the next action
- that the authorization server implementation should take. According to the value of `action`, the
- authorization server implementation must take the steps described below.
-
- ## INTERNAL_SERVER_ERROR
-
- When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization
- server implementation was wrong or that an error occurred in Authlete.
- In either case, from the viewpoint of the client application, it is an error on the server side.
- Therefore, the service implementation should generate a response to the client application with
- HTTP status of "500 Internal Server Error".
- The value of `responseContent` is a JSON string which describes the error, so it can be used
- as the entity body of the response if you want. Note that, however, [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662) does not mention anything about the response
- body of error responses.
-
- ---
-
- The following illustrates an example response which the introspection endpoint of the authorization
- server implementation generates and returns to the client application.
- ```
- HTTP/1.1 500 Internal Server Error
- Content-Type: application/json
- {responseContent}
- ```
-
- ## BAD_REQUEST
-
- When the value of `action` is `BAD_REQUEST`, it means that the request from the client application
- is invalid. This happens when the request from the client did not include the token request parameter.
- See "[2.1. Introspection Request](https://datatracker.ietf.org/doc/html/rfc7662#section-2.1)" in
- RFC 7662 for details about requirements for introspection requests.
- The HTTP status of the response returned to the client application should be "400 Bad Request".
- The value of `responseContent` is a JSON string which describes the error, so it can be used
- as the entity body of the response if you want. Note that, however, [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662)
- does not mention anything about the response body of error responses.
- The following illustrates an example response which the introspection endpoint of the authorization
- server implementation generates and returns to the client application.
- ```
- HTTP/1.1 400 Bad Request
- Content-Type: application/json
- {responseContent}
- ```
-
- ## OK
-
- When the value of `action` is `OK`, the request from the client application is valid.
- The HTTP status of the response returned to the client application must be "200 OK" and its content
- type must be `application/json`.
- The value of `responseContent` is a JSON string which complies with the introspection response
- defined in "2.2. Introspection Response" in RFC7662.
-
- ---
-
- The following illustrates the response which the introspection endpoint of your authorization server
- implementation should generate and return to the client application.
- ```
- HTTP/1.1 200 OK
- Content-Type: application/json
- {responseContent}
- ```
- Note that RFC 7662 says _"To prevent token scanning attacks, **the endpoint MUST also require some
- form of authorization to access this endpoint**"_. This means that you have to protect your introspection
- endpoint in some way or other. Authlete does not care about how your introspection endpoint is protected.
- In most cases, as mentioned in RFC 7662, "401 Unauthorized" is a proper response when an introspection
- request does not satisfy authorization requirements imposed by your introspection endpoint.
parameters:
- in: path
name: serviceId
@@ -4746,124 +4800,130 @@ paths:
summary: Process Revocation Request
description: |
This API revokes access tokens and refresh tokens.
+ x-mint:
+ metadata:
+ description: "This API revokes access tokens and refresh tokens."
+ content: |
+
+ This API is supposed to be called from within the implementation of the revocation endpoint ([RFC
+ 7009](tools.ietf.org/html/rfc7009)) of the authorization server implementation in order to revoke
+ access tokens and refresh tokens.
+ The response from `/auth/revocation` API has some parameters. Among them, it is `action` parameter
+ that the authorization server implementation should check first because it denotes the next action
+ that the authorization server implementation should take. According to the value of `action`, the
+ authorization server implementation must take the steps described below.
+
+ ## INTERNAL_SERVER_ERROR
+
+ When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization
+ server implementation was wrong or that an error occurred in Authlete.
+ In either case, from the viewpoint of the client application, it is an error on the server side.
+ Therefore, the service implementation should generate a response to the client application with
+ HTTP status of "500 Internal Server Error".
+ The value of `responseContent` is a JSON string which describes the error, so it can be
+ used as the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the service implementation should generate and return
+ to the client application.
+ ```
+ HTTP/1.1 500 Internal Server Error
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
+ ## INVALID_CLIENT
+
+ When the value of `action` is `INVALID_CLIENT`, it means that authentication of the client failed.
+ In this case, the HTTP status of the response to the client application is either "400 Bad Request"
+ or "401 Unauthorized". The description about `invalid_client` shown below is an excerpt from [RFC
+ 6749](https://datatracker.ietf.org/doc/html/rfc6749).
+
+ ---
+
+ Client authentication failed (e.g., unknown client, no client authentication included, or unsupported
+ authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code
+ to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate
+ via the `Authorization` request header field, the authorization server MUST respond with an HTTP
+ 401 (Unauthorized) status code and include the `WWW-Authenticate` response header field matching
+ the authentication scheme used by the client.
+
+ ---
+
+ In either case, the value of `responseContent` is a JSON string which can be used as the entity
+ body of the response to the client application.
+
+ ---
+
+ The following illustrates the response which the service implementation should generate and return
+ to the client application.
+
+ ```
+ HTTP/1.1 400 Bad Request
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
+ ```
+ HTTP/1.1 401 Unauthorized
+ WWW-Authenticate: {challenge}
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
+ ## BAD_REQUEST
+
+ When the value of `action` is `BAD_REQUEST`, it means that the request from the client application
+ is invalid.
+ The HTTP status of the response returned to the client application must be "400 Bad Request" and
+ the content type must be `application/json`. [RFC 7009](https://datatracker.ietf.org/doc/html/rfc7009),
+ [2.2.1. Error Respons](https://datatracker.ietf.org/doc/html/rfc7009#section-2.2.1) states "The
+ error presentation conforms to the definition in [Section 5.2](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2)
+ of [[RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749)]."
+ The value of `responseContent` is a JSON string which describes the error, so it can be used
+ as the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the authorization server implementation should generate
+ and return to the client application.
+
+ ```
+ HTTP/1.1 400 Bad Request
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
+ ## OK
+
+ When the value of `action` is `OK`, it means that the request from the client application is valid
+ and the presented token has been revoked successfully or if the client submitted an invalid token.
+ Note that invalid tokens do not cause an error. See [2.2. Revocation Response](https://datatracker.ietf.org/doc/html/rfc7009#section-2.2) for details.
+ The HTTP status of the response returned to the client application must be 200 OK.
+ If the original request from the client application contains callback request parameter and its
+ value is not empty, the content type should be `application/javascript` and the content should be
+ a JavaScript snippet for JSONP.
+ The value of `responseContent` is JavaScript snippet if the original request from the client application
+ contains callback request parameter and its value is not empty. Otherwise, the value of `responseContent`
+ is `null`.
+ ```
+ HTTP/1.1 200 OK
+ Content-Type: application/javascript
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
- This API is supposed to be called from within the implementation of the revocation endpoint ([RFC
- 7009](tools.ietf.org/html/rfc7009)) of the authorization server implementation in order to revoke
- access tokens and refresh tokens.
- The response from `/auth/revocation` API has some parameters. Among them, it is `action` parameter
- that the authorization server implementation should check first because it denotes the next action
- that the authorization server implementation should take. According to the value of `action`, the
- authorization server implementation must take the steps described below.
-
- ## INTERNAL_SERVER_ERROR
-
- When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization
- server implementation was wrong or that an error occurred in Authlete.
- In either case, from the viewpoint of the client application, it is an error on the server side.
- Therefore, the service implementation should generate a response to the client application with
- HTTP status of "500 Internal Server Error".
- The value of `responseContent` is a JSON string which describes the error, so it can be
- used as the entity body of the response.
-
- ---
-
- The following illustrates the response which the service implementation should generate and return
- to the client application.
- ```
- HTTP/1.1 500 Internal Server Error
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
-
- ## INVALID_CLIENT
-
- When the value of `action` is `INVALID_CLIENT`, it means that authentication of the client failed.
- In this case, the HTTP status of the response to the client application is either "400 Bad Request"
- or "401 Unauthorized". The description about `invalid_client` shown below is an excerpt from [RFC
- 6749](https://datatracker.ietf.org/doc/html/rfc6749).
-
- ---
-
- Client authentication failed (e.g., unknown client, no client authentication included, or unsupported
- authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code
- to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate
- via the `Authorization` request header field, the authorization server MUST respond with an HTTP
- 401 (Unauthorized) status code and include the `WWW-Authenticate` response header field matching
- the authentication scheme used by the client.
-
- ---
-
- In either case, the value of `responseContent` is a JSON string which can be used as the entity
- body of the response to the client application.
-
- ---
-
- The following illustrates the response which the service implementation should generate and return
- to the client application.
-
- ```
- HTTP/1.1 400 Bad Request
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
-
- ```
- HTTP/1.1 401 Unauthorized
- WWW-Authenticate: {challenge}
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
-
- ## BAD_REQUEST
-
- When the value of `action` is `BAD_REQUEST`, it means that the request from the client application
- is invalid.
- The HTTP status of the response returned to the client application must be "400 Bad Request" and
- the content type must be `application/json`. [RFC 7009](https://datatracker.ietf.org/doc/html/rfc7009),
- [2.2.1. Error Respons](https://datatracker.ietf.org/doc/html/rfc7009#section-2.2.1) states "The
- error presentation conforms to the definition in [Section 5.2](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2)
- of [[RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749)]."
- The value of `responseContent` is a JSON string which describes the error, so it can be used
- as the entity body of the response.
-
- ---
-
- The following illustrates the response which the authorization server implementation should generate
- and return to the client application.
-
- ```
- HTTP/1.1 400 Bad Request
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
-
- ## OK
-
- When the value of `action` is `OK`, it means that the request from the client application is valid
- and the presented token has been revoked successfully or if the client submitted an invalid token.
- Note that invalid tokens do not cause an error. See [2.2. Revocation Response](https://datatracker.ietf.org/doc/html/rfc7009#section-2.2) for details.
- The HTTP status of the response returned to the client application must be 200 OK.
- If the original request from the client application contains callback request parameter and its
- value is not empty, the content type should be `application/javascript` and the content should be
- a JavaScript snippet for JSONP.
- The value of `responseContent` is JavaScript snippet if the original request from the client application
- contains callback request parameter and its value is not empty. Otherwise, the value of `responseContent`
- is `null`.
- ```
- HTTP/1.1 200 OK
- Content-Type: application/javascript
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
parameters:
- in: path
name: serviceId
@@ -4938,122 +4998,128 @@ paths:
summary: Process UserInfo Request
description: |
This API gathers information about a user.
+ x-mint:
+ metadata:
+ description: "This API gathers information about a user."
+ content: |
+
+ This API is supposed to be called from within the implementation of the [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)
+ of the authorization server in order to get information about the user that is associated with
+ an access token.
+ The response from `/auth/userinfo` API has various parameters. Among them, it is `action` parameter
+ that the authorization server implementation should check first because it denotes the next action
+ that the authorization server implementation should take. According to the value of `action`, the
+ service implementation must take the steps described below.
+
+ ## INTERNAL_SERVER_ERROR
+
+ When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization
+ server implementation was wrong or that an error occurred in Authlete. In either case, from the
+ viewpoint of the client application, it is an error on the server side. Therefore, the service
+ implementation should generate a response to the client application with HTTP status of "500 Internal
+ Server Error".
+ The value of `responseContent` is a string which describes the error in the format of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750)
+ (OAuth 2.0 Bearer Token Usage) so the userinfo endpoint implementation can use the value of `responseContent`
+ as the value of`WWW-Authenticate` header.
+ The following is an example response which complies with RFC 6750. Note that OpenID Connect Core
+ 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo
+ Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details.
+ ```
+ HTTP/1.1 500 Internal Server Error
+ WWW-Authenticate: {responseContent}
+ Cache-Control: no-store
+ Pragma: no-cache
+ ```
+
+ ## BAD_REQUEST
+
+ When the value of `action` is `BAD_REQUEST`, it means that the request from the client application
+ does not contain an access token (= the request from the authorization server implementation to
+ Authlete does not contain `token` parameter).
+ The value of `responseContent` is a string which describes the error in the format
+ of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the
+ userinfo endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate`
+ header.
+ The following is an example response which complies with RFC 6750. Note that OpenID Connect Core
+ 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo
+ Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details.
+ ```
+ HTTP/1.1 400 Bad Request
+ WWW-Authenticate: {responseContent}
+ Cache-Control: no-store
+ Pragma: no-cache
+ ```
+
+ ## UNAUTHORIZED
+
+ When the value of `action` is `UNAUTHORIZED`, it means that the access token does not exist, has
+ expired, or is not associated with any subject (= any user account).
+ The value of `responseContent` is a string which describes the error in the format of [RFC
+ 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo
+ endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate`
+ header.
+ The following is an example response which complies with RFC 6750. Note that OpenID Connect Core
+ 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo
+ Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details.
+ ```
+ HTTP/1.1 401 Unauthorized
+ WWW-Authenticate: {responseContent}
+ Cache-Control: no-store
+ Pragma: no-cache
+ ```
+
+ ## FORBIDDEN
+
+ When the value of `action` is `FORBIDDEN`, it means that the access token does not include the
+ `openid` scope.
+ The value of `responseContent` is a string which describes the error in the format of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750)
+ (OAuth 2.0 Bearer Token Usage) so the userinfo endpoint implementation can use the value of `responseContent`
+ as the value of`WWW-Authenticate` header.
+ The following is an example response which complies with RFC 6750. Note that OpenID Connect Core
+ 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo
+ Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details.
+ ```
+ HTTP/1.1 403 Forbidden
+ WWW-Authenticate: {responseContent}
+ Cache-Control: no-store
+ Pragma: no-cache
+ ```
+
+ ## OK
+
+ When the value of `action` is `OK`, it means that the access token which the client application
+ presented is valid. To be concrete, it means that the access token exists, has not expired, includes
+ the openid scope, and is associated with a subject (= a user account).
+ What the userinfo endpoint implementation should do next is to collect information about the subject
+ (user) from your database. The value of the `subject` is contained in the subject parameter in the
+ response from this API and the names of data, i.e., the claims names are contained in the claims
+ parameter in the response. For example, if the `subject` parameter is `joe123` and the claims
+ parameter is `[ "given_name", "email" ]`, you need to extract information about joe123's given name
+ and email from your database.
+ Then, call Authlete's `/auth/userinfo/issue` API with the collected information and the access token
+ in order to make Authlete generate an ID token.
+ If an error occurred during the above steps, generate an error response to the client. The response
+ should comply with [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750). For example, if the
+ subject associated with the access token does not exist in your database any longer, you may feel
+ like generating a response like below.
+ ```
+ HTTP/1.1 400 Bad Request
+ WWW-Authenticate: Bearer error="invalid_token",
+ error_description="The subject associated with the access token does not exist."
+ Cache-Control: no-store
+ Pragma: no-cache
+ ```
+ Also, an error might occur on database access. If you treat the error as an internal server error,
+ then the response would be like the following.
+ ```
+ HTTP/1.1 500 Internal Server Error
+ WWW-Authenticate: Bearer error="server_error",
+ error_description="Failed to extract information about the subject from the database."
+ Cache-Control: no-store
+ Pragma: no-cache
+ ```
+
- This API is supposed to be called from within the implementation of the [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)
- of the authorization server in order to get information about the user that is associated with
- an access token.
- The response from `/auth/userinfo` API has various parameters. Among them, it is `action` parameter
- that the authorization server implementation should check first because it denotes the next action
- that the authorization server implementation should take. According to the value of `action`, the
- service implementation must take the steps described below.
-
- ## INTERNAL_SERVER_ERROR
-
- When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization
- server implementation was wrong or that an error occurred in Authlete. In either case, from the
- viewpoint of the client application, it is an error on the server side. Therefore, the service
- implementation should generate a response to the client application with HTTP status of "500 Internal
- Server Error".
- The value of `responseContent` is a string which describes the error in the format of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750)
- (OAuth 2.0 Bearer Token Usage) so the userinfo endpoint implementation can use the value of `responseContent`
- as the value of`WWW-Authenticate` header.
- The following is an example response which complies with RFC 6750. Note that OpenID Connect Core
- 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo
- Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details.
- ```
- HTTP/1.1 500 Internal Server Error
- WWW-Authenticate: {responseContent}
- Cache-Control: no-store
- Pragma: no-cache
- ```
-
- ## BAD_REQUEST
-
- When the value of `action` is `BAD_REQUEST`, it means that the request from the client application
- does not contain an access token (= the request from the authorization server implementation to
- Authlete does not contain `token` parameter).
- The value of `responseContent` is a string which describes the error in the format
- of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the
- userinfo endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate`
- header.
- The following is an example response which complies with RFC 6750. Note that OpenID Connect Core
- 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo
- Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details.
- ```
- HTTP/1.1 400 Bad Request
- WWW-Authenticate: {responseContent}
- Cache-Control: no-store
- Pragma: no-cache
- ```
-
- ## UNAUTHORIZED
-
- When the value of `action` is `UNAUTHORIZED`, it means that the access token does not exist, has
- expired, or is not associated with any subject (= any user account).
- The value of `responseContent` is a string which describes the error in the format of [RFC
- 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo
- endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate`
- header.
- The following is an example response which complies with RFC 6750. Note that OpenID Connect Core
- 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo
- Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details.
- ```
- HTTP/1.1 401 Unauthorized
- WWW-Authenticate: {responseContent}
- Cache-Control: no-store
- Pragma: no-cache
- ```
-
- ## FORBIDDEN
-
- When the value of `action` is `FORBIDDEN`, it means that the access token does not include the
- `openid` scope.
- The value of `responseContent` is a string which describes the error in the format of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750)
- (OAuth 2.0 Bearer Token Usage) so the userinfo endpoint implementation can use the value of `responseContent`
- as the value of`WWW-Authenticate` header.
- The following is an example response which complies with RFC 6750. Note that OpenID Connect Core
- 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo
- Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details.
- ```
- HTTP/1.1 403 Forbidden
- WWW-Authenticate: {responseContent}
- Cache-Control: no-store
- Pragma: no-cache
- ```
-
- ## OK
-
- When the value of `action` is `OK`, it means that the access token which the client application
- presented is valid. To be concrete, it means that the access token exists, has not expired, includes
- the openid scope, and is associated with a subject (= a user account).
- What the userinfo endpoint implementation should do next is to collect information about the subject
- (user) from your database. The value of the `subject` is contained in the subject parameter in the
- response from this API and the names of data, i.e., the claims names are contained in the claims
- parameter in the response. For example, if the `subject` parameter is `joe123` and the claims
- parameter is `[ "given_name", "email" ]`, you need to extract information about joe123's given name
- and email from your database.
- Then, call Authlete's `/auth/userinfo/issue` API with the collected information and the access token
- in order to make Authlete generate an ID token.
- If an error occurred during the above steps, generate an error response to the client. The response
- should comply with [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750). For example, if the
- subject associated with the access token does not exist in your database any longer, you may feel
- like generating a response like below.
- ```
- HTTP/1.1 400 Bad Request
- WWW-Authenticate: Bearer error="invalid_token",
- error_description="The subject associated with the access token does not exist."
- Cache-Control: no-store
- Pragma: no-cache
- ```
- Also, an error might occur on database access. If you treat the error as an internal server error,
- then the response would be like the following.
- ```
- HTTP/1.1 500 Internal Server Error
- WWW-Authenticate: Bearer error="server_error",
- error_description="Failed to extract information about the subject from the database."
- Cache-Control: no-store
- Pragma: no-cache
- ```
parameters:
- in: path
name: serviceId
@@ -5132,127 +5198,133 @@ paths:
summary: Issue UserInfo Response
description: |
This API generates an ID token.
+ x-mint:
+ metadata:
+ description: "This API generates an ID token."
+ content: |
+
+ This API is supposed to be called from within the implementation of the [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)
+ of the authorization server in order to generate an ID token. Before calling this API, a valid
+ response from `/auth/userinfo` API must be obtained. Then, call this API with the access token
+ contained in the response and the claims values of the user (subject) associated with the access
+ token. See **OK** written in the description of `/auth/userinfo` API for details.
+ The response from `/auth/userinfo/issue` API has various parameters. Among them, it is `action`
+ parameter that the authorization server implementation should check first because it denotes the
+ next action that the authorization server implementation should take. According to the value of
+ `action`, the service implementation must take the steps described below.
+
+ ## INTERNAL_SERVER_ERROR
+
+ When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization
+ server implementation was wrong or that an error occurred in Authlete. In either case, from the
+ viewpoint of the client application, it is an error on the server side. Therefore, the service
+ implementation should generate a response to the client application with HTTP status of "500 Internal
+ Server Error".
+ The parameter `responseContent` returns a string which describes the error in the format of [RFC
+ 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo
+ endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate`
+ header.
+ The following is an example response which complies with RFC 6750. Note that OpenID Connect Core
+ 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo
+ Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details.
+ ```
+ HTTP/1.1 500 Internal Server Error
+ WWW-Authenticate: {responseContent}
+ Cache-Control: no-store
+ Pragma: no-cache
+ ```
+
+ ## BAD_REQUEST
+
+ When the value of `action` is `BAD_REQUEST`, it means that the request from the client application
+ does not contain an access token (= the request from the authorization server implementation to
+ Authlete does not contain `token` parameter).
+ The parameter `responseContent` returns a string which describes the error in the format of [RFC
+ 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo
+ endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate`
+ header.
+ The following is an example response which complies with RFC 6750. Note that OpenID Connect Core
+ 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo
+ Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details.
+ ```
+ HTTP/1.1 400 Bad Request
+ WWW-Authenticate: {responseContent}
+ Cache-Control: no-store
+ Pragma: no-cache
+ ```
+
+ ## UNAUTHORIZED
+
+ When the value of `action` is `UNAUTHORIZED`, it means that the access token does not exist, has
+ expired, or is not associated with any subject (= any user account).
+ The parameter `responseContent` returns a string which describes the error in the format of [RFC
+ 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo
+ endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate`
+ header.
+ The following is an example response which complies with RFC 6750. Note that OpenID Connect Core
+ 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo
+ Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details.
+ ```
+ HTTP/1.1 401 Unauthorized
+ WWW-Authenticate: {responseContent}
+ Cache-Control: no-store
+ Pragma: no-cache
+ ```
+
+ ## FORBIDDEN
+
+ When the value of `action` is `FORBIDDEN`, it means that the access token does not include the
+ `openid` scope.
+ The parameter `responseContent` returns a string which describes the error in the format of [RFC
+ 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo
+ endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate`
+ header.
+ The following is an example response which complies with RFC 6750. Note that OpenID Connect Core
+ 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo
+ Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details.
+ ```
+ HTTP/1.1 403 Forbidden
+ WWW-Authenticate: {responseContent}
+ Cache-Control: no-store
+ Pragma: no-cache
+ ```
+
+ ## JSON
+
+ When the value of `action` is `JSON`, it means that the access token which the client application
+ presented is valid and an ID token was successfully generated in the format of JSON.
+ The userinfo endpoint implementation is expected to generate a response to the client application.
+ The content type of the response must be `application/json` and the response body must be an ID
+ token in JSON format.
+ The value of `responseContent` is the ID token in JSON format when `action` is `JSON`, so
+ a response to the client can be built like below.
+ ```
+ HTTP/1.1 200 OK
+ Cache-Control: no-store
+ Pragma: no-cache
+ Content-Type: application/json;charset=UTF-8
+ {responseContent}
+ ```
+
+ ## JWT
+
+ When the value of `action` is `JWT`, it means that the access token which the client application
+ presented is valid and an ID token was successfully generated in the format of JWT (JSON Web Token)
+ ([RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519)).
+ The userinfo endpoint implementation is expected to generate a response to the client application.
+ The content type of the response must be `application/jwt` and the response body must be an ID
+ token in JWT format.
+ The value of `responseContent` is the ID token in JSON format when `action` is `JWT`, so a response
+ to the client can be built like below.
+ ```
+ HTTP/1.1 200 OK
+ Cache-Control: no-store
+ Pragma: no-cache
+ Content-Type: application/jwt
+ {responseContent}
+ ```
+
- This API is supposed to be called from within the implementation of the [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)
- of the authorization server in order to generate an ID token. Before calling this API, a valid
- response from `/auth/userinfo` API must be obtained. Then, call this API with the access token
- contained in the response and the claims values of the user (subject) associated with the access
- token. See **OK** written in the description of `/auth/userinfo` API for details.
- The response from `/auth/userinfo/issue` API has various parameters. Among them, it is `action`
- parameter that the authorization server implementation should check first because it denotes the
- next action that the authorization server implementation should take. According to the value of
- `action`, the service implementation must take the steps described below.
-
- ## INTERNAL_SERVER_ERROR
-
- When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization
- server implementation was wrong or that an error occurred in Authlete. In either case, from the
- viewpoint of the client application, it is an error on the server side. Therefore, the service
- implementation should generate a response to the client application with HTTP status of "500 Internal
- Server Error".
- The parameter `responseContent` returns a string which describes the error in the format of [RFC
- 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo
- endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate`
- header.
- The following is an example response which complies with RFC 6750. Note that OpenID Connect Core
- 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo
- Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details.
- ```
- HTTP/1.1 500 Internal Server Error
- WWW-Authenticate: {responseContent}
- Cache-Control: no-store
- Pragma: no-cache
- ```
-
- ## BAD_REQUEST
-
- When the value of `action` is `BAD_REQUEST`, it means that the request from the client application
- does not contain an access token (= the request from the authorization server implementation to
- Authlete does not contain `token` parameter).
- The parameter `responseContent` returns a string which describes the error in the format of [RFC
- 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo
- endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate`
- header.
- The following is an example response which complies with RFC 6750. Note that OpenID Connect Core
- 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo
- Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details.
- ```
- HTTP/1.1 400 Bad Request
- WWW-Authenticate: {responseContent}
- Cache-Control: no-store
- Pragma: no-cache
- ```
-
- ## UNAUTHORIZED
-
- When the value of `action` is `UNAUTHORIZED`, it means that the access token does not exist, has
- expired, or is not associated with any subject (= any user account).
- The parameter `responseContent` returns a string which describes the error in the format of [RFC
- 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo
- endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate`
- header.
- The following is an example response which complies with RFC 6750. Note that OpenID Connect Core
- 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo
- Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details.
- ```
- HTTP/1.1 401 Unauthorized
- WWW-Authenticate: {responseContent}
- Cache-Control: no-store
- Pragma: no-cache
- ```
-
- ## FORBIDDEN
-
- When the value of `action` is `FORBIDDEN`, it means that the access token does not include the
- `openid` scope.
- The parameter `responseContent` returns a string which describes the error in the format of [RFC
- 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo
- endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate`
- header.
- The following is an example response which complies with RFC 6750. Note that OpenID Connect Core
- 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo
- Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details.
- ```
- HTTP/1.1 403 Forbidden
- WWW-Authenticate: {responseContent}
- Cache-Control: no-store
- Pragma: no-cache
- ```
-
- ## JSON
-
- When the value of `action` is `JSON`, it means that the access token which the client application
- presented is valid and an ID token was successfully generated in the format of JSON.
- The userinfo endpoint implementation is expected to generate a response to the client application.
- The content type of the response must be `application/json` and the response body must be an ID
- token in JSON format.
- The value of `responseContent` is the ID token in JSON format when `action` is `JSON`, so
- a response to the client can be built like below.
- ```
- HTTP/1.1 200 OK
- Cache-Control: no-store
- Pragma: no-cache
- Content-Type: application/json;charset=UTF-8
- {responseContent}
- ```
-
- ## JWT
-
- When the value of `action` is `JWT`, it means that the access token which the client application
- presented is valid and an ID token was successfully generated in the format of JWT (JSON Web Token)
- ([RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519)).
- The userinfo endpoint implementation is expected to generate a response to the client application.
- The content type of the response must be `application/jwt` and the response body must be an ID
- token in JWT format.
- The value of `responseContent` is the ID token in JSON format when `action` is `JWT`, so a response
- to the client can be built like below.
- ```
- HTTP/1.1 200 OK
- Cache-Control: no-store
- Pragma: no-cache
- Content-Type: application/jwt
- {responseContent}
- ```
parameters:
- in: path
name: serviceId
@@ -5858,74 +5930,80 @@ paths:
Register a client. This API is supposed to be used to implement a client registration endpoint that
complies with [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591) (OAuth 2.0 Dynamic Client
Registration Protocol).
+ x-mint:
+ metadata:
+ description: "Register a client. This API is supposed to be used to implement a client registration endpoint that complies with [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591) (OAuth 2.0 Dynamic Client Registration Protocol)."
+ content: |
+
+ This API is supposed to be called from the within the implementation of the client registration
+ endpoint of the authorization server. The authorization server implementation should retrieve
+ the value of `action` from the response and take the following steps according to the value.
+
+ ## INTERNAL_SERVER_ERROR
+
+ When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the API call from the authorization
+ server implementation was wrong or that an error occurred in Authlete.
+ In either case, from a viewpoint of the client or developer, it is an error on the server side.
+ Therefore, the authorization server implementation should generate a response with "500 Internal
+ Server Error"s and `application/json`.
+ The value of `responseContent` is a JSON string which describes the error, so it can be used as
+ the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the authorization server implementation should generate
+ and return to the client or developer.
+ ```
+ HTTP/1.1 500 Internal Server Error
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+ The endpoint implementation may return another different response to the client or developer since
+ "500 Internal Server Error" is not required by the specification.
+
+ ## BAD_REQUEST
+
+ When the value of `action` is `BAD_REQUEST`, it means that the request from the client or developer
+ was wrong.
+ The authorization server implementation should generate a response with "400 Bad Request" and `application/json`.
+ The value of `responseContent` is a JSON string which describes the error, so it can be used
+ as the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the authorization server implementation should generate
+ and return to the client or developer.
+ ```
+ HTTP/1.1 400 Bad Request
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
+ ## CREATED
+
+ When the value of `action` is `CREATED`, it means that the request from the client or developer is
+ valid.
+ The authorization server implementation should generate a response to the client or developer with
+ "201 CREATED" and `application/json`.
+ The `responseContent` a JSON string which can be used as the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the authorization server implementation should generate
+ and return to the client or developer.
+ ```
+ HTTP/1.1 201 CREATED
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
- This API is supposed to be called from the within the implementation of the client registration
- endpoint of the authorization server. The authorization server implementation should retrieve
- the value of `action` from the response and take the following steps according to the value.
-
- ## INTERNAL_SERVER_ERROR
-
- When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the API call from the authorization
- server implementation was wrong or that an error occurred in Authlete.
- In either case, from a viewpoint of the client or developer, it is an error on the server side.
- Therefore, the authorization server implementation should generate a response with "500 Internal
- Server Error"s and `application/json`.
- The value of `responseContent` is a JSON string which describes the error, so it can be used as
- the entity body of the response.
-
- ---
-
- The following illustrates the response which the authorization server implementation should generate
- and return to the client or developer.
- ```
- HTTP/1.1 500 Internal Server Error
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
- The endpoint implementation may return another different response to the client or developer since
- "500 Internal Server Error" is not required by the specification.
-
- ## BAD_REQUEST
-
- When the value of `action` is `BAD_REQUEST`, it means that the request from the client or developer
- was wrong.
- The authorization server implementation should generate a response with "400 Bad Request" and `application/json`.
- The value of `responseContent` is a JSON string which describes the error, so it can be used
- as the entity body of the response.
-
- ---
-
- The following illustrates the response which the authorization server implementation should generate
- and return to the client or developer.
- ```
- HTTP/1.1 400 Bad Request
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
-
- ## CREATED
-
- When the value of `action` is `CREATED`, it means that the request from the client or developer is
- valid.
- The authorization server implementation should generate a response to the client or developer with
- "201 CREATED" and `application/json`.
- The `responseContent` a JSON string which can be used as the entity body of the response.
-
- ---
-
- The following illustrates the response which the authorization server implementation should generate
- and return to the client or developer.
- ```
- HTTP/1.1 201 CREATED
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
parameters:
- in: path
name: serviceId
@@ -6026,98 +6104,104 @@ paths:
Get a dynamically registered client. This API is supposed to be used to implement a client registration
management endpoint that complies with [RFC 7592](https://datatracker.ietf.org/doc/html/rfc7592)
(OAuth 2.0 Dynamic Registration Management).
+ x-mint:
+ metadata:
+ description: "Get a dynamically registered client. This API is supposed to be used to implement a client registration management endpoint that complies with [RFC 7592](https://datatracker.ietf.org/doc/html/rfc7592) (OAuth 2.0 Dynamic Registration Management)."
+ content: |
+
+ This API is supposed to be called from the within the implementation of the client registration
+ management endpoint of the authorization server. The authorization server implementation should
+ retrieve the value of `action` from the response and take the following steps according to the value.
+
+ ## INTERNAL_SERVER_ERROR
+
+ When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the API call from the authorization
+ server implementation was wrong or that an error occurred in Authlete.
+ In either case, from a viewpoint of the client or developer, it is an error on the server side.
+ Therefore, the authorization server implementation should generate a response to the client or developer
+ with "500 Internal Server Error"s and `application/json`.
+ The value of `responseContent` is a JSON string which describes the error, so it can be used as
+ the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the authorization server implementation should generate
+ and return to the client or developer.
+ ```
+ HTTP/1.1 500 Internal Server Error
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+ The endpoint implementation may return another different response to the client or developer since
+ "500 Internal Server Error" is not required by the specification.
+
+ ## BAD_REQUEST
+
+ When the value of `action` is `BAD_REQUEST`, it means that the request from the client or developer
+ was wrong.
+ The authorization server implementation should generate a response to the client or developer with
+ "400 Bad Request" and `application/json`.
+ The value of `responseContent` is a JSON string which describes the error, so it can be used as
+ the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the authorization server implementation should generate
+ and return to the client or developer.
+ ```
+ HTTP/1.1 400 Bad Request
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
+ ## UNAUTHORIZED
+
+ When the value of `action` is `UNAUTHORIZED`, it means that the registration access token used by
+ the client configuration request (RFC 7592) is invalid, or the client application which the token
+ is tied to does not exist any longer or is invalid.
+ The HTTP status of the response returned to the client application must be "401 Unauthorized" and
+ the content type must be `application/json`.
+ The value of `responseContent` is a JSON string which describes the error, so it can be used as
+ the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the endpoint implementation should generate and return
+ to the client application.
+ ```
+ HTTP/1.1 401 Unauthorized
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+ NOTE: The `UNAUTHORIZED` value was added in October, 2021. See the description of
+ `Service.unauthorizedOnClientConfigSupported` for details.
+
+ ## OK
+
+ When the value of `action` is `OK`, it means that the request from the client or developer is valid.
+ The authorization server implementation should generate a response to the client or developer with
+ "200 OK" and `application/json`.
+ The `responseContent` a JSON string which can be used as the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the authorization server implementation should generate
+ and return to the client or developer.
+ ```
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
- This API is supposed to be called from the within the implementation of the client registration
- management endpoint of the authorization server. The authorization server implementation should
- retrieve the value of `action` from the response and take the following steps according to the value.
-
- ## INTERNAL_SERVER_ERROR
-
- When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the API call from the authorization
- server implementation was wrong or that an error occurred in Authlete.
- In either case, from a viewpoint of the client or developer, it is an error on the server side.
- Therefore, the authorization server implementation should generate a response to the client or developer
- with "500 Internal Server Error"s and `application/json`.
- The value of `responseContent` is a JSON string which describes the error, so it can be used as
- the entity body of the response.
-
- ---
-
- The following illustrates the response which the authorization server implementation should generate
- and return to the client or developer.
- ```
- HTTP/1.1 500 Internal Server Error
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
- The endpoint implementation may return another different response to the client or developer since
- "500 Internal Server Error" is not required by the specification.
-
- ## BAD_REQUEST
-
- When the value of `action` is `BAD_REQUEST`, it means that the request from the client or developer
- was wrong.
- The authorization server implementation should generate a response to the client or developer with
- "400 Bad Request" and `application/json`.
- The value of `responseContent` is a JSON string which describes the error, so it can be used as
- the entity body of the response.
-
- ---
-
- The following illustrates the response which the authorization server implementation should generate
- and return to the client or developer.
- ```
- HTTP/1.1 400 Bad Request
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
-
- ## UNAUTHORIZED
-
- When the value of `action` is `UNAUTHORIZED`, it means that the registration access token used by
- the client configuration request (RFC 7592) is invalid, or the client application which the token
- is tied to does not exist any longer or is invalid.
- The HTTP status of the response returned to the client application must be "401 Unauthorized" and
- the content type must be `application/json`.
- The value of `responseContent` is a JSON string which describes the error, so it can be used as
- the entity body of the response.
-
- ---
-
- The following illustrates the response which the endpoint implementation should generate and return
- to the client application.
- ```
- HTTP/1.1 401 Unauthorized
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
- NOTE: The `UNAUTHORIZED` value was added in October, 2021. See the description of
- `Service.unauthorizedOnClientConfigSupported` for details.
-
- ## OK
-
- When the value of `action` is `OK`, it means that the request from the client or developer is valid.
- The authorization server implementation should generate a response to the client or developer with
- "200 OK" and `application/json`.
- The `responseContent` a JSON string which can be used as the entity body of the response.
-
- ---
-
- The following illustrates the response which the authorization server implementation should generate
- and return to the client or developer.
- ```
- HTTP/1.1 200 OK
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
parameters:
- in: path
name: serviceId
@@ -6222,98 +6306,104 @@ paths:
Update a dynamically registered client. This API is supposed to be used to implement a client
registration management endpoint that complies with [RFC 7592](https://datatracker.ietf.org/doc/html/rfc7592)
(OAuth 2.0 Dynamic Registration Management).
+ x-mint:
+ metadata:
+ description: "Update a dynamically registered client. This API is supposed to be used to implement a client registration management endpoint that complies with [RFC 7592](https://datatracker.ietf.org/doc/html/rfc7592) (OAuth 2.0 Dynamic Registration Management)."
+ content: |
+
+ This API is supposed to be called from the within the implementation of the client registration
+ management endpoint of the authorization server. The authorization server implementation should
+ retrieve the value of `action` from the response and take the following steps according to the value.
+
+ ## INTERNAL_SERVER_ERROR
+
+ When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the API call from the authorization
+ server implementation was wrong or that an error occurred in Authlete.
+ In either case, from a viewpoint of the client or developer, it is an error on the server side.
+ Therefore, the authorization server implementation should generate a response with "500 Internal
+ Server Error"s and `application/json`.
+ The value of `responseContent` is a JSON string which describes the error, so it can be used as
+ the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the authorization server implementation should generate
+ and return to the client or developer.
+ ```
+ HTTP/1.1 500 Internal Server Error
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+ The endpoint implementation may return another different response to the client or developer since
+ "500 Internal Server Error" is not required by the specification.
+
+ ## BAD_REQUEST
+
+ When the value of `action` is `BAD_REQUEST`, it means that the request from the client or developer
+ was wrong.
+ The authorization server implementation should generate a response with "400 Bad Request" and `application/json`.
+ The value of `responseContent` is a JSON string which describes the error, so it can be used as
+ the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the authorization server implementation should generate
+ and return to the client or developer.
+ ```
+ HTTP/1.1 400 Bad Request
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
+ ## UNAUTHORIZED
+
+ When the value of `action` is `UNAUTHORIZED`, it means that the registration access token used by
+ the client configuration request (RFC 7592) is invalid, or the client application which the token
+ is tied to does not exist any longer or is invalid.
+ The HTTP status of the response returned to the client application must be "401 Unauthorized" and
+ the content type must be `application/json`.
+ The value of `responseContent` is a JSON string which describes the error, so it can be used as
+ the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the endpoint implementation should generate and return
+ to the client application.
+ ```
+ HTTP/1.1 401 Unauthorized
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+ NOTE: The `UNAUTHORIZED` value was added in October, 2021. See the description of
+ `Service.unauthorizedOnClientConfigSupported` for details.
+
+ ## UPDATED
+
+ When the value of `action` is `UPDATED`, it means that the request from the client or developer is
+ valid.
+ The authorization server implementation should generate a response to the client or developer with
+ "200 OK" and `application/json`.
+ The `responseContent` a JSON string which can be used as the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the authorization server implementation should generate
+ and return to the client or developer.
+ ```
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
- This API is supposed to be called from the within the implementation of the client registration
- management endpoint of the authorization server. The authorization server implementation should
- retrieve the value of `action` from the response and take the following steps according to the value.
-
- ## INTERNAL_SERVER_ERROR
-
- When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the API call from the authorization
- server implementation was wrong or that an error occurred in Authlete.
- In either case, from a viewpoint of the client or developer, it is an error on the server side.
- Therefore, the authorization server implementation should generate a response with "500 Internal
- Server Error"s and `application/json`.
- The value of `responseContent` is a JSON string which describes the error, so it can be used as
- the entity body of the response.
-
- ---
-
- The following illustrates the response which the authorization server implementation should generate
- and return to the client or developer.
- ```
- HTTP/1.1 500 Internal Server Error
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
- The endpoint implementation may return another different response to the client or developer since
- "500 Internal Server Error" is not required by the specification.
-
- ## BAD_REQUEST
-
- When the value of `action` is `BAD_REQUEST`, it means that the request from the client or developer
- was wrong.
- The authorization server implementation should generate a response with "400 Bad Request" and `application/json`.
- The value of `responseContent` is a JSON string which describes the error, so it can be used as
- the entity body of the response.
-
- ---
-
- The following illustrates the response which the authorization server implementation should generate
- and return to the client or developer.
- ```
- HTTP/1.1 400 Bad Request
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
-
- ## UNAUTHORIZED
-
- When the value of `action` is `UNAUTHORIZED`, it means that the registration access token used by
- the client configuration request (RFC 7592) is invalid, or the client application which the token
- is tied to does not exist any longer or is invalid.
- The HTTP status of the response returned to the client application must be "401 Unauthorized" and
- the content type must be `application/json`.
- The value of `responseContent` is a JSON string which describes the error, so it can be used as
- the entity body of the response.
-
- ---
-
- The following illustrates the response which the endpoint implementation should generate and return
- to the client application.
- ```
- HTTP/1.1 401 Unauthorized
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
- NOTE: The `UNAUTHORIZED` value was added in October, 2021. See the description of
- `Service.unauthorizedOnClientConfigSupported` for details.
-
- ## UPDATED
-
- When the value of `action` is `UPDATED`, it means that the request from the client or developer is
- valid.
- The authorization server implementation should generate a response to the client or developer with
- "200 OK" and `application/json`.
- The `responseContent` a JSON string which can be used as the entity body of the response.
-
- ---
-
- The following illustrates the response which the authorization server implementation should generate
- and return to the client or developer.
- ```
- HTTP/1.1 200 OK
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
parameters:
- in: path
name: serviceId
@@ -6422,95 +6512,101 @@ paths:
Delete a dynamically registered client. This API is supposed to be used to implement a client
registration management endpoint that complies with [RFC 7592](https://datatracker.ietf.org/doc/html/rfc7592)
(OAuth 2.0 Dynamic Registration Management).
+ x-mint:
+ metadata:
+ description: "Delete a dynamically registered client. This API is supposed to be used to implement a client registration management endpoint that complies with [RFC 7592](https://datatracker.ietf.org/doc/html/rfc7592) (OAuth 2.0 Dynamic Registration Management)."
+ content: |
+
+ This API is supposed to be called from the within the implementation of the client registration
+ management endpoint of the authorization server. The authorization server implementation should
+ retrieve the value of `action` from the response and take the following steps according to the value.
+
+ ## INTERNAL_SERVER_ERROR
+
+ When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the API call from the authorization
+ server implementation was wrong or that an error occurred in Authlete.
+ In either case, from a viewpoint of the client or developer, it is an error on the server side.
+ Therefore, the authorization server implementation should generate a response with "500 Internal
+ Server Error"s and `application/json`.
+ The value of `responseContent` is a JSON string which describes the error, so it can be used as
+ the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the authorization server implementation should generate
+ and return to the client or developer.
+ ```
+ HTTP/1.1 500 Internal Server Error
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+ The endpoint implementation may return another different response to the client or developer since
+ "500 Internal Server Error" is not required by the specification.
+
+ ## BAD_REQUEST
+
+ When the value of `action` is `BAD_REQUEST`, it means that the request from the client or developer
+ was wrong.
+ The authorization server implementation should generate a response with "400 Bad Request" and `application/json`.
+ The value of `responseContent` is a JSON string which describes the error, so it can be used as
+ the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the authorization server implementation should generate
+ and return to the client or developer.
+ ```
+ HTTP/1.1 400 Bad Request
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
+ ## UNAUTHORIZED
+
+ When the value of `action` is `UNAUTHORIZED`, it means that the registration access token used by
+ the client configuration request (RFC 7592) is invalid, or the client application which the token
+ is tied to does not exist any longer or is invalid.
+ The HTTP status of the response returned to the client application must be "401 Unauthorized" and
+ the content type must be `application/json`.
+ The value of `responseContent` is a JSON string which describes the error, so it can be used as
+ the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the endpoint implementation should generate and return
+ to the client application.
+ ```
+ HTTP/1.1 401 Unauthorized
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+ NOTE: The `UNAUTHORIZED` value was added in October, 2021. See the description of
+ `Service.unauthorizedOnClientConfigSupported` for details.
+
+ ## DELETED
+
+ When the value of `action` is `DELETED`, it means that the request from the client or developer is
+ valid.
+ The authorization server implementation should generate a response to the client or developer with
+ "204 No Content".
+
+ ---
+
+ The following illustrates the response which the authorization server implementation should generate
+ and return to the client or developer.
+ ```
+ HTTP/1.1 204 No Content
+ Cache-Control: no-store
+ Pragma: no-cache
+ ```
+
- This API is supposed to be called from the within the implementation of the client registration
- management endpoint of the authorization server. The authorization server implementation should
- retrieve the value of `action` from the response and take the following steps according to the value.
-
- ## INTERNAL_SERVER_ERROR
-
- When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the API call from the authorization
- server implementation was wrong or that an error occurred in Authlete.
- In either case, from a viewpoint of the client or developer, it is an error on the server side.
- Therefore, the authorization server implementation should generate a response with "500 Internal
- Server Error"s and `application/json`.
- The value of `responseContent` is a JSON string which describes the error, so it can be used as
- the entity body of the response.
-
- ---
-
- The following illustrates the response which the authorization server implementation should generate
- and return to the client or developer.
- ```
- HTTP/1.1 500 Internal Server Error
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
- The endpoint implementation may return another different response to the client or developer since
- "500 Internal Server Error" is not required by the specification.
-
- ## BAD_REQUEST
-
- When the value of `action` is `BAD_REQUEST`, it means that the request from the client or developer
- was wrong.
- The authorization server implementation should generate a response with "400 Bad Request" and `application/json`.
- The value of `responseContent` is a JSON string which describes the error, so it can be used as
- the entity body of the response.
-
- ---
-
- The following illustrates the response which the authorization server implementation should generate
- and return to the client or developer.
- ```
- HTTP/1.1 400 Bad Request
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
-
- ## UNAUTHORIZED
-
- When the value of `action` is `UNAUTHORIZED`, it means that the registration access token used by
- the client configuration request (RFC 7592) is invalid, or the client application which the token
- is tied to does not exist any longer or is invalid.
- The HTTP status of the response returned to the client application must be "401 Unauthorized" and
- the content type must be `application/json`.
- The value of `responseContent` is a JSON string which describes the error, so it can be used as
- the entity body of the response.
-
- ---
-
- The following illustrates the response which the endpoint implementation should generate and return
- to the client application.
- ```
- HTTP/1.1 401 Unauthorized
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
- NOTE: The `UNAUTHORIZED` value was added in October, 2021. See the description of
- `Service.unauthorizedOnClientConfigSupported` for details.
-
- ## DELETED
-
- When the value of `action` is `DELETED`, it means that the request from the client or developer is
- valid.
- The authorization server implementation should generate a response to the client or developer with
- "204 No Content".
-
- ---
-
- The following illustrates the response which the authorization server implementation should generate
- and return to the client or developer.
- ```
- HTTP/1.1 204 No Content
- Cache-Control: no-store
- Pragma: no-cache
- ```
parameters:
- in: path
name: serviceId
@@ -6590,268 +6686,274 @@ paths:
This API parses request parameters of a [backchannel authentication request](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_request)
and returns necessary data for the authorization server implementation to process the backchannel
authentication request further.
+ x-mint:
+ metadata:
+ description: "This API parses request parameters of a [backchannel authentication request](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_request) and returns necessary data for the authorization server implementation to process the backchannel authentication request further."
+ content: |
+
+ This API is supposed to be called from within the implementation of the [backchannel authentication
+ endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_endpoint)
+ of the service. The endpoint implementation must extract the request parameters from the
+ backchannel authentication request from the client application and pass them as the value of parameters
+ request parameter for Authlete's `/backchannel/authentication` API.
+ The value of parameters is the entire entity body (which is formatted in `application/x-www-form-urlencoded`)
+ of the request from the client application.
+ The following code snippet is an example in JAX-RS showing how to extract request parameters from
+ the backchannel authentication request.
+ ```java
+ @POST
+ @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
+ public Response post(String parameters)
+ {
+ // 'parameters' is the entity body of the backchannel authentication request.
+ ......
+ }
+ ```
+ The endpoint implementation does not have to parse the request parameters from the client application
+ because Authlete's `/backchannel/authentication` API does it.
+ The response from `/backchannel/authentication` API has various parameters. Among them, it is `action`
+ parameter that the authorization server implementation should check first because it denotes the
+ next action that the authorization server implementation should take. According to the value of
+ `action`, the service implementation must take the steps described below.
+
+ ## INTERNAL_SERVER_ERROR
+
+ When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization
+ server implementation was wrong or that an error occurred in Authlete.
+ In either case, from the viewpoint of the client application, it is an error on the server side.
+ Therefore, the service implementation should generate a response to the client application with
+ HTTP status of "500 Internal Server Error" and `application/json`.
+ The value of `responseContent` is a JSON string which describes the error, so it can be used
+ as the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the service implementation should generate and return
+ to the client application.
+ ```
+ HTTP/1.1 500 Internal Server Error
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
- This API is supposed to be called from within the implementation of the [backchannel authentication
- endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_endpoint)
- of the service. The endpoint implementation must extract the request parameters from the
- backchannel authentication request from the client application and pass them as the value of parameters
- request parameter for Authlete's `/backchannel/authentication` API.
- The value of parameters is the entire entity body (which is formatted in `application/x-www-form-urlencoded`)
- of the request from the client application.
- The following code snippet is an example in JAX-RS showing how to extract request parameters from
- the backchannel authentication request.
- ```java
- @POST
- @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
- public Response post(String parameters)
- {
- // 'parameters' is the entity body of the backchannel authentication request.
- ......
- }
- ```
- The endpoint implementation does not have to parse the request parameters from the client application
- because Authlete's `/backchannel/authentication` API does it.
- The response from `/backchannel/authentication` API has various parameters. Among them, it is `action`
- parameter that the authorization server implementation should check first because it denotes the
- next action that the authorization server implementation should take. According to the value of
- `action`, the service implementation must take the steps described below.
-
- ## INTERNAL_SERVER_ERROR
-
- When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization
- server implementation was wrong or that an error occurred in Authlete.
- In either case, from the viewpoint of the client application, it is an error on the server side.
- Therefore, the service implementation should generate a response to the client application with
- HTTP status of "500 Internal Server Error" and `application/json`.
- The value of `responseContent` is a JSON string which describes the error, so it can be used
- as the entity body of the response.
-
- ---
-
- The following illustrates the response which the service implementation should generate and return
- to the client application.
- ```
- HTTP/1.1 500 Internal Server Error
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
-
- ## BAD_REQUEST
-
- When the value of `action` is `BAD_REQUEST`, it means that the request from the client application
- is invalid.
- The authorization server implementation should generate a response to the client application with
- "400 Bad Request" and `application/json`.
- The value of `responseContent` is a JSON string which describes the error, so it can be used as
- the entity body of the response.
-
- ---
-
- The following illustrates the response which the service implementation should generate and return
- to the client application.
- ```
- HTTP/1.1 400 Bad Request
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
-
- ## UNAUTHORIZED
-
- When the value of `action` is `UNAUTHORIZED`, it means that client authentication of the backchannel
- authentication request failed. Note that client authentication is always required at the backchannel
- authentication endpoint. This implies that public clients are not allowed to use the backchannel
- authentication endpoint.
- The authorization server implementation should generate a response to the client application with
- "401 Unauthorized" and `application/json`.
- The value of `responseContent` is a JSON string which describes the error, so it can be used as
- the entity body of the response.
-
- ---
-
- The following illustrates the response which the service implementation must generate and return
- to the client application.
- ```
- HTTP/1.1 401 Unauthorized
- WWW-Authenticate: (challenge)
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
-
- ## USER_IDENTIFICATION
-
- When the value of `action` is `USER_IDENTIFICATION`, it means that the backchannel authentication
- request from the client application is valid. The authorization server implementation has to follow
- the steps below.
-
- **[1] END-USER IDENTIFICATION**
-
- The first step is to determine the subject (= unique identifier) of the end-user from whom the
- client application wants to get authorization.
- According to the CIBA specification, a backchannel authentication request contains one (and only
- one) of the `login_hint_token`, `id_token_hint` and `login_hint` request parameters as a hint
- by which the authorization server identifies the subject of an end-user.
- The authorization server implementation can know which hint is included in the backchannel authentication
- request by the `hintType` parameter. For example, when the value of the parameter `LOGIN_HINT`,
- it means that the backchannel authentication request contains the `login_hint` request parameter
- as a hint.
- The value of the `hint` parameter is the value of the hint. For example, when the value of the
- `hintType` parameter is `LOGIN_HINT`, The value of the `hint` parameter is the value of the `login_hint`
- request parameter.
- It is up to the authorization server implementation how to determine the subject of the end-user
- from the hint. Only when the `id_token_hint` request parameter is used, authorization server
- implementation can use the sub response parameter, which holds the value of the sub claim in the
- `id_token_hint` request parameter.
+ ## BAD_REQUEST
- **[2] END-USER IDENTIFICATION ERROR**
+ When the value of `action` is `BAD_REQUEST`, it means that the request from the client application
+ is invalid.
+ The authorization server implementation should generate a response to the client application with
+ "400 Bad Request" and `application/json`.
+ The value of `responseContent` is a JSON string which describes the error, so it can be used as
+ the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the service implementation should generate and return
+ to the client application.
+ ```
+ HTTP/1.1 400 Bad Request
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
+ ## UNAUTHORIZED
+
+ When the value of `action` is `UNAUTHORIZED`, it means that client authentication of the backchannel
+ authentication request failed. Note that client authentication is always required at the backchannel
+ authentication endpoint. This implies that public clients are not allowed to use the backchannel
+ authentication endpoint.
+ The authorization server implementation should generate a response to the client application with
+ "401 Unauthorized" and `application/json`.
+ The value of `responseContent` is a JSON string which describes the error, so it can be used as
+ the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the service implementation must generate and return
+ to the client application.
+ ```
+ HTTP/1.1 401 Unauthorized
+ WWW-Authenticate: (challenge)
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
+ ## USER_IDENTIFICATION
+
+ When the value of `action` is `USER_IDENTIFICATION`, it means that the backchannel authentication
+ request from the client application is valid. The authorization server implementation has to follow
+ the steps below.
+
+ **[1] END-USER IDENTIFICATION**
+
+ The first step is to determine the subject (= unique identifier) of the end-user from whom the
+ client application wants to get authorization.
+ According to the CIBA specification, a backchannel authentication request contains one (and only
+ one) of the `login_hint_token`, `id_token_hint` and `login_hint` request parameters as a hint
+ by which the authorization server identifies the subject of an end-user.
+ The authorization server implementation can know which hint is included in the backchannel authentication
+ request by the `hintType` parameter. For example, when the value of the parameter `LOGIN_HINT`,
+ it means that the backchannel authentication request contains the `login_hint` request parameter
+ as a hint.
+ The value of the `hint` parameter is the value of the hint. For example, when the value of the
+ `hintType` parameter is `LOGIN_HINT`, The value of the `hint` parameter is the value of the `login_hint`
+ request parameter.
+ It is up to the authorization server implementation how to determine the subject of the end-user
+ from the hint. Only when the `id_token_hint` request parameter is used, authorization server
+ implementation can use the sub response parameter, which holds the value of the sub claim in the
+ `id_token_hint` request parameter.
+
+ **[2] END-USER IDENTIFICATION ERROR**
+
+ There are some cases where the authorization server implementation encounters an error during
+ the user identification process. In any error case, the service implementation has to return an
+ HTTP response with the error response parameter to the client application. The following is an
+ example of such error responses.
+ ```
+ HTTP/1.1 400 Bad Request
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ { "error":"unknown_user_id" }
+ ```
+ Authlete provides `/backchannel/authentication/fail` API that builds the response body (JSON)
+ of an error response. However, because it is easy to build an error response manually, you may
+ choose not to call the API. One good thing in using the API is that the API call can trigger
+ deletion of the ticket which has been issued from Authlete's `/backchannel/authentication` API.
+ If you don't call `/backchannel/authentication/fail` API, the ticket will continue to exist in
+ the database until it is cleaned up by the batch program after the ticket expires.
+ Possible error cases that the authorization server implementation itself has to handle are as
+ follows. Other error cases have already been covered by `/backchannel/authentication` API.
+ - `expired_login_hint_token`
+ The authorization server implementation detected that the hint presented by the `login_hint_token`
+ request parameter has expired.
+ Note that the format of `login_hint_token` is not described in the CIBA Core spec at all and
+ so there is no consensus on how to detect expiration of `login_hint_token`. Interpretation
+ of `login_hint_token` is left to each authorization server implementation.
+ - `unknown_user_id`
+ The authorization server implementation could not determine the subject of the end-user by
+ the presented hint.
+ - `unauthorized_client`
+ The authorization server implementation has custom rules to reject backchannel authentication
+ requests from some particular clients and found that the client which has made the backchannel
+ authentication request is one of the particular clients.
+ Note that `/backchannel/authentication` API does not return `action=USER_IDENTIFICATION` in
+ cases where the client does not exist or client authentication has failed. Therefore, the
+ authorization server implementation will never have to use the error code `unauthorized_client`
+ unless the server has intentionally implemented custom rules to reject backchannel authentication
+ requests based on clients.
+ - `missing_user_code`
+ The authorization server implementation has custom rules to require that a backchannel authentication
+ request include a user code for some particular users and found that the user identified by
+ the hint is one of the particular users.
+ Note that `/backchannel/authentication` API does not return `action=USER_IDENTIFICATION` when
+ both the `backchannel_user_code_parameter_supported` metadata of the server and the
+ `backchannel_user_code_parameter` metadata of the client are true and the backchannel authentication
+ request does not include the user_code request parameter. In this case, `/backchannel/authentication`
+ API returns action=BAD_REQUEST with JSON containing `"error":"missing_user_code"`. Therefore,
+ the authorization server implementation will never have to use the error code `missing_user_code`
+ unless the server has intentionally implemented custom rules to require a user code based
+ on users even in the case where the `backchannel_user_code_parameter` metadata of the client
+ which has made the backchannel authentication request is `false`.
+ - `invalid_user_code`
+ The authorization server implementation detected that the presented user code is invalid.
+ Note that the format of user_code is not described in the CIBA Core spec at all and so there
+ is no consensus on how to judge whether a user code is valid or not. It is up to each authorization
+ server implementation how to handle user codes.
+ - `invalid_binding_message`
+ The authorization server implementation detected that the presented binding message is invalid.
+ Note that the format of binding_message is not described in the CIBA Core spec at all and
+ so there is no consensus on how to judge whether a binding message is valid or not. It is
+ up to each authorization server implementation how to handle binding messages.
+ - `invalid_target`
+ The authorization server implementation rejects the requested target resources.
+ The error code invalid_target is from "Resource Indicators for OAuth 2.0". The specification
+ defines the resource request parameter. By using the parameter, client applications can request
+ target resources that should be bound to the access token being issued. If the authorization
+ server wants to reject the request, call `/backchannel/authentication/fail` API with `INVALID_TARGET`.
+ - `access_denined`
+ The authorization server implementation has custom rules to reject backchannel authentication
+ requests without asking the end-user and respond to the client as if the end-user had rejected
+ the request in some particular cases and found that the backchannel authentication request
+ is one of the particular cases.
+ The authorization server implementation will never have to use the error code `access_denied`
+ at this timing unless the server has intentionally implemented custom rules to reject backchannel
+ authentication requests without asking the end-user and respond to the client as if the end-user
+ had rejected the request.
+
+ **[3] AUTH_REQ_ID ISSUE**
+
+ If the authorization server implementation has successfully determined the subject of the end-user,
+ the next action is to return an HTTP response to the client application which contains `auth_req_id`.
+ Authlete provides `/backchannel/authentication/issue` API which generates a JSON containing `auth_req_id`,
+ so, your next action is (1) call the API, (2) receive the response from the API, (3) build a response
+ to the client application using the content of the API response, and (4) return the response to
+ the client application. See the description of `/backchannel/authentication/issue` API for details.
+
+ **[4] END-USER AUTHENTICATION AND AUTHORIZATION**
+
+ After sending a JSON containing `auth_req_id` back to the client application, the service implementation
+ starts to communicate with an authentication device of the end-user. It is assumed that end-user
+ authentication is performed on the authentication device and the end-user confirms the content of
+ the backchannel authentication request and grants authorization to the client application if everything
+ is okay. The authorization server implementation must be able to receive the result of the end-user
+ authentication and authorization from the authentication device.
+ How to communicate with an authentication device and achieve end-user authentication and authorization
+ is up to each authorization server implementation, but the following request parameters of the backchannel
+ authentication request should be taken into consideration in any implementation.
+ - `acr_values`
+ A backchannel authentication request may contain an array of ACRs (Authentication Context Class
+ References) in preference order. If multiple authentication devices are registered for the end-user,
+ the authorization server implementation should take the ACRs into consideration when selecting
+ the best authentication device.
+ - `scope`
+ A backchannel authentication request always contains a list of scopes. At least, `openid` is
+ included in the list (otherwise `/backchannel/authentication` API returns `action=BAD_REQUEST`).
+ It would be better to show the requested scopes to the end-user on the authentication device
+ or somewhere appropriate.
+ If the scope request parameter contains `address`, `email`, `phone` and/or `profile`, they are
+ interpreted as defined in "5.4. Requesting Claims using Scope Values of OpenID Connect Core 1.0".
+ That is, they are expanded into a list of claim names. The claimNames parameter returns the expanded
+ result.
+ - `binding_message`
+ A backchannel authentication request may contain a binding message. It is a human readable identifier
+ or message intended to be displayed on both the consumption device (client application) and the
+ authentication device.
+ - `user_code`
+ A backchannel authentication request may contain a user code. It is a secret code, such as password
+ or pin, known only to the end-user but verifiable by the authorization server. The user code should
+ be used to authorize sending a request to the authentication device.
+
+ **[5] END-USER AUTHENTICATION AND AUTHORIZATION COMPLETION**
+
+ After receiving the result of end-user authentication and authorization, the authorization server
+ implementation must call Authlete's `/backchannel/authentication/complete` API to tell Authlete
+ the result and pass necessary data so that Authlete can generate an ID token, an access token and
+ optionally a refresh token. See the description of the API for details.
+
+ **[6] CLIENT NOTIFICATION**
+
+ When the backchannel token delivery mode is either `ping` or `push`, the authorization server implementation
+ must send a notification to the pre-registered notification endpoint of the client after the end-user
+ authentication and authorization. In this case, the `action` parameter in a response from `/backchannel/authentication/complete`
+ API is `NOTIFICATION`. See the description of `/backchannel/authentication/complete` API for details.
+
+ **[7] TOKEN REQUEST**
+
+ When the backchannel token delivery mode is either `ping` or `poll`, the client application will make
+ a token request to the token endpoint to get an ID token, an access token and optionally a refresh
+ token.
+ A token request that corresponds to a backchannel authentication request uses `urn:openid:params:grant-type:ciba`
+ as the value of the `grant_type` request parameter. Authlete's `/auth/token` API recognizes the
+ grant type automatically and behaves properly, so the existing token endpoint implementation does
+ not have to be changed to support CIBA.
+
- There are some cases where the authorization server implementation encounters an error during
- the user identification process. In any error case, the service implementation has to return an
- HTTP response with the error response parameter to the client application. The following is an
- example of such error responses.
- ```
- HTTP/1.1 400 Bad Request
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- { "error":"unknown_user_id" }
- ```
- Authlete provides `/backchannel/authentication/fail` API that builds the response body (JSON)
- of an error response. However, because it is easy to build an error response manually, you may
- choose not to call the API. One good thing in using the API is that the API call can trigger
- deletion of the ticket which has been issued from Authlete's `/backchannel/authentication` API.
- If you don't call `/backchannel/authentication/fail` API, the ticket will continue to exist in
- the database until it is cleaned up by the batch program after the ticket expires.
- Possible error cases that the authorization server implementation itself has to handle are as
- follows. Other error cases have already been covered by `/backchannel/authentication` API.
- - `expired_login_hint_token`
- The authorization server implementation detected that the hint presented by the `login_hint_token`
- request parameter has expired.
- Note that the format of `login_hint_token` is not described in the CIBA Core spec at all and
- so there is no consensus on how to detect expiration of `login_hint_token`. Interpretation
- of `login_hint_token` is left to each authorization server implementation.
- - `unknown_user_id`
- The authorization server implementation could not determine the subject of the end-user by
- the presented hint.
- - `unauthorized_client`
- The authorization server implementation has custom rules to reject backchannel authentication
- requests from some particular clients and found that the client which has made the backchannel
- authentication request is one of the particular clients.
- Note that `/backchannel/authentication` API does not return `action=USER_IDENTIFICATION` in
- cases where the client does not exist or client authentication has failed. Therefore, the
- authorization server implementation will never have to use the error code `unauthorized_client`
- unless the server has intentionally implemented custom rules to reject backchannel authentication
- requests based on clients.
- - `missing_user_code`
- The authorization server implementation has custom rules to require that a backchannel authentication
- request include a user code for some particular users and found that the user identified by
- the hint is one of the particular users.
- Note that `/backchannel/authentication` API does not return `action=USER_IDENTIFICATION` when
- both the `backchannel_user_code_parameter_supported` metadata of the server and the
- `backchannel_user_code_parameter` metadata of the client are true and the backchannel authentication
- request does not include the user_code request parameter. In this case, `/backchannel/authentication`
- API returns action=BAD_REQUEST with JSON containing `"error":"missing_user_code"`. Therefore,
- the authorization server implementation will never have to use the error code `missing_user_code`
- unless the server has intentionally implemented custom rules to require a user code based
- on users even in the case where the `backchannel_user_code_parameter` metadata of the client
- which has made the backchannel authentication request is `false`.
- - `invalid_user_code`
- The authorization server implementation detected that the presented user code is invalid.
- Note that the format of user_code is not described in the CIBA Core spec at all and so there
- is no consensus on how to judge whether a user code is valid or not. It is up to each authorization
- server implementation how to handle user codes.
- - `invalid_binding_message`
- The authorization server implementation detected that the presented binding message is invalid.
- Note that the format of binding_message is not described in the CIBA Core spec at all and
- so there is no consensus on how to judge whether a binding message is valid or not. It is
- up to each authorization server implementation how to handle binding messages.
- - `invalid_target`
- The authorization server implementation rejects the requested target resources.
- The error code invalid_target is from "Resource Indicators for OAuth 2.0". The specification
- defines the resource request parameter. By using the parameter, client applications can request
- target resources that should be bound to the access token being issued. If the authorization
- server wants to reject the request, call `/backchannel/authentication/fail` API with `INVALID_TARGET`.
- - `access_denined`
- The authorization server implementation has custom rules to reject backchannel authentication
- requests without asking the end-user and respond to the client as if the end-user had rejected
- the request in some particular cases and found that the backchannel authentication request
- is one of the particular cases.
- The authorization server implementation will never have to use the error code `access_denied`
- at this timing unless the server has intentionally implemented custom rules to reject backchannel
- authentication requests without asking the end-user and respond to the client as if the end-user
- had rejected the request.
-
- **[3] AUTH_REQ_ID ISSUE**
-
- If the authorization server implementation has successfully determined the subject of the end-user,
- the next action is to return an HTTP response to the client application which contains `auth_req_id`.
- Authlete provides `/backchannel/authentication/issue` API which generates a JSON containing `auth_req_id`,
- so, your next action is (1) call the API, (2) receive the response from the API, (3) build a response
- to the client application using the content of the API response, and (4) return the response to
- the client application. See the description of `/backchannel/authentication/issue` API for details.
-
- **[4] END-USER AUTHENTICATION AND AUTHORIZATION**
-
- After sending a JSON containing `auth_req_id` back to the client application, the service implementation
- starts to communicate with an authentication device of the end-user. It is assumed that end-user
- authentication is performed on the authentication device and the end-user confirms the content of
- the backchannel authentication request and grants authorization to the client application if everything
- is okay. The authorization server implementation must be able to receive the result of the end-user
- authentication and authorization from the authentication device.
- How to communicate with an authentication device and achieve end-user authentication and authorization
- is up to each authorization server implementation, but the following request parameters of the backchannel
- authentication request should be taken into consideration in any implementation.
- - `acr_values`
- A backchannel authentication request may contain an array of ACRs (Authentication Context Class
- References) in preference order. If multiple authentication devices are registered for the end-user,
- the authorization server implementation should take the ACRs into consideration when selecting
- the best authentication device.
- - `scope`
- A backchannel authentication request always contains a list of scopes. At least, `openid` is
- included in the list (otherwise `/backchannel/authentication` API returns `action=BAD_REQUEST`).
- It would be better to show the requested scopes to the end-user on the authentication device
- or somewhere appropriate.
- If the scope request parameter contains `address`, `email`, `phone` and/or `profile`, they are
- interpreted as defined in "5.4. Requesting Claims using Scope Values of OpenID Connect Core 1.0".
- That is, they are expanded into a list of claim names. The claimNames parameter returns the expanded
- result.
- - `binding_message`
- A backchannel authentication request may contain a binding message. It is a human readable identifier
- or message intended to be displayed on both the consumption device (client application) and the
- authentication device.
- - `user_code`
- A backchannel authentication request may contain a user code. It is a secret code, such as password
- or pin, known only to the end-user but verifiable by the authorization server. The user code should
- be used to authorize sending a request to the authentication device.
-
- **[5] END-USER AUTHENTICATION AND AUTHORIZATION COMPLETION**
-
- After receiving the result of end-user authentication and authorization, the authorization server
- implementation must call Authlete's `/backchannel/authentication/complete` API to tell Authlete
- the result and pass necessary data so that Authlete can generate an ID token, an access token and
- optionally a refresh token. See the description of the API for details.
-
- **[6] CLIENT NOTIFICATION**
-
- When the backchannel token delivery mode is either `ping` or `push`, the authorization server implementation
- must send a notification to the pre-registered notification endpoint of the client after the end-user
- authentication and authorization. In this case, the `action` parameter in a response from `/backchannel/authentication/complete`
- API is `NOTIFICATION`. See the description of `/backchannel/authentication/complete` API for details.
-
- **[7] TOKEN REQUEST**
-
- When the backchannel token delivery mode is either `ping` or `poll`, the client application will make
- a token request to the token endpoint to get an ID token, an access token and optionally a refresh
- token.
- A token request that corresponds to a backchannel authentication request uses `urn:openid:params:grant-type:ciba`
- as the value of the `grant_type` request parameter. Authlete's `/auth/token` API recognizes the
- grant type automatically and behaves properly, so the existing token endpoint implementation does
- not have to be changed to support CIBA.
parameters:
- in: path
name: serviceId
@@ -6950,77 +7052,83 @@ paths:
description: |
This API prepares JSON that contains an `auth_req_id`. The JSON should be used as the response body
of the response which is returned to the client from the [backchannel authentication endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_endpoint)
+ x-mint:
+ metadata:
+ description: "This API prepares JSON that contains an `auth_req_id`. The JSON should be used as the response body of the response which is returned to the client from the [backchannel authentication endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_endpoint)"
+ content: |
+
+ This API is supposed to be called from within the implementation of the backchannel authentication
+ endpoint of the service in order to generate a successful response to the client application.
+ The description of the `/backchannel/authentication` API describes the timing when this API should
+ be called and the meaning of request parameters. See [AUTH_REQ_ID ISSUE] in `USER_IDENTIFICATION`.
+ The response from `/backchannel/authentication/issue` API has some parameters. Among them, it is
+ `action` parameter that the authorization server implementation should check first because it denotes
+ the next `action` that the authorization server implementation should take. According to the value
+ of `action`, the authorization server implementation must take the steps described below.
+ ```java
+ @POST
+ @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
+ public Response post(String parameters)
+ {
+ // 'parameters' is the entity body of the backchannel authentication request.
+ ......
+ }
+ ```
+ The endpoint implementation does not have to parse the request parameters from the client application
+ because Authlete's `/backchannel/authentication` API does it.
+ The response from `/backchannel/authentication` API has various parameters. Among them, it is `action`
+ parameter that the authorization server implementation should check first because it denotes the
+ next action that the authorization server implementation should take. According to the value of
+ `action`, the service implementation must take the steps described below.
+
+ ## INTERNAL_SERVER_ERROR
+
+ When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization
+ server implementation was wrong or that an error occurred in Authlete.
+ In either case, from the viewpoint of the client application, it is an error on the server side.
+ Therefore, the service implementation should generate a response to the client application with
+ HTTP status of "500 Internal Server Error" and `application/json`.
+ The value of `responseContent` is a JSON string which describes the error, so it can be used as
+ the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the service implementation should generate and return
+ to the client application.
+ ```
+ HTTP/1.1 500 Internal Server Error
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
+ ## INVALID_TICKET
+
+ When the value of `action` is `INVALID_TICKET`, it means that the ticket included in the API call
+ was invalid. For example, it does not exist or has expired.
+ From a viewpoint of the client application, this is an error on the server side. Therefore, the
+ authorization server implementation should generate a response to the client application with
+ "500 Internal Server Error" and `application/json`.
+ You can build an error response in the same way as shown in the description for the case of `INTERNAL_SERVER_ERROR`.
+
+ ## OK
+
+ When the value of `action` is `OK`, it means that Authlete has succeeded in preparing JSON that
+ contains an `auth_req_id`. The JSON should be used as the response body of the response that is
+ returned to the client from the backchannel authentication endpoint. `responseContent` contains
+ the JSON.
+ The following illustrates the response which the authorization server implementation should generate
+ and return to the client application.
+ ```
+ HTTP/1.1 200 OK
+ Content-Type: text/html;charset=UTF-8
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
- This API is supposed to be called from within the implementation of the backchannel authentication
- endpoint of the service in order to generate a successful response to the client application.
- The description of the `/backchannel/authentication` API describes the timing when this API should
- be called and the meaning of request parameters. See [AUTH_REQ_ID ISSUE] in `USER_IDENTIFICATION`.
- The response from `/backchannel/authentication/issue` API has some parameters. Among them, it is
- `action` parameter that the authorization server implementation should check first because it denotes
- the next `action` that the authorization server implementation should take. According to the value
- of `action`, the authorization server implementation must take the steps described below.
- ```java
- @POST
- @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
- public Response post(String parameters)
- {
- // 'parameters' is the entity body of the backchannel authentication request.
- ......
- }
- ```
- The endpoint implementation does not have to parse the request parameters from the client application
- because Authlete's `/backchannel/authentication` API does it.
- The response from `/backchannel/authentication` API has various parameters. Among them, it is `action`
- parameter that the authorization server implementation should check first because it denotes the
- next action that the authorization server implementation should take. According to the value of
- `action`, the service implementation must take the steps described below.
-
- ## INTERNAL_SERVER_ERROR
-
- When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization
- server implementation was wrong or that an error occurred in Authlete.
- In either case, from the viewpoint of the client application, it is an error on the server side.
- Therefore, the service implementation should generate a response to the client application with
- HTTP status of "500 Internal Server Error" and `application/json`.
- The value of `responseContent` is a JSON string which describes the error, so it can be used as
- the entity body of the response.
-
- ---
-
- The following illustrates the response which the service implementation should generate and return
- to the client application.
- ```
- HTTP/1.1 500 Internal Server Error
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
-
- ## INVALID_TICKET
-
- When the value of `action` is `INVALID_TICKET`, it means that the ticket included in the API call
- was invalid. For example, it does not exist or has expired.
- From a viewpoint of the client application, this is an error on the server side. Therefore, the
- authorization server implementation should generate a response to the client application with
- "500 Internal Server Error" and `application/json`.
- You can build an error response in the same way as shown in the description for the case of `INTERNAL_SERVER_ERROR`.
-
- ## OK
-
- When the value of `action` is `OK`, it means that Authlete has succeeded in preparing JSON that
- contains an `auth_req_id`. The JSON should be used as the response body of the response that is
- returned to the client from the backchannel authentication endpoint. `responseContent` contains
- the JSON.
- The following illustrates the response which the authorization server implementation should generate
- and return to the client application.
- ```
- HTTP/1.1 200 OK
- Content-Type: text/html;charset=UTF-8
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
parameters:
- in: path
name: serviceId
@@ -7098,33 +7206,39 @@ paths:
description: |
The API prepares JSON that contains an error. The JSON should be used as the response body of the
response which is returned to the client from the [backchannel authentication endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_endpoint).
+ x-mint:
+ metadata:
+ description: "The API prepares JSON that contains an error. The JSON should be used as the response body of the response which is returned to the client from the [backchannel authentication endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_endpoint)."
+ content: |
+
+ This API is supposed to be called from within the implementation of the [backchannel authentication
+ endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_endpoint)
+ of the service in order to generate an error response to the client application.
+ The response from `/backchannel/authentication/fails` API has some parameters. Among them, it is
+ `action` parameter that the authorization server implementation should check first because it denotes
+ the next action that the authorization server implementation should take. According to the value
+ of `action`, the authorization server implementation must take the steps described below.
- This API is supposed to be called from within the implementation of the [backchannel authentication
- endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_endpoint)
- of the service in order to generate an error response to the client application.
- The response from `/backchannel/authentication/fails` API has some parameters. Among them, it is
- `action` parameter that the authorization server implementation should check first because it denotes
- the next action that the authorization server implementation should take. According to the value
- of `action`, the authorization server implementation must take the steps described below.
+ ## INTERNAL_SERVER_ERROR
- ## INTERNAL_SERVER_ERROR
+ When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that (1) the `reason` request parameter
+ of the API call was `SERVER_ERROR`, (2) an error occurred on Authlete side, or (3) the request parameters
+ of the API call were wrong. In this case, the authorization server implementation should return
+ a "500 Internal Server Error" response to the client application. However, in most cases, commercial
+ implementations prefer to use other HTTP status code than 5xx.
- When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that (1) the `reason` request parameter
- of the API call was `SERVER_ERROR`, (2) an error occurred on Authlete side, or (3) the request parameters
- of the API call were wrong. In this case, the authorization server implementation should return
- a "500 Internal Server Error" response to the client application. However, in most cases, commercial
- implementations prefer to use other HTTP status code than 5xx.
+ ## BAD_REQUEST
- ## BAD_REQUEST
+ When the value of `action` is `BAD_REQUEST`, the authorization server implementation should return a
+ "400 Bad Request" response to the client application.
- When the value of `action` is `BAD_REQUEST`, the authorization server implementation should return a
- "400 Bad Request" response to the client application.
+ ## FORBIDDEN
- ## FORBIDDEN
+ When the value of `action` is `FORBIDDEN`, it means that the `reason` request parameter of the API call
+ was `ACCESS_DENIED`. In this case, the backchannel authentication endpoint of the authorization
+ server implementation should return a "403 Forbidden" response to the client application.
+
- When the value of `action` is `FORBIDDEN`, it means that the `reason` request parameter of the API call
- was `ACCESS_DENIED`. In this case, the backchannel authentication endpoint of the authorization
- server implementation should return a "403 Forbidden" response to the client application.
parameters:
- in: path
name: serviceId
@@ -7200,91 +7314,97 @@ paths:
This API returns information about what action the authorization server should take after it receives
the result of end-user's decision about whether the end-user has approved or rejected a client application's
request on the authentication device.
+ x-mint:
+ metadata:
+ description: "This API returns information about what action the authorization server should take after it receives the result of end-user's decision about whether the end-user has approved or rejected a client application's request on the authentication device."
+ content: |
+
+ After the implementation of the backchannel authentication endpoint returns JSON containing an
+ `auth_req_id` to the client, the authorization server starts a background process that communicates
+ with the authentication device of the end-user. On the authentication device, end-user authentication
+ is performed and the end-user is asked whether they give authorization to the client or not. The
+ authorization server will receive the result of end-user authentication and authorization from
+ the authentication device.
+ After the authorization server receives the result from the authentication device, or even in the
+ case where the server gave up receiving a response from the authentication device for some reasons,
+ the server should call the `/backchannel/authentication/complete` API to tell Authlete the result.
+ When the end-user was authenticated and authorization was granted to the client by the end-user,
+ the authorization server should call the API with `result=AUTHORIZED`. In this successful case,
+ the `subject` request parameter is mandatory. If the token delivery mode is `push`, the API will generate
+ an access token, an ID token and optionally a refresh token. On the other hand, if the token delivery
+ mode is `poll` or `ping`, the API will just update the database record so that `/auth/token` API
+ can generate tokens later.
+ When the authorization server received the decision of the end-user from the authentication device
+ and it indicates that the end-user has rejected to give authorization to the client, the authorization
+ server should call the API with `result=ACCESS_DENIED`. In this case, if the token delivery mode
+ is `push`, the API will generate an error response that contains the error response parameter and
+ optionally the `error_description` and error_uri response parameters (if the `errorDescription`
+ and `errorUri` request parameters have been given). On the other hand, if the token delivery mode
+ is `poll` or `ping`, the API will just update the database record so that `/auth/token` API can
+ generate an error response later. In any token delivery mode, the value of the error parameter will
+ become `access_denied`.
+ When the authorization server could not get the result of end-user authentication and authorization
+ from the authentication device for some reasons, the authorization server should call the API with
+ `result=TRANSACTION_FAILED`. In this error case, the API will behave in the same way as in the case
+ of `ACCESS_DENIED`. The only difference is that `expired_token` is used as the value of the `error`
+ parameter.
+ The response from `/backchannel/authentication/complete` API has various parameters. Among them,
+ it is `action` parameter that the authorization server implementation should check first because
+ it denotes the next action that the authorization server implementation should take. According to
+ the value of `action`, the service implementation must take the steps described below.
+
+ ## SERVER_ERROR
+
+ When the value of `action` is `SERVER_ERROR`, it means either (1) that the request from the authorization
+ server to Authlete was wrong, or (2) that an error occurred on Authlete side.
+ When the backchannel token delivery mode is `ping` or `push`, `SERVER_ERROR` is used only when
+ an error is detected before the record of the ticket (which is included in the API call to `/backchannel/authentication/complete`)
+ is retrieved from the database successfully. If an error is detected after the record of the ticket
+ is retrieved from the database, `NOTIFICATION` is used instead of `SERVER_ERROR`.
+ When the backchannel token delivery mode is `poll`, `SERVER_ERROR` is used regardless of whether
+ it is before or after the record of the ticket is retrieved from the database.
+
+ ## NO_ACTION
+
+ When the value of `action` is `NO_ACTION`, it means that the authorization server does not have
+ to take any immediate action.
+ `NO_ACTION` is returned when the backchannel token delivery mode is `poll`. In this case, the client
+ will receive the final result at the token endpoint.
+
+ ## NOTIFICATION
+
+ When the value of `action` is `NOTIFICATION`, it means that the authorization server must send a
+ notification to the client notification endpoint.
+ According to the CIBA Core specification, the notification is an HTTP POST request whose request
+ body is JSON and whose `Authorization` header contains the client notification token, which was
+ included in the backchannel authentication request as the value of the `client_notification_token`
+ request parameter, as a bearer token.
+ When the backchannel token delivery mode is `ping`, the request body of the notification is JSON
+ which contains the `auth_req_id` property only. When the backchannel token delivery mode is `push`,
+ the request body will additionally contain an access token, an ID token and other properties. Note
+ that when the backchannel token delivery mode is `poll`, a notification does not have to be sent
+ to the client notification endpoint.
+ In error cases, in the ping mode, however, the content of a notification is not different from the
+ content in successful cases. That is, the notification contains the `auth_req_id` property only.
+ The client will know the error when it accesses the token endpoint. On the other hand, in the
+ `push` mode, in error cases, the content of a notification will include the `error` property instead
+ of an access token and an ID token. The client will know the error by detecting that error is included
+ in the notification.
+ In any case, the value of `responseContent` is JSON which can be used as the request body of the
+ notification.
+ The client notification endpoint that the notification should be sent to the value of the `clientNotificationEndpoint`
+ parameter. Likewise, the client notification token that the notification should include as a bearer
+ token is the `clientNotificationToken` parameter. With these methods, the notification can be built
+ like the following.
+ ```
+ POST {clientNotificationEndpoint} HTTP/1.1
+ HOST: {The host of clientNotificationEndpoint}
+ Authorization: Bearer {notificationToken}
+ Content-Type: application/json
+ {responseContent}
+ ```
+
- After the implementation of the backchannel authentication endpoint returns JSON containing an
- `auth_req_id` to the client, the authorization server starts a background process that communicates
- with the authentication device of the end-user. On the authentication device, end-user authentication
- is performed and the end-user is asked whether they give authorization to the client or not. The
- authorization server will receive the result of end-user authentication and authorization from
- the authentication device.
- After the authorization server receives the result from the authentication device, or even in the
- case where the server gave up receiving a response from the authentication device for some reasons,
- the server should call the `/backchannel/authentication/complete` API to tell Authlete the result.
- When the end-user was authenticated and authorization was granted to the client by the end-user,
- the authorization server should call the API with `result=AUTHORIZED`. In this successful case,
- the `subject` request parameter is mandatory. If the token delivery mode is `push`, the API will generate
- an access token, an ID token and optionally a refresh token. On the other hand, if the token delivery
- mode is `poll` or `ping`, the API will just update the database record so that `/auth/token` API
- can generate tokens later.
- When the authorization server received the decision of the end-user from the authentication device
- and it indicates that the end-user has rejected to give authorization to the client, the authorization
- server should call the API with `result=ACCESS_DENIED`. In this case, if the token delivery mode
- is `push`, the API will generate an error response that contains the error response parameter and
- optionally the `error_description` and error_uri response parameters (if the `errorDescription`
- and `errorUri` request parameters have been given). On the other hand, if the token delivery mode
- is `poll` or `ping`, the API will just update the database record so that `/auth/token` API can
- generate an error response later. In any token delivery mode, the value of the error parameter will
- become `access_denied`.
- When the authorization server could not get the result of end-user authentication and authorization
- from the authentication device for some reasons, the authorization server should call the API with
- `result=TRANSACTION_FAILED`. In this error case, the API will behave in the same way as in the case
- of `ACCESS_DENIED`. The only difference is that `expired_token` is used as the value of the `error`
- parameter.
- The response from `/backchannel/authentication/complete` API has various parameters. Among them,
- it is `action` parameter that the authorization server implementation should check first because
- it denotes the next action that the authorization server implementation should take. According to
- the value of `action`, the service implementation must take the steps described below.
-
- ## SERVER_ERROR
-
- When the value of `action` is `SERVER_ERROR`, it means either (1) that the request from the authorization
- server to Authlete was wrong, or (2) that an error occurred on Authlete side.
- When the backchannel token delivery mode is `ping` or `push`, `SERVER_ERROR` is used only when
- an error is detected before the record of the ticket (which is included in the API call to `/backchannel/authentication/complete`)
- is retrieved from the database successfully. If an error is detected after the record of the ticket
- is retrieved from the database, `NOTIFICATION` is used instead of `SERVER_ERROR`.
- When the backchannel token delivery mode is `poll`, `SERVER_ERROR` is used regardless of whether
- it is before or after the record of the ticket is retrieved from the database.
-
- ## NO_ACTION
-
- When the value of `action` is `NO_ACTION`, it means that the authorization server does not have
- to take any immediate action.
- `NO_ACTION` is returned when the backchannel token delivery mode is `poll`. In this case, the client
- will receive the final result at the token endpoint.
-
- ## NOTIFICATION
-
- When the value of `action` is `NOTIFICATION`, it means that the authorization server must send a
- notification to the client notification endpoint.
- According to the CIBA Core specification, the notification is an HTTP POST request whose request
- body is JSON and whose `Authorization` header contains the client notification token, which was
- included in the backchannel authentication request as the value of the `client_notification_token`
- request parameter, as a bearer token.
- When the backchannel token delivery mode is `ping`, the request body of the notification is JSON
- which contains the `auth_req_id` property only. When the backchannel token delivery mode is `push`,
- the request body will additionally contain an access token, an ID token and other properties. Note
- that when the backchannel token delivery mode is `poll`, a notification does not have to be sent
- to the client notification endpoint.
- In error cases, in the ping mode, however, the content of a notification is not different from the
- content in successful cases. That is, the notification contains the `auth_req_id` property only.
- The client will know the error when it accesses the token endpoint. On the other hand, in the
- `push` mode, in error cases, the content of a notification will include the `error` property instead
- of an access token and an ID token. The client will know the error by detecting that error is included
- in the notification.
- In any case, the value of `responseContent` is JSON which can be used as the request body of the
- notification.
- The client notification endpoint that the notification should be sent to the value of the `clientNotificationEndpoint`
- parameter. Likewise, the client notification token that the notification should include as a bearer
- token is the `clientNotificationToken` parameter. With these methods, the notification can be built
- like the following.
- ```
- POST {clientNotificationEndpoint} HTTP/1.1
- HOST: {The host of clientNotificationEndpoint}
- Authorization: Bearer {notificationToken}
- Content-Type: application/json
- {responseContent}
- ```
parameters:
- in: path
name: serviceId
@@ -7378,88 +7498,94 @@ paths:
This API parses request parameters of a [device authorization request](https://datatracker.ietf.org/doc/html/rfc8628#section-3.1)
and returns necessary data for the authorization server implementation to process the device authorization
request further.
+ x-mint:
+ metadata:
+ description: "This API parses request parameters of a [device authorization request](https://datatracker.ietf.org/doc/html/rfc8628#section-3.1) and returns necessary data for the authorization server implementation to process the device authorization request further."
+ content: |
+
+ This API is supposed to be called from the within the implementation of the device authorization
+ endpoint of the service. The service implementation should retrieve the value of `action` from the
+ response and take the following steps according to the value.
+
+ ## INTERNAL_SERVER_ERROR
+
+ When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the API call from the authorization
+ server implementation was wrong or that an error occurred in Authlete.
+ In either case, from a viewpoint of the client application, it is an error on the server side.
+ Therefore, the authorization server implementation should generate a response to the client application
+ with "500 Internal Server Error"s and `application/json`.
+ The value of `responseContent` is a JSON string which describes t he error, so it can be
+ used as the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the authorization server implementation should generate
+ and return to the client application.
+ ```
+ HTTP/1.1 500 Internal Server Error
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
+ ## BAD_REQUEST
+
+ When the value of `action` is `BAD_REQUEST`, it means that the request from the client application
+ is wrong.
+ The authorization server implementation should generate a response to the client application with
+ "400 Bad Request" and `application/json`.
+ The value of `responseContent` is a JSON string which describes the error, so it can be used as
+ the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the service implementation should generate and return
+ to the client application.
+ ```
+ HTTP/1.1 400 Bad Request
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
+ ## UNAUTHORIZED
+
+ When the value of `action` is `UNAUTHORIZED`, it means that client authentication of the device authorization
+ request failed.
+ The authorization server implementation should generate a response to the client application with
+ "401 Unauthorized" and `application/json`.
+ The value of `responseContent` is a JSON string which describes the error, so it can be used as
+ the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the service implementation must generate and return
+ to the client application.
+ ```
+ HTTP/1.1 401 Unauthorized
+ WWW-Authenticate: (challenge)
+ Content-Type: application/json
+ Cache-Control: no-store
+ Pragma: no-cache
+ {responseContent}
+ ```
+
+ ## OK
+
+ When the value of `action` is `OK`, it means that the device authorization request from the client
+ application is valid.
+ The authorization server implementation should generate a response to the client application with
+ "200 OK" and `application/json`.
+ The `responseContent` is a JSON string which can be used as the entity body of the response.
+
+ ---
+
+ The following illustrates the response which the authorization server implementation should generate
+ and return to the client application.
+
- This API is supposed to be called from the within the implementation of the device authorization
- endpoint of the service. The service implementation should retrieve the value of `action` from the
- response and take the following steps according to the value.
-
- ## INTERNAL_SERVER_ERROR
-
- When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the API call from the authorization
- server implementation was wrong or that an error occurred in Authlete.
- In either case, from a viewpoint of the client application, it is an error on the server side.
- Therefore, the authorization server implementation should generate a response to the client application
- with "500 Internal Server Error"s and `application/json`.
- The value of `responseContent` is a JSON string which describes t he error, so it can be
- used as the entity body of the response.
-
- ---
-
- The following illustrates the response which the authorization server implementation should generate
- and return to the client application.
- ```
- HTTP/1.1 500 Internal Server Error
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
-
- ## BAD_REQUEST
-
- When the value of `action` is `BAD_REQUEST`, it means that the request from the client application
- is wrong.
- The authorization server implementation should generate a response to the client application with
- "400 Bad Request" and `application/json`.
- The value of `responseContent` is a JSON string which describes the error, so it can be used as
- the entity body of the response.
-
- ---
-
- The following illustrates the response which the service implementation should generate and return
- to the client application.
- ```
- HTTP/1.1 400 Bad Request
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
-
- ## UNAUTHORIZED
-
- When the value of `action` is `UNAUTHORIZED`, it means that client authentication of the device authorization
- request failed.
- The authorization server implementation should generate a response to the client application with
- "401 Unauthorized" and `application/json`.
- The value of `responseContent` is a JSON string which describes the error, so it can be used as
- the entity body of the response.
-
- ---
-
- The following illustrates the response which the service implementation must generate and return
- to the client application.
- ```
- HTTP/1.1 401 Unauthorized
- WWW-Authenticate: (challenge)
- Content-Type: application/json
- Cache-Control: no-store
- Pragma: no-cache
- {responseContent}
- ```
-
- ## OK
-
- When the value of `action` is `OK`, it means that the device authorization request from the client
- application is valid.
- The authorization server implementation should generate a response to the client application with
- "200 OK" and `application/json`.
- The `responseContent` is a JSON string which can be used as the entity body of the response.
-
- ---
-
- The following illustrates the response which the authorization server implementation should generate
- and return to the client application.
parameters:
- in: path
name: serviceId
@@ -7561,40 +7687,46 @@ paths:
summary: Process Device Verification Request
description: |
The API returns information associated with a user code.
+ x-mint:
+ metadata:
+ description: "The API returns information associated with a user code."
+ content: |
+
+ After receiving a response from the device authorization endpoint of the authorization server,
+ the client application shows the end-user the user code and the verification URI which are included
+ in the device authorization response. Then, the end-user will access the verification URI using
+ a web browser on another device (typically, a smart phone). In normal implementations, the verification
+ endpoint will return an HTML page with an input form where the end-user inputs a user code. The
+ authorization server will receive a user code from the form.
+ After receiving a user code, the authorization server should call Authlete's `/device/verification`
+ API with the user code. And then, the authorization server implementation should retrieve the value
+ of `action` parameter from the API response and take the following steps according to the value.
- After receiving a response from the device authorization endpoint of the authorization server,
- the client application shows the end-user the user code and the verification URI which are included
- in the device authorization response. Then, the end-user will access the verification URI using
- a web browser on another device (typically, a smart phone). In normal implementations, the verification
- endpoint will return an HTML page with an input form where the end-user inputs a user code. The
- authorization server will receive a user code from the form.
- After receiving a user code, the authorization server should call Authlete's `/device/verification`
- API with the user code. And then, the authorization server implementation should retrieve the value
- of `action` parameter from the API response and take the following steps according to the value.
+ ## SERVER_ERROR
- ## SERVER_ERROR
+ When the value of `action` is `SERVER_ERROR`, it means that an error occurred on Authlete side. The
+ authorization server implementation should tell the end-user that something wrong happened and
+ urge her to re-initiate a device flow.
- When the value of `action` is `SERVER_ERROR`, it means that an error occurred on Authlete side. The
- authorization server implementation should tell the end-user that something wrong happened and
- urge her to re-initiate a device flow.
+ ## NOT_EXIST
- ## NOT_EXIST
+ When the value of `action` is `NOT_EXIST`, it means that the user code does not exist. The authorization
+ server implementation should tell the end-user that the user code is invalid and urge her to retry
+ to input a valid user code.
- When the value of `action` is `NOT_EXIST`, it means that the user code does not exist. The authorization
- server implementation should tell the end-user that the user code is invalid and urge her to retry
- to input a valid user code.
+ ## EXPIRED
- ## EXPIRED
+ When the value of `action` is `EXPIRED`, it means that the user code has expired. The authorization
+ server implementation should tell the end-user that the user code has expired and urge her to
+ re-initiate a device flow.
- When the value of `action` is `EXPIRED`, it means that the user code has expired. The authorization
- server implementation should tell the end-user that the user code has expired and urge her to
- re-initiate a device flow.
+ ## VALID
- ## VALID
+ When the value of `action` is `VALID`, it means that the user code exists, has not expired, and
+ belongs to the service. The authorization server implementation should interact with the end-user
+ to ask whether she approves or rejects the authorization request from the device.
+
- When the value of `action` is `VALID`, it means that the user code exists, has not expired, and
- belongs to the service. The authorization server implementation should interact with the end-user
- to ask whether she approves or rejects the authorization request from the device.
parameters:
- in: path
name: serviceId
@@ -7681,62 +7813,68 @@ paths:
This API returns information about what action the authorization server should take after it receives
the result of end-user's decision about whether the end-user has approved or rejected a client
application's request.
+ x-mint:
+ metadata:
+ description: "This API returns information about what action the authorization server should take after it receives the result of end-user's decision about whether the end-user has approved or rejected a client application's request."
+ content: |
+
+ In the device flow, an end-user accesses the verification endpoint of the authorization server where
+ she interacts with the verification endpoint and inputs a user code. The verification endpoint checks
+ if the user code is valid and then asks the end-user whether she approves or rejects the authorization
+ request which the user code represents.
+ After the authorization server receives the decision of the end-user, it should call Authlete's
+ `/device/complete` API to tell Authlete the decision.
+ When the end-user was authenticated and authorization was granted to the client by the end-user,
+ the authorization server should call the API with `result=AUTHORIZED`. In this successful case,
+ the subject request parameter is mandatory. The API will update the database record so that `/auth/token`
+ API can generate an access token later.
+ If the `scope` parameter of the device authorization request included the openid scope, an ID token
+ is generated. In this case, `sub`, `authTime`, `acr` and `claims` request parameters in the API
+ call to `/device/complete` affect the ID token.
+ When the authorization server receives the decision of the end-user and it indicates that she has
+ rejected to give authorization to the client, the authorization server should call the API with
+ `result=ACCESS_DENIED`. In this case, the API will update the database record so that the `/auth/token`
+ API can generate an error response later. If `errorDescription` and `errorUri` request parameters
+ are given to the `/device/complete` API, they will be used as the values of `error_description`
+ and `error_uri` response parameters in the error response from the token endpoint.
+ When the authorization server could not get decision from the end-user for some reasons, the authorization
+ server should call the API with `result=TRANSACTION_FAILED`. In this error case, the API will behave
+ in the same way as in the case of `ACCESS_DENIED`. The only difference is that `expired_token` is
+ used as the value of the `error` response parameter instead of `access_denied`.
+ After receiving a response from the `/device/complete` API, the implementation of the authorization
+ server should retrieve the value of `action` from the response and take the following steps according
+ to the value.
+
+ ## SERVER_ERROR
+
+ When the value of `action` is `SERVER_ERROR`, it means that an error occurred on Authlete side. The
+ authorization server implementation should tell the end-user that something wrong happened and
+ urge her to re-initiate a device flow.
+
+ ## USER_CODE_NOT_EXIST
+
+ When the value of `action` is `USER_CODE_NOT_EXIST`, it means that the user code included in the API
+ call does not exist. The authorization server implementation should tell the end-user that the user
+ code has been invalidated and urge her to re-initiate a device flow.
+
+ ## USER_CODE_EXPIRED
+
+ When the value of `action` is `USER_CODE_EXPIRED`, it means that the user code included in the API
+ call has expired. The authorization server implementation should tell the end-user that the user
+ code has expired and urge her to re-initiate a device flow.
+
+ ## INVALID_REQUEST
+
+ When the value of `action` is `INVALID_REQUEST`, it means that the API call is invalid. Probably,
+ the authorization server implementation has some bugs.
+
+ ## SUCCESS
+
+ When the value of `action` is `SUCCESS`, it means that the API call has been processed successfully.
+ The authorization server should return a successful response to the web browser the end-user is
+ using.
+
- In the device flow, an end-user accesses the verification endpoint of the authorization server where
- she interacts with the verification endpoint and inputs a user code. The verification endpoint checks
- if the user code is valid and then asks the end-user whether she approves or rejects the authorization
- request which the user code represents.
- After the authorization server receives the decision of the end-user, it should call Authlete's
- `/device/complete` API to tell Authlete the decision.
- When the end-user was authenticated and authorization was granted to the client by the end-user,
- the authorization server should call the API with `result=AUTHORIZED`. In this successful case,
- the subject request parameter is mandatory. The API will update the database record so that `/auth/token`
- API can generate an access token later.
- If the `scope` parameter of the device authorization request included the openid scope, an ID token
- is generated. In this case, `sub`, `authTime`, `acr` and `claims` request parameters in the API
- call to `/device/complete` affect the ID token.
- When the authorization server receives the decision of the end-user and it indicates that she has
- rejected to give authorization to the client, the authorization server should call the API with
- `result=ACCESS_DENIED`. In this case, the API will update the database record so that the `/auth/token`
- API can generate an error response later. If `errorDescription` and `errorUri` request parameters
- are given to the `/device/complete` API, they will be used as the values of `error_description`
- and `error_uri` response parameters in the error response from the token endpoint.
- When the authorization server could not get decision from the end-user for some reasons, the authorization
- server should call the API with `result=TRANSACTION_FAILED`. In this error case, the API will behave
- in the same way as in the case of `ACCESS_DENIED`. The only difference is that `expired_token` is
- used as the value of the `error` response parameter instead of `access_denied`.
- After receiving a response from the `/device/complete` API, the implementation of the authorization
- server should retrieve the value of `action` from the response and take the following steps according
- to the value.
-
- ## SERVER_ERROR
-
- When the value of `action` is `SERVER_ERROR`, it means that an error occurred on Authlete side. The
- authorization server implementation should tell the end-user that something wrong happened and
- urge her to re-initiate a device flow.
-
- ## USER_CODE_NOT_EXIST
-
- When the value of `action` is `USER_CODE_NOT_EXIST`, it means that the user code included in the API
- call does not exist. The authorization server implementation should tell the end-user that the user
- code has been invalidated and urge her to re-initiate a device flow.
-
- ## USER_CODE_EXPIRED
-
- When the value of `action` is `USER_CODE_EXPIRED`, it means that the user code included in the API
- call has expired. The authorization server implementation should tell the end-user that the user
- code has expired and urge her to re-initiate a device flow.
-
- ## INVALID_REQUEST
-
- When the value of `action` is `INVALID_REQUEST`, it means that the API call is invalid. Probably,
- the authorization server implementation has some bugs.
-
- ## SUCCESS
-
- When the value of `action` is `SUCCESS`, it means that the API call has been processed successfully.
- The authorization server should return a successful response to the web browser the end-user is
- using.
parameters:
- in: path
name: serviceId
@@ -8039,88 +8177,6 @@ paths:
api.tokenCreate(req)
tags:
- Token Operations
- /api/{serviceId}/auth/token/create/batch:
- post:
- summary: Create Access Tokens in Batch
- description: |
- Create access tokens in batch.
- parameters:
- - in: path
- name: serviceId
- description: A service ID.
- required: true
- schema:
- type: string
- - in: query
- name: dryRun
- description: |
- If `true`, the request is processed but access tokens are not actually created.
- required: false
- schema:
- type: boolean
- requestBody:
- required: true
- content:
- application/json:
- schema:
- type: array
- items:
- $ref: '#/components/schemas/token_create_request'
- responses:
- '200':
- description: Batch request accepted
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/token_create_batch_response'
- '400':
- $ref: '#/components/responses/400'
- '401':
- $ref: '#/components/responses/401'
- '403':
- $ref: '#/components/responses/403'
- '500':
- $ref: '#/components/responses/500'
- operationId: auth_token_create_batch_api
- tags:
- - Token Operations
- /api/{serviceId}/auth/token/create/batch/status/{tokenBatchRequestId}:
- get:
- summary: Get Batch Token Creation Status
- description: |
- Get the status of a batch token creation request.
- parameters:
- - in: path
- name: serviceId
- description: A service ID.
- required: true
- schema:
- type: string
- - in: path
- name: tokenBatchRequestId
- description: |
- A token batch request ID.
- required: true
- schema:
- type: string
- responses:
- '200':
- description: Successfully retrieved the status
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/token_create_batch_status_response'
- '400':
- $ref: '#/components/responses/400'
- '401':
- $ref: '#/components/responses/401'
- '403':
- $ref: '#/components/responses/403'
- '500':
- $ref: '#/components/responses/500'
- operationId: auth_token_create_batch_status_api
- tags:
- - Token Operations
/api/{serviceId}/auth/token/update:
post:
summary: Update Access Token
@@ -8436,66 +8492,72 @@ paths:
retrieve the value of the `action`
response parameter from the API response and take the following steps
according to the value.
+ x-mint:
+ metadata:
+ description: "This API gathers the federation configuration about a service. The authorization server implementation should retrieve the value of the `action` response parameter from the API response and take the following steps according to the value."
+ content: |
+
+ ### `OK`
+ When the value of the `action` response
+ parameter is `OK`, it means that Authlete
+ could prepare an entity configuration successfully.
+ In this case, the implementation of the entity configuration endpoint of the
+ authorization server should return an HTTP response to the client application
+ with the HTTP status code "`200 OK`" and the content type
+ "`application/entity-statement+jwt`". The message body (= an entity
+ configuration in the JWT format) of the response has been prepared by
+ Authlete's `/federation/configuration` API and it is available as the
+ `responseContent` response parameter.
+ The implementation of the entity configuration endpoint can construct an
+ HTTP response by doing like below.
+ ```
+ 200 OK
+ Content-Type: application/entity-statement+jwt
+ (Other HTTP headers)
+ (the value of the responseContent response parameter)
+ ```
+
+ ### `NOT_FOUND`
+ When the value of the `action` response
+ parameter is `NOT_FOUND`, it means that
+ the service configuration has not enabled the feature of [OpenID Connect
+ Federation 1.0](https://openid.net/specs/openid-connect-federation-1_0.html) and so the client application should have not access the
+ entity configuration endpoint.
+ In this case, the implementation of the entity configuration endpoint of the
+ authorization server should return an HTTP response to the client application
+ with the HTTP status code "`404 Not Found`" and the content type
+ "`application/json`". The message body (= error information in the JSON
+ format) of the response has been prepared by Authlete's
+ `/federation/configuration` API and it is available as the
+ `responseContent` response parameter.
+ The implementation of the entity configuration endpoint can construct an
+ HTTP response by doing like below.
+ ```
+ 404 Not Found
+ Content-Type: application/json
+ (Other HTTP headers)
+ (the value of the responseContent response parameter)
+ ```
+
+ ### `INTERNAL_SERVER_ERROR`
+ could prepare an entity configuration successfully.
+ In this case, the implementation of the entity configuration endpoint of the
+ authorization server should return an HTTP response to the client application
+ with the HTTP status code "`200 OK`" and the content type
+ "`application/entity-statement+jwt`". The message body (= an entity
+ configuration in the JWT format) of the response has been prepared by
+ Authlete's `/federation/configuration` API and it is available as the
+ `responseContent` response parameter.
+ The implementation of the entity configuration endpoint can construct an
+ HTTP response by doing like below.
+ ```
+ 200 OK
+ Content-Type: application/entity-statement+jwt
+ (Other HTTP headers)
+ (the value of the responseContent response parameter)
+ ```
+
- ### `OK`
- When the value of the `action` response
- parameter is `OK`, it means that Authlete
- could prepare an entity configuration successfully.
- In this case, the implementation of the entity configuration endpoint of the
- authorization server should return an HTTP response to the client application
- with the HTTP status code "`200 OK`" and the content type
- "`application/entity-statement+jwt`". The message body (= an entity
- configuration in the JWT format) of the response has been prepared by
- Authlete's `/federation/configuration` API and it is available as the
- `responseContent` response parameter.
- The implementation of the entity configuration endpoint can construct an
- HTTP response by doing like below.
- ```
- 200 OK
- Content-Type: application/entity-statement+jwt
- (Other HTTP headers)
- (the value of the responseContent response parameter)
- ```
-
- ### `NOT_FOUND`
- When the value of the `action` response
- parameter is `NOT_FOUND`, it means that
- the service configuration has not enabled the feature of [OpenID Connect
- Federation 1.0](https://openid.net/specs/openid-connect-federation-1_0.html) and so the client application should have not access the
- entity configuration endpoint.
- In this case, the implementation of the entity configuration endpoint of the
- authorization server should return an HTTP response to the client application
- with the HTTP status code "`404 Not Found`" and the content type
- "`application/json`". The message body (= error information in the JSON
- format) of the response has been prepared by Authlete's
- `/federation/configuration` API and it is available as the
- `responseContent` response parameter.
- The implementation of the entity configuration endpoint can construct an
- HTTP response by doing like below.
- ```
- 404 Not Found
- Content-Type: application/json
- (Other HTTP headers)
- (the value of the responseContent response parameter)
- ```
-
- ### `INTERNAL_SERVER_ERROR`
- could prepare an entity configuration successfully.
- In this case, the implementation of the entity configuration endpoint of the
- authorization server should return an HTTP response to the client application
- with the HTTP status code "`200 OK`" and the content type
- "`application/entity-statement+jwt`". The message body (= an entity
- configuration in the JWT format) of the response has been prepared by
- Authlete's `/federation/configuration` API and it is available as the
- `responseContent` response parameter.
- The implementation of the entity configuration endpoint can construct an
- HTTP response by doing like below.
- ```
- 200 OK
- Content-Type: application/entity-statement+jwt
- (Other HTTP headers)
- (the value of the responseContent response parameter)
- ```
parameters:
- in: path
name: serviceId
@@ -9478,50 +9540,56 @@ paths:
the session id and verify or generate the device secret as required by the flow). The token endpoint
implementation should retrieve the value of `action` from the response and take the following steps
according to the value.
+ x-mint:
+ metadata:
+ description: "This API should be called by the implementation of a token endpoint to generate the ID token and token response that comply with [OpenID Connect Native SSO for Mobile Apps 1.0](https://openid.net/specs/openid-connect-native-sso-1_0.html) (Native SSO) when Authlete’s `/auth/token` response indicates `action = NATIVE_SSO` (after you validate the session id and verify or generate the device secret as required by the flow). The token endpoint implementation should retrieve the value of `action` from the response and take the following steps according to the value."
+ content: |
+
+ ## OK
- ## OK
+ When the action is `OK`, it indicates that the `/nativesso` API processing has successfully completed.
+ In this case, the token endpoint implementation should return a successful response (`200 OK`) to
+ the client. The value of the responseContent property in the `/nativesso` API response can be used
+ directly as the message body of the token response. Therefore, the success response can be constructed
+ as follows:
- When the action is `OK`, it indicates that the `/nativesso` API processing has successfully completed.
- In this case, the token endpoint implementation should return a successful response (`200 OK`) to
- the client. The value of the responseContent property in the `/nativesso` API response can be used
- directly as the message body of the token response. Therefore, the success response can be constructed
- as follows:
+ ```
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+ Cache-Control: no-store
- ```
- HTTP/1.1 200 OK
- Content-Type: application/json
- Cache-Control: no-store
+ (Embed the value of responseContent here.)
+ ```
- (Embed the value of responseContent here.)
- ```
+ ## INTERNAL_SERVER_ERROR
- ## INTERNAL_SERVER_ERROR
+ When the action is `INTERNAL_SERVER_ERROR`, it indicates that something has gone wrong on the Authlete
+ side. For example, an issue such as a database error might have occurred when retrieving the access
+ token specified by the accessToken parameter from the database.
- When the action is `INTERNAL_SERVER_ERROR`, it indicates that something has gone wrong on the Authlete
- side. For example, an issue such as a database error might have occurred when retrieving the access
- token specified by the accessToken parameter from the database.
+ In such cases, the token endpoint implementation should return an error response to the client.
+ The simplest implementation would be to return a `500 Internal Server Error`.
- In such cases, the token endpoint implementation should return an error response to the client.
- The simplest implementation would be to return a `500 Internal Server Error`.
+ ```
+ HTTP/1.1 500 Internal Server Error
+ Content-Type: application/json
+ Cache-Control: no-store
- ```
- HTTP/1.1 500 Internal Server Error
- Content-Type: application/json
- Cache-Control: no-store
+ (Embed the value of responseContent here.)
+ ```
- (Embed the value of responseContent here.)
- ```
+ However, in a production environment, it may be better to return a more abstract error (one that
+ does not directly describe the nature of the issue), rather than a `500` error.
- However, in a production environment, it may be better to return a more abstract error (one that
- does not directly describe the nature of the issue), rather than a `500` error.
+ ## CALLER_ERROR
- ## CALLER_ERROR
+ When the action is `CALLER_ERROR`, it indicates that the issue lies with the caller of the API
+ (i.e., the implementation of the OpenID Provider). For example, this could be due to missing a
+ required parameter such as accessToken.
- When the action is `CALLER_ERROR`, it indicates that the issue lies with the caller of the API
- (i.e., the implementation of the OpenID Provider). For example, this could be due to missing a
- required parameter such as accessToken.
+ If `CALLER_ERROR` is returned, please review the implementation of your OpenID Provider.
+
- If `CALLER_ERROR` is returned, please review the implementation of your OpenID Provider.
parameters:
- in: path
name: serviceId
@@ -9600,22 +9668,28 @@ paths:
(Native SSO). This is accomplished by deleting access/refresh token records associated with the
specified session ID. In Authlete's implementation, access/refresh token records can be associated
with a session ID only through the mechanism introduced by Native SSO.
+ x-mint:
+ metadata:
+ description: "The `/nativesso/logout` API is supposed to be used to support the concept of \"logout from all applications\" in the context of [OpenID Connect Native SSO for Mobile Apps 1.0](https://openid.net/specs/openid-connect-native-sso-1_0.html) (Native SSO). This is accomplished by deleting access/refresh token records associated with the specified session ID. In Authlete's implementation, access/refresh token records can be associated with a session ID only through the mechanism introduced by Native SSO."
+ content: |
+
+ A response from the `/nativesso/logout` API contains `action` response parameter. The possible values
+ are:
- A response from the `/nativesso/logout` API contains `action` response parameter. The possible values
- are:
+ ## OK
- ## OK
+ When the action is `OK`, it indicates that the `/nativesso/logout` API call completed successfully.
- When the action is `OK`, it indicates that the `/nativesso/logout` API call completed successfully.
+ ## SERVER_ERROR
- ## SERVER_ERROR
+ When the action is `SERVER_ERROR`, it indicates that something has gone wrong on the Authlete side.
- When the action is `SERVER_ERROR`, it indicates that something has gone wrong on the Authlete side.
+ ## CALLER_ERROR
- ## CALLER_ERROR
+ When the action is `CALLER_ERROR`, it indicates that the `/nativesso/logout` API call contained a
+ problem. For example, the call may have been missing the required request parameter `sessionId`.
+
- When the action is `CALLER_ERROR`, it indicates that the `/nativesso/logout` API call contained a
- problem. For example, the call may have been missing the required request parameter `sessionId`.
parameters:
- in: path
name: serviceId
@@ -9866,16 +9940,22 @@ components:
description: |
The set of scopes that the client application is allowed to request. This paramter will be one
of the following.
+ x-mint:
+ metadata:
+ description: "The set of scopes that the client application is allowed to request. This paramter will be one of the following."
+ content: |
+
+ - `null`
+ - an empty set
+ - a set with at least one element
+
+ When the value of this parameter is `null`, it means that the set of scopes that the client
+ application is allowed to request is the set of the scopes that the service supports. When the
+ value of this parameter is an empty set, it means that the client application is not allowed to
+ request any scopes. When the value of this parameter is a set with at least one element, it means
+ that the set is the set of scopes that the client application is allowed to request.
+
- - `null`
- - an empty set
- - a set with at least one element
-
- When the value of this parameter is `null`, it means that the set of scopes that the client
- application is allowed to request is the set of the scopes that the service supports. When the
- value of this parameter is an empty set, it means that the client application is not allowed to
- request any scopes. When the value of this parameter is a set with at least one element, it means
- that the set is the set of scopes that the client application is allowed to request.
requestableScopesEnabled:
type: boolean
description: |
@@ -9986,16 +10066,22 @@ components:
description: |
The client secret. A random 512-bit value encoded by base64url (86 letters). The value of this
property is assigned by Authlete.
+ x-mint:
+ metadata:
+ description: "The client secret. A random 512-bit value encoded by base64url (86 letters). The value of this property is assigned by Authlete."
+ content: |
+
+ Note that Authlete issues a client secret even to a "public" client application, but the client
+ application should not use the client secret unless it changes its client type to "confidential".
+ That is, a public client application should behave as if it had not been issued a client secret.
+ To be specific, a token request from a public client of Authlete should not come along with a
+ client secret although [RFC 6749, 3.2.1. Client Authentication](https://datatracker.ietf.org/doc/html/rfc6749#section-3.2.1)
+ says as follows.
+
+ > Confidential clients or other clients issued client credentials MUST authenticate with the
+ authorization server as described in Section 2.3 when making requests to the token endpoint.
+
- Note that Authlete issues a client secret even to a "public" client application, but the client
- application should not use the client secret unless it changes its client type to "confidential".
- That is, a public client application should behave as if it had not been issued a client secret.
- To be specific, a token request from a public client of Authlete should not come along with a
- client secret although [RFC 6749, 3.2.1. Client Authentication](https://datatracker.ietf.org/doc/html/rfc6749#section-3.2.1)
- says as follows.
-
- > Confidential clients or other clients issued client credentials MUST authenticate with the
- authorization server as described in Section 2.3 when making requests to the token endpoint.
clientIdAlias:
type: string
description: |
@@ -10096,45 +10182,51 @@ components:
type: string
description: |
Redirect URIs that the client application uses to receive a response from the authorization endpoint.
- Requirements for a redirect URI are as follows.
-
- **Requirements by RFC 6749** (From [RFC 6749, 3.1.2. Redirection Endpoint](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2))
-
- - Must be an absolute URI.
- - Must not have a fragment component.
-
- **Requirements by OpenID Connect** (From "[OpenID Connect Dynamic Client Registration 1.0, 2.
- Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata),
- application_type")
-
- - The scheme of the redirect URI used for Implicit Grant by a client application whose application
- is `web` must be `https`. This is checked at runtime by Authlete.
- - The hostname of the redirect URI used for Implicit Grant by a client application whose application
- type is `web` must not be `localhost`. This is checked at runtime by Authlete.
- - The scheme of the redirect URI used by a client application whose application type is `native`
- must be either (1) a custom scheme or (2) `http`, which is allowed only when the hostname part
- is `localhost`. This is checked at runtime by Authlete.
-
- ## Requirements by Authlete
-
- - Must consist of printable ASCII letters only.
- - Must not exceed 200 letters.
-
- Note that Authlete allows the application type to be `null`. In other words, a client application
- does not have to choose `web` or `native` as its application type.
- If the application type is `null`, the requirements by OpenID Connect are not checked at runtime.
-
- An authorization request from a client application which has not registered any redirect URI
- fails unless at least all the following conditions are satisfied.
-
- - The client type of the client application is `confidential`.
- - The value of `response_type` request parameter is `code`.
- - The authorization request has the `redirect_uri` request parameter.
- - The value of `scope` request parameter does not contain `openid`.
+ Requirements for a redirect URI are as follows.
+ x-mint:
+ metadata:
+ description: "Redirect URIs that the client application uses to receive a response from the authorization endpoint. Requirements for a redirect URI are as follows."
+ content: |
+
+ **Requirements by RFC 6749** (From [RFC 6749, 3.1.2. Redirection Endpoint](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2))
+
+ - Must be an absolute URI.
+ - Must not have a fragment component.
+
+ **Requirements by OpenID Connect** (From "[OpenID Connect Dynamic Client Registration 1.0, 2.
+ Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata),
+ application_type")
+
+ - The scheme of the redirect URI used for Implicit Grant by a client application whose application
+ is `web` must be `https`. This is checked at runtime by Authlete.
+ - The hostname of the redirect URI used for Implicit Grant by a client application whose application
+ type is `web` must not be `localhost`. This is checked at runtime by Authlete.
+ - The scheme of the redirect URI used by a client application whose application type is `native`
+ must be either (1) a custom scheme or (2) `http`, which is allowed only when the hostname part
+ is `localhost`. This is checked at runtime by Authlete.
+
+ ## Requirements by Authlete
+
+ - Must consist of printable ASCII letters only.
+ - Must not exceed 200 letters.
+
+ Note that Authlete allows the application type to be `null`. In other words, a client application
+ does not have to choose `web` or `native` as its application type.
+ If the application type is `null`, the requirements by OpenID Connect are not checked at runtime.
+
+ An authorization request from a client application which has not registered any redirect URI
+ fails unless at least all the following conditions are satisfied.
+
+ - The client type of the client application is `confidential`.
+ - The value of `response_type` request parameter is `code`.
+ - The authorization request has the `redirect_uri` request parameter.
+ - The value of `scope` request parameter does not contain `openid`.
+
+ RFC 6749 allows partial match of redirect URI under some conditions (see [RFC 6749, 3.1.2.2.
+ Registration Requirements](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2.2) for
+ details), but OpenID Connect requires exact match.
+
- RFC 6749 allows partial match of redirect URI under some conditions (see [RFC 6749, 3.1.2.2.
- Registration Requirements](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2.2) for
- details), but OpenID Connect requires exact match.
authorizationSignAlg:
$ref: '#/components/schemas/jws_alg'
authorizationEncryptionAlg:
@@ -10271,19 +10363,25 @@ components:
The content pointed to by the URL is JSON which complies with the format described in
[JSON Web Key (JWK), 5. JWK Set Format](https://datatracker.ietf.org/doc/html/rfc7517#section-5).
The JWK Set must not include private keys of the client application.
+ x-mint:
+ metadata:
+ description: "The URL pointing to the JWK Set of the client application. The content pointed to by the URL is JSON which complies with the format described in [JSON Web Key (JWK), 5. JWK Set Format](https://datatracker.ietf.org/doc/html/rfc7517#section-5). The JWK Set must not include private keys of the client application."
+ content: |
+
+ If the client application requests encryption for ID tokens (from the authorization/token/userinfo endpoints)
+ and/or signs request objects, it must make available its JWK Set containing public keys for the
+ encryption and/or the signature at the URL of `jwksUri`. The service (Authlete) fetches the JWK
+ Set from the URL as necessary.
+
+ [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html)
+ says that `jwks` must not be used when the client can use `jwks_uri`, but Authlete allows both
+ properties to be registered at the same time. However, Authlete does not use the content of `jwks`
+ when `jwksUri` is registered.
+
+ This property corresponds to `jwks_uri` in [OpenID Connect Dynamic Client Registration 1.0, 2.
+ Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata).
+
- If the client application requests encryption for ID tokens (from the authorization/token/userinfo endpoints)
- and/or signs request objects, it must make available its JWK Set containing public keys for the
- encryption and/or the signature at the URL of `jwksUri`. The service (Authlete) fetches the JWK
- Set from the URL as necessary.
-
- [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html)
- says that `jwks` must not be used when the client can use `jwks_uri`, but Authlete allows both
- properties to be registered at the same time. However, Authlete does not use the content of `jwks`
- when `jwksUri` is registered.
-
- This property corresponds to `jwks_uri` in [OpenID Connect Dynamic Client Registration 1.0, 2.
- Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata).
jwks:
type: string
description: |
@@ -10291,14 +10389,20 @@ components:
The format is described in
[JSON Web Key (JWK), 5. JWK Set Format](https://datatracker.ietf.org/doc/html/rfc7517#section-5).
The JWK Set must not include private keys of the client application.
+ x-mint:
+ metadata:
+ description: "The content of the JWK Set of the client application. The format is described in [JSON Web Key (JWK), 5. JWK Set Format](https://datatracker.ietf.org/doc/html/rfc7517#section-5). The JWK Set must not include private keys of the client application."
+ content: |
+
+ [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html)
+ says that `jwks` must not be used when the client can use `jwks_uri`, but Authlete allows both
+ properties to be registered at the same time. However, Authlete does not use the content of `jwks`
+ when `jwksUri` is registered.
+
+ This property corresponds to `jwks_uri` in [OpenID Connect Dynamic Client Registration 1.0, 2.
+ Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata).
+
- [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html)
- says that `jwks` must not be used when the client can use `jwks_uri`, but Authlete allows both
- properties to be registered at the same time. However, Authlete does not use the content of `jwks`
- when `jwksUri` is registered.
-
- This property corresponds to `jwks_uri` in [OpenID Connect Dynamic Client Registration 1.0, 2.
- Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata).
userInfoSignAlg:
nullable: true
$ref: '#/components/schemas/jws_alg'
@@ -10410,92 +10514,116 @@ components:
type: string
description: |
The custom client metadata in JSON format.
+ x-mint:
+ metadata:
+ description: "The custom client metadata in JSON format."
+ content: |
+
+ Standard specifications define client metadata as necessary. The following are such examples.
+
+ * [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html)
+ * [RFC 7591 OAuth 2.0 Dynamic Client Registration Protocol](https://www.rfc-editor.org/rfc/rfc7591.html)
+ * [RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens](https://www.rfc-editor.org/rfc/rfc8705.html)
+ * [OpenID Connect Client-Initiated Backchannel Authentication Flow - Core 1.0](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html)
+ * [The OAuth 2.0 Authorization Framework: JWT Secured Authorization Request (JAR)](https://datatracker.ietf.org/doc/draft-ietf-oauth-jwsreq/)
+ * [Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/openid-financial-api-jarm.html)
+ * [OAuth 2.0 Pushed Authorization Requests (PAR)](https://datatracker.ietf.org/doc/rfc9126/)
+ * [OAuth 2.0 Rich Authorization Requests (RAR)](https://datatracker.ietf.org/doc/draft-ietf-oauth-rar/)
+
+ Standard client metadata included in Client Registration Request and Client Update Request (cf.
+ [OIDC DynReg](https://openid.net/specs/openid-connect-registration-1_0.html), [RFC 7591](https://www.rfc-editor.org/rfc/rfc7591.html)
+ and [RFC 7592](https://www.rfc-editor.org/rfc/rfc7592.html)) are, if supported by Authlete, set
+ to corresponding properties of the client application. For example, the value of the `client_name`
+ client metadata in Client Registration/Update Request is set to the clientName property. On the
+ other hand, unrecognized client metadata are discarded.
+
+ By listing up custom client metadata in advance by using the `supportedCustomClientMetadata` property
+ of Service, Authlete can recognize them and stores their values into the database. The stored
+ custom client metadata values can be referenced by this property.
+
- Standard specifications define client metadata as necessary. The following are such examples.
-
- * [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html)
- * [RFC 7591 OAuth 2.0 Dynamic Client Registration Protocol](https://www.rfc-editor.org/rfc/rfc7591.html)
- * [RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens](https://www.rfc-editor.org/rfc/rfc8705.html)
- * [OpenID Connect Client-Initiated Backchannel Authentication Flow - Core 1.0](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html)
- * [The OAuth 2.0 Authorization Framework: JWT Secured Authorization Request (JAR)](https://datatracker.ietf.org/doc/draft-ietf-oauth-jwsreq/)
- * [Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/openid-financial-api-jarm.html)
- * [OAuth 2.0 Pushed Authorization Requests (PAR)](https://datatracker.ietf.org/doc/rfc9126/)
- * [OAuth 2.0 Rich Authorization Requests (RAR)](https://datatracker.ietf.org/doc/draft-ietf-oauth-rar/)
-
- Standard client metadata included in Client Registration Request and Client Update Request (cf.
- [OIDC DynReg](https://openid.net/specs/openid-connect-registration-1_0.html), [RFC 7591](https://www.rfc-editor.org/rfc/rfc7591.html)
- and [RFC 7592](https://www.rfc-editor.org/rfc/rfc7592.html)) are, if supported by Authlete, set
- to corresponding properties of the client application. For example, the value of the `client_name`
- client metadata in Client Registration/Update Request is set to the clientName property. On the
- other hand, unrecognized client metadata are discarded.
-
- By listing up custom client metadata in advance by using the `supportedCustomClientMetadata` property
- of Service, Authlete can recognize them and stores their values into the database. The stored
- custom client metadata values can be referenced by this property.
frontChannelRequestObjectEncryptionRequired:
type: boolean
description: |
The flag indicating whether encryption of request object is required when the request object
is passed through the front channel.
+ x-mint:
+ metadata:
+ description: "The flag indicating whether encryption of request object is required when the request object is passed through the front channel."
+ content: |
+
+ This flag does not affect the processing of request objects at the Pushed Authorization Request
+ Endpoint, which is defined in [OAuth 2.0 Pushed Authorization Requests](https://datatracker.ietf.org/doc/rfc9126/).
+ Unecrypted request objects are accepted at the endpoint even if this flag is `true`.
+
+ This flag does not indicate whether a request object is always required. There is a different
+ flag, `requestObjectRequired`, for the purpose.
+
+ Even if this flag is `false`, encryption of request object is required if the `frontChannelRequestObjectEncryptionRequired`
+ flag of the service is `true`.
+
- This flag does not affect the processing of request objects at the Pushed Authorization Request
- Endpoint, which is defined in [OAuth 2.0 Pushed Authorization Requests](https://datatracker.ietf.org/doc/rfc9126/).
- Unecrypted request objects are accepted at the endpoint even if this flag is `true`.
-
- This flag does not indicate whether a request object is always required. There is a different
- flag, `requestObjectRequired`, for the purpose.
-
- Even if this flag is `false`, encryption of request object is required if the `frontChannelRequestObjectEncryptionRequired`
- flag of the service is `true`.
requestObjectEncryptionAlgMatchRequired:
type: boolean
description: |
The flag indicating whether the JWE alg of encrypted request object must match the `request_object_encryption_alg`
client metadata.
+ x-mint:
+ metadata:
+ description: "The flag indicating whether the JWE alg of encrypted request object must match the `request_object_encryption_alg` client metadata."
+ content: |
+
+ The `request_object_encryption_alg` client metadata itself is defined in [OpenID Connect Dynamic
+ Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) as follows.
+
+ > request_object_encryption_alg
+ >
+ > OPTIONAL. JWE [JWE] alg algorithm [JWA] the RP is declaring that it may use for encrypting Request
+ Objects sent to the OP. This parameter SHOULD be included when symmetric encryption will be used,
+ since this signals to the OP that a client_secret value needs to be returned from which the
+ symmetric key will be derived, that might not otherwise be returned. The RP MAY still use other
+ supported encryption algorithms or send unencrypted Request Objects, even when this parameter
+ is present. If both signing and encryption are requested, the Request Object will be signed
+ then encrypted, with the result being a Nested JWT, as defined in [JWT]. The default, if omitted,
+ is that the RP is not declaring whether it might encrypt any Request Objects.
+
+ The point here is "The RP MAY still use other supported encryption algorithms or send unencrypted
+ Request Objects, even when this parameter is present."
+
+ The property that represents the client metadata is `requestEncryptionAlg`. See the description
+ of `requestEncryptionAlg` for details.
+
+ Even if this flag is `false`, the match is required if the `requestObjectEncryptionAlgMatchRequired`
+ flag of the service is `true`.
+
- The `request_object_encryption_alg` client metadata itself is defined in [OpenID Connect Dynamic
- Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) as follows.
-
- > request_object_encryption_alg
- >
- > OPTIONAL. JWE [JWE] alg algorithm [JWA] the RP is declaring that it may use for encrypting Request
- Objects sent to the OP. This parameter SHOULD be included when symmetric encryption will be used,
- since this signals to the OP that a client_secret value needs to be returned from which the
- symmetric key will be derived, that might not otherwise be returned. The RP MAY still use other
- supported encryption algorithms or send unencrypted Request Objects, even when this parameter
- is present. If both signing and encryption are requested, the Request Object will be signed
- then encrypted, with the result being a Nested JWT, as defined in [JWT]. The default, if omitted,
- is that the RP is not declaring whether it might encrypt any Request Objects.
-
- The point here is "The RP MAY still use other supported encryption algorithms or send unencrypted
- Request Objects, even when this parameter is present."
-
- The property that represents the client metadata is `requestEncryptionAlg`. See the description
- of `requestEncryptionAlg` for details.
-
- Even if this flag is `false`, the match is required if the `requestObjectEncryptionAlgMatchRequired`
- flag of the service is `true`.
requestObjectEncryptionEncMatchRequired:
type: boolean
description: |
The flag indicating whether the JWE enc of encrypted request object must match the `request_object_encryption_enc`
client metadata.
+ x-mint:
+ metadata:
+ description: "The flag indicating whether the JWE enc of encrypted request object must match the `request_object_encryption_enc` client metadata."
+ content: |
+
+ The `request_object_encryption_enc` client metadata itself is defined in [OpenID Connect Dynamic
+ Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) as follows.
+
+ > request_object_encryption_enc
+ >
+ > OPTIONAL. JWE enc algorithm [JWA] the RP is declaring that it may use for encrypting Request
+ Objects sent to the OP. If request_object_encryption_alg is specified, the default for this
+ value is A128CBC-HS256. When request_object_encryption_enc is included, request_object_encryption_alg
+ MUST also be provided.
+
+ The property that represents the client metadata is `requestEncryptionEnc`. See the description
+ of `requestEncryptionEnc` for details.
+
+ Even if this flag is `false`, the match is required if the `requestObjectEncryptionEncMatchRequired`
+ flag of the service is `true`.
+
- The `request_object_encryption_enc` client metadata itself is defined in [OpenID Connect Dynamic
- Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) as follows.
-
- > request_object_encryption_enc
- >
- > OPTIONAL. JWE enc algorithm [JWA] the RP is declaring that it may use for encrypting Request
- Objects sent to the OP. If request_object_encryption_alg is specified, the default for this
- value is A128CBC-HS256. When request_object_encryption_enc is included, request_object_encryption_alg
- MUST also be provided.
-
- The property that represents the client metadata is `requestEncryptionEnc`. See the description
- of `requestEncryptionEnc` for details.
-
- Even if this flag is `false`, the match is required if the `requestObjectEncryptionEncMatchRequired`
- flag of the service is `true`.
digestAlgorithm:
type: string
description: |
@@ -10612,15 +10740,21 @@ components:
$ref: '#/components/schemas/fapi_mode'
description: |
The FAPI modes for this client.
+ x-mint:
+ metadata:
+ description: "The FAPI modes for this client."
+ content: |
+
+ When the value of this property is not `null`, Authlete always processes requests from this client
+ based on the specified FAPI modes if the FAPI feature is enabled in Authlete, the FAPI profile
+ is supported by the service, and the FAPI modes for the service are set to `null`.
+
+ For instance, when this property is set to an array containing `FAPI1_ADVANCED` only, Authlete
+ always processes requests from this client based on "Financial-grade API Security Profile 1.0 -
+ Part 2: Advanced" if the FAPI feature is enabled in Authlete, the FAPI profile is supported by
+ the service, and the FAPI modes for the service are set to `null`.
+
- When the value of this property is not `null`, Authlete always processes requests from this client
- based on the specified FAPI modes if the FAPI feature is enabled in Authlete, the FAPI profile
- is supported by the service, and the FAPI modes for the service are set to `null`.
-
- For instance, when this property is set to an array containing `FAPI1_ADVANCED` only, Authlete
- always processes requests from this client based on "Financial-grade API Security Profile 1.0 -
- Part 2: Advanced" if the FAPI feature is enabled in Authlete, the FAPI profile is supported by
- the service, and the FAPI modes for the service are set to `null`.
responseModes:
type: array
items:
@@ -11225,15 +11359,21 @@ components:
format: int64
description: |
The duration of pushed authorization requests in seconds.
+ x-mint:
+ metadata:
+ description: "The duration of pushed authorization requests in seconds."
+ content: |
+
+ [OAuth 2.0 Pushed Authorization Requests](https://tools.ietf.org/html/draft-lodderstedt-oauth-par)
+ defines an endpoint (called "pushed authorization request endpoint") which client applications
+ can register authorization requests into and get corresponding URIs (called "request URIs") from.
+ The issued URIs represent the registered authorization requests. The client applications can use
+ the URIs as the value of the `request_uri` request parameter in an authorization request.
+
+ The property represents the duration of registered authorization requests and is used as the value
+ of the `expires_in` parameter in responses from the pushed authorization request endpoint.
+
- [OAuth 2.0 Pushed Authorization Requests](https://tools.ietf.org/html/draft-lodderstedt-oauth-par)
- defines an endpoint (called "pushed authorization request endpoint") which client applications
- can register authorization requests into and get corresponding URIs (called "request URIs") from.
- The issued URIs represent the registered authorization requests. The client applications can use
- the URIs as the value of the `request_uri` request parameter in an authorization request.
-
- The property represents the duration of registered authorization requests and is used as the value
- of the `expires_in` parameter in responses from the pushed authorization request endpoint.
parRequired:
type: boolean
description: |
@@ -11259,19 +11399,25 @@ components:
The flag to indicate whether a request object is processed based on rules defined in
[OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) or JAR (JWT
Secured Authorization Request).
+ x-mint:
+ metadata:
+ description: "The flag to indicate whether a request object is processed based on rules defined in [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) or JAR (JWT Secured Authorization Request)."
+ content: |
+
+ Differences between rules in OpenID Connect Core 1.0 and ones in JAR are as follows.
+ - JAR requires that a request object be always -signed.
+ - JAR does not allow request parameters outside a request object to be referred to.
+ - OIDC Core 1.0 requires that response_type request parameter exist outside a request object even if the request object includes the request parameter.
+ - OIDC Core 1.0 requires that scope request parameter exist outside a request object if the authorization request is an
+ - OIDC request even if the request object includes the request parameter.
+
+ If this flag is set to `false` and the value of `requestObjectRequired` is `true`, the value of
+ `require_signed_request_object` server metadata of this service
+ is reported as `true` in the discovery document. The metadata is defined in JAR (JWT Secured
+ Authorization Request). That `require_signed_request_object` is `true` means that authorization
+ requests which don't conform to the JAR specification are rejected.
+
- Differences between rules in OpenID Connect Core 1.0 and ones in JAR are as follows.
- - JAR requires that a request object be always -signed.
- - JAR does not allow request parameters outside a request object to be referred to.
- - OIDC Core 1.0 requires that response_type request parameter exist outside a request object even if the request object includes the request parameter.
- - OIDC Core 1.0 requires that scope request parameter exist outside a request object if the authorization request is an
- - OIDC request even if the request object includes the request parameter.
-
- If this flag is set to `false` and the value of `requestObjectRequired` is `true`, the value of
- `require_signed_request_object` server metadata of this service
- is reported as `true` in the discovery document. The metadata is defined in JAR (JWT Secured
- Authorization Request). That `require_signed_request_object` is `true` means that authorization
- requests which don't conform to the JAR specification are rejected.
mutualTlsValidatePkiCertChain:
type: boolean
description: |
@@ -11288,21 +11434,27 @@ components:
$ref: '#/components/schemas/named_uri'
description: |
The MTLS endpoint aliases.
+ x-mint:
+ metadata:
+ description: "The MTLS endpoint aliases."
+ content: |
+
+ This property corresponds to the mtls_endpoint_aliases metadata defined in "5. Metadata for Mutual TLS Endpoint Aliases" of [OAuth 2.0 Mutual TLS Client Authentication and Certificate-Bound Access Tokens](https://datatracker.ietf.org/doc/rfc8705/).
- This property corresponds to the mtls_endpoint_aliases metadata defined in "5. Metadata for Mutual TLS Endpoint Aliases" of [OAuth 2.0 Mutual TLS Client Authentication and Certificate-Bound Access Tokens](https://datatracker.ietf.org/doc/rfc8705/).
+ The aliases will be embedded in the response from the discovery endpoint like the following.
- The aliases will be embedded in the response from the discovery endpoint like the following.
-
- ```json
- {
- ......,
- "mtls_endpoint_aliases": {
- "token_endpoint": "https://mtls.example.com/token",
- "revocation_endpoint": "https://mtls.example.com/revo",
- "introspection_endpoint": "https://mtls.example.com/introspect"
+ ```json
+ {
+ ......,
+ "mtls_endpoint_aliases": {
+ "token_endpoint": "https://mtls.example.com/token",
+ "revocation_endpoint": "https://mtls.example.com/revo",
+ "introspection_endpoint": "https://mtls.example.com/introspect"
+ }
}
- }
- ```
+ ```
+
+
accessTokenType:
type: string
description: |
@@ -11378,36 +11530,48 @@ components:
$ref: '#/components/schemas/scope'
description: |
Scopes supported by the service.
+ x-mint:
+ metadata:
+ description: "Scopes supported by the service."
+ content: |
+
+ Authlete strongly recommends that the service register at least the following scopes.
+
+ | Name | Description |
+ | --- | --- |
+ | openid | A permission to get an ID token of an end-user. The `openid` scope appears in [OpenID Connect Core 1.0, 3.1.2.1. Authentication Request, scope](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). Without this scope, Authlete does not allow `response_type` request parameter to have values other than code and token. |
+ | profile | A permission to get information about `name`, `family_name`, `given_name`, `middle_name`, `nickname`, `preferred_username`, `profile`, `picture`, `website`, `gender`, `birthdate`, `zoneinfo`, `locale` and `updated_at` from the user info endpoint. See [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) for details. |
+ | email | A permission to get information about `email` and `email_verified` from the user info endpoint. See [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) for details. |
+ | address | A permission to get information about address from the user info endpoint. See [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) and [5.1.1. Address Claim](https://openid.net/specs/openid-connect-core-1_0.html#AddressClaim) for details. |
+ | phone | A permission to get information about `phone_number` and `phone_number_verified` from the user info endpoint. See [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) for details. |
+ | offline_access | A permission to get information from the user info endpoint even when the end-user is not present. See [OpenID Connect Core 1.0, 11. Offline Access](https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess) for details. |
- Authlete strongly recommends that the service register at least the following scopes.
+ The value of this property is used as `scopes_supported` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).
+
- | Name | Description |
- | --- | --- |
- | openid | A permission to get an ID token of an end-user. The `openid` scope appears in [OpenID Connect Core 1.0, 3.1.2.1. Authentication Request, scope](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). Without this scope, Authlete does not allow `response_type` request parameter to have values other than code and token. |
- | profile | A permission to get information about `name`, `family_name`, `given_name`, `middle_name`, `nickname`, `preferred_username`, `profile`, `picture`, `website`, `gender`, `birthdate`, `zoneinfo`, `locale` and `updated_at` from the user info endpoint. See [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) for details. |
- | email | A permission to get information about `email` and `email_verified` from the user info endpoint. See [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) for details. |
- | address | A permission to get information about address from the user info endpoint. See [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) and [5.1.1. Address Claim](https://openid.net/specs/openid-connect-core-1_0.html#AddressClaim) for details. |
- | phone | A permission to get information about `phone_number` and `phone_number_verified` from the user info endpoint. See [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) for details. |
- | offline_access | A permission to get information from the user info endpoint even when the end-user is not present. See [OpenID Connect Core 1.0, 11. Offline Access](https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess) for details. |
-
- The value of this property is used as `scopes_supported` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).
scopeRequired:
type: boolean
description: |
The flag to indicate whether requests that request no scope are rejected or not.
+ x-mint:
+ metadata:
+ description: "The flag to indicate whether requests that request no scope are rejected or not."
+ content: |
+
+ When a request has no explicit `scope` parameter and the service's pre-defined default scope set is empty,
+ the authorization server regards the request requests no scope. When this flag is set to `true`,
+ requests that request no scope are rejected.
- When a request has no explicit `scope` parameter and the service's pre-defined default scope set is empty,
- the authorization server regards the request requests no scope. When this flag is set to `true`,
- requests that request no scope are rejected.
+ The requirement below excerpted from [RFC 6749 Section 3.3](https://tools.ietf.org/html/rfc6749#section-3.3)
+ does not explicitly mention the case where the default scope set is empty.
- The requirement below excerpted from [RFC 6749 Section 3.3](https://tools.ietf.org/html/rfc6749#section-3.3)
- does not explicitly mention the case where the default scope set is empty.
+ > If the client omits the scope parameter when requesting authorization, the authorization server
+ MUST either process the request using a pre-defined default value or fail the request indicating an invalid scope.
- > If the client omits the scope parameter when requesting authorization, the authorization server
- MUST either process the request using a pre-defined default value or fail the request indicating an invalid scope.
+ However, if you interpret *"the default scope set exists but is empty"* as *"the default scope set does not exist"*
+ and want to strictly conform to the requirement above, this flag has to be `true`.
+
- However, if you interpret *"the default scope set exists but is empty"* as *"the default scope set does not exist"*
- and want to strictly conform to the requirement above, this flag has to be `true`.
idTokenDuration:
type: integer
format: int64
@@ -11450,46 +11614,58 @@ components:
Claim names that the service supports. The standard claim names listed in [OpenID Connect Core 1.0,
5.1. Standard Claim](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) should
be supported. The following is the list of standard claims.
+ x-mint:
+ metadata:
+ description: "Claim names that the service supports. The standard claim names listed in [OpenID Connect Core 1.0, 5.1. Standard Claim](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) should be supported. The following is the list of standard claims."
+ content: |
+
+ - `sub`
+ - `name`
+ - `given_name`
+ - `family_name`
+ - `middle_name`
+ - `nickname`
+ - `preferred_username`
+ - `profile`
+ - `picture`
+ - `website`
+ - `email`
+ - `email_verified`
+ - `gender`
+ - `birthdate`
+ - `zoneinfo`
+ - `locale`
+ - `phone_number`
+ - `phone_number_verified`
+ - `address`
+ - `updated_at`
+
+ The value of this property is used as `claims_supported` property in the [OpenID Provider
+ Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).
+
+ The service may support its original claim names. See [OpenID Connect Core 1.0, 5.1.2. Additional
+ Claims](https://openid.net/specs/openid-connect-core-1_0.html#AdditionalClaims).
+
- - `sub`
- - `name`
- - `given_name`
- - `family_name`
- - `middle_name`
- - `nickname`
- - `preferred_username`
- - `profile`
- - `picture`
- - `website`
- - `email`
- - `email_verified`
- - `gender`
- - `birthdate`
- - `zoneinfo`
- - `locale`
- - `phone_number`
- - `phone_number_verified`
- - `address`
- - `updated_at`
-
- The value of this property is used as `claims_supported` property in the [OpenID Provider
- Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).
-
- The service may support its original claim names. See [OpenID Connect Core 1.0, 5.1.2. Additional
- Claims](https://openid.net/specs/openid-connect-core-1_0.html#AdditionalClaims).
claimShortcutRestrictive:
type: boolean
description: |
The flag indicating whether claims specified by shortcut scopes (e.g. `profile`) are included
in the issued ID token only when no access token is issued.
+ x-mint:
+ metadata:
+ description: "The flag indicating whether claims specified by shortcut scopes (e.g. `profile`) are included in the issued ID token only when no access token is issued."
+ content: |
+
+ To strictly conform to the description below excerpted from [OpenID Connect Core 1.0 Section
+ 5.4](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims), this flag has to be `true`.
+
+ > The Claims requested by the profile, email, address, and phone scope values are returned from
+ the UserInfo Endpoint, as described in Section 5.3.2, when a response_type value is used that
+ results in an Access Token being issued. However, when no Access Token is issued (which is the
+ case for the response_type value id_token), the resulting Claims are returned in the ID Token.
+
- To strictly conform to the description below excerpted from [OpenID Connect Core 1.0 Section
- 5.4](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims), this flag has to be `true`.
-
- > The Claims requested by the profile, email, address, and phone scope values are returned from
- the UserInfo Endpoint, as described in Section 5.3.2, when a response_type value is used that
- results in an Access Token being issued. However, when no Access Token is issued (which is the
- case for the response_type value id_token), the resulting Claims are returned in the ID Token.
jwksUri:
type: string
format: uri
@@ -11522,52 +11698,70 @@ components:
type: string
description: |
The key ID to identify a JWK used for ID token signature using an asymmetric key.
+ x-mint:
+ metadata:
+ description: "The key ID to identify a JWK used for ID token signature using an asymmetric key."
+ content: |
+
+ A JWK Set can be registered as a property of a Service. A JWK Set can contain 0 or more JWKs
+ (See [RFC 7517](https://tools.ietf.org/html/rfc7517) for details about JWK). Authlete Server has
+ to pick up one JWK for signature from the JWK Set when it generates an ID token and signature
+ using an asymmetric key is required. Authlete Server searches the registered JWK Set for a JWK
+ which satisfies conditions for ID token signature. If the number of JWK candidates which satisfy
+ the conditions is 1, there is no problem. On the other hand, if there exist multiple candidates,
+ a [Key ID](https://tools.ietf.org/html/rfc7517#section-4.5) is needed to be specified so that
+ Authlete Server can pick up one JWK from among the JWK candidates.
+
+ This `idTokenSignatureKeyId` property exists for the purpose described above. For key rotation
+ (OpenID Connect Core 1.0, [10.1.1. Rotation of Asymmetric Signing Keys](http://openid.net/specs/openid-connect-core-1_0.html#RotateSigKeys)),
+ this mechanism is needed.
+
- A JWK Set can be registered as a property of a Service. A JWK Set can contain 0 or more JWKs
- (See [RFC 7517](https://tools.ietf.org/html/rfc7517) for details about JWK). Authlete Server has
- to pick up one JWK for signature from the JWK Set when it generates an ID token and signature
- using an asymmetric key is required. Authlete Server searches the registered JWK Set for a JWK
- which satisfies conditions for ID token signature. If the number of JWK candidates which satisfy
- the conditions is 1, there is no problem. On the other hand, if there exist multiple candidates,
- a [Key ID](https://tools.ietf.org/html/rfc7517#section-4.5) is needed to be specified so that
- Authlete Server can pick up one JWK from among the JWK candidates.
-
- This `idTokenSignatureKeyId` property exists for the purpose described above. For key rotation
- (OpenID Connect Core 1.0, [10.1.1. Rotation of Asymmetric Signing Keys](http://openid.net/specs/openid-connect-core-1_0.html#RotateSigKeys)),
- this mechanism is needed.
userInfoSignatureKeyId:
type: string
description: |
The key ID to identify a JWK used for user info signature using an asymmetric key.
+ x-mint:
+ metadata:
+ description: "The key ID to identify a JWK used for user info signature using an asymmetric key."
+ content: |
+
+ A JWK Set can be registered as a property of a Service. A JWK Set can contain 0 or more JWKs
+ (See [RFC 7517](https://tools.ietf.org/html/rfc7517) for details about JWK). Authlete Server has
+ to pick up one JWK for signature from the JWK Set when it is required to sign user info (which
+ is returned from [userinfo endpoint](http://openid.net/specs/openid-connect-core-1_0.html#UserInfo))
+ using an asymmetric key. Authlete Server searches the registered JWK Set for a JWK which satisfies
+ conditions for user info signature. If the number of JWK candidates which satisfy the conditions
+ is 1, there is no problem. On the other hand, if there exist multiple candidates, a [Key ID](https://tools.ietf.org/html/rfc7517#section-4.5)
+ is needed to be specified so that Authlete Server can pick up one JWK from among the JWK candidates.
+
+ This `userInfoSignatureKeyId` property exists for the purpose described above. For key rotation
+ (OpenID Connect Core 1.0, [10.1.1. Rotation of Asymmetric Signing Keys](http://openid.net/specs/openid-connect-core-1_0.html#RotateSigKeys)),
+ this mechanism is needed.
+
- A JWK Set can be registered as a property of a Service. A JWK Set can contain 0 or more JWKs
- (See [RFC 7517](https://tools.ietf.org/html/rfc7517) for details about JWK). Authlete Server has
- to pick up one JWK for signature from the JWK Set when it is required to sign user info (which
- is returned from [userinfo endpoint](http://openid.net/specs/openid-connect-core-1_0.html#UserInfo))
- using an asymmetric key. Authlete Server searches the registered JWK Set for a JWK which satisfies
- conditions for user info signature. If the number of JWK candidates which satisfy the conditions
- is 1, there is no problem. On the other hand, if there exist multiple candidates, a [Key ID](https://tools.ietf.org/html/rfc7517#section-4.5)
- is needed to be specified so that Authlete Server can pick up one JWK from among the JWK candidates.
-
- This `userInfoSignatureKeyId` property exists for the purpose described above. For key rotation
- (OpenID Connect Core 1.0, [10.1.1. Rotation of Asymmetric Signing Keys](http://openid.net/specs/openid-connect-core-1_0.html#RotateSigKeys)),
- this mechanism is needed.
authorizationSignatureKeyId:
type: string
description: |
The key ID to identify a JWK used for signing authorization responses using an asymmetric key.
+ x-mint:
+ metadata:
+ description: "The key ID to identify a JWK used for signing authorization responses using an asymmetric key."
+ content: |
+
+ [Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/openid-financial-api-jarm.html)
+ defines new values for the `response_mode` request parameter. They are `query.jwt`, `fragment.jwt`,
+ `form_post.jwt` and `jwt`. If one of them is specified as the response mode, response parameters
+ from the authorization endpoint will be packed into a JWT. This property is used to compute the
+ value of the `exp` claim of the JWT.
+
+ Authlete Server searches the JWK Set for a JWK which satisfies conditions for authorization response
+ signature. If the number of JWK candidates which satisfy the conditions is 1, there is no problem.
+ On the other hand, if there exist multiple candidates, a Key ID is needed to be specified so that
+ Authlete Server can pick up one JWK from among the JWK candidates. This property exists to specify
+ the key ID.
+
- [Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/openid-financial-api-jarm.html)
- defines new values for the `response_mode` request parameter. They are `query.jwt`, `fragment.jwt`,
- `form_post.jwt` and `jwt`. If one of them is specified as the response mode, response parameters
- from the authorization endpoint will be packed into a JWT. This property is used to compute the
- value of the `exp` claim of the JWT.
-
- Authlete Server searches the JWK Set for a JWK which satisfies conditions for authorization response
- signature. If the number of JWK candidates which satisfy the conditions is 1, there is no problem.
- On the other hand, if there exist multiple candidates, a Key ID is needed to be specified so that
- Authlete Server can pick up one JWK from among the JWK candidates. This property exists to specify
- the key ID.
userInfoEndpoint:
type: string
description: |
@@ -11664,15 +11858,21 @@ components:
description: |
The flag to indicate whether the `binding_message` request parameter is always required whenever
a backchannel authentication request is judged as a request for Financial-grade API.
+ x-mint:
+ metadata:
+ description: "The flag to indicate whether the `binding_message` request parameter is always required whenever a backchannel authentication request is judged as a request for Financial-grade API."
+ content: |
+
+ The FAPI-CIBA profile requires that the authorization server _"shall ensure unique authorization
+ context exists in the authorization request or require a `binding_message` in the authorization
+ request"_ (FAPI-CIBA, 5.2.2, 2). The simplest way to fulfill this requirement is to set this property
+ to `true`.
+
+ If this property is set to `false`, the `binding_message` request parameter remains optional
+ even in FAPI context, but in exchange, your authorization server must implement a custom mechanism
+ that ensures each backchannel authentication request has unique context.
+
- The FAPI-CIBA profile requires that the authorization server _"shall ensure unique authorization
- context exists in the authorization request or require a `binding_message` in the authorization
- request"_ (FAPI-CIBA, 5.2.2, 2). The simplest way to fulfill this requirement is to set this property
- to `true`.
-
- If this property is set to `false`, the `binding_message` request parameter remains optional
- even in FAPI context, but in exchange, your authorization server must implement a custom mechanism
- that ensures each backchannel authentication request has unique context.
deviceAuthorizationEndpoint:
type: string
format: uri
@@ -11693,17 +11893,23 @@ components:
The verification URI for the device flow with a placeholder for a user code. This URI is used
to build the value of the `verification_uri_complete` parameter in responses from the device
authorization endpoint.
+ x-mint:
+ metadata:
+ description: "The verification URI for the device flow with a placeholder for a user code. This URI is used to build the value of the `verification_uri_complete` parameter in responses from the device authorization endpoint."
+ content: |
+
+ It is expected that the URI contains a fixed string `USER_CODE` somewhere as a placeholder for
+ a user code. For example, like the following.
- It is expected that the URI contains a fixed string `USER_CODE` somewhere as a placeholder for
- a user code. For example, like the following.
+ `https://example.com/device?user_code=USER_CODE`
- `https://example.com/device?user_code=USER_CODE`
+ The fixed string is replaced with an actual user code when Authlete builds a verification URI
+ with a user code for the `verification_uri_complete` parameter.
- The fixed string is replaced with an actual user code when Authlete builds a verification URI
- with a user code for the `verification_uri_complete` parameter.
+ If this URI is not set, the `verification_uri_complete` parameter won't appear in device authorization
+ responses.
+
- If this URI is not set, the `verification_uri_complete` parameter won't appear in device authorization
- responses.
deviceFlowCodeDuration:
type: integer
format: int32
@@ -11775,154 +11981,196 @@ components:
description: |
The flag indicating whether the nbf claim in the request object is optional even when the authorization
request is regarded as a FAPI-Part2 request.
+ x-mint:
+ metadata:
+ description: "The flag indicating whether the nbf claim in the request object is optional even when the authorization request is regarded as a FAPI-Part2 request."
+ content: |
+
+ The final version of Financial-grade API was approved in January, 2021. The Part 2 of the final
+ version has new requirements on lifetime of request objects. They require that request objects
+ contain an `nbf` claim and the lifetime computed by `exp` - `nbf` be no longer than 60 minutes.
+
+ Therefore, when an authorization request is regarded as a FAPI-Part2 request, the request object
+ used in the authorization request must contain an nbf claim. Otherwise, the authorization server
+ rejects the authorization request.
+
+ When this flag is `true`, the `nbf` claim is treated as an optional claim even when the authorization
+ request is regarded as a FAPI-Part2 request. That is, the authorization server does not perform
+ the validation on lifetime of the request object.
+
+ Skipping the validation is a violation of the FAPI specification. The reason why this flag has
+ been prepared nevertheless is that the new requirements (which do not exist in the Implementer's
+ Draft 2 released in October, 2018) have big impacts on deployed implementations of client
+ applications and Authlete thinks there should be a mechanism whereby to make the migration
+ from ID2 to Final smooth without breaking live systems.
+
- The final version of Financial-grade API was approved in January, 2021. The Part 2 of the final
- version has new requirements on lifetime of request objects. They require that request objects
- contain an `nbf` claim and the lifetime computed by `exp` - `nbf` be no longer than 60 minutes.
-
- Therefore, when an authorization request is regarded as a FAPI-Part2 request, the request object
- used in the authorization request must contain an nbf claim. Otherwise, the authorization server
- rejects the authorization request.
-
- When this flag is `true`, the `nbf` claim is treated as an optional claim even when the authorization
- request is regarded as a FAPI-Part2 request. That is, the authorization server does not perform
- the validation on lifetime of the request object.
-
- Skipping the validation is a violation of the FAPI specification. The reason why this flag has
- been prepared nevertheless is that the new requirements (which do not exist in the Implementer's
- Draft 2 released in October, 2018) have big impacts on deployed implementations of client
- applications and Authlete thinks there should be a mechanism whereby to make the migration
- from ID2 to Final smooth without breaking live systems.
issSuppressed:
type: boolean
description: |
The flag indicating whether generation of the iss response parameter is suppressed.
+ x-mint:
+ metadata:
+ description: "The flag indicating whether generation of the iss response parameter is suppressed."
+ content: |
+
+ "OAuth 2.0 Authorization Server Issuer Identifier in Authorization Response" has defined a new
+ authorization response parameter, `iss`, as a countermeasure for a certain type of mix-up attacks.
- "OAuth 2.0 Authorization Server Issuer Identifier in Authorization Response" has defined a new
- authorization response parameter, `iss`, as a countermeasure for a certain type of mix-up attacks.
+ The specification requires that the `iss` response parameter always be included in authorization
+ responses unless JARM (JWT Secured Authorization Response Mode) is used.
- The specification requires that the `iss` response parameter always be included in authorization
- responses unless JARM (JWT Secured Authorization Response Mode) is used.
+ When this flag is `true`, the authorization server does not include the `iss` response parameter
+ in authorization responses. By turning this flag on and off, developers of client applications
+ can experiment the mix-up attack and the effect of the `iss` response parameter.
- When this flag is `true`, the authorization server does not include the `iss` response parameter
- in authorization responses. By turning this flag on and off, developers of client applications
- can experiment the mix-up attack and the effect of the `iss` response parameter.
+ Note that this flag should not be `true` in production environment unless there are special
+ reasons for it.
+
- Note that this flag should not be `true` in production environment unless there are special
- reasons for it.
supportedCustomClientMetadata:
type: array
items:
type: string
description: |
custom client metadata supported by this service.
+ x-mint:
+ metadata:
+ description: "custom client metadata supported by this service."
+ content: |
+
+ Standard specifications define client metadata as necessary. The following are such examples.
+
+ * [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html)
+ * [RFC 7591 OAuth 2.0 Dynamic Client Registration Protocol](https://www.rfc-editor.org/rfc/rfc7591.html)
+ * [RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens](https://www.rfc-editor.org/rfc/rfc8705.html)
+ * [OpenID Connect Client-Initiated Backchannel Authentication Flow - Core 1.0](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html)
+ * [The OAuth 2.0 Authorization Framework: JWT Secured Authorization Request (JAR)](https://datatracker.ietf.org/doc/draft-ietf-oauth-jwsreq/)
+ * [Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/openid-financial-api-jarm.html)
+ * [OAuth 2.0 Pushed Authorization Requests (PAR)](https://datatracker.ietf.org/doc/rfc9126/)
+ * [OAuth 2.0 Rich Authorization Requests (RAR)](https://datatracker.ietf.org/doc/draft-ietf-oauth-rar/)
+
+ Standard client metadata included in Client Registration Request and Client Update Request (cf.
+ [OIDC DynReg](https://openid.net/specs/openid-connect-registration-1_0.html), [RFC 7591](https://www.rfc-editor.org/rfc/rfc7591.html)
+ and [RFC 7592](https://www.rfc-editor.org/rfc/rfc7592.html)) are, if supported by Authlete, stored
+ into Authlete database. On the other hand, unrecognized client metadata are discarded.
+
+ By listing up custom client metadata in advance by using this property (`supportedCustomClientMetadata`),
+ Authlete can recognize them and stores their values into the database. The stored custom client
+ metadata values can be referenced by `customMetadata`.
+
- Standard specifications define client metadata as necessary. The following are such examples.
-
- * [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html)
- * [RFC 7591 OAuth 2.0 Dynamic Client Registration Protocol](https://www.rfc-editor.org/rfc/rfc7591.html)
- * [RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens](https://www.rfc-editor.org/rfc/rfc8705.html)
- * [OpenID Connect Client-Initiated Backchannel Authentication Flow - Core 1.0](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html)
- * [The OAuth 2.0 Authorization Framework: JWT Secured Authorization Request (JAR)](https://datatracker.ietf.org/doc/draft-ietf-oauth-jwsreq/)
- * [Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/openid-financial-api-jarm.html)
- * [OAuth 2.0 Pushed Authorization Requests (PAR)](https://datatracker.ietf.org/doc/rfc9126/)
- * [OAuth 2.0 Rich Authorization Requests (RAR)](https://datatracker.ietf.org/doc/draft-ietf-oauth-rar/)
-
- Standard client metadata included in Client Registration Request and Client Update Request (cf.
- [OIDC DynReg](https://openid.net/specs/openid-connect-registration-1_0.html), [RFC 7591](https://www.rfc-editor.org/rfc/rfc7591.html)
- and [RFC 7592](https://www.rfc-editor.org/rfc/rfc7592.html)) are, if supported by Authlete, stored
- into Authlete database. On the other hand, unrecognized client metadata are discarded.
-
- By listing up custom client metadata in advance by using this property (`supportedCustomClientMetadata`),
- Authlete can recognize them and stores their values into the database. The stored custom client
- metadata values can be referenced by `customMetadata`.
tokenExpirationLinked:
type: boolean
description: |
The flag indicating whether the expiration date of an access token never exceeds that of the
corresponding refresh token.
+ x-mint:
+ metadata:
+ description: "The flag indicating whether the expiration date of an access token never exceeds that of the corresponding refresh token."
+ content: |
+
+ When a new access token is issued by a refresh token request (= a token request with `grant_type=refresh_token`),
+ the expiration date of the access token may exceed the expiration date of the corresponding
+ refresh token. This behavior itself is not wrong and may happen when `refreshTokenKept` is
+ `true` and/or when `refreshTokenDurationKept` is `true`.
+
+ When this flag is `true`, the expiration date of an access token never exceeds that of the corresponding
+ refresh token regardless of the calculated duration based on other settings such as `accessTokenDuration`,
+ `accessTokenDuration` in `extension` and `access_token.duration` scope attribute.
+
+ It is technically possible to set a value which is bigger than the duration of refresh tokens
+ as the duration of access tokens although it is strange. In the case, the duration of an access
+ token becomes longer than the duration of the refresh token which is issued together with the
+ access token. Even if the duration values are configured so, if this flag is `true`, the expiration
+ date of the access token does not exceed that of the refresh token. That is, the duration of
+ the access token will be shortened, and as a result, the access token and the refresh token
+ will have the same expiration date.
+
- When a new access token is issued by a refresh token request (= a token request with `grant_type=refresh_token`),
- the expiration date of the access token may exceed the expiration date of the corresponding
- refresh token. This behavior itself is not wrong and may happen when `refreshTokenKept` is
- `true` and/or when `refreshTokenDurationKept` is `true`.
-
- When this flag is `true`, the expiration date of an access token never exceeds that of the corresponding
- refresh token regardless of the calculated duration based on other settings such as `accessTokenDuration`,
- `accessTokenDuration` in `extension` and `access_token.duration` scope attribute.
-
- It is technically possible to set a value which is bigger than the duration of refresh tokens
- as the duration of access tokens although it is strange. In the case, the duration of an access
- token becomes longer than the duration of the refresh token which is issued together with the
- access token. Even if the duration values are configured so, if this flag is `true`, the expiration
- date of the access token does not exceed that of the refresh token. That is, the duration of
- the access token will be shortened, and as a result, the access token and the refresh token
- will have the same expiration date.
frontChannelRequestObjectEncryptionRequired:
type: boolean
description: |
The flag indicating whether encryption of request object is required when the request object
is passed through the front channel.
+ x-mint:
+ metadata:
+ description: "The flag indicating whether encryption of request object is required when the request object is passed through the front channel."
+ content: |
+
+ This flag does not affect the processing of request objects at the Pushed Authorization Request
+ Endpoint, which is defined in [OAuth 2.0 Pushed Authorization Requests](https://datatracker.ietf.org/doc/rfc9126/).
+ Unecrypted request objects are accepted at the endpoint even if this flag is `true`.
+
+ This flag does not indicate whether a request object is always required. There is a different
+ flag, `requestObjectRequired`, for the purpose. See the description of `requestObjectRequired`
+ for details.
+
+ Even if this flag is `false`, encryption of request object is required if the `frontChannelRequestObjectEncryptionRequired`
+ flag of the client is `true`.
+
- This flag does not affect the processing of request objects at the Pushed Authorization Request
- Endpoint, which is defined in [OAuth 2.0 Pushed Authorization Requests](https://datatracker.ietf.org/doc/rfc9126/).
- Unecrypted request objects are accepted at the endpoint even if this flag is `true`.
-
- This flag does not indicate whether a request object is always required. There is a different
- flag, `requestObjectRequired`, for the purpose. See the description of `requestObjectRequired`
- for details.
-
- Even if this flag is `false`, encryption of request object is required if the `frontChannelRequestObjectEncryptionRequired`
- flag of the client is `true`.
requestObjectEncryptionAlgMatchRequired:
type: boolean
description: |
The flag indicating whether the JWE alg of encrypted request object must match the `request_object_encryption_alg`
client metadata of the client that has sent the request object.
+ x-mint:
+ metadata:
+ description: "The flag indicating whether the JWE alg of encrypted request object must match the `request_object_encryption_alg` client metadata of the client that has sent the request object."
+ content: |
+
+ The request_object_encryption_alg client metadata itself is defined in [OpenID Connect Dynamic
+ Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) as follows.
+
+ > request_object_encryption_alg
+ >
+ > OPTIONAL. JWE [JWE] alg algorithm [JWA] the RP is declaring that it may use for encrypting
+ Request Objects sent to the OP. This parameter SHOULD be included when symmetric encryption
+ will be used, since this signals to the OP that a client_secret value needs to be returned
+ from which the symmetric key will be derived, that might not otherwise be returned. The RP
+ MAY still use other supported encryption algorithms or send unencrypted Request Objects, even
+ when this parameter is present. If both signing and encryption are requested, the Request Object
+ will be signed then encrypted, with the result being a Nested JWT, as defined in [JWT]. The
+ default, if omitted, is that the RP is not declaring whether it might encrypt any Request Objects.
+
+ The point here is "The RP MAY still use other supported encryption algorithms or send unencrypted
+ Request Objects, even when this parameter is present."
+
+ The Client's property that represents the client metadata is `requestEncryptionAlg`. See the
+ description of `requestEncryptionAlg` for details.
+
+ Even if this flag is `false`, the match is required if the `requestObjectEncryptionAlgMatchRequired`
+ flag of the client is `true`.
+
- The request_object_encryption_alg client metadata itself is defined in [OpenID Connect Dynamic
- Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) as follows.
-
- > request_object_encryption_alg
- >
- > OPTIONAL. JWE [JWE] alg algorithm [JWA] the RP is declaring that it may use for encrypting
- Request Objects sent to the OP. This parameter SHOULD be included when symmetric encryption
- will be used, since this signals to the OP that a client_secret value needs to be returned
- from which the symmetric key will be derived, that might not otherwise be returned. The RP
- MAY still use other supported encryption algorithms or send unencrypted Request Objects, even
- when this parameter is present. If both signing and encryption are requested, the Request Object
- will be signed then encrypted, with the result being a Nested JWT, as defined in [JWT]. The
- default, if omitted, is that the RP is not declaring whether it might encrypt any Request Objects.
-
- The point here is "The RP MAY still use other supported encryption algorithms or send unencrypted
- Request Objects, even when this parameter is present."
-
- The Client's property that represents the client metadata is `requestEncryptionAlg`. See the
- description of `requestEncryptionAlg` for details.
-
- Even if this flag is `false`, the match is required if the `requestObjectEncryptionAlgMatchRequired`
- flag of the client is `true`.
requestObjectEncryptionEncMatchRequired:
type: boolean
description: |
The flag indicating whether the JWE `enc` of encrypted request object must match the `request_object_encryption_enc`
client metadata of the client that has sent the request object.
+ x-mint:
+ metadata:
+ description: "The flag indicating whether the JWE `enc` of encrypted request object must match the `request_object_encryption_enc` client metadata of the client that has sent the request object."
+ content: |
+
+ The `request_object_encryption_enc` client metadata itself is defined in [OpenID Connect Dynamic
+ Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) as follows.
+
+ > request_object_encryption_enc
+ >
+ > OPTIONAL. JWE enc algorithm [JWA] the RP is declaring that it may use for encrypting Request
+ Objects sent to the OP. If request_object_encryption_alg is specified, the default for this
+ value is A128CBC-HS256. When request_object_encryption_enc is included, request_object_encryption_alg
+ MUST also be provided.
- The `request_object_encryption_enc` client metadata itself is defined in [OpenID Connect Dynamic
- Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) as follows.
-
- > request_object_encryption_enc
- >
- > OPTIONAL. JWE enc algorithm [JWA] the RP is declaring that it may use for encrypting Request
- Objects sent to the OP. If request_object_encryption_alg is specified, the default for this
- value is A128CBC-HS256. When request_object_encryption_enc is included, request_object_encryption_alg
- MUST also be provided.
+ The Client's property that represents the client metadata is `requestEncryptionEnc`. See the
+ description of `requestEncryptionEnc` for details.
- The Client's property that represents the client metadata is `requestEncryptionEnc`. See the
- description of `requestEncryptionEnc` for details.
+ Even if this flag is false, the match is required if the `requestObjectEncryptionEncMatchRequired`
+ flag is `true`.
+
- Even if this flag is false, the match is required if the `requestObjectEncryptionEncMatchRequired`
- flag is `true`.
hsmEnabled:
type: boolean
description: |
@@ -11953,34 +12201,46 @@ components:
The flag indicating whether every authorization request (and any request serving as an authorization
request such as CIBA backchannel authentication request and device authorization request) must
include the `grant_management_action` request parameter.
+ x-mint:
+ metadata:
+ description: "The flag indicating whether every authorization request (and any request serving as an authorization request such as CIBA backchannel authentication request and device authorization request) must include the `grant_management_action` request parameter."
+ content: |
+
+ This property corresponds to the `grant_management_action_required` server metadata defined
+ in [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html).
+
+ Note that setting true to this property will result in blocking all public clients because
+ the specification requires that grant management be usable only by confidential clients for
+ security reasons.
+
- This property corresponds to the `grant_management_action_required` server metadata defined
- in [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html).
-
- Note that setting true to this property will result in blocking all public clients because
- the specification requires that grant management be usable only by confidential clients for
- security reasons.
unauthorizedOnClientConfigSupported:
type: boolean
description: |
The flag indicating whether Authlete's `/api/client/registration` API uses `UNAUTHORIZED` as
a value of the `action` response parameter when appropriate.
+ x-mint:
+ metadata:
+ description: "The flag indicating whether Authlete's `/api/client/registration` API uses `UNAUTHORIZED` as a value of the `action` response parameter when appropriate."
+ content: |
+
+ The `UNAUTHORIZED` enum value was initially not defined as a possible value of the `action`
+ parameter in an `/api/client/registration` API response. This means that implementations of
+ client `configuration` endpoint were not able to conform to [RFC 7592](https://www.rfc-editor.org/rfc/rfc7592.html)
+ strictly.
+
+ For backward compatibility (to avoid breaking running systems), Authlete's `/api/client/registration`
+ API does not return the `UNAUTHORIZED` enum value if this flag is not turned on.
+
+ The steps an existing implementation of client configuration endpoint has to do in order to
+ conform to the requirement related to "401 Unauthorized" are as follows.
+
+ 1. Update the Authlete library (e.g. authlete-java-common) your system is using.
+ 2. Update your implementation of client configuration endpoint so that it can handle the
+ `UNAUTHORIZED` action.
+ 3. Turn on this `unauthorizedOnClientConfigSupported` flag.
+
- The `UNAUTHORIZED` enum value was initially not defined as a possible value of the `action`
- parameter in an `/api/client/registration` API response. This means that implementations of
- client `configuration` endpoint were not able to conform to [RFC 7592](https://www.rfc-editor.org/rfc/rfc7592.html)
- strictly.
-
- For backward compatibility (to avoid breaking running systems), Authlete's `/api/client/registration`
- API does not return the `UNAUTHORIZED` enum value if this flag is not turned on.
-
- The steps an existing implementation of client configuration endpoint has to do in order to
- conform to the requirement related to "401 Unauthorized" are as follows.
-
- 1. Update the Authlete library (e.g. authlete-java-common) your system is using.
- 2. Update your implementation of client configuration endpoint so that it can handle the
- `UNAUTHORIZED` action.
- 3. Turn on this `unauthorizedOnClientConfigSupported` flag.
dcrScopeUsedAsRequestable:
type: boolean
description: |
@@ -12007,65 +12267,77 @@ components:
description: |
The flag indicating whether the port number component of redirection URIs can be variable when
the host component indicates loopback.
+ x-mint:
+ metadata:
+ description: "The flag indicating whether the port number component of redirection URIs can be variable when the host component indicates loopback."
+ content: |
+
+ When this flag is `true`, if the host component of a redirection URI specified in an authorization
+ request indicates loopback (to be precise, when the host component is localhost, `127.0.0.1`
+ or `::1`), the port number component is ignored when the specified redirection URI is compared
+ to pre-registered ones. This behavior is described in [7.3. Loopback Interface Redirection](
+ https://www.rfc-editor.org/rfc/rfc8252.html#section-7.3) of [RFC 8252 OAuth 2.0](https://www.rfc-editor.org/rfc/rfc8252.html)
+ for Native Apps.
+
+ [3.1.2.3. Dynamic Configuration](https://www.rfc-editor.org/rfc/rfc6749.html#section-3.1.2.3)
+ of [RFC 6749](https://www.rfc-editor.org/rfc/rfc6749.html) states _"If the client registration
+ included the full redirection URI, the authorization server MUST compare the two URIs using
+ simple string comparison as defined in [RFC3986] Section 6.2.1."_ Also, the description of
+ `redirect_uri` in [3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)
+ of [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) states
+ _"This URI MUST exactly match one of the Redirection URI values for the Client pre-registered
+ at the OpenID Provider, with the matching performed as described in Section 6.2.1 of [RFC3986]
+ (**Simple String Comparison**)."_ These "Simple String Comparison" requirements are preceded
+ by this flag. That is, even when the conditions described in RFC 6749 and OpenID Connect Core 1.0
+ are satisfied, the port number component of loopback redirection URIs can be variable when this
+ flag is `true`.
+
+ [8.3. Loopback Redirect Considerations](https://www.rfc-editor.org/rfc/rfc8252.html#section-8.3)
+ of [RFC 8252](https://www.rfc-editor.org/rfc/rfc8252.html) states as follows.
+
+ > While redirect URIs using localhost (i.e., `"http://localhost:{port}/{path}"`) function
+ similarly to loopback IP redirects described in Section 7.3, the use of localhost is NOT RECOMMENDED.
+ Specifying a redirect URI with the loopback IP literal rather than localhost avoids inadvertently
+ listening on network interfaces other than the loopback interface. It is also less susceptible
+ to client-side firewalls and misconfigured host name resolution on the user's device.
+
+ However, Authlete allows the port number component to be variable in the case of `localhost`,
+ too. It is left to client applications whether they use `localhost` or a literal loopback IP
+ address (`127.0.0.1` for IPv4 or `::1` for IPv6).
+
+ Section 7.3 and Section 8.3 of [RFC 8252](https://www.rfc-editor.org/rfc/rfc8252.html) state
+ that loopback redirection URIs use the `"http"` scheme, but Authlete allows the port number
+ component to be variable in other cases (e.g. in the case of the `"https"` scheme), too.
+
- When this flag is `true`, if the host component of a redirection URI specified in an authorization
- request indicates loopback (to be precise, when the host component is localhost, `127.0.0.1`
- or `::1`), the port number component is ignored when the specified redirection URI is compared
- to pre-registered ones. This behavior is described in [7.3. Loopback Interface Redirection](
- https://www.rfc-editor.org/rfc/rfc8252.html#section-7.3) of [RFC 8252 OAuth 2.0](https://www.rfc-editor.org/rfc/rfc8252.html)
- for Native Apps.
-
- [3.1.2.3. Dynamic Configuration](https://www.rfc-editor.org/rfc/rfc6749.html#section-3.1.2.3)
- of [RFC 6749](https://www.rfc-editor.org/rfc/rfc6749.html) states _"If the client registration
- included the full redirection URI, the authorization server MUST compare the two URIs using
- simple string comparison as defined in [RFC3986] Section 6.2.1."_ Also, the description of
- `redirect_uri` in [3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)
- of [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) states
- _"This URI MUST exactly match one of the Redirection URI values for the Client pre-registered
- at the OpenID Provider, with the matching performed as described in Section 6.2.1 of [RFC3986]
- (**Simple String Comparison**)."_ These "Simple String Comparison" requirements are preceded
- by this flag. That is, even when the conditions described in RFC 6749 and OpenID Connect Core 1.0
- are satisfied, the port number component of loopback redirection URIs can be variable when this
- flag is `true`.
-
- [8.3. Loopback Redirect Considerations](https://www.rfc-editor.org/rfc/rfc8252.html#section-8.3)
- of [RFC 8252](https://www.rfc-editor.org/rfc/rfc8252.html) states as follows.
-
- > While redirect URIs using localhost (i.e., `"http://localhost:{port}/{path}"`) function
- similarly to loopback IP redirects described in Section 7.3, the use of localhost is NOT RECOMMENDED.
- Specifying a redirect URI with the loopback IP literal rather than localhost avoids inadvertently
- listening on network interfaces other than the loopback interface. It is also less susceptible
- to client-side firewalls and misconfigured host name resolution on the user's device.
-
- However, Authlete allows the port number component to be variable in the case of `localhost`,
- too. It is left to client applications whether they use `localhost` or a literal loopback IP
- address (`127.0.0.1` for IPv4 or `::1` for IPv6).
-
- Section 7.3 and Section 8.3 of [RFC 8252](https://www.rfc-editor.org/rfc/rfc8252.html) state
- that loopback redirection URIs use the `"http"` scheme, but Authlete allows the port number
- component to be variable in other cases (e.g. in the case of the `"https"` scheme), too.
requestObjectAudienceChecked:
type: boolean
description: |
The flag indicating whether Authlete checks whether the `aud` claim of request objects matches
the issuer identifier of this service.
+ x-mint:
+ metadata:
+ description: "The flag indicating whether Authlete checks whether the `aud` claim of request objects matches the issuer identifier of this service."
+ content: |
+
+ [Section 6.1. Passing a Request Object by Value](https://openid.net/specs/openid-connect-core-1_0.html#JWTRequests)
+ of [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) has the following
+ statement.
- [Section 6.1. Passing a Request Object by Value](https://openid.net/specs/openid-connect-core-1_0.html#JWTRequests)
- of [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) has the following
- statement.
+ > The `aud` value SHOULD be or include the OP's Issuer Identifier URL.
- > The `aud` value SHOULD be or include the OP's Issuer Identifier URL.
+ Likewise, [Section 4. Request Object](https://www.rfc-editor.org/rfc/rfc9101.html#section-4) of
+ [RFC 9101](https://www.rfc-editor.org/rfc/rfc9101.html) (The OAuth 2.0 Authorization Framework:
+ JWT-Secured Authorization Request (JAR)) has the following statement.
- Likewise, [Section 4. Request Object](https://www.rfc-editor.org/rfc/rfc9101.html#section-4) of
- [RFC 9101](https://www.rfc-editor.org/rfc/rfc9101.html) (The OAuth 2.0 Authorization Framework:
- JWT-Secured Authorization Request (JAR)) has the following statement.
+ > The value of aud should be the value of the authorization server (AS) issuer, as defined in
+ [RFC 8414](https://www.rfc-editor.org/rfc/rfc8414.html).
- > The value of aud should be the value of the authorization server (AS) issuer, as defined in
- [RFC 8414](https://www.rfc-editor.org/rfc/rfc8414.html).
+ As excerpted above, validation on the `aud` claim of request objects is optional. However, if
+ this flag is turned on, Authlete checks whether the `aud` claim of request objects matches the issuer
+ identifier of this service and raises an error if they are different.
+
- As excerpted above, validation on the `aud` claim of request objects is optional. However, if
- this flag is turned on, Authlete checks whether the `aud` claim of request objects matches the issuer
- identifier of this service and raises an error if they are different.
accessTokenForExternalAttachmentEmbedded:
type: boolean
description: |
@@ -12602,14 +12874,20 @@ components:
type: string
description: |
The value of the `credential_configuration_ids` property of the credential offer.
+ x-mint:
+ metadata:
+ description: "The value of the `credential_configuration_ids` property of the credential offer."
+ content: |
+
+ ```
+ {
+ "credential_issuer": "...",
+ "credential_configuration_ids": [ ... ],
+ "grants": { ... }
+ }
+ ```
+
- ```
- {
- "credential_issuer": "...",
- "credential_configuration_ids": [ ... ],
- "grants": { ... }
- }
- ```
txCode:
type: string
description: |
@@ -13300,65 +13578,83 @@ components:
description: |
The flag indicating whether encryption of request object is required when the request object
is passed through the front channel.
+ x-mint:
+ metadata:
+ description: "The flag indicating whether encryption of request object is required when the request object is passed through the front channel."
+ content: |
+
+ This flag does not affect the processing of request objects at the Pushed Authorization Request
+ Endpoint, which is defined in [OAuth 2.0 Pushed Authorization Requests](https://datatracker.ietf.org/doc/rfc9126/).
+ Unecrypted request objects are accepted at the endpoint even if this flag is `true`.
+
+ This flag does not indicate whether a request object is always required. There is a different
+ flag, `requestObjectRequired`, for the purpose.
+
+ Even if this flag is `false`, encryption of request object is required if the `frontChannelRequestObjectEncryptionRequired`
+ flag of the service is `true`.
+
- This flag does not affect the processing of request objects at the Pushed Authorization Request
- Endpoint, which is defined in [OAuth 2.0 Pushed Authorization Requests](https://datatracker.ietf.org/doc/rfc9126/).
- Unecrypted request objects are accepted at the endpoint even if this flag is `true`.
-
- This flag does not indicate whether a request object is always required. There is a different
- flag, `requestObjectRequired`, for the purpose.
-
- Even if this flag is `false`, encryption of request object is required if the `frontChannelRequestObjectEncryptionRequired`
- flag of the service is `true`.
requestObjectEncryptionAlgMatchRequired:
type: boolean
description: |
The flag indicating whether the JWE alg of encrypted request object must match the `request_object_encryption_alg`
client metadata.
+ x-mint:
+ metadata:
+ description: "The flag indicating whether the JWE alg of encrypted request object must match the `request_object_encryption_alg` client metadata."
+ content: |
+
+ The `request_object_encryption_alg` client metadata itself is defined in [OpenID Connect Dynamic
+ Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) as follows.
+
+ > request_object_encryption_alg
+ >
+ > OPTIONAL. JWE [JWE] alg algorithm [JWA] the RP is declaring that it may use for encrypting Request
+ Objects sent to the OP. This parameter SHOULD be included when symmetric encryption will be used,
+ since this signals to the OP that a client_secret value needs to be returned from which the
+ symmetric key will be derived, that might not otherwise be returned. The RP MAY still use other
+ supported encryption algorithms or send unencrypted Request Objects, even when this parameter
+ is present. If both signing and encryption are requested, the Request Object will be signed
+ then encrypted, with the result being a Nested JWT, as defined in [JWT]. The default, if omitted,
+ is that the RP is not declaring whether it might encrypt any Request Objects.
+
+ The point here is "The RP MAY still use other supported encryption algorithms or send unencrypted
+ Request Objects, even when this parameter is present."
+
+ The property that represents the client metadata is `requestEncryptionAlg`. See the description
+ of `requestEncryptionAlg` for details.
+
+ Even if this flag is `false`, the match is required if the `requestObjectEncryptionAlgMatchRequired`
+ flag of the service is `true`.
+
- The `request_object_encryption_alg` client metadata itself is defined in [OpenID Connect Dynamic
- Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) as follows.
-
- > request_object_encryption_alg
- >
- > OPTIONAL. JWE [JWE] alg algorithm [JWA] the RP is declaring that it may use for encrypting Request
- Objects sent to the OP. This parameter SHOULD be included when symmetric encryption will be used,
- since this signals to the OP that a client_secret value needs to be returned from which the
- symmetric key will be derived, that might not otherwise be returned. The RP MAY still use other
- supported encryption algorithms or send unencrypted Request Objects, even when this parameter
- is present. If both signing and encryption are requested, the Request Object will be signed
- then encrypted, with the result being a Nested JWT, as defined in [JWT]. The default, if omitted,
- is that the RP is not declaring whether it might encrypt any Request Objects.
-
- The point here is "The RP MAY still use other supported encryption algorithms or send unencrypted
- Request Objects, even when this parameter is present."
-
- The property that represents the client metadata is `requestEncryptionAlg`. See the description
- of `requestEncryptionAlg` for details.
-
- Even if this flag is `false`, the match is required if the `requestObjectEncryptionAlgMatchRequired`
- flag of the service is `true`.
requestObjectEncryptionEncMatchRequired:
type: boolean
description: |
The flag indicating whether the JWE enc of encrypted request object must match the `request_object_encryption_enc`
client metadata.
+ x-mint:
+ metadata:
+ description: "The flag indicating whether the JWE enc of encrypted request object must match the `request_object_encryption_enc` client metadata."
+ content: |
+
+ The `request_object_encryption_enc` client metadata itself is defined in [OpenID Connect Dynamic
+ Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) as follows.
+
+ > request_object_encryption_enc
+ >
+ > OPTIONAL. JWE enc algorithm [JWA] the RP is declaring that it may use for encrypting Request
+ Objects sent to the OP. If request_object_encryption_alg is specified, the default for this
+ value is A128CBC-HS256. When request_object_encryption_enc is included, request_object_encryption_alg
+ MUST also be provided.
+
+ The property that represents the client metadata is `requestEncryptionEnc`. See the description
+ of `requestEncryptionEnc` for details.
+
+ Even if this flag is `false`, the match is required if the `requestObjectEncryptionEncMatchRequired`
+ flag of the service is `true`.
+
- The `request_object_encryption_enc` client metadata itself is defined in [OpenID Connect Dynamic
- Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) as follows.
-
- > request_object_encryption_enc
- >
- > OPTIONAL. JWE enc algorithm [JWA] the RP is declaring that it may use for encrypting Request
- Objects sent to the OP. If request_object_encryption_alg is specified, the default for this
- value is A128CBC-HS256. When request_object_encryption_enc is included, request_object_encryption_alg
- MUST also be provided.
-
- The property that represents the client metadata is `requestEncryptionEnc`. See the description
- of `requestEncryptionEnc` for details.
-
- Even if this flag is `false`, the match is required if the `requestObjectEncryptionEncMatchRequired`
- flag of the service is `true`.
singleAccessTokenPerSubject:
type: boolean
description: |
@@ -13650,61 +13946,91 @@ components:
type: string
description: |
The value of the `id_token` property in the claims request parameter or in the claims property in a request object.
+ x-mint:
+ metadata:
+ description: "The value of the `id_token` property in the claims request parameter or in the claims property in a request object."
+ content: |
+
+ A client application may request certain claims be embedded in an ID token or in a response from the userInfo endpoint.
+ There are several ways. Including the `claims` request parameter and including the `claims` property in a request object are such examples.
+ In both the cases, the value of the `claims` parameter/property is JSON. Its format is described in [5.5. Requesting Claims using the "claims"
+ Request Parameter](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter).
+
+ The following is an excerpt from the specification.
+ You can find `userinfo` and `id_token` are top-level properties.
+
+ ```json
+ {
+ "userinfo":
+ {
+ "given_name": { "essential": true },
+ "nickname": null,
+ "email": { "essential": true },
+ "email_verified": { "essential": true },
+ "picture": null,
+ "http://example.info/claims/groups": null
+ },
+ "id_token":
+ {
+ "auth_time": { "essential": true },
+ "acr": { "values": [ "urn:mace:incommon:iap:silver" ] }
+ }
+ }
+ ```
- A client application may request certain claims be embedded in an ID token or in a response from the userInfo endpoint.
- There are several ways. Including the `claims` request parameter and including the `claims` property in a request object are such examples.
- In both the cases, the value of the `claims` parameter/property is JSON. Its format is described in [5.5. Requesting Claims using the "claims"
- Request Parameter](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter).
-
- The following is an excerpt from the specification.
- You can find `userinfo` and `id_token` are top-level properties.
+ This value of this property is the value of the `id_token` property in JSON format.
+ For example, if the JSON above is included in an authorization request, this property holds JSON equivalent to the following.
- ```json
- {
- "userinfo":
- {
- "given_name": { "essential": true },
- "nickname": null,
- "email": { "essential": true },
- "email_verified": { "essential": true },
- "picture": null,
- "http://example.info/claims/groups": null
- },
- "id_token":
+ ```json
{
"auth_time": { "essential": true },
"acr": { "values": [ "urn:mace:incommon:iap:silver" ] }
}
- }
- ```
-
- This value of this property is the value of the `id_token` property in JSON format.
- For example, if the JSON above is included in an authorization request, this property holds JSON equivalent to the following.
+ ```
- ```json
- {
- "auth_time": { "essential": true },
- "acr": { "values": [ "urn:mace:incommon:iap:silver" ] }
- }
- ```
+ Note that if a request object is given and it contains the `claims` property and if the `claims` request parameter is also given,
+ this property holds the former value.
+
- Note that if a request object is given and it contains the `claims` property and if the `claims` request parameter is also given,
- this property holds the former value.
userInfoClaims:
type: string
description: |
The value of the `userinfo` property in the `claims` request parameter or in the `claims` property in a request object.
+ x-mint:
+ metadata:
+ description: "The value of the `userinfo` property in the `claims` request parameter or in the `claims` property in a request object."
+ content: |
+
+ A client application may request certain claims be embedded in an ID token or in a response from the userInfo endpoint.
+ There are several ways. Including the `claims` request parameter and including the `claims` property in a request object are such examples.
+ In both the cases, the value of the `claims` parameter/property is JSON. Its format is described in [5.5. Requesting Claims using the "claims"
+ Request Parameter](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter).
+
+ The following is an excerpt from the specification. You can find `userinfo` and `id_token` are top-level properties.
+
+ ```json
+ {
+ "userinfo":
+ {
+ "given_name": { "essential": true },
+ "nickname": null,
+ "email": { "essential": true },
+ "email_verified": { "essential": true },
+ "picture": null,
+ "http://example.info/claims/groups": null
+ },
+ "id_token":
+ {
+ "auth_time": { "essential": true },
+ "acr": { "values": [ "urn:mace:incommon:iap:silver" ] }
+ }
+ }
+ ````
- A client application may request certain claims be embedded in an ID token or in a response from the userInfo endpoint.
- There are several ways. Including the `claims` request parameter and including the `claims` property in a request object are such examples.
- In both the cases, the value of the `claims` parameter/property is JSON. Its format is described in [5.5. Requesting Claims using the "claims"
- Request Parameter](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter).
-
- The following is an excerpt from the specification. You can find `userinfo` and `id_token` are top-level properties.
+ The value of this property is the value of the `userinfo` property in JSON format.
+ For example, if the JSON above is included in an authorization request, this property holds JSON equivalent to the following.
- ```json
- {
- "userinfo":
+ ```json
{
"given_name": { "essential": true },
"nickname": null,
@@ -13712,31 +14038,13 @@ components:
"email_verified": { "essential": true },
"picture": null,
"http://example.info/claims/groups": null
- },
- "id_token":
- {
- "auth_time": { "essential": true },
- "acr": { "values": [ "urn:mace:incommon:iap:silver" ] }
}
- }
- ````
+ ```
- The value of this property is the value of the `userinfo` property in JSON format.
- For example, if the JSON above is included in an authorization request, this property holds JSON equivalent to the following.
-
- ```json
- {
- "given_name": { "essential": true },
- "nickname": null,
- "email": { "essential": true },
- "email_verified": { "essential": true },
- "picture": null,
- "http://example.info/claims/groups": null
- }
- ```
+ Note that if a request object is given and it contains the `claims` property and if the `claims` request parameter is also given,
+ the value of this property holds the former value.
+
- Note that if a request object is given and it contains the `claims` property and if the `claims` request parameter is also given,
- the value of this property holds the former value.
resources:
type: array
items:
@@ -13906,15 +14214,21 @@ components:
description: |
Flag which indicates whether [Native SSO](https://openid.net/specs/openid-connect-native-sso-1_0.html)
is requested. This property should be set to `true` when all the following conditions are satisfied:
+ x-mint:
+ metadata:
+ description: "Flag which indicates whether [Native SSO](https://openid.net/specs/openid-connect-native-sso-1_0.html) is requested. This property should be set to `true` when all the following conditions are satisfied:"
+ content: |
+
+ - The service supports Native SSO (see `nativeSsoSupported` property of Service).
+ - The service supports the `openid` and `device_sso` scopes.
+ - The client is allowed to request the `openid` and `device_sso` scopes.
+ - The authorization request includes the `openid` and `device_sso` scopes.
+ - The authorization request's `response_type` includes `code`.
+
+ NOTE: If this property is set to `true`, the `sessionId` request parameter must be provided
+ to the `/auth/authorization/issue` API.
+
- - The service supports Native SSO (see `nativeSsoSupported` property of Service).
- - The service supports the `openid` and `device_sso` scopes.
- - The client is allowed to request the `openid` and `device_sso` scopes.
- - The authorization request includes the `openid` and `device_sso` scopes.
- - The authorization request's `response_type` includes `code`.
-
- NOTE: If this property is set to `true`, the `sessionId` request parameter must be provided
- to the `/auth/authorization/issue` API.
metadataDocumentUsed:
type: boolean
description: |
@@ -14063,10 +14377,16 @@ components:
to support the [OpenID Connect Native SSO for Mobile Apps 1.0](https://openid.net/specs/openid-connect-native-sso-1_0.html)
specification (a.k.a. "Native SSO"). To enable support for the Native SSO specification, the
`nativeSsoSupported` property of your service must be set to `true`.
+ x-mint:
+ metadata:
+ description: "The session ID of the user's authentication session. The specified value will be embedded in the ID token as the value of the `sid` claim. This parameter needs to be provided only if you want to support the [OpenID Connect Native SSO for Mobile Apps 1.0](https://openid.net/specs/openid-connect-native-sso-1_0.html) specification (a.k.a. \"Native SSO\"). To enable support for the Native SSO specification, the `nativeSsoSupported` property of your service must be set to `true`."
+ content: |
+
+ NOTE: When the response from the `/auth/authorization` API contains the `nativeSsoRequested`
+ property with a value of `true`, the `sessionId` request parameter must be provided to the
+ `/auth/authorization/issue` API.
+
- NOTE: When the response from the `/auth/authorization` API contains the `nativeSsoRequested`
- property with a value of `true`, the `sessionId` request parameter must be provided to the
- `/auth/authorization/issue` API.
idTokenAudType:
type: string
description: |
@@ -14085,66 +14405,72 @@ components:
type: string
description: |
Values of verified claims requested indirectly by "transformed claims".
-
- A client application may request "transformed claims". Each of transformed claims uses an existing
- claim as input. As a result, to compute the value of a transformed claim, the value of the referenced
- existing claim is needed. This `verifiedClaimsForTx` request parameter has to be used to provide
- values of existing claims for computation of transformed claims.
-
- A response from the `/auth/authorization` API may include the `requestedVerifiedClaimsForTx` response
- parameter which is a list of verified claims that are referenced indirectly by transformed claims
- (cf. `requestedVerifiedClaimsForTx` in `/auth/authorization` API response). The authorization
- server implementation should prepare values of the verified claims listed in `requestedVerifiedClaimsForTx`
- and pass them as the value of this `verifiedClaimsForTx` request parameter.
-
- The following is an example of the value of this request parameter.
-
- ```
- [
- "{\"birthdate\":\"1970-01-23\",\"nationalities\":[\"DEU\",\"USA\"]}"
- ]
- ```
-
- The reason that this `verifiedClaimsForTx` property is an array is that the `"verified_claims"`
- property in the claims request parameter of an authorization request can be an array like below.
-
- ```
- {
- "transformed_claims": {
- "nationality_usa": {
- "claim": "nationalities",
- "fn": [
- [ "eq", "USA" ],
- "any"
+ x-mint:
+ metadata:
+ description: "Values of verified claims requested indirectly by \"transformed claims\"."
+ content: |
+
+ A client application may request "transformed claims". Each of transformed claims uses an existing
+ claim as input. As a result, to compute the value of a transformed claim, the value of the referenced
+ existing claim is needed. This `verifiedClaimsForTx` request parameter has to be used to provide
+ values of existing claims for computation of transformed claims.
+
+ A response from the `/auth/authorization` API may include the `requestedVerifiedClaimsForTx` response
+ parameter which is a list of verified claims that are referenced indirectly by transformed claims
+ (cf. `requestedVerifiedClaimsForTx` in `/auth/authorization` API response). The authorization
+ server implementation should prepare values of the verified claims listed in `requestedVerifiedClaimsForTx`
+ and pass them as the value of this `verifiedClaimsForTx` request parameter.
+
+ The following is an example of the value of this request parameter.
+
+ ```
+ [
+ "{\"birthdate\":\"1970-01-23\",\"nationalities\":[\"DEU\",\"USA\"]}"
+ ]
+ ```
+
+ The reason that this `verifiedClaimsForTx` property is an array is that the `"verified_claims"`
+ property in the claims request parameter of an authorization request can be an array like below.
+
+ ```
+ {
+ "transformed_claims": {
+ "nationality_usa": {
+ "claim": "nationalities",
+ "fn": [
+ [ "eq", "USA" ],
+ "any"
+ ]
+ }
+ },
+ "id_token": {
+ "verified_claims": [
+ {
+ "verification": { "trust_framework": { "value": "gold" } },
+ "claims": { "::18_or_above": null }
+ },
+ {
+ "verification": { "trust_framework": { "value": "silver" } },
+ "claims": { ":nationality_usa": null }
+ }
]
}
- },
- "id_token": {
- "verified_claims": [
- {
- "verification": { "trust_framework": { "value": "gold" } },
- "claims": { "::18_or_above": null }
- },
- {
- "verification": { "trust_framework": { "value": "silver" } },
- "claims": { ":nationality_usa": null }
- }
- ]
}
- }
- ```
+ ```
- For the example above, the value of this `verifiedClaimsForTx` property should be an array of
- size 2 and look like below. The first element is JSON including claims which have been verified
- under the trust framework `"gold"`, and the second element is JSON including claims which have
- been verified under the trust framework `"silver"`.
+ For the example above, the value of this `verifiedClaimsForTx` property should be an array of
+ size 2 and look like below. The first element is JSON including claims which have been verified
+ under the trust framework `"gold"`, and the second element is JSON including claims which have
+ been verified under the trust framework `"silver"`.
+
+ ```
+ [
+ "{\"birthdate\":\"1970-01-23\"}",
+ "{\"nationalities\":[\"DEU\",\"USA\"]}"
+ ]
+ ```
+
- ```
- [
- "{\"birthdate\":\"1970-01-23\"}",
- "{\"nationalities\":[\"DEU\",\"USA\"]}"
- ]
- ```
authorization_ticket_info:
type: object
properties:
@@ -14750,24 +15076,36 @@ components:
be used as the value of this `deviceSecret` request parameter to the `/nativesso` API. The authorization
server may choose to issue a new device secret; in that case, it is free to generate a new device
secret and specify the new value.
+ x-mint:
+ metadata:
+ description: "If the response from the `/auth/token` API contains the `deviceSecret` parameter, its value should be used as the value of this `deviceSecret` request parameter to the `/nativesso` API. The authorization server may choose to issue a new device secret; in that case, it is free to generate a new device secret and specify the new value."
+ content: |
+
+ If the response from the `/auth/token` API does not contain the `deviceSecret` parameter, or
+ if its value is invalid, the authorization server must generate a new device secret and specify
+ it in the deviceSecret parameter to the `/nativesso` API.
+
+ The specified value is used as the value of the `device_secret` property in the token response.
+
- If the response from the `/auth/token` API does not contain the `deviceSecret` parameter, or
- if its value is invalid, the authorization server must generate a new device secret and specify
- it in the deviceSecret parameter to the `/nativesso` API.
-
- The specified value is used as the value of the `device_secret` property in the token response.
deviceSecretHash:
type: string
description: |
The authorization server should compute the hash value of the device secret based on its own logic
and specify the computed hash as the value of this `deviceSecretHash` request parameter to the
`/nativesso` API.
+ x-mint:
+ metadata:
+ description: "The authorization server should compute the hash value of the device secret based on its own logic and specify the computed hash as the value of this `deviceSecretHash` request parameter to the `/nativesso` API."
+ content: |
+
+ When the `deviceSecretHash` parameter is omitted, the implementation of the `/nativesso` API
+ generates the device secret hash by computing the SHA-256 hash of the device secret and encoding
+ it with base64url. Note that this hash computation logic is not a rule defined in the Native SSO
+ specification; rather, it is Authlete-specific fallback logic used when the `deviceSecretHash`
+ parameter is omitted.
+
- When the `deviceSecretHash` parameter is omitted, the implementation of the `/nativesso` API
- generates the device secret hash by computing the SHA-256 hash of the device secret and encoding
- it with base64url. Note that this hash computation logic is not a rule defined in the Native SSO
- specification; rather, it is Authlete-specific fallback logic used when the `deviceSecretHash`
- parameter is omitted.
metadataDocumentLocation:
type: string
format: uri
@@ -15100,22 +15438,28 @@ components:
type: string
description: |
The target URI of the resource request, including the query part, if any.
+ x-mint:
+ metadata:
+ description: "The target URI of the resource request, including the query part, if any."
+ content: |
+
+ This parameter is used as the value of the @target-uri derived component for HTTP message signatures
+ [RFC 9421 HTTP Message Signatures, Section 2.2.2. Target URI](https://www.rfc-editor.org/rfc/rfc9421.html#section-2.2.2)).
+ Additionally, other derived components such as `@authority`, `@scheme`, `@path`, `@query` and
+ `@query-param` are computed from this parameter.
+
+ When this parameter is omitted, the value of the `htu` parameter is used. The `htu` parameter
+ represents the URL of the resource endpoint, which is identical to the target URI of the resource
+ request as long as the request does not include a query component. Conversely, if the resource
+ request includes a query component, the value of the `htu` parameter will not match the target
+ URI, and in that case, the HTTP message signature verification will fail.
+
+ If neither this `targetUri` parameter nor the `htu` parameter is specified, the target URI is
+ considered unavailable. If HTTP message signing requires the target-uri derived component or
+ other derived components computed based on the target URI, the HTTP message signature verification
+ will fail.
+
- This parameter is used as the value of the @target-uri derived component for HTTP message signatures
- [RFC 9421 HTTP Message Signatures, Section 2.2.2. Target URI](https://www.rfc-editor.org/rfc/rfc9421.html#section-2.2.2)).
- Additionally, other derived components such as `@authority`, `@scheme`, `@path`, `@query` and
- `@query-param` are computed from this parameter.
-
- When this parameter is omitted, the value of the `htu` parameter is used. The `htu` parameter
- represents the URL of the resource endpoint, which is identical to the target URI of the resource
- request as long as the request does not include a query component. Conversely, if the resource
- request includes a query component, the value of the `htu` parameter will not match the target
- URI, and in that case, the HTTP message signature verification will fail.
-
- If neither this `targetUri` parameter nor the `htu` parameter is specified, the target URI is
- considered unavailable. If HTTP message signing requires the target-uri derived component or
- other derived components computed based on the target URI, the HTTP message signature verification
- will fail.
dpopNonceRequired:
type: boolean
description: |
@@ -15232,15 +15576,21 @@ components:
type: string
description: |
The target resources this proeprty holds may be the same as or different from the ones `resource` property holds.
+ x-mint:
+ metadata:
+ description: "The target resources this proeprty holds may be the same as or different from the ones `resource` property holds."
+ content: |
+
+ In some flows, the initial request and the subsequent token request are sent to different endpoints.
+ Example flows are the Authorization Code Flow, the Refresh Token Flow, the CIBA Ping Mode, the CIBA Poll Mode and the Device Flow.
+ In these flows, not only the initial request but also the subsequent token request can include the `resource` request parameters.
+ The purpose of the `resource` request parameters in the token request is to narrow the range of the target resources from the original
+ set of target resources requested by the preceding initial request. If narrowing down is performed, the target resources holded by the
+ `resource` proeprty and the ones holded by this property are different. This property holds the narrowed set of target resources.
+
+ See "Resource Indicators for OAuth 2.0" for details.
+
- In some flows, the initial request and the subsequent token request are sent to different endpoints.
- Example flows are the Authorization Code Flow, the Refresh Token Flow, the CIBA Ping Mode, the CIBA Poll Mode and the Device Flow.
- In these flows, not only the initial request but also the subsequent token request can include the `resource` request parameters.
- The purpose of the `resource` request parameters in the token request is to narrow the range of the target resources from the original
- set of target resources requested by the preceding initial request. If narrowing down is performed, the target resources holded by the
- `resource` proeprty and the ones holded by this property are different. This property holds the narrowed set of target resources.
-
- See "Resource Indicators for OAuth 2.0" for details.
authorizationDetails:
$ref: '#/components/schemas/authz_details'
serviceAttributes:
@@ -15591,20 +15941,26 @@ components:
type: string
description: |
The target URI of the userinfo request, including the query part, if any.
+ x-mint:
+ metadata:
+ description: "The target URI of the userinfo request, including the query part, if any."
+ content: |
+
+ This parameter is used as the value of the `@target-uri` derived component for HTTP message signatures
+ ([RFC 9421 HTTP Message Signatures, Section 2.2.2. Target URI](https://www.rfc-editor.org/rfc/rfc9421.html#section-2.2.2)).
+ Additionally, other derived components such as `@authority`, `@scheme`, `@path`, `@query` and
+ `@query-param` are computed from this parameter.
+
+ When this parameter is omitted, the value of the `htu` parameter is used. The `htu` parameter
+ represents the URL of the userinfo endpoint, which usually serves as the target URI of the userinfo request.
+ The only exception is when the access token is specified as a query parameter, as defined in
+ [RFC 6750 Section 2.3](https://www.rfc-editor.org/rfc/rfc6750.html#section-2.3). However, RFC 6750
+ states that this method "SHOULD NOT be used" unless other methods are not viable.
+
+ If neither this `targetUri` parameter nor the `htu` parameter is specified, the `userInfoEndpoint`
+ property of the service is used as a fallback.
+
- This parameter is used as the value of the `@target-uri` derived component for HTTP message signatures
- ([RFC 9421 HTTP Message Signatures, Section 2.2.2. Target URI](https://www.rfc-editor.org/rfc/rfc9421.html#section-2.2.2)).
- Additionally, other derived components such as `@authority`, `@scheme`, `@path`, `@query` and
- `@query-param` are computed from this parameter.
-
- When this parameter is omitted, the value of the `htu` parameter is used. The `htu` parameter
- represents the URL of the userinfo endpoint, which usually serves as the target URI of the userinfo request.
- The only exception is when the access token is specified as a query parameter, as defined in
- [RFC 6750 Section 2.3](https://www.rfc-editor.org/rfc/rfc6750.html#section-2.3). However, RFC 6750
- states that this method "SHOULD NOT be used" unless other methods are not viable.
-
- If neither this `targetUri` parameter nor the `htu` parameter is specified, the `userInfoEndpoint`
- property of the service is used as a fallback.
dpopNonceRequired:
type: boolean
description: |
@@ -15618,17 +15974,23 @@ components:
type: boolean
description: |
The flag indicating whether the userinfo request contains a request body.
+ x-mint:
+ metadata:
+ description: "The flag indicating whether the userinfo request contains a request body."
+ content: |
+
+ When the userinfo request must comply with the HTTP message signing requirements defined in the
+ FAPI 2.0 Message Signing specification, the `"content-digest"` component identifier must be included
+ in the signature base of the HTTP message signature (see [RFC 9421 HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421.html))
+ if the userinfo request contains a request body.
+
+ When this `requestBodyContained` parameter is set to `true`, Authlete checks whether `"content-digest"`
+ is included in the signature base, if the FAPI profile applies to the userinfo request.
+
+ NOTE: The FAPI 2.0 Message Signing specification is not applied to the userinfo endpoint until
+ its necessity is agreed upon by the industry (cf. [FAPI Issue 723](https://bitbucket.org/openid/fapi/issues/723)).
+
- When the userinfo request must comply with the HTTP message signing requirements defined in the
- FAPI 2.0 Message Signing specification, the `"content-digest"` component identifier must be included
- in the signature base of the HTTP message signature (see [RFC 9421 HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421.html))
- if the userinfo request contains a request body.
-
- When this `requestBodyContained` parameter is set to `true`, Authlete checks whether `"content-digest"`
- is included in the signature base, if the FAPI profile applies to the userinfo request.
-
- NOTE: The FAPI 2.0 Message Signing specification is not applied to the userinfo endpoint until
- its necessity is agreed upon by the industry (cf. [FAPI Issue 723](https://bitbucket.org/openid/fapi/issues/723)).
userinfo_response:
type: object
properties:
@@ -15696,17 +16058,41 @@ components:
type: string
description: |
The value of the `userinfo` property in the `claims` request parameter or in the `claims` property in an authorization request object.
+ x-mint:
+ metadata:
+ description: "The value of the `userinfo` property in the `claims` request parameter or in the `claims` property in an authorization request object."
+ content: |
+
+ A client application may request certain claims be embedded in an ID token or in a response from the userInfo endpoint.
+ There are several ways. Including the `claims` request parameter and including the `claims` property in a request object are such examples.
+ In both cases, the value of the `claims` parameter/property is JSON. Its format is described in [5.5. Requesting Claims using the "claims"
+ Request Parameter](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter).
+
+ The following is an excerpt from the specification. You can find `userinfo` and `id_token` are top-level properties.
+
+ ```json
+ {
+ "userinfo":
+ {
+ "given_name": { "essential": true },
+ "nickname": null,
+ "email": { "essential": true },
+ "email_verified": { "essential": true },
+ "picture": null,
+ "http://example.info/claims/groups": null
+ },
+ "id_token":
+ {
+ "auth_time": { "essential": true },
+ "acr": { "values": [ "urn:mace:incommon:iap:silver" ] }
+ }
+ }
+ ````
- A client application may request certain claims be embedded in an ID token or in a response from the userInfo endpoint.
- There are several ways. Including the `claims` request parameter and including the `claims` property in a request object are such examples.
- In both cases, the value of the `claims` parameter/property is JSON. Its format is described in [5.5. Requesting Claims using the "claims"
- Request Parameter](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter).
-
- The following is an excerpt from the specification. You can find `userinfo` and `id_token` are top-level properties.
+ The value of this property is the value of the `userinfo` property in JSON format.
+ For example, if the JSON above is included in an authorization request, this property holds JSON equivalent to the following.
- ```json
- {
- "userinfo":
+ ```json
{
"given_name": { "essential": true },
"nickname": null,
@@ -15714,31 +16100,13 @@ components:
"email_verified": { "essential": true },
"picture": null,
"http://example.info/claims/groups": null
- },
- "id_token":
- {
- "auth_time": { "essential": true },
- "acr": { "values": [ "urn:mace:incommon:iap:silver" ] }
}
- }
- ````
+ ```
- The value of this property is the value of the `userinfo` property in JSON format.
- For example, if the JSON above is included in an authorization request, this property holds JSON equivalent to the following.
-
- ```json
- {
- "given_name": { "essential": true },
- "nickname": null,
- "email": { "essential": true },
- "email_verified": { "essential": true },
- "picture": null,
- "http://example.info/claims/groups": null
- }
- ```
+ Note that if a request object is given and it contains the `claims` property and if the `claims` request parameter is also given,
+ the value of this property holds the former value.
+
- Note that if a request object is given and it contains the `claims` property and if the `claims` request parameter is also given,
- the value of this property holds the former value.
serviceAttributes:
type: array
items:
@@ -15901,66 +16269,72 @@ components:
type: string
description: |
Values of verified claims requested indirectly by "transformed claims".
-
- A client application may request "transformed claims". Each of transformed claims uses an existing
- claim as input. As a result, to compute the value of a transformed claim, the value of the referenced
- existing claim is needed. This `verifiedClaimsForTx` request parameter has to be used to provide
- values of existing claims for computation of transformed claims.
-
- A response from the `/auth/userinfo` API may include the `requestedVerifiedClaimsForTx` response
- parameter which is a list of verified claims that are referenced indirectly by transformed claims
- (cf. `requestedVerifiedClaimsForTx` in `/auth/userinfo` API response). The authorization server
- implementation should prepare values of the verified claims listed in `requestedVerifiedClaimsForTx`
- and pass them as the value of this `verifiedClaimsForTx` request parameter.
-
- The following is an example of the value of this request parameter.
-
- ```
- [
- "{\"birthdate\":\"1970-01-23\",\"nationalities\":[\"DEU\",\"USA\"]}"
- ]
- ```
-
- The reason that this `verifiedClaimsForTx` property is an array is that the `"verified_claims"`
- property in the claims request parameter of an authorization request can be an array like below.
-
- ```
- {
- "transformed_claims": {
- "nationality_usa": {
- "claim": "nationalities",
- "fn": [
- [ "eq", "USA" ],
- "any"
+ x-mint:
+ metadata:
+ description: "Values of verified claims requested indirectly by \"transformed claims\"."
+ content: |
+
+ A client application may request "transformed claims". Each of transformed claims uses an existing
+ claim as input. As a result, to compute the value of a transformed claim, the value of the referenced
+ existing claim is needed. This `verifiedClaimsForTx` request parameter has to be used to provide
+ values of existing claims for computation of transformed claims.
+
+ A response from the `/auth/userinfo` API may include the `requestedVerifiedClaimsForTx` response
+ parameter which is a list of verified claims that are referenced indirectly by transformed claims
+ (cf. `requestedVerifiedClaimsForTx` in `/auth/userinfo` API response). The authorization server
+ implementation should prepare values of the verified claims listed in `requestedVerifiedClaimsForTx`
+ and pass them as the value of this `verifiedClaimsForTx` request parameter.
+
+ The following is an example of the value of this request parameter.
+
+ ```
+ [
+ "{\"birthdate\":\"1970-01-23\",\"nationalities\":[\"DEU\",\"USA\"]}"
+ ]
+ ```
+
+ The reason that this `verifiedClaimsForTx` property is an array is that the `"verified_claims"`
+ property in the claims request parameter of an authorization request can be an array like below.
+
+ ```
+ {
+ "transformed_claims": {
+ "nationality_usa": {
+ "claim": "nationalities",
+ "fn": [
+ [ "eq", "USA" ],
+ "any"
+ ]
+ }
+ },
+ "userinfo": {
+ "verified_claims": [
+ {
+ "verification": { "trust_framework": { "value": "gold" } },
+ "claims": { "::18_or_above": null }
+ },
+ {
+ "verification": { "trust_framework": { "value": "silver" } },
+ "claims": { ":nationality_usa": null }
+ }
]
}
- },
- "userinfo": {
- "verified_claims": [
- {
- "verification": { "trust_framework": { "value": "gold" } },
- "claims": { "::18_or_above": null }
- },
- {
- "verification": { "trust_framework": { "value": "silver" } },
- "claims": { ":nationality_usa": null }
- }
- ]
}
- }
- ```
+ ```
- For the example above, the value of this `verifiedClaimsForTx` property should be an array of
- size 2 and look like below. The first element is JSON including claims which have been verified
- under the trust framework `"gold"`, and the second element is JSON including claims which have
- been verified under the trust framework `"silver"`.
+ For the example above, the value of this `verifiedClaimsForTx` property should be an array of
+ size 2 and look like below. The first element is JSON including claims which have been verified
+ under the trust framework `"gold"`, and the second element is JSON including claims which have
+ been verified under the trust framework `"silver"`.
+
+ ```
+ [
+ "{\"birthdate\":\"1970-01-23\"}",
+ "{\"nationalities\":[\"DEU\",\"USA\"]}"
+ ]
+ ```
+
- ```
- [
- "{\"birthdate\":\"1970-01-23\"}",
- "{\"nationalities\":[\"DEU\",\"USA\"]}"
- ]
- ```
userinfo_issue_response:
type: object
properties:
@@ -16323,15 +16697,21 @@ components:
$ref: '#/components/schemas/scope'
description: |
The scopes requested by the backchannel authentication request.
+ x-mint:
+ metadata:
+ description: "The scopes requested by the backchannel authentication request."
+ content: |
+
+ Basically, this property holds the value of the `scope` request parameter in the backchannel
+ authentication request. However, because unregistered scopes are dropped on Authlete side,
+ if the `scope` request parameter contains unknown scopes, the list returned by this
+ property becomes different from the value of the `scope` request parameter.
+
+ Note that `description` property and `descriptions` property of each `scope` object
+ in the array contained in this property is always null even if descriptions of the scopes
+ are registered.
+
- Basically, this property holds the value of the `scope` request parameter in the backchannel
- authentication request. However, because unregistered scopes are dropped on Authlete side,
- if the `scope` request parameter contains unknown scopes, the list returned by this
- property becomes different from the value of the `scope` request parameter.
-
- Note that `description` property and `descriptions` property of each `scope` object
- in the array contained in this property is always null even if descriptions of the scopes
- are registered.
claimNames:
type: array
items:
@@ -16971,15 +17351,21 @@ components:
$ref: '#/components/schemas/scope'
description: |
The scopes requested by the device authorization request.
+ x-mint:
+ metadata:
+ description: "The scopes requested by the device authorization request."
+ content: |
+
+ Basically, this property holds the value of the scope request parameter in the device
+ authorization request. However, because unregistered scopes are dropped on Authlete
+ side, if the `scope` request parameter contains unknown scopes, the list returned by
+ this property becomes different from the value of the `scope` request parameter.
+
+ Note that `description` property and `descriptions` property of each scope object in the
+ array contained in this property is always `null` even if descriptions of the scopes
+ are registered.
+
- Basically, this property holds the value of the scope request parameter in the device
- authorization request. However, because unregistered scopes are dropped on Authlete
- side, if the `scope` request parameter contains unknown scopes, the list returned by
- this property becomes different from the value of the `scope` request parameter.
-
- Note that `description` property and `descriptions` property of each scope object in the
- array contained in this property is always `null` even if descriptions of the scopes
- are registered.
claimNames:
type: array
items:
@@ -17492,46 +17878,64 @@ components:
description: |
A boolean request parameter which indicates whether to emulate that the client ID alias is used
instead of the original numeric client ID when a new access token is created.
+ x-mint:
+ metadata:
+ description: "A boolean request parameter which indicates whether to emulate that the client ID alias is used instead of the original numeric client ID when a new access token is created."
+ content: |
+
+ This has an effect only on the value of the aud claim in a response from [UserInfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo).
+ When you access the UserInfo endpoint (which is expected to be implemented using Authlete's
+ `/api/auth/userinfo` API and `/api/auth/userinfo/issue` API) with an access token which has been
+ created using Authlete's `/api/auth/token/create` API with this property (`clientIdAliasUsed`)
+ `true`, the client ID alias is used as the value of the aud claim in a response from the UserInfo
+ endpoint.
+
+ Note that if a client ID alias is not assigned to the client when Authlete's `/api/auth/token/create`
+ API is called, this property (`clientIdAliasUsed`) has no effect (it is always regarded as `false`).
+
- This has an effect only on the value of the aud claim in a response from [UserInfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo).
- When you access the UserInfo endpoint (which is expected to be implemented using Authlete's
- `/api/auth/userinfo` API and `/api/auth/userinfo/issue` API) with an access token which has been
- created using Authlete's `/api/auth/token/create` API with this property (`clientIdAliasUsed`)
- `true`, the client ID alias is used as the value of the aud claim in a response from the UserInfo
- endpoint.
-
- Note that if a client ID alias is not assigned to the client when Authlete's `/api/auth/token/create`
- API is called, this property (`clientIdAliasUsed`) has no effect (it is always regarded as `false`).
accessToken:
type: string
description: |
The value of the new access token.
+ x-mint:
+ metadata:
+ description: "The value of the new access token."
+ content: |
+
+ The `/api/auth/token/create` API generates an access token. Therefore, callers of the API do not
+ have to specify values of newly created access tokens. However, in some cases, for example, if
+ you want to migrate existing access tokens from an old system to Authlete, you may want to specify
+ values of access tokens. In such a case, you can specify the value of a newly created access token
+ by passing a non-null value as the value of accessToken request parameter. The implementation
+ of the `/api/auth/token/create` uses the value of the accessToken request parameter instead of
+ generating a new value when the request parameter holds a non-null value.
+
+ Note that if the hash value of the specified access token already exists in Authlete's database,
+ the access token cannot be inserted and the `/api/auth/token/create` API will report an error.
+
- The `/api/auth/token/create` API generates an access token. Therefore, callers of the API do not
- have to specify values of newly created access tokens. However, in some cases, for example, if
- you want to migrate existing access tokens from an old system to Authlete, you may want to specify
- values of access tokens. In such a case, you can specify the value of a newly created access token
- by passing a non-null value as the value of accessToken request parameter. The implementation
- of the `/api/auth/token/create` uses the value of the accessToken request parameter instead of
- generating a new value when the request parameter holds a non-null value.
-
- Note that if the hash value of the specified access token already exists in Authlete's database,
- the access token cannot be inserted and the `/api/auth/token/create` API will report an error.
refreshToken:
type: string
description: |
The value of the new refresh token.
+ x-mint:
+ metadata:
+ description: "The value of the new refresh token."
+ content: |
+
+ The `/api/auth/token/create` API may generate a refresh token. Therefore, callers of the API do
+ not have to specify values of newly created refresh tokens. However, in some cases, for example,
+ if you want to migrate existing refresh tokens from an old system to Authlete, you may want to
+ specify values of refresh tokens. In such a case, you can specify the value of a newly created
+ refresh token by passing a non-null value as the value of refreshToken request parameter. The
+ implementation of the `/api/auth/token/create` uses the value of the refreshToken request parameter
+ instead of generating a new value when the request parameter holds a non-null value.
+
+ Note that if the hash value of the specified refresh token already exists in Authlete's database,
+ the refresh token cannot be inserted and the `/api/auth/token/create` API will report an error.
+
- The `/api/auth/token/create` API may generate a refresh token. Therefore, callers of the API do
- not have to specify values of newly created refresh tokens. However, in some cases, for example,
- if you want to migrate existing refresh tokens from an old system to Authlete, you may want to
- specify values of refresh tokens. In such a case, you can specify the value of a newly created
- refresh token by passing a non-null value as the value of refreshToken request parameter. The
- implementation of the `/api/auth/token/create` uses the value of the refreshToken request parameter
- instead of generating a new value when the request parameter holds a non-null value.
-
- Note that if the hash value of the specified refresh token already exists in Authlete's database,
- the refresh token cannot be inserted and the `/api/auth/token/create` API will report an error.
accessTokenPersistent:
type: boolean
description: |
@@ -17701,70 +18105,6 @@ components:
NOTE: A refresh token must be associated with a session ID, which is the ID of the user's authentication
session, in order to be used to obtain a [Native SSO](https://openid.net/specs/openid-connect-native-sso-1_0.html)-compliant
ID token in the refresh token flow.
- token_create_batch_response:
- type: object
- description: |
- Response from a token create batch request.
- properties:
- resultCode:
- type: string
- description: The result code of the request.
- resultMessage:
- type: string
- description: The result message of the request.
- requestId:
- type: string
- description: The ID of the issued token batch request.
- token_batch_status:
- type: object
- description: |
- Status of a token batch operation.
- properties:
- batchKind:
- type: string
- enum:
- - CREATE
- description: The kind of batch operation.
- requestId:
- type: string
- description: The request ID.
- result:
- type: string
- enum:
- - SUCCEEDED
- - FAILED
- description: The result of the batch operation.
- errorCode:
- type: string
- description: The error code if the operation failed.
- errorDescription:
- type: string
- description: The error description if the operation failed.
- tokenCount:
- type: integer
- format: int64
- description: The number of tokens processed.
- createdAt:
- type: integer
- format: int64
- description: The time at which the batch operation was created (timestamp).
- modifiedAt:
- type: integer
- format: int64
- description: The time at which the batch operation was last modified (timestamp).
- token_create_batch_status_response:
- type: object
- description: |
- Response from a token create batch status request.
- properties:
- resultCode:
- type: string
- description: The result code of the request.
- resultMessage:
- type: string
- description: The result message of the request.
- status:
- $ref: '#/components/schemas/token_batch_status'
token_update_request:
type: object
properties:
@@ -18433,87 +18773,111 @@ components:
type: string
description: |
The value of the `credential_configuration_ids` array.
+ x-mint:
+ metadata:
+ description: "The value of the `credential_configuration_ids` array."
+ content: |
+
+ ```
+ {
+ "credential_issuer": "...",
+ "credential_configuration_ids": [ ... ],
+ "grants": { ... }
+ }
+ ```
- ```
- {
- "credential_issuer": "...",
- "credential_configuration_ids": [ ... ],
- "grants": { ... }
- }
- ```
+ This property is mandatory.
+
- This property is mandatory.
txCode:
type: string
description: |
The transaction code that should be associated with the credential offer.
-
- If this parameter is not empty and the `preAuthorizedCodeGrantIncluded` parameter is `true`, the
- `urn:ietf:params:oauth:grant-type:pre-authorized_code` object will include the `tx_code` object.
-
- The length of the value of this parameter will be used as the value of the `length` property in
- the `tx_code` object.
-
- ```
- {
- "credential_issuer": "...",
- "credential_configuration_ids": [ ... ],
- "grants": {
- "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
- "pre-authorized_code": "...",
- "tx_code": {
- "length": length
+ x-mint:
+ metadata:
+ description: "The transaction code that should be associated with the credential offer."
+ content: |
+
+ If this parameter is not empty and the `preAuthorizedCodeGrantIncluded` parameter is `true`, the
+ `urn:ietf:params:oauth:grant-type:pre-authorized_code` object will include the `tx_code` object.
+
+ The length of the value of this parameter will be used as the value of the `length` property in
+ the `tx_code` object.
+
+ ```
+ {
+ "credential_issuer": "...",
+ "credential_configuration_ids": [ ... ],
+ "grants": {
+ "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
+ "pre-authorized_code": "...",
+ "tx_code": {
+ "length": length
+ }
}
}
}
- }
- ```
+ ```
+
+
txCodeInputMode:
type: string
description: |
The input mode of the transaction code.
-
- The value of this property will be used as the value of the `input_mode` property in the `tx_code`
- object.
-
- ```
- {
- "credential_issuer": "...",
- "credential_configuration_ids": [ ... ],
- "grants": {
- "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
- "pre-authorized_code": "...",
- "tx_code": {
- "length": length,
- "input_mode": "..."
+ x-mint:
+ metadata:
+ description: "The input mode of the transaction code."
+ content: |
+
+ The value of this property will be used as the value of the `input_mode` property in the `tx_code`
+ object.
+
+ ```
+ {
+ "credential_issuer": "...",
+ "credential_configuration_ids": [ ... ],
+ "grants": {
+ "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
+ "pre-authorized_code": "...",
+ "tx_code": {
+ "length": length,
+ "input_mode": "..."
+ }
}
}
}
- }
- ```
+ ```
+
+
txCodeDescription:
type: string
description: |
The description of the transaction code.
-
- The value of this property will be used as the value of the `description` property in the `tx_code`
- object.
-
- ```
- {
- "credential_issuer": "...",
- "credential_configuration_ids": [ ... ],
- "grants": {
- "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
- "pre-authorized_code": "...",
- "tx_code": {
- "length": length,
- "description": "..."
+ x-mint:
+ metadata:
+ description: "The description of the transaction code."
+ content: |
+
+ The value of this property will be used as the value of the `description` property in the `tx_code`
+ object.
+
+ ```
+ {
+ "credential_issuer": "...",
+ "credential_configuration_ids": [ ... ],
+ "grants": {
+ "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
+ "pre-authorized_code": "...",
+ "tx_code": {
+ "length": length,
+ "description": "..."
+ }
}
}
}
- }
- ```
+ ```
+
+
vci_offer_create_response:
type: object
properties:
@@ -18862,28 +19226,40 @@ components:
description: |
The type of the `aud` claim of the ID token being issued. Valid values of this parameter are
as follows:
+ x-mint:
+ metadata:
+ description: "The type of the `aud` claim of the ID token being issued. Valid values of this parameter are as follows:"
+ content: |
+
+ - `"array"`
+ The type of the `aud` claim becomes an array of strings.
- - `"array"`
- The type of the `aud` claim becomes an array of strings.
+ - `"string"`
+ The type of the `aud` claim becomes a single string.
- - `"string"`
- The type of the `aud` claim becomes a single string.
+ This parameter is optional, and the default value when omitted is `"array"`. This parameter takes
+ precedence over the `idTokenAudType` property of `Service`.
+
- This parameter is optional, and the default value when omitted is `"array"`. This parameter takes
- precedence over the `idTokenAudType` property of `Service`.
deviceSecret:
type: string
description: |
The device secret. The value of this parameter should be the value of the `deviceSecret` parameter
in the response from the `/auth/token` API, if the parameter is present. Otherwise, the authorization
server should generate a new device secret and specify it as the value of this parameter.
+ x-mint:
+ metadata:
+ description: "The device secret. The value of this parameter should be the value of the `deviceSecret` parameter in the response from the `/auth/token` API, if the parameter is present. Otherwise, the authorization server should generate a new device secret and specify it as the value of this parameter."
+ content: |
+
+ The specified device secret is included as the value of the `device_secret` property in the token
+ response prepared by the `/nativesso` API.
+
+ Additionally, if the `deviceSecretHash` request parameter is omitted, the device secret is used
+ to compute the value of the `ds_hash` claim. In this case, the `ds_hash` claim will be the
+ base64url-encoded SHA-256 hash of the device secret.
+
- The specified device secret is included as the value of the `device_secret` property in the token
- response prepared by the `/nativesso` API.
-
- Additionally, if the `deviceSecretHash` request parameter is omitted, the device secret is used
- to compute the value of the `ds_hash` claim. In this case, the `ds_hash` claim will be the
- base64url-encoded SHA-256 hash of the device secret.
deviceSecretHash:
type: string
description: |