|
|
@@ -86,7 +86,7 @@
|
|
|
<literal>/secure/</literal> pattern. If they were reversed, the
|
|
|
<literal>/secure/</literal> pattern would always match and the
|
|
|
<literal>/secure/super/</literal> pattern would never be evaluated.</para>
|
|
|
-<!--
|
|
|
+ <!--
|
|
|
TODO: Put in FAQ instead. Or drop.
|
|
|
<para>As with other security interceptors, the <literal>validateConfigAttributes</literal>
|
|
|
property is observed. When set to <literal>true</literal> (the default), at startup time
|
|
|
@@ -96,16 +96,15 @@
|
|
|
<interfacename>AccessDecisionManager</interfacename> or the
|
|
|
<literal>RunAsManager</literal>. If neither of these can process a particular
|
|
|
configuration attribute, an exception is thrown.</para>
|
|
|
--->
|
|
|
+-->
|
|
|
</section>
|
|
|
<section xml:id="exception-translation-filter">
|
|
|
<title>
|
|
|
<classname>ExceptionTranslationFilter</classname></title>
|
|
|
- <para>The <classname>ExceptionTranslationFilter</classname> sits above the <classname>FilterSecurityInterceptor</classname>
|
|
|
- in the security filter stack. It doesn't do any actual security enforcement itself,
|
|
|
- but handles exceptions thrown by the security interceptors and provides suitable
|
|
|
- and HTTP responses.
|
|
|
- <programlisting language="xml"><![CDATA[
|
|
|
+ <para>The <classname>ExceptionTranslationFilter</classname> sits above the
|
|
|
+ <classname>FilterSecurityInterceptor</classname> in the security filter stack. It
|
|
|
+ doesn't do any actual security enforcement itself, but handles exceptions thrown by the
|
|
|
+ security interceptors and provides suitable and HTTP responses. <programlisting language="xml"><![CDATA[
|
|
|
<bean id="exceptionTranslationFilter"
|
|
|
class="org.springframework.security.web.access.ExceptionTranslationFilter">
|
|
|
<property name="authenticationEntryPoint" ref="authenticationEntryPoint"/>
|
|
|
@@ -121,22 +120,20 @@
|
|
|
class="org.springframework.security.web.access.AccessDeniedHandlerImpl">
|
|
|
<property name="errorPage" value="/accessDenied.htm"/>
|
|
|
</bean>
|
|
|
-]]></programlisting>
|
|
|
- </para>
|
|
|
+]]></programlisting></para>
|
|
|
<section xml:id="auth-entry-point">
|
|
|
<title><interfacename>AuthenticationEntryPoint</interfacename></title>
|
|
|
- <para>
|
|
|
- The <interfacename>AuthenticationEntryPoint</interfacename> will be
|
|
|
- called if the user requests a secure HTTP resource but they are not authenticated. An
|
|
|
- appropriate <exceptionname>AuthenticationException</exceptionname> or
|
|
|
- <exceptionname>AccessDeniedException</exceptionname> will be thrown by a security
|
|
|
- interceptor further down the call stack, triggering the
|
|
|
- <methodname>commence</methodname> method on the entry point. This does the job of
|
|
|
- presenting the appropriate response to the user so that authentication can begin. The
|
|
|
- one we've used here is <classname>LoginUrlAuthenticationEntryPoint</classname>, which
|
|
|
- redirects the request to a different URL (typically a login page). The actual
|
|
|
- implementation used will depend on the authentication mechanism you want to be used in
|
|
|
- your application. </para>
|
|
|
+ <para> The <interfacename>AuthenticationEntryPoint</interfacename> will be called if the
|
|
|
+ user requests a secure HTTP resource but they are not authenticated. An appropriate
|
|
|
+ <exceptionname>AuthenticationException</exceptionname> or
|
|
|
+ <exceptionname>AccessDeniedException</exceptionname> will be thrown by a
|
|
|
+ security interceptor further down the call stack, triggering the
|
|
|
+ <methodname>commence</methodname> method on the entry point. This does the job
|
|
|
+ of presenting the appropriate response to the user so that authentication can begin.
|
|
|
+ The one we've used here is <classname>LoginUrlAuthenticationEntryPoint</classname>,
|
|
|
+ which redirects the request to a different URL (typically a login page). The actual
|
|
|
+ implementation used will depend on the authentication mechanism you want to be used
|
|
|
+ in your application. </para>
|
|
|
</section>
|
|
|
<section xml:id="access-denied-handler">
|
|
|
<title><interfacename>AccessDeniedHandler</interfacename></title>
|
|
|
@@ -156,65 +153,69 @@
|
|
|
for which they don't have enough permissions. In this case,
|
|
|
<classname>ExceptionTranslationFilter</classname> will invoke a second strategy,
|
|
|
the <interfacename>AccessDeniedHandler</interfacename>. By default, an
|
|
|
- <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>
|
|
|
- <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"/>.</para>
|
|
|
+ <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>
|
|
|
+ <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"/>.</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[
|
|
|
+ <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>
|
|
|
-
|
|
|
+ ]]></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">
|
|
|
+ <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);
|
|
|
}
|
|
|
-</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[
|
|
|
+</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[
|
|
|
<bean id="securityContextPersistenceFilter"
|
|
|
class="org.springframework.security.web.context.SecurityContextPersistenceFilter">
|
|
|
<property name='securityContextRepository'>
|
|
|
@@ -223,83 +224,89 @@ public interface SecurityContextRepository {
|
|
|
</bean>
|
|
|
</property>
|
|
|
</bean>
|
|
|
- ]]></programlisting>
|
|
|
-
|
|
|
- Alternatively you could provide a null implementation of the <interfacename>SecurityContextRepository</interfacename> interface.
|
|
|
- </para>
|
|
|
+ ]]></programlisting> Alternatively you could provide a null implementation of the
|
|
|
+ <interfacename>SecurityContextRepository</interfacename> interface. </para>
|
|
|
</section>
|
|
|
</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>
|
|
|
+ <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>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
|
|
|
+ <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[
|
|
|
+ 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>
|
|
|
-
|
|
|
+ </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>
|
|
|
- processes 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 as
|
|
|
- much as you want
|
|
|
- <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> 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.
|
|
|
+ <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>
|
Luke Taylor