Replace Servlet Guides w/ Hello World Samples

Issue gh-2567

Co-authored-by: Jay Bryant <[email protected]>
Co-authored-by: Rob Winch <[email protected]>

Author: 3 people

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 <<servlet-hello-jc>>.
+For how to use Spring Security with XML Configuration, see <<servlet-hello-xml>>.
+
+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 <<getting-maven-boot,Maven>> or <<getting-gradle-boot,Gradle>>.
+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()`]

docs/manual/src/docs/asciidoc/_includes/servlet/hello/guides.adoc

@@ -0,0 +1,8 @@
+= Hello Spring Security
+
+This section covers a minimal Spring Security application that uses <<servlet-hello-boot,Spring Boot>>, <<servlet-hello-jc,Java Configuration>>, or <<servlet-hello-xml,XML Configuration>>.
+// FIXME add Spring Boot
+
+include::boot.adoc[leveloffset=+1]
+include::java-configuration.adoc[leveloffset=+1]
+include::xml-configuration.adoc[leveloffset=+1]

docs/manual/src/docs/asciidoc/_includes/servlet/hello/index.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 <<servlet-hello-xml>>.
+For how to use Spring Security with Spring Boot configuration, see <<servlet-hello-boot>>.
+
+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 <<getting-maven-without-spring-boot,Maven>> or <<gradle-without-spring-boot,Gradle>>.
+
+
+[[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 <<servlet-hello-ews,`WebSecurityConfig`>>.
+* 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[] { "/" };
+	}
+
+}
+
+----
+=====
+====

docs/manual/src/docs/asciidoc/_includes/servlet/hello/java-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 <<servlet-hello-jc>>.
+For how to use Spring Security with Spring Boot configuration, see <<servlet-hello-boot>>.
+
+== Updating Dependencies
+
+The first step is to update the dependencies by using <<maven-without-spring-boot,Maven>> or <<gradle-without-spring-boot,Gradle>>.
+
+
+[[servlet-hello-xml-http]]
+== Minimal `<http>` 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]
+----
+<b:beans xmlns="http://www.springframework.org/schema/security"
+		 xmlns:b="http://www.springframework.org/schema/beans"
+		 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+		 xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
+						http://www.springframework.org/schema/security http://www.springframework.org/schema/security/spring-security.xsd">
+	<http />
+
+	<user-service>
+		<user name="user" password="{noop}password" authorities="ROLE_USER" />
+	</user-service>
+</b:beans>
+
+----
+====
+
+
+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]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
+		 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+		 xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
+  http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
+
+	<!--
+		Loads the Spring configurations from contextConfigLocation
+	-->
+	<listener>
+		<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
+	</listener>
+
+	<!--
+		The locations of the Spring Configuration. In this case, all configuration is
+		in /WEB-INF/spring/
+	-->
+	<context-param>
+		<param-name>contextConfigLocation</param-name>
+		<param-value>
+			/WEB-INF/spring/*.xml
+		</param-value>
+	</context-param>
+
+	<!--
+		DelegatingFilterProxy looks for a Spring bean by the name of filter (springSecurityFilterChain) and delegates
+		all work to that Bean. This is how the Servlet Container can a Spring Bean to act as a Servlet Filter.
+	-->
+	<filter>
+		<filter-name>springSecurityFilterChain</filter-name>
+		<filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
+	</filter>
+	<filter-mapping>
+		<filter-name>springSecurityFilterChain</filter-name>
+		<url-pattern>/*</url-pattern>
+	</filter-mapping>
+
+</web-app>
+----
+====
+
+[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]
+----
+<servlet>
+	<servlet-name>spring</servlet-name>
+	<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
+	<!-- Load Spring MVC configuration from root ApplicationContext (context-param from above) -->
+	<init-param>
+		<param-name>contextConfigLocation</param-name>
+		<param-value></param-value>
+	</init-param>
+</servlet>
+
+<servlet-mapping>
+  <servlet-name>spring</servlet-name>
+  <url-pattern>/</url-pattern>
+</servlet-mapping>
+----
+=====
+====