Documentation

UserInfoResponse extends ApiResponse

Response from Authlete's /api/auth/userinfo API.

Authlete's /api/auth/userinfo API returns JSON which can be mapped to this class. The userinfo endpoint implementation should retrieve the value of the action response parameter (which can be obtained by getAction() method of this class) and take the following steps according to the value.

When the value returned from getAction() method is UserInfoAction::$INTERNAL_SERVER_ERROR, it means that the request from your system 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 userinfo endpoint implementation should generate a response to the client application with the HTTP status of 500 Internal Server Error.

In this case, getResponseContent() method returns a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage), so the userinfo endpoint implementation can use the string returned from the method as the value of the 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 the userinfo endpoint comply with RFC 6750. See 5.3.3. UserInfo Error Response of OpenID Connect Core 1.0 for details.

HTTP/1.1 500 Internal Server Error
WWW-Authenticate: (The value returned from getResponseContent())
Cache-Control: no-store
Pragma: no-cache

When the value returned from getAction() method is UserInfoAction::$BAD_REQUEST, it means that the request from the client application does not contain an access token (= the request from your system to Authlete does not contain the token request parameter).

HTTP/1.1 400 Bad Request
WWW-Authenticate: (The value returned from getResponseContent())
Cache-Control: no-store
Pragma: no-cache

When the value returned from getAction() method is UserInfoAction::$UNAUTHORIZED, it means that the access token does not exist, has expired, or is not associated with any subject (= any end-user).

HTTP/1.1 401 Unauthorized
WWW-Authenticate: (The value returned from getResponseContent())
Cache-Control: no-store
Pragma: no-cache

When the value returned from getAction() method is UserInfoAction::$FORBIDDEN, it means that the access token does not have the openid scope.

HTTP/1.1 403 Forbidden
WWW-Authenticate: (The value returned from getResponseContent())
Cache-Control: no-store
Pragma: no-cache

When the value returned from getAction() method is UserInfoAction::$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, has the openid scope, and is associated with a subject (= an end-user).

What the userinfo endpoint implementation of your system should do next is to collect information about the subject (end-user) from your database. The value of the subject can be obtained from getSubject() method, and the names of data, i.e., the claim names, can be obtained from getClaims() method. For example, if getSubject() method returns joe123 and getClaims() method returns ["given_name", "email"], you need to extract information about joe123's given name and email from your database.

Then, call Authlete's /api/auth/userinfo/issue API with the collected information and the access token in order to make Authlete generate a userinfo response. See the description of UserInfoIssueRequest and UserInfoIssueResponse for details about /api/auth/userinfo/issue API.

If an error occurred during the above steps, generate an error response to the client application. The response should comply with RFC 6750. 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 user does not exist any longer."
Cache-Control: no-store
Pragram: 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 access the database."
Cache-Control: no-store
Pragma: no-cache

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.
getAction() : UserInfoAction: Get the next action that the userinfo endpoint should take.
getClaims() : array<string|int, string>: Get the list of claims that the client application requests to be embedded in the userinfo response.
getClientId() : int|string: Get the ID of the client application to which the access token has been issued.
getClientIdAlias() : string: Get the client ID alias when the authorization request for the access token was made.
getProperties() : array<string|int, Property>: Get the properties associated with the access token.
getResponseContent() : string: Get the response content which can be used as a part of the response to the client application.
getResultCode() : string: Get the code of the result of an Authlete API call.
getResultMessage() : string: Get the message of the result of an Authlete API call.
getScopes() : array<string|int, string>: Get the scopes that the access token covers.
getSubject() : string: Get the subject (= unique identifier) of the end-user which is associated with the access token.
getToken() : string: Get the access token that the userinfo endpoint received from the client application.
getUserInfoClaims() : string: Get the value of the `userinfo` property in the `claims` request parameter or in the `claims` property in an authorization request object.
isClientIdAliasUsed() : bool: Get the flag which indicates whether the client ID alias was used when the authorization request for the access token was made.
setAction() : UserInfoResponse: Set the next action that the userinfo endpoint should take.
setClaims() : UserInfoResponse: Set the list of claims that the client application requests to be embedded in the userinfo response.
setClientId() : UserInfoResponse: Set the ID of the client application to which the access token has been issued.
setClientIdAlias() : UserInfoResponse: Set the client ID alias when the authorization request for the access token was made.
setClientIdAliasUsed() : UserInfoResponse: Set the flag which indicates whether the client ID alias was used when the authorization request for the access token was made.
setProperties() : UserInfoResponse: Set the properties associated with the access token.
setResponseContent() : UserInfoResponse: Set the response content which can be used as a part of the response to the client application.
setResultCode() : ApiResponse: Set the code of the result of an Authlete API call.
setResultMessage() : ApiResponse: Set the message of the result of an Authlete API call.
setScopes() : UserInfoResponse: Set the scopes that the access token covers.
setSubject() : UserInfoResponse: Set the subject (= unique identifier) of the end-user which is associated with the access token.
setToken() : UserInfoResponse: Set the access token that the userinfo endpoint received from the client application.
setUserInfoClaims() : UserInfoResponse: Set the value of the `userinfo` property in the `claims` request parameter or in the `claims` property in a request object.
toArray() : array<string|int, mixed>: Convert this object into an array.
toJson() : string: Convert this object into a JSON string.

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.

getAction()

Get the next action that the userinfo endpoint should take.


    public
                getAction() : UserInfoAction

Return values

UserInfoAction —

The next action that the userinfo endpoint should take.

getClaims()

Get the list of claims that the client application requests to be embedded in the userinfo response.


    public
                getClaims() : array<string|int, string>

The value comes from the scope and/or claims request parameters of the original authorization request. See 5.4. Requesting Claims using Scope Values and 5.5. Requesting Claims using the "claims" Request Parameter of OpenID Connect Core 1.0 for details.

Return values

array<string|int, string> —

The list of claims that the client application requests to be embedded in the userinfo response.

getClientId()

Get the ID of the client application to which the access token has been issued.


    public
                getClientId() : int|string

Return values

int|string —

The client ID.

getClientIdAlias()

Get the client ID alias when the authorization request for the access token was made.


    public
                getClientIdAlias() : string

Note that this value may be different from the current client ID alias.

Return values

string —

The client ID alias when the authorization request for the access token was made.

getProperties()

Get the properties associated with the access token.


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

Return values

array<string|int, Property> —

The troperties associated with the access token.

getResponseContent()

Get the response content which can be used as a part of the response to the client application.


    public
                getResponseContent() : string

Return values

string —

The response content.

getResultCode()

Get the code of the result of an Authlete API call.


    public
                getResultCode() : string

Return values

string —

The result code.

getResultMessage()

Get the message of the result of an Authlete API call.


    public
                getResultMessage() : string

Return values

string —

The result message.

getScopes()

Get the scopes that the access token covers.


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

Return values

array<string|int, string> —

The scopes that the access token covers.

getSubject()

Get the subject (= unique identifier) of the end-user which is associated with the access token.


    public
                getSubject() : string

Return values

string —

The subject of the end-user.

getToken()

Get the access token that the userinfo endpoint received from the client application.


    public
                getToken() : string

Return values

string —

The access token that the userinfo endpoint received from the client application.

getUserInfoClaims()

Get the value of the `userinfo` property in the `claims` request parameter or in the `claims` property in an authorization request object.


    public
                getUserInfoClaims() : string

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 of OpenID Connect Core 1.0.

The following is an excerpt from the specification. You can find userinfo and id_token are top-level properties.

{
 "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"] }
  }
}

This method (getUserInfoClaims) returns the value of the userinfo property in JSON format. For example, if the JSON above is included in an authorization request, this method returns JSON equivalent to the following.

{
 "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, this method returns the value in the former.

Return values

string —

The value of the userinfo property in the claims in JSON format.

isClientIdAliasUsed()

Get the flag which indicates whether the client ID alias was used when the authorization request for the access token was made.


    public
                isClientIdAliasUsed() : bool

Return values

bool —

true if the client ID alias was used when the authorization request for the access token was made.

setAction()

Set the next action that the userinfo endpoint should take.


    public
                setAction([UserInfoAction $action = null ]) : UserInfoResponse

Parameters

$action : UserInfoAction = null: The next action that the userinfo endpoint should take.

Return values

UserInfoResponse —

$this object.

setClaims()

Set the list of claims that the client application requests to be embedded in the userinfo response.


    public
                setClaims([array<string|int, string> $claims = null ]) : UserInfoResponse

Parameters

$claims : array<string|int, string> = null: The list of claims that the client application requests to be embedded in the userinfo response.

Return values

UserInfoResponse —

$this object.

setClientId()

Set the ID of the client application to which the access token has been issued.


    public
                setClientId(int|string $clientId) : UserInfoResponse

Parameters

$clientId : int|string: The client ID.

Return values

UserInfoResponse —

$this object.

setClientIdAlias()

Set the client ID alias when the authorization request for the access token was made.


    public
                setClientIdAlias(string $alias) : UserInfoResponse

Parameters

$alias : string: The client ID alias when the authorization request for the access token was made.

Return values

UserInfoResponse —

$this object.

setClientIdAliasUsed()

Set the flag which indicates whether the client ID alias was used when the authorization request for the access token was made.


    public
                setClientIdAliasUsed(bool $used) : UserInfoResponse

Parameters

$used : bool: true if the client ID alias was used when the authorization request for the access token was made.

Return values

UserInfoResponse —

$this object.

setProperties()

Set the properties associated with the access token.


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

Parameters

$properties : array<string|int, Property> = null: The troperties associated with the access token.

Return values

UserInfoResponse —

$this object.

setResponseContent()

Set the response content which can be used as a part of the response to the client application.


    public
                setResponseContent(string $responseContent) : UserInfoResponse

Parameters

$responseContent : string: The response content.

Return values

UserInfoResponse —

$this object.

setResultCode()

Set the code of the result of an Authlete API call.


    public
                setResultCode(string $resultCode) : ApiResponse

Parameters

$resultCode : string: The result code.

Return values

ApiResponse —

$this object.

setResultMessage()

Set the message of the result of an Authlete API call.


    public
                setResultMessage(string $resultMessage) : ApiResponse

Parameters

$resultMessage : string: The result message.

Return values

ApiResponse —

$this object.

setScopes()

Set the scopes that the access token covers.


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

Parameters

$scopes : array<string|int, string> = null: The scopes that the access token covers.

Return values

UserInfoResponse —

$this object.

setSubject()

Set the subject (= unique identifier) of the end-user which is associated with the access token.


    public
                setSubject(string $subject) : UserInfoResponse

Parameters

$subject : string: The subject of the end-user.

Return values

UserInfoResponse —

$this object.

setToken()

Set the access token that the userinfo endpoint received from the client application.


    public
                setToken(string $token) : UserInfoResponse

Parameters

$token : string: The access token that the userinfo endpoint received from the client application.

Return values

UserInfoResponse —

$this object.

setUserInfoClaims()

Set the value of the `userinfo` property in the `claims` request parameter or in the `claims` property in a request object.


    public
                setUserInfoClaims(string $claims) : UserInfoResponse

Parameters

$claims : string: The value of the userinfo property in the claims in JSON format.

Return values

UserInfoResponse —

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

UserInfoResponse extends ApiResponse

Table of Contents

Methods

copyFromArray()

Parameters

Return values

copyToArray()

Parameters

Return values

fromArray()

Parameters

Return values

fromJson()

Parameters

Return values

getAction()

Return values

getClaims()

Return values

getClientId()

Return values

getClientIdAlias()

Return values

getProperties()

Return values

getResponseContent()

Return values

getResultCode()

Return values

getResultMessage()

Return values

getScopes()

Return values

getSubject()

Return values

getToken()

Return values

getUserInfoClaims()

Tags

Return values

isClientIdAliasUsed()

Return values

setAction()

Parameters

Return values

setClaims()

Parameters

Return values

setClientId()

Parameters

Return values

setClientIdAlias()

Parameters

Return values

setClientIdAliasUsed()

Parameters

Return values

setProperties()

Parameters

Return values

setResponseContent()

Parameters

Return values

setResultCode()

Parameters

Return values

setResultMessage()

Parameters

Return values

setScopes()

Parameters

Return values

setSubject()

Parameters

Return values

setToken()

Parameters

Return values

setUserInfoClaims()

Parameters