Package com.authlete.common.dto

Class UserInfoRequest

  • All Implemented Interfaces:
    Serializable
    public class UserInfoRequest
extends Object
implements Serializable
    Request to Authlete's /auth/userinfo API.
    token (REQUIRED)

    An access token to get user information.

    clientCertificate (OPTIONAL)

    The client certificate from the MTLS of the userinfo request from the client application. See RFC 8705 (OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens) for details.

    dpop (OPTIONAL)

    The value of the DPoP HTTP header. See RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP) for details.

    htm (OPTIONAL)

    The HTTP method of the userinfo request. In normal cases, the value should be either "GET" or "POST". See RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP) for details.

    htu (OPTIONAL)

    The URL of the userinfo endpoint, without query or fragment components. If omitted, the userInfoEndpoint property of Service is used as the default value. See RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP) for details.

    targetUri (OPTIONAL; Authlete 2.3 onwards)

    The full URL of the userinfo request, including the query part, if any.

    headers (OPTIONAL; Authlete 2.3 onwards)

    The HTTP headers included in the userinfo request. They are used to compute component values, which will be part of the signature base for HTTP message signatures.

    requestBodyContained (OPTIONAL; Authlete 2.3 onwards)

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

    dpopNonceRequired (OPTIONAL; Authlete 3.0 onwards)

    The flag indicating whether to require the DPoP proof JWT to include the nonce claim. Even if the service's dpopNonceRequired property is false, calling the /auth/userinfo API with this dpopNonceRequired parameter true will force the Authlete API to check whether the DPoP proof JWT includes the expected nonce value.

    Author:
    Takahiko Kawasaki
    See Also:
    Serialized Form

    • Constructor Detail

      • UserInfoRequest

        public UserInfoRequest()

    • Method Detail

      • getToken

        public String getToken()
        Get the access token which has come along with the userinfo request from the client application.

      • setToken

        public UserInfoRequest setToken​(String token)
        Set the access token which has been issued by Authlete. The access token is the one that has come along with the userinfo request from the client application.

      • getClientCertificate

        public String getClientCertificate()
        Get the client certificate used in the TLS connection established between the client application and the userinfo endpoint.
        Returns:
        The client certificate in PEM format.

      • setClientCertificate

        public UserInfoRequest setClientCertificate​(String certificate)
        Set the 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 RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens for details about the specification of certificate-bound access tokens.

        Parameters:
        certificate - The client certificate in PEM format.
        Returns:
        this object.
        Since:
        2.37

      • getUri

        @Deprecated
public String getUri()
        Deprecated.
        Get the URL of the userinfo endpoint. This field is used to validate the HTTP Message Signature.

        If this parameter is omitted, the userInfoEndpoint property of the Service is used as the default value.

        NOTE: This parameter has been deprecated and replaced with the targetUri parameter.

        Returns:
        The URL of the userinfo endpoint.
        Since:
        3.38, Authlete 2.3

      • setUri

        @Deprecated
public UserInfoRequest setUri​(String uri)
        Deprecated.
        Set the URL of the userinfo endpoint. This field is used to validate the HTTP Message Signature.

        If this parameter is omitted, the userInfoEndpoint property of the Service is used as the default value.

        NOTE: This parameter has been deprecated and replaced with the targetUri parameter.

        Parameters:
        uri - The URL of the userinfo endpoint.
        Returns:
        this object.
        Since:
        3.38, Authlete 2.3

      • getTargetUri

        public URI getTargetUri()
        Get 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.

        Returns:
        The target URI of the userinfo request.
        Since:
        4.12, Authlete 2.3.26
        See Also:
        RFC 9421 HTTP Message Signatures, Section 2.2.2. Target URI

      • setTargetUri

        public UserInfoRequest setTargetUri​(URI targetUri)
        Set 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.

        Parameters:
        targetUri - The target URI of the userinfo request.
        Returns:
        this object.
        Since:
        4.12, Authlete 2.3.26
        See Also:
        RFC 9421 HTTP Message Signatures, Section 2.2.2. Target URI

      • getHeaders

        public Pair[] getHeaders()
        Get the HTTP headers included in the userinfo request. They are used to compute component values, which will be part of the signature base for HTTP message signatures.
        Returns:
        The HTTP headers.
        Since:
        3.38, Authlete 2.3

      • setHeaders

        public UserInfoRequest setHeaders​(Pair[] headers)
        Set the HTTP headers included in the userinfo request. They are used to compute component values, which will be part of the signature base for HTTP message signatures.
        Parameters:
        headers - The HTTP headers.
        Returns:
        this object.
        Since:
        3.38, Authlete 2.3

      • getMessage

        @Deprecated
public String getMessage()
        Deprecated.
        Get the HTTP message body, if present. If provided, this will be used to calculate the expected value of the Content-Digest in the headers of the request covered by the HTTP Message Signature.

        NOTE: This parameter has been deprecated. In exchange, the requestBodyContained parameter has been introduced.

        Returns:
        The HTTP message body.
        Since:
        3.38, Authlete 2.3

      • setMessage

        @Deprecated
public UserInfoRequest setMessage​(String message)
        Deprecated.
        Set the HTTP message body, if present. If provided, this will be used to calculate the expected value of the Content-Digest in the headers of the request covered by the HTTP Message Signature.

        NOTE: This parameter has been deprecated. In exchange, the requestBodyContained parameter has been introduced.

        Parameters:
        message - The HTTP message body.
        Returns:
        this object.
        Since:
        3.38, Authlete 2.3

      • isRequestBodyContained

        public boolean isRequestBodyContained()
        Get 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 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).

        Returns:
        true if the userinfo request contains a request body.
        Since:
        4.12, Authlete 2.3.26

      • setRequestBodyContained

        public UserInfoRequest setRequestBodyContained​(boolean contained)
        Set 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 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).

        Parameters:
        contained - true to indicate that the userinfo request contains a request body.
        Returns:
        this object.
        Since:
        4.12, Authlete 2.3.26

      • isDpopNonceRequired

        public boolean isDpopNonceRequired()
        Get the flag indicating whether to check if the DPoP proof JWT includes the expected nonce value.

        If this request parameter is true or if the service's dpopNonceRequired property (Service.isDpopNonceRequired()) is 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.

        Returns:
        true if the /auth/userinfo API checks whether the DPoP proof JWT includes the expected nonce value, even if the service's dpopNonceRequired property is false.
        Since:
        3.82, Authlete 3.0
        See Also:
        RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP)

      • setDpopNonceRequired

        public UserInfoRequest setDpopNonceRequired​(boolean required)
        Set the flag indicating whether to check if the DPoP proof JWT includes the expected nonce value.

        If this request parameter is true or if the service's dpopNonceRequired property (Service.isDpopNonceRequired()) is 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.

        Parameters:
        required - true to have the /auth/userinfo API check whether the DPoP proof JWT includes the expected nonce value, even if the service's dpopNonceRequired property is false.
        Returns:
        this object.
        Since:
        3.82, Authlete 3.0
        See Also:
        RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP)