This version is still in development and is not considered stable yet. For the latest stable version, please use Spring Security 6.1.12!

Hello Spring Security

This section covers the minimum setup for how to use Spring Security with Spring Boot and then points you to next steps after that.

The completed starter application can be found in our samples repository. For your convenience, you can download a minimal Spring Boot + Spring Security application prepared by Spring Initializr.

Updating Dependencies

You first need to add Spring Security to your application’s classpath; two ways to do this are to use Maven or Gradle.

Starting Hello Spring Security Boot

With Spring Security on the classpath, you can now run the Spring Boot application. The following snippet shows some of the output that indicates that Spring Security is enabled in your application:

Running Spring Boot Application

  • Maven

  • Gradle

  • Jar

$ ./mvnw spring-boot:run
...
INFO 23689 --- [  restartedMain] .s.s.UserDetailsServiceAutoConfiguration :

Using generated security password: 8e557245-73e2-4286-969a-ff57fe326336

...
$ ./gradlew :bootRun
...
INFO 23689 --- [  restartedMain] .s.s.UserDetailsServiceAutoConfiguration :

Using generated security password: 8e557245-73e2-4286-969a-ff57fe326336

...
$ java -jar target/myapplication-0.0.1.jar
...
INFO 23689 --- [  restartedMain] .s.s.UserDetailsServiceAutoConfiguration :

Using generated security password: 8e557245-73e2-4286-969a-ff57fe326336

...

Now that you have it running, you might try hitting an endpoint to see what happens. If you hit an endpoint without credentials like so:

Querying a Secured Boot Application
$ curl -i http://localhost:8080/some/path
HTTP/1.1 401
...

then Spring Security denies access with a 401 Unauthorized.

If you provide the same URL in a browser, it will redirect to a default login page.

And if you hit an endpoint with credentials (found in the console output) as follows:

Querying with Credentials
$ curl -i -u user:8e557245-73e2-4286-969a-ff57fe326336 http://localhost:8080/some/path
HTTP/1.1 404
...

then Spring Boot will service the request, returning a 404 Not Found in this case since /some/path doesn’t exist.

From here, you can:

Runtime Expectations

The default arrangement of Spring Boot and Spring Security affords the following behaviors at runtime:

It can be helpful to understand how Spring Boot is coordinating with Spring Security to achieve this. Taking a look at Boot’s security auto configuration, it does the following (simplified for illustration):

Spring Boot Security Auto Configuration
@EnableWebSecurity (1)
@Configuration
public class DefaultSecurityConfig {
    @Bean
    @ConditionalOnMissingBean(UserDetailsService.class)
    InMemoryUserDetailsManager inMemoryUserDetailsManager() { (2)
        String generatedPassword = // ...;
        return new InMemoryUserDetailsManager(User.withUsername("user")
                .password(generatedPassword).roles("USER").build());
    }

    @Bean
    @ConditionalOnMissingBean(AuthenticationEventPublisher.class)
    DefaultAuthenticationEventPublisher defaultAuthenticationEventPublisher(ApplicationEventPublisher delegate) { (3)
        return new DefaultAuthenticationEventPublisher(delegate);
    }
}

  1. Adds the @EnableWebSecurity annotation. (Among other things, this publishes Spring Security’s default Filter chain as a @Bean)

  2. Publishes a UserDetailsService @Bean with a username of user and a randomly generated password that is logged to the console

  3. Publishes an AuthenticationEventPublisher @Bean for publishing authentication events

Spring Boot adds any Filter published as a @Bean to the application’s filter chain. This means that using @EnableWebSecurity in conjunction with Spring Boot automatically registers Spring Security’s filter chain for every request.

Security Use Cases

There are a number of places that you may want to go from here. To figure out what’s next for you and your application, consider these common use cases that Spring Security is built to address:

In case none of those match what you are looking for, consider thinking about your application in the following order:

  1. Protocol: First, consider the protocol your application will use to communicate. For servlet-based applications, Spring Security supports HTTP as well as Websockets.

  2. Authentication: Next, consider how users will authenticate and if that authentication will be stateful or stateless

  3. Authorization: Then, consider how you will determine what a user is authorized to do

  4. Defense: Finally, integrate with Spring Security’s default protections and consider which additional protections you need