From af47e730a03780bfa531b96da65913ec39dd3d20 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Tue, 26 Nov 2019 08:38:08 -0600 Subject: [PATCH] Only Hello Spring Security Boot For those getting started, we really need to send the message of using Spring Boot. Fixes gh-7627 --- .../manual/spring-security-docs-manual.gradle | 1 + .../_includes/servlet/hello/boot.adoc | 67 -------- .../_includes/servlet/hello/index.adoc | 76 ++++++++- .../servlet/hello/java-configuration.adoc | 138 ---------------- .../servlet/hello/xml-configuration.adoc | 148 ------------------ 5 files changed, 72 insertions(+), 358 deletions(-) delete mode 100644 docs/manual/src/docs/asciidoc/_includes/servlet/hello/boot.adoc delete mode 100644 docs/manual/src/docs/asciidoc/_includes/servlet/hello/java-configuration.adoc delete mode 100644 docs/manual/src/docs/asciidoc/_includes/servlet/hello/xml-configuration.adoc diff --git a/docs/manual/spring-security-docs-manual.gradle b/docs/manual/spring-security-docs-manual.gradle index ace6a4c2ef..4006bac83a 100644 --- a/docs/manual/spring-security-docs-manual.gradle +++ b/docs/manual/spring-security-docs-manual.gradle @@ -5,6 +5,7 @@ asciidoctor { def ghUrl = "https://github.com/spring-projects/spring-security/tree/$ghTag" attributes 'spring-security-version' : project.version, 'spring-version' : project(':spring-security-core').dependencyManagement.managedVersions['org.springframework:spring-core'], + 'spring-boot-version' : springBootVersion, revnumber : project.version, 'gh-url': ghUrl, 'gh-samples-url': "$ghUrl/samples" diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/hello/boot.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/hello/boot.adoc deleted file mode 100644 index 848a5b8a5e..0000000000 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/hello/boot.adoc +++ /dev/null @@ -1,67 +0,0 @@ -[[servlet-hello-boot]] -= Hello Spring Security (Boot) - -This section covers the minimum setup for how to use Spring Security with Spring Boot. -For how to use Spring Security with Java Configuration, see <>. -For how to use Spring Security with XML Configuration, see <>. - -NOTE: The completed application can be found at {gh-samples-url}/boot/helloworld[samples/boot/helloworld] - -[[servlet-hello-boot-dependencies]] -== Updating Dependencies - -The only step you need to do is update the dependencies by using <> or <>. -For your convenience, you can download a minimal Spring Boot + Spring Security application by https://start.spring.io/starter.zip?type=maven-project&language=java&bootVersion=2.1.2.RELEASE&baseDir=hello-spring-security&groupId=sample&artifactId=sample&name=hello-spring-security&description=Demo+project+for+Spring+Boot&packageName=sample&packaging=jar&javaVersion=1.8&autocomplete=&style=security&style=web&generate-project=[clicking here]. - -== Starting Hello Spring Security Boot - -You can now https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#using-boot-running-with-the-maven-plugin[run the Spring Boot application] by using the Maven Plugin's `run` goal. -The following example shows how to do so (and the beginning of the output from doing so): - -.Running Spring Boot Application -==== -[source,bash] ----- -$ ./mvn spring-boot:run -... -INFO 23689 --- [ restartedMain] .s.s.UserDetailsServiceAutoConfiguration : - -Using generated security password: 8e557245-73e2-4286-969a-ff57fe326336 - -... ----- -==== - - -[[servlet-hello-boot-auto-configuration]] -== Spring Boot Auto Configuration - -Spring Boot automatically: - -* Enables Spring Security's default configuration, which creates a servlet `Filter` as a bean named `springSecurityFilterChain`. -This bean is responsible for all the security (protecting the application URLs, validating submitted username and passwords, redirecting to the log in form, and so on) within your application. -* Creates a `UserDetailsService` bean with a username of `user` and a randomly generated password that is logged to the console. -* Registers the `Filter` with a bean named `springSecurityFilterChain` with the Servlet container for every request. - -Spring Boot is not configuring much, but it does a lot. -A summary of the features follows: - -* Require an authenticated user for any interaction with the application -* Generate a default login form for you -* Let the user with a username of `user` and a password that is logged to the console to authenticate with form-based authentication (in the preceding example, the password is `8e557245-73e2-4286-969a-ff57fe326336`) -* Protects the password storage with BCrypt -* Lets the user log out -* https://en.wikipedia.org/wiki/Cross-site_request_forgery[CSRF attack] prevention -* https://en.wikipedia.org/wiki/Session_fixation[Session Fixation] protection -* Security Header integration -** https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security[HTTP Strict Transport Security] for secure requests -** https://msdn.microsoft.com/en-us/library/ie/gg622941(v=vs.85).aspx[X-Content-Type-Options] integration -** Cache Control (can be overridden later by your application to allow caching of your static resources) -** https://msdn.microsoft.com/en-us/library/dd565647(v=vs.85).aspx[X-XSS-Protection] integration -** X-Frame-Options integration to help prevent https://en.wikipedia.org/wiki/Clickjacking[Clickjacking] -* Integrate with the following Servlet API methods: -** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getRemoteUser()[`HttpServletRequest#getRemoteUser()`] -** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getUserPrincipal()[`HttpServletRequest.html#getUserPrincipal()`] -** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#isUserInRole(java.lang.String)[`HttpServletRequest.html#isUserInRole(java.lang.String)`] -** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#login(java.lang.String,%20java.lang.String)[`HttpServletRequest.html#login(java.lang.String, java.lang.String)`] -** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#logout()[`HttpServletRequest.html#logout()`] diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/hello/index.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/hello/index.adoc index e0aeec6650..57e9f5f1ce 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/hello/index.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/hello/index.adoc @@ -1,8 +1,74 @@ +[[servlet-hello]] = Hello Spring Security -This section covers a minimal Spring Security application that uses <>, <>, or <>. -// FIXME add Spring Boot +This section covers the minimum setup for how to use Spring Security with Spring Boot. + +[NOTE] +==== +The completed application can be found at {gh-samples-url}/boot/helloworld[samples/boot/helloworld] +For your convenience, you can download a minimal Spring Boot + Spring Security application by 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[clicking here]. +==== + +[[servlet-hello-dependencies]] +== Updating Dependencies + +The only step you need to do is update the dependencies by using <> or <>. + +[[servlet-hello-starting]] +== Starting Hello Spring Security Boot + +You can now https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#using-boot-running-with-the-maven-plugin[run the Spring Boot application] by using the Maven Plugin's `run` goal. +The following example shows how to do so (and the beginning of the output from doing so): + +.Running Spring Boot Application +==== +[source,bash] +---- +$ ./mvn spring-boot:run +... +INFO 23689 --- [ restartedMain] .s.s.UserDetailsServiceAutoConfiguration : + +Using generated security password: 8e557245-73e2-4286-969a-ff57fe326336 + +... +---- +==== + + +[[servlet-hello-auto-configuration]] +== Spring Boot Auto Configuration + +// FIXME: Link to relevant portions of documentation +// FIXME: Link to Spring Boot's Security Auto configuration classes +// FIXME: Add a links for what user's should do next + +Spring Boot automatically: + +* Enables Spring Security's default configuration, which creates a servlet `Filter` as a bean named `springSecurityFilterChain`. +This bean is responsible for all the security (protecting the application URLs, validating submitted username and passwords, redirecting to the log in form, and so on) within your application. +* Creates a `UserDetailsService` bean with a username of `user` and a randomly generated password that is logged to the console. +* Registers the `Filter` with a bean named `springSecurityFilterChain` with the Servlet container for every request. + +Spring Boot is not configuring much, but it does a lot. +A summary of the features follows: + +* Require an authenticated user for any interaction with the application +* Generate a default login form for you +* Let the user with a username of `user` and a password that is logged to the console to authenticate with form-based authentication (in the preceding example, the password is `8e557245-73e2-4286-969a-ff57fe326336`) +* Protects the password storage with BCrypt +* Lets the user log out +* https://en.wikipedia.org/wiki/Cross-site_request_forgery[CSRF attack] prevention +* https://en.wikipedia.org/wiki/Session_fixation[Session Fixation] protection +* Security Header integration +** https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security[HTTP Strict Transport Security] for secure requests +** https://msdn.microsoft.com/en-us/library/ie/gg622941(v=vs.85).aspx[X-Content-Type-Options] integration +** Cache Control (can be overridden later by your application to allow caching of your static resources) +** https://msdn.microsoft.com/en-us/library/dd565647(v=vs.85).aspx[X-XSS-Protection] integration +** X-Frame-Options integration to help prevent https://en.wikipedia.org/wiki/Clickjacking[Clickjacking] +* Integrate with the following Servlet API methods: +** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getRemoteUser()[`HttpServletRequest#getRemoteUser()`] +** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getUserPrincipal()[`HttpServletRequest.html#getUserPrincipal()`] +** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#isUserInRole(java.lang.String)[`HttpServletRequest.html#isUserInRole(java.lang.String)`] +** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#login(java.lang.String,%20java.lang.String)[`HttpServletRequest.html#login(java.lang.String, java.lang.String)`] +** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#logout()[`HttpServletRequest.html#logout()`] -include::boot.adoc[leveloffset=+1] -include::java-configuration.adoc[leveloffset=+1] -include::xml-configuration.adoc[leveloffset=+1] diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/hello/java-configuration.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/hello/java-configuration.adoc deleted file mode 100644 index 7434dadf7d..0000000000 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/hello/java-configuration.adoc +++ /dev/null @@ -1,138 +0,0 @@ -[[servlet-hello-jc]] -= Hello Spring Security (Java Configuration) - -This section covers how to use Spring Security with Java Configuration. -For how to use Spring Security with XML configuration, see <>. -For how to use Spring Security with Spring Boot configuration, see <>. - -NOTE: You can find the completed application at {gh-samples-url}/javaconfig/helloworld[samples/javaconfig/helloworld]. - -== Updating Dependencies - -The first step is to update the dependencies by using <> or <>. - - -[[servlet-hello-jc-ews]] -== Minimal `@EnableWebSecurity` Configuration - -The first step is to create our Spring Security Java configuration. -The configuration creates a servlet `Filter` (known as the `springSecurityFilterChain`), which is responsible for all the security features (protecting the application URLs, validating submitted username and passwords, redirecting to the log in form, and so on) within your application. -The following example shows the most basic example of a Spring Security Java Configuration: - -.WebSecurity.java -==== -[source,java] ----- -import org.springframework.context.annotation.*; -import org.springframework.security.config.annotation.web.configuration.*; -import org.springframework.security.core.userdetails.*; -import org.springframework.security.provisioning.*; - -@EnableWebSecurity -public class WebSecurityConfig { - - // @formatter:off - @Bean - public UserDetailsService userDetailsService() { - UserDetails user = User.withDefaultPasswordEncoder() - .username("user") - .password("password") - .roles("USER") - .build(); - return new InMemoryUserDetailsManager(user); - } - // @formatter:on -} ----- -==== - -There really is not much to this configuration, but it does a lot. -A summary of the features follows: - -* Require an authenticated user for any interaction with the application -* Generate a default login form for you -* Lets the user with a username of `user` and a password of `password` authenticate with form-based authentication -* Protects the password storage with BCrypt -* Lets the user log out -* https://en.wikipedia.org/wiki/Cross-site_request_forgery[CSRF attack] prevention -* https://en.wikipedia.org/wiki/Session_fixation[Session Fixation] protection -* Security Header integration -** https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security[HTTP Strict Transport Security] for secure requests -** https://msdn.microsoft.com/en-us/library/ie/gg622941(v=vs.85).aspx[X-Content-Type-Options] integration -** Cache Control (can be overridden later by your application to allow caching of your static resources) -** https://msdn.microsoft.com/en-us/library/dd565647(v=vs.85).aspx[X-XSS-Protection] integration -** X-Frame-Options integration to help prevent https://en.wikipedia.org/wiki/Clickjacking[Clickjacking] -* Integrate with the following Servlet API methods: -** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getRemoteUser()[`HttpServletRequest#getRemoteUser()`] -** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getUserPrincipal()[`HttpServletRequest.html#getUserPrincipal()`] -** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#isUserInRole(java.lang.String)[`HttpServletRequest.html#isUserInRole(java.lang.String)`] -** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#login(java.lang.String,%20java.lang.String)[`HttpServletRequest.html#login(java.lang.String, java.lang.String)`] -** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#logout()[`HttpServletRequest.html#logout()`] - -// FIXME: After completed rewriting, link to all the sections of doc that this relates to - -== Using `AbstractSecurityWebApplicationInitializer` - -The next step is to register the `springSecurityFilterChain` with the war. -Spring Security provides a base class (`AbstractSecurityWebApplicationInitializer`) that leverages https://docs.spring.io/spring/docs/current/spring-framework-reference/web.html#mvc-servlet[Spring's WebApplicationInitializer support]. - -The following example shows an example configuration: - -.SecurityInitializer.java -==== -[source,java] ----- -import org.springframework.security.web.context.*; - -public class SecurityInitializer - extends AbstractSecurityWebApplicationInitializer { - - public SecurityInitializer() { - super(WebSecurityConfig.class); - } -} ----- -==== - -The `SecurityInitializer` does the following things: - -* Adds a `ContextLoaderListener` that loads the <>. -* Finds the bean of type `Filter` named `springSecurityFilterChain` and registers it to process every URL in the application. - - -[NOTE] -==== -If you are integrating with a Spring MVC application, be sure to configure the `DispatcherServlet` to load the configuration from the root `ApplicationContext`. -The following example shows how to do so: - -.MvcInitializer.java -===== -[source,java] ----- -public class MvcInitializer extends - AbstractAnnotationConfigDispatcherServletInitializer { - - // the Root Config is registered in SecurityInitializer - @Override - protected Class[] getRootConfigClasses() { - return null; - } - - // the Spring MVC configuration should be added to SecurityInitializer constructor - // i.e. - // super(MvcConfig.class, WebSecurityConfig.class); - @Override - protected Class[] getServletConfigClasses() { - return null; - } - - @Override - protected String[] getServletMappings() { - return new String[] { "/" }; - } - -} - ----- -===== -==== diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/hello/xml-configuration.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/hello/xml-configuration.adoc deleted file mode 100644 index 183634be7a..0000000000 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/hello/xml-configuration.adoc +++ /dev/null @@ -1,148 +0,0 @@ -[[servlet-hello-xml]] -= Hello Spring Security (XML) - -This section covers how to use Spring Security with XML Configuration. -For how to use Spring Security with Java configuration, see <>. -For how to use Spring Security with Spring Boot configuration, see <>. - -== Updating Dependencies - -The first step is to update the dependencies by using <> or <>. - - -[[servlet-hello-xml-http]] -== Minimal `` Configuration - -In this section, we discuss how to use Spring Security with XML Configuration. - -NOTE: The completed application can be found at {gh-samples-url}/xml/helloworld[samples/xml/helloworld] -// FIXME: Link to Java Configuration and Boot - -The first step is to create our Spring Security XML Configuration. -The configuration creates a Servlet `Filter` (known as the `springSecurityFilterChain`), which is responsible for all the security (protecting the application URLs, validating submitted username and passwords, redirecting to the log in form, and so on) within your application. -The following example shows the most basic example of a Spring Security XML Configuration: - -.src/main/webapp/WEB-INF/spring/security.xml -==== -[source,xml] ----- - - - - - - - - ----- -==== - - -There really is not much to this configuration, but it does a lot. -A summary of the features follows: - -* Require an authenticated user for any interaction with the application -* Generate a default login form for you -* Lets the user with a username of `user` and a password of `password` authenticate with form-based authentication -* Protects the password storage with BCrypt -* Lets the user to log out -* https://en.wikipedia.org/wiki/Cross-site_request_forgery[CSRF attack] prevention -* https://en.wikipedia.org/wiki/Session_fixation[Session Fixation] protection -* Security Header integration -** https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security[HTTP Strict Transport Security] for secure requests -** https://msdn.microsoft.com/en-us/library/ie/gg622941(v=vs.85).aspx[X-Content-Type-Options] integration -** Cache Control (can be overridden later by your application to allow caching of your static resources) -** https://msdn.microsoft.com/en-us/library/dd565647(v=vs.85).aspx[X-XSS-Protection] integration -** X-Frame-Options integration to help prevent https://en.wikipedia.org/wiki/Clickjacking[Clickjacking] -* Integrate with the following Servlet API methods: -** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getRemoteUser()[`HttpServletRequest#getRemoteUser()`] -** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getUserPrincipal()[`HttpServletRequest.html#getUserPrincipal()`] -** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#isUserInRole(java.lang.String)[`HttpServletRequest.html#isUserInRole(java.lang.String)`] -** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#login(java.lang.String,%20java.lang.String)[`HttpServletRequest.html#login(java.lang.String, java.lang.String)`] -** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#logout()[`HttpServletRequest.html#logout()`] - -// FIXME: After completed rewriting, link to all the sections of doc that this relates to - - -[[servlet-hello-xml-webxml]] -== `web.xml` Configuration - -The next step is to ensure that our Security configuration is being read in. -To do so, we need to ensure a `ContextLoaderListener` is registered and the `contextConfigLocation` is including the configuration. -The following example shows how to do so: - -.src/main/webapp/WEB-INF/web.xml -==== -[source,xml] ----- - - - - - - org.springframework.web.context.ContextLoaderListener - - - - - contextConfigLocation - - /WEB-INF/spring/*.xml - - - - - - springSecurityFilterChain - org.springframework.web.filter.DelegatingFilterProxy - - - springSecurityFilterChain - /* - - - ----- -==== - -[NOTE] -==== -If you integrate with an existing Spring MVC application, be sure to configure the `DispatcherServlet` to load the configuration from the root `ApplicationContext`. -The following example shows how to do so: - -===== -.src/main/webapp/WEB-INF/web.xml -[source,xml] ----- - - spring - org.springframework.web.servlet.DispatcherServlet - - - contextConfigLocation - - - - - - spring - / - ----- -===== -====