Package com.authlete.common.dto

Class UserInfoResponse

  • All Implemented Interfaces:
    Serializable
    public class UserInfoResponse
extends ApiResponse
    Response from Authlete's /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 transformed 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 transformed claim. See the descriptions of getRequestedClaimsForTx() and getRequestedVerifiedClaimsForTx() for details.

    Author:
    Takahiko Kawasaki
    See Also:
    Serialized Form

    • Constructor Detail

      • UserInfoResponse

        public UserInfoResponse()

    • Method Detail

      • getAction

        public UserInfoResponse.Action getAction()
        Get the next action the service implementation should take.

      • setAction

        public void setAction​(UserInfoResponse.Action action)
        Set the next action the service implementation should take.

      • getClientId

        public long getClientId()
        Get the client ID.

      • setClientId

        public void setClientId​(long clientId)
        Set the client ID.

      • getSubject

        public String getSubject()
        Get the subject (= resource owner's ID).

      • setSubject

        public void setSubject​(String subject)
        Set the subject (= resource owner's ID).

      • getScopes

        public String[] getScopes()
        Get the scopes covered by the access token.

      • setScopes

        public void setScopes​(String[] scopes)
        Set the scopes covered by the access token.

      • setClaims

        public void setClaims​(String[] claims)
        Set the list of claims that the client application requests to be embedded in the ID token.

      • getToken

        public String getToken()
        Get the access token that came along with the userinfo request.

      • setToken

        public void setToken​(String accessToken)
        Set the access token that came along with the userinfo request.

      • getResponseContent

        public String getResponseContent()
        Get the response content which can be used as a part of the response to the client application.

      • setResponseContent

        public void setResponseContent​(String responseContent)
        Set the response content which can be used as a part of the response to the client application.

      • summarize

        public String summarize()
        Get the summary of this instance.

      • getProperties

        public Property[] getProperties()
        Get the extra properties associated with the access token.
        Returns:
        Extra properties. This method returns null when no extra property is associated with the access token.
        Since:
        2.5

      • setProperties

        public void setProperties​(Property[] properties)
        Set the extra properties associated with the access token.
        Parameters:
        properties - Extra properties.
        Since:
        2.5

      • getClientIdAlias

        public String getClientIdAlias()
        Get 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.
        Returns:
        The client ID alias when the authorization request for the access token was made.
        Since:
        2.5

      • setClientIdAlias

        public void setClientIdAlias​(String alias)
        Set the client ID alias when the authorization request for the access token was made.
        Parameters:
        alias - The client ID alias.
        Since:
        2.5

      • isClientIdAliasUsed

        public boolean isClientIdAliasUsed()
        Get the flag which indicates whether the client ID alias was used when the authorization request for the access token was made.
        Returns:
        true if the client ID alias was used when the authorization request for the access token was made.
        Since:
        2.5

      • setClientIdAliasUsed

        public 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.
        Parameters:
        used - true if the client ID alias was used when the authorization request for the access token was made.
        Since:
        2.5

      • getClientEntityId

        public URI getClientEntityId()
        Get the entity ID of the client.

        "Entity ID" is a technical term defined in OpenID Federation 1.0.

        Returns:
        The entity ID of the client.
        Since:
        3.37, Authlete 2.3
        See Also:
        OpenID Federation 1.0

      • setClientEntityId

        public void setClientEntityId​(URI entityId)
        Set the entity ID of the client.

        "Entity ID" is a technical term defined in OpenID Federation 1.0.

        Parameters:
        entityId - The entity ID of the client.
        Since:
        3.37, Authlete 2.3
        See Also:
        OpenID Federation 1.0

      • isClientEntityIdUsed

        public boolean isClientEntityIdUsed()
        Get the flag which indicates whether the entity ID of the client was used when the request for the access token was made.

        "Entity ID" is a technical term defined in OpenID Federation 1.0.

        Returns:
        true if the entity ID of the client was used when the request for the access token was made.
        Since:
        3.37, Authlete 2.3
        See Also:
        OpenID Federation 1.0

      • setClientEntityIdUsed

        public void setClientEntityIdUsed​(boolean used)
        Set the flag which indicates whether the entity ID of the client was used when the request for the access token was made.

        "Entity ID" is a technical term defined in OpenID Federation 1.0.

        Parameters:
        used - true to indicate that the entity ID of the client was used when the request for the access token was made.
        Since:
        3.37, Authlete 2.3
        See Also:
        OpenID Federation 1.0

      • getUserInfoClaims

        public String getUserInfoClaims()
        Get 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 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.

        Returns:
        The value of the "userinfo" property in the "claims" in JSON format.
        Since:
        2.64

      • setUserInfoClaims

        public 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.
        Parameters:
        userInfoClaims - The value of the "userinfo" property in the "claims" in JSON format.
        Since:
        2.64

      • getTransformedClaims

        public 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.
        Returns:
        The value of the "transformed_claims" property in the "claims" in JSON format.
        Since:
        3.8
        See Also:
        OpenID Connect Advanced Syntax for Claims (ASC) 1.0

      • setTransformedClaims

        public 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.
        Parameters:
        transformedClaims - The value of the "transformed_claims" property in the "claims" in JSON format.
        Since:
        3.8
        See Also:
        OpenID Connect Advanced Syntax for Claims (ASC) 1.0

      • getRequestedClaimsForTx

        public String[] getRequestedClaimsForTx()
        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 (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.

        Returns:
        Names of claims that are requested indirectly by "transformed claims"
        Since:
        3.8
        See Also:
        OpenID Connect Advanced Syntax for Claims (ASC) 1.0

      • getRequestedVerifiedClaimsForTx

        public StringArray[] getRequestedVerifiedClaimsForTx()
        Get names of verified 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": {
     "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 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 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 requestedVerifiedClaimsForTx 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.

        Returns:
        Names of verified claims that are requested indirectly by "transformed claims"
        Since:
        3.8
        See Also:
        OpenID Connect Advanced Syntax for Claims (ASC) 1.0, OpenID Connect for Identity Assurance 1.0

      • getServiceAttributes

        public Pair[] getServiceAttributes()
        Get the attributes of the service that the client application belongs to.

        This property is available since Authlete 2.2.

        Returns:
        The attributes of the service.
        Since:
        2.88

      • setServiceAttributes

        public void setServiceAttributes​(Pair[] attributes)
        Set the attributes of the service that the client application belongs to.

        This property is available since Authlete 2.2.

        Parameters:
        attributes - The attributes of the service.
        Since:
        2.88

      • getClientAttributes

        public Pair[] getClientAttributes()
        Get the attributes of the client that the access token has been issued to.

        This property is available since Authlete 2.2.

        Returns:
        The attributes of the client.
        Since:
        2.88

      • setClientAttributes

        public void setClientAttributes​(Pair[] attributes)
        Set the attributes of the client that the access token has been issued to.

        This property is available since Authlete 2.2.

        Parameters:
        attributes - The attributes of the client.
        Since:
        2.88

      • getDpopNonce

        public String getDpopNonce()
        Get the expected nonce value for DPoP proof JWT, which should be used as the value of the DPoP-Nonce HTTP header.

        When this response parameter is not null, the implementation of the userinfo endpoint should add the DPoP-Nonce HTTP header in the response from the endpoint to the client application, using the value of this response parameter as the value of the HTTP header. 

         DPoP-Nonce: (The value of this dpopNonce response parameter)
        Returns:
        The expected nonce value for DPoP proof JWT.
        Since:
        3.82, Authlete 3.0
        See Also:
        RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP)

      • setDpopNonce

        public void setDpopNonce​(String dpopNonce)
        Set the expected nonce value for DPoP proof JWT, which should be used as the value of the DPoP-Nonce HTTP header.

        When this response parameter is not null, the implementation of the userinfo endpoint should add the DPoP-Nonce HTTP header in the response from the endpoint to the client application, using the value of this response parameter as the value of the HTTP header. 

         DPoP-Nonce: (The value of this dpopNonce response parameter)
        Parameters:
        dpopNonce - The expected nonce value for DPoP proof JWT.
        Since:
        3.82, Authlete 3.0
        See Also:
        RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP)