public class UserInfoResponse extends ApiResponse
/auth/userinfo API.
Authlete's /auth/userinfo API returns JSON which can be mapped
to this class. The service implementation should retrieve the value of
"action" from the response and take the following steps
according to the value.
INTERNAL_SERVER_ERROR
When the value of "action" is "INTERNAL_SERVER_ERROR",
it means that the request from the service 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 the HTTP status of
"500 Internal Server Error".
getResponseContent() returns a string which describes the error
in the format of RFC 6750
(OAuth 2.0 Bearer Token Usage), so the UserInfo
Endpoint implementation of your service can use the string returned
from the method as the value of 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 UserInfo endpoint comply with RFC 6750. See 5.3.3. UserInfo Error Response for details.
HTTP/1.1 500 Internal Server Error
WWW-Authenticate: (The value returned from getResponseContent())
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 service implementation to Authlete does
not contain "token" parameter).
getResponseContent() returns a string which describes the error
in the format of RFC 6750
(OAuth 2.0 Bearer Token Usage), so the UserInfo
Endpoint implementation of your service can use the string returned
from the method as the value of 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 UserInfo endpoint comply with RFC 6750. See 5.3.3. UserInfo Error Response for details.
HTTP/1.1 400 Bad Request
WWW-Authenticate: (The value returned from getResponseContent())
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).
getResponseContent() returns a string which describes the error
in the format of RFC 6750
(OAuth 2.0 Bearer Token Usage), so the UserInfo
Endpoint implementation of your service can use the string returned
from the method as the value of 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 UserInfo endpoint comply with RFC 6750. See 5.3.3. UserInfo Error Response for details.
HTTP/1.1 401 Unauthorized
WWW-Authenticate: (The value returned from getResponseContent())
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.
getResponseContent() returns a string which describes the error
in the format of RFC 6750
(OAuth 2.0 Bearer Token Usage), so the UserInfo
Endpoint implementation of your service can use the string returned
from the method as the value of 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 UserInfo endpoint comply with RFC 6750. See 5.3.3. UserInfo Error Response for details.
HTTP/1.1 403 Forbidden
WWW-Authenticate: (The value returned from getResponseContent())
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 of your service should do next is to collect information
about the subject (user) from your database. The value of the subject
can be obtained from getSubject(), and the names of data, i.e.,
the claims names can be obtained from getClaims().
For example, if getSubject() returns "joe123" and getClaims() returns ["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 a userinfo
response. See the descriptions of UserInfoIssueRequest and UserInfoIssueResponse for details about /auth/userinfo/issue API.
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
Authlete 2.3 and newer version support "Transformed Claims". An
authorization request may request "transformed claims". A transformed
claim uses an existing claim as input. For example, an authorization server
may predefine a transformed claim named 18_or_over which uses the
birthdate claim as input. If a client application requests the
18_or_over transformation claim, the authorization server needs to
prepare the value of the birthdate claim and passes it to Authlete's
/api/auth/userinfo/issue API so that Authlete can compute the value
of the 18_or_over transformation claim. See the descriptions of
getRequestedClaimsForTx() and getRequestedVerifiedClaimsForTx()
for details.
| Modifier and Type | Class and Description |
|---|---|
static class |
UserInfoResponse.Action
The next action the service implementation should take.
|
| Constructor and Description |
|---|
UserInfoResponse() |
| Modifier and Type | Method and Description |
|---|---|
UserInfoResponse.Action |
getAction()
Get the next action the service implementation should take.
|
String[] |
getClaims()
Get the list of claims that the client application requests
to be embedded in the userinfo response.
|
Pair[] |
getClientAttributes()
Get the attributes of the client that the access token has been issued to.
|
long |
getClientId()
Get the client ID.
|
String |
getClientIdAlias()
Get the client ID alias when the authorization request for the access
token was made.
|
String[] |
getConsentedClaims()
Get the claims that the user has consented for the client application
to know.
|
Property[] |
getProperties()
Get the extra properties associated with the access token.
|
String[] |
getRequestedClaimsForTx()
Get names of claims that are requested indirectly by "transformed
claims".
|
StringArray[] |
getRequestedVerifiedClaimsForTx()
Get names of verified claims that are requested indirectly by
"transformed claims".
|
String |
getResponseContent()
Get the response content which can be used as a part of the
response to the client application.
|
String[] |
getScopes()
Get the scopes covered by the access token.
|
Pair[] |
getServiceAttributes()
Get the attributes of the service that the client application belongs to.
|
String |
getSubject()
Get the subject (= resource owner's ID).
|
String |
getToken()
Get the access token that came along with the userinfo request.
|
String |
getTransformedClaims()
Get 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. |
String |
getUserInfoClaims()
Get the value of the
"userinfo" property in the "claims"
request parameter or in the "claims" property in an authorization
request object. |
boolean |
isClientIdAliasUsed()
Get the flag which indicates whether the client ID alias was used
when the authorization request for the access token was made.
|
void |
setAction(UserInfoResponse.Action action)
Set the next action the service implementation should take.
|
void |
setClaims(String[] claims)
Set the list of claims that the client application requests
to be embedded in the ID token.
|
void |
setClientAttributes(Pair[] attributes)
Set the attributes of the client that the access token has been issued to.
|
void |
setClientId(long clientId)
Set the client ID.
|
void |
setClientIdAlias(String alias)
Set the client ID alias when the authorization request for the access
token was made.
|
void |
setClientIdAliasUsed(boolean used)
Set the flag which indicates whether the client ID alias was used
when the authorization request for the access token was made.
|
void |
setConsentedClaims(String[] claims)
Set the claims that the user has consented for the client application
to know.
|
void |
setProperties(Property[] properties)
Set the extra properties associated with the access token.
|
void |
setRequestedClaimsForTx(String[] claims)
Set names of claims that are requested indirectly by "transformed
claims".
|
void |
setRequestedVerifiedClaimsForTx(StringArray[] claimsArray)
Set names of verified claims that are requested indirectly by
"transformed claims".
|
void |
setResponseContent(String responseContent)
Set the response content which can be used as a part of the
response to the client application.
|
void |
setScopes(String[] scopes)
Set the scopes covered by the access token.
|
void |
setServiceAttributes(Pair[] attributes)
Set the attributes of the service that the client application belongs to.
|
void |
setSubject(String subject)
Set the subject (= resource owner's ID).
|
void |
setToken(String accessToken)
Set the access token that came along with the userinfo request.
|
void |
setTransformedClaims(String transformedClaims)
Set 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. |
void |
setUserInfoClaims(String userInfoClaims)
Set the value of the
"userinfo" property in the "claims"
request parameter or in the "claims" property in an authorization
request object. |
String |
summarize()
Get the summary of this instance.
|
getResultCode, getResultMessage, setResultCode, setResultMessagepublic UserInfoResponse.Action getAction()
public void setAction(UserInfoResponse.Action action)
public long getClientId()
public void setClientId(long clientId)
public String getSubject()
public void setSubject(String subject)
public String[] getScopes()
public void setScopes(String[] scopes)
public String[] getClaims()
"scope" and "claims" request parameters of
the original authorization request.public void setClaims(String[] claims)
public String getToken()
public void setToken(String accessToken)
public String getResponseContent()
public void setResponseContent(String responseContent)
public String summarize()
public Property[] getProperties()
null when
no extra property is associated with the access token.public void setProperties(Property[] properties)
properties - Extra properties.public String getClientIdAlias()
public void setClientIdAlias(String alias)
alias - The client ID alias.public boolean isClientIdAliasUsed()
true if the client ID alias was used when the
authorization request for the access token was made.public void setClientIdAliasUsed(boolean used)
used - true if the client ID alias was used when the
authorization request for the access token was made.public String getUserInfoClaims()
"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
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.
"userinfo" property in the
"claims" in JSON format.public void setUserInfoClaims(String userInfoClaims)
"userinfo" property in the "claims"
request parameter or in the "claims" property in an authorization
request object.userInfoClaims - The value of the "userinfo" property in the
"claims" in JSON format.public String getTransformedClaims()
"transformed_claims" property in the
"claims" request parameter of an authorization request or
in the "claims" property in a request object."transformed_claims" property in the
"claims" in JSON format.public void setTransformedClaims(String transformedClaims)
"transformed_claims" property in the
"claims" request parameter of an authorization request or
in the "claims" property in a request object.transformedClaims - The value of the "transformed_claims" property in the
"claims" in JSON format.public String[] getConsentedClaims()
The following Authlete APIs accept a consentedClaims request
parameter (which is supported from Authlete 2.3).
/api/auth/authorization/issue
/api/backchannel/authentication/complete
/api/device/complete
The request parameter is used to convey consented claims to Authlete.
This property holds the consented claims. See the description of
AuthorizationIssueRequest.setConsentedClaims(String[]) for
details.
AuthorizationIssueRequest#setConsentedClaims(String[])},
BackchannelAuthenticationCompleteRequest#setConsentedClaims(String[])},
DeviceCompleteRequest#setConsentedClaims(String[])}public void setConsentedClaims(String[] claims)
The following Authlete APIs accept a consentedClaims request
parameter (which is supported from Authlete 2.3).
/api/auth/authorization/issue
/api/backchannel/authentication/complete
/api/device/complete
The request parameter is used to convey consented claims to Authlete.
This property holds the consented claims. See the description of
AuthorizationIssueRequest.setConsentedClaims(String[]) for
details.
claims - Consented claims.AuthorizationIssueRequest#setConsentedClaims(String[])},
BackchannelAuthenticationCompleteRequest#setConsentedClaims(String[])},
DeviceCompleteRequest#setConsentedClaims(String[])}public String[] getRequestedClaimsForTx()
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 transformation claim. Likewise, the
birthdate claim is requested indirectly by the 18_or_over
transformation 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
(cf. UserInfoIssueRequest.setClaimsForTx(String)). The following
is an example of the value of the claimsForTx request parameter.
{
"birthdate": "1970-01-23",
"nationalities": [ "DEU", "USA" ]
}
This requestedClaimsForTx property is available from Authlete 2.3
onwards.
public void setRequestedClaimsForTx(String[] claims)
See the description of getRequestedClaimsForTx() for details.
claims - Names of claims that are requested indirectly by
"transformed claims"getRequestedClaimsForTx()public StringArray[] getRequestedVerifiedClaimsForTx()
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": {
"verified_claims": {
"verification": {
"trust_framework": null
},
"claims": {
"::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 transformation claim. Likewise, the
birthdate claim is requested indirectly by the 18_or_over
transformation claim.
When the claims request parameter of an authorization request is
like the example above, this requestedVerifiedClaimsForTx property
will hold the following value.
[
{ "array": [ "birthdate", "nationalities" ] }
]
It is expected that the authorization server implementation prepares
values of the listed verified claims and passes them as the value of
the verifiedClaimsForTx request parameter when it calls the
/api/auth/userinfo/issue API (cf.
UserInfoIssueRequest.setVerifiedClaimsForTx(String[])).
The following is an example of the value of the
verifiedClaimsForTx request parameter.
[
"{\"birthdate\":\"1970-01-23\",\"nationalities\":[\"DEU\",\"USA\"]}"
]
The reason that this requestVerifiedClaimsForTx property and
the verifiedClaimsForTx request parameter are arrays is that
the "verified_claims" property in the claims request
parameter 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 }
}
]
}
}
The order of elements in requestedVerifiedClaimsForTx matches
the order of elements in the "verified_claims" array.
This requestedVerifiedClaimsForTx property is available from
Authlete 2.3 onwards.
public void setRequestedVerifiedClaimsForTx(StringArray[] claimsArray)
See the description of getRequestedVerifiedClaimsForTx() for
details.
This requestedVerifiedClaimsForTx property is available from
Authlete 2.3 onwards.
claimsArray - Names of verified claims that are requested indirectly by
"transformed claims"getRequestedVerifiedClaimsForTx()public Pair[] getServiceAttributes()
This property is available since Authlete 2.2.
public void setServiceAttributes(Pair[] attributes)
This property is available since Authlete 2.2.
attributes - The attributes of the service.public Pair[] getClientAttributes()
This property is available since Authlete 2.2.
public void setClientAttributes(Pair[] attributes)
This property is available since Authlete 2.2.
attributes - The attributes of the client.Copyright © 2022. All rights reserved.