mirror of
https://github.com/spring-projects/spring-security.git
synced 2025-10-28 05:09:06 +00:00
174 lines
9.0 KiB
Plaintext
174 lines
9.0 KiB
Plaintext
[[servlet-hello]]
|
|
= Hello Spring Security
|
|
|
|
This section covers the minimum setup for how to use Spring Security with {spring-boot-reference-url}[Spring Boot] and then points you to next steps after that.
|
|
|
|
[NOTE]
|
|
====
|
|
The completed starter application can be found {gh-samples-url}/servlet/spring-boot/java/hello-security[in our samples repository].
|
|
For your convenience, you can download a minimal Spring Boot + Spring Security application https://start.spring.io/starter.zip?type=maven-project&language=java&packaging=jar&jvmVersion=1.8&groupId=example&artifactId=hello-security&name=hello-security&description=Hello%20Security&packageName=example.hello-security&dependencies=web,security[prepared by Spring Initializr].
|
|
====
|
|
|
|
[[servlet-hello-dependencies]]
|
|
== Updating Dependencies
|
|
|
|
You first need to add Spring Security to your application's classpath; two ways to do this are to xref:getting-spring-security.adoc#getting-maven-boot[use Maven] or xref:getting-spring-security.adoc#getting-gradle-boot[Gradle].
|
|
|
|
[[servlet-hello-starting]]
|
|
== Starting Hello Spring Security Boot
|
|
|
|
With Spring Security <<servlet-hello-dependencies,on the classpath>>, you can now {spring-boot-reference-url}reference/using/running-your-application.html[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
|
|
[tabs]
|
|
======
|
|
Maven::
|
|
+
|
|
[source,bash,role="primary"]
|
|
----
|
|
$ ./mvnw spring-boot:run
|
|
...
|
|
INFO 23689 --- [ restartedMain] .s.s.UserDetailsServiceAutoConfiguration :
|
|
|
|
Using generated security password: 8e557245-73e2-4286-969a-ff57fe326336
|
|
|
|
...
|
|
----
|
|
|
|
Gradle::
|
|
+
|
|
[source,bash,role="secondary"]
|
|
----
|
|
$ ./gradlew :bootRun
|
|
...
|
|
INFO 23689 --- [ restartedMain] .s.s.UserDetailsServiceAutoConfiguration :
|
|
|
|
Using generated security password: 8e557245-73e2-4286-969a-ff57fe326336
|
|
|
|
...
|
|
----
|
|
|
|
Jar::
|
|
+
|
|
[source,bash,role="secondary"]
|
|
----
|
|
$ 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
|
|
[source,bash]
|
|
----
|
|
$ curl -i http://localhost:8080/some/path
|
|
HTTP/1.1 401
|
|
...
|
|
----
|
|
|
|
then Spring Security denies access with a `401 Unauthorized`.
|
|
|
|
[TIP]
|
|
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
|
|
[source,bash]
|
|
----
|
|
$ 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 <<servlet-hello-auto-configuration,what Spring Boot enables in Spring Security by default>>
|
|
* Read about <<security-use-cases,common use cases>> that Spring Security helps with
|
|
* Start configuring xref:servlet/authentication/index.adoc[authentication]
|
|
|
|
[[servlet-hello-auto-configuration]]
|
|
== Runtime Expectations
|
|
|
|
The default arrangement of Spring Boot and Spring Security affords the following behaviors at runtime:
|
|
|
|
* Requires an authenticated user xref:servlet/authorization/authorize-http-requests.adoc[for any endpoint] (including Boot's `/error` endpoint)
|
|
* xref:servlet/authentication/passwords/user-details-service.adoc[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 xref:servlet/authentication/passwords/password-encoder.adoc[password storage with BCrypt] as well as others
|
|
* Provides form-based xref:servlet/authentication/passwords/form.adoc[login] and xref:servlet/authentication/logout.adoc[logout] flows
|
|
* Authenticates xref:servlet/authentication/passwords/form.adoc[form-based login] as well as xref:servlet/authentication/passwords/basic.adoc[HTTP Basic]
|
|
* Provides content negotiation; for web requests, redirects to the login page; for service requests, returns a `401 Unauthorized`
|
|
* xref:servlet/exploits/csrf.adoc[Mitigates CSRF] attacks
|
|
* xref:servlet/authentication/session-management.adoc#ns-session-fixation[Mitigates Session Fixation] attacks
|
|
* Writes xref:servlet/exploits/headers.adoc#servlet-headers-hsts[Strict-Transport-Security] to https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security[ensure HTTPS]
|
|
* Writes xref:servlet/exploits/headers.adoc#servlet-headers-content-type-options[X-Content-Type-Options] to mitigate https://cheatsheetseries.owasp.org/cheatsheets/HTTP_Headers_Cheat_Sheet.html#x-content-type-options[sniffing attacks]
|
|
* Writes xref:servlet/exploits/headers.adoc#servlet-headers-cache-control[Cache Control headers] that protect authenticated resources
|
|
* Writes xref:servlet/exploits/headers.adoc#servlet-headers-frame-options[X-Frame-Options] to mitigate https://cheatsheetseries.owasp.org/cheatsheets/HTTP_Headers_Cheat_Sheet.html#x-frame-options[Clickjacking]
|
|
* Integrates with xref:servlet/integrations/servlet-api.adoc[``HttpServletRequest``'s authentication methods]
|
|
* Publishes xref:servlet/authentication/events.adoc[authentication success and failure events]
|
|
|
|
It can be helpful to understand how Spring Boot is coordinating with Spring Security to achieve this.
|
|
Taking a look at {spring-boot-api-url}org/springframework/boot/autoconfigure/security/servlet/SecurityAutoConfiguration.html[Boot's security auto configuration], it does the following (simplified for illustration):
|
|
|
|
.Spring Boot Security Auto Configuration
|
|
[source,java]
|
|
----
|
|
@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 xref:servlet/architecture.adoc#servlet-securityfilterchain[Spring Security's default `Filter` chain] as a `@Bean`)
|
|
2. Publishes a xref:servlet/authentication/passwords/user-details-service.adoc[`UserDetailsService`] `@Bean` with a username of `user` and a randomly generated password that is logged to the console
|
|
3. Publishes an xref:servlet/authentication/events.adoc[`AuthenticationEventPublisher`] `@Bean` for publishing authentication events
|
|
|
|
[NOTE]
|
|
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]]
|
|
== 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 xref:servlet/oauth2/resource-server/jwt.adoc[authenticate a JWT] or xref:servlet/oauth2/resource-server/opaque-token.adoc[other bearer token]
|
|
* I am building a Web Application, API Gateway, or BFF and
|
|
** I need to xref:servlet/oauth2/login/core.adoc[login using OAuth 2.0 or OIDC]
|
|
** I need to xref:servlet/saml2/login/index.adoc[login using SAML 2.0]
|
|
** I need to xref:servlet/authentication/cas.adoc[login using CAS]
|
|
* I need to manage
|
|
** Users in xref:servlet/authentication/passwords/ldap.adoc[LDAP] or xref:servlet/authentication/passwords/ldap.adoc#_active_directory[Active Directory], with xref:servlet/integrations/data.adoc[Spring Data], or with xref:servlet/authentication/passwords/jdbc.adoc[JDBC]
|
|
** xref:servlet/authentication/passwords/storage.adoc[Passwords]
|
|
|
|
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 xref:servlet/integrations/websocket.adoc[Websockets].
|
|
2. *Authentication*: Next, consider how users will xref:servlet/authentication/index.adoc[authenticate] and if that authentication will be stateful or stateless
|
|
3. *Authorization*: Then, consider how you will determine xref:servlet/authorization/index.adoc[what a user is authorized to do]
|
|
4. *Defense*: Finally, xref:servlet/exploits/csrf.adoc#csrf-considerations[integrate with Spring Security's default protections] and consider xref:servlet/exploits/headers.adoc[which additional protections you need]
|