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

Properties
UserInfoAction	Action `[get, set]`
	The next action that the userinfo endpoint should take. More...

long	ClientId `[get, set]`
	The ID of the client application to which the access token has been issued. More...

string	Subject `[get, set]`
	The subject (= unique identifier) of an end-user which is associated with the access token. More...

string[]	Scopes `[get, set]`
	The scopes that the access token covers. More...

string[]	Claims `[get, set]`
	The list of claims that the client application requests to be embedded in the userinfo response. 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. More...

string	Token `[get, set]`
	The access token that the userinfo endpoint of your system received from the client application and sent to Authlete's `/api/auth/userinfo` API. More...

string	ResponseContent `[get, set]`
	The response content which can be used as a part of the response to the client application. More...

Property[]	Properties `[get, set]`
	Properties associated with the access token. More...

string	ClientIdAlias `[get, set]`
	The client ID alias when the authorization request for the access token was made. Note that this value may be different from the current client ID alias. More...

bool	ClientIdAliasUsed `[get, set]`
	The flag which indicates whether the client ID alias was used when the authorization request for the access token was made. More...

Detailed Description

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 via the Action property of this class) and take the following steps according to the value.

When the value of the Action property 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, the ResponseContent property 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 property 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 ResponseContent)
Cache-Control: no-store
Pragma: no-cache

When the value of the Action property 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).

In this case, the ResponseContent property 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 property as the value of the WWW-Authenticate header. The following is an example response from the userinfo endpoint to the client application.

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

When the value of the Action property is UserInfoAction.UNAUTHORIZED, it means that the access token does not exist, has expired, or is not associated with any subject (= any end-user).

In this case, the ResponseContent property 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 property as the value of the WWW-Authenticate header. The following is an example response from the userinfo endpoint to the client application.

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

When the value of the Action property is UserInfoAction.FORBIDDEN, it means that the access token does not have the "openid" scope.

In this case, the ResponseContent property 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 property as the value of the WWW-Authenticate header. The following is an example response from the userinfo endpoint to the client application.

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

When the value of the Action property 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 the Subject property, and the names of data, i.e., the claim names, can be obtained from the Claims property. For example, if the Subject property returns "joe123" and the Claims property 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

Property Documentation

◆ Action

UserInfoAction Action

getset

The next action that the userinfo endpoint should take.

◆ Claims

string [] Claims

getset

The list of claims that the client application requests to be embedded in the userinfo response. 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.

◆ ClientId

long ClientId

getset

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

◆ ClientIdAlias

string ClientIdAlias

getset

The client ID alias when the authorization request for the access token was made. Note that this value may be different from the current client ID alias.

◆ ClientIdAliasUsed

bool ClientIdAliasUsed

getset

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

◆ Properties

Property [] Properties

getset

Properties associated with the access token.

◆ ResponseContent

string ResponseContent

getset

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

◆ Scopes

string [] Scopes

getset

The scopes that the access token covers.

◆ Subject

string Subject

getset

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

◆ Token

string Token

getset

The access token that the userinfo endpoint of your system received from the client application and sent to Authlete's /api/auth/userinfo API.

The documentation for this class was generated from the following file:

Authlete/Dto/UserInfoResponse.cs