Sign in
UserInfo Endpoint

Process UserInfo Request

This API gathers information about a user.

Description

This API is supposed to be called from within the implementation of the userinfo endpoint of the authorization server in order to get information about the user that is associated with an access token. The response from /auth/userinfo 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 value of responseContent is 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 value of responseContent is 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 value of responseContent is 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 value of responseContent is 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

OK When the value of action is 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, includes the openid scope, and is associated with a subject (= a user account). What the userinfo endpoint implementation should do next is to collect information about the subject (user) from your database. The value of the subject is contained in the subject parameter in the response from this API and the names of data, i.e., the claims names are contained in the claims parameter in the response. For example, if the subject parameter is joe123 and the claims parameter is [ "given\_name", "email" ], you need to extract information about joe123's given name and email from your database. Then, call Authlete's /auth/userinfo/issue API with the collected information and the access token in order to make Authlete generate an ID token. If an error occurred during the above steps, generate an error response to the client. 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 subject associated with the access token does not exist."
Cache-Control: no-store
Pragma: 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 extract information about the subject from the database."
Cache-Control: no-store
Pragma: no-cache
post/api/{serviceId}/auth/userinfo

Path parameters

serviceIdstring required

A service ID.

Request body

tokenstring required

An access token.

clientCertificatestring

Client certificate used in the TLS connection established between the client application and the userinfo endpoint.

The value of this request parameter is referred to when the access token given to the userinfo endpoint was bound to a client certificate when it was issued. See [OAuth 2.0 Mutual TLS Client Authentication and Certificate-Bound Access Tokens] (https://datatracker.ietf.org/doc/rfc8705/) for details about the specification of certificate-bound access tokens.

dpopstring

DPoP header presented by the client during the request to the user info endpoint.

The header contains a signed JWT which includes the public key that is paired with the private key used to sign the JWT. See OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP) for details.

htmstring

HTTP method of the user info request. This field is used to validate the DPoP header. In normal cases, the value is either GET or POST.

htustring

URL of the user info endpoint. This field is used to validate the DPoP header.

If this parameter is omitted, the userInfoEndpoint property of the service is used as the default value. See OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP) for details.

uristring

The full URL of the userinfo endpoint.

messagestring

The HTTP message body of the request, if present.

targetUristring

The target URI of the userinfo request, including the query part, if any.

This parameter is used as the value of the @target-uri derived component for HTTP message signatures (RFC 9421 HTTP Message Signatures, Section 2.2.2. Target URI). Additionally, other derived components such as @authority, @scheme, @path, @query and @query-param are computed from this parameter.

When this parameter is omitted, the value of the htu parameter is used. The htu parameter represents the URL of the userinfo endpoint, which usually serves as the target URI of the userinfo request. The only exception is when the access token is specified as a query parameter, as defined in RFC 6750 Section 2.3. However, RFC 6750 states that this method "SHOULD NOT be used" unless other methods are not viable.

If neither this targetUri parameter nor the htu parameter is specified, the userInfoEndpoint property of the service is used as a fallback.

dpopNonceRequiredboolean

The flag indicating whether to check if the DPoP proof JWT includes the expected nonce value.

If this request parameter is set to true or if the service's dpopNonceRequired property is set to true, the /auth/userinfo API checks if the DPoP proof JWT includes the expected nonce value. In this case, the response from the /auth/userinfo API will include the dpopNonce response parameter, which should be used as the value of the DPoP-Nonce HTTP header.

requestBodyContainedboolean

The flag indicating whether the userinfo request contains a request body.

When the userinfo request must comply with the HTTP message signing requirements defined in the FAPI 2.0 Message Signing specification, the "content-digest" component identifier must be included in the signature base of the HTTP message signature (see RFC 9421 HTTP Message Signatures) if the userinfo request contains a request body.

When this requestBodyContained parameter is set to true, Authlete checks whether "content-digest" is included in the signature base, if the FAPI profile applies to the userinfo request.

NOTE: The FAPI 2.0 Message Signing specification is not applied to the userinfo endpoint until its necessity is agreed upon by the industry (cf. FAPI Issue 723).

Response

User info retrieved 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' | 'OK'

The next action that the authorization server implementation should take.

claimsstring[]

The list of claims that the client application requests to be embedded in the ID token.

clientIdinteger

The ID of the client application which is associated with the access token.

clientIdAliasstring

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

clientIdAliasUsedboolean

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

responseContentstring

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

scopesstring[]

The scopes covered by the access token.

subjectstring

The subject (= resource owner's ID).

tokenstring

The access token that came along with the userinfo request.

userInfoClaimsstring

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

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 cases, the value of the claims parameter/property is JSON. Its format is described in 5.5. Requesting Claims using the "claims" Request Parameter.

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

The value of this property is the value of the userinfo property in JSON format. For example, if the JSON above is included in an authorization request, this property holds 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, the value of this property holds the former value.

consentedClaimsstring[]

the claims that the user has consented for the client application to know.

requestedClaimsForTxstring[]

Get names of claims that are requested indirectly by "transformed claims". A client application can request "transformed claims" by adding names of transformed claims in the claims request parameter. The following is an example of the claims request parameter that requests a predefined transformed claim named 18\_or\_over and a transformed claim named nationality\_usa to be embedded in the response from the userinfo endpoint.

{
"transformed\_claims": {
"nationality\_usa": {
"claim": "nationalities",
"fn": [
[ "eq", "USA" ],
"any"
]
}
},
"userinfo": {
"::18\_or\_over": null,
":nationality\_usa": null
}
}

The example above assumes that a transformed claim named 18\_or\_over is predefined by the authorization server like below.

{
"18\_or\_over": {
"claim": "birthdate",
"fn": [
"years\_ago",
[ "gte", 18 ]
]
}
}

In the example, the nationalities claim is requested indirectly by the nationality\_usa transformed claim. Likewise, the birthdate claim is requested indirectly by the 18\_or\_over transformed claim. When the claims request parameter of an authorization request is like the example above, this requestedClaimsForTx property will hold the following value.

[ "birthdate", "nationalities" ]

It is expected that the authorization server implementation prepares values of the listed claims and passes them as the value of the claimsForTx request parameter when it calls the /api/auth/userinfo/issue API. The following is an example of the value of the claimsForTx request parameter.

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

the value of the transformed_claims property in the claims request parameter of an authorization request or in the claims property in a request object.

clientEntityIdstring

The entity ID of the client.

clientEntityIdUsedboolean

Flag which indicates whether the entity ID of the client was used when the request for the access token was made.

dpopNoncestring

The expected nonce value for DPoP proof JWT, which should be used as the value of the DPoP-Nonce HTTP header.

metadataDocumentLocationstring uri

The location of the client's metadata document that was used to resolve client metadata.

This property is set when client metadata was retrieved via the OAuth Client ID Metadata Document (CIMD) mechanism.

metadataDocumentUsedboolean

Flag indicating whether a metadata document was used to resolve client metadata for this request.

When true, the client metadata was retrieved via the CIMD mechanism rather than from the Authlete database.

Changes