spring-security/docs/manual/src/docbook/web-infrastructure.xml

<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="web-infrastructure"
    xmlns:xlink="http://www.w3.org/1999/xlink">
    <info>
        <title>Web Application Infrastructure</title>
    </info>

    <section xml:id="filters">
        <title>The Security Filter Chain</title>
        <para>Spring Security's web infrastructure is based entirely on standard servlet filters. It
            doesn't use servlets or any other servlet-based frameworks (such as Spring MVC)
            internally, so it has no strong links to any particular web technology. It deals in
            <classname>HttpServletRequest</classname>s and
            <classname>HttpServletResponse</classname>s and doesn't care whether the requests come
            from a browser, a web service client, an <classname>HttpInvoker</classname> or an AJAX
            application. </para>
        <para> Spring Security maintains a filter chain internally where each of the filters has a
            particular responsibility and filters are added or removed from the configuration
            depending on which services are required. The ordering of the filters is important as
            there are dependencies between them. If you have been using <link
            xlink:href="#ns-config">namespace configuration</link>, then the filters are
            automatically configured for you and you don't have to define any Spring beans
            explicitly but here may be times when you want full control over the security filter
            chain, either because you are using features which aren't supported in the namespace, or
            you are using your own customized versions of classes.</para>
        <section xml:id="delegating-filter-proxy">
            <title><classname>DelegatingFilterProxy</classname></title>
            <para> When using servlet filters, you obviously need to declare them in your
                <filename>web.xml</filename>, or they will be ignored by the servlet container. In
                Spring Security, the filter classes are also Spring beans defined in the application
                context and thus able to take advantage of Spring's rich dependency-injection
                facilities and lifecycle interfaces. Spring's
                <classname>DelegatingFilterProxy</classname> provides the link between
                <filename>web.xml</filename> and the application context. </para>
            <para>When using <classname>DelegatingFilterProxy</classname>, you will see something
                like this in the <filename>web.xml</filename> file: <programlisting><![CDATA[
  <filter>
    <filter-name>myFilter</filter-name>
    <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
  </filter>

  <filter-mapping>
    <filter-name>myFilter</filter-name>
    <url-pattern>/*</url-pattern>
  </filter-mapping>]]>
        </programlisting> Notice that the filter is actually a
                <literal>DelegatingFilterProxy</literal>, and not the class that will actually
                implement the logic of the filter. What <classname>DelegatingFilterProxy</classname>
                does is delegate the <interfacename>Filter</interfacename>'s methods through to a
                bean which is obtained from the Spring application context. This enables the bean to
                benefit from the Spring web application context lifecycle support and configuration
                flexibility. The bean must implement
                <interfacename>javax.servlet.Filter</interfacename> and it must have the same name
                as that in the <literal>filter-name</literal> element. Read the Javadoc for
                <classname>DelegatingFilterProxy</classname> for more information</para>
        </section>
        <section xml:id="filter-chain-proxy">
            <title><classname>FilterChainProxy</classname></title>
            <para> It should now be clear that you can declare each Spring Security filter bean that
                you require in your application context file and add a corresponding
                <classname>DelegatingFilterProxy</classname> entry to <filename>web.xml</filename>
                for each filter, making sure that they are ordered correctly. This is a cumbersome
                approach and clutters up the <filename>web.xml</filename> file quickly if we have a
                lot of filters. We would prefer to just add a single entry to
                <filename>web.xml</filename> and deal entirely with the application context file for
                managing our web security beans. This is where Spring Secuiryt's
                <classname>FilterChainProxy</classname> comes in. It is wired using a
                <literal>DelegatingFilterProxy</literal>, just like in the example above, but with
                the <literal>filter-name</literal> set to the bean name
                <quote>filterChainProxy</quote>. The filter chain is then declared in the
                application context with the same bean name. Here's an example: <programlisting language="xml"><![CDATA[
<bean id="filterChainProxy" class="org.springframework.security.web.FilterChainProxy">
  <sec:filter-chain-map path-type="ant">
     <sec:filter-chain pattern="/webServices/**" filters="
           securityContextPersistenceFilterWithASCFalse,
           basicProcessingFilter,
           exceptionTranslationFilter,
           filterSecurityInterceptor" />
     <sec:filter-chain pattern="/**" filters="
           securityContextPersistenceFilterWithASCTrue,
           authenticationProcessingFilter,
           exceptionTranslationFilter,
           filterSecurityInterceptor" />
  </sec:filter-chain-map>
</bean>
]]>
      </programlisting> The namespace element <literal>filter-chain-map</literal> is used to set
                up the security filter chain(s) which are required within the application<footnote>
                <para>Note that you'll need to include the security namespace in your application
                    context XML file in order to use this syntax.</para>
                </footnote>. It maps a particular URL pattern to a chain of filters built up from
                the bean names specified in the <literal>filters</literal> element. Both regular
                expressions and Ant Paths are supported, and the most specific URIs appear first. At
                runtime the <classname>FilterChainProxy</classname> will locate the first URI
                pattern that matches the current web request and the list of filter beans specified
                by the <literal>filters</literal> attribute will be applied to that request. The
                filters will be invoked in the order they are defined, so you have complete control
                over the filter chain which is applied to a particular URL.</para>
            <para>You may have noticed we have declared two
                <classname>SecurityContextPersistenceFilter</classname>s in the filter chain
                (<literal>ASC</literal> is short for <literal>allowSessionCreation</literal>, a
                property of <classname>SecurityContextPersistenceFilter</classname>). As web
                services will never present a <literal>jsessionid</literal> on future requests,
                creating <literal>HttpSession</literal>s for such user agents would be wasteful. If
                you had a high-volume application which required maximum scalability, we recommend
                you use the approach shown above. For smaller applications, using a single
                <classname>SecurityContextPersistenceFilter</classname> (with its default
                <literal>allowSessionCreation</literal> as <literal>true</literal>) would likely be
                sufficient.</para>
            <para>In relation to lifecycle issues, the <classname>FilterChainProxy</classname> will
                always delegate <methodname>init(FilterConfig)</methodname> and
                <methodname>destroy()</methodname> methods through to the underlaying
                <interfacename>Filter</interfacename>s if such methods are called against
                <classname>FilterChainProxy</classname> itself. In this case,
                <classname>FilterChainProxy</classname> guarantees to only initialize and destroy
                each <literal>Filter</literal> bean once, no matter how many times it is declared in
                the filter chain(s). You control the overall choice as to whether these methods are
                called or not via the <literal>targetFilterLifecycle</literal> initialization
                parameter of <literal>DelegatingFilterProxy</literal>. By default this property is
                <literal>false</literal> and servlet container lifecycle invocations are not
                delegated through <literal>DelegatingFilterProxy</literal>.</para>
            <para> When we looked at how to set up web security using <link
                xlink:href="#namespace-auto-config">namespace configuration</link>, we used a
                <literal>DelegatingFilterProxy</literal> with the name
                <quote>springSecurityFilterChain</quote>. You should now be able to see that this is
                the name of the <classname>FilterChainProxy</classname> which is created by the
                namespace. </para>
            <section>
                <title>Bypassing the Filter Chain</title>
                <para> As with the namespace, you can use the attribute <literal>filters =
                    "none"</literal> as an alternative to supplying a filter bean list. This will
                    omit the request pattern from the security filter chain entirely. Note that
                    anything matching this path will then have no authentication or authorization
                    services applied and will be freely accessible. If you want to make use of the
                    contents of the <classname>SecurityContext</classname> contents during a
                    request, then it must have passed through the security filter chain. Otherwise
                    the <classname>SecurityContextHolder</classname> will not have been populated
                    and the contents will be null.</para>
            </section>
        </section>
        <section>
            <title>Filter Ordering</title>
            <para>The order that filters are defined in the chain is very important. Irrespective of
                which filters you are actually using, the order should be as follows: <orderedlist>
                <listitem>
                    <para><classname>ChannelProcessingFilter</classname>, because it might need to
                        redirect to a different protocol</para>
                </listitem>
                <listitem>
                    <para><classname>ConcurrentSessionFilter</classname>, because it doesn't use any
                        <classname>SecurityContextHolder</classname> functionality but needs to
                        update the <interfacename>SessionRegistry</interfacename> to reflect ongoing
                        requests from the principal</para>
                </listitem>
                <listitem>
                    <para><classname>SecurityContextPersistenceFilter</classname>, so a
                        <interfacename>SecurityContext</interfacename> can be set up in the
                        <classname>SecurityContextHolder</classname> at the beginning of a web
                        request, and any changes to the
                        <interfacename>SecurityContext</interfacename> can be copied to the
                        <literal>HttpSession</literal> when the web request ends (ready for use with
                        the next web request)</para>
                </listitem>
                <listitem>
                    <para>Authentication processing mechanisms -
                        <classname>UsernamePasswordAuthenticationFilter</classname>,
                        <classname>CasProcessingFilter</classname>,
                        <classname>BasicProcessingFilter</classname> etc - so that the
                        <classname>SecurityContextHolder</classname> can be modified to contain a
                        valid <interfacename>Authentication</interfacename> request token</para>
                </listitem>
                <listitem>
                    <para>The <literal>SecurityContextHolderAwareRequestFilter</literal>, if you are
                        using it to install a Spring Security aware
                        <literal>HttpServletRequestWrapper</literal> into your servlet
                        container</para>
                </listitem>
                <listitem>
                    <para><classname>RememberMeProcessingFilter</classname>, so that if no earlier
                        authentication processing mechanism updated the
                        <classname>SecurityContextHolder</classname>, and the request presents a
                        cookie that enables remember-me services to take place, a suitable
                        remembered <interfacename>Authentication</interfacename> object will be put
                        there</para>
                </listitem>
                <listitem>
                    <para><classname>AnonymousProcessingFilter</classname>, so that if no earlier
                        authentication processing mechanism updated the
                        <classname>SecurityContextHolder</classname>, an anonymous
                        <interfacename>Authentication</interfacename> object will be put
                        there</para>
                </listitem>
                <listitem>
                    <para><classname>ExceptionTranslationFilter</classname>, to catch any Spring
                        Security exceptions so that either an HTTP error response can be returned or
                        an appropriate <interfacename>AuthenticationEntryPoint</interfacename> can
                        be launched</para>
                </listitem>
                <listitem>
                    <para><classname>FilterSecurityInterceptor</classname>, to protect web URIs and
                        raise exceptions when access is denied</para>
                </listitem>
                </orderedlist></para>
        </section>
        <section>
            <title>Use with other Filter-Based Frameworks</title>
            <para>If you're using some other framework that is also filter-based, then you need to
                make sure that the Spring Security filters come first. This enables the
                <classname>SecurityContextHolder</classname> to be populated in time for use by the
                other filters. Examples are the use of SiteMesh to decorate your web pages or a web
                framework like Wicket which uses a filter to handle its requests. </para>
        </section>
    </section>
    <!--
  <section xml:id="taglib">
    <info>
      <title>Tag Libraries</title>
    </info>
    <para>Spring Security comes bundled with several JSP tag libraries which provide a range of
      different services.</para>
    <section xml:id="taglib-config">
      <info>
        <title>Configuration</title>
      </info>
      <para>All taglib classes are included in the core
          <literal>spring-security-taglibs-&lt;version>.jar</literal> file, with the
          <literal>security.tld</literal> located in the JAR's <literal>META-INF</literal>
        directory. This means for JSP 1.2+ web containers you can simply include the JAR in the
        WAR's <literal>WEB-INF/lib</literal> directory and it will be available.</para>
    </section>
    <section xml:id="taglib-usage">
      <info>
        <title>Usage</title>
      </info>
      <para>Now that you've configured the tag libraries, refer to the individual reference guide
        sections for details on how to use them. Note that when using the tags, you should include
        the taglib reference in your JSP:
        <programlisting>
  &lt;%@ taglib prefix='security' uri='http://www.springframework.org/security/tags' %&gt;
</programlisting></para>
    </section>
  </section>

<section xml:id="authentication-taglibs">
<info>
<title>Authentication Tag Libraries</title>
</info>
<para><literal>AuthenticationTag</literal> is used to simply output a property of the current
<interfacename>Authentication</interfacename> object to the web page.</para>
<para>The following JSP fragment illustrates how to use the
<literal>AuthenticationTag</literal>:</para>
<para>
<programlisting>&lt;security:authentication property="principal.username"/&gt;</programlisting>
</para>
<para>This tag would cause the principal's name to be output. Here we are assuming the
<literal>Authentication.getPrincipal()</literal> is a
<interfacename>UserDetails</interfacename> object, which is generally the case when using
one of Spring Security's stadard <classname>AuthenticationProvider</classname>
implementations.</para>
</section>



-->
</chapter>