Package com.authlete.common.dto

Class TokenResponse

  • All Implemented Interfaces:
    Serializable
    public class TokenResponse
extends ApiResponse
    Response from Authlete's /auth/token API.

    Authlete's /auth/token API returns JSON which can be mapped to this class. The service implementation should retrieve the value of "action" from the response and take the following steps according to the value.

    INVALID_CLIENT

    When the value of "action" is "INVALID_CLIENT", it means that authentication of the client failed. In this case, the HTTP status of the response to the client application is either "400 Bad Request" or "401 Unauthorized". This requirement comes from RFC 6749, 5.2. Error Response. The description about "invalid_client" shown below is an excerpt from RFC 6749.

    invalid_client

    Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate via the "Authorization" request header field, the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the "WWW-Authenticate" response header field matching the authentication scheme used by the client.

    In either case, the JSON string returned by getResponseContent() can be used as the entity body of the response to the client application.

    The following illustrate the response which the service implementation should generate and return to the client application. 

     HTTP/1.1 400 Bad Request
 Content-Type: application/json
 Cache-Control: no-store
 Pragma: no-cache

 (The value returned from getResponseContent())
     HTTP/1.1 401 Unauthorized
 WWW-Authenticate: (challenge)
 Content-Type: application/json
 Cache-Control: no-store
 Pragma: no-cache

 (The value returned from getResponseContent())

    INTERNAL_SERVER_ERROR

    When the value of "action" is "INTERNAL_SERVER_ERROR", it means that the request from the service implementation (AuthorizationIssueRequest) was wrong or that an error occurred in Authlete.

    In either case, from the viewpoint of the client application, it is an error on the server side. Therefore, the service implementation should generate a response to the client application with the HTTP status of "500 Internal Server Error".

    getResponseContent() returns a JSON string which describes the error, so it can be used as the entity body of the response.

    The following illustrates the response which the service implementation should generate and return to the client application. 

     HTTP/1.1 500 Internal Server Error
 Content-Type: application/json
 Cache-Control: no-store
 Pragma: no-cache

 (The value returned from getResponseContent())

    BAD_REQUEST

    When the value of "action" is "BAD_REQUEST", it means that the request from the client application is invalid.

    The HTTP status of the response returned to the client application must be "400 Bad Request" and the content type must be "application/json".

    getResponseContent() returns a JSON string which describes the error, so it can be used as the entity body of the response.

    The following illustrates the response which the service implementation should generate and return to the client application. 

     HTTP/1.1 400 Bad Request
 Content-Type: application/json
 Cache-Control: no-store
 Pragma: no-cache

 (The value returned from getResponseContent())

    PASSWORD

    When the value of "action" is "PASSWORD", it means that the request from the client application is valid and grant_type is "password". That is, the flow is "Resource Owner Password Credentials".

    In this case, getUsername() returns the value of "username" request parameter and getPassword() returns the value of "password" request parameter which were contained in the token request from the client application. The service implementation must validate the credentials of the resource owner (= end-user) and take either of the actions below according to the validation result.

    1. When the credentials are valid, call Authlete's /auth/token/issue API to generate an access token for the client application. The API requires "ticket" request parameter and "subject" request parameter. Use the value returned from getTicket() method as the value for "ticket" parameter.

      The response from /auth/token/issue API (TokenIssueResponse) contains data (an access token and others) which should be returned to the client application. Use the data to generate a response to the client application.

    2. When the credentials are invalid, call Authlete's /auth/token/fail API with reason=INVALID_RESOURCE_OWNER_CREDENTIALS to generate an error response for the client application. The API requires "ticket" request parameter. Use the value returned from getTicket() method as the value for "ticket" parameter.

      The response from /auth/token/fail API (TokenFailResponse) contains error information which should be returned to the client application. Use it to generate a response to the client application.

    OK

    When the value of "action" is "OK", it means that the request from the client application is valid and an access token, and optionally an ID token, is ready to be issued.

    The HTTP status of the response returned to the client application must be "200 OK" and the content type must be "application/json".

    getResponseContent() returns a JSON string which contains an access token (and optionally an ID token), so it can be used as the entity body of the response.

    The following illustrates the response which the service implementation should generate and return to the client application. 

     HTTP/1.1 200 OK
 Content-Type: application/json
 Cache-Control: no-store
 Pragma: no-cache

 (The value returned from getResponseContent())

    TOKEN_EXCHANGE (Authlete 2.3 onwards)

    When the value of "action" is "TOKEN_EXCHANGE", it means that the request from the client application is a valid token exchange request (cf. RFC 8693 OAuth 2.0 Token Exchange) and that the request has already passed the following validation steps.

    1. Confirm that the value of the requested_token_type request parameter is one of the registered token type identifiers if the request parameter is given and its value is not empty.

    2. Confirm that the subject_token request parameter is given and its value is not empty.

    3. Confirm that the subject_token_type request parameter is given and its value is one of the registered token type identifiers.

    4. Confirm that the actor_token_type request parameter is given and its value is one of the registered token type identifiers if the actor_token request parameter is given and its value is not empty.

    5. Confirm that the actor_token_type request parameter is not given or its value is empty when the actor_token request parameter is not given or its value is empty.

    Furthermore, Authlete performs additional validation on the tokens specified by the subject_token request parameter and the actor_token request parameter according to their respective token types as shown below.

    Token Validation Steps
    Token Type urn:ietf:params:oauth:token-type:jwt

    1. Confirm that the format conforms to the JWT specification (RFC 7519).

    2. Check if the JWT is encrypted and if it is encrypted, then (a) reject the token exchange request when the tokenExchangeEncryptedJwtRejected flag of the service is true or (b) skip remaining validation steps when the flag is false. Note that Authlete does not verify an encrypted JWT because there is no standard way to obtain the key to decrypt the JWT with. This means that you must verify an encrypted JWT by yourself when one is used as an input token with the token type "urn:ietf:params:oauth:token-type:jwt".

    3. Confirm that the current time has not reached the time indicated by the exp claim if the JWT contains the claim.

    4. Confirm that the current time is equal to or after the time indicated by the iat claim if the JWT contains the claim.

    5. Confirm that the current time is equal to or after the time indicated by the nbf claim if the JWT contains the claim.

    6. Check if the JWT is signed and if it is not signed, then (a) reject the token exchange request when the tokenExchangeUnsignedJwtRejected flag of the service is true or (b) finish validation on the input token. Note that Authlete does not verify the signature of the JWT because there is no standard way to obtain the key to verify the signature of a JWT with. This means that you must verify the signature by yourself when a signed JWT is used as an input token with the token type "urn:ietf:params:oauth:token-type:jwt".

    Token Type urn:ietf:params:oauth:token-type:access_token

    1. Confirm that the token is an access token that has been issued by the Authlete server of your service. This implies that access tokens issued by other systems cannot be used as a subject token or an actor token with the token type urn:ietf:params:oauth:token-type:access_token.

    2. Confirm that the access token has not expired.

    3. Confirm that the access token belongs to the service.

    Token Type urn:ietf:params:oauth:token-type:refresh_token

    1. Confirm that the token is a refresh token that has been issued by the Authlete server of your service. This implies that refresh tokens issued by other systems cannot be used as a subject token or an actor token with the token type urn:ietf:params:oauth:token-type:refresh_token.

    2. Confirm that the refresh token has not expired.

    3. Confirm that the refresh token belongs to the service.

    Token Type urn:ietf:params:oauth:token-type:id_token

    1. Confirm that the format conforms to the JWT specification (RFC 7519).

    2. Check if the ID Token is encrypted and if it is encrypted, then (a) reject the token exchange request when the tokenExchangeEncryptedJwtRejected flag of the service is true or (b) skip remaining validation steps when the flag is false. Note that Authlete does not verify an encrypted ID Token because there is no standard way to obtain the key to decrypt the ID Token with in the context of token exchange where the client ID for the encrypted ID Token cannot be determined. This means that you must verify an encrypted ID Token by yourself when one is used as an input token with the token type "urn:ietf:params:oauth:token-type:id_token".

    3. Confirm that the ID Token contains the exp claim and the current time has not reached the time indicated by the claim.

    4. Confirm that the ID Token contains the iat claim and the current time is equal to or after the time indicated by the claim.

    5. Confirm that the current time is equal to or after the time indicated by the nbf claim if the ID Token contains the claim.

    6. Confirm that the ID Token contains the iss claim and the value is a valid URI. In addition, confirm that the URI has the https scheme, no query component and no fragment component.

    7. Confirm that the ID Token contains the aud claim and its value is a JSON string or an array of JSON strings.

    8. Confirm that the value of the nonce claim is a JSON string if the ID Token contains the claim.

    9. Check if the ID Token is signed and if it is not signed, then (a) reject the token exchange request when the tokenExchangeUnsignedJwtRejected flag of the service is true or (b) finish validation on the input token.

    10. Confirm that the signature algorithm is asymmetric. This implies that ID Tokens whose signature algorithm is symmetric (HS256, HS384 or HS512) cannot be used as a subject token or an actor token with the token type urn:ietf:params:oauth:token-type:id_token.

    11. Verify the signature of the ID Token. Signature verification is performed even in the case where the issuer of the ID Token is not your service. But in that case, the issuer must support the discovery endpoint defined in OpenID Connect Discovery 1.0. Otherwise, signature verification fails.

    Token Type urn:ietf:params:oauth:token-type:saml1

    1. (Authlete does not perform any validation for this token type.)

    Token Type urn:ietf:params:oauth:token-type:saml2

    1. (Authlete does not perform any validation for this token type.)

    The specification of Token Exchange (RFC 8693) is very flexible. In other words, the specification has abandoned the task of determining details. Therefore, for secure token exchange, you have to complement the specification with your own rules. For that purpose, Authlete provides some configuration options as listed below. Authorization server implementers may utilize them and/or implement their own rules.

    In the case of TOKEN_EXCHANGE, the getResponseContent() method returns null. You have to construct the token response by yourself.

    For example, you may generate an access token by calling Authlete's /api/auth/token/create API and construct a token response like below. 

     HTTP/1.1 200 OK
 Content-Type: application/json
 Cache-Control: no-cache, no-store

 {
   "access_token":      "TokenCreateResponse.getAccessToken()",
   "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
   "token_type":        "Bearer",
   "expires_in":        TokenCreateResponse.getExpiresIn(),
   "scope":             "String.join(" ", TokenCreateResponse.getScopes())"
 }

    JWT_BEARER (Authlete 2.3 onwards)

    When the value of "action" is "JWT_BEARER", it means that the request from the client application is a valid token request with the grant type "urn:ietf:params:oauth:grant-type:jwt-bearer" (RFC 7523 JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants) and that the request has already passed the following validation steps.

    1. Confirm that the assertion request parameter is given and its value is not empty.

    2. Confirm that the format of the assertion conforms to the JWT specification (RFC 7519).

    3. Check if the JWT is encrypted and if it is encrypted, then (a) reject the token request when the jwtGrantEncryptedJwtRejected flag of the service is true or (b) skip remaining validation steps when the flag is false. Note that Authlete does not verify an encrypted JWT because there is no standard way to obtain the key to decrypt the JWT with. This means that you must verify an encrypted JWT by yourself.

    4. Confirm that the JWT contains the iss claim and its value is a JSON string.

    5. Confirm that the JWT contains the sub claim and its value is a JSON string.

    6. Confirm that the JWT contains the aud claim and its value is either a JSON string or an array of JSON strings.

    7. Confirm that the issuer identifier of the service (cf. Service.getIssuer()) or the URL of the token endpoint (cf. Service.getTokenEndpoint()) is listed as audience in the aud claim.

    8. Confirm that the JWT contains the exp claim and the current time has not reached the time indicated by the claim.

    9. Confirm that the current time is equal to or after the time indicated by by the iat claim if the JWT contains the claim.

    10. Confirm that the current time is equal to or after the time indicated by by the nbf claim if the JWT contains the claim.

    11. Check if the JWT is signed and if it is not signed, then (a) reject the token request when the jwtGrantUnsignedJwtRejected flag of the service is true or (b) finish validation on the JWT. Note that Authlete does not verify the signature of the JWT because there is no standard way to obtain the key to verify the signature of a JWT with. This means that you must verify the signature by yourself.

    Authlete provides some configuration options for the grant type as listed below. Authorization server implementers may utilize them and/or implement their own rules.

    • Service.jwtGrantByIdentifiableClientsOnly - whether to reject token requests that use the grant type "urn:ietf:params:oauth:grant-type:jwt-bearer" but contain no client identifier.

    • Service.jwtGrantEncryptedJwtRejected - whether to reject token requests that use an encrypted JWT as an authorization grant with the grant type "urn:ietf:params:oauth:grant-type:jwt-bearer".

    • Service.jwtGrantUnsignedJwtRejected - whether to reject token requests that use an unsigned JWT as an authorization grant with the grant type "urn:ietf:params:oauth:grant-type:jwt-bearer".

    In the case of JWT_BEARER, the getResponseContent() method returns null. You have to construct the token response by yourself.

    For example, you may generate an access token by calling Authlete's /api/auth/token/create API and construct a token response like below. 

     HTTP/1.1 200 OK
 Content-Type: application/json
 Cache-Control: no-cache, no-store

 {
   "access_token": "TokenCreateResponse.getAccessToken()",
   "token_type":   "Bearer",
   "expires_in":   TokenCreateResponse.getExpiresIn(),
   "scope":        "String.join(" ", TokenCreateResponse.getScopes())"
 }

    Finally, note again that Authlete does not verify the signature of the JWT specified by the assertion request parameter. You must verify the signature by yourself.

    ID_TOKEN_REISSUABLE (Authlete 2.3.8 onwards)

    The "action" value "ID_TOKEN_REISSUABLE" indicates that an ID token can be reissued by the token request. This action value is returned when the following conditions are met.

    1. The service's "idTokenReissuable" property is true (cf. Service.isIdTokenReissuable()).
    2. The flow of the token request is the refresh token flow.
    3. The scope set after processing the token request still contains the "openid" scope.
    4. The access token is associated with the subject of a user.
    5. The access token is associated with a client application.

    When receiving this action value, the implementation of the token endpoint can take either of the following actions.

    1. Execute the same steps as for the case of the "OK" action. This will result in that the token endpoint behaves as before, and no ID token is reissued.
    2. Call Authlete's /idtoken/reissue API to reissue an ID token and let the API prepare a token response including a new ID token together with the new access token and a refresh token.

    If you choose to reissue a new ID token, the following steps should be taken.

    1. Identify the user associated with the access token based on the "subject" parameter in the response from the /auth/token API (cf. getSubject()).
    2. Get the list of requested claims for ID tokens by referring to the value of the "requestedIdTokenClaims" parameter in the response from the /auth/token API. Note that, however, the parameter always holds null when the Authlete server you are using is older than the version 3.0. See the description of the getRequestedIdTokenClaims() method for details.
    3. Get the values of the requested claims of the user from your user database.
    4. Construct a JSON object that includes the name-value pairs of the requested claims. The JSON is used as the value of the "claims" request parameter passed to the /idtoken/reissue API.
    5. Select the representation of the access token based on the following logic: if the value of the "jwtAccessToken" parameter (cf. getJwtAccessToken()) is not null, use the value. Otherwise, use the value of the "accessToken" parameter (cf. getAccessToken()). The selected representation is used as the value of the "accessToken" parameter passed to the /idtoken/reissue API.
    6. Get the value of the refresh token (cf. getRefreshToken()). The value is used as the value of the "refreshToken" parameter passed to the /idtoken/reissue API.
    7. Call the /idtoken/reissue API and follow the instruction of the API. See the descriptions of the IDTokenReissueRequest class and the IDTokenReissueResponse class for details.

    DPoP Nonce (Authlete 3.0 onwards)

    Since version 3.0, Authlete recognizes the nonce claim in DPoP proof JWTs. If the nonce claim is required (= if the service's dpopNonceRequired property is true, or the value of the dpopNonceRequired request parameter passed to the Authlete API is true), the Authlete API checks whether the nonce claim in the presented DPoP proof JWT is identical to the expected value.

    If the dpopNonce response parameter from the API is not null, its value is the expected nonce value for DPoP proof JWT. The expected value needs to be conveyed to the client application as the value of the DPoP-Nonce HTTP header. 

    DPoP-Nonce: (The value returned from getDpopNonce())

    See RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP) for details.

    See Also:
    RFC 6749 The OAuth 2.0 Authorization Framework, RFC 7521 Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants, RFC 7523 JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants, RFC 8693 OAuth 2.0 Token Exchange, RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP), Serialized Form

    • Constructor Detail

      • TokenResponse

        public TokenResponse()

    • Method Detail

      • getAction

        public TokenResponse.Action getAction()
        Get the next action that the service implementation should take.

      • setAction

        public void setAction​(TokenResponse.Action action)
        Set the next action that the service implementation should take.

      • getResponseContent

        public String getResponseContent()
        Get the response content which can be used as the entity body of the response returned to the client application.

      • setResponseContent

        public void setResponseContent​(String responseContent)
        Set the response content which can be used as the entity body of the response returned to the client application.

      • getUsername

        public String getUsername()
        Get the value of "username" request parameter.

        This method returns a non-null value only when the value of "grant_type" request parameter in the token request is "password".

        getSubject() method was renamed to getUsername() on version 1.13.

        Since:
        1.13
        See Also:
        RFC 6749, 4.3.2. Access Token Request

      • setUsername

        public void setUsername​(String username)
        Set the value of "username" request parameter.

        setSubject(String} was renamed to setUsername(String) on version 1.13.

        Since:
        1.13

      • getPassword

        public String getPassword()
        Get the value of "password" request parameter.

        This method returns a non-null value only when the value of "grant_type" request parameter in the token request is "password".

        See Also:
        RFC 6749, 4.3.2. Access Token Request

      • setPassword

        public void setPassword​(String password)
        Set the value of "password" request parameter.

      • getTicket

        public String getTicket()
        Get the ticket issued from Authlete's /auth/token endpoint. The value is to be used as the value of "ticket" request parameter for /auth/token/issue API or /auth/token/fail API.

        This method returns a non-null value only when "action" is PASSWORD.

      • setTicket

        public void setTicket​(String ticket)
        Set the ticket used for /auth/token/issue API or /auth/token/fail API.

      • summarize

        public String summarize()
        Get the summary of this instance.

      • getAccessToken

        public String getAccessToken()
        Get the newly issued access token. This method returns a non-null value only when getAction() returns TokenResponse.Action.OK.

        If the service is configured to issue JWT-based access tokens, a JWT-based access token is issued additionally. In the case, getJwtAccessToken() returns the JWT-based access token.

        Returns:
        The newly issued access token.
        Since:
        1.34
        See Also:
        getJwtAccessToken()

      • setAccessToken

        public void setAccessToken​(String accessToken)
        Set the newly issued access token.
        Parameters:
        accessToken - The newly issued access token.
        Since:
        1.34

      • getAccessTokenExpiresAt

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

      • setAccessTokenExpiresAt

        public void setAccessTokenExpiresAt​(long expiresAt)
        Set the date in milliseconds since the Unix epoch (1970-01-01) at which the access token will expire.
        Parameters:
        expiresAt - The expiration date in milliseconds since the Unix epoch (1970-01-01) at which the access token will expire.
        Since:
        1.34

      • getAccessTokenDuration

        public long getAccessTokenDuration()
        Get the duration of the access token in seconds.
        Returns:
        Duration in seconds.
        Since:
        1.34

      • setAccessTokenDuration

        public void setAccessTokenDuration​(long duration)
        Set the duration of the access token in seconds.
        Parameters:
        duration - Duration in seconds.
        Since:
        1.34

      • setRefreshToken

        public void setRefreshToken​(String refreshToken)
        Set the newly issued refresh token.
        Parameters:
        refreshToken - The newly issued refresh token.
        Since:
        1.34

      • getRefreshTokenExpiresAt

        public long getRefreshTokenExpiresAt()
        Get the date in milliseconds since the Unix epoch (1970-01-01) at which the refresh token will expire.
        Returns:
        The expiration date in milliseconds since the Unix epoch (1970-01-01) at which the refresh token will expire. If the refresh token is null, this method returns 0.
        Since:
        1.34

      • setRefreshTokenExpiresAt

        public void setRefreshTokenExpiresAt​(long expiresAt)
        Set the date in milliseconds since the Unix epoch (1970-01-01) at which the refresh token will expire.
        Parameters:
        expiresAt - The expiration date in milliseconds since the Unix epoch (1970-01-01) at which the refresh token will expire. If the refresh token is null, this method returns 0.
        Since:
        1.34

      • getRefreshTokenDuration

        public long getRefreshTokenDuration()
        Get the duration of the refresh token in seconds.
        Returns:
        Duration in seconds.
        Since:
        1.34

      • setRefreshTokenDuration

        public void setRefreshTokenDuration​(long duration)
        Set the duration of the refresh token in seconds.
        Parameters:
        duration - Duration in seconds.
        Since:
        1.34

      • setIdToken

        public void setIdToken​(String idToken)
        Set the ID token.
        Parameters:
        idToken - ID token.
        Since:
        1.34

      • getGrantType

        public GrantType getGrantType()
        Get the grant type of the token request.
        Since:
        2.8

      • setGrantType

        public void setGrantType​(GrantType grantType)
        Set the grant type of the token request.
        Parameters:
        grantType - Grant type of the token request.
        Since:
        2.8

      • getClientId

        public long getClientId()
        Get the client ID.
        Since:
        2.8

      • setClientId

        public void setClientId​(long clientId)
        Set the client ID.
        Since:
        2.8

      • getClientIdAlias

        public String getClientIdAlias()
        Get the client ID alias when the token request was made.

        If the client did not have an alias, this method returns null. Also, if the token request was invalid and it failed to identify a client, this method returns null.

        Returns:
        The client ID alias.
        Since:
        2.8

      • setClientIdAlias

        public void setClientIdAlias​(String alias)
        Set the client ID alias when the token request was made.
        Parameters:
        alias - The client ID alias.
        Since:
        2.8

      • isClientIdAliasUsed

        public boolean isClientIdAliasUsed()
        Get the flag which indicates whether the client ID alias was used when the token request was made.
        Returns:
        true if the client ID alias was used when the token request was made.
        Since:
        2.8

      • setClientIdAliasUsed

        public void setClientIdAliasUsed​(boolean used)
        Set the flag which indicates whether the client ID alias was used when the token request was made.
        Parameters:
        used - true if the client ID alias was used when the token request was made.
        Since:
        2.8

      • getClientEntityId

        public URI getClientEntityId()
        Get the entity ID of the client.

        "Entity ID" is a technical term defined in OpenID Federation 1.0.

        Returns:
        The entity ID of the client.
        Since:
        3.37, Authlete 2.3
        See Also:
        OpenID Federation 1.0

      • setClientEntityId

        public void setClientEntityId​(URI entityId)
        Set the entity ID of the client.

        "Entity ID" is a technical term defined in OpenID Federation 1.0.

        Parameters:
        entityId - The entity ID of the client.
        Since:
        3.37, Authlete 2.3
        See Also:
        OpenID Federation 1.0

      • isClientEntityIdUsed

        public boolean isClientEntityIdUsed()
        Get the flag which indicates whether the entity ID of the client was used when the request for the access token was made.

        "Entity ID" is a technical term defined in OpenID Federation 1.0.

        Returns:
        true if the entity ID of the client was used when the request for the access token was made.
        Since:
        3.37, Authlete 2.3
        See Also:
        OpenID Federation 1.0

      • setClientEntityIdUsed

        public void setClientEntityIdUsed​(boolean used)
        Set the flag which indicates whether the entity ID of the client was used when the request for the access token was made.

        "Entity ID" is a technical term defined in OpenID Federation 1.0.

        Parameters:
        used - true to indicate that the entity ID of the client was used when the request for the access token was made.
        Since:
        3.37, Authlete 2.3
        See Also:
        OpenID Federation 1.0

      • getSubject

        public String getSubject()
        Get the subject (= resource owner's ID) of the access token.

        Even if an access token has been issued by the call of /api/auth/token API, this method returns null if the flow of the token request was Client Credentials Flow (grant_type=client_credentials) because it means the access token is not associated with any specific end-user.

        Since:
        2.8

      • setSubject

        public void setSubject​(String subject)
        Set the subject (= resource owner's ID) of the access token.
        Since:
        2.8

      • getScopes

        public String[] getScopes()
        Get the scopes covered by the access token.
        Since:
        2.8

      • setScopes

        public void setScopes​(String[] scopes)
        Set the scopes covered by the access token.
        Since:
        2.8

      • getProperties

        public Property[] getProperties()
        Get the extra properties associated with the access token. This method returns null when no extra property is associated with the issued access token.
        Returns:
        Extra properties associated with the issued access token.
        Since:
        2.8

      • setProperties

        public void setProperties​(Property[] properties)
        Set the extra properties associated with the access token.
        Parameters:
        properties - Extra properties.
        Since:
        2.8

      • getJwtAccessToken

        public String getJwtAccessToken()
        Get the newly issued access token in JWT format.

        If the authorization server is configured to issue JWT-based access tokens (= if Service.getAccessTokenSignAlg() returns a non-null value), a JWT-based access token is issued along with the original random-string one.

        Regarding the detailed format of the JWT-based access token, see the description of the Service class.

        Returns:
        The newly issued access token in JWT format. If the service is not configured to issue JWT-based access tokens, this method always returns null.
        Since:
        2.37
        See Also:
        getAccessToken()

      • setJwtAccessToken

        public void setJwtAccessToken​(String jwtAccessToken)
        Set the newly issued access token in JWT format.
        Parameters:
        jwtAccessToken - The newly issued access token in JWT format.
        Since:
        2.37

      • getClientAuthMethod

        public ClientAuthMethod getClientAuthMethod()
        Get the client authentication method that should be performed at the token endpoint.

        If the client could not be identified by the information in the request, this method returns null.

        Returns:
        The client authentication method that should be performed at the token endpoint.
        Since:
        2.50

      • setClientAuthMethod

        public void setClientAuthMethod​(ClientAuthMethod method)
        Set the client authentication method that should be performed at the token endpoint.
        Parameters:
        method - The client authentication method that should be performed at the token endpoint.
        Since:
        2.50

      • getResources

        public URI[] getResources()
        Get the resources specified by the resource request parameters in the token request.

        See "Resource Indicators for OAuth 2.0" for details.

        Returns:
        Resources specified by the resource request parameters in the token request.
        Since:
        2.62

      • setResources

        public void setResources​(URI[] resources)
        Set the resources specified by the resource request parameters in the token request.

        See "Resource Indicators for OAuth 2.0" for details.

        Parameters:
        resources - Resources specified by the resource request parameters in the token request.
        Since:
        2.62

      • getAccessTokenResources

        public URI[] getAccessTokenResources()
        Get the target resources of the access token being issued.

        See "Resource Indicators for OAuth 2.0" for details.

        Returns:
        The target resources of the access token.
        Since:
        2.62

      • setAccessTokenResources

        public void setAccessTokenResources​(URI[] resources)
        Set the target resources of the access token being issued.

        See "Resource Indicators for OAuth 2.0" for details.

        Parameters:
        resources - The target resources of the access token.
        Since:
        2.62

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

        When the action (= the value returned from getAction() is PASSWORD, this method returns an array that represents the authorization_details request parameter included in the token request. In other successful cases, this method returns the authorization details associated with the issued access token.

        Returns:
        Authorization details.
        Since:
        2.56

      • setAuthorizationDetails

        public void setAuthorizationDetails​(AuthzDetails details)
        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:
        details - Authorization details.
        Since:
        2.56

      • getGrantId

        public String getGrantId()
        Get the value of the grant_id parameter in the token response.
        Returns:
        The value of the grant_id response parameter.
        Since:
        3.1
        See Also:
        Grant Management for OAuth 2.0

      • setGrantId

        public void setGrantId​(String grantId)
        Set the value of the grant_id parameter in the token response.
        Parameters:
        grantId - The value of the grant_id response parameter.
        Since:
        3.1
        See Also:
        Grant Management for OAuth 2.0

      • getServiceAttributes

        public Pair[] getServiceAttributes()
        Get the attributes of the service that the client application belongs to.

        This property is available since Authlete 2.2.

        Returns:
        The attributes of the service.
        Since:
        2.88

      • setServiceAttributes

        public void setServiceAttributes​(Pair[] attributes)
        Set the attributes of the service that the client application belongs to.

        This property is available since Authlete 2.2.

        Parameters:
        attributes - The attributes of the service.
        Since:
        2.88

      • getClientAttributes

        public Pair[] getClientAttributes()
        Get the attributes of the client.

        This property is available since Authlete 2.2.

        Returns:
        The attributes of the client.
        Since:
        2.88

      • setClientAttributes

        public void setClientAttributes​(Pair[] attributes)
        Set the attributes of the client.

        This property is available since Authlete 2.2.

        Parameters:
        attributes - The attributes of the client.
        Since:
        2.88

      • setAudiences

        public void setAudiences​(String[] audiences)
        Set the values of the audience request parameters that are contained in the token exchange request (cf. RFC 8693).

        The audience request parameter is defined in RFC 8693 OAuth 2.0 Token Exchange. Although RFC 6749 The OAuth 2.0 Authorization Framework states "Request and response parameters MUST NOT be included more than once", RFC 8693 allows a token exchange request to include the audience request parameter multiple times.

        Parameters:
        audiences - The values of the audience request parameters.
        Since:
        3.26, Authlete 2.3
        See Also:
        RFC 8693 OAuth 2.0 Token Exchange

      • setRequestedTokenType

        public void setRequestedTokenType​(TokenType tokenType)
        Set the value of the requested_token_type request parameter.

        The requested_token_type request parameter is defined in RFC 8693 OAuth 2.0 Token Exchange.

        Parameters:
        tokenType - The value of the requested_token_type request parameter.
        Since:
        3.26, Authlete 2.3
        See Also:
        RFC 8693 OAuth 2.0 Token Exchange

      • setSubjectTokenType

        public void setSubjectTokenType​(TokenType tokenType)
        Set the value of the subject_token_type request parameter.

        The subject_token_type request parameter is defined in RFC 8693 OAuth 2.0 Token Exchange.

        Parameters:
        tokenType - The value of the subject_token_type request parameter.
        Since:
        3.26, Authlete 2.3
        See Also:
        RFC 8693 OAuth 2.0 Token Exchange

      • getSubjectTokenInfo

        public TokenInfo getSubjectTokenInfo()
        Get the information about the token specified by the subject_token request parameter.

        This property holds a non-null value only when the value of the subject_token_type request parameter is either "urn:ietf:params:oauth:token-type:access_token" or "urn:ietf:params:oauth:token-type:refresh_token" (= only when the subjectTokenType property is either "ACCESS_TOKEN" or "REFRESH_TOKEN").

        Returns:
        The information about the token specified by the subject_token request parameter.
        Since:
        3.26, Authlete 2.3
        See Also:
        RFC 8693 OAuth 2.0 Token Exchange

      • setSubjectTokenInfo

        public void setSubjectTokenInfo​(TokenInfo tokenInfo)
        Set the information about the token specified by the subject_token request parameter.

        This property holds a non-null value only when the value of the subject_token_type request parameter is either "urn:ietf:params:oauth:token-type:access_token" or "urn:ietf:params:oauth:token-type:refresh_token" (= only when the subjectTokenType property is either "ACCESS_TOKEN" or "REFRESH_TOKEN").

        Parameters:
        tokenInfo - The information about the token specified by the subject_token request parameter.
        Since:
        3.26, Authlete 2.3
        See Also:
        RFC 8693 OAuth 2.0 Token Exchange

      • getActorTokenInfo

        public TokenInfo getActorTokenInfo()
        Get the information about the token specified by the actor_token request parameter.

        This property holds a non-null value only when the value of the actor_token_type request parameter is either "urn:ietf:params:oauth:token-type:access_token" or "urn:ietf:params:oauth:token-type:refresh_token" (= only when the actorTokenType property is either "ACCESS_TOKEN" or "REFRESH_TOKEN").

        Returns:
        The information about the token specified by the actor_token request parameter.
        Since:
        3.26, Authlete 2.3
        See Also:
        RFC 8693 OAuth 2.0 Token Exchange

      • setActorTokenInfo

        public void setActorTokenInfo​(TokenInfo tokenInfo)
        Set the information about the token specified by the actor_token request parameter.

        This property holds a non-null value only when the value of the actor_token_type request parameter is either "urn:ietf:params:oauth:token-type:access_token" or "urn:ietf:params:oauth:token-type:refresh_token" (= only when the actorTokenType property is either "ACCESS_TOKEN" or "REFRESH_TOKEN").

        Parameters:
        tokenInfo - The information about the token specified by the actor_token request parameter.
        Since:
        3.26, Authlete 2.3
        See Also:
        RFC 8693 OAuth 2.0 Token Exchange

      • isPreviousRefreshTokenUsed

        public boolean isPreviousRefreshTokenUsed()
        Get the flag indicating whether the previous refresh token that had been kept in the database for a short time was used.

        If the /auth/token API succeeds and includes a refresh token and if this flag is true, the refresh token is the same renewed refresh token that was issued on the previous refresh token request.

        If the /auth/token API reports that the refresh token presented by the client application does not exist but if this flag is true, it implies that the previous refresh token was used but the short time had already passed.

        This flag will never become true if the feature of "Idempotent Refresh Token" is not enabled. See the description of Service.isRefreshTokenIdempotent() about the feature.

        Returns:
        true if the previous refresh token that had been kept in the database for a short time was used.
        Since:
        3.50, Authlete 2.3
        See Also:
        Service.isRefreshTokenIdempotent()

      • setPreviousRefreshTokenUsed

        public void setPreviousRefreshTokenUsed​(boolean used)
        Set the flag indicating whether the previous refresh token that had been kept in the database for a short time was used.

        If the /auth/token API succeeds and includes a refresh token and if this flag is true, the refresh token is the same renewed refresh token that was issued on the previous refresh token request.

        If the /auth/token API reports that the refresh token presented by the client application does not exist but if this flag is true, it implies that the previous refresh token was used but the short time had already passed.

        This flag will never become true if the feature of "Idempotent Refresh Token" is not enabled. See the description of Service.isRefreshTokenIdempotent() about the feature.

        Parameters:
        used - true to indicate that the previous refresh token that had been kept in the database for a short time was used.
        Since:
        3.50, Authlete 2.3
        See Also:
        Service.isRefreshTokenIdempotent()

      • setCnonce

        public void setCnonce​(String nonce)
        Set the c_nonce.

        c_nonce is issued in the pre-authorized code flow. In addition, a new c_nonce may be issued in the refresh token flow. See OpenID for Verifiable Credentials Issuance for details.

        The setCNonce(String) method added by the version 3.63 has been renamed to setCnonce(String) by the version 3.90.

        Parameters:
        nonce - The c_nonce.
        Since:
        3.90, Authlete 3.0
        See Also:
        OpenID for Verifiable Credentials Issuance

      • getCnonceExpiresAt

        public long getCnonceExpiresAt()
        Get the time at which the c_nonce expires in milliseconds since the Unix epoch (1970-01-01).

        The getCNonceExpiresAt() method added by the version 3.63 has been renamed to getCnonceExpiresAt() by the version 3.90.

        Returns:
        The time at which the c_nonce expires.
        Since:
        3.90, Authlete 3.0
        See Also:
        OpenID for Verifiable Credentials Issuance

      • setCnonceExpiresAt

        public void setCnonceExpiresAt​(long expiresAt)
        Set the time at which the c_nonce expires in milliseconds since the Unix epoch (1970-01-01).

        The setCNonceExpiresAt(long) method added by the version 3.63 has been renamed to setCnonceExpiresAt(long) by the version 3.90.

        Parameters:
        expiresAt - The time at which the c_nonce expires.
        Since:
        3.90, Authlete 3.0
        See Also:
        OpenID for Verifiable Credentials Issuance

      • getCnonceDuration

        public long getCnonceDuration()
        Get the duration of the c_nonce in seconds.

        The getCNonceDuration() method added by the version 3.63 has been renamed to getCnonceDuration() by the version 3.90.

        Returns:
        The duration of the c_nonce in seconds.
        Since:
        3.90, Authlete 3.0
        See Also:
        OpenID for Verifiable Credentials Issuance

      • setCnonceDuration

        public void setCnonceDuration​(long duration)
        Set the duration of the c_nonce in seconds.

        The setCNonceDuration(long) method added by the version 3.63 has been renamed to setCnonceDuration(long) by the version 3.90.

        Parameters:
        duration - The duration of the c_nonce in seconds.
        Since:
        3.90, Authlete 3.0
        See Also:
        OpenID for Verifiable Credentials Issuance

      • getRequestedIdTokenClaims

        public String[] getRequestedIdTokenClaims()
        Get the names of the claims that the authorization request (which resulted in generation of the access token) requested to be embedded in ID tokens.

        Basically the value of this parameter corresponds to the content of the id_token object in the claims request parameter (OpenID Connect Core 1.0, Section 5.5) of the authorization request.

        Note that, however, the value of this parameter is always null when the Authlete server you are using is older than the version 3.0. It's because database records for access tokens issued by old Authlete servers do not maintain information about "requested claims for ID tokens".

        It is expected that this response parameter is referred to when the action parameter in the response from the /auth/token API is ID_TOKEN_REISSUABLE.

        Returns:
        The names of the claims that the authorization request requested to be embedded in ID tokens.
        Since:
        3.68, Authlete 3.0

      • setRequestedIdTokenClaims

        public void setRequestedIdTokenClaims​(String[] claims)
        Set the names of the claims that the authorization request (which resulted in generation of the access token) requested to be embedded in ID tokens.

        Basically the value of this parameter corresponds to the content of the id_token object in the claims request parameter (OpenID Connect Core 1.0, Section 5.5) of the authorization request.

        Note that, however, the value of this parameter is always null when the Authlete server you are using is older than the version 3.0. It's because database records for access tokens issued by old Authlete servers do not maintain information about "requested claims for ID tokens".

        It is expected that this response parameter is referred to when the action parameter in the response from the /auth/token API is ID_TOKEN_REISSUABLE.

        Parameters:
        claims - The names of the claims that the authorization request requested to be embedded in ID tokens.
        Since:
        3.68, Authlete 3.0

      • getDpopNonce

        public String getDpopNonce()
        Get the expected nonce value for DPoP proof JWT, which should be used as the value of the DPoP-Nonce HTTP header.

        When this response parameter is not null, the implementation of the token endpoint should add the DPoP-Nonce HTTP header in the response from the endpoint to the client application, using the value of this response parameter as the value of the HTTP header. 

         DPoP-Nonce: (The value of this dpopNonce response parameter)
        Returns:
        The expected nonce value for DPoP proof JWT.
        Since:
        3.82, Authlete 3.0
        See Also:
        RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP)

      • setDpopNonce

        public void setDpopNonce​(String dpopNonce)
        Set the expected nonce value for DPoP proof JWT, which should be used as the value of the DPoP-Nonce HTTP header.

        When this response parameter is not null, the implementation of the token endpoint should add the DPoP-Nonce HTTP header in the response from the endpoint to the client application, using the value of this response parameter as the value of the HTTP header. 

         DPoP-Nonce: (The value of this dpopNonce response parameter)
        Parameters:
        dpopNonce - The expected nonce value for DPoP proof JWT.
        Since:
        3.82, Authlete 3.0
        See Also:
        RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP)

      • getRefreshTokenScopes

        public String[] getRefreshTokenScopes()
        Get the scopes associated with the refresh token.
        Returns:
        The scopes associated with the refresh token. May be null.
        Since:
        3.89, Authlete API 3.0

      • setRefreshTokenScopes

        public void setRefreshTokenScopes​(String[] refreshTokenScopes)
        Set the scopes associated with the refresh token.
        Parameters:
        refreshTokenScopes - The scopes associated with the refresh token.
        Since:
        3.89, Authlete API 3.0