Migrate Application from Spring Security 5 to Spring Security 6/Spring Boot 3

1. Overview

Spring Security 6 comes with several major changes, including the removal of classes, and deprecated methods, and the introduction of new methods.

Migrating from Spring Security 5 to Spring Security 6 can be done incrementally without breaking the existing code base. Also, we can use third-party plugins like OpenRewrite to facilitate migration to the latest version.

In this tutorial, we’ll learn how to migrate an existing application using Spring Security 5 to Spring Security 6. We’ll replace deprecated methods and utilize lambda DSL to simplify configuration. Also, we’ll utilize OpenRewrite to make migration faster.

2. Spring Security and Spring Boot Version

Spring Boot is based on the Spring framework, and the versions of Spring Boot use the latest version of the Spring framework. Spring Boot 2 defaults to Spring Security 5, while Spring Boot 3 uses Spring Security 6.

To use Spring Security in a Spring Boot application, we always add the spring-boot-starter-security dependency to the pom.xml.

However, we can override the default Spring Security version by specifying a desired version in the properties section of pom.xml:

<properties>
    <spring-security.version>5.8.9</spring-security.version>
</properties>

Here, we specify that we are using Spring Security 5.8.9 in our project, overwriting the default version.

Notably, we can also use Spring Security 6 in Spring Boot 2 by overriding the default version in the properties section.

3. What’s New in Spring Security 6

Spring Security 6 introduces several feature updates to improve security and robustness. It now requires at least Java version 17 and uses the jakarta namespace.

One of the major changes is the removal of WebSecurityConfigurerAdapter in favor of component-based security configuration.

Also, the authorizeRequests() is removed and replaced with authorizeHttpRequests() to define authorization rules.

Furthermore, it introduces methods like requestMatcher() and securityMatcher() to replace antMatcher() and mvcMatcher() for configuring security for request resources. The requestMatcher() method is more secure because it chooses the appropriate RequestMatcher implementation for request configuration.

Other deprecated methods like cors() and csrf() now have functional style alternatives.

4. Project Setup

To begin, let’s bootstrap a Spring Boot 2.7.5 project by adding spring-boot-starter-web and spring-boot-starter-security to the pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>2.7.5</version>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
    <version>2.7.5</version>
</dependency>

The spring-boot-starter-security dependency uses the Spring Security 5.

Next, let’s create a class named WebSecurityConfig:

@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
class WebSecurityConfig extends WebSecurityConfigurerAdapter {
}

Here, we annotate the class with @EnableWebSecurity to initiate the process of configuring security for web requests. Also, we enable method-level authorization. Next, the class extends the WebSecurityConfigurerAdapter class to provide various security configuration methods.

Furthermore, let’s define an in-memory user for authentication:

@Override
void configure(AuthenticationManagerBuilder auth) throws Exception {
    UserDetails user = User.withDefaultPasswordEncoder()
      .username("Admin")
      .password("password")
      .roles("ADMIN")
      .build();
    auth.inMemoryAuthentication().withUser(user);
}

In the method above, we create an in-memory user by overriding the default configuration.

Moving on, let’s exclude static resources from the security by overriding the configure(WebSecurity web) method:

@Override
void configure(WebSecurity web) {
    web.ignoring().antMatchers("/js/**", "/css/**");
}

Finally, let’s create HttpSecurity by overriding the configure(HttpSecurity http) method:

@Override
void configure(HttpSecurity http) throws Exception {
    http
      .authorizeRequests()
      .antMatchers("/").permitAll()
      .anyRequest().authenticated()
      .and()
      .formLogin()
      .and()
      .httpBasic();
}

Notably, this setup showcases typical Spring Security 5 configuration. In the subsequent section, we’ll migrate this code to Spring Security 6.

5. Migrating Project to Spring Security 6

Spring recommends an incremental migration approach to prevent breaking existing code when updating to Spring Security 6. Before upgrading to Spring Security 6, we can first upgrade our Spring Boot application to Spring Security 5.8.5 and update the code to use new features. Migrating to 5.8.5 prepares us for expected changes in version 6.

While migrating incrementally, our IDE can warn us of deprecated features. This aids the incremental update process.

For simplicity, let’s migrate the sample project straight to Spring Security 6 by updating the application to use Spring Boot version 3.3.2. In a case where the application uses Spring Boot version 2, we can specify Spring Security 6 in the properties section.

To begin the migration process, let’s modify the pom.xml to use the latest Spring Boot version:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>3.3.2</version>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
    <version>3.3.2</version>
</dependency>

In the initial setup, we use Spring Boot 2.7.5, which uses Spring Security 5 under the hood.

Notably, the minimum Java version for Spring Boot 3 is Java 17.

In the subsequent sub-sections, we’ll refactor the existing code to use Spring Security 6.

5.1. @Configuration Annotation

Before Spring Security 6, the @Configuration annotation is part of @EnableWebSecurity, but with the latest update, we have to annotate our security configuration with the @Configuration annotation:

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class WebSecurityConfig extends WebSecurityConfigurerAdapter {
}

Here, we introduce the @Configuration annotation to the existing code base because it’s no longer part of the @EnableWebSecurity annotation. Also, the annotation is no longer part of @EnableMethodSecurity, @EnableWebFluxSecurity, or @EnableGlobalMethodSecurity annotations.

Additionally, @EnableGlobalMethodSecurity is marked for deprecation and to be replaced by @EnableMethodSecurity. By default, it enables Spring’s pre-post annotations. Hence, we introduce @EnableMethodSecurity to provide authorization at the method level

5.2. WebSecurityConfigurerAdapter

The latest update removes the WebSecurityConfigurerAdapter class and adopts component-based configuration:

@Configuration
@EnableWebSecurity
public class WebSecurityConfig {
}

Here, we remove the WebSecurityConfigurerAdapter, and this eliminates overriding methods for security configuration. Instead, we can register a bean for security configuration. We can register the WebSecurityCustomizer bean to configure web security, the SecurityFilterChain bean to configure HTTP security, the InMemoryUserDetails bean to register custom users, etc.

5.3. WebSecurityCustomizer Bean

Let’s modify the method that excludes static resources by publishing a WebSecurityCustomizer bean:

@Bean
WebSecurityCustomizer webSecurityCustomizer() {
   return (web) -> web.ignoring().requestMatchers("/js/**", "/css/**");
}

The WebSecurityCustomizer interface replaces configure(Websecurity web) from the WebSecurityConfigurerAdapter interface.

5.4. AuthenticationManager Bean

In the earlier section, we created an in-memory user by overriding configure(AuthenticationManagerBuilder auth) from the WebSecurityConfigurerAdapter.

Let’s refactor the authentication credentials logic by registering InMemoryUserDetailsManager bean instead:

@Bean
InMemoryUserDetailsManager userDetailsService() {
    UserDetails user = User.withDefaultPasswordEncoder()
      .username("Admin")
      .password("admin")
      .roles("USER")
      .build();

    return new InMemoryUserDetailsManager(user);
}

Here, we define an in-memory user with a USER role to provide role-based authorization.

5.5. HTTP Security Configuration

In the previous Spring Security version, we configure HttpSecurity by overriding the configure method from the WebSecurityConfigurer class. Since it’s removed in the latest version, let’s register the SecurityFilterChain bean for HTTP security configuration:

@Bean
SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http
      .authorizeHttpRequests(
          request -> request
            .requestMatchers("/").permitAll()
            .anyRequest().authenticated()
      )
      .formLogin(Customizer.withDefaults())
      .httpBasic(Customizer.withDefaults());
   return http.build();
}

In the code above, we replace the authorizeRequest() method with authorizeHttpRequests(). The new method uses AuthorizationManager API, which simplifies reuse and customization.

Additionally, it improves performance by delaying authentication lookup. Authentication lookup occurs only when a request requires authorization.

When we don’t have a customized rule, we use the Customizer.withDefaults() method to use the default configuration.

Additionally, we use requestMatchers() instead of antMatcher() or mvcMatcher() to secure resources.

5.6. RequestCache

The request cache helps save user requests when they are required to authenticate and redirect users to the request once they successfully authenticate. Before Spring Security 6, RequestCache checks on every incoming request to see if there are any saved requests to redirect to. This read the HttpSession on every RequestCache.

However, in Spring Security 6, the request cache only checks if the request contains a special parameter name “continue“. This improves performance and prevents unnecessary reading of HttpSession.

6. Using OpenRewrite

Moreover, we can use third-party tools like OpenRewrite to migrate an existing Spring Boot application to Spring Boot 3. Since Spring Boot 3 uses Spring Security 6, it also migrates the security configuration to version 6.

To use OpenRewrite, we can add a plugin to the pom.xml:

<plugin>
    <groupId>org.openrewrite.maven</groupId>
    <artifactId>rewrite-maven-plugin</artifactId>
    <version>5.23.1</version>
    <configuration>
        <activeRecipes>
            <recipe>org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_0</recipe>
        </activeRecipes>
    </configuration>
    <dependencies>
        <dependency>
            <groupId>org.openrewrite.recipe</groupId>
            <artifactId>rewrite-spring</artifactId>
            <version>5.5.0</version>
        </dependency>
    </dependencies>
</plugin>

Here, we specify upgrading to Spring Boot version 3 through the recipe property. OpenRewrite has a lot of recipes to choose from for upgrading a Java project.

Finally, let’s run the migration command:

$ mvn rewrite:run

The command above migrates the project to Spring Boot 3, including the security configuration. However, OpenRewrite currently doesn’t use lambda DSL for the migrated security configuration. Of course, this is likely to change in future releases.

7. Conclusion

In this article, we saw a step-by-step guide for migrating an existing code base using Spring Security 5 to Spring Security 6 by replacing deprecated classes and methods. Additionally, we saw how to use a third-party plugin to automate the migration.