spring-security/docs/guides/src/asciidoc/helloworld.asc

= Hello Spring Security Java Config
:author: Rob Winch
:starter-appname: insecure
:completed-appname: helloworld-jc
:include-dir: _includes
:hello-include-dir: _hello-includes

This guide provides instructions on how to add Spring Security to an existing application without the use of XML.

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.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
* Select *New->Class*
* Enter _SecurityWebApplicationInitializer_ for the *Name*
* Click *Finish*
* Replace the file with the following contents:

.src/main/java/org/springframework/security/samples/config/SecurityWebApplicationInitializer.java
[source,java]
----
package org.springframework.security.samples.config;

import org.springframework.security.web.context.*;

public class SecurityWebApplicationInitializer
      extends AbstractSecurityWebApplicationInitializer {

    public SecurityWebApplicationInitializer() {
        super(SecurityConfig.class);
    }
}
----

The `SecurityWebApplicationInitializer` will do the following things:

* Automatically register the springSecurityFilterChain Filter for every URL in your application
* Add a ContextLoaderListener that loads the <<security-config-java,SecurityConfig>>.

NOTE: Since we were not already using Spring, this is a simple way to add our <<security-config-java,SecurityConfig>>. If we were already using Spring, then we should add our <<security-config-java,SecurityConfig>> 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[]

==== 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]
----
<body>
  <div class="container">
    <h1>This is secured!</h1>
    <p>
      Hello <b><c:out value="${pageContext.request.remoteUser}"/></b>
    </p>
  </div>
</body>
----

WARNING: The `<c:out />` 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 <<servlet-api-integration,Servlet API methods>>

==== 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]
----
<body>
  <div class="container">
    <h1>This is secured!</h1>
    <p>
      Hello <b><c:out value="${pageContext.request.remoteUser}"/></b>
    </p>
    <c:url var="logoutUrl" value="/logout"/>
    <form class="form-inline" action="${logoutUrl}" method="post">
      <input type="submit" value="Log out" />
      <input type="hidden" name="${_csrf.parameterName}" value="${_csrf.token}"/>
    </form>
  </div>
</body>
----

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.

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 without using any XML. To learn more refer to the link:index.html[Spring Security Guides index page].
SEC-2251: Create Hello World Java Configuration guides 2013-08-07 00:35:48 +08:00			`= Hello Spring Security Java Config`
SEC-2251: Polish Hello World guides * Correct how to add username and logout to mvc * Externalize :revnumber: 2013-08-10 00:47:04 +08:00			`:author: Rob Winch`
SEC-1574: Add CSRF Support 2013-08-16 03:49:21 +08:00			`:starter-appname: insecure`
SEC-2251: Create Hello World Java Configuration guides 2013-08-07 00:35:48 +08:00			`:completed-appname: helloworld-jc`
Polish Guides 2013-12-07 01:12:07 +08:00			`:include-dir: _includes`
			`:hello-include-dir: _hello-includes`
SEC-2251: Create Hello World Java Configuration guides 2013-08-07 00:35:48 +08:00
			`This guide provides instructions on how to add Spring Security to an existing application without the use of XML.`

Update to latest Asciidoctor version We will temporarily remove PDF support until the plugin supports it. 2013-10-31 05:56:00 +08:00			`include::{include-dir}/setting-up-the-sample.asc[]`
SEC-2251: Create Hello World Java Configuration guides 2013-08-07 00:35:48 +08:00
Polish Guides 2013-12-07 01:12:07 +08:00			`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.asc[]`
SEC-2251: Create Hello World Java Configuration guides 2013-08-07 00:35:48 +08:00
			`=== Registering Spring Security with the war`

Polish guide 2013-10-16 23:44:16 +08:00			`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:`
SEC-2251: Create Hello World Java Configuration guides 2013-08-07 00:35:48 +08:00
			`* Navigate to the Package Explorer view`
			`* Right click the org.springframework.security.samples.config package within the spring-security-samples-{starter-appname} project`
			`* Select New->Class`
			`* Enter _SecurityWebApplicationInitializer_ for the Name`
			`* Click Finish`
			`* Replace the file with the following contents:`

			`.src/main/java/org/springframework/security/samples/config/SecurityWebApplicationInitializer.java`
			`[source,java]`
			`----`
			`package org.springframework.security.samples.config;`

			`import org.springframework.security.web.context.*;`

			`public class SecurityWebApplicationInitializer`
			`extends AbstractSecurityWebApplicationInitializer {`

			`public SecurityWebApplicationInitializer() {`
			`super(SecurityConfig.class);`
			`}`
			`}`
			`----`

			The `SecurityWebApplicationInitializer` will do the following things:

			`* Automatically register the springSecurityFilterChain Filter for every URL in your application`
Polish Guides 2013-12-07 01:12:07 +08:00			`* Add a ContextLoaderListener that loads the <<security-config-java,SecurityConfig>>.`
SEC-2251: Create Hello World Java Configuration guides 2013-08-07 00:35:48 +08:00
Polish Guides 2013-12-07 01:12:07 +08:00			`NOTE: Since we were not already using Spring, this is a simple way to add our <<security-config-java,SecurityConfig>>. If we were already using Spring, then we should add our <<security-config-java,SecurityConfig>> with the reset of our Spring configuration (i.e. a subclass of AbstractContextLoaderInitializer or AbstractDispatcherServletInitializer) and use the default constructor instead.`
SEC-2251: Create Hello World Java Configuration guides 2013-08-07 00:35:48 +08:00
Polish Guides 2013-12-07 01:12:07 +08:00			`include::{hello-include-dir}/exploring-the-secured-application.asc[]`
SEC-2251: Create Hello World Java Configuration guides 2013-08-07 00:35:48 +08:00
SEC-2251: Polish Hello World guides * Correct how to add username and logout to mvc * Externalize :revnumber: 2013-08-10 00:47:04 +08:00			`==== 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]`
			`----`
			`<body>`
			`<div class="container">`
			`<h1>This is secured!</h1>`
			`<p>`
			`Hello <b><c:out value="${pageContext.request.remoteUser}"/></b>`
			`</p>`
			`</div>`
			`</body>`
			`----`

			WARNING: The `<c:out />` 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 <<servlet-api-integration,Servlet API methods>>`

			`==== Logging out`

Polish Guides 2013-12-07 01:12:07 +08:00			`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:`
SEC-2251: Polish Hello World guides * Correct how to add username and logout to mvc * Externalize :revnumber: 2013-08-10 00:47:04 +08:00
			`.src/main/webapp/index.jsp`
			`[source,html]`
			`----`
			`<body>`
			`<div class="container">`
			`<h1>This is secured!</h1>`
			`<p>`
SEC-1574: Add CSRF Support 2013-08-16 03:49:21 +08:00			`Hello <b><c:out value="${pageContext.request.remoteUser}"/></b>`
SEC-2251: Polish Hello World guides * Correct how to add username and logout to mvc * Externalize :revnumber: 2013-08-10 00:47:04 +08:00			`</p>`
SEC-1574: Add CSRF Support 2013-08-16 03:49:21 +08:00			`<c:url var="logoutUrl" value="/logout"/>`
			`<form class="form-inline" action="${logoutUrl}" method="post">`
			`<input type="submit" value="Log out" />`
			`<input type="hidden" name="${_csrf.parameterName}" value="${_csrf.token}"/>`
			`</form>`
SEC-2251: Polish Hello World guides * Correct how to add username and logout to mvc * Externalize :revnumber: 2013-08-10 00:47:04 +08:00			`</div>`
			`</body>`
			`----`

SEC-1574: Add CSRF Support 2013-08-16 03:49:21 +08:00			`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`
Polish Guides 2013-12-07 01:12:07 +08:00			`* 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.`
SEC-1574: Add CSRF Support 2013-08-16 03:49:21 +08:00
			`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.`
SEC-2251: Polish Hello World guides * Correct how to add username and logout to mvc * Externalize :revnumber: 2013-08-10 00:47:04 +08:00
SEC-2251: Create Hello World Java Configuration guides 2013-08-07 00:35:48 +08:00			`== Conclusion`

Polish Guides 2013-12-07 01:12:07 +08:00			`You should now know how to secure your application using Spring Security without using any XML. To learn more refer to the link:index.html[Spring Security Guides index page].`