|
|
@@ -40,29 +40,32 @@
|
|
|
<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[
|
|
|
+ <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>Spring Security's web infrastructure should only be used by delegating to an
|
|
|
+ instance of <classname>FilterChainProxy</classname>. The security filters should not
|
|
|
+ be used by themselves In theory you could 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, but this would be
|
|
|
+ cumbersome and would clutter up the <filename>web.xml</filename> file quickly if you
|
|
|
+ have a lot of filters. <classname>FilterChainProxy</classname> lets us add a single
|
|
|
+ entry to <filename>web.xml</filename> and deal entirely with the application context
|
|
|
+ file for managing our web security beans. 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="
|
|
|
@@ -78,56 +81,175 @@
|
|
|
</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>
|
|
|
+ </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 URLs appear first. At
|
|
|
+ runtime the <classname>FilterChainProxy</classname> will locate the first URL
|
|
|
+ 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>Note that <classname>FilterChainProxy</classname> does not invoke standard filter
|
|
|
+ lifecycle methods on the filters it is configured with. We recommend you use
|
|
|
+ Spring's application context lifecycle interfaces as an alternative, just as you
|
|
|
+ would for any other Spring bean.</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 xml:id="request-matching">
|
|
|
+ <title>Request Matching</title>
|
|
|
+ <para>Spring Security has several areas where patterns you have defined are tested
|
|
|
+ against incoming requests in order to decide how the request should be handled. This
|
|
|
+ occurs when the <classname>FilterChainProxy</classname> decides which filter chain a
|
|
|
+ request should be passed through and also when the
|
|
|
+ <classname>FilterSecurityInterceptor</classname> decides which security constraints
|
|
|
+ apply to a request. It's important to understand what the mechanism is and what URL
|
|
|
+ value is used when testing against the patterns that you define.</para>
|
|
|
+ <para>The Servlet Specification defines several properties for the
|
|
|
+ <interfacename>HttpServletRequest</interfacename> which are accessible via getter
|
|
|
+ methods, and which we might want to match against. These are the
|
|
|
+ <literal>contextPath</literal>, <literal>servletPath</literal>,
|
|
|
+ <literal>pathInfo</literal> and <literal>queryString</literal>. Spring Security is
|
|
|
+ only interested in securing paths within the application, so the
|
|
|
+ <literal>contextPath</literal> is ignored. Each path segment of a URL may contain
|
|
|
+ parameters, as defined in <link xlink:href="http://www.ietf.org/rfc/rfc2396.txt">RFC
|
|
|
+ 2396</link><footnote>
|
|
|
+ <para>You have probably seen this when a browser doesn't support cookies and the
|
|
|
+ <literal>jsessionid</literal> parameter is appended to the URL after a
|
|
|
+ semi-colon. However the RFC allows the presence of these parameters in any path
|
|
|
+ segment of the URL</para>
|
|
|
+ </footnote>. The Specification does not clearly state whether these should be
|
|
|
+ included in the <literal>servletPath</literal> and <literal>pathInfo</literal> value
|
|
|
+ and the behaviour varies between different servlet containers. There is a danger
|
|
|
+ that when an application is deployed in a container which does not strip path
|
|
|
+ parameters from these values, an attacker could add them to the requested URL in
|
|
|
+ order to cause a pattern match to succeed or fail unexpectedly. Spring Security's
|
|
|
+ <classname>FilterChainProxy</classname> therefore wraps incoming requests to
|
|
|
+ consistently return <literal>servletPath</literal> and <literal>pathInfo</literal>
|
|
|
+ values which do not contain path parameters. For example, an original request path
|
|
|
+ <literal>/secure;hack=1/somefile.html;hack=2</literal> will be returned as
|
|
|
+ <literal>/secure/somefile.html</literal>. It is therefore essential that a
|
|
|
+ <classname>FilterChainProxy</classname> is used to manage the security filter
|
|
|
+ chain.</para>
|
|
|
+ <para>As mentioned above, the default strategy is to use Ant-style paths for matching
|
|
|
+ and this is likely to be the best choice for most users. Matching is performed
|
|
|
+ a pattern against the concatenated <literal>servletPath</literal> and
|
|
|
+ <literal>pathInfo</literal>, ignoring the <literal>queryString</literal>, and is case insensitive by default.</para>
|
|
|
+ <para>In practice we recommend that you use method security at your service layer, to
|
|
|
+ control access to your application, and do not rely entirely on the use of security
|
|
|
+ constraints defined at the web-application level. URLs change and it is difficult to
|
|
|
+ take account of all the possible URLs that an application might support and how
|
|
|
+ requests might be manipulated. You should try and restrict yourself to using a few
|
|
|
+ simple ant paths which are simple to understand. Always try to use a
|
|
|
+ <quote>deny-by-default</quote> approach where you have a catch-all wildcard
|
|
|
+ (<literal>/**</literal>) defined last and denying access.</para>
|
|
|
+ <para>Security defined at the service layer is much more robust and harder to bypass, so
|
|
|
+ you should always take advantage of Spring Security's method security
|
|
|
+ options.</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>
|
|
|
<title>Filter Ordering</title>
|
Luke Taylor