GitHub-Spring
/
spring-security
mirror of https://github.com/spring-projects/spring-security.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Only Hello Spring Security Boot 

For those getting started, we really need to send the message of using
Spring Boot.

Fixes gh-7627
pull/7589/head
Rob Winch 6 years ago
parent
c5b36664ce
commit
af47e730a0
5 changed files with 72 additions and 358 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 1
      docs/manual/spring-security-docs-manual.gradle
  2. 67
      docs/manual/src/docs/asciidoc/_includes/servlet/hello/boot.adoc
  3. 76
      docs/manual/src/docs/asciidoc/_includes/servlet/hello/index.adoc
  4. 138
      docs/manual/src/docs/asciidoc/_includes/servlet/hello/java-configuration.adoc
  5. 148
      docs/manual/src/docs/asciidoc/_includes/servlet/hello/xml-configuration.adoc

1
docs/manual/spring-security-docs-manual.gradle
Unescape View File

@ -5,6 +5,7 @@ asciidoctor { @@ -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"

67
docs/manual/src/docs/asciidoc/_includes/servlet/hello/boot.adoc
Unescape View File

@ -1,67 +0,0 @@ @@ -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 <<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
* 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()`]

76
docs/manual/src/docs/asciidoc/_includes/servlet/hello/index.adoc
Unescape View File

@ -1,8 +1,74 @@ @@ -1,8 +1,74 @@
[[servlet-hello]]
= 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
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 <<getting-maven-boot,Maven>> or <<getting-gradle-boot,Gradle>>.
[[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]

138
docs/manual/src/docs/asciidoc/_includes/servlet/hello/java-configuration.adoc
Unescape View File

@ -1,138 +0,0 @@ @@ -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 <<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-no-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
* 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 <<servlet-hello-jc-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[] { "/" };
}
}
----
=====
====

148
docs/manual/src/docs/asciidoc/_includes/servlet/hello/xml-configuration.adoc
Unescape View File

@ -1,148 +0,0 @@ @@ -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 <<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 https://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/security https://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
* 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]
----
<?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>
----
=====
====
Write Preview
Loading…
Cancel
Save