Package com.authlete.common.dto

Class TokenIssueRequest

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

    The ticket issued by Authlete's /auth/token API to the service implementation. It is the value of "ticket" contained in the response from Authlete's /auth/token API (TokenResponse).

    subject (REQUIRED)

    The subject (= unique identifier) of the authenticated user.

    properties (OPTIONAL)

    Extra properties to associate with a newly created 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

    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; Authlete 2.2.27 onwards)

    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.

    subject request parameter was added as a required parameter on version 1.13.

    Author:
    Takahiko Kawasaki
    See Also:
    TokenResponse, Serialized Form

    • Constructor Detail

      • TokenIssueRequest

        public TokenIssueRequest()

    • Method Detail

      • getTicket

        public String getTicket()
        Get the value of "ticket" which is the ticket issued by Authlete's /auth/token API to the service implementation.
        Returns:
        The ticket.

      • setTicket

        public TokenIssueRequest setTicket​(String ticket)
        Set the value of "ticket" which is the ticket issued by Authlete's /auth/token API to the service implementation.
        Parameters:
        ticket - The ticket.
        Returns:
        this object.

      • getSubject

        public String getSubject()
        Get the value of "subject" which is the unique identifier of the authenticated user.
        Returns:
        The subject of the authenticated user.
        Since:
        1.13

      • setSubject

        public TokenIssueRequest setSubject​(String subject)
        Set the value of "subject" which is the unique identifier of the authenticated user.
        Parameters:
        subject - The subject of the authenticated user.
        Returns:
        this object.
        Since:
        1.13

      • getProperties

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

      • setProperties

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

        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

      • 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.

        Returns:
        Additional claims that are added to the payload part of the JWT access token.
        Since:
        3.23

      • setJwtAtClaims

        public TokenIssueRequest 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.

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

      • 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 TokenIssueRequest 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.65, Authlete 2.2.41, Authlete 2.3.5, Authlete 3.0

      • setAccessTokenDuration

        public TokenIssueRequest 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.65, Authlete 2.2.41, Authlete 2.3.5, Authlete 3.0