Documentation

BackchannelAuthenticationCompleteRequest implements ArrayCopyable, Arrayable, Jsonable Uses ArrayTrait, JsonTrait

Request to Authlete's /api/backchannel/authentication/complete API.

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

Tags
since
1.8

Interfaces, Classes and Traits

ArrayCopyable
Interface to declare instances can be converted into/from arrays.
Arrayable
Interface to declare that instances can be converted into an array.
Jsonable
Interface to declare that instances can be converted into JSON strings.

Table of Contents

copyFromArray()  : mixed
Copy the content of the given array into this object.
copyToArray()  : mixed
Copy the content of this object into the given array.
fromArray()  : static
Convert an array into an instance of this class.
fromJson()  : static
Convert a JSON string into an instance of this class.
getAcr()  : string
Get the reference of the authentication context class which the end-user authentication satisfied. When this property holds a non-null value, the value will be used as the value of the `acr` claim in the ID token.
getAuthTime()  : int|string
Get the time when the authentication of the end-user occurred.
getClaims()  : string
Get additional claims which will be embedded in the ID token.
getErrorDescription()  : string
Get the description of the error. This corresponds to the `error_description` property in the response to the client.
getErrorUri()  : string
Get the URI of a document which describes the error in detail. This corresponds to the `error_uri` property in the response to the client.
getIdtHeaderParams()  : string
Get JSON that represents additional JWS header parameters for the ID token that may be issued from the token endpoint.
getProperties()  : array<string|int, Property>
Get the extra properties associated with the access token that will be issued.
getResult()  : BackchannelAuthenticationCompleteResult
Get the result of end-user authentication and authorization.
getScopes()  : array<string|int, string>
Get scopes associated with the access token. If this property holds a non-null value, the set of scopes will be used instead of the scopes specified in the original backchannel authentication request.
getSub()  : string
Get the value of the `sub` claim that should be used in the ID token.
getSubject()  : string
Get the subject (= unique identifier) of the end-user who has granted authorization to the client application. This request parameter is mandatory when the `result` property holds `BackchannelAuthenticationCompleteResult::$AUTHORIZED`.
getTicket()  : string
Get the ticket which is necessary to call Authlete's `/api/backchannel/authentication/complete` API.
setAcr()  : BackchannelAuthenticationCompleteRequest
Set the reference of the authentication context class which the end-user authentication satisfied. When this property holds a non-null value, the value will be used as the value of the `acr` claim in the ID token.
setAuthTime()  : BackchannelAuthenticationCompleteRequest
Set the time when the authentication of the end-user occurred.
setClaims()  : BackchannelAuthenticationCompleteRequest
Set additional claims which will be embedded in the ID token.
setErrorDescription()  : BackchannelAuthenticationCompleteRequest
Set the description of the error. This corresponds to the `error_description` property in the response to the client.
setErrorUri()  : BackchannelAuthenticationCompleteRequest
Set the URI of a document which describes the error in detail. This corresponds to the `error_uri` property in the response to the client.
setIdtHeaderParams()  : BackchannelAuthenticationCompleteRequest
Set JSON that represents additional JWS header parameters for the ID token that may be issued from the token endpoint.
setProperties()  : BackchannelAuthenticationCompleteRequest
Set the extra properties associated with the access token that will be issued.
setResult()  : BackchannelAuthenticationCompleteRequest
Set the result of end-user authentication and authorization.
setScopes()  : BackchannelAuthenticationCompleteRequest
Set scopes associated with the access token. If this property holds a non-null value, the set of scopes will be used instead of the scopes specified in the original backchannel authentication request.
setSub()  : BackchannelAuthenticationCompleteRequest
Set the value of the `sub` claim that should be used in the ID token.
setSubject()  : BackchannelAuthenticationCompleteRequest
Set the subject (= unique identifier) of the end-user who has granted authorization to the client application. This request parameter is mandatory when the `result` property holds `BackchannelAuthenticationCompleteResult::$AUTHORIZED`.
setTicket()  : BackchannelAuthenticationCompleteRequest
Set the ticket which is necessary to call Authlete's `/api/backchannel/authentication/complete` API.
toArray()  : array<string|int, mixed>
Convert this object into an array.
toJson()  : string
Convert this object into a JSON string.

Methods

copyFromArray()

Copy the content of the given array into this object.

public copyFromArray(array<string|int, mixed> &$array) : mixed
Parameters
$array : array<string|int, mixed>
Return values
mixed —

copyToArray()

Copy the content of this object into the given array.

public copyToArray(array<string|int, mixed> &$array) : mixed
Parameters
$array : array<string|int, mixed>
Return values
mixed —

fromArray()

Convert an array into an instance of this class.

public static fromArray([array<string|int, mixed> $array = null ]) : static

This static function returns a new instance of this class. If $array is null, null is returned.

Parameters
$array : array<string|int, mixed> = null

An array

Return values
static —

An instance of this class.

fromJson()

Convert a JSON string into an instance of this class.

public static fromJson(string $json) : static

This static function returns a new instance of this class. If $json is null or the type of $json is not string, null is returned.

Parameters
$json : string

A JSON string.

Return values
static —

An instance of this class.

getAcr()

Get the reference of the authentication context class which the end-user authentication satisfied. When this property holds a non-null value, the value will be used as the value of the `acr` claim in the ID token.

public getAcr() : string
Return values
string —

The authentication context class reference.

getAuthTime()

Get the time when the authentication of the end-user occurred.

public getAuthTime() : int|string

The value represents the elapsed time since the Unix epoch (1970-Jan-1) in seconds.

Return values
int|string —

The time when the authentication of the end-user occurred.

getClaims()

Get additional claims which will be embedded in the ID token.

public getClaims() : string
Return values
string —

Additional claims in JSON format which will be embedded in the ID token.

getErrorDescription()

Get the description of the error. This corresponds to the `error_description` property in the response to the client.

public getErrorDescription() : string
Return values
string —

The description of the error.

getErrorUri()

Get the URI of a document which describes the error in detail. This corresponds to the `error_uri` property in the response to the client.

public getErrorUri() : string
Return values
string —

The URI of a document which describes the error in detail.

getIdtHeaderParams()

Get JSON that represents additional JWS header parameters for the ID token that may be issued from the token endpoint.

public getIdtHeaderParams() : string
Tags
since
1.9
Return values
string —

JSON that represents additional JWS header parameters for the ID token.

getScopes()

Get scopes associated with the access token. If this property holds a non-null value, the set of scopes will be used instead of the scopes specified in the original backchannel authentication request.

public getScopes() : array<string|int, string>
Return values
array<string|int, string> —

Scopes to replace the scopes specified in the original backchannel authentication request with. If this property holds null, replacement is not performed.

getSub()

Get the value of the `sub` claim that should be used in the ID token.

public getSub() : string

If this property holds null or its value is empty, the value held by the subject property is used as the value of the sub claim. The main purpose of this sub property is to hide the actual value of the subject from client applications.

Note that the value of the subject request parameter is used as the value of the subject associated with the access token regardless of whether this sub property is a non-empty value or not. In other words, this sub property affects only the sub claim in the ID token.

Return values
string —

The value of the sub claim.

getSubject()

Get the subject (= unique identifier) of the end-user who has granted authorization to the client application. This request parameter is mandatory when the `result` property holds `BackchannelAuthenticationCompleteResult::$AUTHORIZED`.

public getSubject() : string

This subject property is used as the value of the subject associated with the access token and as the value of the sub claim in the ID token.

Note that, if the sub property holds a non-null value, it is used as the value of the sub claim in the ID token. However, even in the case, the value of the subject associated with the access token is still the value of this subject property.

Return values
string —

The subject of the end-user.

getTicket()

Get the ticket which is necessary to call Authlete's `/api/backchannel/authentication/complete` API.

public getTicket() : string

This request parameter is mandatory.

Return values
string —

The ticket previously issued from Authlete's /api/backchannel/authentication API.

setClaims()

Set additional claims which will be embedded in the ID token.

public setClaims(string $claims) : BackchannelAuthenticationCompleteRequest

The authorization server implementation is required to retrieve values of requested claims of the end-user from its database and format them in JSON format.

For example, if given_name claim, family_name claim and email claim are requested, the authorization server implementation should generate a JSON object like the following:

{
  "given_name": "Takahiko",
  "family_name": "Kawasaki",
  "email": "takahiko.kawasaki@example.com"
}

and set its string representation by this method.

See 5.1. Standard Claims in OpenID Connect Core 1.0 for details about the format.

Parameters
$claims : string

Additional claims in JSON format which will be embedded in the ID token.

Return values
BackchannelAuthenticationCompleteRequest —

$this object.

setErrorDescription()

Set the description of the error. This corresponds to the `error_description` property in the response to the client.

public setErrorDescription(string $description) : BackchannelAuthenticationCompleteRequest

If this optional request parameter is given, its value is used as the value of the error_description property, but it is used only when the result is not AUTHORIZED.

To comply with the specification strictly, the description must not include characters outside the set %x20-21 / %x23-5B / %x5D-7E.

Parameters
$description : string

The description of the error.

Return values
BackchannelAuthenticationCompleteRequest —

$this object.

setErrorUri()

Set the URI of a document which describes the error in detail. This corresponds to the `error_uri` property in the response to the client.

public setErrorUri(string $uri) : BackchannelAuthenticationCompleteRequest

If this optional request parameter is given, its value is used as the value of the error_uri property, but it is used only when the result is not AUTHORIZED.

Parameters
$uri : string

The URI of a document which describes the error in detail.

Return values
BackchannelAuthenticationCompleteRequest —

$this object.

setProperties()

Set the extra properties associated with the access token that will be issued.

public setProperties([array<string|int, mixed> $properties = null ]) : BackchannelAuthenticationCompleteRequest

Keys of extra properties will be used as labels of top-level entries in a JSON response returned from the authorization server. An example is example_parameter, which you can find in 5.1. Successful Response in RFC 6749. The following code snippet is an example to set one extra property having example_parameter as its key and example_value as its value.

$properties = array(
    new Property('example_parameter', 'example_value')
);

$request->setProperties($properties);

Note that there is an upper limit on the total size of extra properties. On Authlete side, the properties will be (1) converted to a multidimensional string array, (2) converted to JSON, (3) encrypted by AES/CBC/PKCS5Padding, (4) encoded by base64url, and then stored into the database. The length of the resultant string must not exceed 65,535 in bytes. This is the upper limit, but we think it is big enough.

Parameters
$properties : array<string|int, mixed> = null

Extra properties.

Return values
BackchannelAuthenticationCompleteRequest —

$this object.

setScopes()

Set scopes associated with the access token. If this property holds a non-null value, the set of scopes will be used instead of the scopes specified in the original backchannel authentication request.

public setScopes([array<string|int, mixed> $scopes = null ]) : BackchannelAuthenticationCompleteRequest

Scopes that are not included in the original request can be included.

Note that because the CIBA specification requires openid as a mandatory scope, openid should be always included.

Parameters
$scopes : array<string|int, mixed> = null

Scopes to replace the scopes specified in the original backchannel authentication request with. If this property holds null, replacement is not performed.

Return values
BackchannelAuthenticationCompleteRequest —

$this object.

setSub()

Set the value of the `sub` claim that should be used in the ID token.

public setSub(string $sub) : BackchannelAuthenticationCompleteRequest

If this property holds null or its value is empty, the value held by the subject property is used as the value of the sub claim. The main purpose of this sub property is to hide the actual value of the subject from client applications.

Note that the value of the subject request parameter is used as the value of the subject associated with the access token regardless of whether this sub property is a non-empty value or not. In other words, this sub property affects only the sub claim in the ID token.

Parameters
$sub : string

The value of the sub claim.

Return values
BackchannelAuthenticationCompleteRequest —

$this object.

setSubject()

Set the subject (= unique identifier) of the end-user who has granted authorization to the client application. This request parameter is mandatory when the `result` property holds `BackchannelAuthenticationCompleteResult::$AUTHORIZED`.

public setSubject(string $subject) : BackchannelAuthenticationCompleteRequest

This subject property is used as the value of the subject associated with the access token and as the value of the sub claim in the ID token.

Note that, if the sub property holds a non-null value, it is used as the value of the sub claim in the ID token. However, even in the case, the value of the subject associated with the access token is still the value of this subject property.

Parameters
$subject : string

The subject of the end-user.

Return values
BackchannelAuthenticationCompleteRequest —

$this object.

toArray()

Convert this object into an array.

public toArray() : array<string|int, mixed>
Return values
array<string|int, mixed> —

An array.

toJson()

Convert this object into a JSON string.

public toJson(int $options) : string
Parameters
$options : int

Options passed to json_encode(). This parameter is optional and its default value is 0.

Return values
string —

A JSON string.

Search results