From 842159439787a89fcb6371a7e42fe41e293a6b4f Mon Sep 17 00:00:00 2001 From: Josh Cummings Date: Mon, 30 Sep 2019 07:12:36 -0600 Subject: [PATCH] Replace Servlet Guides w/ Hello World Samples Issue gh-2567 Co-authored-by: Jay Bryant Co-authored-by: Rob Winch --- .../_includes/servlet/hello/boot.adoc | 67 ++++++++ .../_includes/servlet/hello/guides.adoc | 34 ---- .../_includes/servlet/hello/index.adoc | 8 + .../servlet/hello/java-configuration.adoc | 138 ++++++++++++++++ .../servlet/hello/xml-configuration.adoc | 148 ++++++++++++++++++ .../asciidoc/_includes/servlet/index.adoc | 2 +- docs/manual/src/docs/asciidoc/index.adoc | 2 +- 7 files changed, 363 insertions(+), 36 deletions(-) create mode 100644 docs/manual/src/docs/asciidoc/_includes/servlet/hello/boot.adoc delete mode 100644 docs/manual/src/docs/asciidoc/_includes/servlet/hello/guides.adoc create mode 100644 docs/manual/src/docs/asciidoc/_includes/servlet/hello/index.adoc create mode 100644 docs/manual/src/docs/asciidoc/_includes/servlet/hello/java-configuration.adoc create mode 100644 docs/manual/src/docs/asciidoc/_includes/servlet/hello/xml-configuration.adoc diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/hello/boot.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/hello/boot.adoc new file mode 100644 index 0000000000..328cfe1481 --- /dev/null +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/hello/boot.adoc @@ -0,0 +1,67 @@ +[[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 +* http://en.wikipedia.org/wiki/Cross-site_request_forgery[CSRF attack] prevention +* http://en.wikipedia.org/wiki/Session_fixation[Session Fixation] protection +* Security Header integration +** http://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security[HTTP Strict Transport Security] for secure requests +** http://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) +** http://msdn.microsoft.com/en-us/library/dd565647(v=vs.85).aspx[X-XSS-Protection] integration +** X-Frame-Options integration to help prevent http://en.wikipedia.org/wiki/Clickjacking[Clickjacking] +* Integrate with the following Servlet API methods: +** http://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getRemoteUser()[`HttpServletRequest#getRemoteUser()`] +** http://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getUserPrincipal()[`HttpServletRequest.html#getUserPrincipal()`] +** http://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#isUserInRole(java.lang.String)[`HttpServletRequest.html#isUserInRole(java.lang.String)`] +** http://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)`] +** http://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/guides.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/hello/guides.adoc deleted file mode 100644 index 8749067886..0000000000 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/hello/guides.adoc +++ /dev/null @@ -1,34 +0,0 @@ -[[samples]] -== Samples and Guides (Start Here) - -If you are looking to get started with Spring Security, the best place to start is our Sample Applications. - -.Sample Applications -|=== -| Source | Description | Guide - -| {gh-samples-url}/javaconfig/helloworld[Hello Spring Security] -| Demonstrates how to integrate Spring Security with an existing application using Java-based configuration. -| link:../../guides/html5/helloworld-javaconfig.html[Hello Spring Security Guide] - -| {gh-samples-url}/boot/helloworld[Hello Spring Security Boot] -| Demonstrates how to integrate Spring Security with an existing Spring Boot application. -| link:../../guides/html5/helloworld-boot.html[Hello Spring Security Boot Guide] - -| {gh-samples-url}/xml/helloworld[Hello Spring Security XML] -| Demonstrates how to integrate Spring Security with an existing application using XML-based configuration. -| link:../../guides/html5/helloworld-xml.html[Hello Spring Security XML Guide] - -| {gh-samples-url}/javaconfig/hellomvc[Hello Spring MVC Security] -| Demonstrates how to integrate Spring Security with an existing Spring MVC application. -| link:../../guides/html5/hellomvc-javaconfig.html[Hello Spring MVC Security Guide] - -| {gh-samples-url}/javaconfig/form[Custom Login Form] -| Demonstrates how to create a custom login form. -| link:../../guides/html5/form-javaconfig.html[Custom Login Form Guide] - -| {gh-samples-url}/boot/oauth2login[OAuth 2.0 Login] -| Demonstrates how to integrate OAuth 2.0 Login with an OAuth 2.0 or OpenID Connect 1.0 Provider. -| link:{gh-samples-url}/boot/oauth2login/README.adoc[OAuth 2.0 Login Guide] - -|=== diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/hello/index.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/hello/index.adoc new file mode 100644 index 0000000000..e0aeec6650 --- /dev/null +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/hello/index.adoc @@ -0,0 +1,8 @@ += Hello Spring Security + +This section covers a minimal Spring Security application that uses <>, <>, or <>. +// FIXME add Spring Boot + +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 new file mode 100644 index 0000000000..43ecd5fc04 --- /dev/null +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/hello/java-configuration.adoc @@ -0,0 +1,138 @@ +[[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 +* http://en.wikipedia.org/wiki/Cross-site_request_forgery[CSRF attack] prevention +* http://en.wikipedia.org/wiki/Session_fixation[Session Fixation] protection +* Security Header integration +** http://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security[HTTP Strict Transport Security] for secure requests +** http://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) +** http://msdn.microsoft.com/en-us/library/dd565647(v=vs.85).aspx[X-XSS-Protection] integration +** X-Frame-Options integration to help prevent http://en.wikipedia.org/wiki/Clickjacking[Clickjacking] +* Integrate with the following Servlet API methods: +** http://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getRemoteUser()[`HttpServletRequest#getRemoteUser()`] +** http://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getUserPrincipal()[`HttpServletRequest.html#getUserPrincipal()`] +** http://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#isUserInRole(java.lang.String)[`HttpServletRequest.html#isUserInRole(java.lang.String)`] +** http://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)`] +** http://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 new file mode 100644 index 0000000000..cb04924721 --- /dev/null +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/hello/xml-configuration.adoc @@ -0,0 +1,148 @@ +[[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 +* http://en.wikipedia.org/wiki/Cross-site_request_forgery[CSRF attack] prevention +* http://en.wikipedia.org/wiki/Session_fixation[Session Fixation] protection +* Security Header integration +** http://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security[HTTP Strict Transport Security] for secure requests +** http://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) +** http://msdn.microsoft.com/en-us/library/dd565647(v=vs.85).aspx[X-XSS-Protection] integration +** X-Frame-Options integration to help prevent http://en.wikipedia.org/wiki/Clickjacking[Clickjacking] +* Integrate with the following Servlet API methods: +** http://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getRemoteUser()[`HttpServletRequest#getRemoteUser()`] +** http://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getUserPrincipal()[`HttpServletRequest.html#getUserPrincipal()`] +** http://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#isUserInRole(java.lang.String)[`HttpServletRequest.html#isUserInRole(java.lang.String)`] +** http://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)`] +** http://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 + / + +---- +===== +==== diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/index.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/index.adoc index 0d02f9e5e2..07ffc30eb0 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/index.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/index.adoc @@ -2,7 +2,7 @@ Spring Security integrates with the Servlet Container by using a standard Servlet `Filter`. This means it works with any application that runs in a Servlet Container. More concretely, you do not need to use Spring in your Servlet-based application to take advantage of Spring Security. -include::hello/guides.adoc[] +include::hello/index.adoc[leveloffset=+1] include::architecture/index.adoc[leveloffset=+1] diff --git a/docs/manual/src/docs/asciidoc/index.adoc b/docs/manual/src/docs/asciidoc/index.adoc index 18f28485d9..a6a0be176a 100644 --- a/docs/manual/src/docs/asciidoc/index.adoc +++ b/docs/manual/src/docs/asciidoc/index.adoc @@ -1,5 +1,5 @@ = Spring Security Reference -Ben Alex; Luke Taylor; Rob Winch; Gunnar Hillert; Joe Grandja; Jay Bryant; Eddú Meléndez +Ben Alex; Luke Taylor; Rob Winch; Gunnar Hillert; Joe Grandja; Jay Bryant; Eddú Meléndez; Josh Cummings :include-dir: _includes :security-api-url: https://docs.spring.io/spring-security/site/docs/current/api/ :source-indent: 0