Hilla Documentation

Stateless Authentication With Spring Security

Using stateless authentication to persist authentication on the client side between requests.

After a user logs in, the web application has to persist the authentication data over server requests, so that the user is not asked to log in again for every single action. Stateless authentication presents a way to persist the authentication data on the client side between requests.

Unlike server-side authentication storage solutions, which commonly rely on sessions, stateless authentication does not require you to keep track of sessions on the server.

When to Use Stateless Authentication

Using stateless authentication brings benefits in the following use cases:

Horizontal scaling of the backend

Helps to avoid the complexity of managing shared or sticky sessions between multiple backend servers.

Seamless deployment

Backend servers can be restarted without logging users out, and without the need for session persistence.

Offline logout for client-side applications

Users can log off and have their authentication data destroyed on the client without requesting a logout from the server.

Hilla provides stateless authentication support in applications using Spring Security. Under the hood, it uses a signed JSON Web Token (JWT) stored in a cookie pair: the token content in the JS-accessible cookie, and the signature in the HTTP-only cookie.

Enabling Stateless Authentication

The following examples describe the steps to enable stateless authentication in a Hilla application that uses Spring Security.

Step 1: Dependencies

Add the following dependencies to the project’s pom.xml:


Step 2: Configure Spring Security

Modify the Spring Security configuration and use the HillaWebSecurityConfigurerAdapter.setStatelessAuthentication() method to set up stateless authentication, as follows:

public class SecurityConfig extends VaadinWebSecurityConfigurerAdapter {

    private String authSecret;

    protected void configure(HttpSecurity http) throws Exception {


        setLoginView(http, "/login");

                new SecretKeySpec(Base64.getDecoder().decode(authSecret), 1
                        JwsAlgorithms.HS256), 2
                "com.example.application" 3
  1. Sets the secret key that is used for signing and verifying the JWT.

  2. Sets the JWT signature algorithm. Note that the key length should match the algorithm chosen. For example, the HS256 algorithm used here requires a 32-byte secret key.

  3. Sets the issuer JWT claim – a string or a URL that identifies your application.

Secret-key considerations
  • The secret key must be unique to your application.

  • Use different keys in the development, staging, and production environments.

  • Do not commit the secret key into the repository.

The security configuration given here gets the secret key from the Base64-encoded my.app.auth.secret string property. You should configure the property value in your environment accordingly.

To avoid hard-coding the value and committing it into the repository, you can create a separate application.properties file in the config/local/ subdirectory and instruct Git to ignore the directory.

For example:

mkdir -p config/local/

echo "
# Contains secrets that shouldn’t go into the repository
config/local/" >> .gitignore

echo "my.app.auth.secret=$(openssl rand -base64 32)" > config/local/application.properties

Spring Boot supports many ways of configuring properties. See the Externalized Configuration feature section in the Spring Boot Reference.

Step 3: Handle the JWT Authentication Principal

The authentication principal is a JWT

When using stateless authentication, the SecurityContext.getAuthentication().getPrincipal() call returns a Jwt instance that contains only the username and roles.

In your application, you need to verify that the reference returned by Authentication.getPrincipal() is a Jwt instance.

In applications that use username-and-password authentication, you may need to access the full UserDetails instance for the current user. You can use the UserDetailsService to load the user details via the username from the JWT:

public class SecurityUtils  {

    private UserDetailsService userDetailsService;

    public Optional<UserDetails> getAuthenticatedUser() {
        SecurityContext context = SecurityContextHolder.getContext();
        Object principal = context.getAuthentication().getPrincipal();
        if (principal instanceof Jwt) {
            String username = ((Jwt) principal).getSubject();
            return Optional.of(userDetailsService.loadUserByUsername(username));
        // Anonymous or no authentication.
        return Optional.empty();


Step 4: Verify

After the step 3, your application should be using stateless authentication.

To verify this:

  1. start the development server and open your application

  2. log in

  3. restart the development server

You should remain logged in after the restart.

JWT Expiration

By default, the JWT and cookies expire 30 minutes after the last server request. You can customize the expiration period by using an additional duration argument for the configuration method.

For example:

public class SecurityConfig extends HillaWebSecurityConfigurerAdapter {
    protected void configure(HttpSecurity http) throws Exception {
            new SecretKeySpec(Base64.getDecoder().decode("..."),
            3600 // The JWT lifetime in seconds