Spring Boot Security Form-Based Authentication Tutorial

In this tutorial, we will walk through the process of setting up form-based authentication in a Spring Boot application using the latest version of Spring Security. We'll cover creating a simple Spring Boot application, configuring Spring Security for form-based authentication, and securing a web application with a custom login page.

What is Form-Based Authentication?

Form-based authentication is a popular method in which users are required to log in through a web login form. Upon successful authentication, users are granted access to protected resources. This method allows for a customizable user experience, as the login form can be styled and designed to match the look and feel of the application.


Before we start, ensure you have the following:

  • Java Development Kit (JDK) installed
  • Apache Maven installed
  • An IDE (Integrated Development Environment) like IntelliJ IDEA or Eclipse

Step 1: Setting Up the Project

Create a Spring Boot Project

  1. Open your IDE and create a new Spring Boot project using Spring Initializr.
  2. Add the following dependencies:
    • Spring Web
    • Spring Security
    • Spring Data JPA
    • H2 Database (for simplicity, but you can use any database of your choice)
    • Spring Boot Starter Thymeleaf (for creating simple views)

Project Structure

Your project structure should look like this:

├── src
│   ├── main
│   │   ├── java
│   │   │   └── com
│   │   │       └── example
│   │   │           └── security
│   │   │               ├── SecurityConfig.java
│   │   │               ├── SecurityApplication.java
│   │   │               ├── model
│   │   │               │   └── User.java
│   │   │               ├── repository
│   │   │               │   └── UserRepository.java
│   │   │               ├── service
│   │   │               │   └── UserService.java
│   │   │               └── controller
│   │   │                   └── HomeController.java
│   ├── main
│   │   └── resources
│   │       ├── templates
│   │       │   ├── home.html
│   │       │   ├── login.html
│   │       └── application.properties
└── pom.xml

Step 2: Adding Dependencies

Add the necessary dependencies for Spring Security, Spring Data JPA, H2 database, and Thymeleaf in the pom.xml file.


        <!-- Spring Boot Starter Web -->

        <!-- Spring Boot Starter Security -->

        <!-- Spring Boot Starter Data JPA -->

        <!-- H2 Database -->

        <!-- Thymeleaf -->

        <!-- Spring Boot Starter Test -->

Step 3: Configuring the Application Properties

Configure the application properties for the H2 database and other settings.


# H2 Database configuration

# JPA settings

# Thymeleaf settings

Step 4: Creating the User Entity

Create a User entity in the com.example.security.model package.


package com.example.security.model;

import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;

public class User {

    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String username;
    private String password;
    private String role;

    // Getters and Setters

    public Long getId() {
        return id;

    public void setId(Long id) {
        this.id = id;

    public String getUsername() {
        return username;

    public void setUsername(String username) {
        this.username = username;

    public String getPassword() {
        return password;

    public void setPassword(String password) {
        this.password = password;

    public String getRole() {
        return role;

    public void setRole(String role) {
        this.role = role;

Step 5: Creating the User Repository

Create a UserRepository interface in the com.example.security.repository package.


package com.example.security.repository;

import com.example.security.model.User;
import org.springframework.data.jpa.repository.JpaRepository;

public interface UserRepository extends JpaRepository<User, Long> {
    User findByUsername(String username);

Step 6: Creating the User Service

Create a UserService class in the com.example.security.service package.


package com.example.security.service;

import com.example.security.model.User;
import com.example.security.repository.UserRepository;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.core.userdetails.UsernameNotFoundException;
import org.springframework.security.core.userdetails.User;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.stereotype.Service;

import javax.annotation.PostConstruct;
import java.util.HashSet;

public class UserService implements UserDetailsService {

    private UserRepository userRepository;

    private PasswordEncoder passwordEncoder;

    public void init() {
        User admin = new User();

        User user = new User();

    public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {
        com.example.security.model.User user = userRepository.findByUsername(username);
        if (user == null) {
            throw new UsernameNotFoundException("User not found");
        return User.builder()

Step 7: Configuring Spring Security

Create a SecurityConfig class in the com.example.security package to configure Spring Security for form-based authentication.


package com.example.security;

import com.example.security.service.UserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
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.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.web.SecurityFilterChain;

public class SecurityConfig {

    private UserService userService;

    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
            .authorizeHttpRequests(authorizeRequests ->
                    .requestMatchers("/h2-console/**").permitAll()  // Allow access to H2

                    .requestMatchers("/", "/home").permitAll()
            .formLogin(formLogin ->
                    .defaultSuccessUrl("/home", true)
            .logout(logout ->

        // Disable CSRF and frame options for H2 console

        return http.build();

    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();

    public void configureGlobal(AuthenticationManagerBuilder auth) throws Exception {

Step 8: Creating the Home Controller

Create a HomeController class in the com.example.security.controller package.


package com.example.security.controller;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;

public class HomeController {

    public String root() {
        return "index";

    public String home() {
        return "home";

    public String login() {
        return "login";

Step 9: Creating the Views

Create simple HTML views for the home page, login page, and index page in the src/main/resources/templates directory.


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
    <h1>Welcome to the Home Page!</h1>
        <a href="/logout" th:href="@{/logout}">Logout</a>


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
    <form th:action="@{/login}" method="post">
            <input type="text" name="username"/>
            <input type="password" name="password"/>
            <button type="submit">Login</button>


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
    <h1>Welcome to the Application!</h1>
        <a href="/login" th:href="@{/login}">Login</a>

Step 10: Creating the Main Application Class

Create the main application class to run your Spring Boot application.


package com.example.security;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

public class SecurityApplication {

    public static void main(String[] args) {
        SpringApplication.run(SecurityApplication.class, args);

Step 11: Running the Application

To run the application, execute the SecurityApplication class. This will start the Spring Boot application with Spring Security configured for form-based authentication.

Accessing the Application

  1. Open your browser and navigate to http://localhost:8080/h2-console to access the H2 database console. Use the JDBC URL jdbc:h2:mem:testdb, username sa, and an empty password to log in.
  2. Navigate to http://localhost:8080/ to access the index page.
  3. Navigate to http://localhost:8080/login to access the login page. Use the credentials defined in your UserService:
    • username: admin
    • password: admin
    • username: user
    • password: password

After logging in, you will be redirected to the home page.


In this tutorial, we have walked through setting up a basic Spring Boot application and integrating it with Spring Security for form-based authentication. We configured Spring Security to secure our application with a custom login form and created a simple web application with Thymeleaf views. By following this tutorial, you should now have a good understanding of how to integrate Spring Security with Spring Boot and secure your web applications using form-based authentication.