Build a Basic Login Form With Spring Security, Thymeleaf, and Java

This short tutorial will show you how to build a basic login form using Spring Boot, Spring Security, and Thymeleaf.

Mar 18, 2025

Hello Java developers! If you are developing Spring boot-based applications, Spring Security is the de facto standard for securing your Spring-based applications.

In this short tutorial, we'll build a basic login form using Spring Boot, Spring Security, and Thymeleaf.

First, let's briefly cover some project files that are of less interest:

Application.java contains our main method and the @SpringBootApplication annotation. The standard way to start a spring boot application.
A CSS stylesheet is located under src/main/resources/static/css/to make the demo pretty.
Some Thymeleaf HTML templates are under src/main/resources/ for demo purposes.
Finally, an application.properties file is located under src/main/resources, where we can pass configuration parameters to our spring boot application. A complete list of configuration options can be found here.

Dependencies

As with all Spring boot applications, many 'Starter' libraries make it easy to add jars to your classpath:

spring-boot-starter-parent — brings in all the required spring dependencies and manages their versions
spring-boot-starter-thymeleaf — adds thymeleaf-spring5 and thymeleaf-extras-java8time dependencies (more on thymeleaf)
spring-boot-starter-security — adds spring-security-config, spring-security-web, and spring-aop dependencies
spring-boot-starter-test — adds spring-boot-test, junit, hamcrest and mockito
spring-security-test — adds the ability to mock user and user roles

Here is the entire pom.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="<http://maven.apache.org/POM/4.0.0>"
  xmlns:xsi="<http://www.w3.org/2001/XMLSchema-instance>"
  xsi:schemaLocation="<http://maven.apache.org/POM/4.0.0> <http://maven.apache.org/xsd/maven-4.0.0.xsd>">
  <modelVersion>4.0.0</modelVersion>

  <groupId>dev.mwhyte</groupId>
  <artifactId>spring-security-basic</artifactId>
  <version>0.0.1-SNAPSHOT</version>

  <name>spring-security-basic</name>
  <description>An introduction to spring security</description>

  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.6.1</version>
  </parent>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <java.version>17</java.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-thymeleaf</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-security</artifactId>
    </dependency>

    <!-- TEST -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-test</artifactId>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.springframework.security</groupId>
      <artifactId>spring-security-test</artifactId>
      <scope>test</scope>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>
</project>

MvcConfig

package dev.mwhyte.spring.sec.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ViewControllerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class MvcConfig implements WebMvcConfigurer {

  @Override
  public void addViewControllers(ViewControllerRegistry registry) {
    registry.addViewController("/").setViewName("login");
    registry.addViewController("/index").setViewName("index");
    registry.addViewController("/login").setViewName("login");
  }
}

The MvcConfig.java class implements Spring's WebMvcConfigurer interface. It allows you to override the method addViewControllers (and others) to configure simple automated controllers. In this example, we have mapped them to our Thymeleaf views (under src/main/resources).

WebSecurityConfig

package dev.mwhyte.spring.sec.config;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;

@Configuration
@EnableWebSecurity
public class WebSecurityConfig extends WebSecurityConfigurerAdapter {

  @Override
  protected void configure(HttpSecurity http) throws Exception {
    http
        .authorizeRequests()
        .antMatchers("/css/**").permitAll()
        .anyRequest().authenticated()
        .and()
        .formLogin()
        .loginPage("/login")
        .defaultSuccessUrl("/index")
        .permitAll()
        .and()
        .logout()
        .permitAll()
        .and().csrf().disable(); // we'll enable this in a later blog post
  }

  @Autowired
  public void configureGlobal(AuthenticationManagerBuilder auth) throws Exception {
    auth
        .inMemoryAuthentication()
        .withUser("user").password("{noop}pass").roles("USER");
  }
}

A lot is happening in this class as it contains the main security configuration to enable and configure our basic login form.

Extending WebSecurityConfigurerAdapter, another abstract base class, allows you to override certain aspects of Spring security's default configuration. In our case, we are going to override the method configure.

configure(HttpSecurity http) method

Note the parameter passed to this method. There are several different overloaded configure methods. We will be overriding and configuring HttpSecurity specifically

authorizeRequests() — Allows us to configure which resources on our web server to secure. You can see from our example code that we have allowed unsecured access to our CSS directory and requested that all other resources be secured and can only be accessed by an authenticated user.
formLogin() — Tells Spring Security we wish to use a login form. We provide the URL we want to redirect to if the authentication is successful, and finally, we permit access to the login and logout endpoints.
We are disabling cross-site request forgery protection, which is enabled by default. We will cover this later in the series.

configureGlobal method

This method allows us to autowire an AuthenticationManager class globally throughout our application. We’ll use a basic in-memory approach with one user and one user role for this example.

Thymeleaf namespace

A few things to note in our login.html file:

The thymeleaf Spring-security namespace:

<html
  xmlns="<http://www.w3.org/1999/xhtml>"
  xmlns:th="<http://www.thymeleaf.org>"
  xmlns:sec="<http://www.thymeleaf.org/thymeleaf-extras-springsecurity3>"
></html>

The thymeleaf action instructs the form to make a POST request to the URL provided (/login):

<form th:action="@{/login}" method="post" class="form login"></form>

The thymeleaf if condition can check for URL parameters, error and log out responses and display content if they return true:

<div class="text--center" th:if="${param.error}">Invalid username and password.</div>
<div class="text--center" th:if="${param.logout}">You have been logged out.</div>

Complete list of what's available on the thymeleaf website

Unit Testing

package dev.mwhyte.spring.sec;

import static org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestBuilders.formLogin;
import static org.springframework.security.test.web.servlet.response.SecurityMockMvcResultMatchers.authenticated;
import static org.springframework.security.test.web.servlet.response.SecurityMockMvcResultMatchers.unauthenticated;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.redirectedUrlPattern;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.security.test.context.support.WithMockUser;
import org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestBuilders.FormLoginRequestBuilder;
import org.springframework.test.context.junit.jupiter.SpringExtension;
import org.springframework.test.web.servlet.MockMvc;

@ExtendWith(SpringExtension.class)
@SpringBootTest
@AutoConfigureMockMvc
public class ApplicationTests {

  @Autowired
  private MockMvc mockMvc;

  @Test
  public void loginWithValidUserThenAuthenticated() throws Exception {
    FormLoginRequestBuilder login = formLogin()
        .user("user")
        .password("pass");

    mockMvc.perform(login)
        .andExpect(authenticated().withUsername("user"));
  }

  @Test
  public void loginWithInvalidUserThenUnauthenticated() throws Exception {
    FormLoginRequestBuilder login = formLogin()
        .user("invalid")
        .password("invalidpassword");

    mockMvc.perform(login)
        .andExpect(unauthenticated());
  }

  @Test
  public void accessUnsecuredResourceThenOk() throws Exception {
    mockMvc.perform(get("/css/style.css"))
        .andExpect(status().isOk());
  }

  @Test
  public void accessSecuredResourceUnauthenticatedThenRedirectsToLogin() throws Exception {
    mockMvc.perform(get("/hello"))
        .andExpect(status().is3xxRedirection())
        .andExpect(redirectedUrlPattern("**/login"));
  }

  @Test
  @WithMockUser
  public void accessSecuredResourceAuthenticatedThenOk() throws Exception {
    mockMvc.perform(get("/index"))
        .andExpect(status().isOk());
  }
}

@ExtendWith(SpringExtension.class) — Tells JUnit5 to run unit tests with Spring's testing support

@SpringBootTest — Run as spring boot app. i.e. load application.properties and spring beans

@AutoConfigureMockMvc — Creates a Test helper class called MockMvc. We can imitate a front-end client making requests to the server from this.

@WithMockUser — Provides the ability to mock certain users—an authenticated user in our case.

FormLoginRequestBuilder — A utility class that allows us to create a form-based login request.

Demo

To run the demo, you can find the complete code for this example on GitHub

Open the Application.java class and right-click run. The port 8080 must be available on your machine to start the demo. If it is not, you can change this default in the application.properties file using: