Sign in
UserInfo Endpoint

Issue UserInfo Response

This API generates an ID token.

Description

This API is supposed to be called from within the implementation of the userinfo endpoint of the authorization server in order to generate an ID token. Before calling this API, a valid response from /auth/userinfo API must be obtained. Then, call this API with the access token contained in the response and the claims values of the user (subject) associated with the access token. See OK written in the description of /auth/userinfo API for details. The response from /auth/userinfo/issue API has various 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 service 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 parameter responseContent 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 value of responseContent as the value ofWWW-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 userinfo endpoint comply with RFC 6750. See 5.3.3. UserInfo Response for details.

HTTP/1.1 500 Internal Server Error
WWW-Authenticate: {responseContent}
Cache-Control: no-store
Pragma: no-cache

BAD_REQUEST When the value of action is BAD\_REQUEST, it means that the request from the client application does not contain an access token (= the request from the authorization server implementation to Authlete does not contain token parameter). The parameter responseContent 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 value of responseContent as the value ofWWW-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 userinfo endpoint comply with RFC 6750. See 5.3.3. UserInfo Response for details.

HTTP/1.1 400 Bad Request
WWW-Authenticate: {responseContent}
Cache-Control: no-store
Pragma: no-cache

UNAUTHORIZED When the value of action is UNAUTHORIZED, it means that the access token does not exist, has expired, or is not associated with any subject (= any user account). The parameter responseContent 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 value of responseContent as the value ofWWW-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 userinfo endpoint comply with RFC 6750. See 5.3.3. UserInfo Response for details.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: {responseContent}
Cache-Control: no-store
Pragma: no-cache

FORBIDDEN When the value of action is FORBIDDEN, it means that the access token does not include the openid scope. The parameter responseContent 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 value of responseContent as the value ofWWW-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 userinfo endpoint comply with RFC 6750. See 5.3.3. UserInfo Response for details.

HTTP/1.1 403 Forbidden
WWW-Authenticate: {responseContent}
Cache-Control: no-store
Pragma: no-cache

JSON When the value of action is JSON, it means that the access token which the client application presented is valid and an ID token was successfully generated in the format of JSON. The userinfo endpoint implementation is expected to generate a response to the client application. The content type of the response must be application/json and the response body must be an ID token in JSON format. The value of responseContent is the ID token in JSON format when action is JSON, so a response to the client can be built like below.

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

JWT When the value of action is JWT, it means that the access token which the client application presented is valid and an ID token was successfully generated in the format of JWT (JSON Web Token) (RFC 7519). The userinfo endpoint implementation is expected to generate a response to the client application. The content type of the response must be application/jwt and the response body must be an ID token in JWT format. The value of responseContent is the ID token in JSON format when action is JWT, so a response to the client can be built like below.

HTTP/1.1 200 OK
Cache-Control: no-store
Pragma: no-cache
Content-Type: application/jwt
{responseContent}
post/api/{serviceId}/auth/userinfo/issue

Path parameters

serviceIdstring required

A service ID.

Request body

tokenstring required

The access token that has been passed to the userinfo endpoint by the client application. In other words, the access token which was contained in the userinfo request.

claimsstring

Claims in JSON format. As for the format, see OpenID Connect Core 1.0, 5.1. Standard Claims.

substring

The value of the sub claim. If the value of this request parameter is not empty, it is used as the value of the sub claim. Otherwise, the value of the subject associated with the access token is used.

claimsForTxstring

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

requestSignaturestring

The Signature header value from the request.

verifiedClaimsForTxstring[]

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

A client application may request "transformed claims". Each of transformed claims uses an existing claim as input. As a result, to compute the value of a transformed claim, the value of the referenced existing claim is needed. This verifiedClaimsForTx request parameter has to be used to provide values of existing claims for computation of transformed claims.

A response from the /auth/userinfo API may include the requestedVerifiedClaimsForTx response parameter which is a list of verified claims that are referenced indirectly by transformed claims (cf. requestedVerifiedClaimsForTx in /auth/userinfo API response). The authorization server implementation should prepare values of the verified claims listed in requestedVerifiedClaimsForTx and pass them as the value of this verifiedClaimsForTx request parameter.

The following is an example of the value of this request parameter.

[
  "{\"birthdate\":\"1970-01-23\",\"nationalities\":[\"DEU\",\"USA\"]}"
]

The reason that this verifiedClaimsForTx property is an array is that the "verified_claims" property in the claims request parameter of an authorization request can be an array like below.

{
  "transformed_claims": {
    "nationality_usa": {
      "claim": "nationalities",
      "fn": [
        [ "eq", "USA" ],
        "any"
      ]
    }
  },
  "userinfo": {
    "verified_claims": [
      {
        "verification": { "trust_framework": { "value": "gold" } },
        "claims": { "::18_or_above": null }
      },
      {
        "verification": { "trust_framework": { "value": "silver" } },
        "claims": { ":nationality_usa": null }
      }
    ]
  }
}

For the example above, the value of this verifiedClaimsForTx property should be an array of size 2 and look like below. The first element is JSON including claims which have been verified under the trust framework "gold", and the second element is JSON including claims which have been verified under the trust framework "silver".

[
  "{\"birthdate\":\"1970-01-23\"}",
  "{\"nationalities\":[\"DEU\",\"USA\"]}"
]

Response

User info issued successfully

resultCodestring

The code which represents the result of the API call.

resultMessagestring

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

action'INTERNAL_SERVER_ERROR' | 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'JSON' | 'JWT'

The next action that the authorization server implementation should take.

responseContentstring

The content that the authorization server implementation can use as the value of WWW-Authenticate header on errors.

signaturestring

The signature header of the response message.

signatureInputstring

The signature-input header of the response message

contentDigeststring

The content-digest header of the response message

Changes