SEC-1171: Documentation of changes related to use of multiple <http> elements.
This commit is contained in:
Luke Taylor
parent
6a37e4be86
commit
0d94e75a93
|
|
@ -19,14 +19,15 @@
|
|||
>schema file</link> directly.</para>
|
||||
<section xml:id="nsa-http">
|
||||
<title>Web Application Security - the <literal><http></literal> Element</title>
|
||||
<para> The <literal><http></literal> element encapsulates the security configuration
|
||||
for the web layer of your application. It creates a
|
||||
<classname>FilterChainProxy</classname> bean named "springSecurityFilterChain" which
|
||||
maintains the stack of security filters which make up the web security configuration <footnote>
|
||||
<para> If you use an <literal><http></literal> element within your application,
|
||||
a <classname>FilterChainProxy</classname> bean named "springSecurityFilterChain" is created and
|
||||
the configuration within the element is used to build a filter chain within
|
||||
<classname>FilterChainProxy</classname>. As of Spring Security 3.1, additional
|
||||
<literal>http</literal> elements can be used to add extra filter chains <footnote>
|
||||
<para>See the <link xlink:href="#ns-web-xml"> introductory chapter</link> for how to
|
||||
set up the mapping from your <literal>web.xml</literal></para>
|
||||
</footnote>. Some core filters are always created and others will be added to the stack
|
||||
depending on the attributes child elements which are present. The positions of the
|
||||
</footnote>. Some core filters are always created in a filter chain and others will be added
|
||||
to the stack depending on the attributes and child elements which are present. The positions of the
|
||||
standard filters are fixed (see <link xlink:href="#filter-stack">the filter order
|
||||
table</link> in the namespace introduction), removing a common source of errors with
|
||||
previous versions of the framework when users had to configure the filter chain
|
||||
|
|
@ -37,22 +38,38 @@
|
|||
with the internal instance created by the namespace configuration (see the <link
|
||||
xlink:href="#ns-auth-manager"> introductory chapter</link> for more on the
|
||||
<interfacename>AuthenticationManager</interfacename>). </para>
|
||||
<para> The <literal><http></literal> namespace block always creates an
|
||||
<classname>HttpSessionContextIntegrationFilter</classname>, an
|
||||
<para> Each <literal><http></literal> namespace block always creates an
|
||||
<classname>SecurityContextPersistenceFilter</classname>, an
|
||||
<classname>ExceptionTranslationFilter</classname> and a
|
||||
<classname>FilterSecurityInterceptor</classname>. These are fixed and cannot be
|
||||
replaced with alternatives. </para>
|
||||
<section xml:id="nsa-http-attributes">
|
||||
<title><literal><http></literal> Attributes</title>
|
||||
<para> The attributes on the <literal><http></literal> element control some of the
|
||||
properties on the core filters. </para>
|
||||
properties on the core filters. </para>
|
||||
<section xml:id="nsa-http-pattern">
|
||||
<title><literal>pattern</literal></title>
|
||||
<para>Defining a pattern for the <literal>http</literal> element controls
|
||||
the requests which will be filtered through the list of filters which it defines. The
|
||||
interpretation is dependent on the configured <link xlink:href="#nsa-path-type">request-matcher</link>.
|
||||
If no pattern is defined, all requests will be matched, so the most specific patterns should be
|
||||
declared first.
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="nsa-http-secured">
|
||||
<title><literal>secured</literal></title>
|
||||
<para>A request pattern can be mapped to an empty filter chain, by setting
|
||||
this attribute to <literal>false</literal>. No security will be applied and
|
||||
none of Spring Security's features will be available.
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="nsa-servlet-api-provision">
|
||||
<title><literal>servlet-api-provision</literal></title>
|
||||
<para> Provides versions of <literal>HttpServletRequest</literal> security methods
|
||||
such as <literal>isUserInRole()</literal> and <literal>getPrincipal()</literal>
|
||||
which are implemented by adding a
|
||||
<classname>SecurityContextHolderAwareRequestFilter</classname> bean to the
|
||||
stack. Defaults to "true". </para>
|
||||
stack. Defaults to "true".</para>
|
||||
</section>
|
||||
<section xml:id="nsa-path-type">
|
||||
<title><literal>request-matcher</literal></title>
|
||||
|
|
@ -142,9 +159,7 @@
|
|||
<para> This element is used to define the set of URL patterns that the application is
|
||||
interested in and to configure how they should be handled. It is used to construct
|
||||
the <interfacename>FilterInvocationSecurityMetadataSource</interfacename> used by
|
||||
the <classname>FilterSecurityInterceptor</classname> and to exclude particular
|
||||
patterns from the filter chain entirely (by setting the attribute
|
||||
<literal>filters="none"</literal>). It is also responsible for configuring a
|
||||
the <classname>FilterSecurityInterceptor</classname>. It is also responsible for configuring a
|
||||
<classname>ChannelAuthenticationFilter</classname> if particular URLs need to be
|
||||
accessed by HTTPS, for example. When matching the specified patterns against an
|
||||
incoming request, the matching is done in the order in which the elements are
|
||||
|
|
|
|||
|
|
@ -241,8 +241,10 @@
|
|||
default <literal><http></literal> configuration, so the
|
||||
<literal><anonymous /></literal> element is added regardless of
|
||||
whether <literal>auto-config</literal> is enabled.</para>
|
||||
</footnote> . They each have attributes which can be used to alter their
|
||||
behaviour. </para>
|
||||
</footnote>. They each have attributes which can be used to alter their
|
||||
behaviour. In anything other than very basic scenarios, it is probably better
|
||||
to omit the <literal>auto-config</literal> attribute and configure what you require
|
||||
explicitly in the interest of clarity.</para>
|
||||
</section>
|
||||
</section>
|
||||
<section xml:id="ns-form-and-basic">
|
||||
|
|
@ -275,16 +277,33 @@
|
|||
itself! This is a common configuration error and will result in an infinite loop in
|
||||
the application. Spring Security will emit a warning in the log if your login page
|
||||
appears to be secured. It is also possible to have all requests matching a
|
||||
particular pattern bypass the security filter chain completely: <programlisting language="xml"><![CDATA[
|
||||
particular pattern bypass the security filter chain completely, by defining a separate
|
||||
<literal>http</literal> element for the pattern like this: <programlisting language="xml"><![CDATA[
|
||||
<http pattern="/css/**" secured="false"/>
|
||||
<http pattern="/login.jsp*" secured="false"/>
|
||||
|
||||
<http auto-config='true'>
|
||||
<intercept-url pattern="/css/**" filters="none"/>
|
||||
<intercept-url pattern="/login.jsp*" filters="none"/>
|
||||
<intercept-url pattern="/**" access="ROLE_USER" />
|
||||
<form-login login-page='/login.jsp'/>
|
||||
</http>
|
||||
]]>
|
||||
</programlisting>It's important to realise that these requests will be completely
|
||||
oblivious to any further Spring Security web-related configuration or additional
|
||||
</programlisting>
|
||||
From Spring Security 3.1 it is now possible to use multiple <literal>http</literal>
|
||||
elements to define separate security filter chain configurations for different
|
||||
request patterns. If the <literal>pattern</literal> attribute is omitted from an
|
||||
<literal>http</literal> element, it matches all requests. Creating an unsecured
|
||||
pattern is a simple example of this syntax, where the pattern is mapped to an empty filter chain
|
||||
<footnote><para>The use of multiple <literal><http></literal> elements is an
|
||||
important feature, allowing the namespace to simultaneously support both stateful and stateless
|
||||
paths within the same application, for example. The previous syntax, using the attribute
|
||||
<literal>filters="none"</literal> on an <literal>intercept-url</literal> element
|
||||
is incompatible with this change and is no longer supported in 3.1.</para></footnote>.
|
||||
We'll look at this new syntax in more detail in the chapter on the
|
||||
<link xlink:href="#filter-chains-with-ns">Security Filter Chain</link>.
|
||||
</para>
|
||||
<para>
|
||||
It's important to realise that these unsecured requests will be completely
|
||||
oblivious to any Spring Security web-related configuration or additional
|
||||
attributes such as <literal>requires-channel</literal>, so you will not be able to
|
||||
access information on the current user or call secured methods during the request.
|
||||
Use <literal>access='IS_AUTHENTICATED_ANONYMOUSLY'</literal> as an alternative if
|
||||
|
|
@ -311,8 +330,8 @@
|
|||
<literal>always-use-default-target</literal> attribute to "true". This is
|
||||
useful if your application always requires that the user starts at a "home"
|
||||
page, for example: <programlisting language="xml"><![CDATA[
|
||||
<http pattern="/login.htm*" secured="false"/>
|
||||
<http>
|
||||
<intercept-url pattern='/login.htm*' filters='none'/>
|
||||
<intercept-url pattern='/**' access='ROLE_USER' />
|
||||
<form-login login-page='/login.htm' default-target-url='/home.htm'
|
||||
always-use-default-target='true' />
|
||||
|
|
@ -573,7 +592,7 @@
|
|||
are returned as part of the authentication process and can be accessed
|
||||
afterwards using the following code:
|
||||
<programlisting language="java">
|
||||
OpenIDAuthenticationToken token =
|
||||
OpenIDAuthenticationToken token =
|
||||
(OpenIDAuthenticationToken)SecurityContextHolder.getContext().getAuthentication();
|
||||
List<OpenIDAttribute> attributes = token.getAttributes();</programlisting>The
|
||||
<classname>OpenIDAttribute</classname> contains the attribute type and the
|
||||
|
|
|
|||
|
|
@ -62,7 +62,7 @@
|
|||
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="
|
||||
<sec:filter-chain pattern="/restful/**" filters="
|
||||
securityContextPersistenceFilterWithASCFalse,
|
||||
basicAuthenticationFilter,
|
||||
exceptionTranslationFilter,
|
||||
|
|
@ -75,8 +75,8 @@
|
|||
</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>
|
||||
</programlisting> The namespace element <literal>filter-chain-map</literal> is used for convenience
|
||||
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
|
||||
|
|
@ -105,7 +105,7 @@
|
|||
namespace. </para>
|
||||
<section>
|
||||
<title>Bypassing the Filter Chain</title>
|
||||
<para> As with the namespace, you can use the attribute <literal>filters =
|
||||
<para> 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
|
||||
|
|
@ -184,6 +184,36 @@
|
|||
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 xml:id="filter-chains-with-ns">
|
||||
<title>Advanced Namespace Configuration</title>
|
||||
<para>As we saw earlier in the namespace chapter, it's possible to use multiple <literal>http</literal>
|
||||
elements to define different security configurations for different URL patterns.
|
||||
Each element creates a filter chain within the internal <classname>FilterChainProxy</classname> and the
|
||||
URL pattern that should be mapped to it. The elements will be added in the order they are declared, so the
|
||||
most specific patterns must again be declared first. Here's another example, for a similar situation to
|
||||
that above, where the application supports both a stateless RESTful API and also a normal web application
|
||||
which users log into using a form.
|
||||
<programlisting>
|
||||
<![CDATA[
|
||||
<!-- Stateless RESTful service using Basic authentication -->
|
||||
<http pattern="/restful/**" create-session="stateless">
|
||||
<intercept-url pattern='/**' access='ROLE_REMOTE' />
|
||||
<http-basic />
|
||||
</http>
|
||||
|
||||
<!-- Empty filter chain for the login page -->
|
||||
<http pattern="/login.htm*" secured="false"/>
|
||||
|
||||
<!-- Additional filter chain for normal users, matching all other requests -->
|
||||
<http>
|
||||
<intercept-url pattern='/**' access='ROLE_USER' />
|
||||
<form-login login-page='/login.htm' default-target-url="/home.htm"/>
|
||||
<logout />
|
||||
</http>
|
||||
]]>
|
||||
</programlisting>
|
||||
</para>
|
||||
</section>
|
||||
<!--
|
||||
<section xml:id="taglib">
|
||||
<info>
|
||||
|
|
|
|||
Loading…
Reference in New Issue