Cwikius-Spring
/
spring-security
mirror of https://github.com/spring-projects/spring-security.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Ref manual content and docbook improvements

This commit is contained in:
Luke Taylor 2009-12-12 21:21:59 +00:00
parent 282bfc3151
commit fdc9c5fd08
16 changed files with 497 additions and 304 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
docs/manual/src/docbook/anon-auth-provider.xml
View File

@ -1,4 +1,4 @@
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="anonymous"> <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="anonymous" xmlns:xlink="http://www.w3.org/1999/xlink">
<info> <info>
<title>Anonymous Authentication</title> <title>Anonymous Authentication</title>
</info> </info>
@ -37,7 +37,7 @@
<title>Configuration</title> <title>Configuration</title>
</info> </info>
<para>Anonymous authentication support is provided automatically when using the HTTP <para>Anonymous authentication support is provided automatically when using the HTTP
configurain Spring Security 3.0 and can be customized (or disabled) using the configuration Spring Security 3.0 and can be customized (or disabled) using the
<literal>&lt;anonymous></literal> element. You don't need to configure the beans <literal>&lt;anonymous></literal> element. You don't need to configure the beans
described here unless you are using traditional bean configuration.</para> described here unless you are using traditional bean configuration.</para>
<para>Three classes that together provide the anonymous authentication feature. <para>Three classes that together provide the anonymous authentication feature.
@ -69,10 +69,10 @@
</programlisting> </programlisting>
</para> </para>
<para>The <literal>key</literal> is shared between the filter and authentication provider, <para>The <literal>key</literal> is shared between the filter and authentication provider,
so that tokens created by the former are accepted by the latter<footnote><para>The use so that tokens created by the former are accepted by the latter<footnote>
of the <literal>key</literal> property should not be regarded as providing any <para>The use of the <literal>key</literal> property should not be regarded as
real security here. It is merely a book-keeping exercise. If you are sharing a providing any real security here. It is merely a book-keeping exercise. If you
<classname>ProviderManager</classname> which contains an are sharing a <classname>ProviderManager</classname> which contains an
<classname>AnonymousAuthenticationProvider</classname> in a scenario where <classname>AnonymousAuthenticationProvider</classname> in a scenario where
it is possible for an authenticating client to construct the it is possible for an authenticating client to construct the
<interfacename>Authentication</interfacename> object (such as with RMI <interfacename>Authentication</interfacename> object (such as with RMI
@ -83,8 +83,8 @@
anonymous provider. This isn't a problem with normal usage but if you are using anonymous provider. This isn't a problem with normal usage but if you are using
RMI you would be best to use a customized <classname>ProviderManager</classname> RMI you would be best to use a customized <classname>ProviderManager</classname>
which omits the anonymous provider rather than sharing the one you use for your which omits the anonymous provider rather than sharing the one you use for your
HTTP authentication mechanisms.</para></footnote>. The HTTP authentication mechanisms.</para>
<literal>userAttribute</literal> is expressed in the form of </footnote>. The <literal>userAttribute</literal> is expressed in the form of
<literal>usernameInTheAuthenticationToken,grantedAuthority[,grantedAuthority]</literal>. <literal>usernameInTheAuthenticationToken,grantedAuthority[,grantedAuthority]</literal>.
This is the same syntax as used after the equals sign for This is the same syntax as used after the equals sign for
<literal>InMemoryDaoImpl</literal>'s <literal>userMap</literal> property.</para> <literal>InMemoryDaoImpl</literal>'s <literal>userMap</literal> property.</para>
@ -128,8 +128,9 @@
<para> You will often see the <literal>ROLE_ANONYMOUS</literal> attribute in the above <para> You will often see the <literal>ROLE_ANONYMOUS</literal> attribute in the above
interceptor configuration replaced with <literal>IS_AUTHENTICATED_ANONYMOUSLY</literal>. interceptor configuration replaced with <literal>IS_AUTHENTICATED_ANONYMOUSLY</literal>.
This is an example of the use of the <classname>AuthenticatedVoter</classname> which This is an example of the use of the <classname>AuthenticatedVoter</classname> which
will see in ???. It uses an <interfacename>AuthenticationTrustResolver</interfacename> will see in the <link xlink:href="#authz-authenticated-voter">authorization
to process this particular configuration attribute and grant access to aonymous users. chapter</link>. It uses an
</para> <interfacename>AuthenticationTrustResolver</interfacename> to process this
particular configuration attribute and grant access to aonymous users. </para>
</section> </section>
</chapter> </chapter>

88
docs/manual/src/docbook/appendix-namespace.xml
View File

@ -22,15 +22,16 @@
<para> The <literal>&lt;http&gt;</literal> element encapsulates the security configuration for <para> The <literal>&lt;http&gt;</literal> element encapsulates the security configuration for
the web layer of your application. It creates a <classname>FilterChainProxy</classname> bean 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 named "springSecurityFilterChain" which maintains the stack of security filters which make up
the web security configuration <footnote><para>See the <link xlink:href="#ns-web-xml"> the web security configuration <footnote>
introductory chapter</link> for how to set up the mapping from your <para>See the <link xlink:href="#ns-web-xml"> introductory chapter</link> for how to set up
<literal>web.xml</literal></para></footnote>. Some core filters are always created and the mapping from your <literal>web.xml</literal></para>
others will be added to the stack depending on the attributes child elements which are </footnote>. Some core filters are always created and others will be added to the stack
present. The positions of the standard filters are fixed (see <link xlink:href="#filter-stack" depending on the attributes child elements which are present. The positions of the standard
>the filter order table</link> in the namespace introduction), removing a common source of filters are fixed (see <link xlink:href="#filter-stack">the filter order table</link> in the
errors with previous versions of the framework when users had to configure the filter chain namespace introduction), removing a common source of errors with previous versions of the
explicitly in the<classname>FilterChainProxy</classname> bean. You can, of course, still do framework when users had to configure the filter chain explicitly in
this if you need full control of the configuration. </para> the<classname>FilterChainProxy</classname> bean. You can, of course, still do this if you
need full control of the configuration. </para>
<para> All filters which require a reference to the <para> All filters which require a reference to the
<interfacename>AuthenticationManager</interfacename> will be automatically injected with the <interfacename>AuthenticationManager</interfacename> will be automatically injected with the
internal instance created by the namespace configuration (see the <link internal instance created by the namespace configuration (see the <link
@ -112,7 +113,7 @@
</section> </section>
</section> </section>
<section xml:id="nsa-access-denied-handler"> <section xml:id="nsa-access-denied-handler">
<title><literal>access-denied-handler</literal></title> <title><literal>&lt;access-denied-handler></literal></title>
<para> This element allows you to set the <literal>errorPage</literal> property for the <para> This element allows you to set the <literal>errorPage</literal> property for the
default <interfacename>AccessDeniedHandler</interfacename> used by the default <interfacename>AccessDeniedHandler</interfacename> used by the
<classname>ExceptionTranslationFilter</classname>, (using the <classname>ExceptionTranslationFilter</classname>, (using the
@ -129,7 +130,10 @@
<classname>FilterSecurityInterceptor</classname> and to exclude particular patterns from <classname>FilterSecurityInterceptor</classname> and to exclude particular patterns from
the filter chain entirely (by setting the attribute <literal>filters="none"</literal>). It the filter chain entirely (by setting the attribute <literal>filters="none"</literal>). It
is also responsible for configuring a <classname>ChannelAuthenticationFilter</classname> if is also responsible for configuring a <classname>ChannelAuthenticationFilter</classname> if
particular URLs need to be accessed by HTTPS, for example. </para> 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 declared. So the most specific matches patterns should come first and the most
general should come last.</para>
<section xml:id="nsa-pattern"> <section xml:id="nsa-pattern">
<title><literal>pattern</literal></title> <title><literal>pattern</literal></title>
<para> The pattern which defines the URL path. The content will depend on the <para> The pattern which defines the URL path. The content will depend on the
@ -139,24 +143,25 @@
<section xml:id="nsa-method"> <section xml:id="nsa-method">
<title><literal>method</literal></title> <title><literal>method</literal></title>
<para> The HTTP Method which will be used in combination with the pattern to match an <para> The HTTP Method which will be used in combination with the pattern to match an
incoming request. If omitted, any method will match. </para> incoming request. If omitted, any method will match. If an identical pattern is specified
with and without a method, the method-specific match will take precedence.</para>
</section> </section>
<section xml:id="nsa-access"> <section xml:id="nsa-access">
<title><literal>access</literal></title> <title><literal>access</literal></title>
<para> Lists the access attributes which will be stored in the <para> Lists the access attributes which will be stored in the
<interfacename>FilterInvocationDefinitionSource</interfacename> for the defined URL <interfacename>FilterInvocationDefinitionSource</interfacename> for the defined URL
pattern/method combination. This should be a comma-separated list of the attributes (such pattern/method combination. This should be a comma-separated list of the security
as role names). </para> configuration attributes (such as role names). </para>
</section> </section>
<section xml:id="nsa-requires-channel"> <section xml:id="nsa-requires-channel">
<title><literal>requires-channel</literal></title> <title><literal>requires-channel</literal></title>
<para> Can be "http" or "https" depending on whether a particular URL pattern should be <para> Can be <quote>http</quote> or <quote>https</quote> depending on whether a particular
accessed over HTTP or HTTPS respectively. Alternatively the value "any" can be used when URL pattern should be accessed over HTTP or HTTPS respectively. Alternatively the value
there is no preference. If this attribute is present on any <quote>any</quote> can be used when there is no preference. If this attribute is present
<literal>&lt;intercept-url&gt;</literal> element, then a on any <literal>&lt;intercept-url&gt;</literal> element, then a
<classname>ChannelAuthenticationFilter</classname> will be added to the filter stack and <classname>ChannelAuthenticationFilter</classname> will be added to the filter stack and
its additional dependencies added to the application context. its additional dependencies added to the application
<!--See the chapter on <link context.<!--See the chapter on <link
xlink:href="#channel-security-config">channel security</link> for an example xlink:href="#channel-security-config">channel security</link> for an example
configuration using traditional beans. --></para> configuration using traditional beans. --></para>
<para> If a <literal>&lt;port-mappings&gt;</literal> configuration is added, this will be <para> If a <literal>&lt;port-mappings&gt;</literal> configuration is added, this will be
@ -164,6 +169,14 @@
<classname>InsecureChannelProcessor</classname> beans to determine the ports used for <classname>InsecureChannelProcessor</classname> beans to determine the ports used for
redirecting to HTTP/HTTPS. </para> redirecting to HTTP/HTTPS. </para>
</section> </section>
<section>
<title><literal>filters</literal></title>
<para>Can only take the value <quote>none</quote>. This will cause any matching request to
bypass the Spring Security filter chain entirely. None of the rest of the
<literal>&lt;http></literal> configuration will have any effect on the request and there
will be no security context available for its duration. Access to secured methods during
the request will fail.</para>
</section>
</section> </section>
<section> <section>
<title>The <literal>&lt;port-mappings&gt;</literal> Element</title> <title>The <literal>&lt;port-mappings&gt;</literal> Element</title>
@ -180,13 +193,14 @@
filter stack and an <classname>LoginUrlAuthenticationEntryPoint</classname> to the filter stack and an <classname>LoginUrlAuthenticationEntryPoint</classname> to the
application context to provide authentication on demand. This will always take precedence application context to provide authentication on demand. This will always take precedence
over other namespace-created entry points. If no attributes are supplied, a login page will over other namespace-created entry points. If no attributes are supplied, a login page will
be generated automatically at the URL "/spring-security-login" <footnote><para>This feature be generated automatically at the URL "/spring-security-login" <footnote>
is really just provided for convenience and is not intended for production (where a view <para>This feature is really just provided for convenience and is not intended for
technology will have been chosen and can be used to render a customized login page). The production (where a view technology will have been chosen and can be used to render a
class <classname>DefaultLoginPageGeneratingFilter</classname> is responsible for customized login page). The class
rendering the login page and will provide login forms for both normal form login and/or <classname>DefaultLoginPageGeneratingFilter</classname> is responsible for rendering
OpenID if required.</para></footnote> The behaviour can be customized using the the login page and will provide login forms for both normal form login and/or OpenID if
following attributes. </para> required.</para>
</footnote> The behaviour can be customized using the following attributes. </para>
<section> <section>
<title><literal>login-page</literal></title> <title><literal>login-page</literal></title>
<para> The URL that should be used to render the login page. Maps to the <para> The URL that should be used to render the login page. Maps to the
@ -279,9 +293,11 @@
<title>The <literal>key</literal> Attribute</title> <title>The <literal>key</literal> Attribute</title>
<para>Maps to the "key" property of <classname>AbstractRememberMeServices</classname>. <para>Maps to the "key" property of <classname>AbstractRememberMeServices</classname>.
Should be set to a unique value to ensure that remember-me cookies are only valid within Should be set to a unique value to ensure that remember-me cookies are only valid within
the one application <footnote><para>This doesn't affect the use of the one application <footnote>
<para>This doesn't affect the use of
<classname>PersistentTokenBasedRememberMeServices</classname>, where the tokens are <classname>PersistentTokenBasedRememberMeServices</classname>, where the tokens are
stored on the server side.</para></footnote>. </para> stored on the server side.</para>
</footnote>. </para>
</section> </section>
<section> <section>
<title><literal>token-validity-seconds</literal></title> <title><literal>token-validity-seconds</literal></title>
@ -507,11 +523,15 @@
<para> Rather than defining security attributes on an individual method or class basis using <para> Rather than defining security attributes on an individual method or class basis using
the <literal>@Secured</literal> annotation, you can define cross-cutting security the <literal>@Secured</literal> annotation, you can define cross-cutting security
constraints across whole sets of methods and interfaces in your service layer using the constraints across whole sets of methods and interfaces in your service layer using the
<literal>&lt;protect-pointcut&gt;</literal> element. This has two attributes: <literal>&lt;protect-pointcut&gt;</literal> element. This has two attributes: <itemizedlist>
<itemizedlist><listitem><para><literal>expression</literal> - the pointcut <listitem>
expression</para></listitem><listitem><para><literal>access</literal> - the security <para><literal>expression</literal> - the pointcut expression</para>
attributes which apply</para></listitem></itemizedlist> You can find an example in </listitem>
the <link xlink:href="#ns-protect-pointcut">namespace introduction</link>. </para> <listitem>
<para><literal>access</literal> - the security attributes which apply</para>
</listitem>
</itemizedlist> You can find an example in the <link xlink:href="#ns-protect-pointcut"
>namespace introduction</link>. </para>
</section> </section>
<section xml:id="nsa-custom-after-invocation"> <section xml:id="nsa-custom-after-invocation">
<title>The <literal>&lt;after-invocation-provider&gt;</literal> Element</title> <title>The <literal>&lt;after-invocation-provider&gt;</literal> Element</title>

202
docs/manual/src/docbook/authorization-common.xml
View File

@ -1,9 +1,9 @@
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="authorization-common" <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="authz-arch"
xmlns:xlink="http://www.w3.org/1999/xlink"> xmlns:xlink="http://www.w3.org/1999/xlink">
<info> <info>
<title>Common Authorization Concepts</title> <title>Authorization Architecture</title>
</info> </info>
<section xml:id="authorities"> <section xml:id="authz-authorities">
<info> <info>
<title>Authorities</title> <title>Authorities</title>
</info> </info>
@ -45,7 +45,7 @@
<literal>GrantedAuthorityImpl</literal> to populate the <literal>GrantedAuthorityImpl</literal> to populate the
<interfacename>Authentication</interfacename> object.</para> <interfacename>Authentication</interfacename> object.</para>
</section> </section>
<section xml:id="pre-invocation"> <section xml:id="authz-pre-invocation">
<info> <info>
<title>Pre-Invocation Handling</title> <title>Pre-Invocation Handling</title>
</info> </info>
@ -53,7 +53,7 @@
chapter, Spring Security provides interceptors which control access to secure objects such as chapter, Spring Security provides interceptors which control access to secure objects such as
method invocations or web requests. A pre-invocation decision on whether the invocation is method invocations or web requests. A pre-invocation decision on whether the invocation is
allowed to proceed is made by the <interfacename>AccessDecisionManager</interfacename>. </para> allowed to proceed is made by the <interfacename>AccessDecisionManager</interfacename>. </para>
<section> <section xml:id="authz-access-decision-manager">
<title>The AccessDecisionManager</title> <title>The AccessDecisionManager</title>
<para>The <interfacename>AccessDecisionManager</interfacename> is called by the <para>The <interfacename>AccessDecisionManager</interfacename> is called by the
<classname>AbstractSecurityInterceptor</classname> and is responsible for making final <classname>AbstractSecurityInterceptor</classname> and is responsible for making final
@ -82,102 +82,110 @@
called by a security interceptor implementation to ensure the configured called by a security interceptor implementation to ensure the configured
<interfacename>AccessDecisionManager</interfacename> supports the type of secure object <interfacename>AccessDecisionManager</interfacename> supports the type of secure object
that the security interceptor will present.</para> that the security interceptor will present.</para>
<section> </section>
<title>Voting-Based AccessDecisionManager Implementations</title> <section xml:id="authz-voting-based">
<para>Whilst users can implement their own <title>Voting-Based AccessDecisionManager Implementations</title>
<interfacename>AccessDecisionManager</interfacename> to control all aspects of <para>Whilst users can implement their own
authorization, Spring Security includes several <interfacename>AccessDecisionManager</interfacename> to control all aspects of
<interfacename>AccessDecisionManager</interfacename> implementations that are based on authorization, Spring Security includes several
voting. <xref linkend="authz-access-voting"/> illustrates the relevant classes.</para> <interfacename>AccessDecisionManager</interfacename> implementations that are based on
<figure xml:id="authz-access-voting"> voting. <xref linkend="authz-access-voting"/> illustrates the relevant classes.</para>
<title>Voting Decision Manager</title> <figure xml:id="authz-access-voting">
<mediaobject> <title>Voting Decision Manager</title>
<!-- <mediaobject>
<imageobject role="fo"> <!--
<imagedata align="center" fileref="resources/images/AccessDecisionVoting.gif" format="GIF"/> <imageobject role="fo">
</imageobject> <imagedata align="center" fileref="resources/images/AccessDecisionVoting.gif" format="GIF"/>
</imageobject>
--> -->
<imageobject> <imageobject>
<imagedata align="center" scalefit="1" fileref="images/AccessDecisionVoting.gif" <imagedata align="center" scalefit="1" fileref="images/AccessDecisionVoting.gif"
format="GIF"/> format="GIF" />
</imageobject> </imageobject>
</mediaobject> </mediaobject>
</figure> </figure>
<para>Using this approach, a series of <interfacename>AccessDecisionVoter</interfacename> <para>Using this approach, a series of <interfacename>AccessDecisionVoter</interfacename>
implementations are polled on an authorization decision. The implementations are polled on an authorization decision. The
<interfacename>AccessDecisionManager</interfacename> then decides whether or not to <interfacename>AccessDecisionManager</interfacename> then decides whether or not to throw
throw an <literal>AccessDeniedException</literal> based on its assessment of the an <literal>AccessDeniedException</literal> based on its assessment of the votes.</para>
votes.</para> <para>The <interfacename>AccessDecisionVoter</interfacename> interface has three methods:
<para>The <interfacename>AccessDecisionVoter</interfacename> interface has three methods: <programlisting>
<programlisting>
int vote(Authentication authentication, Object object, List&lt;ConfigAttribute&gt; config); int vote(Authentication authentication, Object object, List&lt;ConfigAttribute&gt; config);
boolean supports(ConfigAttribute attribute); boolean supports(ConfigAttribute attribute);
boolean supports(Class clazz); boolean supports(Class clazz);
</programlisting> </programlisting>
Concrete implementations return an <literal>int</literal>, with possible values being Concrete implementations return an <literal>int</literal>, with possible values being
reflected in the <interfacename>AccessDecisionVoter</interfacename> static fields reflected in the <interfacename>AccessDecisionVoter</interfacename> static fields
<literal>ACCESS_ABSTAIN</literal>, <literal>ACCESS_DENIED</literal> and <literal>ACCESS_ABSTAIN</literal>, <literal>ACCESS_DENIED</literal> and
<literal>ACCESS_GRANTED</literal>. A voting implementation will return <literal>ACCESS_GRANTED</literal>. A voting implementation will return
<literal>ACCESS_ABSTAIN</literal> if it has no opinion on an authorization decision. If <literal>ACCESS_ABSTAIN</literal> if it has no opinion on an authorization decision. If it
it does have an opinion, it must return either <literal>ACCESS_DENIED</literal> or does have an opinion, it must return either <literal>ACCESS_DENIED</literal> or
<literal>ACCESS_GRANTED</literal>.</para> <literal>ACCESS_GRANTED</literal>.</para>
<para>There are three concrete <interfacename>AccessDecisionManager</interfacename>s <para>There are three concrete <interfacename>AccessDecisionManager</interfacename>s provided
provided with Spring Security that tally the votes. The <literal>ConsensusBased</literal> with Spring Security that tally the votes. The <literal>ConsensusBased</literal>
implementation will grant or deny access based on the consensus of non-abstain votes. implementation will grant or deny access based on the consensus of non-abstain votes.
Properties are provided to control behavior in the event of an equality of votes or if all Properties are provided to control behavior in the event of an equality of votes or if all
votes are abstain. The <literal>AffirmativeBased</literal> implementation will grant votes are abstain. The <literal>AffirmativeBased</literal> implementation will grant access
access if one or more <literal>ACCESS_GRANTED</literal> votes were received (i.e. a deny if one or more <literal>ACCESS_GRANTED</literal> votes were received (i.e. a deny vote will
vote will be ignored, provided there was at least one grant vote). Like the be ignored, provided there was at least one grant vote). Like the
<literal>ConsensusBased</literal> implementation, there is a parameter that controls the <literal>ConsensusBased</literal> implementation, there is a parameter that controls the
behavior if all voters abstain. The <literal>UnanimousBased</literal> provider expects behavior if all voters abstain. The <literal>UnanimousBased</literal> provider expects
unanimous <literal>ACCESS_GRANTED</literal> votes in order to grant access, ignoring unanimous <literal>ACCESS_GRANTED</literal> votes in order to grant access, ignoring
abstains. It will deny access if there is any <literal>ACCESS_DENIED</literal> vote. Like abstains. It will deny access if there is any <literal>ACCESS_DENIED</literal> vote. Like
the other implementations, there is a parameter that controls the behaviour if all voters the other implementations, there is a parameter that controls the behaviour if all voters
abstain.</para>
<para>It is possible to implement a custom
<interfacename>AccessDecisionManager</interfacename> that tallies votes differently. For
example, votes from a particular <interfacename>AccessDecisionVoter</interfacename> might
receive additional weighting, whilst a deny vote from a particular voter may have a veto
effect.</para>
<section xml:id="authz-role-voter">
<title><classname>RoleVoter</classname></title>
<para> The most commonly used <interfacename>AccessDecisionVoter</interfacename> provided
with Spring Security is the simple <classname>RoleVoter</classname>, which treats
configuration attributes as simple role names and votes to grant access if the user has
been assigned that role.</para>
<para>It will vote if any <interfacename>ConfigAttribute</interfacename> begins with the
prefix <literal>ROLE_</literal>. It will vote to grant access if there is a
<interfacename>GrantedAuthority</interfacename> which returns a
<literal>String</literal> representation (via the <literal>getAuthority()</literal>
method) exactly equal to one or more <literal>ConfigAttributes</literal> starting with
<literal>ROLE_</literal>. If there is no exact match of any
<literal>ConfigAttribute</literal> starting with <literal>ROLE_</literal>, the
<literal>RoleVoter</literal> will vote to deny access. If no
<literal>ConfigAttribute</literal> begins with <literal>ROLE_</literal>, the voter will
abstain.</para> abstain.</para>
<para>It is possible to implement a custom </section>
<interfacename>AccessDecisionManager</interfacename> that tallies votes differently. For <section xml:id="authz-authenticated-voter">
example, votes from a particular <interfacename>AccessDecisionVoter</interfacename> might <title><classname>AuthenticatedVoter</classname></title>
receive additional weighting, whilst a deny vote from a particular voter may have a veto <para> Another voter which we've implicitly seen is the
effect.</para> <classname>AuthenticatedVoter</classname>, which can be used to differentiate between
<section> anonymous, fully-authenticated and remember-me authenticated users. When we've used the
<title><classname>RoleVoter</classname></title> attribute <literal>IS_AUTHENTICATED_ANONYMOUSLY</literal> to grant anonymous access, this
<para> The most commonly used <interfacename>AccessDecisionVoter</interfacename> provided attribute was being processed by the <classname>AuthenticatedVoter</classname>. See the
with Spring Security is the simple <classname>RoleVoter</classname>, which treats Javadoc for this class for more information. </para>
configuration attributes as simple role names and votes to grant access if the user has </section>
been assigned that role.</para> <section>
<para>It will vote if any ConfigAttribute begins with the prefix <literal>ROLE_</literal>. <title>Custom Voters</title>
It will vote to grant access if there is a <para>It is also possible to implement a custom
<interfacename>GrantedAuthority</interfacename> which returns a <interfacename>AccessDecisionVoter</interfacename>. Several examples are provided in
<literal>String</literal> representation (via the <literal>getAuthority()</literal> Spring Security unit tests, including <literal>ContactSecurityVoter</literal> and
method) exactly equal to one or more <literal>ConfigAttributes</literal> starting with <literal>DenyVoter</literal>. The <literal>ContactSecurityVoter</literal> abstains from
<literal>ROLE_</literal>. If there is no exact match of any voting decisions where a <literal>CONTACT_OWNED_BY_CURRENT_USER</literal>
<literal>ConfigAttribute</literal> starting with <literal>ROLE_</literal>, the <literal>ConfigAttribute</literal> is not found. If voting, it queries the
<literal>RoleVoter</literal> will vote to deny access. If no <classname>MethodInvocation</classname> to extract the owner of the
<literal>ConfigAttribute</literal> begins with <literal>ROLE_</literal>, the voter <literal>Contact</literal> object that is subject of the method call. It votes to grant
will abstain. The comparisons of attributes and</para> access if the <literal>Contact</literal> owner matches the principal presented in the
</section> <interfacename>Authentication</interfacename> object. It could have just as easily
<section> compared the <literal>Contact</literal> owner with some
<title>Custom Voters</title> <interfacename>GrantedAuthority</interfacename> the
<para>It is also possible to implement a custom <interfacename>Authentication</interfacename> object presented. All of this is achieved
<interfacename>AccessDecisionVoter</interfacename>. Several examples are provided in with relatively few lines of code and demonstrates the flexibility of the authorization
Spring Security unit tests, including <literal>ContactSecurityVoter</literal> and model.</para>
<literal>DenyVoter</literal>. The <literal>ContactSecurityVoter</literal> abstains
from voting decisions where a <literal>CONTACT_OWNED_BY_CURRENT_USER</literal>
<literal>ConfigAttribute</literal> is not found. If voting, it queries the
<classname>MethodInvocation</classname> to extract the owner of the
<literal>Contact</literal> object that is subject of the method call. It votes to
grant access if the <literal>Contact</literal> owner matches the principal presented in
the <interfacename>Authentication</interfacename> object. It could have just as easily
compared the <literal>Contact</literal> owner with some
<interfacename>GrantedAuthority</interfacename> the
<interfacename>Authentication</interfacename> object presented. All of this is
achieved with relatively few lines of code and demonstrates the flexibility of the
authorization model.</para>
</section>
</section> </section>
</section> </section>
</section> </section>
<section xml:id="after-invocation"> <section xml:id="authz-after-invocation-handling">
<info> <info>
<title>After Invocation Handling</title> <title>After Invocation Handling</title>
</info> </info>
@ -189,11 +197,15 @@ boolean supports(Class clazz);
that integrate with its ACL capabilities.</para> that integrate with its ACL capabilities.</para>
<para><xref linkend="authz-after-invocation"/> illustrates Spring Security's <para><xref linkend="authz-after-invocation"/> illustrates Spring Security's
<literal>AfterInvocationManager</literal> and its concrete implementations. <figure <literal>AfterInvocationManager</literal> and its concrete implementations. <figure
xml:id="authz-after-invocation"><title>After Invocation xml:id="authz-after-invocation">
Implementation</title><mediaobject><imageobject> <title>After Invocation Implementation</title>
<mediaobject>
<imageobject>
<imagedata align="center" scalefit="1" fileref="images/AfterInvocation.gif" format="GIF" <imagedata align="center" scalefit="1" fileref="images/AfterInvocation.gif" format="GIF"
/> />
</imageobject></mediaobject></figure></para> </imageobject>
</mediaobject>
</figure></para>
<para>Like many other parts of Spring Security, <literal>AfterInvocationManager</literal> has a <para>Like many other parts of Spring Security, <literal>AfterInvocationManager</literal> has a
single concrete implementation, <literal>AfterInvocationProviderManager</literal>, which polls single concrete implementation, <literal>AfterInvocationProviderManager</literal>, which polls
a list of <literal>AfterInvocationProvider</literal>s. Each a list of <literal>AfterInvocationProvider</literal>s. Each

BIN
docs/manual/src/docbook/images/ACLSecurity.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 3.9 KiB

BIN
docs/manual/src/docbook/images/BasicAclProvider.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 9.7 KiB

BIN
docs/manual/src/docbook/images/Context.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 4.2 KiB

BIN
docs/manual/src/docbook/images/Permissions.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 14 KiB

BIN
docs/manual/src/docbook/images/SecurityInterception.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 5.4 KiB

BIN
docs/manual/src/docbook/images/logo.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 8.7 KiB

BIN
docs/manual/src/docbook/images/xdev-spring_logo.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 36 KiB

320
docs/manual/src/docbook/namespace-config.xml
View File

@ -9,8 +9,8 @@
<para> Namespace configuration has been available since version 2.0 of the Spring framework. It <para> Namespace configuration has been available since version 2.0 of the Spring framework. It
allows you to supplement the traditional Spring beans application context syntax with elements allows you to supplement the traditional Spring beans application context syntax with elements
from additional XML schema. You can find more information in the Spring <link from additional XML schema. You can find more information in the Spring <link
xlink:href="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/apc.html"> xlink:href="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/apc.html"
Reference Documentation</link>. A namespace element can be used simply to allow a more > Reference Documentation</link>. A namespace element can be used simply to allow a more
concise way of configuring an individual bean or, more powerfully, to define an alternative concise way of configuring an individual bean or, more powerfully, to define an alternative
configuration syntax which more closely matches the problem domain and hides the underlying configuration syntax which more closely matches the problem domain and hides the underlying
complexity from the user. A simple element may conceal the fact that multiple beans and complexity from the user. A simple element may conceal the fact that multiple beans and
@ -21,13 +21,13 @@
]]></programlisting> This is much simpler than wiring up the equivalent Apache Directory Server ]]></programlisting> This is much simpler than wiring up the equivalent Apache Directory Server
beans. The most common alternative configuration requirements are supported by attributes on beans. The most common alternative configuration requirements are supported by attributes on
the <literal>ldap-server</literal> element and the user is isolated from worrying about which the <literal>ldap-server</literal> element and the user is isolated from worrying about which
beans they need to create and what the bean property names are. <footnote><para>You can find out beans they need to create and what the bean property names are. <footnote>
more about the use of the <literal>ldap-server</literal> element in the chapter on <link <para>You can find out more about the use of the <literal>ldap-server</literal> element in
xlink:href="#ldap">LDAP</link>.</para></footnote>. Use of a good XML editor while the chapter on <link xlink:href="#ldap">LDAP</link>.</para>
editing the application context file should provide information on the attributes and elements </footnote>. Use of a good XML editor while editing the application context file should
that are available. We would recommend that you try out the <link provide information on the attributes and elements that are available. We would recommend that
xlink:href="http://www.springsource.com/products/sts">SpringSource Tool Suite</link> as it you try out the <link xlink:href="http://www.springsource.com/products/sts">SpringSource Tool
has special features for working with standard Spring namespaces. </para> Suite</link> as it has special features for working with standard Spring namespaces. </para>
<para> To start using the security namespace in your application context, all you need to do is <para> To start using the security namespace in your application context, all you need to do is
add the schema declaration to your application context file: <programlisting language="xml"> add the schema declaration to your application context file: <programlisting language="xml">
<![CDATA[ <![CDATA[
@ -61,28 +61,44 @@
<para> The namespace is designed to capture the most common uses of the framework and provide <para> The namespace is designed to capture the most common uses of the framework and provide
a simplified and concise syntax for enabling them within an application. The design is based a simplified and concise syntax for enabling them within an application. The design is based
around the large-scale dependencies within the framework, and can be divided up into the around the large-scale dependencies within the framework, and can be divided up into the
following areas: <itemizedlist><listitem><para> following areas: <itemizedlist>
<listitem>
<para>
<emphasis>Web/HTTP Security</emphasis> - the most complex part. Sets up the filters <emphasis>Web/HTTP Security</emphasis> - the most complex part. Sets up the filters
and related service beans used to apply the framework authentication mechanisms, to and related service beans used to apply the framework authentication mechanisms, to
secure URLs, render login and error pages and much secure URLs, render login and error pages and much more.</para>
more.</para></listitem><listitem><para> </listitem>
<listitem>
<para>
<emphasis>Business Object (Method) Security</emphasis> - options for securing the <emphasis>Business Object (Method) Security</emphasis> - options for securing the
service layer.</para></listitem><listitem><para> service layer.</para>
</listitem>
<listitem>
<para>
<emphasis>AuthenticationManager</emphasis> - handles authentication requests from <emphasis>AuthenticationManager</emphasis> - handles authentication requests from
other parts of the framework.</para></listitem><listitem><para> other parts of the framework.</para>
</listitem>
<listitem>
<para>
<emphasis>AccessDecisionManager</emphasis> - provides access decisions for web and <emphasis>AccessDecisionManager</emphasis> - provides access decisions for web and
method security. A default one will be registered, but you can also choose to use a method security. A default one will be registered, but you can also choose to use a
custom one, declared using normal Spring bean custom one, declared using normal Spring bean syntax.</para>
syntax.</para></listitem><listitem><para> </listitem>
<listitem>
<para>
<emphasis>AuthenticationProvider</emphasis>s - mechanisms against which the <emphasis>AuthenticationProvider</emphasis>s - mechanisms against which the
authentication manager authenticates users. The namespace provides supports for authentication manager authenticates users. The namespace provides supports for
several standard options and also a means of adding custom beans declared using a several standard options and also a means of adding custom beans declared using a
traditional syntax. </para></listitem><listitem><para> traditional syntax. </para>
</listitem>
<listitem>
<para>
<emphasis>UserDetailsService</emphasis> - closely related to authentication providers, <emphasis>UserDetailsService</emphasis> - closely related to authentication providers,
but often also required by other beans.</para></listitem> but often also required by other beans.</para>
</listitem>
<!-- todo: diagram and link to other sections which describe the interfaces --> <!-- todo: diagram and link to other sections which describe the interfaces -->
</itemizedlist></para> </itemizedlist></para>
<para>We'll see how these work together in the following sections.</para> <para>We'll see how to configure these in the following sections.</para>
</section> </section>
</section> </section>
<section xml:id="ns-getting-started"> <section xml:id="ns-getting-started">
@ -91,8 +107,8 @@
of the main features of the framework. Let's assume you initially want to get up and running of the main features of the framework. Let's assume you initially want to get up and running
as quickly as possible and add authentication support and access control to an existing web as quickly as possible and add authentication support and access control to an existing web
application, with a few test logins. Then we'll look at how to change over to authenticating application, with a few test logins. Then we'll look at how to change over to authenticating
against a database or other security information repository. In later sections we'll introduce against a database or other security repository. In later sections we'll introduce more
more advanced namespace configuration options. </para> advanced namespace configuration options. </para>
<section xml:id="ns-web-xml"> <section xml:id="ns-web-xml">
<title><literal>web.xml</literal> Configuration</title> <title><literal>web.xml</literal> Configuration</title>
<para> The first thing you need to do is add the following filter declaration to your <para> The first thing you need to do is add the following filter declaration to your
@ -124,12 +140,28 @@
</http> </http>
]]> ]]>
</programlisting> Which says that we want all URLs within our application to be secured, </programlisting> Which says that we want all URLs within our application to be secured,
requiring the role <literal>ROLE_USER</literal> to access them.</para> requiring the role <literal>ROLE_USER</literal> to access them. The
<literal>&lt;http></literal> element is the parent for all web-related namespace
functionality. The <literal>&lt;intercept-url></literal> element defines a
<literal>pattern</literal> which is matched against the URLs of incoming requests using an
ant path style syntax. The <literal>access</literal> attribute defines the access
requirements for requests matching the given pattern. With the default configuration, this
is typically a comma-separated list of roles, one of which a user must have to be allowed to
make the request. Access-control in Spring Security is not limited to the use of simple
roles, however, and we'll see later how the interpretation can vary<footnote>
<para>The interpretation of the comma-separated values in the <literal>access</literal>
attribute depends on the implementation of the <link xlink:href="#ns-access-manager"
>AccessDecisionManager</link> which is used. In Spring Security 3.0, the attribute can
also be populated with an <link xlink:href="#el-access">EL expression</link>.</para>
</footnote>.</para>
<note> <note>
<para>You can use multiple <literal>&lt;intercept-url&gt;</literal> elements to define <para>You can use multiple <literal>&lt;intercept-url&gt;</literal> elements to define
different access requirements for different sets of URLs, but they will be evaluated in different access requirements for different sets of URLs, but they will be evaluated in
the order listed and the first match will be used. So you must put the most specific the order listed and the first match will be used. So you must put the most specific
matches at the top.</para> matches at the top. You can also add a <literal>method</literal> attribute to limit the
match to a particular HTTP method (<literal>GET</literal>, <literal>POST</literal>,
<literal>PUT</literal> etc.). For a pattern defined both with and without a method, the
method-specific match will take precedence regardless of ordering. </para>
</note> </note>
<para> To add some users, you can define a set of test data directly in the namespace: <programlisting language="xml"><![CDATA[ <para> To add some users, you can define a set of test data directly in the namespace: <programlisting language="xml"><![CDATA[
<authentication-manager> <authentication-manager>
@ -144,10 +176,10 @@
</programlisting></para> </programlisting></para>
<sidebar> <sidebar>
<para>If you are familiar with pre-namespace versions of the framework, you can probably <para>If you are familiar with pre-namespace versions of the framework, you can probably
already guess roughly what's going on here. The &lt;http&gt; element is responsible for already guess roughly what's going on here. The <literal>&lt;http&gt;</literal> element is
creating a <classname>FilterChainProxy</classname> and the filter beans which it uses. responsible for creating a <classname>FilterChainProxy</classname> and the filter beans
Common issues like incorrect filter ordering are no longer an issue as the filter which it uses. Common problems like incorrect filter ordering are no longer an issue as
positions are predefined.</para> the filter positions are predefined.</para>
<para>The <literal>&lt;authentication-provider&gt;</literal> element creates a <para>The <literal>&lt;authentication-provider&gt;</literal> element creates a
<classname>DaoAuthenticationProvider</classname> bean and the <classname>DaoAuthenticationProvider</classname> bean and the
<literal>&lt;user-service&gt;</literal> element creates an <literal>&lt;user-service&gt;</literal> element creates an
@ -185,14 +217,15 @@
<logout /> <logout />
</http> </http>
]]></programlisting> These other elements are responsible for setting up form-login, basic ]]></programlisting> These other elements are responsible for setting up form-login, basic
authentication and logout handling services respectively <footnote><para>In versions prior authentication and logout handling services respectively <footnote>
to 3.0, this list also included remember-me functionality. This could cause some <para>In versions prior to 3.0, this list also included remember-me functionality. This
confusing errors with some configurations and was removed in 3.0. In 3.0, the addition could cause some confusing errors with some configurations and was removed in 3.0. In
of an <classname>AnonymousAuthenticationFilter</classname> is part of the default 3.0, the addition of an <classname>AnonymousAuthenticationFilter</classname> is part
<literal>&lt;http></literal> configuration, so the <literal>&lt;anonymous of the default <literal>&lt;http></literal> configuration, so the
/></literal> element is added regardless of whether <literal>auto-config</literal> <literal>&lt;anonymous /></literal> element is added regardless of whether
is enabled.</para></footnote> . They each have attributes which can be used to alter <literal>auto-config</literal> is enabled.</para>
their behaviour. </para> </footnote> . They each have attributes which can be used to alter their behaviour.
</para>
</section> </section>
<section xml:id="ns-form-and-basic"> <section xml:id="ns-form-and-basic">
<title>Form and Basic Login Options</title> <title>Form and Basic Login Options</title>
@ -213,13 +246,16 @@
</programlisting> Note that you can still use <literal>auto-config</literal>. The </programlisting> Note that you can still use <literal>auto-config</literal>. The
<literal>form-login</literal> element just overrides the default settings. Also note <literal>form-login</literal> element just overrides the default settings. Also note
that we've added an extra <literal>intercept-url</literal> element to say that any that we've added an extra <literal>intercept-url</literal> element to say that any
requests for the login page should be available to anonymous users <footnote><para>See the requests for the login page should be available to anonymous users <footnote>
chapter on <link xlink:href="#anonymous">anonymous authentication</link> for more <para>See the chapter on <link xlink:href="#anonymous">anonymous authentication</link>
details.</para></footnote>. Otherwise the request would be matched by the pattern and also the <link xlink:href="#authz-authenticated-voter">AuthenticatedVoter</link>
<literal>/**</literal> and it wouldn't be possible to access the login page itself! This class for more details on how the value
is a common configuration error and will result in an infinite loop in the application. <literal>IS_AUTHENTICATED_ANONYMOUSLY</literal> is processed.</para>
Spring Security will emit a warning in the log if your login page appears to be secured. </footnote>. Otherwise the request would be matched by the pattern <literal>/**</literal>
It is also possible to have all requests matching a particular pattern bypass the security and it wouldn't be possible to access the login page 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[ filter chain completely: <programlisting language="xml"><![CDATA[
<http auto-config='true'> <http auto-config='true'>
<intercept-url pattern="/css/**" filters="none"/> <intercept-url pattern="/css/**" filters="none"/>
@ -228,9 +264,12 @@
<form-login login-page='/login.jsp'/> <form-login login-page='/login.jsp'/>
</http> </http>
]]> ]]>
</programlisting> Note that these requests will be completely oblivious to Spring </programlisting>It's important to realise that these requests will be completely
Security, so you will not be able to access information on the current user or call oblivious to any further Spring Security web-related configuration or additional
secured methods during the request. </para> 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 you still
want the security filter chain to be applied.</para>
<para>If you want to use basic authentication instead of form login, then change the <para>If you want to use basic authentication instead of form login, then change the
configuration to <programlisting language="xml"><![CDATA[ configuration to <programlisting language="xml"><![CDATA[
<http auto-config='true'> <http auto-config='true'>
@ -282,7 +321,7 @@
</authentication-provider> </authentication-provider>
</authentication-manager> </authentication-manager>
]]> ]]>
</programlisting> Where "securityDataSource" is the name of a </programlisting> Where <quote>securityDataSource</quote> is the name of a
<classname>DataSource</classname> bean in the application context, pointing at a database <classname>DataSource</classname> bean in the application context, pointing at a database
containing the standard Spring Security <link xlink:href="#db_schema_users_authorities">user containing the standard Spring Security <link xlink:href="#db_schema_users_authorities">user
data tables</link>. Alternatively, you could configure a Spring Security data tables</link>. Alternatively, you could configure a Spring Security
@ -437,14 +476,20 @@
logs in. If you don't require this protection, or it conflicts with some other logs in. If you don't require this protection, or it conflicts with some other
requirement, you can control the behaviour using the requirement, you can control the behaviour using the
<literal>session-fixation-protection</literal> attribute on <literal>session-fixation-protection</literal> attribute on
<literal>&lt;session-management&gt;</literal>, which has three options <literal>&lt;session-management&gt;</literal>, which has three options <itemizedlist>
<itemizedlist><listitem><para><literal>migrateSession</literal> - creates a new <listitem>
session and copies the existing session attributes to the new session. This is the <para><literal>migrateSession</literal> - creates a new session and copies the
default.</para></listitem><listitem><para><literal>none</literal> - Don't do existing session attributes to the new session. This is the default.</para>
anything. The original session will be </listitem>
retained.</para></listitem><listitem><para><literal>newSession</literal> - Create <listitem>
a new "clean" session, without copying the existing session <para><literal>none</literal> - Don't do anything. The original session will be
data.</para></listitem></itemizedlist></para> retained.</para>
</listitem>
<listitem>
<para><literal>newSession</literal> - Create a new "clean" session, without copying
the existing session data.</para>
</listitem>
</itemizedlist></para>
</section> </section>
</section> </section>
<section xml:id="ns-openid"> <section xml:id="ns-openid">
@ -481,48 +526,112 @@
<para>The order of the filters is always strictly enforced when using the namespace. When the <para>The order of the filters is always strictly enforced when using the namespace. When the
application context is being created, the filter beans are sorted by the namespace handling application context is being created, the filter beans are sorted by the namespace handling
code and the standard Spring Security filters each have an alias in the namespace and a code and the standard Spring Security filters each have an alias in the namespace and a
well-known position.<note><para>In previous versions, the sorting took place after the well-known position.<note>
filter instances had been created, during post-processing of the application context. In <para>In previous versions, the sorting took place after the filter instances had been
version 3.0+ the sorting is now done at the bean metadata level, before the classes have created, during post-processing of the application context. In version 3.0+ the sorting
been instantiated. This has implications for how you add your own filters to the stack is now done at the bean metadata level, before the classes have been instantiated. This
as the entire filter list must be known during the parsing of the has implications for how you add your own filters to the stack as the entire filter list
<literal>&lt;http></literal> element, so the syntax has changed slightly in must be known during the parsing of the <literal>&lt;http></literal> element, so the
3.0.</para></note>The filters, aliases and namespace elements/attributes which create syntax has changed slightly in 3.0.</para>
the filters are shown in <xref linkend="filter-stack"/>. The filters are listed in the order </note>The filters, aliases and namespace elements/attributes which create the filters are
in which they occur in the filter chain. <table xml:id="filter-stack"><title>Standard Filter shown in <xref linkend="filter-stack"/>. The filters are listed in the order in which they
Aliases and Ordering</title><tgroup cols="3" align="left"><thead><row><entry occur in the filter chain. <table xml:id="filter-stack">
align="center">Alias</entry><entry align="center">Filter Class</entry><entry <title>Standard Filter Aliases and Ordering</title>
align="center">Namespace Element or <tgroup cols="3" align="left">
Attribute</entry></row></thead><tbody><row><entry> <thead>
CHANNEL_FILTER</entry><entry><literal>ChannelProcessingFilter</literal></entry><entry><literal>http/intercept-url@requires-channel</literal></entry></row><row><entry> <row>
CONCURRENT_SESSION_FILTER</entry><entry><literal>ConcurrentSessionFilter</literal> <entry align="center">Alias</entry>
</entry><entry><literal>session-management/concurrency-control</literal></entry></row><row><entry> <entry align="center">Filter Class</entry>
SECURITY_CONTEXT_FILTER</entry><entry><classname>SecurityContextPersistenceFilter</classname></entry><entry><literal>http</literal></entry></row><row><entry> <entry align="center">Namespace Element or Attribute</entry>
LOGOUT_FILTER </row>
</entry><entry><literal>LogoutFilter</literal></entry><entry><literal>http/logout</literal></entry></row><row><entry> </thead>
X509_FILTER <tbody>
</entry><entry><literal>X509AuthenticationFilter</literal></entry><entry><literal>http/x509</literal></entry></row><row><entry> <row>
PRE_AUTH_FILTER <entry> CHANNEL_FILTER</entry>
</entry><entry><literal>AstractPreAuthenticatedProcessingFilter</literal> <entry><literal>ChannelProcessingFilter</literal></entry>
Subclasses</entry><entry>N/A</entry></row><row><entry> CAS_FILTER <entry><literal>http/intercept-url@requires-channel</literal></entry>
</entry><entry><literal>CasAuthenticationFilter</literal></entry><entry>N/A</entry></row><row><entry> </row>
FORM_LOGIN_FILTER <row>
</entry><entry><literal>UsernamePasswordAuthenticationFilter</literal></entry><entry><literal>http/form-login</literal></entry></row><row><entry> <entry> CONCURRENT_SESSION_FILTER</entry>
BASIC_AUTH_FILTER <entry><literal>ConcurrentSessionFilter</literal>
</entry><entry><literal>BasicAuthenticationFilter</literal></entry><entry><literal>http/http-basic</literal></entry></row><row><entry> </entry>
SERVLET_API_SUPPORT_FILTER</entry><entry><literal>SecurityContextHolderAwareFilter</literal></entry><entry><literal>http/@servlet-api-provision</literal></entry></row><row><entry> <entry><literal>session-management/concurrency-control</literal></entry>
REMEMBER_ME_FILTER </row>
</entry><entry><classname>RememberMeAuthenticationFilter</classname></entry><entry><literal>http/remember-me</literal></entry></row><row><entry> <row>
ANONYMOUS_FILTER <entry> SECURITY_CONTEXT_FILTER</entry>
</entry><entry><literal>AnonymousAuthenticationFilter</literal></entry><entry><literal>http/anonymous</literal></entry></row><row><entry> <entry><classname>SecurityContextPersistenceFilter</classname></entry>
SESSION_MANAGEMENT_FILTER</entry><entry><literal>SessionManagementFilter</literal></entry><entry><literal>session-management</literal></entry></row><row><entry>EXCEPTION_TRANSLATION_FILTER <entry><literal>http</literal></entry>
</entry><entry><classname>ExceptionTranslationFilter</classname></entry><entry><literal>http</literal></entry></row><row><entry> </row>
FILTER_SECURITY_INTERCEPTOR <row>
</entry><entry><classname>FilterSecurityInterceptor</classname></entry><entry><literal>http</literal></entry></row><row><entry> <entry> LOGOUT_FILTER </entry>
SWITCH_USER_FILTER <entry><literal>LogoutFilter</literal></entry>
</entry><entry><literal>SwitchUserFilter</literal></entry><entry>N/A</entry></row></tbody></tgroup></table> <entry><literal>http/logout</literal></entry>
You can add your own filter to the stack, using the <literal>custom-filter</literal> element </row>
and one of these names to specify the position your filter should appear at: <programlisting language="xml"><![CDATA[ <row>
<entry> X509_FILTER </entry>
<entry><literal>X509AuthenticationFilter</literal></entry>
<entry><literal>http/x509</literal></entry>
</row>
<row>
<entry> PRE_AUTH_FILTER </entry>
<entry><literal>AstractPreAuthenticatedProcessingFilter</literal> Subclasses</entry>
<entry>N/A</entry>
</row>
<row>
<entry> CAS_FILTER </entry>
<entry><literal>CasAuthenticationFilter</literal></entry>
<entry>N/A</entry>
</row>
<row>
<entry> FORM_LOGIN_FILTER </entry>
<entry><literal>UsernamePasswordAuthenticationFilter</literal></entry>
<entry><literal>http/form-login</literal></entry>
</row>
<row>
<entry> BASIC_AUTH_FILTER </entry>
<entry><literal>BasicAuthenticationFilter</literal></entry>
<entry><literal>http/http-basic</literal></entry>
</row>
<row>
<entry> SERVLET_API_SUPPORT_FILTER</entry>
<entry><literal>SecurityContextHolderAwareFilter</literal></entry>
<entry><literal>http/@servlet-api-provision</literal></entry>
</row>
<row>
<entry> REMEMBER_ME_FILTER </entry>
<entry><classname>RememberMeAuthenticationFilter</classname></entry>
<entry><literal>http/remember-me</literal></entry>
</row>
<row>
<entry> ANONYMOUS_FILTER </entry>
<entry><literal>AnonymousAuthenticationFilter</literal></entry>
<entry><literal>http/anonymous</literal></entry>
</row>
<row>
<entry> SESSION_MANAGEMENT_FILTER</entry>
<entry><literal>SessionManagementFilter</literal></entry>
<entry><literal>session-management</literal></entry>
</row>
<row>
<entry>EXCEPTION_TRANSLATION_FILTER </entry>
<entry><classname>ExceptionTranslationFilter</classname></entry>
<entry><literal>http</literal></entry>
</row>
<row>
<entry> FILTER_SECURITY_INTERCEPTOR </entry>
<entry><classname>FilterSecurityInterceptor</classname></entry>
<entry><literal>http</literal></entry>
</row>
<row>
<entry> SWITCH_USER_FILTER </entry>
<entry><literal>SwitchUserFilter</literal></entry>
<entry>N/A</entry>
</row>
</tbody>
</tgroup>
</table> You can add your own filter to the stack, using the
<literal>custom-filter</literal> element and one of these names to specify the position
your filter should appear at: <programlisting language="xml"><![CDATA[
<http> <http>
<custom-filter position="FORM_LOGIN_FILTER" ref="myFilter" /> <custom-filter position="FORM_LOGIN_FILTER" ref="myFilter" />
</http> </http>
@ -569,10 +678,10 @@
<para>From version 2.0 onwards Spring Security has improved support substantially for adding <para>From version 2.0 onwards Spring Security has improved support substantially for adding
security to your service layer methods. It provides support for JSR-250 security as well as security to your service layer methods. It provides support for JSR-250 security as well as
the framework's original <literal>@Secured</literal> annotation. From 3.0 you can also make the framework's original <literal>@Secured</literal> annotation. From 3.0 you can also make
use of new <link xlink:href="el-access">expression-based annotations</link>. use of new <link xlink:href="el-access">expression-based annotations</link>. You can apply
You can apply security to a single bean, using the security to a single bean, using the <literal>intercept-methods</literal> element to decorate
<literal>intercept-methods</literal> element to decorate the bean declaration, or you can the bean declaration, or you can secure multiple beans across the entire service layer using
secure multiple beans across the entire service layer using the AspectJ style pointcuts. </para> the AspectJ style pointcuts. </para>
<section xml:id="ns-global-method"> <section xml:id="ns-global-method">
<title>The <literal>&lt;global-method-security&gt;</literal> Element</title> <title>The <literal>&lt;global-method-security&gt;</literal> Element</title>
<para> This element is used to enable annotation-based security in your application (by <para> This element is used to enable annotation-based security in your application (by
@ -639,7 +748,7 @@
<para> This section assumes you have some knowledge of the underlying architecture for <para> This section assumes you have some knowledge of the underlying architecture for
access-control within Spring Security. If you don't you can skip it and come back to it later, access-control within Spring Security. If you don't you can skip it and come back to it later,
as this section is only really relevant for people who need to do some customization in order as this section is only really relevant for people who need to do some customization in order
to use more than simple role based security. </para> to use more than simple role-based security. </para>
<para> When you use a namespace configuration, a default instance of <para> When you use a namespace configuration, a default instance of
<interfacename>AccessDecisionManager</interfacename> is automatically registered for you and <interfacename>AccessDecisionManager</interfacename> is automatically registered for you and
will be used for making access decisions for method invocations and web URL access, based on will be used for making access decisions for method invocations and web URL access, based on
@ -648,7 +757,8 @@
annotation secured methods). </para> annotation secured methods). </para>
<para> The default strategy is to use an <classname>AffirmativeBased</classname> <para> The default strategy is to use an <classname>AffirmativeBased</classname>
<interfacename>AccessDecisionManager</interfacename> with a <classname>RoleVoter</classname> <interfacename>AccessDecisionManager</interfacename> with a <classname>RoleVoter</classname>
and an <classname>AuthenticatedVoter</classname>. </para> and an <classname>AuthenticatedVoter</classname>. You can find out more about these in the
chapter on <link xlink:href="authorization">authorization</link>.</para>
<section xml:id="ns-custom-access-mgr"> <section xml:id="ns-custom-access-mgr">
<title>Customizing the AccessDecisionManager</title> <title>Customizing the AccessDecisionManager</title>
<para> If you need to use a more complicated access control strategy then it is easy to set an <para> If you need to use a more complicated access control strategy then it is easy to set an
@ -694,9 +804,9 @@
</bean> </bean>
]]></programlisting></para> ]]></programlisting></para>
<para> Another common requirement is that another bean in the context may require a reference to <para> Another common requirement is that another bean in the context may require a reference to
the <interfacename>AuthenticationManager</interfacename>. You can easily the <interfacename>AuthenticationManager</interfacename>. You can easily register an alias for
register an alias for the <interfacename>AuthenticationManager</interfacename> and the <interfacename>AuthenticationManager</interfacename> and use this name elsewhere in your
use this name elsewhere in your application context. <programlisting language="xml"><![CDATA[ application context. <programlisting language="xml"><![CDATA[
<security:authentication-manager alias="authenticationManager"> <security:authentication-manager alias="authenticationManager">
... ...
</security:authentication-manager> </security:authentication-manager>

29
docs/manual/src/docbook/remember-me-authentication.xml
View File

@ -46,7 +46,7 @@
more significant security is needed you should use the approach described in the next more significant security is needed you should use the approach described in the next
section. Alternatively remember-me services should simply not be used at all.</para> section. Alternatively remember-me services should simply not be used at all.</para>
<para>If you are familiar with the topics discussed in the chapter on <link <para>If you are familiar with the topics discussed in the chapter on <link
xlink:href="ns-config">namespace configuration</link>, you can enable remember-me xlink:href="#ns-config">namespace configuration</link>, you can enable remember-me
authentication just by adding the <literal>&lt;remember-me&gt;</literal> element: <programlisting><![CDATA[ authentication just by adding the <literal>&lt;remember-me&gt;</literal> element: <programlisting><![CDATA[
<http> <http>
... ...
@ -64,11 +64,12 @@
<para>This approach is based on the article <link <para>This approach is based on the article <link
xlink:href="http://jaspan.com/improved_persistent_login_cookie_best_practice" xlink:href="http://jaspan.com/improved_persistent_login_cookie_best_practice"
>http://jaspan.com/improved_persistent_login_cookie_best_practice</link> with some >http://jaspan.com/improved_persistent_login_cookie_best_practice</link> with some
minor modifications <footnote><para>Essentially, the username is not included in the minor modifications <footnote>
cookie, to prevent exposing a valid login name unecessarily. There is a <para>Essentially, the username is not included in the cookie, to prevent exposing a
discussion on this in the comments section of this article.</para></footnote>. valid login name unecessarily. There is a discussion on this in the comments
To use the this approach with namespace configuration, you would supply a datasource section of this article.</para>
reference: <programlisting><![CDATA[ </footnote>. To use the this approach with namespace configuration, you would supply a
datasource reference: <programlisting><![CDATA[
<http> <http>
... ...
<remember-me data-source-ref="someDataSource"/> <remember-me data-source-ref="someDataSource"/>
@ -161,12 +162,16 @@
<para> This class can be used in the same way as <para> This class can be used in the same way as
<classname>TokenBasedRememberMeServices</classname>, but it additionally needs <classname>TokenBasedRememberMeServices</classname>, but it additionally needs
to be configured with a <interfacename>PersistentTokenRepository</interfacename> to to be configured with a <interfacename>PersistentTokenRepository</interfacename> to
store the tokens. There are two standard implementations. store the tokens. There are two standard implementations. <itemizedlist>
<itemizedlist><listitem><para><classname>InMemoryTokenRepositoryImpl</classname> <listitem>
which is intended for testing <para><classname>InMemoryTokenRepositoryImpl</classname> which is intended
only.</para></listitem><listitem><para><classname>JdbcTokenRepositoryImpl</classname> for testing only.</para>
which stores the tokens in a database. </para></listitem></itemizedlist> </listitem>
The database schema is described above in <xref <listitem>
<para><classname>JdbcTokenRepositoryImpl</classname> which stores the tokens
in a database. </para>
</listitem>
</itemizedlist> The database schema is described above in <xref
linkend="remember-me-persistent-token"/>. </para> linkend="remember-me-persistent-token"/>. </para>
</section> </section>
</section> </section>

16
docs/manual/src/docbook/springsecurity.xml
View File

@ -1,12 +1,14 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<book version="5.0" xml:id="spring-security-reference-guide" xmlns="http://docbook.org/ns/docbook" <book version="5.0" xml:id="spring-security-reference-guide" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude"> xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
<info><title>Spring Security</title><subtitle>Reference <info><title>Spring Security</title><subtitle>Reference Documentation</subtitle><authorgroup>
Documentation</subtitle><authorgroup><author> <author>
<personname>Ben Alex</personname> <personname>Ben Alex</personname>
</author><author> </author>
<author>
<personname>Luke Taylor</personname> <personname>Luke Taylor</personname>
</author></authorgroup> </author>
</authorgroup>
<productname>Spring Security</productname> <productname>Spring Security</productname>
<releaseinfo>3.0.0.RC2</releaseinfo> <releaseinfo>3.0.0.RC2</releaseinfo>
</info> </info>
@ -77,9 +79,9 @@
<para> We'll also take a look at the sample applications that are available. It's worth trying <para> We'll also take a look at the sample applications that are available. It's worth trying
to run these and experimenting with them a bit even before you read the later sections - you to run these and experimenting with them a bit even before you read the later sections - you
can dip back into them as your understanding of the framework increases. Please also check can dip back into them as your understanding of the framework increases. Please also check
out the <link xlink:href="http://static.springsource.org/spring-security/site/index.html">project website</link> as out the <link xlink:href="http://static.springsource.org/spring-security/site/index.html"
it has useful information on building the project, plus links to articles, videos and tutorials. >project website</link> as it has useful information on building the project, plus links
</para> to articles, videos and tutorials. </para>
</partintro> </partintro>
<xi:include href="introduction.xml"/> <xi:include href="introduction.xml"/>
<xi:include href="namespace-config.xml"/> <xi:include href="namespace-config.xml"/>

115
docs/manual/src/docbook/technical-overview.xml
View File

@ -189,31 +189,50 @@ if (principal instanceof UserDetails) {
own proprietary authentication system. </para> own proprietary authentication system. </para>
<section> <section>
<title>What is authentication in Spring Security?</title> <title>What is authentication in Spring Security?</title>
<para> Let's consider a standard authentication scenario that everyone is familiar with. <para> Let's consider a standard authentication scenario that everyone is familiar with. <orderedlist>
<orderedlist><listitem><para>A user is prompted to log in with a username and <listitem>
password.</para></listitem><listitem><para>The system (successfully) verifies that the <para>A user is prompted to log in with a username and password.</para>
password is correct for the username.</para></listitem><listitem><para>The context </listitem>
information for that user is obtained (their list of roles and so <listitem>
on).</para></listitem><listitem><para>A security context is established for the <para>The system (successfully) verifies that the password is correct for the
user</para></listitem><listitem><para>The user proceeds, potentially to perform some username.</para>
operation which is potentially protected by an access control mechanism which checks </listitem>
the required permissions for the operation against the current security context <listitem>
information. </para></listitem></orderedlist> The first three items constitute the <para>The context information for that user is obtained (their list of roles and so
authentication process so we'll take a look at how these take place within Spring on).</para>
Security.<orderedlist><listitem><para>The username and password are obtained and </listitem>
combined into an instance of <listitem>
<para>A security context is established for the user</para>
</listitem>
<listitem>
<para>The user proceeds, potentially to perform some operation which is potentially
protected by an access control mechanism which checks the required permissions for the
operation against the current security context information. </para>
</listitem>
</orderedlist> The first three items constitute the authentication process so we'll take a
look at how these take place within Spring Security.<orderedlist>
<listitem>
<para>The username and password are obtained and combined into an instance of
<classname>UsernamePasswordAuthenticationToken</classname> (an instance of the <classname>UsernamePasswordAuthenticationToken</classname> (an instance of the
<interfacename>Authentication</interfacename> interface, which we saw <interfacename>Authentication</interfacename> interface, which we saw
earlier).</para></listitem><listitem><para>The token is passed to an instance of earlier).</para>
<interfacename>AuthenticationManager</interfacename> for </listitem>
validation.</para></listitem><listitem><para>The <listitem>
<interfacename>AuthenticationManager</interfacename> returns a fully populated <para>The token is passed to an instance of
<interfacename>AuthenticationManager</interfacename> for validation.</para>
</listitem>
<listitem>
<para>The <interfacename>AuthenticationManager</interfacename> returns a fully populated
<interfacename>Authentication</interfacename> instance on successful <interfacename>Authentication</interfacename> instance on successful
authentication.</para></listitem><listitem><para>The security context is established authentication.</para>
by calling <code>SecurityContextHolder.getContext().setAuthentication(...)</code>, </listitem>
passing in the returned authentication object.</para></listitem></orderedlist>From <listitem>
that point on, the user is considered to be authenticated. Let's look at some code as an <para>The security context is established by calling
example. <code>SecurityContextHolder.getContext().setAuthentication(...)</code>, passing in
the returned authentication object.</para>
</listitem>
</orderedlist>From that point on, the user is considered to be authenticated. Let's look at
some code as an example.
<programlisting language="java">import org.springframework.security.authentication.*; <programlisting language="java">import org.springframework.security.authentication.*;
import org.springframework.security.core.*; import org.springframework.security.core.*;
import org.springframework.security.core.authority.GrantedAuthorityImpl; import org.springframework.security.core.authority.GrantedAuthorityImpl;
@ -484,17 +503,29 @@ Successfully authenticated. Security context contains: \
<interfacename>Authentication</interfacename> if the principal has been <interfacename>Authentication</interfacename> if the principal has been
authenticated.</para> authenticated.</para>
<para><classname>AbstractSecurityInterceptor</classname> provides a consistent workflow for <para><classname>AbstractSecurityInterceptor</classname> provides a consistent workflow for
handling secure object requests, typically: <orderedlist><listitem><para>Look up the handling secure object requests, typically: <orderedlist>
<quote>configuration attributes</quote> associated with the present <listitem>
request</para></listitem><listitem><para>Submitting the secure object, current <para>Look up the <quote>configuration attributes</quote> associated with the present
request</para>
</listitem>
<listitem>
<para>Submitting the secure object, current
<interfacename>Authentication</interfacename> and configuration attributes to the <interfacename>Authentication</interfacename> and configuration attributes to the
<interfacename>AccessDecisionManager</interfacename> for an authorization <interfacename>AccessDecisionManager</interfacename> for an authorization
decision</para></listitem><listitem><para>Optionally change the decision</para>
<interfacename>Authentication</interfacename> under which the invocation takes </listitem>
place</para></listitem><listitem><para>Allow the secure object invocation to proceed <listitem>
(assuming access was granted)</para></listitem><listitem><para>Call the <para>Optionally change the <interfacename>Authentication</interfacename> under which
<interfacename>AfterInvocationManager</interfacename> if configured, once the the invocation takes place</para>
invocation has returned.</para></listitem></orderedlist></para> </listitem>
<listitem>
<para>Allow the secure object invocation to proceed (assuming access was granted)</para>
</listitem>
<listitem>
<para>Call the <interfacename>AfterInvocationManager</interfacename> if configured, once
the invocation has returned.</para>
</listitem>
</orderedlist></para>
<section xml:id="tech-intro-config-attributes"> <section xml:id="tech-intro-config-attributes">
<title>What are Configuration Attributes?</title> <title>What are Configuration Attributes?</title>
<para> A <quote>configuration attribute</quote> can be thought of as a String that has <para> A <quote>configuration attribute</quote> can be thought of as a String that has
@ -507,8 +538,16 @@ Successfully authenticated. Security context contains: \
<interfacename>SecurityMetadataSource</interfacename> which it uses to look up the <interfacename>SecurityMetadataSource</interfacename> which it uses to look up the
attributes for a secure object. Usually this configuration will be hidden from the user. attributes for a secure object. Usually this configuration will be hidden from the user.
Configuration attributes will be entered as annotations on secured methods or as access Configuration attributes will be entered as annotations on secured methods or as access
attributes on secured URLs (using the namespace <literal>&lt;intercept-url&gt;</literal> attributes on secured URLs. For example, when we saw something like
syntax).</para> <literal>&lt;intercept-url pattern='/secure/**' access='ROLE_A,ROLE_B'/></literal> in
the namespace introduction, this is saying that the configuration attributes
<literal>ROLE_A</literal> and <literal>ROLE_B</literal> apply to web requests matching
the given pattern. In practice, with the default
<interfacename>AccessDecisionManager</interfacename> configuration, this means that
anyone who has a <interfacename>GrantedAuthority</interfacename> matching either of these
two attributes will be allowed access. Strictly speaking though, they are just attributes
and the interpretation is dependent on the
<interfacename>AccessDecisionManager</interfacename> implementation.</para>
</section> </section>
<section> <section>
<title>RunAsManager</title> <title>RunAsManager</title>
@ -539,10 +578,14 @@ Successfully authenticated. Security context contains: \
or not change it in any way as it chooses.</para> or not change it in any way as it chooses.</para>
<para><classname>AbstractSecurityInterceptor</classname> and its related objects are shown <para><classname>AbstractSecurityInterceptor</classname> and its related objects are shown
in <xref linkend="abstract-security-interceptor"/>. <figure in <xref linkend="abstract-security-interceptor"/>. <figure
xml:id="abstract-security-interceptor"><title>Security interceptors and the xml:id="abstract-security-interceptor">
<quote>secure object</quote> model</title><mediaobject><imageobject> <title>Security interceptors and the <quote>secure object</quote> model</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/security-interception.png" format="PNG"/> <imagedata align="center" fileref="images/security-interception.png" format="PNG"/>
</imageobject></mediaobject></figure></para> </imageobject>
</mediaobject>
</figure></para>
</section> </section>
<section> <section>
<title>Extending the Secure Object Model</title> <title>Extending the Secure Object Model</title>

4
docs/manual/src/xsl/html-custom.xsl
View File

@ -41,11 +41,11 @@
<!-- Activate Graphics --> <!-- Activate Graphics -->
<xsl:param name="admon.graphics" select="1"/> <xsl:param name="admon.graphics" select="1"/>
<xsl:param name="admon.graphics.path">images/</xsl:param> <xsl:param name="admon.graphics.path">images/</xsl:param>
<xsl:param name="admon.graphics.extension">.gif</xsl:param> <xsl:param name="admon.graphics.extension">.png</xsl:param>
<xsl:param name="callout.graphics" select="1" /> <xsl:param name="callout.graphics" select="1" />
<xsl:param name="callout.defaultcolumn">120</xsl:param> <xsl:param name="callout.defaultcolumn">120</xsl:param>
<xsl:param name="callout.graphics.path">images/callouts/</xsl:param> <xsl:param name="callout.graphics.path">images/callouts/</xsl:param>
<xsl:param name="callout.graphics.extension">.gif</xsl:param> <xsl:param name="callout.graphics.extension">.png</xsl:param>
<xsl:param name="table.borders.with.css" select="1"/> <xsl:param name="table.borders.with.css" select="1"/>
<xsl:param name="html.stylesheet">css/manual.css</xsl:param> <xsl:param name="html.stylesheet">css/manual.css</xsl:param>

4
docs/manual/src/xsl/pdf-custom.xsl
View File

@ -28,8 +28,8 @@
<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/fo/highlight.xsl"/> <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/fo/highlight.xsl"/>
<xsl:param name="admon.graphics">'1'</xsl:param> <xsl:param name="admon.graphics">'1'</xsl:param>
<xsl:param name="admon.graphics.path">images/</xsl:param> <xsl:param name="admon.graphics.path">src/docbook/images/</xsl:param>
<xsl:param name="draft.watermark.image" select="'images/draft.png'"/> <!-- xsl:param name="draft.watermark.image" select="'images/draft.png'"/ -->
<xsl:param name="paper.type" select="'A4'"/> <xsl:param name="paper.type" select="'A4'"/>
<xsl:param name="page.margin.top" select="'1cm'"/> <xsl:param name="page.margin.top" select="'1cm'"/>