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. |
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:
-
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:
$ 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:
$ 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:
-
Better understand what Spring Boot enables in Spring Security by default
-
Read about common use cases that Spring Security helps with
-
Start configuring authentication
Runtime Expectations
The default arrangement of Spring Boot and Spring Security affords the following behaviors at runtime:
-
Requires an authenticated user for any endpoint (including Boot’s
/error
endpoint) -
Registers a default user with a generated password at startup (the password is logged to the console; in the preceding example, the password is
8e557245-73e2-4286-969a-ff57fe326336
) -
Protects password storage with BCrypt as well as others
-
Authenticates form-based login as well as HTTP Basic
-
Provides content negotiation; for web requests, redirects to the login page; for service requests, returns a
401 Unauthorized
-
Mitigates CSRF attacks
-
Mitigates Session Fixation attacks
-
Writes Strict-Transport-Security to ensure HTTPS
-
Writes X-Content-Type-Options to mitigate sniffing attacks
-
Writes Cache Control headers that protect authenticated resources
-
Writes X-Frame-Options to mitigate Clickjacking
-
Integrates with
HttpServletRequest
's authentication methods
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):
@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);
}
}
-
Adds the
@EnableWebSecurity
annotation. (Among other things, this publishes Spring Security’s defaultFilter
chain as a@Bean
) -
Publishes a
UserDetailsService
@Bean
with a username ofuser
and a randomly generated password that is logged to the console -
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:
-
I am building a REST API, and I need to authenticate a JWT or other bearer token
-
I am building a Web Application, API Gateway, or BFF and
-
I need to login using OAuth 2.0 or OIDC
-
I need to login using SAML 2.0
-
I need to login using CAS
-
-
I need to manage
-
Users in LDAP or Active Directory, with Spring Data, or with JDBC
-
In case none of those match what you are looking for, consider thinking about your application in the following order:
-
Protocol: First, consider the protocol your application will use to communicate. For servlet-based applications, Spring Security supports HTTP as well as Websockets.
-
Authentication: Next, consider how users will authenticate and if that authentication will be stateful or stateless
-
Authorization: Then, consider how you will determine what a user is authorized to do
-
Defense: Finally, integrate with Spring Security’s default protections and consider which additional protections you need