diff --git a/docs/guides/src/docs/asciidoc/_hello-includes/exploring-the-secured-application.asc b/docs/guides/src/docs/asciidoc/_hello-includes/exploring-the-secured-application-javaconfig.asc similarity index 100% rename from docs/guides/src/docs/asciidoc/_hello-includes/exploring-the-secured-application.asc rename to docs/guides/src/docs/asciidoc/_hello-includes/exploring-the-secured-application-javaconfig.asc diff --git a/docs/guides/src/docs/asciidoc/_hello-includes/exploring-the-secured-application-xml.asc b/docs/guides/src/docs/asciidoc/_hello-includes/exploring-the-secured-application-xml.asc new file mode 100644 index 0000000000..b8c6d971fe --- /dev/null +++ b/docs/guides/src/docs/asciidoc/_hello-includes/exploring-the-secured-application-xml.asc @@ -0,0 +1,19 @@ +=== Exploring the secured application + +Start the server as we did in <> Now when you visit http://localhost:8080/sample/ you will be prompted with a login page that is automatically generated by Spring Security. + +==== Authenticating to the secured application + +Try entering an invalid username and password: + +* *Username* _invalid_ +* *Password* _invalid_ + +You should see an error message stating that authentication failed. Now try entering a valid username and password: + +* *Username* _user_ +* *Password* _password_ + +You should now see the page that we wanted to secure. + +NOTE: The reason we can successfully authenticate with *Username* _user_ and *Password* _password_ is because that is what we configured in our <>. diff --git a/docs/guides/src/docs/asciidoc/_hello-includes/secure-the-application.asc b/docs/guides/src/docs/asciidoc/_hello-includes/secure-the-application-javaconfig.asc similarity index 95% rename from docs/guides/src/docs/asciidoc/_hello-includes/secure-the-application.asc rename to docs/guides/src/docs/asciidoc/_hello-includes/secure-the-application-javaconfig.asc index 9b910e8efe..67ff008038 100644 --- a/docs/guides/src/docs/asciidoc/_hello-includes/secure-the-application.asc +++ b/docs/guides/src/docs/asciidoc/_hello-includes/secure-the-application-javaconfig.asc @@ -29,7 +29,7 @@ In order to use Spring Security you must add the necessary dependencies. For the After you have completed this, you need to ensure that STS knows about the updated dependencies by: -* Right click on the _spring-security-samples-{starter-appname}_ application +* Right click on the _spring-security-samples-{starter-config-type}-{starter-appname}_ application * Select *Maven->Update project...* * Ensure the project is selected, and click *OK* @@ -37,7 +37,7 @@ After you have completed this, you need to ensure that STS knows about the updat The next step is to create a Spring Security configuration. -* Right click the _spring-security-samples-{starter-appname}_ project the Package Explorer view +* Right click the _spring-security-samples-{starter-config-type}-{starter-appname}_ project in the Package Explorer view * Select *New->Class* * Enter _org.springframework.security.samples.config_ for the *Package* * Enter _SecurityConfig_ for the *Name* diff --git a/docs/guides/src/docs/asciidoc/_hello-includes/secure-the-application-xml.asc b/docs/guides/src/docs/asciidoc/_hello-includes/secure-the-application-xml.asc new file mode 100644 index 0000000000..1119a3482d --- /dev/null +++ b/docs/guides/src/docs/asciidoc/_hello-includes/secure-the-application-xml.asc @@ -0,0 +1,89 @@ +== Securing the application + +Before securing your application, it is important to ensure that the existing application works as we did in <>. Now that the application runs without security, we are ready to add security to our application. This section demonstrates the minimal steps to add Spring Security to our application. + +=== Updating your dependencies + +include::../{include-maven-repository}[] + +In order to use Spring Security you must add the necessary dependencies. For the sample we will add the following Spring Security dependencies: + +.pom.xml +[source,xml] +[subs="verbatim,attributes"] +---- + + + + org.springframework.security + spring-security-web + {spring-security-version} + + + org.springframework.security + spring-security-config + {spring-security-version} + + +---- + +After you have completed this, you need to ensure that STS knows about the updated dependencies by: + +* Right click on the _spring-security-samples-{starter-config-type}-{starter-appname}_ application +* Select *Maven->Update project...* +* Ensure the project is selected, and click *OK* + +=== Creating your Spring Security configuration + +The next step is to create a Spring Security configuration. + +* In the Package Explorer view, right click on the folder _src/main/webapp_ +* Select *New->Folder* +* Enter _WEB-INF/spring_ for the *Folder name* +* Then right click on the new folder _WEB-INF/spring_ +* Select *New->File* +* Enter _security.xml_ for the *File name* +* Click *Finish* +* Replace the contents of the file with the following: + +[[security-config-xml]] +.src/main/webapp/WEB-INF/spring/security.xml +[source,xml] +---- + + + + + + + + + +---- + +[[servlet-api-integration]] +The <> will: + +* Require authentication to every URL in your application +* Generate a login form for you +* Allow the user with the *Username* _user_ and the *Password* _password_ to authenticate with form based authentication +* Allow the user to logout +* 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/guides/src/docs/asciidoc/_includes/setting-up-the-sample.asc b/docs/guides/src/docs/asciidoc/_includes/setting-up-the-sample.asc index 5b5eaf2502..96c66dd1cc 100644 --- a/docs/guides/src/docs/asciidoc/_includes/setting-up-the-sample.asc +++ b/docs/guides/src/docs/asciidoc/_includes/setting-up-the-sample.asc @@ -2,39 +2,42 @@ Variables: -starter-appname: the name of the module users should start with to complete the excercise +starter-appname: the name of the module users should start with to complete the exercise +starter-config-type: the type of configuration the starter sample uses: javaconfig, xml, boot completed-appname: the name of the module that contains the completed application +completed-config-type: the type of configuration the completed sample uses: javaconfig, xml, boot download-url: the URL to download the Spring Security distribution + //// == Setting up the sample -This section outlines how to setup a workspace within https://spring.io/tools/sts[Spring Tool Suite (STS)] so that you can follow along with this guide. The next section outlines generic steps for how to apply Spring Security to your existing application. While you could simply apply the steps to your existing application, we encourage you to follow along with this guide as is to reduce the complexity. +This section outlines how to setup a workspace within https://spring.io/tools/sts[Spring Tool Suite (STS)] so that you can follow along with this guide. The next section outlines generic steps for how to apply Spring Security to your existing application. While you could simply apply the steps to your existing application, we encourage you to follow along with this guide in order to reduce the complexity. -=== Obtaining the sample projects +=== Obtaining the sample project Extract the {download-url}[Spring Security Distribution] to a known location and remember it as _SPRING_SECURITY_HOME_. === Import the {starter-appname} sample application -In order to follow along, we encourage you to import the {starter-appname} sample application into your IDE. You may use any IDE you prefer, but the instructions in the guide will assume you are using Spring Tool Suite (STS). +In order to follow along, we encourage you to import the {starter-appname} sample application into your IDE. You may use any IDE you prefer, but the instructions in this guide will assume you are using Spring Tool Suite (STS). -TIP: The completed sample application can be found at _SPRING_SECURITY_HOME_/samples/{completed-appname} +TIP: The completed sample application can be found at _SPRING_SECURITY_HOME_/samples/{completed-config-type}/{completed-appname} * If you do not have STS installed, download STS from https://spring.io/tools -* Start STS and import the sample applications into STS using the following steps: +* Start STS and import the sample application into STS using the following steps: ** *File->Import* ** *Existing Maven Projects* ** Click *Next >* ** Click *Browse...* -** Navigate to the samples (i.e. _SPRING_SECURITY_HOME_/samples/{starter-appname}) and click *OK* +** Navigate to the samples (i.e. _SPRING_SECURITY_HOME_/samples/{starter-config-type}/{starter-appname}) and click *OK* ** Click *Finish* === Running the {starter-appname} application -In the following exercise we will be modifying the _spring-security-samples-{starter-appname}_ application. Before we make any changes, it is best to verify that the sample works properly. Perform the following steps to ensure that _spring-security-samples-{starter-appname}_ works. +In the following exercise we will be modifying the _spring-security-samples-{starter-config-type}-{starter-appname}_ application. Before we make any changes, it is best to verify that the sample works properly. Perform the following steps to ensure that _spring-security-samples-{starter-config-type}-{starter-appname}_ works. -* Right click on the _spring-security-samples-{starter-appname}_ application +* Right click on the _spring-security-samples-{starter-config-type}-{starter-appname}_ application * Select *Run As->Run on Server* * Select the latest tc Server -* Click *Finish* \ No newline at end of file +* Click *Finish* diff --git a/docs/guides/src/docs/asciidoc/helloworld.asc b/docs/guides/src/docs/asciidoc/helloworld-javaconfig.asc similarity index 90% rename from docs/guides/src/docs/asciidoc/helloworld.asc rename to docs/guides/src/docs/asciidoc/helloworld-javaconfig.asc index 66e4dbc7b9..5fdee917c2 100644 --- a/docs/guides/src/docs/asciidoc/helloworld.asc +++ b/docs/guides/src/docs/asciidoc/helloworld-javaconfig.asc @@ -1,7 +1,9 @@ = Hello Spring Security Java Config :author: Rob Winch :starter-appname: insecure -:completed-appname: javaconfig/helloworld +:starter-config-type: xml +:completed-appname: helloworld +:completed-config-type: javaconfig :include-dir: _includes :hello-include-dir: _hello-includes @@ -16,14 +18,14 @@ Once you have verified the application runs, stop the application server using t * In the Servers view select the latest tc Server * Click the stop button (a red square) to stop the application server -include::{hello-include-dir}/secure-the-application.asc[] +include::{hello-include-dir}/secure-the-application-javaconfig.asc[] === Registering Spring Security with the war We have created the Spring Security configuration, but we still need to register it with the war. This can be done using the following steps: * Navigate to the *Package Explorer* view -* Right click the *org.springframework.security.samples.config* package within the *spring-security-samples-{starter-appname}* project +* Right click the *org.springframework.security.samples.config* package within the *spring-security-samples-{starter-config-type}-{starter-appname}* project * Select *New->Class* * Enter _SecurityWebApplicationInitializer_ for the *Name* * Click *Finish* @@ -52,7 +54,7 @@ The `SecurityWebApplicationInitializer` will do the following things: NOTE: Since we were not already using Spring, this is a simple way to add our <>. If we were already using Spring, then we should add our <> with the reset of our Spring configuration (i.e. a subclass of AbstractContextLoaderInitializer or AbstractDispatcherServletInitializer) and use the default constructor instead. -include::{hello-include-dir}/exploring-the-secured-application.asc[] +include::{hello-include-dir}/exploring-the-secured-application-javaconfig.asc[] ==== Displaying the user name @@ -100,7 +102,7 @@ Now that we can view the user name, let's update the application to allow loggin In order to help protect against http://en.wikipedia.org/wiki/Cross-site_request_forgery[CSRF attacks], by default, Spring Security Java Configuration log out requires: * the HTTP method must be a POST -* the CSRF token must be added to the request You can access it on the ServletRequest using the attribute _csrf as illustrated above. +* the CSRF token must be added to the request. You can access it on the ServletRequest using the attribute _csrf as illustrated above. NOTE: If you were using Spring MVC's tag library or Thymeleaf, the CSRF token is automatically added as a hidden input for you. diff --git a/docs/guides/src/docs/asciidoc/helloworld-xml.asc b/docs/guides/src/docs/asciidoc/helloworld-xml.asc new file mode 100644 index 0000000000..78f5e69f2d --- /dev/null +++ b/docs/guides/src/docs/asciidoc/helloworld-xml.asc @@ -0,0 +1,136 @@ += Hello Spring Security Xml Config +:author: Joe Grandja +:starter-appname: insecure +:starter-config-type: xml +:completed-appname: helloworld +:completed-config-type: xml +:include-dir: _includes +:hello-include-dir: _hello-includes + +This guide provides instructions on how to add Spring Security to an existing application using XML configuration. + +include::{include-dir}/setting-up-the-sample.asc[] + +Verify the application is working by ensuring a page stating *TODO Secure this* is displayed at http://localhost:8080/sample/ + +Once you have verified the application runs, stop the application server using the following steps: + +* In the Servers view select the latest tc Server +* Click the stop button (a red square) to stop the application server + +include::{hello-include-dir}/secure-the-application-xml.asc[] + +=== Registering Spring Security with the war + +We have created the Spring Security configuration, but we still need to register it with the war. This can be done using the following steps: + +* In the Package Explorer view, right click on the folder _src/main/webapp/WEB-INF_ +* Select *New->File* +* Enter _web.xml_ for the *File name* +* Click *Finish* +* Replace the contents of the file with the following: + +.src/main/webapp/WEB-INF/web.xml +[source,xml] +---- + + + + + + contextConfigLocation + + /WEB-INF/spring/*.xml + + + + + + springSecurityFilterChain + org.springframework.web.filter.DelegatingFilterProxy + + + springSecurityFilterChain + /* + + + + + org.springframework.web.context.ContextLoaderListener + + + +---- + +The _web.xml_ will do the following things: + +* Registers the `springSecurityFilterChain` Filter for every URL in your application +* Adds a `ContextLoaderListener` that loads the <>. + +include::{hello-include-dir}/exploring-the-secured-application-xml.asc[] + +==== Displaying the user name + +Now that we have authenticated, let's update the application to display the username. Update the body of index.jsp to be the following: + +.src/main/webapp/index.jsp +[source,html] +---- + +
+

This is secured!

+

+ Hello +

+
+ +---- + +WARNING: The `` tag ensures the username is escaped to avoid http://en.wikipedia.org/wiki/Cross-site_scripting[XSS vulnerabilities] Regardless of how an application renders user inputed values, it should ensure that the values are properly escaped. + +Refresh the page at http://localhost:8080/sample/ and you will see the user name displayed. This works because Spring Security integrates with the <> + +==== Logging out + +Now that we can view the user name, let's update the application to allow logging out. Update the body of index.jsp to contain a log out form as shown below: + +.src/main/webapp/index.jsp +[source,html] +---- + +
+

This is secured!

+

+ Hello +

+ +
+ + +
+
+ +---- + +In order to help protect against http://en.wikipedia.org/wiki/Cross-site_request_forgery[CSRF attacks], by default, Spring Security Xml Configuration log out requires: + +* the HTTP method must be a POST +* the CSRF token must be added to the request. You can access it on the ServletRequest using the attribute _csrf as illustrated above. + +NOTE: If you were using Spring MVC's tag library or Thymeleaf, the CSRF token is automatically added as a hidden input for you. + +Refresh the page at http://localhost:8080/sample/ and you will see the log out button. Click the logout button and see that the application logs you out successfully. + +== Conclusion + +You should now know how to secure your application using Spring Security with XML. To learn more refer to the link:index.html[Spring Security Guides index page]. diff --git a/docs/guides/src/docs/asciidoc/index.asc b/docs/guides/src/docs/asciidoc/index.asc index 3444b36b49..fab82ea7e1 100644 --- a/docs/guides/src/docs/asciidoc/index.asc +++ b/docs/guides/src/docs/asciidoc/index.asc @@ -7,9 +7,10 @@ These are step by step guides on how to use Spring Security. These are the most basic starting points for using a web based application. -* link:helloworld.html[Hello Spring Security Java Config] - demonstrates how to integrate Spring Security with an existing application that does not already use Spring +* link:helloworld-javaconfig.html[Hello Spring Security Java Config] - demonstrates how to integrate Spring Security with an existing application using Java-based configuration +* link:helloworld-xml.html[Hello Spring Security Xml Config] - demonstrates how to integrate Spring Security with an existing application using Xml-based configuration * link:hellomvc.html[Hello Spring MVC Security Java Config] - demonstrates how to integrate Spring Security with an existing Spring MVC application == Simple Customization -* link:form.html[Creating a custom login form] - demonstrates how to create a custom login form \ No newline at end of file +* link:form.html[Creating a custom login form] - demonstrates how to create a custom login form