com.authlete.common.dto

Class TokenResponse

java.lang.Object

com.authlete.common.dto.ApiResponse

com.authlete.common.dto.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
Confirm that the format conforms to the JWT specification (RFC 7519). 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". Confirm that the current time has not reached the time indicated by the exp claim if the JWT contains the claim. Confirm that the current time is equal to or after the time indicated by the iat claim if the JWT contains the claim. Confirm that the current time is equal to or after the time indicated by the nbf claim if the JWT contains the claim. 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
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. Confirm that the access token has not expired. Confirm that the access token belongs to the service.
Token Type	urn:ietf:params:oauth:token-type:refresh_token
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. Confirm that the refresh token has not expired. Confirm that the refresh token belongs to the service.
Token Type	urn:ietf:params:oauth:token-type:id_token
Confirm that the format conforms to the JWT specification (RFC 7519). 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". Confirm that the ID Token contains the exp claim and the current time has not reached the time indicated by the claim. Confirm that the ID Token contains the iat claim and the current time is equal to or after the time indicated by the claim. Confirm that the current time is equal to or after the time indicated by the nbf claim if the ID Token contains the claim. 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. Confirm that the ID Token contains the aud claim and its value is a JSON string or an array of JSON strings. Confirm that the value of the nonce claim is a JSON string if the ID Token contains the claim. 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. 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. 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
(Authlete does not perform any validation for this token type.)
Token Type	urn:ietf:params:oauth:token-type:saml2
(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.

• Service.tokenExchangeByIdentifiableClientsOnly - whether to reject token exchange requests that contain no client identifier.

• Service.tokenExchangeByConfidentialClientsOnly - whether to reject token exchange requests by public clients.

• Service.tokenExchangeByPermittedClientsOnly - whether to reject token exchange requests by clients that have no explicit permission.

• Service.tokenExchangeEncryptedJwtRejected - whether to reject token exchange requests which use encrypted JWTs as input tokens.

• Service.tokenExchangeUnsignedJwtRejected - whether to reject token exchange requests which use unsigned JWTs as input tokens.

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.

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, Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	TokenResponse.Action The next action that the service implementation should take.

Constructor Summary

Constructors

Constructor and Description
TokenResponse()

Method Summary

Modifier and Type	Method and Description
String	getAccessToken() Get the newly issued access token.
long	getAccessTokenDuration() Get the duration of the access token in seconds.
long	getAccessTokenExpiresAt() Get the date in milliseconds since the Unix epoch (1970-01-01) at which the access token will expire.
URI[]	getAccessTokenResources() Get the target resources of the access token being issued.
TokenResponse.Action	getAction() Get the next action that the service implementation should take.
String	getActorToken() Get the value of the actor_token request parameter.
TokenInfo	getActorTokenInfo() Get the information about the token specified by the actor_token request parameter.
TokenType	getActorTokenType() Get the value of the actor_token_type request parameter.
String	getAssertion() Get the value of the assertion request parameter.
String[]	getAudiences() Get the values of the audience request parameters that are contained in the token exchange request (cf. RFC 8693).
AuthzDetails	getAuthorizationDetails() Get the authorization details.
Pair[]	getClientAttributes() Get the attributes of the client.
ClientAuthMethod	getClientAuthMethod() Get the client authentication method that should be performed at the token endpoint.
URI	getClientEntityId() Get the entity ID of the client.
long	getClientId() Get the client ID.
String	getClientIdAlias() Get the client ID alias when the token request was made.
String	getGrantId() Get the value of the grant_id parameter in the token response.
GrantType	getGrantType() Get the grant type of the token request.
String	getIdToken() Get the ID token.
String	getJwtAccessToken() Get the newly issued access token in JWT format.
String	getPassword() Get the value of "password" request parameter.
Property[]	getProperties() Get the extra properties associated with the access token.
String	getRefreshToken() Get the newly issued refresh token.
long	getRefreshTokenDuration() Get the duration of the refresh token in seconds.
long	getRefreshTokenExpiresAt() Get the date in milliseconds since the Unix epoch (1970-01-01) at which the refresh token will expire.
TokenType	getRequestedTokenType() Get the value of the requested_token_type request parameter.
URI[]	getResources() Get the resources specified by the resource request parameters in the token request.
String	getResponseContent() Get the response content which can be used as the entity body of the response returned to the client application.
String[]	getScopes() Get the scopes covered by the access token.
Pair[]	getServiceAttributes() Get the attributes of the service that the client application belongs to.
String	getSubject() Get the subject (= resource owner's ID) of the access token.
String	getSubjectToken() Get the value of the subject_token request parameter.
TokenInfo	getSubjectTokenInfo() Get the information about the token specified by the subject_token request parameter.
TokenType	getSubjectTokenType() Get the value of the subject_token_type request parameter.
String	getTicket() Get the ticket issued from Authlete's /auth/token endpoint.
String	getUsername() Get the value of "username" request parameter.
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.
boolean	isClientIdAliasUsed() Get the flag which indicates whether the client ID alias was used when the token request was made.
boolean	isPreviousRefreshTokenUsed() Get the flag indicating whether the previous refresh token that had been kept in the database for a short time was used.
void	setAccessToken(String accessToken) Set the newly issued access token.
void	setAccessTokenDuration(long duration) Set the duration of the access token in seconds.
void	setAccessTokenExpiresAt(long expiresAt) Set the date in milliseconds since the Unix epoch (1970-01-01) at which the access token will expire.
void	setAccessTokenResources(URI[] resources) Set the target resources of the access token being issued.
void	setAction(TokenResponse.Action action) Set the next action that the service implementation should take.
void	setActorToken(String token) Set the value of the actor_token request parameter.
void	setActorTokenInfo(TokenInfo tokenInfo) Set the information about the token specified by the actor_token request parameter.
void	setActorTokenType(TokenType tokenType) Set the value of the actor_token_type request parameter.
void	setAssertion(String assertion) Set the value of the assertion request parameter.
void	setAudiences(String[] audiences) Set the values of the audience request parameters that are contained in the token exchange request (cf. RFC 8693).
void	setAuthorizationDetails(AuthzDetails details) Set the authorization details.
void	setClientAttributes(Pair[] attributes) Set the attributes of the client.
void	setClientAuthMethod(ClientAuthMethod method) Set the client authentication method that should be performed at the token endpoint.
void	setClientEntityId(URI entityId) Set the entity ID of the client.
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.
void	setClientId(long clientId) Set the client ID.
void	setClientIdAlias(String alias) Set the client ID alias when the token request was made.
void	setClientIdAliasUsed(boolean used) Set the flag which indicates whether the client ID alias was used when the token request was made.
void	setGrantId(String grantId) Set the value of the grant_id parameter in the token response.
void	setGrantType(GrantType grantType) Set the grant type of the token request.
void	setIdToken(String idToken) Set the ID token.
void	setJwtAccessToken(String jwtAccessToken) Set the newly issued access token in JWT format.
void	setPassword(String password) Set the value of "password" request parameter.
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.
void	setProperties(Property[] properties) Set the extra properties associated with the access token.
void	setRefreshToken(String refreshToken) Set the newly issued refresh token.
void	setRefreshTokenDuration(long duration) Set the duration of the refresh token in seconds.
void	setRefreshTokenExpiresAt(long expiresAt) Set the date in milliseconds since the Unix epoch (1970-01-01) at which the refresh token will expire.
void	setRequestedTokenType(TokenType tokenType) Set the value of the requested_token_type request parameter.
void	setResources(URI[] resources) Set the resources specified by the resource request parameters in the token request.
void	setResponseContent(String responseContent) Set the response content which can be used as the entity body of the response returned to the client application.
void	setScopes(String[] scopes) Set the scopes covered by the access token.
void	setServiceAttributes(Pair[] attributes) Set the attributes of the service that the client application belongs to.
void	setSubject(String subject) Set the subject (= resource owner's ID) of the access token.
void	setSubjectToken(String token) Set the value of the subject_token request parameter.
void	setSubjectTokenInfo(TokenInfo tokenInfo) Set the information about the token specified by the subject_token request parameter.
void	setSubjectTokenType(TokenType tokenType) Set the value of the subject_token_type request parameter.
void	setTicket(String ticket) Set the ticket used for /auth/token/issue API or /auth/token/fail API.
void	setUsername(String username) Set the value of "username" request parameter.
String	summarize() Get the summary of this instance.

Methods inherited from class com.authlete.common.dto.ApiResponse

getResultCode, getResultMessage, setResultCode, setResultMessage

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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

getRefreshToken

public String getRefreshToken()

Get the newly issued refresh token. This method returns a non-null value only when getAction() returns TokenResponse.Action.OK and the service supports the refresh token flow.

Returns:

The newly issued refresh token.

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

getIdToken

public String getIdToken()

Get the ID token.

An ID token is issued from a token endpoint when the authorization code flow is used and "openid" is included in the scope list.

Returns:

ID token.

Since:

1.34

See Also:

Authentication using the Authorization Code Flow

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 Connect Federation 1.0.

Returns:

The entity ID of the client.

Since:

3.37, Authlete 2.3

See Also:

OpenID Connect 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 Connect Federation 1.0.

Parameters:

entityId - The entity ID of the client.

Since:

3.37, Authlete 2.3

See Also:

OpenID Connect 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 Connect 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 Connect 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 Connect 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 Connect 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

getAudiences

public String[] getAudiences()

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

Returns:

The values of the audience request parameters.

Since:

3.26, Authlete 2.3

See Also:

RFC 8693 OAuth 2.0 Token Exchange

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

getRequestedTokenType

public TokenType getRequestedTokenType()

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

Returns:

The value of the requested_token_type request parameter.

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

getSubjectToken

public String getSubjectToken()

Get the value of the subject_token request parameter.

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

Returns:

The value of the subject_token request parameter.

Since:

3.26, Authlete 2.3

See Also:

RFC 8693 OAuth 2.0 Token Exchange

setSubjectToken

public void setSubjectToken(String token)

Set the value of the subject_token request parameter.

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

Parameters:

token - The value of the subject_token request parameter.

Since:

3.26, Authlete 2.3

See Also:

RFC 8693 OAuth 2.0 Token Exchange

getSubjectTokenType

public TokenType getSubjectTokenType()

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

Returns:

The value of the subject_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

getActorToken

public String getActorToken()

Get the value of the actor_token request parameter.

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

Returns:

The value of the actor_token request parameter.

Since:

3.26, Authlete 2.3

See Also:

RFC 8693 OAuth 2.0 Token Exchange

setActorToken

public void setActorToken(String token)

Set the value of the actor_token request parameter.

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

Parameters:

token - The value of the actor_token request parameter.

Since:

3.26, Authlete 2.3

See Also:

RFC 8693 OAuth 2.0 Token Exchange

getActorTokenType

public TokenType getActorTokenType()

Get the value of the actor_token_type request parameter.

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

Returns:

The value of the actor_token_type request parameter.

Since:

3.26, Authlete 2.3

See Also:

RFC 8693 OAuth 2.0 Token Exchange

setActorTokenType

public void setActorTokenType(TokenType tokenType)

Set the value of the actor_token_type request parameter.

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

Parameters:

tokenType - The value of the actor_token_type 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

getAssertion

public String getAssertion()

Get the value of the assertion request parameter.

The assertion request parameter is defined in Section 4.1 of RFC 7521 Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants.

Returns:

The value of the assertion request parameter.

Since:

3.30, Authlete 2.3

See Also:

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

setAssertion

public void setAssertion(String assertion)

Set the value of the assertion request parameter.

The assertion request parameter is defined in Section 4.1 of RFC 7521 Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants.

Parameters:

assertion - The value of the assertion request parameter.

Since:

3.30, Authlete 2.3

See Also:

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

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()