Class TokenCreateRequest

  • All Implemented Interfaces:
    Serializable

    public class TokenCreateRequest
    extends Object
    implements Serializable
    Request to Authlete's /auth/token/create API.

    The API is used to create an arbitrary access token in a special way that is different from standard grant flows.

    grantType (REQUIRED)

    The grant type for a newly created access token. One of the following. REFRESH_TOKEN is not allowed.

    1. AUTHORIZATION_CODE
    2. IMPLICIT
    3. PASSWORD
    4. CLIENT_CREDENTIALS
    5. CIBA (Authlete 2.1 onwards)
    6. DEVICE_CODE (Authlete 2.1 onwards)
    7. TOKEN_EXCHANGE (Authlete 2.3 onwards)
    8. JWT_BEARER (Authlete 2.3 onwards)
    9. PRE_AUTHORIZED_CODE (Authlete 3.0 onwards)

    When grantType is either IMPLICIT or CLIENT_CREDENTIALS, a refresh token is not issued.

    clientId (REQUIRED)

    The ID of the client application which will be associated with a newly created access token.

    subject (CONDITIONALLY REQUIRED)

    The subject (= unique identifier) of the user who will be associated with a newly created access token. This parameter is ignored when the grant type is CLIENT_CREDENTIALS. This parameter is optional when the grant type is JWT_BEARER. In other cases, this parameter is required. When specified, the value must consist of only ASCII characters and its length must not exceed 100.

    scopes (OPTIONAL)

    The scopes which will be associated with a newly created access token. Scopes that are not supported by the service cannot be specified and requesting them will cause an error.

    accessTokenDuration (OPTIONAL)

    The duration of a newly created access token in seconds. If the value is 0, the duration is determined according to the settings of the service.

    refreshTokenDuration (OPTIONAL)

    The duration of a newly created refresh token in seconds. If the value is 0, the duration is determined according to the settings of the service.

    A refresh token is not created (1) if the service does not support REFRESH_TOKEN, or (2) if the specified grant type is either IMPLICIT or CLIENT_CREDENTIALS.

    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

    clientIdAliasUsed (OPTIONAL)

    A boolean request parameter which indicates whether to emulate that the client ID alias is used instead of the original numeric client ID when a new access token is created.

    This has an effect only on the value of the aud claim in a response from UserInfo endpoint. When you access the UserInfo endpoint (which is expected to be implemented using Authlete's /api/auth/userinfo API and /api/auth/userinfo/issue API) with an access token which has been created using Authlete's /api/auth/token/create API with this property ( clientIdAliasUsed) true, the client ID alias is used as the value of the aud claim in a response from the UserInfo endpoint.

    Note that if a client ID alias is not assigned to the client when Authlete's /api/auth/token/create API is called, this property ( clientIdAliasUsed) has no effect (it is always regarded as false).

    accessToken (OPTIONAL)

    The value of the new access token.

    The /api/auth/token/create API generates an access token. Therefore, callers of the API do not have to specify values of newly created access tokens. However, in some cases, for example, if you want to migrate existing access tokens from an old system to Authlete, you may want to specify values of access tokens. In such a case, you can specify the value of a newly created access token by passing a non-null value as the value of accessToken request parameter. The implementation of the /api/auth/token/create uses the value of the accessToken request parameter instead of generating a new value when the request parameter holds a non-null value.

    Note that if the hash value of the specified access token already exists in Authlete's database, the access token cannot be inserted and the /api/auth/token/create API will report an error.

    refreshToken (OPTIONAL)

    The value of the new refresh token.

    The /api/auth/token/create API may generate a refresh token. Therefore, callers of the API do not have to specify values of newly created refresh tokens. However, in some cases, for example, if you want to migrate existing refresh tokens from an old system to Authlete, you may want to specify values of refresh tokens. In such a case, you can specify the value of a newly created refresh token by passing a non-null value as the value of refreshToken request parameter. The implementation of the /api/auth/token/create uses the value of the refreshToken request parameter instead of generating a new value when the request parameter holds a non-null value.

    Note that if the hash value of the specified refresh token already exists in Authlete's database, the refresh token cannot be inserted and the /api/auth/token/create API will report an error.

    accessTokenPersistent (OPTIONAL)

    A boolean request parameter which indicates whether the access token expires or not. By default, all access tokens expire after a period of time determined by their service. If this request parameter is true then the access token will not automatically expire and must be revoked or deleted manually at the service.

    If this request parameter is true, the accessTokenDuration request parameter is ignored.

    certificateThumbprint (OPTIONAL)

    The thumbprint of the MTLS certificate bound to this token. If this field is set, a certificate with the corresponding value MUST be presented with the access token when it is used by a client.

    dpopKeyThumbprint (OPTIONAL)

    The thumbprint of the public key used for DPoP presentation of this token. If this field is set, a DPoP proof signed with the corresponding private key MUST be presented with the access token when it is used by a client. Additionally, the token's token_type will be set to 'DPoP'.

    authorizationDetails (OPTIONAL)

    The value of the authorization_details to associate with the token. Can be null.

    resources (OPTIONAL)

    The value of the resources to associate with the token. Can be null.

    forExternalAttachment (OPTIONAL)

    A boolean flag which indicates whether the access token is for an external attachment. See External Attachments of OpenID Connect for Identity Assurance 1.0 for details about external attachments.

    Since:
    1.13
    See Also:
    TokenCreateResponse, Serialized Form
    • Constructor Detail

      • TokenCreateRequest

        public TokenCreateRequest()
    • Method Detail

      • getGrantType

        public GrantType getGrantType()
        Get the grant type for a newly created access token.
        Returns:
        Grant type.
      • setGrantType

        public TokenCreateRequest setGrantType​(GrantType grantType)
        Set the grant type for a newly created access token.
        Parameters:
        grantType - Grant type.
        Returns:
        this object.
      • getClientId

        public long getClientId()
        Get the client ID that will be associated with a newly created access token.
        Returns:
        Client ID.
      • setClientId

        public TokenCreateRequest setClientId​(long clientId)
        Set the client ID that will be associated with a newly created access token.
        Parameters:
        clientId - Client ID.
        Returns:
        this object.
      • getSubject

        public String getSubject()
        Get the subject (= unique identifier) of the user who will be associated with a newly created access token.
        Returns:
        The subject of the user.
      • setSubject

        public TokenCreateRequest setSubject​(String subject)
        Set the subject (= unique identifier) of the user who will be associated with a newly created access token.
        Parameters:
        subject - The subject of the user.
        Returns:
        this object.
      • getScopes

        public String[] getScopes()
        Get the scopes that will be associated with a newly created access token.
        Returns:
        Scopes.
      • setScopes

        public TokenCreateRequest setScopes​(String[] scopes)
        Set the scopes that will be associated with a newly created access token.
        Parameters:
        scopes - Scopes.
        Returns:
        this object.
      • getAccessTokenDuration

        public long getAccessTokenDuration()
        Get the duration of a newly created access token in seconds. 0 means that the duration will be determined according to the settings of the service.
        Returns:
        The duration of a newly created access token.
      • setAccessTokenDuration

        public TokenCreateRequest setAccessTokenDuration​(long accessTokenDuration)
        Set the duration of a newly created access token in seconds. 0 means that the duration will be determined according to the settings of the service.
        Parameters:
        accessTokenDuration - The duration of a newly created access token.
        Returns:
        this object.
      • getRefreshTokenDuration

        public long getRefreshTokenDuration()
        Get the duration of a newly created refresh token in seconds. 0 means that the duration will be determined according to the settings of the service.
        Returns:
        The duration of a newly created refresh token.
      • setRefreshTokenDuration

        public TokenCreateRequest setRefreshTokenDuration​(long refreshTokenDuration)
        Set the duration of a newly created refresh token in seconds. 0 means that the duration will be determined according to the settings of the service.
        Parameters:
        refreshTokenDuration - The duration of a newly created refresh token.
        Returns:
        this object.
      • 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 TokenCreateRequest 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
      • isClientIdAliasUsed

        public boolean isClientIdAliasUsed()
        Get the flag which indicates whether to emulate that the client ID alias is used instead of the original numeric client ID when a new access token is created.

        This has an effect only on the value of the aud claim in a response from UserInfo endpoint. When you access the UserInfo endpoint (which is expected to be implemented using Authlete's /api/auth/userinfo API and /api/auth/userinfo/issue API) with an access token which has been created using Authlete's /api/auth/token/create API with this property ( clientIdAliasUsed) true, the client ID alias is used as the value of the aud claim in a response from the UserInfo endpoint.

        Note that if a client ID alias is not assigned to the client when Authlete's /api/auth/token/create API is called, this property ( clientIdAliasUsed) has no effect (it is always regarded as false).

        Note that clientIdAliasUsed and clientEntityIdUsed are mutually exclusive.

        Returns:
        true to emulate that the client ID alias is used when a new access token is created.
        Since:
        2.3
      • setClientIdAliasUsed

        public TokenCreateRequest setClientIdAliasUsed​(boolean used)
        Set the flag which indicates whether to emulate that the client ID alias is used instead of the original numeric client ID when a new access token is created.

        This has an effect only on the value of the aud claim in a response from UserInfo endpoint. When you access the UserInfo endpoint (which is expected to be implemented using Authlete's /api/auth/userinfo API and /api/auth/userinfo/issue API) with an access token which has been created using Authlete's /api/auth/token/create API with this property ( clientIdAliasUsed) true, the client ID alias is used as the value of the aud claim in a response from the UserInfo endpoint.

        Note that if a client ID alias is not assigned to the client when Authlete's /api/auth/token/create API is called, this property ( clientIdAliasUsed) has no effect (it is always regarded as false).

        Note that clientIdAliasUsed and clientEntityIdUsed are mutually exclusive.

        Parameters:
        used - true to emulate that the client ID alias is used when a new access token is created.
        Returns:
        this object.
        Since:
        2.3
      • isClientEntityIdUsed

        public boolean isClientEntityIdUsed()
        Get the flag which indicates whether to emulate that the entity ID is used as a client ID when a new access token is created.

        This has an effect only on the value of the aud claim in a response from UserInfo endpoint. When you access the UserInfo endpoint (which is expected to be implemented using Authlete's /auth/userinfo API and /auth/userinfo/issue API) with an access token which has been created using Authlete's /auth/token/create API with this property (clientEntityIdUsed) true, the entity ID of the client is used as the value of the aud claim in a response from the UserInfo endpoint.

        Note that if an entity ID is not assigned to the client when Authlete's /auth/token/create API is called, this property (clientEntityIdUsed) has no effect (it is always regarded as false).

        Note that clientIdAliasUsed and clientEntityIdUsed are mutually exclusive.

        Returns:
        true to emulate that the entity ID is used when a new access token is created.
        Since:
        3.37, Authlete 2.3
      • setClientEntityIdUsed

        public TokenCreateRequest setClientEntityIdUsed​(boolean used)
        Set the flag which indicates whether to emulate that the entity ID is used as a client ID when a new access token is created.

        This has an effect only on the value of the aud claim in a response from UserInfo endpoint. When you access the UserInfo endpoint (which is expected to be implemented using Authlete's /auth/userinfo API and /auth/userinfo/issue API) with an access token which has been created using Authlete's /auth/token/create API with this property (clientEntityIdUsed) true, the entity ID of the client is used as the value of the aud claim in a response from the UserInfo endpoint.

        Note that if an entity ID is not assigned to the client when Authlete's /auth/token/create API is called, this property (clientEntityIdUsed) has no effect (it is always regarded as false).

        Note that clientIdAliasUsed and clientEntityIdUsed are mutually exclusive.

        Parameters:
        used - true to emulate that the entity ID is used when a new access token is created.
        Returns:
        this object.
        Since:
        3.37, Authlete 2.3
      • getAccessToken

        public String getAccessToken()
        Get the access token.

        When this method returns a non-null value, the implementation of /api/auth/token/create uses the value instead of generating a new one. See the description of setAccessToken(String) for details.

        Returns:
        The value of the access token. In normal cases, null is returned.
        Since:
        2.6
        See Also:
        setAccessToken(String)
      • setAccessToken

        public TokenCreateRequest setAccessToken​(String accessToken)
        Set the access token.

        The /api/auth/token/create API generates an access token. Therefore, callers of the API do not have to specify values of newly created access tokens. However, in some cases, for example, if you want to migrate existing access tokens from an old system to Authlete, you may want to specify values of access tokens. In such a case, you can specify the value of a newly created access token by passing a non-null value as the value of accessToken request parameter. The implementation of the /api/auth/token/create uses the value of the accessToken request parameter instead of generating a new value when the request parameter holds a non-null value.

        Note that if the hash value of the specified access token already exists in Authlete's database, the access token cannot be inserted and the /api/auth/token/create API will report an error.

        Parameters:
        accessToken - The value of the access token. If a non-null value is specified, the implementation of /api/auth/token/create API will use the value instead of generating a new one. Because Authlete does not store the value of the access token into its database (Authlete stores the hash value of the access token only), any value is accepted as the value of this accessToken request parameter.
        Returns:
        this object.
        Since:
        2.6
      • getRefreshToken

        public String getRefreshToken()
        Get the refresh token.

        When this method returns a non-null value, the implementation of /api/auth/token/create uses the value instead of generating a new one. See the description of setRefreshToken(String) for details.

        Returns:
        The value of the refresh token. In normal cases, null is returned.
        Since:
        2.6
        See Also:
        setRefreshToken(String)
      • setRefreshToken

        public TokenCreateRequest setRefreshToken​(String refreshToken)
        Set the refresh token.

        The /api/auth/token/create API may generate a refresh token. Therefore, callers of the API do not have to specify values of newly created refresh tokens. However, in some cases, for example, if you want to migrate existing refresh tokens from an old system to Authlete, you may want to specify values of refresh tokens. In such a case, you can specify the value of a newly created refresh token by passing a non-null value as the value of refreshToken request parameter. The implementation of the /api/auth/token/create uses the value of the refreshToken request parameter instead of generating a new value when the request parameter holds a non-null value.

        Note that if the hash value of the specified refresh token already exists in Authlete's database, the refresh token cannot be inserted and the /api/auth/token/create API will report an error.

        Parameters:
        refreshToken - The value of the refresh token. If a non-null value is specified, the implementation of /api/auth/token/create API will use the value instead of generating a new one. Because Authlete does not store the value of the refresh token into its database (Authlete stores the hash value of the refresh token only), any value is accepted as the value of this refreshToken request parameter.
        Returns:
        this object.
        Since:
        2.6
      • isAccessTokenPersistent

        public boolean isAccessTokenPersistent()
        Get whether the access token expires or not. By default, all access tokens expire after a period of time determined by their service. If this request parameter is true then the access token will not automatically expire and must be revoked or deleted manually at the service.

        If this request parameter is true, the accessTokenDuration request parameter is ignored.

        Returns:
        false if the access token expires (default). true if the access token does not expire.
        Since:
        2.30
      • setAccessTokenPersistent

        public TokenCreateRequest setAccessTokenPersistent​(boolean persistent)
        Set whether the access token expires or not. By default, all access tokens expire after a period of time determined by their service. If this request parameter is true then the access token will not automatically expire and must be revoked or deleted manually at the service.

        If this request parameter is true, the accessTokenDuration request parameter is ignored.

        Parameters:
        persistent - false to make the access token expire (default). true to make the access token be persistent.
        Returns:
        this object.
        Since:
        2.30
      • getCertificateThumbprint

        public String getCertificateThumbprint()
        Get the thumbprint of the MTLS certificate bound to this token. If this field is set, a certificate with the corresponding value MUST be presented with the access token when it is used by a client.
        Returns:
        The SHA256 certificate thumbprint, base64url encoded.
        Since:
        2.72
      • setCertificateThumbprint

        public TokenCreateRequest setCertificateThumbprint​(String certificateThumbprint)
        Set the thumbprint of the MTLS certificate bound to this token. If this field is set, a certificate with the corresponding value MUST be presented with the access token when it is used by a client.
        Parameters:
        certificateThumbprint - The SHA256 certificate thumbprint, base64url encoded.
        Returns:
        this object.
        Since:
        2.72
      • getDpopKeyThumbprint

        public String getDpopKeyThumbprint()
        Get the thumbprint of the public key used for DPoP presentation of this token. If this field is set, a DPoP proof signed with the corresponding private key MUST be presented with the access token when it is used by a client. Additionally, the token's token_type will be set to 'DPoP'.
        Returns:
        The JWK public key thumbprint.
        Since:
        2.72
      • setDpopKeyThumbprint

        public TokenCreateRequest setDpopKeyThumbprint​(String dpopKeyThumbprint)
        Set the thumbprint of the public key used for DPoP presentation of this token. If this field is set, a DPoP proof signed with the corresponding private key MUST be presented with the access token when it is used by a client. Additionally, the token's token_type will be set to 'DPoP'.
        Parameters:
        dpopKeyThumbprint - The JWK public key thumbprint.
        Returns:
        this object.
        Since:
        2.72
      • getAuthorizationDetails

        public AuthzDetails getAuthorizationDetails()
        Get the authorization details. This represents the value of the "authorization_details" request parameter which is defined in "OAuth 2.0 Rich Authorization Requests".
        Returns:
        Authorization details.
        Since:
        2.99
      • setAuthorizationDetails

        public TokenCreateRequest setAuthorizationDetails​(AuthzDetails authorizationDetails)
        Set the authorization details. This represents the value of the "authorization_details" request parameter which is defined in "OAuth 2.0 Rich Authorization Requests".
        Parameters:
        authorizationDetails - Authorization details.
        Returns:
        this object.
        Since:
        2.99
      • getResources

        public URI[] getResources()
        Get the resources. This represents the value of one or more "resource" request parameters which is defined in "RFC8707 Resource Indicators for OAuth 2.0".
        Returns:
        Array of resource URIs.
        Since:
        2.99
      • setResources

        public TokenCreateRequest setResources​(URI[] resources)
        Get the resources. This represents the value of one or more "resource" request parameters which is defined in "RFC8707 Resource Indicators for OAuth 2.0".
        Parameters:
        resources - Array of resource URIs.
        Returns:
        this object.
        Since:
        2.99
      • setForExternalAttachment

        public TokenCreateRequest setForExternalAttachment​(boolean forExternalAttachment)
        Set the flag which indicates whether the access token is for an external attachment.
        Parameters:
        forExternalAttachment - true to indicate that the access token is for an external attachment.
        Returns:
        this object.
        Since:
        3.16
        See Also:
        OpenID Connect for Identity Assurance 1.0, External Attachments
      • 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 TokenCreateRequest 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
      • getAcr

        public String getAcr()
        Get the Authentication Context Class Reference of the user authentication that the authorization server performed during the course of issuing the access token.

        Note that this parameter is ignored in cases where the subject parameter is missing or ignored.

        Returns:
        The Authentication Context Class Reference.
        Since:
        3.40, Authlete 2.3
        See Also:
        RFC 9470 OAuth 2.0 Step Up Authentication Challenge Protocol
      • setAcr

        public TokenCreateRequest setAcr​(String acr)
        Set the Authentication Context Class Reference of the user authentication that the authorization server performed during the course of issuing the access token.

        Note that this parameter is ignored in cases where the subject parameter is missing or ignored.

        Parameters:
        acr - The Authentication Context Class Reference.
        Returns:
        this object.
        Since:
        3.40, Authlete 2.3
        See Also:
        RFC 9470 OAuth 2.0 Step Up Authentication Challenge Protocol
      • getAuthTime

        public long getAuthTime()
        Get the time when the user authentication was performed during the course of issuing the access token.

        Note that this parameter is ignored in cases where the subject parameter is missing or ignored.

        Returns:
        The time of the user authentication in seconds since the Unix epoch.
        Since:
        3.40, Authlete 2.3
        See Also:
        RFC 9470 OAuth 2.0 Step Up Authentication Challenge Protocol
      • setAuthTime

        public TokenCreateRequest setAuthTime​(long authTime)
        Set the time when the user authentication was performed during the course of issuing the access token.

        Note that this parameter is ignored in cases where the subject parameter is missing or ignored.

        Parameters:
        authTime - The time of the user authentication in seconds since the Unix epoch. Must not be negative.
        Returns:
        this object.
        Since:
        3.40, Authlete 2.3
        See Also:
        RFC 9470 OAuth 2.0 Step Up Authentication Challenge Protocol