= 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]
----
<?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
  https://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">

	<!--
	  - Location of the XML file that defines the root application context
	  - Applied by ContextLoaderListener.
	  -->
	<context-param>
		<param-name>contextConfigLocation</param-name>
		<param-value>
			/WEB-INF/spring/*.xml
		</param-value>
	</context-param>


	<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>

	<!--
	  - Loads the root application context of this web app at startup.
	  - The application context is then available via
	  - WebApplicationContextUtils.getWebApplicationContext(servletContext).
	-->
	<listener>
		<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
	</listener>

</web-app>
----

The _web.xml_ will do the following things:

* Registers the `springSecurityFilterChain` Filter for every URL in your application
* Adds a `ContextLoaderListener` that loads the <<security-config-xml,security-config-xml>>.

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]
----
<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 https://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 https://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].
