diff --git a/docs/guides/build.gradle b/docs/guides/build.gradle index d1b92bf49e..5a84b29b3b 100644 --- a/docs/guides/build.gradle +++ b/docs/guides/build.gradle @@ -15,7 +15,8 @@ file("src/asciidoc").eachFileMatch(~/.*\.asc/) { file-> toc: '', idprefix: '', idseparator: '-', - 'spring-security-version' : project.version + 'spring-security-version' : project.version, + revnumber : project.version ] ] } diff --git a/docs/guides/src/asciidoc/Guardfile b/docs/guides/src/asciidoc/Guardfile index 21a269e74d..4f11a925af 100644 --- a/docs/guides/src/asciidoc/Guardfile +++ b/docs/guides/src/asciidoc/Guardfile @@ -3,7 +3,7 @@ require 'erb' guard 'shell' do watch(/^.*\.asc$/) {|m| - Asciidoctor.render_file(m[0], :to_dir => "build/", :safe => Asciidoctor::SafeMode::UNSAFE, :attributes=> {'toc' => '', 'idprefix' => '', 'idseparator' => '-', 'copycss' => '', 'icons' => 'font', 'source-highlighter' => 'prettify', 'sectanchors' => '', 'toc-placement' => 'preamble', 'spring-security-version' => '3.2.0.CI-SNAPSHOT'}) + Asciidoctor.render_file(m[0], :to_dir => "build/", :safe => Asciidoctor::SafeMode::UNSAFE, :attributes=> {'toc' => '', 'idprefix' => '', 'idseparator' => '-', 'copycss' => '', 'icons' => 'font', 'source-highlighter' => 'prettify', 'sectanchors' => '', 'toc-placement' => 'preamble', 'spring-security-version' => '3.2.0.CI-SNAPSHOT', 'revnumber' => '3.2.0.CI-SNAPSHOT' }) } end diff --git a/docs/guides/src/asciidoc/hello-includes/basic-authentication.asc b/docs/guides/src/asciidoc/hello-includes/basic-authentication.asc new file mode 100644 index 0000000000..884e3da011 --- /dev/null +++ b/docs/guides/src/asciidoc/hello-includes/basic-authentication.asc @@ -0,0 +1,22 @@ +==== Basic authentication + +We stated that Spring Security supported both form and HTTP Basic authentication, but how does Spring Security know when to use one and not the other? When using HTTP Basic, the user should receive a HTTP 401 response, but when we visit our application in our web browser we are redirected to a login page. The reason for this is because Spring Security uses content negotiation to determine which type of authentication to use. For example, if we specified our *Accept* header to be _application/json_ the result would be an HTTP 401. + +You can use any tool you prefer (i.e. curl), but the instructions in this section we will use https://www.google.com/intl/en/chrome/browser/[Google Chrome] and the https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en[Postman - REST Client] to make an _application/json_ request to our application. + +* Open Google Chrome and launch the Postman - REST Client extension +* Enter _http://localhost:8080/sample/_ into the request URL field +* Select the *Headers* button +* Enter _Accept_ into the *Header* input +* Enter _application/json_ into the *Value* field +* Presss the *Send* button + +Observe that we get an HTTP Status of 401 instead of our redirect. Now lets try entering our user name and password. + +* Select the *Basic Auth* tab +* Enter _user_ for the *Username* +* Enter _password_ for the *Password* +* Click the *Refresh headers* button +* Click the *Send* button + +This time you should see the HTML of our secured page. diff --git a/docs/guides/src/asciidoc/hello-includes/exploring-the-secured-application.asc b/docs/guides/src/asciidoc/hello-includes/exploring-the-secured-application.asc index 622edb8cb4..c123d913c9 100644 --- a/docs/guides/src/asciidoc/hello-includes/exploring-the-secured-application.asc +++ b/docs/guides/src/asciidoc/hello-includes/exploring-the-secured-application.asc @@ -17,70 +17,3 @@ You should see an error message stating that authentication failed. Now try ente 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 <>. - -==== 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 link as shown below: - -.src/main/webapp/index.jsp -[source,html] ----- - -
-

This is secured!

- -

- Hello -

-

- Click here to log out. -

-
- ----- - -Refresh the page at http://localhost:8080/sample/ and you will see the log out link. Click the link and see that the application logs you out successfully. - -==== Basic authentication - -We stated that Spring Security supported both form and HTTP Basic authentication, but how does Spring Security know when to use one and not the other? When using HTTP Basic, the user should receive a HTTP 401 response, but when we visit our application in our web browser we are redirected to a login page. The reason for this is because Spring Security uses content negotiation to determine which type of authentication to use. For example, if we specified our *Accept* header to be _application/json_ the result would be an HTTP 401. - -You can use any tool you prefer (i.e. curl), but the instructions in this section we will use https://www.google.com/intl/en/chrome/browser/[Google Chrome] and the https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en[Postman - REST Client] to make an _application/json_ request to our application. - -* Open Google Chrome and launch the Postman - REST Client extension -* Enter _http://localhost:8080/sample/_ into the request URL field -* Select the *Headers* button -* Enter _Accept_ into the *Header* input -* Enter _application/json_ into the *Value* field -* Presss the *Send* button - -Observe that we get an HTTP Status of 401 instead of our redirect. Now lets try entering our user name and password. - -* Select the *Basic Auth* tab -* Enter _user_ for the *Username* -* Enter _password_ for the *Password* -* Click the *Refresh headers* button -* Click the *Send* button - -This time you should see the HTML of our secured page. diff --git a/docs/guides/src/asciidoc/hellomvc.asc b/docs/guides/src/asciidoc/hellomvc.asc index 6a947377b4..1aa0c004ca 100644 --- a/docs/guides/src/asciidoc/hellomvc.asc +++ b/docs/guides/src/asciidoc/hellomvc.asc @@ -1,7 +1,6 @@ = Hello Spring MVC Security Java Config -Rob Winch -{spring-security-version} -:starter-appname: insecuremvc +:author: Rob Winch +:starter-appname: insecuremvc :completed-appname: hellomvc-jc :verify-starter-app-include: hello-includes/verify-insecuremvc-app.asc @@ -27,19 +26,22 @@ We have created the Spring Security configuration, but we still need to register ---- package org.springframework.security.samples.config; +import org.springframework.core.annotation.*; import org.springframework.security.web.context.*; -public class SecurityWebApplicationInitializer +@Order(2) +public class MessageSecurityWebApplicationInitializer extends AbstractSecurityWebApplicationInitializer { } ---- -The `SecurityWebApplicationInitializer` will automatically register the springSecurityFilterChain Filter for every URL in your application. +The `MessageSecurityWebApplicationInitializer` will automatically register the springSecurityFilterChain Filter for every URL in your application. We add `@Order(2)` so the springSecurityFilterChain is inserted before our Sitemesh Filter declared in <> === Verify SecurityConfig is loaded - + Just because <> exists, does not mean that our Spring application knows about it. In this instance, our Spring root application context is initialized using MessageWebApplicationInitializer which is included with our spring-security-samples-messages-jc project. You can find a snippet of it below: +[[message-web-application-inititializer-java]] .MessageWebApplicationInitializer.java [source,java] ---- @@ -70,12 +72,64 @@ public class RootConfiguration { } ---- -The `@ComponentScan` is loading all configuration in the org.springframework.security.samples.config package. Since <> is in this package, it will be loaded with our existing setup and there is nothing more to do. +The `@ComponentScan` is loading all configuration in the org.springframework.security.samples.config package. Since <> is in this package, it will be loaded with our existing setup and there is nothing more to do. NOTE: Had <> not been loaded, we could have used an `@Import(SecurityConfig)` above the class definition of <> or added <> as one of the results for `getRootConfigClasses()`. include::hello-includes/exploring-the-secured-application.asc[] +==== Displaying the user name + +Now that we have authenticated, let's update the application to display the username. Update main.jsp to contain the following snippet: + +.src/main/webapp/WEB-INF/decorators/main.jsp +[source,html] +[subs="verbatim,quotes"] +---- +
+ *

+ +

* + +
+---- + +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 link as shown below: + +.src/main/webapp/index.jsp +[source,html] +[subs="verbatim,quotes"] +---- +
+

+ + * + Log out* +

+ +
+---- + +Refresh the page at http://localhost:8080/sample/ and you will see the log out link. Click the link and see that the application logs you out successfully. + +include::hello-includes/basic-authentication.asc[] + == Conclusion You should now now how to secure your application using Spring Security without using any XML. diff --git a/docs/guides/src/asciidoc/helloworld.asc b/docs/guides/src/asciidoc/helloworld.asc index 2eb5de2f48..8260ed7146 100644 --- a/docs/guides/src/asciidoc/helloworld.asc +++ b/docs/guides/src/asciidoc/helloworld.asc @@ -1,6 +1,5 @@ = Hello Spring Security Java Config -Rob Winch -{spring-security-version} +:author: Rob Winch :starter-appname: insecure :completed-appname: helloworld-jc :verify-starter-app-include: hello-includes/verify-insecure-app.asc @@ -47,6 +46,52 @@ NOTE: Since we were not already using Spring, this is a simple way to add our << include::hello-includes/exploring-the-secured-application.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 link as shown below: + +.src/main/webapp/index.jsp +[source,html] +---- + +
+

This is secured!

+ +

+ Hello +

+

+ Click here to log out. +

+
+ +---- + +Refresh the page at http://localhost:8080/sample/ and you will see the log out link. Click the link and see that the application logs you out successfully. + +include::hello-includes/basic-authentication.asc[] + == Conclusion You should now now how to secure your application using Spring Security without using any XML.