Package org.springframework.security.web.authentication.rememberme

# Class TokenBasedRememberMeServices

java.lang.Object
org.springframework.security.web.authentication.rememberme.AbstractRememberMeServices
org.springframework.security.web.authentication.rememberme.TokenBasedRememberMeServices

All Implemented Interfaces:
  `org.springframework.beans.factory.Aware`, `org.springframework.beans.factory.InitializingBean`, `org.springframework.context.MessageSourceAware`, `LogoutHandler`, `RememberMeServices`

public class TokenBasedRememberMeServices extends AbstractRememberMeServices
Identifies previously remembered users by a Base-64 encoded cookie.

This implementation does not rely on an external database, so is attractive for simple applications. The cookie will be valid for a specific period from the date of the last `AbstractRememberMeServices.loginSuccess(HttpServletRequest, HttpServletResponse, Authentication)`. As per the interface contract, this method will only be called when the principal completes a successful interactive authentication. As such the time period commences from the last authentication attempt where they furnished credentials - not the time period they last logged in via remember-me. The implementation will only send a remember-me token if the parameter defined by `AbstractRememberMeServices.setParameter(String)` is present.

An `UserDetailsService` is required by this implementation, so that it can construct a valid `Authentication` from the returned `UserDetails`. This is also necessary so that the user's password is available and can be checked as part of the encoded cookie.

The cookie encoded by this implementation adopts the following form:

     username + ":" + expiryTime + ":" + algorithmName + ":"
                    + algorithmHex(username + ":" + expiryTime + ":" + password + ":" + key)

This implementation uses the algorithm configured in `encodingAlgorithm` to encode the signature. It will try to use the algorithm retrieved from the `algorithmName` to validate the signature. However, if the `algorithmName` is not present in the cookie value, the algorithm configured in `matchingAlgorithm` will be used to validate the signature. This allows users to safely upgrade to a different encoding algorithm while still able to verify old ones if there is no `algorithmName` present.

As such, if the user changes their password, any remember-me token will be invalidated. Equally, the system administrator may invalidate every remember-me token on issue by changing the key. This provides some reasonable approaches to recovering from a remember-me token being left on a public machine (e.g. kiosk system, Internet cafe etc). Most importantly, at no time is the user's password ever sent to the user agent, providing an important security safeguard. Unfortunately the username is necessary in this implementation (as we do not want to rely on a database for remember-me services). High security applications should be aware of this occasionally undesired disclosure of a valid username.

This is a basic remember-me implementation which is suitable for many applications. However, we recommend a database-based implementation if you require a more secure remember-me approach (see `PersistentTokenBasedRememberMeServices`).

By default the tokens will be valid for 14 days from the last successful authentication attempt. This can be changed using `AbstractRememberMeServices.setTokenValiditySeconds(int)`. If this value is less than zero, the `expiryTime` will remain at 14 days, but the negative value will be used for the `maxAge` property of the cookie, meaning that it will not be stored when the browser is closed.

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static enum`
`TokenBasedRememberMeServices.RememberMeTokenAlgorithm`

## Field Summary

### Fields inherited from class org.springframework.security.web.authentication.rememberme.AbstractRememberMeServices

`DEFAULT_PARAMETER, logger, messages, SPRING_SECURITY_REMEMBER_ME_COOKIE_KEY, TWO_WEEKS_S`

## Constructor Summary

Constructors
Constructor
Description
`TokenBasedRememberMeServices(String key, org.springframework.security.core.userdetails.UserDetailsService userDetailsService)`
`TokenBasedRememberMeServices(String key, org.springframework.security.core.userdetails.UserDetailsService userDetailsService, TokenBasedRememberMeServices.RememberMeTokenAlgorithm encodingAlgorithm)`
Construct the instance with the parameters provided

## Method Summary

Modifier and Type
Method
Description
`protected int`
`calculateLoginLifetime(jakarta.servlet.http.HttpServletRequest request, org.springframework.security.core.Authentication authentication)`
Calculates the validity period in seconds for a newly generated remember-me login.
`protected boolean`
`isTokenExpired(long tokenExpiryTime)`
`protected String`
`makeTokenSignature(long tokenExpiryTime, String username, String password)`
Calculates the digital signature to be put in the cookie.
`protected String`
`makeTokenSignature(long tokenExpiryTime, String username, String password, TokenBasedRememberMeServices.RememberMeTokenAlgorithm algorithm)`
Calculates the digital signature to be put in the cookie.
`void`
`onLoginSuccess(jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response, org.springframework.security.core.Authentication successfulAuthentication)`
Called from loginSuccess when a remember-me login has been requested.
`protected org.springframework.security.core.userdetails.UserDetails`
`processAutoLoginCookie(String[] cookieTokens, jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response)`
Called from autoLogin to process the submitted persistent login cookie.
`protected String`
`retrievePassword(org.springframework.security.core.Authentication authentication)`
`protected String`
`retrieveUserName(org.springframework.security.core.Authentication authentication)`
`void`
`setMatchingAlgorithm(TokenBasedRememberMeServices.RememberMeTokenAlgorithm matchingAlgorithm)`
Sets the algorithm to be used to match the token signature

### Methods inherited from class org.springframework.security.web.authentication.rememberme.AbstractRememberMeServices

`afterPropertiesSet, autoLogin, cancelCookie, createSuccessfulAuthentication, decodeCookie, encodeCookie, extractRememberMeCookie, getAuthenticationDetailsSource, getCookieName, getKey, getParameter, getTokenValiditySeconds, getUserDetailsService, loginFail, loginSuccess, logout, onLoginFail, rememberMeRequested, setAlwaysRemember, setAuthenticationDetailsSource, setAuthoritiesMapper, setCookie, setCookieCustomizer, setCookieDomain, setCookieName, setMessageSource, setParameter, setTokenValiditySeconds, setUserDetailsChecker, setUseSecureCookie`

### Methods inherited from class java.lang.Object

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

## Constructor Details

### TokenBasedRememberMeServices

public TokenBasedRememberMeServices(String key, org.springframework.security.core.userdetails.UserDetailsService userDetailsService)

### TokenBasedRememberMeServices

public TokenBasedRememberMeServices(String key, org.springframework.security.core.userdetails.UserDetailsService userDetailsService, TokenBasedRememberMeServices.RememberMeTokenAlgorithm encodingAlgorithm)
Construct the instance with the parameters provided

Parameters:
  `key` - the signature key
  `userDetailsService` - the `UserDetailsService`
  `encodingAlgorithm` - the `TokenBasedRememberMeServices.RememberMeTokenAlgorithm` used to encode the signature
Since:
  5.8

## Method Details

### processAutoLoginCookie

protected org.springframework.security.core.userdetails.UserDetails processAutoLoginCookie(String[] cookieTokens, jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response)
Description copied from class: `AbstractRememberMeServices`
Called from autoLogin to process the submitted persistent login cookie. Subclasses should validate the cookie and perform any additional management required.

Specified by:
  `processAutoLoginCookie` in class `AbstractRememberMeServices`
Parameters:
  `cookieTokens` - the decoded and tokenized cookie value
  `request` - the request
  `response` - the response, to allow the cookie to be modified if required.
Returns:
  the UserDetails for the corresponding user account if the cookie was validated successfully.

### makeTokenSignature

protected String makeTokenSignature(long tokenExpiryTime, String username, String password)
Calculates the digital signature to be put in the cookie. Default value is `encodingAlgorithm` applied to ("username:tokenExpiryTime:password:key")

### makeTokenSignature

protected String makeTokenSignature(long tokenExpiryTime, String username, String password, TokenBasedRememberMeServices.RememberMeTokenAlgorithm algorithm)
Calculates the digital signature to be put in the cookie.

Since:
  5.8

### isTokenExpired

protected boolean isTokenExpired(long tokenExpiryTime)

### onLoginSuccess

public void onLoginSuccess(jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response, org.springframework.security.core.Authentication successfulAuthentication)
Description copied from class: `AbstractRememberMeServices`
Called from loginSuccess when a remember-me login has been requested. Typically implemented by subclasses to set a remember-me cookie and potentially store a record of it if the implementation requires this.

Specified by:
  `onLoginSuccess` in class `AbstractRememberMeServices`

### setMatchingAlgorithm

public void setMatchingAlgorithm(TokenBasedRememberMeServices.RememberMeTokenAlgorithm matchingAlgorithm)
Sets the algorithm to be used to match the token signature

Parameters:
  `matchingAlgorithm` - the matching algorithm
Since:
  5.8

### calculateLoginLifetime

protected int calculateLoginLifetime(jakarta.servlet.http.HttpServletRequest request, org.springframework.security.core.Authentication authentication)
Calculates the validity period in seconds for a newly generated remember-me login. After this period (from the current time) the remember-me login will be considered expired. This method allows customization based on request parameters supplied with the login or information in the `Authentication` object. The default value is just the token validity period property, `tokenValiditySeconds`.

The returned value will be used to work out the expiry time of the token and will also be used to set the `maxAge` property of the cookie.

See SEC-485.

Parameters:
  `request` - the request passed to onLoginSuccess
  `authentication` - the successful authentication object.
Returns:
  the lifetime in seconds.

### retrieveUserName

protected String retrieveUserName(org.springframework.security.core.Authentication authentication)

### retrievePassword

protected String retrievePassword(org.springframework.security.core.Authentication authentication)