Fixed section boundaries in core-filters doc
This commit is contained in:
Luke Taylor
parent
e7486fc203
commit
283aa1b34b
|
|
@ -2,13 +2,14 @@
|
|||
xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<title>Core Security Filters</title>
|
||||
<para> There are some key filters which will always be used in a web application which uses
|
||||
Spring Security, so we'll look at these and their supporting classes and interfaces them
|
||||
first. We won't cover every feature, so be sure to look at the Javadoc for them if you want
|
||||
to get the complete picture.</para>
|
||||
Spring Security, so we'll look at these and their supporting classes and interfaces first.
|
||||
We won't cover every feature, so be sure to look at the Javadoc for them if you want to get
|
||||
the complete picture.</para>
|
||||
<section xml:id="filter-security-interceptor">
|
||||
<title><classname>FilterSecurityInterceptor</classname></title>
|
||||
<para>We've already seen <classname>FilterSecurityInterceptor</classname> briefly when
|
||||
discussing <link xlink:href="#tech-intro-access-control">access-control in general</link>, and we've already used it with the namespace where the
|
||||
discussing <link xlink:href="#tech-intro-access-control">access-control in
|
||||
general</link>, and we've already used it with the namespace where the
|
||||
<literal><intercept-url></literal> elements are combined to configure it
|
||||
internally. Now we'll see how to explicitly configure it for use with a
|
||||
<classname>FilterChainProxy</classname>, along with its companion filter
|
||||
|
|
@ -30,7 +31,8 @@
|
|||
<interfacename>AuthenticationManager</interfacename> and an
|
||||
<interfacename>AccessDecisionManager</interfacename>. It is also supplied with
|
||||
configuration attributes that apply to different HTTP URL requests. Refer back to <link
|
||||
xlink:href="#tech-intro-config-attributes">the original discussion on these</link> in the technical introduction.</para>
|
||||
xlink:href="#tech-intro-config-attributes">the original discussion on these</link>
|
||||
in the technical introduction.</para>
|
||||
<para>The <classname>FilterSecurityInterceptor</classname> can be configured with
|
||||
configuration attributes in two ways. The first, which is shown above, is using the
|
||||
<literal><filter-security-metadata-source></literal> namespace element. This
|
||||
|
|
@ -155,159 +157,147 @@
|
|||
<classname>AccessDeniedHandlerImpl</classname> is used, which just sends a 403
|
||||
(Forbidden) response to the client. Alternatively you can configure an instance
|
||||
explicitly (as in the above example) and set an error page URL which it will
|
||||
forwards the request to <footnote>
|
||||
<para>We use a forward so that the SecurityContextHolder still contains details
|
||||
of the principal, which may be useful for displaying to the user. In old
|
||||
releases of Spring Security we relied upon the servlet container to handle a
|
||||
403 error message, which lacked this useful contextual information.</para>
|
||||
</footnote>. This can be a simple <quote>access denied</quote> page, such as a JSP,
|
||||
or it could be a more complex handler such as an MVC controller. And of course, you
|
||||
can implement the interface yourself and use your own implementation. </para>
|
||||
forwards the request to <footnote><para>We use a forward so that the
|
||||
SecurityContextHolder still contains details of the principal, which may be
|
||||
useful for displaying to the user. In old releases of Spring Security we
|
||||
relied upon the servlet container to handle a 403 error message, which
|
||||
lacked this useful contextual information.</para></footnote>. This can be a
|
||||
simple <quote>access denied</quote> page, such as a JSP, or it could be a more
|
||||
complex handler such as an MVC controller. And of course, you can implement the
|
||||
interface yourself and use your own implementation. </para>
|
||||
<para>It's also possible to supply a custom
|
||||
<interfacename>AccessDeniedHandler</interfacename> when you're using the
|
||||
namespace to configure your application. See
|
||||
<link xlink:href="#nsa-access-denied-handler">the namespace appendix</link> for more details.</para>
|
||||
namespace to configure your application. See <link
|
||||
xlink:href="#nsa-access-denied-handler">the namespace appendix</link> for more
|
||||
details.</para>
|
||||
</section>
|
||||
<section xml:id="security-context-persistence-filter">
|
||||
<title><classname>SecurityContextPersistenceFilter</classname></title>
|
||||
<para> We covered the purpose of this all-important filter in <link
|
||||
xlink:href="#tech-intro-sec-context-persistence"/> so you might want to re-read
|
||||
that section at this point. Let's first take a look at how you would configure it
|
||||
for use with a <classname>FilterChainProxy</classname>. A basic configuration only
|
||||
requires the bean itself <programlisting><![CDATA[
|
||||
</section>
|
||||
<section xml:id="security-context-persistence-filter">
|
||||
<title><classname>SecurityContextPersistenceFilter</classname></title>
|
||||
<para> We covered the purpose of this all-important filter in <link
|
||||
xlink:href="#tech-intro-sec-context-persistence"/> so you might want to re-read that
|
||||
section at this point. Let's first take a look at how you would configure it for use
|
||||
with a <classname>FilterChainProxy</classname>. A basic configuration only requires the
|
||||
bean itself <programlisting><![CDATA[
|
||||
<bean id="securityContextPersistenceFilter"
|
||||
class="org.springframework.security.web.context.SecurityContextPersistenceFilter"/>
|
||||
]]></programlisting> As we saw previously, this filter has two main tasks. It is responsible for
|
||||
storage of the <classname>SecurityContext</classname> contents between HTTP requests
|
||||
and for clearing the <classname>SecurityContextHolder</classname> when a request is
|
||||
completed. Clearing the <classname>ThreadLocal</classname> in which the context is
|
||||
stored is essential, as it might otherwise be possible for a thread to be replaced
|
||||
into the servlet container's thread pool, with the security context for a particular
|
||||
user still attached. This thread might then be used at a later stage, performing
|
||||
operations with the wrong credentials. </para>
|
||||
<section xml:id="security-context-repository">
|
||||
<title><interfacename>SecurityContextRepository</interfacename></title>
|
||||
<para>From Spring Security 3.0, the job of loading and storing the security context
|
||||
is now delegated to a separate strategy interface:
|
||||
<programlisting language="java">
|
||||
class="org.springframework.security.web.context.SecurityContextPersistenceFilter"/>
|
||||
]]></programlisting> As we saw previously, this filter has two main tasks. It is responsible for
|
||||
storage of the <classname>SecurityContext</classname> contents between HTTP requests and
|
||||
for clearing the <classname>SecurityContextHolder</classname> when a request is
|
||||
completed. Clearing the <classname>ThreadLocal</classname> in which the context is
|
||||
stored is essential, as it might otherwise be possible for a thread to be replaced into
|
||||
the servlet container's thread pool, with the security context for a particular user
|
||||
still attached. This thread might then be used at a later stage, performing operations
|
||||
with the wrong credentials. </para>
|
||||
<section xml:id="security-context-repository">
|
||||
<title><interfacename>SecurityContextRepository</interfacename></title>
|
||||
<para>From Spring Security 3.0, the job of loading and storing the security context is
|
||||
now delegated to a separate strategy interface:
|
||||
<programlisting language="java">
|
||||
public interface SecurityContextRepository {
|
||||
SecurityContext loadContext(HttpRequestResponseHolder requestResponseHolder);
|
||||
void saveContext(SecurityContext context, HttpServletRequest request, HttpServletResponse response);
|
||||
SecurityContext loadContext(HttpRequestResponseHolder requestResponseHolder);
|
||||
void saveContext(SecurityContext context, HttpServletRequest request, HttpServletResponse response);
|
||||
}
|
||||
</programlisting>
|
||||
The <classname>HttpRequestResponseHolder</classname> is simply a container for
|
||||
the incoming request and response objects, allowing the implementation to
|
||||
replace these with wrapper classes. The returned contents will be passed to the
|
||||
filter chain. </para>
|
||||
<para> The default implementation is
|
||||
<classname>HttpSessionSecurityContextRepository</classname>, which stores
|
||||
the security context as an <interfacename>HttpSession</interfacename> attribute <footnote>
|
||||
<para>In Spring Security 2.0 and earlier, this filter was called
|
||||
<classname>HttpSessionContextIntegrationFilter</classname> and
|
||||
performed all the work of storing the context was performed by the
|
||||
filter itself. If you were familiar with this class, then most of the
|
||||
configuration options which were available can now be found on
|
||||
<classname>HttpSessionSecurityContextRepository</classname>. </para>
|
||||
</footnote>. The most important configuration parameter for this implementation
|
||||
is the <literal>allowSessionCreation</literal> property, which defaults to
|
||||
<literal>true</literal>, thus allowing the class to create a session if it
|
||||
needs one to store the security context for an authenticated user (it won't
|
||||
create one unless authentication has taken place and the contents of the
|
||||
security context have changed). If you don't want a session to be created, then
|
||||
you can set this property to <literal>false</literal>: <programlisting language="xml"><![CDATA[
|
||||
The <classname>HttpRequestResponseHolder</classname> is simply a container for the
|
||||
incoming request and response objects, allowing the implementation to replace these
|
||||
with wrapper classes. The returned contents will be passed to the filter chain. </para>
|
||||
<para> The default implementation is
|
||||
<classname>HttpSessionSecurityContextRepository</classname>, which stores the
|
||||
security context as an <interfacename>HttpSession</interfacename> attribute
|
||||
<footnote><para>In Spring Security 2.0 and earlier, this filter was called
|
||||
<classname>HttpSessionContextIntegrationFilter</classname> and performed
|
||||
all the work of storing the context was performed by the filter itself. If
|
||||
you were familiar with this class, then most of the configuration options
|
||||
which were available can now be found on
|
||||
<classname>HttpSessionSecurityContextRepository</classname>.
|
||||
</para></footnote>. The most important configuration parameter for this
|
||||
implementation is the <literal>allowSessionCreation</literal> property, which
|
||||
defaults to <literal>true</literal>, thus allowing the class to create a session if
|
||||
it needs one to store the security context for an authenticated user (it won't
|
||||
create one unless authentication has taken place and the contents of the security
|
||||
context have changed). If you don't want a session to be created, then you can set
|
||||
this property to <literal>false</literal>: <programlisting language="xml"><![CDATA[
|
||||
<bean id="securityContextPersistenceFilter"
|
||||
class="org.springframework.security.web.context.SecurityContextPersistenceFilter">
|
||||
<property name='securityContextRepository'>
|
||||
<bean class='org.springframework.security.web.context.HttpSessionSecurityContextRepository'>
|
||||
<property name='allowSessionCreation' value='false' />
|
||||
</bean>
|
||||
</property>
|
||||
class="org.springframework.security.web.context.SecurityContextPersistenceFilter">
|
||||
<property name='securityContextRepository'>
|
||||
<bean class='org.springframework.security.web.context.HttpSessionSecurityContextRepository'>
|
||||
<property name='allowSessionCreation' value='false' />
|
||||
</bean>
|
||||
]]></programlisting> Alternatively you could provide a null implementation of the
|
||||
<interfacename>SecurityContextRepository</interfacename> interface. </para>
|
||||
</section>
|
||||
</property>
|
||||
</bean>
|
||||
]]></programlisting> Alternatively you could provide a null implementation of the
|
||||
<interfacename>SecurityContextRepository</interfacename> interface. </para>
|
||||
</section>
|
||||
<section xml:id="form-login-filter">
|
||||
<title><classname>UsernamePasswordAuthenticationProcessingFilter</classname></title>
|
||||
<para>We've now seen the three main filters which are always present in a Spring
|
||||
Security web configuration. These are also the three which are automatically created
|
||||
by the namespace <literal><http></literal> element and cannot be substituted
|
||||
with alternatives. The only thing that's missing now is an actual authentication
|
||||
mechanism, something that will allow a user to authenticate. This filter is the most
|
||||
commonly used authentication filter and the one that is most often customized <footnote>
|
||||
<para>For historical reasons, prior to Spring Security 3.0, this filter was
|
||||
called <classname>AuthenticationProcessingFilter</classname> and the entry
|
||||
point was called
|
||||
<classname>AuthenticationProcessingFilterEntryPoint</classname>. Since
|
||||
the framework now supports many different forms of authentication, they have
|
||||
both been given more specific names in 3.0.</para>
|
||||
</footnote>. It also provides the implementation used by the <form-login>
|
||||
element from the namespace. There are three stages required to configure it. <orderedlist>
|
||||
<listitem>
|
||||
<para>Configure a <classname>LoginUrlAuthenticationEntryPoint</classname>
|
||||
with the URL of the login page, just as we did above, and set it on the
|
||||
<classname>ExceptionTranslationFilter</classname>. </para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Implement the login page (using a JSP or MVC controller).</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Configure an instance of
|
||||
<classname>UsernamePasswordAuthenticationProcessingFilter</classname>
|
||||
in the application context</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Add the filter bean to your filter chain proxy (making sure you pay
|
||||
attention to the order). <!-- TODO: link --></para>
|
||||
</listitem>
|
||||
</orderedlist> The login form simply contains <literal>j_username</literal> and
|
||||
<literal>j_password</literal> input fields, and posts to the URL that is
|
||||
monitored by the filter (by default this is
|
||||
<literal>/j_spring_security_check</literal>). The basic filter configuration
|
||||
looks something like this: <programlisting><![CDATA[
|
||||
</section>
|
||||
<section xml:id="form-login-filter">
|
||||
<title><classname>UsernamePasswordAuthenticationProcessingFilter</classname></title>
|
||||
<para>We've now seen the three main filters which are always present in a Spring Security
|
||||
web configuration. These are also the three which are automatically created by the
|
||||
namespace <literal><http></literal> element and cannot be substituted with
|
||||
alternatives. The only thing that's missing now is an actual authentication mechanism,
|
||||
something that will allow a user to authenticate. This filter is the most commonly used
|
||||
authentication filter and the one that is most often customized <footnote><para>For
|
||||
historical reasons, prior to Spring Security 3.0, this filter was called
|
||||
<classname>AuthenticationProcessingFilter</classname> and the entry point
|
||||
was called <classname>AuthenticationProcessingFilterEntryPoint</classname>.
|
||||
Since the framework now supports many different forms of authentication, they
|
||||
have both been given more specific names in 3.0.</para></footnote>. It also
|
||||
provides the implementation used by the <form-login> element from the namespace.
|
||||
There are three stages required to configure it. <orderedlist><listitem><para>Configure
|
||||
a <classname>LoginUrlAuthenticationEntryPoint</classname> with the URL of
|
||||
the login page, just as we did above, and set it on the
|
||||
<classname>ExceptionTranslationFilter</classname>.
|
||||
</para></listitem><listitem><para>Implement the login page (using a JSP or
|
||||
MVC controller).</para></listitem><listitem><para>Configure an instance of
|
||||
<classname>UsernamePasswordAuthenticationProcessingFilter</classname> in
|
||||
the application context</para></listitem><listitem><para>Add the filter bean
|
||||
to your filter chain proxy (making sure you pay attention to the order).
|
||||
<!-- TODO: link --></para></listitem></orderedlist> The login form simply
|
||||
contains <literal>j_username</literal> and <literal>j_password</literal> input fields,
|
||||
and posts to the URL that is monitored by the filter (by default this is
|
||||
<literal>/j_spring_security_check</literal>). The basic filter configuration looks
|
||||
something like this: <programlisting><![CDATA[
|
||||
<bean id="authenticationProcessingFilter" class=
|
||||
"org.springframework.security.web.authentication.UsernamePasswordAuthenticationProcessingFilter">
|
||||
<property name="authenticationManager" ref="authenticationManager"/>
|
||||
<property name="filterProcessesUrl" value="/j_spring_security_check"/>
|
||||
</bean> ]]>
|
||||
</programlisting></para>
|
||||
<section xml:id="form-login-flow-handling">
|
||||
<title>Application Flow on Authentication Success and Failure</title>
|
||||
<para> The filter calls the configured
|
||||
<interfacename>AuthenticationManager</interfacename> to process each
|
||||
authentication request. The destination following a successful authentication or
|
||||
an authentication failure is controlled by the
|
||||
<interfacename>AuthenticationSuccessHandler</interfacename> and
|
||||
<interfacename>AuthenticationFailureHandler</interfacename> strategy
|
||||
interfaces, respectively. The filter has properties which allow you to set these
|
||||
so you can customize the behaviour completely <footnote>
|
||||
<para>In versions prior to 3.0, the application flow at this point had
|
||||
evolved to a stage was controlled by a mix of properties on this class
|
||||
and strategy plugins. The decision was made for 3.0 to refactor the code
|
||||
to make these two strategies entirely responsible. </para>
|
||||
</footnote>. Some standard implementations are supplied such as
|
||||
<classname>SimpleUrlAuthenticationSuccessHandler</classname>,
|
||||
<classname>SavedRequestAwareAuthenticationSuccessHandler</classname>,
|
||||
<classname>SimpleUrlAuthenticationFailureHandler</classname> and
|
||||
<classname>ExceptionMappingAuthenticationFailureHandler</classname>. Have a
|
||||
look at the Javadoc for these classes to see how they work. </para>
|
||||
<para>If authentication is successful, the resulting
|
||||
<interfacename>Authentication</interfacename> object will be placed into the
|
||||
<classname>SecurityContextHolder</classname>. The configured
|
||||
AuthenticationSuccessHandler will then be called to either redirect or forward
|
||||
the user to the approprate destination. By default a
|
||||
<classname>SavedRequestAwareAuthenticationSuccessHandler</classname> is
|
||||
used, which means that the user will be redirected to the original destination
|
||||
they requested before they were asked to login. <note>
|
||||
<para> The <classname>ExceptionTranslationFilter</classname> caches the
|
||||
original request a user makes. When the user authenticates, the request
|
||||
handler makes use of this cached request to obtain the original URL and
|
||||
redirect to it. The original request is then rebuilt and used as an
|
||||
alternative. </para>
|
||||
</note> If authentication fails, the configured
|
||||
<interfacename>AuthenticationFailureHandler</interfacename> will be invoked.
|
||||
</para>
|
||||
</section>
|
||||
</programlisting></para>
|
||||
<section xml:id="form-login-flow-handling">
|
||||
<title>Application Flow on Authentication Success and Failure</title>
|
||||
<para> The filter calls the configured
|
||||
<interfacename>AuthenticationManager</interfacename> to process each
|
||||
authentication request. The destination following a successful authentication or an
|
||||
authentication failure is controlled by the
|
||||
<interfacename>AuthenticationSuccessHandler</interfacename> and
|
||||
<interfacename>AuthenticationFailureHandler</interfacename> strategy interfaces,
|
||||
respectively. The filter has properties which allow you to set these so you can
|
||||
customize the behaviour completely <footnote><para>In versions prior to 3.0, the
|
||||
application flow at this point had evolved to a stage was controlled by a
|
||||
mix of properties on this class and strategy plugins. The decision was made
|
||||
for 3.0 to refactor the code to make these two strategies entirely
|
||||
responsible. </para></footnote>. Some standard implementations are supplied
|
||||
such as <classname>SimpleUrlAuthenticationSuccessHandler</classname>,
|
||||
<classname>SavedRequestAwareAuthenticationSuccessHandler</classname>,
|
||||
<classname>SimpleUrlAuthenticationFailureHandler</classname> and
|
||||
<classname>ExceptionMappingAuthenticationFailureHandler</classname>. Have a look
|
||||
at the Javadoc for these classes to see how they work. </para>
|
||||
<para>If authentication is successful, the resulting
|
||||
<interfacename>Authentication</interfacename> object will be placed into the
|
||||
<classname>SecurityContextHolder</classname>. The configured
|
||||
AuthenticationSuccessHandler will then be called to either redirect or forward the
|
||||
user to the approprate destination. By default a
|
||||
<classname>SavedRequestAwareAuthenticationSuccessHandler</classname> is used,
|
||||
which means that the user will be redirected to the original destination they
|
||||
requested before they were asked to login. <note><para> The
|
||||
<classname>ExceptionTranslationFilter</classname> caches the original
|
||||
request a user makes. When the user authenticates, the request handler makes
|
||||
use of this cached request to obtain the original URL and redirect to it.
|
||||
The original request is then rebuilt and used as an alternative.
|
||||
</para></note> If authentication fails, the configured
|
||||
<interfacename>AuthenticationFailureHandler</interfacename> will be invoked.
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
</chapter>
|
||||
|
|
|
|||
Loading…
Reference in New Issue