Sign in
Authorization Endpoint

Issue Authorization Response

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

Description

This API is supposed to be called from within the implementation of the authorization endpoint of the service in order to generate a successful response to the client application. The description of the /auth/authorization API describes the timing when this API should be called and the meaning of request parameters. See [ISSUE] in NO\_INTERACTION. 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}
post/api/{serviceId}/auth/authorization/issue

Path parameters

serviceIdstring required

A service ID.

Request body

ticketstring required

The ticket issued from Authlete /auth/authorization API.

subjectstring required

The subject (= a user account managed by the service) who has granted authorization to the client application.

authTimeinteger

The time when the authentication of the end-user occurred. Its value is the number of seconds from 1970-01-01.

acrstring

The Authentication Context Class Reference performed for the end-user authentication.

claimsstring

The claims of the end-user (= pieces of information about the end-user) in JSON format. See OpenID Connect Core 1.0, 5.1. Standard Claims for details about the format.

scopesstring[]

Scopes to associate with an access token and/or an authorization code. If a non-empty string array is given, it replaces the scopes specified by the original authorization request.

substring

The value of the sub claim to embed in an ID token. If this request parameter is null or empty, the value of the subject request parameter is used as the value of the sub claim.

idtHeaderParamsstring

JSON that represents additional JWS header parameters for ID tokens that may be issued based on the authorization request.

claimsForTxstring

Claim key-value pairs that are used to compute transformed claims.

consentedClaimsstring[]

the claims that the user has consented for the client application to know.

jwtAtClaimsstring

Additional claims that are added to the payload part of the JWT access token.

accessTokenstring

The representation of an access token that may be issued as a result of the Authlete API call.

accessTokenDurationinteger

The duration (in seconds) of the access token that may be issued as a result of the Authlete API call.

When this request parameter holds a positive integer, it is used as the duration of the access token in. In other cases, this request parameter is ignored.

sessionIdstring

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

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.

idTokenAudTypestring

The type of the aud claim of the ID token being issued. Valid values are as follows.

ValueDescription
"array"The type of the aud claim is always an array of strings.
"string"The type of the aud claim is always a single string.
nullThe type of the aud claim remains the same as before.

This request parameter takes precedence over the idTokenAudType property of the service.

verifiedClaimsForTxstring[]

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"
      ]
    }
  },
  "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".

[
  "{\"birthdate\":\"1970-01-23\"}",
  "{\"nationalities\":[\"DEU\",\"USA\"]}"
]

Response

resultCodestring

The code which represents the result of the API call.

resultMessagestring

A short message which explains the result of the API call.

action'INTERNAL_SERVER_ERROR' | 'BAD_REQUEST' | 'LOCATION' | 'FORM'

The next action that the authorization server implementation should take.

responseContentstring

The content that the authorization server implementation is to return to the client application. Its format varies depending on the value of action parameter.

accessTokenstring

The newly issued access token. Note that an access token is issued from an authorization endpoint only when response_type contains token.

accessTokenExpiresAtinteger

The datetime at which the newly issued access token will expire. The value is represented in milliseconds since the Unix epoch (1970-01-01).

accessTokenDurationinteger

The duration of the newly issued access token in seconds.

idTokenstring

The newly issued ID token. Note that an ID token is issued from an authorization endpoint only when response_type contains id_token.

authorizationCodestring

The newly issued authorization code. Note that an authorization code is issued only when response_type contains code.

jwtAccessTokenstring

The newly issued access token in JWT format. If the service is not configured to issue JWT-based access tokens, this property is always set to null.

Changes