Package com.authlete.common.dto

Class TokenUpdateRequest

  • All Implemented Interfaces:
    Serializable
    public class TokenUpdateRequest
extends Object
implements Serializable
    Request to Authlete's /auth/token/update API.

    The API is used to update an existing access token.

    accessToken

    An existing access token.

    accessTokenExpiresAt

    A new date at which the access token will expire in milliseconds since the Unix epoch (1970-01-01). If the accessTokenExpiresAt request parameter is not included in a request or its value is 0 (or negative), the expiration date of the access token is not changed.

    scopes

    A new set of scopes assigned to the access token. Scopes that are not supported by the service and those that the client application associated with the access token is not allowed to request are ignored on the server side. If the scopes request parameter is not included in a request or its value is null, the scopes of the access token are not changed.

    properties

    A new set of properties assigned to the access token. If the properties request parameter is not included in a request or its value is null, the properties of the access token are not changed.

    accessTokenExpiresAtUpdatedOnScopeUpdate

    A boolean request parameter which indicates whether the API attempts to update the expiration date of the access token when the scopes linked to the access token are changed by this request. The default value is false. For more details, see the description of setAccessTokenExpiresAtUpdatedOnScopeUpdate(boolean).

    accessTokenHash

    The hash of the access token value. Used when the hash of the token is known (perhaps from lookup) but the value of the token itself is not.

    The value of the accessToken parameter takes precedence.

    accessTokenValueUpdated

    A boolean request parameter which indicates whether to update the value of the access token in the data store. If this parameter is set to true then a new access token value is generated by the server and returned in the response. The default value is false and the access token's previous value is retained.

    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. If this value is null, the authorization details will not be changed. If this value is set, it will completely replace the authorization details previously set on the token.

    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.34
    See Also:
    TokenUpdateResponse, Serialized Form

    • Constructor Detail

      • TokenUpdateRequest

        public TokenUpdateRequest()

    • Method Detail

      • getAccessToken

        public String getAccessToken()
        Get the access token to update.
        Returns:
        The access token to update.

      • setAccessToken

        public TokenUpdateRequest setAccessToken​(String accessToken)
        Set an existing access token to update.
        Parameters:
        accessToken - An existing access token to update.
        Returns:
        this object.

      • getAccessTokenExpiresAt

        public long getAccessTokenExpiresAt()
        Get the new date at which the access token will expire.
        Returns:
        The new expiration date in milliseconds since the Unix epoch (1970-01-01).

      • setAccessTokenExpiresAt

        public TokenUpdateRequest setAccessTokenExpiresAt​(long expiresAt)
        Set the new date at which the access token will expire.

        If 0 or a negative value is given, the expiration date of the access token is not changed.

        Parameters:
        expiresAt - The new expiration date in milliseconds since the Unix epoch (1970-01-01).
        Returns:
        this object.

      • getRefreshTokenExpiresAt

        public long getRefreshTokenExpiresAt()
        Get the new date at which the refresh token will expire.
        Returns:
        The new expiration date in milliseconds since the Unix epoch (1970-01-01).
        Since:
        3.84

      • setRefreshTokenExpiresAt

        public TokenUpdateRequest setRefreshTokenExpiresAt​(long expiresAt)
        Set the new date at which the refresh token will expire.

        If 0 or a negative value is given, the expiration date of the refresh token is not changed.

        Parameters:
        expiresAt - The new expiration date in milliseconds since the Unix epoch (1970-01-01).
        Returns:
        this object.
        Since:
        3.84

      • getScopes

        public String[] getScopes()
        Get the new set of scopes assigned to the access token.
        Returns:
        The new set of scopes.

      • setScopes

        public TokenUpdateRequest setScopes​(String[] scopes)
        Set a new set of scopes assigned to the access token.

        If null is given, the scope set associated with the access token is not changed.

        Parameters:
        scopes - A new set of scopes. null means that scopes are not changed.
        Returns:
        this object.

      • getProperties

        public Property[] getProperties()
        Get a new set of properties assigned to the access token.
        Returns:
        A new set of properties.

      • setProperties

        public TokenUpdateRequest setProperties​(Property[] properties)
        Set a new set of properties assigned to the access token.

        If null is given, the property set associated with the access token is not changed.

        Parameters:
        properties - A new set of properties. null means that properties are not changed.
        Returns:
        this object.

      • isAccessTokenExpiresAtUpdatedOnScopeUpdate

        public boolean isAccessTokenExpiresAtUpdatedOnScopeUpdate()
        Get the flag which indicates whether /auth/token/update API attempts to update the expiration date of the access token when the scopes linked to the access token are changed by this request.
        Returns:
        The flag which indicates whether /auth/token/update API attempts to update the expiration date of the access token when the scopes linked to the access token are changed by this request.
        Since:
        2.29

      • setAccessTokenExpiresAtUpdatedOnScopeUpdate

        public TokenUpdateRequest setAccessTokenExpiresAtUpdatedOnScopeUpdate​(boolean updated)
        Set the flag which indicates whether /auth/token/update API attempts to update the expiration date of the access token when the scopes linked to the access token are changed by this request. This request parameter is optional and its default value is false. If this request parameter is set to true and all of the following conditions are satisfied, the API performs an update on the expiration date of the access token even if the accessTokenExpiresAt request parameter is not explicitly specified in the request.
        1. The accessTokenExpiresAt request parameter is not included in the request or its value is 0 (or negative).
        2. The scopes linked to the access token are changed by the scopes request parameter in the request.
        3. Any of the new scopes to be linked to the access token has one or more attributes specifying access token duration.

        When multiple access token duration values are found in the attributes of the specified scopes, the smallest value among them is used.

        For more details, see the following examples.

        Example 1.

        Let's say we send the following request to /auth/token/update API 

         {
   "accessToken" : "JDGiiM9PuWT63FIwGjG9eYlGi-aZMq6CQ2IB475JUxs",
   "scopes" : ["read_profile"]
 }

        and "read_profile" has the following attributes. 

         {
   "key" : "access_token.duration",
   "value" : "10000"
 }

        In this case, the API evaluates "10000" as a new value of the duration of the access token (in seconds) and updates the expiration date of the access token using the duration.

        Example 2.

        Let's say we send the following request to /auth/token/update API 

         {
   "accessToken" : "JDGiiM9PuWT63FIwGjG9eYlGi-aZMq6CQ2IB475JUxs",
   "scopes" : ["read_profile", "write_profile"]
 }

        and "read_profile" has the following attributes 

         {
   "key" : "access_token.duration",
   "value" : "10000"
 }

        and "write_profile" has the following attributes. 

         {
   "key" : "access_token.duration",
   "value" : "5000"
 }

        In this case, the API evaluates "10000" and "5000" as candidate values for new duration of the access token (in seconds) and chooses the smallest value of them (i.e. "5000" is adopted) and updates the expiration date of the access token using the duration.

        Parameters:
        updated - The flag which indicates whether /auth/token/update API attempts to update the expiration date of the access token when the scopes linked to the access token are changed by this request.
        Returns:
        this object.
        Since:
        2.29

      • isRefreshTokenExpiresAtUpdatedOnScopeUpdate

        public boolean isRefreshTokenExpiresAtUpdatedOnScopeUpdate()
        Get the flag which indicates whether /auth/token/update API attempts to update the expiration date of the refresh token when the scopes linked to the refresh token are changed by this request.
        Returns:
        The flag which indicates whether /auth/token/update API attempts to update the expiration date of the refresh token when the scopes linked to the refresh token are changed by this request.
        Since:
        3.85

      • setRefreshTokenExpiresAtUpdatedOnScopeUpdate

        public TokenUpdateRequest setRefreshTokenExpiresAtUpdatedOnScopeUpdate​(boolean updated)
        Set the flag which indicates whether /auth/token/update API attempts to update the expiration date of the refresh token when the scopes linked to the refresh token are changed by this request. This request parameter is optional and its default value is false. If this request parameter is set to true and all of the following conditions are satisfied, the API performs an update on the expiration date of the refresh token even if the refreshTokenExpiresAt request parameter is not explicitly specified in the request.
        1. The refreshTokenExpiresAt request parameter is not included in the request or its value is 0 (or negative).
        2. The scopes linked to the refresh token are changed by the scopes request parameter in the request.
        3. Any of the new scopes to be linked to the refresh token has one or more attributes specifying refresh token duration.

        When multiple refresh token duration values are found in the attributes of the specified scopes, the smallest value among them is used.

        For more details, see the following examples.

        Example 1.

        Let's say we send the following request to /auth/token/update API 

         {
   "refreshToken" : "JDGiiM9PuWT63FIwGjG9eYlGi-aZMq6CQ2IB475JUxs",
   "scopes" : ["read_profile"]
 }

        and "read_profile" has the following attributes. 

         {
   "key" : "refresh_token.duration",
   "value" : "10000"
 }

        In this case, the API evaluates "10000" as a new value of the duration of the refresh token (in seconds) and updates the expiration date of the refresh token using the duration.

        Example 2.

        Let's say we send the following request to /auth/token/update API 

         {
   "refreshToken" : "JDGiiM9PuWT63FIwGjG9eYlGi-aZMq6CQ2IB475JUxs",
   "scopes" : ["read_profile", "write_profile"]
 }

        and "read_profile" has the following attributes 

         {
   "key" : "refresh_token.duration",
   "value" : "10000"
 }

        and "write_profile" has the following attributes. 

         {
   "key" : "refresh_token.duration",
   "value" : "5000"
 }

        In this case, the API evaluates "10000" and "5000" as candidate values for new duration of the refresh token (in seconds) and chooses the smallest value of them (i.e. "5000" is adopted) and updates the expiration date of the refresh token using the duration.

        Parameters:
        updated - The flag which indicates whether /auth/token/update API attempts to update the expiration date of the refresh token when the scopes linked to the refresh token are changed by this request.
        Returns:
        this object.
        Since:
        3.85

      • 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 accessTokenExpiresAt request parameter is ignored. If this request parameter is false, the accessTokenExpiresAt request parameter is processed normally.

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

      • setAccessTokenPersistent

        public TokenUpdateRequest 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 accessTokenExpiresAt request parameter is ignored. If this request parameter is false, the accessTokenExpiresAt request parameter is processed normally.

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

      • getAccessTokenHash

        public String getAccessTokenHash()
        Get the hash of the access token value. Used when the hash of the token is known (perhaps from lookup) but the value of the token itself is not.

        The value of the accessToken parameter takes precedence.

        Returns:
        The hash of the access token value.
        Since:
        2.31

      • setAccessTokenHash

        public TokenUpdateRequest setAccessTokenHash​(String accessTokenHash)
        Set the hash of the access token value. Used when the hash of the token is known (perhaps from lookup) but the value of the token itself is not.

        The value of the accessToken parameter takes precedence.

        Parameters:
        accessTokenHash - The hash of the access token value.
        Returns:
        this object.
        Since:
        2.31

      • isAccessTokenValueUpdated

        public boolean isAccessTokenValueUpdated()
        Get whether to update the value of the access token in the data store. If this parameter is set to true then a new access token value is generated by the server and returned in the response.
        Returns:
        false to keep the access token's current value (default). true to have the server update the access token's value.
        Since:
        2.31

      • setAccessTokenValueUpdated

        public TokenUpdateRequest setAccessTokenValueUpdated​(boolean updated)
        Set whether to update the value of the access token in the data store. If this parameter is set to true then a new access token value is generated by the server and returned in the response.
        Parameters:
        updated - false to keep the access token's current value (default). true to have the server update the access token's value.
        Returns:
        this object.
        Since:
        2.31

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

      • setForExternalAttachment

        public TokenUpdateRequest 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

      • getTokenId

        public String getTokenId()
        Get the token identifier.
        Returns:
        The token identifier string.
        Since:
        3.23, Authlete API 3.0

      • setTokenId

        public TokenUpdateRequest setTokenId​(String tokenId)
        Set the token identifier.
        Parameters:
        tokenId - The token identifier string.
        Returns:
        this object.
        Since:
        3.23, Authlete API 3.0