Package com.authlete.common.dto

Class TokenRequest

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

    OAuth 2.0 token request parameters which are the request parameters that the OAuth 2.0 token endpoint of the service implementation received from the client application.

    The value of "parameters" is the entire entity body (which is formatted in application/x-www-form-urlencoded) of the request from the client application.

    clientId (OPTIONAL)

    The client ID extracted from Authorization header of the token request from the client application.

    If the token endpoint of the service implementation supports Basic Authentication as a means of client authentication, and the request from the client application contained its client ID in Authorization header, the value should be extracted and set to this parameter.

    clientSecret (OPTIONAL)

    The client secret extracted from Authorization header of the token request from the client application.

    If the token endpoint of the service implementation supports Basic Authentication as a means of client authentication, and the request from the client application contained its client secret in Authorization header, the value should be extracted and set to this parameter.

    clientCertificate (OPTIONAL)

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

    clientCertificatePath (OPTIONAL)

    The certificate path presented by the client during client authentication. The certificates are strings in PEM format.

    properties (OPTIONAL)

    Extra properties to associate with an access token. Note that properties parameter is accepted only when Content-Type of the request is application/json, so don't use application/x-www-form-urlencoded if you want to specify properties.

    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 token request. In normal cases, the value should be "POST". If omitted, "POST" is used as the default value. See RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP) for details.

    htu (OPTIONAL)

    The URL of the token endpoint. If omitted, the tokenEndpoint property of Service is used as the default value. See RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP) for details.

    jwtAtClaims (OPTIONAL; Authlete 2.3 onwards)

    Additional claims in JSON object format that are added to the payload part of the JWT access token. See the description of getJwtAtClaims() for details.

    accessToken (OPTIONAL)

    The representation of an access token that may be issued as a result of the Authlete API call. See getAccessToken() for details.

    accessTokenDuration (OPTIONAL)

    The duration of the access token that may be issued as a result of the Authlete API call. See getAccessTokenDuration() for details.

    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/token API with this dpopNonceRequired parameter true will force the Authlete API to check whether the DPoP proof JWT includes the expected nonce value.

    An entity body of a token request may contain the client ID (client_id) and the client secret (client_secret) along with other request parameters as described in RFC 6749, 2.3.1. Client Password. If the client credentials are contained in both Authorization header and the entity body, they must be identical. Otherwise, Authlete's /auth/token API generates an error (it's not a service error but a client error).

    See Also:
    Serialized Form

    • Constructor Detail

      • TokenRequest

        public TokenRequest()

    • Method Detail

      • getParameters

        public String getParameters()
        Get the value of parameters which are the request parameters that the OAuth 2.0 token endpoint of the service implementation received from the client application.

      • setParameters

        public TokenRequest setParameters​(String parameters)
        Set the value of parameters which are the request parameters that the OAuth 2.0 token endpoint of the service implementation received from the client application.

      • setParameters

        public TokenRequest setParameters​(Map<String,​String[]> parameters)
        Set the value of parameters which are the request parameters that the OAuth 2.0 token endpoint of the service implementation received from the client application.

        This method converts the given map into a string in x-www-form-urlencoded and passes it to setParameters(String) method.

        Parameters:
        parameters - Request parameters.
        Returns:
        this object.
        Since:
        1.24

      • getClientId

        public String getClientId()
        Get the client ID extracted from Authorization header of the token request from the client application.

      • setClientId

        public TokenRequest setClientId​(String clientId)
        Set the client ID extracted from Authorization header of the token request from the client application.

      • getClientSecret

        public String getClientSecret()
        Get the client secret extracted from Authorization header of the token request from the client application.

      • setClientSecret

        public TokenRequest setClientSecret​(String clientSecret)
        Set the client secret extracted from Authorization header of the token request from the client application.

      • getClientCertificate

        public String getClientCertificate()
        Get the client certificate from the MTLS of the token request from the client application.
        Since:
        2.12

      • setClientCertificate

        public TokenRequest setClientCertificate​(String clientCertificate)
        Set the client certificate from the MTLS of the token request from the client application.
        Since:
        2.12

      • getProperties

        public Property[] getProperties()
        Get the extra properties to associate with an access token which may be issued by this request.
        Returns:
        Extra properties.
        Since:
        1.30

      • setProperties

        public TokenRequest setProperties​(Property[] properties)
        Set extra properties to associate with an access token which may be issued by this request.

        If the value of grant_type parameter contained in the token request from the client application is authorization_code, properties set by this method will be added as the extra properties of a newly created access token. The extra properties specified when the authorization code was issued (using AuthorizationIssueRequest.setProperties(Property[])) will also be used, but their values will be overwritten if the extra properties set by this method have the same keys. In other words, extra properties contained in this request will be merged into existing extra properties which are associated with the authorization code.

        Otherwise, if the value of grant_type parameter contained in the token request from the client application is refresh_token, properties set by this method will be added to the existing extra properties of the corresponding access token. Extra properties having the same keys will be overwritten in the same manner as the case of grant_type=authorization_code.

        Otherwise, if the value of grant_type parameter contained in the token request from the client application is client_credentials, properties set by this method will be used simply as extra properties of a newly created access token. Because Client Credentials flow does not have a preceding authorization request, merging extra properties will not be performed. This is different from the cases of grant_type=authorization_code and grant_type=refresh_token.

        In other cases (grant_type=password), properties set by this method will not be used. When you want to associate extra properties with an access token which is issued using Resource Owner Password Credentials flow, use TokenIssueRequest.setProperties(Property[]) method instead.

        The argument properties is an array of properties. Each property must be a pair of a string key and a string value. That is, each property must be a string array of size 2. The key must not be null or an empty string, but the value may be.

        Keys of extra properties will be used as labels of top-level entries in a JSON response containing an access token which is returned from an authorization server. An example is example_parameter, which you can find in 5.1. Successful Response in RFC 6749. The following code snippet is an example to set one extra property having example_parameter as its key and example_value as its value. 

         Property[] properties = { new Property("example_parameter", "example_value") };
 request.setProperties(properties);

        Keys listed below should not be used and they would be ignored on the server side even if they were used. It's because they are reserved in RFC 6749 and OpenID Connect Core 1.0.

        • access_token
        • token_type
        • expires_in
        • refresh_token
        • scope
        • error
        • error_description
        • error_uri
        • id_token

        Note that there is an upper limit on the total size of extra properties. On the server side, the properties will be (1) converted to a multidimensional string array, (2) converted to JSON, (3) encrypted by AES/CBC/PKCS5Padding, (4) encoded by base64url, and then stored into the database. The length of the resultant string must not exceed 65,535 in bytes. This is the upper limit, but we think it is big enough.

        Parameters:
        properties - Extra properties.
        Returns:
        this object.
        Since:
        1.30

      • getClientCertificatePath

        public String[] getClientCertificatePath()
        Get the certificate path presented by the client during client authentication. These certificates are strings in PEM format.
        Returns:
        The client certificate path as an array of strings in PEM format.
        Since:
        2.15

      • setClientCertificatePath

        public TokenRequest setClientCertificatePath​(String[] clientCertificatePath)
        Set the certificate path presented by the client during client authentication. These certificates are strings in PEM format.
        Parameters:
        clientCertificatePath - The client certificate path as an array of strings in PEM format.
        Returns:
        this object.
        Since:
        2.15

      • getJwtAtClaims

        public String getJwtAtClaims()
        Get the additional claims in JSON object format that are added to the payload part of the JWT access token.

        This request parameter has a meaning only when the format of access tokens issued by this service is JWT. In other words, it has a meaning only when the accessTokenSignAlg property of the Service holds a non-null value. See the description of the getAccessTokenSignAlg() method for details.

        Note that this jwtAtClaims request parameter to the /auth/token API works only in the client credentials flow (RFC 6749 Section 4.4). For other flows, additional claims need to be passed to Authlete through other APIs. For example, to embed additional claims in an access token that is issued by the authorization code flow (RFC 6749 Section 4.1), the jwtAtClaims request parameter of the /auth/authorization/issue API has to be used.

        Returns:
        Additional claims that are added to the payload part of the JWT access token.
        Since:
        3.35, Authlete 2.3

      • setJwtAtClaims

        public TokenRequest setJwtAtClaims​(String claims)
        Set the additional claims in JSON object format that are added to the payload part of the JWT access token.

        This request parameter has a meaning only when the format of access tokens issued by this service is JWT. In other words, it has a meaning only when the accessTokenSignAlg property of the Service holds a non-null value. See the description of the getAccessTokenSignAlg() method for details.

        Note that this jwtAtClaims request parameter to the /auth/token API works only in the client credentials flow (RFC 6749 Section 4.4). For other flows, additional claims need to be passed to Authlete through other APIs. For example, to embed additional claims in an access token that is issued by the authorization code flow (RFC 6749 Section 4.1), the jwtAtClaims request parameter of the /auth/authorization/issue API has to be used.

        Parameters:
        claims - Additional claims that are added to the payload part of the JWT access token.
        Returns:
        this object.
        Since:
        3.35, Authlete 2.3

      • getAccessToken

        public String getAccessToken()
        Get the representation of an access token that may be issued as a result of the Authlete API call.

        Basically, it is the Authlete server's role to generate an access token. However, some systems may have inflexible restrictions on the format of access tokens. Such systems may use this accessToken request parameter to specify the representation of an access token by themselves instead of leaving the access token generation task to the Authlete server.

        Usually, the Authlete server (1) generates a random 256-bit value, (2) base64url-encodes the value into a 43-character string, and (3) uses the resultant string as the representation of an access token. The Authlete implementation is written on the assumption that the 256-bit entropy is big enough. Therefore, make sure that the entropy of the value of the accessToken request parameter is big enough, too.

        The entropy does not necessarily have to be equal to or greater than 256 bits. For example, 192-bit random values (which will become 32-character strings when encoded by base64url) may be enough. However, note that if the entropy is too low, access token string values will collide and Authlete API calls will fail.

        When no access token is generated as a result of the Authlete API call, this accessToken request parameter is not used.

        Returns:
        The representation of an access token that may be issued as a result of the Authlete API call.
        Since:
        3.24, Authlete 2.2.27

      • setAccessToken

        public TokenRequest setAccessToken​(String accessToken)
        Set the representation of an access token that may be issued as a result of the Authlete API call.

        Basically, it is the Authlete server's role to generate an access token. However, some systems may have inflexible restrictions on the format of access tokens. Such systems may use this accessToken request parameter to specify the representation of an access token by themselves instead of leaving the access token generation task to the Authlete server.

        Usually, the Authlete server (1) generates a random 256-bit value, (2) base64url-encodes the value into a 43-character string, and (3) uses the resultant string as the representation of an access token. The Authlete implementation is written on the assumption that the 256-bit entropy is big enough. Therefore, make sure that the entropy of the value of the accessToken request parameter is big enough, too.

        The entropy does not necessarily have to be equal to or greater than 256 bits. For example, 192-bit random values (which will become 32-character strings when encoded by base64url) may be enough. However, note that if the entropy is too low, access token string values will collide and Authlete API calls will fail.

        When no access token is generated as a result of the Authlete API call, this accessToken request parameter is not used.

        Parameters:
        accessToken - The representation of an access token that may be issued as a result of the Authlete API call.
        Returns:
        this object.
        Since:
        3.24, Authlete 2.2.27

      • getAccessTokenDuration

        public long getAccessTokenDuration()
        Get the duration of the access token that may be issued as a result of the Authlete API call.

        When this request parameter holds a positive integer, it is used as the duration of the access token. In other cases, this request parameter is ignored.

        Returns:
        The duration of the access token in seconds.
        Since:
        3.64, Authlete 2.2.41, Authlete 2.3.5, Authlete 3.0

      • setAccessTokenDuration

        public TokenRequest setAccessTokenDuration​(long duration)
        Set the duration of the access token that may be issued as a result of the Authlete API call.

        When this request parameter holds a positive integer, it is used as the duration of the access token. In other cases, this request parameter is ignored.

        Parameters:
        duration - The duration of the access token in seconds.
        Returns:
        this request parameter.
        Since:
        3.64, Authlete 2.2.41, Authlete 2.3.5, Authlete 3.0

      • 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/token API checks if the DPoP proof JWT includes the expected nonce value. In this case, the response from the /auth/token 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/token 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 TokenRequest 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/token API checks if the DPoP proof JWT includes the expected nonce value. In this case, the response from the /auth/token 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/token 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)