67 lines
4.2 KiB
XML
67 lines
4.2 KiB
XML
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="form">
|
|
<info><title>Form Authentication Mechanism</title></info>
|
|
|
|
<section xml:id="form-overview">
|
|
<info><title>Overview</title></info>
|
|
|
|
<para>HTTP Form Authentication involves using the
|
|
<literal>UsernamePasswordAuthenticationProcessingFilter</literal> to process a login
|
|
form. This is the most common way for an application to authenticate end
|
|
users. Form-based authentication is entirely compatible with the DAO, LDAP
|
|
and JAAS authentication providers.</para>
|
|
<para>This is also the mechanism used by the <form-login> element from the namespace
|
|
and it's recommended that you use that unless you have specific customization requirements.
|
|
</para>
|
|
</section>
|
|
|
|
<section xml:id="form-config">
|
|
<info><title>Configuration</title></info>
|
|
|
|
<para>The login form simply contains <literal>j_username</literal> and
|
|
<literal>j_password</literal> input fields, and posts to a URL that is
|
|
monitored by the filter (by default
|
|
<literal>/j_spring_security_check</literal>). You should add an
|
|
<literal>UsernamePasswordAuthenticationProcessingFilter</literal> to your application context:
|
|
<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>
|
|
<para>
|
|
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> interfaces, respectively.
|
|
The filter has properties which allow you to set these
|
|
<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 for these 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>
|
|
</chapter> |