Unlocking Spring Security Auto‑Configuration in Spring Boot: A Deep Dive

1. Introduction

In previous posts we examined Spring Security's user‑details and password mechanisms. This article continues the series by decoding how Spring Security is auto‑configured within Spring Boot.

2. Spring Boot Auto‑Configuration for Spring Security

The auto‑configuration classes reside under org.springframework.boot.autoconfigure.security.servlet in the current Spring Boot version (2.1.9.RELEASE).

2.1 SecurityAutoConfiguration

package org.springframework.boot.autoconfigure.security.servlet;

import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.boot.autoconfigure.security.SecurityDataConfiguration;
import org.springframework.boot.autoconfigure.security.SecurityProperties;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.ApplicationEventPublisher;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import org.springframework.security.authentication.AuthenticationEventPublisher;
import org.springframework.security.authentication.DefaultAuthenticationEventPublisher;

/**
 * Auto‑configuration for Spring Security.
 */
@Configuration
@ConditionalOnClass(DefaultAuthenticationEventPublisher.class)
@EnableConfigurationProperties(SecurityProperties.class)
@Import({ SpringBootWebSecurityConfiguration.class, WebSecurityEnablerConfiguration.class, SecurityDataConfiguration.class })
public class SecurityAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean(AuthenticationEventPublisher.class)
    public DefaultAuthenticationEventPublisher authenticationEventPublisher(ApplicationEventPublisher publisher) {
        return new DefaultAuthenticationEventPublisher(publisher);
    }
}

SecurityAutoConfiguration

imports three configuration classes ( SpringBootWebSecurityConfiguration, WebSecurityEnablerConfiguration, SecurityDataConfiguration) and registers DefaultAuthenticationEventPublisher as the default AuthenticationEventPublisher in the Spring IoC container.

2.2 SpringBootWebSecurityConfiguration

@Configuration
@ConditionalOnClass(WebSecurityConfigurerAdapter.class)
@ConditionalOnMissingBean(WebSecurityConfigurerAdapter.class)
@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
public class SpringBootWebSecurityConfiguration {

    @Configuration
    @Order(SecurityProperties.BASIC_AUTH_ORDER)
    static class DefaultConfigurerAdapter extends WebSecurityConfigurerAdapter {
    }
}

This class provides the default security configuration for servlet‑based Spring Boot applications. The core is the WebSecurityConfigurerAdapter adapter, which is ordered by SecurityProperties.BASIC_AUTH_ORDER. Developers can extend this adapter for custom security settings.

2.3 WebSecurityEnablerConfiguration

@Configuration
@ConditionalOnBean(WebSecurityConfigurerAdapter.class)
@ConditionalOnMissingBean(name = BeanIds.SPRING_SECURITY_FILTER_CHAIN)
@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
@EnableWebSecurity
public class WebSecurityEnablerConfiguration {
}

This configuration activates @EnableWebSecurity when the required conditions are met, effectively enabling Spring Security’s web support.

3. @EnableWebSecurity Annotation

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Documented
@Import({ WebSecurityConfiguration.class, SpringWebMvcImportSelector.class, OAuth2ImportSelector.class })
@EnableGlobalAuthentication
@Configuration
public @interface EnableWebSecurity {
    /** Controls debugging support for Spring Security. */
    boolean debug() default false;
}

The annotation imports three configuration selectors: WebSecurityConfiguration – builds a WebSecurity object and a FilterChainProxy bean. SpringWebMvcImportSelector – adds MVC‑specific security support when a DispatcherServlet is present. OAuth2ImportSelector – enables OAuth2 client configuration if the spring-security-oauth2 module is on the classpath.

3.1 WebSecurityConfiguration

Creates a WebSecurity instance based on user‑provided or default settings and exposes beans such as the security filter chain ( springSecurityFilterChain) and a SecurityExpressionHandler.

3.2 SpringWebMvcImportSelector

Activates WebMvcSecurityConfiguration when a DispatcherServlet is detected, adapting Spring Security to Spring MVC.

3.3 OAuth2ImportSelector

Enables OAuth2 client support ( OAuth2ClientConfiguration) when the OAuth2 module is present.

3.4 @EnableGlobalAuthentication

Imports AuthenticationConfiguration to construct the central AuthenticationManager.

4. SecurityFilterAutoConfiguration

@Configuration
@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
@EnableConfigurationProperties(SecurityProperties.class)
@ConditionalOnClass({ AbstractSecurityWebApplicationInitializer.class, SessionCreationPolicy.class })
@AutoConfigureAfter(SecurityAutoConfiguration.class)
public class SecurityFilterAutoConfiguration {

    private static final String DEFAULT_FILTER_NAME = AbstractSecurityWebApplicationInitializer.DEFAULT_FILTER_NAME;

    @Bean
    @ConditionalOnBean(name = DEFAULT_FILTER_NAME)
    public DelegatingFilterProxyRegistrationBean securityFilterChainRegistration(SecurityProperties securityProperties) {
        DelegatingFilterProxyRegistrationBean registration = new DelegatingFilterProxyRegistrationBean(DEFAULT_FILTER_NAME);
        registration.setOrder(securityProperties.getFilter().getOrder());
        registration.setDispatcherTypes(getDispatcherTypes(securityProperties));
        return registration;
    }

    private EnumSet<DispatcherType> getDispatcherTypes(SecurityProperties securityProperties) {
        if (securityProperties.getFilter().getDispatcherTypes() == null) {
            return null;
        }
        return securityProperties.getFilter().getDispatcherTypes().stream()
                .map(type -> DispatcherType.valueOf(type.name()))
                .collect(Collectors.collectingAndThen(Collectors.toSet(), EnumSet::copyOf));
    }
}

This class registers a DelegatingFilterProxy named springSecurityFilterChain as a servlet filter, delegating request handling to the Spring Security filter chain.

5. Conclusion

The article provides a high‑level overview of Spring Security’s auto‑configuration mechanisms in Spring Boot, highlighting the key configuration classes, annotation imports, and how the security filter chain is wired into the servlet container. A deeper dive into each class will reveal more detailed behavior for advanced security customisation.