Cwikius-Spring/spring-security
1
0
Fork 0
mirror of https://github.com/spring-projects/spring-security.git synced 2025-06-28 14:52:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

SEC-1327: Minor doc update

Browse Source
This commit is contained in:
Luke Taylor 2009-12-22 13:40:05 +00:00
parent be56d72912
commit 1af9f8efea
1 changed files with 60 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

109
docs/manual/src/docbook/core-filters.xml
View File

@ -157,14 +157,14 @@
<classname>AccessDeniedHandlerImpl</classname> is used, which just sends a 403 <classname>AccessDeniedHandlerImpl</classname> is used, which just sends a 403
(Forbidden) response to the client. Alternatively you can configure an instance (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 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 forwards the request to <footnote>
SecurityContextHolder still contains details of the principal, which may be <para>We use a forward so that the SecurityContextHolder still contains details
useful for displaying to the user. In old releases of Spring Security we of the principal, which may be useful for displaying to the user. In old
relied upon the servlet container to handle a 403 error message, which releases of Spring Security we relied upon the servlet container to handle a
lacked this useful contextual information.</para></footnote>. This can be a 403 error message, which lacked this useful contextual information.</para>
simple <quote>access denied</quote> page, such as a JSP, or it could be a more </footnote>. This can be a simple <quote>access denied</quote> page, such as a JSP,
complex handler such as an MVC controller. And of course, you can implement the or it could be a more complex handler such as an MVC controller. And of course, you
interface yourself and use your own implementation. </para> can implement the interface yourself and use your own implementation. </para>
<para>It's also possible to supply a custom <para>It's also possible to supply a custom
<interfacename>AccessDeniedHandler</interfacename> when you're using the <interfacename>AccessDeniedHandler</interfacename> when you're using the
namespace to configure your application. See <link namespace to configure your application. See <link
@ -175,9 +175,9 @@
<section xml:id="security-context-persistence-filter"> <section xml:id="security-context-persistence-filter">
<title><classname>SecurityContextPersistenceFilter</classname></title> <title><classname>SecurityContextPersistenceFilter</classname></title>
<para> We covered the purpose of this all-important filter in the <link <para> We covered the purpose of this all-important filter in the <link
xlink:href="#tech-intro-sec-context-persistence">Technical Overview</link> chapter xlink:href="#tech-intro-sec-context-persistence">Technical Overview</link> chapter
so you might want to re-read that section at this point. Let's first take a look at how 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 you would configure it for use with a <classname>FilterChainProxy</classname>. A basic
configuration only requires the bean itself <programlisting><![CDATA[ configuration only requires the bean itself <programlisting><![CDATA[
<bean id="securityContextPersistenceFilter" <bean id="securityContextPersistenceFilter"
class="org.springframework.security.web.context.SecurityContextPersistenceFilter"/> class="org.springframework.security.web.context.SecurityContextPersistenceFilter"/>
@ -205,20 +205,20 @@ public interface SecurityContextRepository {
with wrapper classes. The returned contents will be passed to the filter chain. </para> with wrapper classes. The returned contents will be passed to the filter chain. </para>
<para> The default implementation is <para> The default implementation is
<classname>HttpSessionSecurityContextRepository</classname>, which stores the <classname>HttpSessionSecurityContextRepository</classname>, which stores the
security context as an <interfacename>HttpSession</interfacename> attribute security context as an <interfacename>HttpSession</interfacename> attribute <footnote>
<footnote><para>In Spring Security 2.0 and earlier, this filter was called <para>In Spring Security 2.0 and earlier, this filter was called
<classname>HttpSessionContextIntegrationFilter</classname> and performed <classname>HttpSessionContextIntegrationFilter</classname> and performed
all the work of storing the context was performed by the filter itself. If 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 you were familiar with this class, then most of the configuration options
which were available can now be found on which were available can now be found on
<classname>HttpSessionSecurityContextRepository</classname>. <classname>HttpSessionSecurityContextRepository</classname>. </para>
</para></footnote>. The most important configuration parameter for this </footnote>. The most important configuration parameter for this implementation is
implementation is the <literal>allowSessionCreation</literal> property, which the <literal>allowSessionCreation</literal> property, which defaults to
defaults to <literal>true</literal>, thus allowing the class to create a session if <literal>true</literal>, thus allowing the class to create a session if it needs
it needs one to store the security context for an authenticated user (it won't one to store the security context for an authenticated user (it won't create one
create one unless authentication has taken place and the contents of the security unless authentication has taken place and the contents of the security context have
context have changed). If you don't want a session to be created, then you can set changed). If you don't want a session to be created, then you can set this property
this property to <literal>false</literal>: <programlisting language="xml"><![CDATA[ to <literal>false</literal>: <programlisting language="xml"><![CDATA[
<bean id="securityContextPersistenceFilter" <bean id="securityContextPersistenceFilter"
class="org.springframework.security.web.context.SecurityContextPersistenceFilter"> class="org.springframework.security.web.context.SecurityContextPersistenceFilter">
<property name='securityContextRepository'> <property name='securityContextRepository'>
@ -228,7 +228,9 @@ class="org.springframework.security.web.context.SecurityContextPersistenceFilter
</property> </property>
</bean> </bean>
]]></programlisting> Alternatively you could provide a null implementation of the ]]></programlisting> Alternatively you could provide a null implementation of the
<interfacename>SecurityContextRepository</interfacename> interface. </para> <interfacename>SecurityContextRepository</interfacename> interface, which will
prevent the security context from being stored, even if a session has already been
created during the request. </para>
</section> </section>
</section> </section>
<section xml:id="form-login-filter"> <section xml:id="form-login-filter">
@ -238,27 +240,35 @@ class="org.springframework.security.web.context.SecurityContextPersistenceFilter
namespace <literal>&lt;http&gt;</literal> element and cannot be substituted with namespace <literal>&lt;http&gt;</literal> element and cannot be substituted with
alternatives. The only thing that's missing now is an actual authentication mechanism, 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 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 authentication filter and the one that is most often customized <footnote>
historical reasons, prior to Spring Security 3.0, this filter was called <para>For historical reasons, prior to Spring Security 3.0, this filter was called
<classname>AuthenticationProcessingFilter</classname> and the entry point <classname>AuthenticationProcessingFilter</classname> and the entry point
was called <classname>AuthenticationProcessingFilterEntryPoint</classname>. was called <classname>AuthenticationProcessingFilterEntryPoint</classname>.
Since the framework now supports many different forms of authentication, they 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 have both been given more specific names in 3.0.</para>
provides the implementation used by the &lt;form-login&gt; element from the namespace. </footnote>. It also provides the implementation used by the &lt;form-login&gt; element
There are three stages required to configure it. <orderedlist><listitem><para>Configure from the namespace. There are three stages required to configure it. <orderedlist>
a <classname>LoginUrlAuthenticationEntryPoint</classname> with the URL of <listitem>
the login page, just as we did above, and set it on the <para>Configure a <classname>LoginUrlAuthenticationEntryPoint</classname> with
<classname>ExceptionTranslationFilter</classname>. the URL of the login page, just as we did above, and set it on the
</para></listitem><listitem><para>Implement the login page (using a JSP or <classname>ExceptionTranslationFilter</classname>. </para>
MVC controller).</para></listitem><listitem><para>Configure an instance of </listitem>
<listitem>
<para>Implement the login page (using a JSP or MVC controller).</para>
</listitem>
<listitem>
<para>Configure an instance of
<classname>UsernamePasswordAuthenticationFilter</classname> in the <classname>UsernamePasswordAuthenticationFilter</classname> in the
application context</para></listitem><listitem><para>Add the filter bean to application context</para>
your filter chain proxy (making sure you pay attention to the order). </listitem>
<!-- TODO: link --></para></listitem></orderedlist> The login form simply <listitem>
contains <literal>j_username</literal> and <literal>j_password</literal> input fields, <para>Add the filter bean to your filter chain proxy (making sure you pay
and posts to the URL that is monitored by the filter (by default this is attention to the order). <!-- TODO: link --></para>
<literal>/j_spring_security_check</literal>). The basic filter configuration looks </listitem>
something like this: <programlisting><![CDATA[ </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="authenticationFilter" class= <bean id="authenticationFilter" class=
"org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter"> "org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter">
<property name="authenticationManager" ref="authenticationManager"/> <property name="authenticationManager" ref="authenticationManager"/>
@ -274,12 +284,13 @@ class="org.springframework.security.web.context.SecurityContextPersistenceFilter
<interfacename>AuthenticationSuccessHandler</interfacename> and <interfacename>AuthenticationSuccessHandler</interfacename> and
<interfacename>AuthenticationFailureHandler</interfacename> strategy interfaces, <interfacename>AuthenticationFailureHandler</interfacename> strategy interfaces,
respectively. The filter has properties which allow you to set these so you can 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 customize the behaviour completely <footnote>
application flow at this point had evolved to a stage was controlled by a <para>In versions prior to 3.0, the application flow at this point had evolved
mix of properties on this class and strategy plugins. The decision was made to a stage was controlled by a mix of properties on this class and strategy
for 3.0 to refactor the code to make these two strategies entirely plugins. The decision was made for 3.0 to refactor the code to make these
responsible. </para></footnote>. Some standard implementations are supplied two strategies entirely responsible. </para>
such as <classname>SimpleUrlAuthenticationSuccessHandler</classname>, </footnote>. Some standard implementations are supplied such as
<classname>SimpleUrlAuthenticationSuccessHandler</classname>,
<classname>SavedRequestAwareAuthenticationSuccessHandler</classname>, <classname>SavedRequestAwareAuthenticationSuccessHandler</classname>,
<classname>SimpleUrlAuthenticationFailureHandler</classname> and <classname>SimpleUrlAuthenticationFailureHandler</classname> and
<classname>ExceptionMappingAuthenticationFailureHandler</classname>. Have a look <classname>ExceptionMappingAuthenticationFailureHandler</classname>. Have a look
@ -291,12 +302,12 @@ class="org.springframework.security.web.context.SecurityContextPersistenceFilter
user to the approprate destination. By default a user to the approprate destination. By default a
<classname>SavedRequestAwareAuthenticationSuccessHandler</classname> is used, <classname>SavedRequestAwareAuthenticationSuccessHandler</classname> is used,
which means that the user will be redirected to the original destination they which means that the user will be redirected to the original destination they
requested before they were asked to login. <note><para> The requested before they were asked to login. <note>
<classname>ExceptionTranslationFilter</classname> caches the original <para> The <classname>ExceptionTranslationFilter</classname> caches the original
request a user makes. When the user authenticates, the request handler makes 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. 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. The original request is then rebuilt and used as an alternative. </para>
</para></note> If authentication fails, the configured </note> If authentication fails, the configured
<interfacename>AuthenticationFailureHandler</interfacename> will be invoked. <interfacename>AuthenticationFailureHandler</interfacename> will be invoked.
</para> </para>
</section> </section>