Documentation

AuthorizationIssueRequest implements ArrayCopyable, Arrayable, Jsonable Uses ArrayTrait, JsonTrait

Request to Authlete's /api/auth/authorization/issue API.

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 Authentication Context Class Reference performed for the end-user authentication.
getAuthTime()  : int|string
Get the time when the authentication of the end-user occurred.
getClaims()  : string
Get the claims of the end-user (= pieces of information about the end-user) in JSON format.
getIdtHeaderParams()  : string
Get JSON that represents additional JWS header parameters for ID tokens that may be issued based on the authorization request.
getProperties()  : array<string|int, Property>
Get the properties which are associated with an access token and/or an authorization code which will be issued.
getScopes()  : array<string|int, string>
Get scopes that should be associated with an authorization code and/or an access token.
getSub()  : string
Get the value of the "sub" claim used in the ID token which is to be issued.
getSubject()  : string
Get the subject (= unique identifier) of the end-user who has granted authorization to the client application.
getTicket()  : string
Get the ticket issued by Authlete's /api/auth/authorization API.
setAcr()  : AuthorizationIssueRequest
Set the Authentication Context Class Reference performed for the end-user authentication.
setAuthTime()  : AuthorizationIssueRequest
Get the time when the authentication of the end-user occurred.
setClaims()  : AuthorizationIssueRequest
Set the claims of the end-user (= pieces of information about the end-user) in JSON format. This request parameter is optional.
setIdtHeaderParams()  : AuthorizationIssueRequest
Set JSON that represents additional JWS header parameters for ID tokens that may be issued based on the authorization request.
setProperties()  : AuthorizationIssueRequest
Set the properties which are associated with an access token and/or an authorization code which will be issued. This request parameter is optional.
setScopes()  : AuthorizationIssueRequest
Set scopes that should be associated with an authorization code and/or an access token.
setSub()  : AuthorizationIssueRequest
Get the value of the "sub" claim used in the ID token which is to be issued. This request parameter is optional.
setSubject()  : AuthorizationIssueRequest
Set the subject (= unique identifier) of the end-user who has granted authorization to the client application.
setTicket()  : AuthorizationIssueRequest
Set the ticket issued by Authlete's /api/auth/authorization 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 Authentication Context Class Reference performed for the end-user authentication.

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 the claims of the end-user (= pieces of information about the end-user) in JSON format.

public getClaims() : string
Return values
string —

The claims of the end-user in JSON format.

getIdtHeaderParams()

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

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

JSON that represents additional JWS header parameters for ID tokens.

getProperties()

Get the properties which are associated with an access token and/or an authorization code which will be issued.

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

Extra properties.

getScopes()

Get scopes that should be associated with an authorization code and/or an access token.

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

A string array that represents scope names.

getSub()

Get the value of the "sub" claim used in the ID token which is to be issued.

public getSub() : string
Return values
string —

The value of the sub claim used in the ID token.

getSubject()

Get the subject (= unique identifier) of the end-user who has granted authorization to the client application.

public getSubject() : string
Return values
string —

The unique identifier of an end-user.

getTicket()

Get the ticket issued by Authlete's /api/auth/authorization API.

public getTicket() : string
Return values
string —

The ticket issued by Authlete's /api/auth/authorization API.

setAuthTime()

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

public setAuthTime(int|string $authTime) : AuthorizationIssueRequest

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

Parameters
$authTime : int|string

The time when the authentication of the end-user occurred. The value should represent the elapsed time since the Unix epoch (1970-Jan-1) in seconds.

Return values
AuthorizationIssueRequest —

$this object.

setClaims()

Set the claims of the end-user (= pieces of information about the end-user) in JSON format. This request parameter is optional.

public setClaims(string $claims) : AuthorizationIssueRequest

The authorization server implementation is required to retrieve claims of the subject (= information about 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 required, the authorization server implementation should generate a JSON object like the following and pass its string representation to this method.

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

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

Parameters
$claims : string

The claims of the end-user in JSON format.

Return values
AuthorizationIssueRequest —

$this object.

setIdtHeaderParams()

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

public setIdtHeaderParams(string $params) : AuthorizationIssueRequest
Parameters
$params : string

JSON that represents additional JWS header parameters for ID tokens.

Tags
since
1.8
Return values
AuthorizationIssueRequest —

$this object.

setProperties()

Set the properties which are associated with an access token and/or an authorization code which will be issued. This request parameter is optional.

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

Properties will be returned to the client application together with an access token unless they are marked as hidden. For example, if you set one property as follows:

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

$request->setProperties($properties);

The property will be contained in the final response from the authorization server as follows:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"example",
  "expires_in":3600,
  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
  "example_parameter":"example_value"
}

The above example is an excerpted from 5.1. Successful Response in RFC 6749.

Keys listed below should not be used and they would be ignored on Authlete side even if they were used. It's because they are reserved in RFC 6749 and OpenID Connect Core 1.0.

  • access_token
  • token_type
  • expires_in
  • refresh_token
  • scope
  • error
  • error_description
  • error_uri
  • id_token

Note that there is an upper limit on the total size of 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.

You can know properties associated with an access token by calling Authlete's /api/auth/introspection API.

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

An array of \Authlete\Dto\Property.

Return values
AuthorizationIssueRequest —

$this object.

setScopes()

Set scopes that should be associated with an authorization code and/or an access token.

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

If null (the default value) is set, the scopes specified in the original authorization request from the client application are used. In other cases, the scopes set by this method will replace the original scopes contained in the original request. This request parameter is optional.

Even scopes that are not included in the original authorization request can be specified. However, as an exception, openid scope is ignored on Authlete side if it is not included in the original request (to be exact, if openid was not included in the parameters request parameter of the request to /api/auth/authorization API). It is because the existence of the 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 the offline_access scope although it is not included in the original request, keep in mind that the specification requires explicit consent from the end-user for the scope (11. Offline Access of OpenID Connect Core 1.0). When offline_access is included in the original authorization request, the current implementation of Authlete's /api/auth/authorization API checks whether the authorization request has come along with the prompt request parameter and its value includes consent. However, note that the implementation of Authlete's /api/auth/authorization/issue API does not perform the same validation even if the offline_access scope is newly added via this method.

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

A string array that represents scope names.

Return values
AuthorizationIssueRequest —

$this object.

setSub()

Get the value of the "sub" claim used in the ID token which is to be issued. This request parameter is optional.

public setSub(string $sub) : AuthorizationIssueRequest

If a non-empty value is set, it is used as the value of the sub claim. Otherwise, the value returned from getSubject() method is used. The main purpose of this setSub() method is to hide the actual value of the subject from client applications.

Parameters
$sub : string

The value of the sub claim used in the ID token.

Return values
AuthorizationIssueRequest —

$this object.

setSubject()

Set the subject (= unique identifier) of the end-user who has granted authorization to the client application.

public setSubject(string $subject) : AuthorizationIssueRequest

This request parameter is required unless the authorization request has come with response_type=none (which means the client application did not request any token to be returned). See 4. None Response Type in OAuth 2.0 Multiple Response Type Encoding Practices for details about response_type=none.

The given value is used as the value of the subject associated with the access token (if one is issued) and as the value of the sub claim in the ID token (if one is issued).

Note that, if getSub() method returns a non-empty value, it is used as the value of the sub claim in the ID token. However, even in such a case, the value of the subject associated with the access token is still the value which is passed to this method.

Parameters
$subject : string

The unique identifier of an end-user.

Return values
AuthorizationIssueRequest —

$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