Issue Authorization Response - Authlete Documentation

Full 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
&#123;responseContent&#125;

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
&#123;responseContent&#125;

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: &#123;responseContent&#125;
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
&#123;responseContent&#125;

Authorizations

Authorization

string

header

required

Authenticate every request with a Service Access Token or Organization Token. Set the token value in the Authorization: Bearer <token> header.

Service Access Token: Scoped to a single service. Use when automating service-level configuration or runtime flows.

Organization Token: Scoped to the organization; inherits permissions across services. Use for org-wide automation or when managing multiple services programmatically.

Both token types are issued by the Authlete console or provisioning APIs.

Path Parameters

serviceId

string

required

A service ID.

Body

ticket

string

required

The ticket issued from Authlete /auth/authorization API.

subject

string

required

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

authTime

integer<int64>

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

acr

string

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

claims

string

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.

properties

object[]

Extra properties to associate with an access token and/or an authorization code.

Show child attributes

scopes

string[]

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.

sub

string

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.

idtHeaderParams

string

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

claimsForTx

string

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

consentedClaims

string[]

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

authorizationDetails

object

The authorization details. This represents the value of the authorization_details request parameter in the preceding device authorization request which is defined in "OAuth 2.0 Rich Authorization Requests".

Show child attributes

jwtAtClaims

string

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

accessToken

string

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

accessTokenDuration

integer<int64>

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.

sessionId

string

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.

idTokenAudType

string

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

Value	Description
"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.
null	The type of the aud claim remains the same as before.

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

verifiedClaimsForTx

string[]

Values of verified claims requested indirectly by "transformed claims".

Response

resultCode

string

The code which represents the result of the API call.

resultMessage

string

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

action

enum<string>

The next action that the authorization server implementation should take.

Available options:

INTERNAL_SERVER_ERROR,

BAD_REQUEST,

LOCATION,

FORM

responseContent

string

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

accessToken

string

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

accessTokenExpiresAt

integer<int64>

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

accessTokenDuration

integer<int64>

The duration of the newly issued access token in seconds.

idToken

string

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

authorizationCode

string

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

jwtAccessToken

string

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.

ticketInfo

object

The information about the ticket.

Show child attributes

Authlete

​INTERNAL_SERVER_ERROR

​BAD_REQUEST

​LOCATION

​FORM

Authorizations

Path Parameters

Body

Response

INTERNAL_SERVER_ERROR

BAD_REQUEST

LOCATION

FORM