<?xml version="1.0" encoding="UTF-8"?>
<chapter xml:id="flow-security"
	xmlns="http://docbook.org/ns/docbook" version="5.0"
	xmlns:xl="http://www.w3.org/1999/xlink"
	xmlns:xi="http://www.w3.org/2001/XInclude"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="
		http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd
		http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd">
	<title>Securing Flows</title>
	<sect1 xml:id="flow-security-introduction">
		<title>Introduction</title>
		<para>
			Security is an important concept for any application.
			End users should not be able to access any portion of a site simply by guessing the URL.
			Areas of a site that are sensitive must ensure that only authorized requests are processed.
			Spring Security is a proven security platform that can integrate with your application at multiple levels.
			This section will focus on securing flow execution.
		</para>
	</sect1>
	<sect1 xml:id="flow-security-how-to">
		<title>How do I secure a flow?</title>
		<para>
			Securing flow execution is a three step process:
			<itemizedlist>
				<listitem><para>Configure Spring Security with authentication and authorization rules</para></listitem>
				<listitem><para>Annotate the flow definition with the secured element to define the security rules</para></listitem>
				<listitem><para>Add the SecurityFlowExecutionListener to process the security rules.</para></listitem>
			</itemizedlist>
		</para>
		<para>
			Each of these steps must be completed or else flow security rules will not be applied.
		</para>
	</sect1>
	<sect1 xml:id="flow-security-secured-element">
		<title>The secured element</title>
		<para>
			The secured element designates that its containing element should apply the authorization check before fully entering.
			This may not occur more then once per stage of the flow execution that is secured.
		</para>
		<para>
			Three phases of flow execution can be secured: flows, states and transitions.
			In each case the syntax for the secured element is identical.
			The secured element is located inside the element it is securing.
			For example, to secure a state the secured element occurs directly inside that state:
		</para>
		<programlisting language="xml"><![CDATA[
<view-state id="secured-view">
    <secured attributes="ROLE_USER" />
    ...
</view-state>]]>
		</programlisting>
		<sect2 xml:id="flow-security-secured-element-attributes">
			<title>Security attributes</title>
			<para>
				The <code>attributes</code> attribute is a comma separated list of Spring Security authorization attributes.
				Often, these are specific security roles.
				The attributes are compared against the user's granted attributes by a Spring Security access decision manager.
			</para>
			<programlisting language="xml"><![CDATA[
<secured attributes="ROLE_USER" />]]>
			</programlisting>
			<para>
				By default, a role based access decision manager is used to determine if the user is allowed access.
				This will need to be overridden if your application is not using authorization roles.
			</para>
		</sect2>
		<sect2 xml:id="flow-security-secured-element-match">
			<title>Matching type</title>
			<para>
				There are two types of matching available: <code>any</code> and <code>all</code>.
				Any, allows access if at least one of the required security attributes is granted to the user.
				All, allows access only if each of the required security attributes are granted to the user.
			</para>
			<programlisting language="xml"><![CDATA[
<secured attributes="ROLE_USER, ROLE_ANONYMOUS" match="any" />]]>
			</programlisting>
			<para>
				This attribute is optional.
				If not defined, the default value is <code>any</code>.
			</para>
			<para>
				The <code>match</code> attribute will only be respected if the default access decision manager is used.
			</para>
		</sect2>
	</sect1>
	<sect1 xml:id="flow-security-listener">
		<title>The SecurityFlowExecutionListener</title>
		<para>
			Defining security rules in the flow by themselves will not protect the flow execution.
			A <code>SecurityFlowExecutionListener</code> must also be defined in the webflow configuration and applied to the flow executor.
		</para>
		<programlisting language="xml"><![CDATA[
<webflow:flow-executor id="flowExecutor" flow-registry="flowRegistry">
    <webflow:flow-execution-listeners>
        <webflow:listener ref="securityFlowExecutionListener" />
    </webflow:flow-execution-listeners>
</webflow:flow-executor>

<bean id="securityFlowExecutionListener"
      class="org.springframework.webflow.security.SecurityFlowExecutionListener" />
		]]></programlisting>
		<para>
			If access is denied to a portion of the application an <code>AccessDeniedException</code> will be thrown.
			This exception will later be caught by Spring Security and used to prompt the user to authenticate.
			It is important that this exception be allowed to travel up the execution stack uninhibited, otherwise the end user may not be prompted to authenticate.
		</para>
		<sect2 xml:id="flow-security-listener-adm">
			<title>Custom Access Decision Managers</title>
			<para>
				If your application is using authorities that are not role based, you will need to configure a custom <code>AccessDecisionManager</code>.
				You can override the default decision manager by setting the <code>accessDecisionManager</code> property on the security listener.
				Please consult the <link xl:href="http://static.springframework.org/spring-security/site/reference.html">Spring Security reference documentation</link> to learn more about decision managers.
			</para>
			<programlisting language="xml"><![CDATA[
<bean id="securityFlowExecutionListener"
      class="org.springframework.webflow.security.SecurityFlowExecutionListener">
    <property name="accessDecisionManager" ref="myCustomAccessDecisionManager" />
</bean>
			]]></programlisting>
		</sect2>
	</sect1>
	<sect1 xml:id="flow-security-configuration">
		<title>Configuring Spring Security</title>
		<para>
			Spring Security has robust configuration options available.
			As every application and environment has its own security requirements, the <link xl:href="http://static.springframework.org/spring-security/site/reference.html">Spring Security reference documentation</link> is the best place to learn the available options.
		</para>
		<para>
			Both the <code>booking-faces</code> and <code>booking-mvc</code> sample applications are configured to use Spring Security.
			Configuration is needed at both the Spring and web.xml levels.
		</para>
		<sect2 xml:id="flow-security-configuration-spring">
			<title>Spring configuration</title>
			<para>
				The Spring configuration defines <code>http</code> specifics (such as protected URLs and login/logout mechanics) and the <code>authentication-provider</code>.
				For the sample applications, a local authentication provider is configured.
			</para>
			<programlisting language="xml"><![CDATA[
<security:http auto-config="true">
    <security:form-login login-page="/spring/login"
                         login-processing-url="/spring/loginProcess"
                         default-target-url="/spring/main"
                         authentication-failure-url="/spring/login?login_error=1" />
    <security:logout logout-url="/spring/logout" logout-success-url="/spring/logout-success" />
</security:http>

<security:authentication-provider>
    <security:password-encoder hash="md5" />
    <security:user-service>
        <security:user name="keith" password="417c7382b16c395bc25b5da1398cf076"
                       authorities="ROLE_USER,ROLE_SUPERVISOR" />
        <security:user name="erwin" password="12430911a8af075c6f41c6976af22b09"
                       authorities="ROLE_USER,ROLE_SUPERVISOR" />
        <security:user name="jeremy" password="57c6cbff0d421449be820763f03139eb"
                       authorities="ROLE_USER" />
        <security:user name="scott" password="942f2339bf50796de535a384f0d1af3e"
                       authorities="ROLE_USER" />
    </security:user-service>
</security:authentication-provider>]]>
			</programlisting>
		</sect2>
		<sect2 xml:id="flow-security-configuration-web">
			<title>web.xml Configuration</title>
			<para>
				In the <code>web.xml</code> file, a <code>filter</code> is defined to intercept all requests.
				This filter will listen for login/logout requests and process them accordingly.
				It will also catch <code>AccesDeniedException</code>s and redirect the user to the login page.
			</para>
			<programlisting language="xml"><![CDATA[
<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>]]>
			</programlisting>
		</sect2>
	</sect1>
</chapter>
