Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 39 ยท Getting Started

Boot Auto-Configuration and Security Defaults

Understand how Spring Boot configures Spring Security for you, which beans it creates, when it backs off, and which properties and defaults you can change.

When you add the starter and your application is suddenly protected, no magic is involved. Spring Boot's auto-configuration inspects the classpath and your beans, and registers a default set of security beans unless you have already provided your own. Knowing the rules of that process lets you predict what the application will do, and explains why defining one bean can silently switch a lot of other behavior off.

This lesson lists what Boot sets up, how "back off" works, how to read the report of what happened, and which properties you can use. It also introduces the conditional mechanism with a small stand-in that you can run.

What Boot registers

The relevant auto-configuration classes live in spring-boot-autoconfigure and spring-boot-security. In plain words they do the following:

Auto-configuration What it gives you Backs off when
SecurityAutoConfiguration Default event publisher and chain setup
SpringBootWebSecurityConfiguration The default SecurityFilterChain (all requests authenticated, form login, Basic) You define any SecurityFilterChain bean
UserDetailsServiceAutoConfiguration An in-memory user from spring.security.user.* You define a UserDetailsService, AuthenticationProvider, AuthenticationManager or JWT/OAuth beans
SecurityFilterAutoConfiguration Registers DelegatingFilterProxy with the servlet container, named springSecurityFilterChain Rarely
OAuth2 client / resource server auto-configuration Registrations and decoders from properties You define your own beans

The most important rule is the second row: the default chain exists only if you define no chain yourself. This is expressed internally by an annotation with the meaning "only if no SecurityFilterChain bean is present" (@ConditionalOnDefaultWebSecurity plus @ConditionalOnMissingBean). Your first chain bean therefore replaces the default completely; it does not add to it.

The mechanism: conditions

Auto-configuration is a list of @Configuration classes, each guarded by conditions:

Java
@AutoConfiguration
@ConditionalOnClass(DefaultAuthenticationEventPublisher.class)
public class SecurityAutoConfiguration {

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

The common conditions are @ConditionalOnClass (a library is on the classpath), @ConditionalOnMissingBean (you did not supply one), @ConditionalOnWebApplication and @ConditionalOnProperty. Your own @Bean methods are processed before auto-configuration, which is what makes "back off" work.

The stand-in below implements this order of events in a few lines: a registry that first takes the user's beans and then adds each default only if its type is missing.

Java Back off: defaults only when you have no bean

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Reading what Boot decided

When a result surprises you, ask Boot for the conditions evaluation report. Start with --debug (or debug=true in properties) and look for the section CONDITIONS EVALUATION REPORT. Under "Positive matches" you see every auto-configuration that applied, and under "Negative matches" the ones that did not, each with the reason, such as @ConditionalOnMissingBean (types: SecurityFilterChain; SearchStrategy: all) found beans 'securityFilterChain'. The actuator endpoint /actuator/conditions shows the same data from a running application.

Also turn on security logging while learning:

PROPERTIES
logging.level.org.springframework.security=DEBUG

At DEBUG you see which filter chain matched each request and the list of filters; at TRACE you see each filter being entered and the authorization decision.

Properties you can set

Most of what you need at first is available without code:

PROPERTIES
# the single default user (development only)
spring.security.user.name=ana
spring.security.user.password=changeit
spring.security.user.roles=USER

# filter order of the security filter in the servlet chain
spring.security.filter.order=-100

# session cookie hardening
server.servlet.session.cookie.http-only=true
server.servlet.session.cookie.secure=true
server.servlet.session.cookie.same-site=lax
server.servlet.session.timeout=30m

The spring.security.user.* properties build the in-memory user only when no other user source exists. Everything beyond that is configured in code, because security rules are too important to hide in a property file where one typo silently opens a URL.

Servlet and reactive stacks

Boot picks the stack by looking at the classpath. With spring-boot-starter-web you get the servlet configuration (SecurityFilterChain, HttpSecurity, @EnableWebSecurity). With spring-boot-starter-webflux you get the reactive configuration (SecurityWebFilterChain, ServerHttpSecurity, @EnableWebFluxSecurity). The concepts are the same, the types are different, and this course uses the servlet stack. If both are present Boot prefers the servlet stack.

The default chain, written out

The default chain behaves as if you had written:

Java
@Bean
SecurityFilterChain defaultChain(HttpSecurity http) throws Exception {
    http
        .authorizeHttpRequests(a -> a.anyRequest().authenticated())
        .formLogin(Customizer.withDefaults())
        .httpBasic(Customizer.withDefaults());
    return http.build();
}

Keep this snippet as a mental baseline. Every custom chain is "the default, plus or minus something". A useful habit is to start a new chain by writing exactly this and then change one thing at a time.

When defaults are not what you want

Three typical reasons to leave the defaults:

  1. A stateless API. There is no login page; callers send tokens. You switch off form login, disable the session, and add a token mechanism.
  2. A public site with a private admin area. Most URLs are open; a few are protected, so the rule list flips from "authenticated by default" to an explicit list.
  3. Several kinds of clients. A web UI with sessions and a mobile API with tokens need two chains (multiple filter chains).

The next chapter explains the filters behind all of this, starting with the filter chain.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What happens to Boot's default SecurityFilterChain when you declare your own SecurityFilterChain bean?

    The default chain is conditional on there being no SecurityFilterChain bean, so yours replaces it.
  2. 2. Which command line option makes Boot print a conditions evaluation report?

    Starting with --debug (or debug=true) prints positive and negative auto-configuration matches.
  3. 3. When is the spring.security.user.* in-memory user created?

    UserDetailsServiceAutoConfiguration backs off as soon as you provide a user source.
  4. 4. Why is @ConditionalOnMissingBean able to see your own beans?

    User configuration is registered first, then auto-configuration evaluates its conditions against what already exists.

Summary

  • Boot registers a default chain, a default user and the servlet filter unless you provide your own beans.
  • Back-off is based on conditions such as @ConditionalOnMissingBean, evaluated after your configuration.
  • Run with --debug or /actuator/conditions to see what applied and why; use logging.level.org.springframework.security=DEBUG to see requests.
  • The default chain is "authenticated everywhere, form login plus Basic"; every custom chain is a variation of it.
  • Servlet and reactive stacks have parallel types; this course uses the servlet stack.

Next: The filter chain, step by step