The SOLID principles are fundamental to object-oriented design, fostering modular, testable, and adaptable code.

1. Single Responsibility Principle (SRP)

A class should have one and only one reason to change, meaning that a class should have only one job.

This principle ensures that a class has a single responsibility, making it easier to maintain and modify without impacting other parts of the system. For example, a ReportGenerator class should handle report creation, while a ReportSaver class saves reports to storage.

2. Open/Closed Principle (OCP)

Objects or entities should be open for extension but closed for modification.

This principle encourages adding new functionality through extension rather than modifying existing code. For instance, if you have a Shape interface, new shapes like Circle or Square can be added without altering the existing implementation.

3. Liskov Substitution Principle (LSP)

Derived classes must be substitutable for their base classes

A subclass should not break the behaviour expected from its superclass. For example, if a Bird class has a method fly(), a Penguin subclass shouldn't override it with a "not implemented" exception—it breaks the principle.

4. Interface Segregation Principle (ISP)

A client should never be forced to implement an interface that it doesn’t use, or clients shouldn’t be forced to depend on methods they do not use.

Instead of having one large interface, split it into smaller, more specific interfaces. For example, instead of a Vehicle interface with unrelated methods like fly() and drive(), create separate interfaces like FlyingVehicle and DrivingVehicle.

5. Dependency Inversion Principle (DIP)

Depend on abstractions, not on concretions

This principle suggests that high-level modules should not depend on low-level modules. Both should depend on abstractions. Dependency injection frameworks often embody this principle.

DRY (Don’t Repeat Yourself)

Every piece of knowledge must have a single, unambiguous, authoritative representation within a system

Duplication in code leads to inconsistencies and additional maintenance efforts. If you find yourself repeating code, abstract it into reusable functions or modules.

YAGNI (You Ain’t Gonna Need It)

Don’t implement something until you actually need it

Avoid speculative development. Over-engineering adds unnecessary complexity and often wastes time. Build only what you need for the current requirements.

KISS (Keep It Simple, Stupid)

Simplicity is the ultimate sophistication

Write code that is simple to read, understand, and maintain. While overly complex solutions may seem clever, they often lead to bugs and technical debt.

Law of Demeter (LoD)

Talk only to your immediate friends

A module should only communicate with its direct dependencies and not with the dependencies of those dependencies. For example, avoid chaining method calls like a.getB().getC().doSomething();. Instead, encapsulate such interactions.

Composition Over Inheritance

Favor composition over inheritance

Inheritance often leads to tightly coupled code and an inflexible hierarchy. Composition, on the other hand, promotes reusability by combining behaviours through interfaces or mixins. For example, instead of a monolithic Animal class with dozens of subclasses, create composable behaviours like Swimmer, Flyer, or Walker.

Encapsulate What Varies

Identify the aspects of your application that vary and separate them from what stays the same

This principle is fundamental to design patterns like Strategy and Factory. For example, if you have different ways to calculate discounts, encapsulate the logic into separate classes instead of hardcoding it.

Hollywood Principle

Don’t call us, we’ll call you

This principle encourages frameworks or inversion of control, where the framework dictates the flow. For instance, in an event-driven system, the framework invokes your code in response to specific events.

Program Against Abstractions

Depend on interfaces or abstract classes rather than concrete implementations

This principle promotes flexibility and testability. For example, instead of directly using a concrete FileLogger class, depend on a Logger interface, which allows you to swap implementations easily.

Books

Some recommended books to explore the concepts further:

Clean Code: A Handbook of Agile Software Craftsmanship (Robert C. Martin) (Robert C. Martin Series)

Pragmatic Programmer, The: Your journey to mastery, 20th Anniversary Edition

Designing Data-Intensive Applications: The Big Ideas Behind Reliable, Scalable, and Maintainable Systems

In May 2020, Google announced that Java 11 was coming to Google Cloud Functions.

Naturally, I thought, “Excellent, but can I write functions in other JVM-based languages like Kotlin?”

Thankfully, there is no such limitation. You can write your functions in any JVM language of your choosing.

The source code for this example can be found on GitHub:

https://github.com/mwhyte-dev/kotlin-google-cloud-function

Prerequisites

You’ll need some things to follow along with this example:

• Java 11

• Gradle

• Access to GCP with a sample project created

• gcloud installed and authenticated

• The source code is cloned and imported into your IDE of choice

Main Function

The main function is a straightforward one to get us started — a basic HTTP endpoint that will return the string “FUNCTION COMPLETE” when triggered:

This class extends HttpFunction from the functions-framework library. The service function takes an HttpRequest an HttpResponse object as parameters.

For non-HTTP ways to trigger a cloud function, you can use a RawBackgroundFunction or a typed variant.

For example: BackgroundFunction<PubSubMessage>

Some other options for triggering functions include Cloud Pub/Sub, Cloud Storage, Cloud Firestore, and various Firebase-based triggers.

You can find examples of other triggering mechanisms in the functions-framework-java readme.

Gradle Build File

We use Gradle’s Kotlin DSL to configure our project for this example.

Dependencies

There are a few critical dependencies.

• The Functions-framework-API allows us to write lightweight functions that run across many environments, including Google Cloud Functions and Cloud Run.

• Java-function-invoker enables us to run the function locally for testing.

runFunction Task

The runFunction task in the Gradle build file triggers the java-function-invoker, which wraps the function and serves it using a Jetty web server.

To run the function locally, call runFunction using the Gradle wrapper:

Optionally, you can override some args:

buildFunction Task

The buildFunction task in the Gradle build file works with the Gradle Shadow plugin to create a fat jar and copy it to the build/deploy directory. The jar is then ready to be uploaded to GCP Cloud Storage.

To execute this, use the Gradle wrapper:

Deploying with gcloud

So you’ve tested your function locally, built it, and now it's time to deploy. The gcloud command-line utility makes deployment easy.

First, ensure you are deploying to the GCP Project of your choice:

Then select the region you wish to deploy to :

Lastly, deploy the function:

Note: The entry-point argument is the function's fully qualified class name, and the source is the location of our fat jar.

If you open the GCP console and navigate to Cloud Functions, you’ll see the function:

You can open it here and view various information, including the trigger. Alternatively, you can run a describe from gcloud:

By hitting the trigger URL, you will see the function return the expected response:

References

We’ve seen how easy it is to deploy a Kotlin function to GCP. To explore the topic further, I’d recommend the following documentation:

https://github.com/mwhyte-dev/kotlin-google-cloud-function

Cloud Run functions documentation | Cloud Run functions Documentation | Google Cloud

https://github.com/GoogleCloudPlatform/functions-framework-java

https://github.com/GoogleCloudPlatform/functions-framework-java/issues/35

In the last lesson, we expanded on the first by adding different user roles and showing and hiding front-end content based on these roles (User Roles and Thymeleaf Extras).

Today, we'll look at redirecting users with different roles to different pages after logging in.

Admin.html

Following our previous example, we've created a new HTML file called admin.html. When our admin users log in, we will redirect them to this new page.

  <!DOCTYPE html>
  <html xmlns="<http://www.w3.org/1999/xhtml>" xmlns:th="<http://www.thymeleaf.org>">

  <head>
      <title>codenerve.com - Welcome!</title>
      <meta charset="UTF-8">
      <title>Admin</title>
      <link href="<https://fonts.googleapis.com/css?family=Open+Sans:400,700>" rel="stylesheet">
      <link rel="stylesheet" href="css/style.css">
  </head>
      <body>
          <h1 th:inline="text">Hello [[${#httpServletRequest.remoteUser}]]!</h1>

          <div>
               Custom administrator page.
          </div>


          <br/>
          <form th:action="@{/logout}" method="post">
              <input type="submit" value="Sign Out"/>
          </form>
      </body>
  </html>

MvcConfig

To serve the new admin.html page, we must add this page to our MvcConfig class.

As with the previous examples, this is accomplished by creating a class extending WebMvcConfigurerAdapter and overriding the addViewControllers method.

This time, we are adding all the earlier pages of our app and the new admin page:

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("/admin").setViewName("admin");
        registry.addViewController("/login").setViewName("login");
    }
}

WebSecurityConfig

The Constructor

To decide what to do when different user roles log in. We've created a new field of type AuthenticationSuccessHandler. We're setting this new configuration bean via constructor injection.

configure method

This method is responsible for explicitly overriding and configuring HttpSecurity. We've added two lines from the last example.

First, we've added a new antMatcher under the authorizeRequests section, and we've told spring security only to allow a user with the “ADMIN” role access to all endpoints starting with “/admin”:

.antMatchers("/admin").hasRole("ADMIN")

Secondly, we've added our CustomAuthenticationSuccessHandler under the formLogin section to tell Spring security to ask this CustomAuthenticationSuccessHandler what to do when a successful login occurs:

.successHandler(authenticationSuccessHandler)

configureGlobal method

The configureGlobal method is our in-memory registry of users. We've added two users. One with the primary USER role and the other with the ADMIN role.

Full example:

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;
import org.springframework.security.web.authentication.AuthenticationSuccessHandler;

@Configuration
@EnableWebSecurity
public class WebSecurityConfig extends WebSecurityConfigurerAdapter {

    private AuthenticationSuccessHandler authenticationSuccessHandler;

    @Autowired
    public WebSecurityConfig(AuthenticationSuccessHandler authenticationSuccessHandler) {
        this.authenticationSuccessHandler = authenticationSuccessHandler;
    }

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
                .authorizeRequests()
                .antMatchers( "/css/**", "/images/**", "/favicon.ico").permitAll()
                .antMatchers("/admin").hasRole("ADMIN")
                .anyRequest().authenticated()
                .and()
                .formLogin()
                .loginPage("/login")
                .successHandler(authenticationSuccessHandler)
                .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")
                .and()
                .withUser("admin").password("{noop}pass").roles("ADMIN");
    }
}

CustomAuthenticationSuccessHandler

As you can see from our sample code below, this class implements Springs AuthenticationSuccessHandler class and overrides the onAuthenticationSuccess method.

Once a user successfully logs in, the onAuthenticationSuccess method is called, and the user's role is checked. If the user's role is admin, we redirect to the /admin HTTP endpoint; otherwise, we redirect them to the /index endpoint.

Our MvcConfig takes over and serves the correct HTML page based on the viewController we created previously.

package dev.mwhyte.spring.sec.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.authority.AuthorityUtils;
import org.springframework.security.web.authentication.AuthenticationSuccessHandler;

import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.util.Set;

@Configuration
public class CustomAuthenticationSuccessHandler implements AuthenticationSuccessHandler {

    @Override
    public void onAuthenticationSuccess(HttpServletRequest httpServletRequest, HttpServletResponse httpServletResponse, Authentication authentication) throws IOException, ServletException {

        Set<String> roles = AuthorityUtils.authorityListToSet(authentication.getAuthorities());

        if (roles.contains("ROLE_ADMIN")) {
            httpServletResponse.sendRedirect("/admin");
        } else {
            httpServletResponse.sendRedirect("/index");
        }
    }
}

Demo

Check out the source code, open the Application class, and right-click to run the demo.

To start the example, port 8080 must be available on your machine. If it is not, you can change this default in the application.properties file using:

server.port=8081

Set this to whatever value you wish.

Alternatively, you can watch this short video:

Unit Testing

As always, we've amended and added some additional tests to cover the new functionality:

package dev.mwhyte.spring.sec;

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;

import static org.hamcrest.core.StringContains.containsString;
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.*;

@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());
	}

	@Test
	@WithMockUser(roles = "USER")
	public void loginWithRoleUserThenExpectAdminPageForbidden() throws Exception {
		mockMvc.perform(get("/admin"))
				.andExpect(status().isForbidden());
	}

	@Test
	@WithMockUser(roles = "ADMIN")
	public void loginWithRoleAdminThenExpectAdminContent() throws Exception {
		mockMvc.perform(get("/admin"))
				.andExpect(status().isOk())
				.andExpect(content().string(containsString("Custom administrator page.")));
	}

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

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

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

		mockMvc.perform(login)
				.andExpect(authenticated().withUsername("admin"))
				.andExpect(redirectedUrl("/admin"));
	}
}

Here is a quick recap of the Spring test support we're using:

• @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. From this, we can imitate a front-end client making requests to the server.

• @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.

Next, we will cover Spring Security's Cross-Site Request Forgery (CSRF) protection.

Resources

GitHub - mwhyte-dev/spring-security at 3.redirect-based-on-role

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

Spring Security — User Roles and ThymeLeaf Extras

Spring Security

Thymeleaf + Spring Security integration basics - Thymeleaf

The last lesson taught us how to use spring security to build a basic login form.

Today, we'll be looking at adding user roles and some excellent features of the Thymeleaf library, including the ability to show and hide content based on these roles.

Dependencies

As with all Spring boot applications, some starter libraries make adding jars to your classpath easy.

<?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>
		<dependency>
			<groupId>org.thymeleaf.extras</groupId>
			<artifactId>thymeleaf-extras-springsecurity5</artifactId>
			<version>3.0.4.RELEASE</version>
		</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>

WebSecurityConfig

First, we'll add another user to our application's WebSecurityConfig.configureGlobal method.

This time, giving them a new role as admin. The existing user has been granted the user role — roles("USER") :

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/**", "/images/**", "/favicon.ico").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")
                .and()
                .withUser("admin").password("{noop}pass").roles("ADMIN");
    }
}

This now gives us two available users to log in with. Each user is configured with a different role that we can now use to hide and show different content.

The remainder of this class remains unchanged, and the key points can be summarised as:

authorizeRequests() — Allows us to configure which resources on our web server to secure.

Our example code shows we have allowed unsecured access to our CSS, images directory, and favicon.

All other resources are 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.

Thymeleaf: Authorize

Next, we'll use the Thymeleaf attribute sec:authorize to check user roles before rendering the divs in our index.html page.

To do this, we first need to add the thymeleaf XML namespace to our index.html.

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

Then, we can use the sec:authorize attribute to check a user’s roles (what they are permitted to see):

<div sec:authorize="hasRole('ADMIN')">This content is only shown to administrators.§§</div>
<div sec:authorize="hasRole('USER')">This content is only shown to users.</div>

As you can see, the attribute sec:authorize is added to each div, and we use the Spring security dialect to check users' Spring security roles. Content will only be rendered if the logged-in user has that role, i.e., hasRole returns true.

It is important to note that content is not just hidden from view but will not be rendered when our application server returns the page to the browser.

Thymeleaf: Authentication

Another useful Thymeleaf feature is the sec:authentication attribute. This attribute can return various security-related metadata.

In the example below, we can retrieve the user's username and roles and display these in our HTML.

<div>
  User: <span sec:authentication="name">NOT FOUND</span> Spring Roles:
  <span sec:authentication="principal.authorities">NOT FOUND</span>
</div>

For more attribute options, see the Thymeleaf documentation

Demo

To run the demo, check out the source code, open the Application class and right-click run.

To start the example, port 8080 must be available on your machine. If it is not, you can change this default in the application.properties file using:

server.port=8081

Set this to whatever value you wish.

Alternatively, you can watch this short video:

Unit Testing

We've added a few more unit tests to cover this new functionality:

package dev.mwhyte.spring.sec;

import org.hamcrest.CoreMatchers;
import org.hamcrest.Matcher;
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;

import static org.hamcrest.core.StringContains.containsString;
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.*;

@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());
    }

    @Test
    @WithMockUser(roles = "USER")
    public void loginWithRoleUserThenExpectUserSpecificContent() throws Exception {
        mockMvc.perform(get("/index"))
                .andExpect(status().isOk())
                .andExpect(content().string(containsString("This content is only shown to users.")))
                .andExpect(content().string(doesNotContainString("This content is only shown to administrators.")));
    }

    @Test
    @WithMockUser(roles = "ADMIN")
    public void loginWithRoleAdminThenExpectAdminSpecificContent() throws Exception {
        mockMvc.perform(get("/index"))
                .andExpect(status().isOk())
                .andExpect(content().string(containsString("This content is only shown to administrators.")))
                .andExpect(content().string(doesNotContainString("This content is only shown to users.")));
    }

    private Matcher<String> doesNotContainString(String s) {
        return CoreMatchers.not(containsString(s));
    }

}

We've created a small utility method doesNotContainString. Using this and Hamcrests's containsString method, we can check whether the content is rendered (or not) based on a particular user role.

Crucially, the spring test annotation @WithMockUser allows us to mock certain users—an authenticated user with user or admin roles in our scenario.

Here is a quick recap of the Spring test support we are using:

• @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. From this, we can imitate a front-end client making requests to the server.

• @WithMockUser — It allows us to mock certain users, such as authenticated users.

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

Next, we will continue to cover Spring Security's user roles, but this time, we will redirect admins to their admin page (admin.html) and secure this page so that only admin users can access it.

Resources

GitHub - mwhyte-dev/spring-security at 2.thymeleaf-extras

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:

server.port=8081

Set this to whatever value you wish.

Alternatively, you can watch this short video:

Next, we will cover Spring Security's user roles and the ability to hide and show content on our site based on the user's entitlements.

Resources

GitHub - mwhyte-dev/spring-security at 1.basic-form-login

Spring Security

Thymeleaf + Spring Security integration basics - Thymeleaf