Cwikius-Spring/spring-security
1
0
Fork 0
mirror of https://github.com/spring-projects/spring-security.git synced 2025-06-29 07:12:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

Converted literals to classname/interfacename docbook tags for easier indexing

Browse Source
This commit is contained in:
Luke Taylor 2008-09-02 01:05:57 +00:00
parent 09c70bb28e
commit de379dc2ac
24 changed files with 410 additions and 410 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
src/docbkx/anon-auth-provider.xml
View File

@ -14,11 +14,11 @@
logout and home pages of an application. There are also other logout and home pages of an application. There are also other
situations where anonymous authentication would be desired, such as situations where anonymous authentication would be desired, such as
when an auditing interceptor queries the when an auditing interceptor queries the
<literal>SecurityContextHolder</literal> to identify which principal <classname>SecurityContextHolder</classname> to identify which principal
was responsible for a given operation. Such classes can be authored was responsible for a given operation. Such classes can be authored
with more robustness if they know the with more robustness if they know the
<literal>SecurityContextHolder</literal> always contains an <classname>SecurityContextHolder</classname> always contains an
<literal>Authentication</literal> object, and never <interfacename>Authentication</interfacename> object, and never
<literal>null</literal>.</para> <literal>null</literal>.</para>
</section> </section>
@ -28,8 +28,8 @@
<para>Spring Security provides three classes that together provide an <para>Spring Security provides three classes that together provide an
anonymous authentication feature. anonymous authentication feature.
<literal>AnonymousAuthenticationToken</literal> is an implementation <literal>AnonymousAuthenticationToken</literal> is an implementation
of <literal>Authentication</literal>, and stores the of <interfacename>Authentication</interfacename>, and stores the
<literal>GrantedAuthority</literal>[]s which apply to the anonymous <interfacename>GrantedAuthority</interfacename>[]s which apply to the anonymous
principal. There is a corresponding principal. There is a corresponding
<literal>AnonymousAuthenticationProvider</literal>, which is chained <literal>AnonymousAuthenticationProvider</literal>, which is chained
into the <literal>ProviderManager</literal> so that into the <literal>ProviderManager</literal> so that
@ -37,8 +37,8 @@
Finally, there is an AnonymousProcessingFilter, which is chained after Finally, there is an AnonymousProcessingFilter, which is chained after
the normal authentication mechanisms and automatically add an the normal authentication mechanisms and automatically add an
<literal>AnonymousAuthenticationToken</literal> to the <literal>AnonymousAuthenticationToken</literal> to the
<literal>SecurityContextHolder</literal> if there is no existing <classname>SecurityContextHolder</classname> if there is no existing
<literal>Authentication</literal> held there. The definition of the <interfacename>Authentication</interfacename> held there. The definition of the
filter and authentication provider appears as follows:</para> filter and authentication provider appears as follows:</para>
<para><programlisting> <para><programlisting>
@ -91,12 +91,12 @@
<literal>isAnonymous(Authentication)</literal> method, which allows <literal>isAnonymous(Authentication)</literal> method, which allows
interested classes to take into account this special type of interested classes to take into account this special type of
authentication status. The authentication status. The
<literal>ExceptionTranslationFilter</literal> uses this interface in <classname>ExceptionTranslationFilter</classname> uses this interface in
processing <literal>AccessDeniedException</literal>s. If an processing <literal>AccessDeniedException</literal>s. If an
<literal>AccessDeniedException</literal> is thrown, and the <literal>AccessDeniedException</literal> is thrown, and the
authentication is of an anonymous type, instead of throwing a 403 authentication is of an anonymous type, instead of throwing a 403
(forbidden) response, the filter will instead commence the (forbidden) response, the filter will instead commence the
<literal>AuthenticationEntryPoint</literal> so the principal can <interfacename>AuthenticationEntryPoint</interfacename> so the principal can
authenticate properly. This is a necessary distinction, otherwise authenticate properly. This is a necessary distinction, otherwise
principals would always be deemed "authenticated" and never be given principals would always be deemed "authenticated" and never be given
an opportunity to login via form, basic, digest or some other normal an opportunity to login via form, basic, digest or some other normal

136
src/docbkx/authorization-common.xml
View File

@ -5,50 +5,50 @@
<info><title>Authorities</title></info> <info><title>Authorities</title></info>
<para>As briefly mentioned in the Authentication section, all <para>As briefly mentioned in the Authentication section, all
<literal>Authentication</literal> implementations are required to <interfacename>Authentication</interfacename> implementations are required to
store an array of <literal>GrantedAuthority</literal> objects. These store an array of <interfacename>GrantedAuthority</interfacename> objects. These
represent the authorities that have been granted to the principal. The represent the authorities that have been granted to the principal. The
<literal>GrantedAuthority</literal> objects are inserted into the <interfacename>GrantedAuthority</interfacename> objects are inserted into the
<literal>Authentication</literal> object by the <interfacename>Authentication</interfacename> object by the
<literal>AuthenticationManager</literal> and are later read by <interfacename>AuthenticationManager</interfacename> and are later read by
<literal>AccessDecisionManager</literal>s when making authorization <interfacename>AccessDecisionManager</interfacename>s when making authorization
decisions.</para> decisions.</para>
<para><literal>GrantedAuthority</literal> is an interface with only <para><interfacename>GrantedAuthority</interfacename> is an interface with only
one method: one method:
<programlisting> <programlisting>
String getAuthority(); String getAuthority();
</programlisting> </programlisting>
This method allows <literal>AccessDecisionManager</literal>s to This method allows <interfacename>AccessDecisionManager</interfacename>s to
obtain a precise <literal>String</literal> representation of the obtain a precise <literal>String</literal> representation of the
<literal>GrantedAuthority</literal>. By returning a representation as <interfacename>GrantedAuthority</interfacename>. By returning a representation as
a <literal>String</literal>, a <literal>GrantedAuthority</literal> can a <literal>String</literal>, a <interfacename>GrantedAuthority</interfacename> can
be easily "read" by most <literal>AccessDecisionManager</literal>s. If be easily "read" by most <interfacename>AccessDecisionManager</interfacename>s. If
a <literal>GrantedAuthority</literal> cannot be precisely represented a <interfacename>GrantedAuthority</interfacename> cannot be precisely represented
as a <literal>String</literal>, the as a <literal>String</literal>, the
<literal>GrantedAuthority</literal> is considered "complex" and <interfacename>GrantedAuthority</interfacename> is considered "complex" and
<literal>getAuthority()</literal> must return <literal>getAuthority()</literal> must return
<literal>null</literal>.</para> <literal>null</literal>.</para>
<para>An example of a "complex" <literal>GrantedAuthority</literal> <para>An example of a "complex" <interfacename>GrantedAuthority</interfacename>
would be an implementation that stores a list of operations and would be an implementation that stores a list of operations and
authority thresholds that apply to different customer account numbers. authority thresholds that apply to different customer account numbers.
Representing this complex <literal>GrantedAuthority</literal> as a Representing this complex <interfacename>GrantedAuthority</interfacename> as a
<literal>String</literal> would be quite complex, and as a result the <literal>String</literal> would be quite complex, and as a result the
<literal>getAuthority()</literal> method should return <literal>getAuthority()</literal> method should return
<literal>null</literal>. This will indicate to any <literal>null</literal>. This will indicate to any
<literal>AccessDecisionManager</literal> that it will need to <interfacename>AccessDecisionManager</interfacename> that it will need to
specifically support the <literal>GrantedAuthority</literal> specifically support the <interfacename>GrantedAuthority</interfacename>
implementation in order to understand its contents.</para> implementation in order to understand its contents.</para>
<para>Spring Security includes one concrete <para>Spring Security includes one concrete
<literal>GrantedAuthority</literal> implementation, <interfacename>GrantedAuthority</interfacename> implementation,
<literal>GrantedAuthorityImpl</literal>. This allows any <literal>GrantedAuthorityImpl</literal>. This allows any
user-specified <literal>String</literal> to be converted into a user-specified <literal>String</literal> to be converted into a
<literal>GrantedAuthority</literal>. All <interfacename>GrantedAuthority</interfacename>. All
<literal>AuthenticationProvider</literal>s included with the security <classname>AuthenticationProvider</classname>s included with the security
architecture use <literal>GrantedAuthorityImpl</literal> to populate architecture use <literal>GrantedAuthorityImpl</literal> to populate
the <literal>Authentication</literal> object.</para> the <interfacename>Authentication</interfacename> object.</para>
</section> </section>
<section xml:id="pre-invocation"> <section xml:id="pre-invocation">
@ -64,10 +64,10 @@
<section> <section>
<title>The AccessDecisionManager</title> <title>The AccessDecisionManager</title>
<para>The <literal>AccessDecisionManager</literal> is called by the <para>The <interfacename>AccessDecisionManager</interfacename> is called by the
<literal>AbstractSecurityInterceptor</literal> and is responsible for <classname>AbstractSecurityInterceptor</classname> and is responsible for
making final access control decisions. The making final access control decisions. The
<literal>AccessDecisionManager</literal> interface contains three <interfacename>AccessDecisionManager</interfacename> interface contains three
methods: methods:
<programlisting> <programlisting>
void decide(Authentication authentication, Object secureObject, ConfigAttributeDefinition config) throws AccessDeniedException; void decide(Authentication authentication, Object secureObject, ConfigAttributeDefinition config) throws AccessDeniedException;
@ -75,33 +75,33 @@
boolean supports(Class clazz); boolean supports(Class clazz);
</programlisting> </programlisting>
As can be seen from the first method, the As can be seen from the first method, the
<literal>AccessDecisionManager</literal> is passed via method <interfacename>AccessDecisionManager</interfacename> is passed via method
parameters all information that is likely to be of value in assessing parameters all information that is likely to be of value in assessing
an authorization decision. In particular, passing the secure an authorization decision. In particular, passing the secure
<literal>Object</literal> enables those arguments contained in the <literal>Object</literal> enables those arguments contained in the
actual secure object invocation to be inspected. For example, let's actual secure object invocation to be inspected. For example, let's
assume the secure object was a <literal>MethodInvocation</literal>. It assume the secure object was a <classname>MethodInvocation</classname>. It
would be easy to query the <literal>MethodInvocation</literal> for any would be easy to query the <classname>MethodInvocation</classname> for any
<literal>Customer</literal> argument, and then implement some sort of <literal>Customer</literal> argument, and then implement some sort of
security logic in the <literal>AccessDecisionManager</literal> to security logic in the <interfacename>AccessDecisionManager</interfacename> to
ensure the principal is permitted to operate on that customer. ensure the principal is permitted to operate on that customer.
Implementations are expected to throw an Implementations are expected to throw an
<literal>AccessDeniedException</literal> if access is denied.</para> <literal>AccessDeniedException</literal> if access is denied.</para>
<para>The <literal>supports(ConfigAttribute)</literal> method is <para>The <literal>supports(ConfigAttribute)</literal> method is
called by the <literal>AbstractSecurityInterceptor</literal> at called by the <classname>AbstractSecurityInterceptor</classname> at
startup time to determine if the startup time to determine if the
<literal>AccessDecisionManager</literal> can process the passed <interfacename>AccessDecisionManager</interfacename> can process the passed
<literal>ConfigAttribute</literal>. The <literal>ConfigAttribute</literal>. The
<literal>supports(Class)</literal> method is called by a security <literal>supports(Class)</literal> method is called by a security
interceptor implementation to ensure the configured interceptor implementation to ensure the configured
<literal>AccessDecisionManager</literal> supports the type of secure <interfacename>AccessDecisionManager</interfacename> supports the type of secure
object that the security interceptor will present.</para> object that the security interceptor will present.</para>
<section> <section>
<title>Voting-Based AccessDecisionManager Implementations</title> <title>Voting-Based AccessDecisionManager Implementations</title>
<para>Whilst users can implement their own <literal>AccessDecisionManager</literal> to control all aspects of <para>Whilst users can implement their own <interfacename>AccessDecisionManager</interfacename> to control all aspects of
authorization, Spring Security includes several <literal>AccessDecisionManager</literal> implementations that are authorization, Spring Security includes several <interfacename>AccessDecisionManager</interfacename> implementations that are
based on voting. <xref linkend="authz-access-voting"/> illustrates the relevant classes.</para> based on voting. <xref linkend="authz-access-voting"/> illustrates the relevant classes.</para>
<figure xml:id="authz-access-voting"> <figure xml:id="authz-access-voting">
<title>Voting Decision Manager</title> <title>Voting Decision Manager</title>
@ -115,13 +115,13 @@
</mediaobject> </mediaobject>
</figure> </figure>
<para>Using this approach, a series of <para>Using this approach, a series of
<literal>AccessDecisionVoter</literal> implementations are polled on <interfacename>AccessDecisionVoter</interfacename> implementations are polled on
an authorization decision. The an authorization decision. The
<literal>AccessDecisionManager</literal> then decides whether or not <interfacename>AccessDecisionManager</interfacename> then decides whether or not
to throw an <literal>AccessDeniedException</literal> based on its to throw an <literal>AccessDeniedException</literal> based on its
assessment of the votes.</para> assessment of the votes.</para>
<para>The <literal>AccessDecisionVoter</literal> interface has three <para>The <interfacename>AccessDecisionVoter</interfacename> interface has three
methods: methods:
<programlisting> <programlisting>
int vote(Authentication authentication, Object object, ConfigAttributeDefinition config); int vote(Authentication authentication, Object object, ConfigAttributeDefinition config);
@ -130,7 +130,7 @@ boolean supports(Class clazz);
</programlisting> </programlisting>
Concrete implementations return an <literal>int</literal>, with Concrete implementations return an <literal>int</literal>, with
possible values being reflected in the possible values being reflected in the
<literal>AccessDecisionVoter</literal> static fields <interfacename>AccessDecisionVoter</interfacename> static fields
<literal>ACCESS_ABSTAIN</literal>, <literal>ACCESS_DENIED</literal> <literal>ACCESS_ABSTAIN</literal>, <literal>ACCESS_DENIED</literal>
and <literal>ACCESS_GRANTED</literal>. A voting implementation will and <literal>ACCESS_GRANTED</literal>. A voting implementation will
return <literal>ACCESS_ABSTAIN</literal> if it has no opinion on an return <literal>ACCESS_ABSTAIN</literal> if it has no opinion on an
@ -139,7 +139,7 @@ boolean supports(Class clazz);
<literal>ACCESS_GRANTED</literal>.</para> <literal>ACCESS_GRANTED</literal>.</para>
<para>There are three concrete <para>There are three concrete
<literal>AccessDecisionManager</literal>s provided with Spring <interfacename>AccessDecisionManager</interfacename>s provided with Spring
Security that tally the votes. The <literal>ConsensusBased</literal> Security that tally the votes. The <literal>ConsensusBased</literal>
implementation will grant or deny access based on the consensus of implementation will grant or deny access based on the consensus of
non-abstain votes. Properties are provided to control behavior in the non-abstain votes. Properties are provided to control behavior in the
@ -157,21 +157,21 @@ boolean supports(Class clazz);
abstain.</para> abstain.</para>
<para>It is possible to implement a custom <para>It is possible to implement a custom
<literal>AccessDecisionManager</literal> that tallies votes <interfacename>AccessDecisionManager</interfacename> that tallies votes
differently. For example, votes from a particular differently. For example, votes from a particular
<literal>AccessDecisionVoter</literal> might receive additional <interfacename>AccessDecisionVoter</interfacename> might receive additional
weighting, whilst a deny vote from a particular voter may have a veto weighting, whilst a deny vote from a particular voter may have a veto
effect.</para> effect.</para>
<section> <section>
<title><classname>RoleVoter</classname></title> <title><classname>RoleVoter</classname></title>
<para> <para>
The most commonly used <literal>AccessDecisionVoter</literal> The most commonly used <interfacename>AccessDecisionVoter</interfacename>
provided with Spring Security is the simple <classname>RoleVoter</classname>, which treats 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 configuration attributes as simple role names and votes to grant access if the user has been assigned
that role.</para> that role.</para>
<para>It will vote if any ConfigAttribute begins with the prefix <literal>ROLE_</literal>. <para>It will vote if any ConfigAttribute begins with the prefix <literal>ROLE_</literal>.
It will vote to grant access if there is a <literal>GrantedAuthority</literal> which returns a It will vote to grant access if there is a <interfacename>GrantedAuthority</interfacename> which returns a
<literal>String</literal> representation (via the <literal>String</literal> representation (via the
<literal>getAuthority()</literal> method) exactly equal to one or more <literal>getAuthority()</literal> method) exactly equal to one or more
<literal>ConfigAttributes</literal> starting with <literal>ConfigAttributes</literal> starting with
@ -222,7 +222,7 @@ boolean supports(Class clazz);
In the above example, you'd define In the above example, you'd define
<literal>ACL_CONTACT_READ</literal> or <literal>ACL_CONTACT_READ</literal> or
<literal>ACL_CONTACT_DELETE</literal> against some methods on a <literal>ACL_CONTACT_DELETE</literal> against some methods on a
<literal>MethodSecurityInterceptor</literal> or <classname>MethodSecurityInterceptor</classname> or
<literal>AspectJSecurityInterceptor</literal>. When those methods are <literal>AspectJSecurityInterceptor</literal>. When those methods are
invoked, the above applicable voter defined above would vote to grant invoked, the above applicable voter defined above would vote to grant
or deny access. The voter would look at the method invocation to or deny access. The voter would look at the method invocation to
@ -230,7 +230,7 @@ boolean supports(Class clazz);
<literal>sample.contact.Contact</literal>, and then pass that <literal>sample.contact.Contact</literal>, and then pass that
<literal>Contact</literal> to the <literal>AclManager</literal>. The <literal>Contact</literal> to the <literal>AclManager</literal>. The
<literal>AclManager</literal> will then return an access control list <literal>AclManager</literal> will then return an access control list
(ACL) that applies to the current <literal>Authentication</literal>. (ACL) that applies to the current <interfacename>Authentication</interfacename>.
Assuming that ACL contains one of the listed Assuming that ACL contains one of the listed
<literal>requirePermission</literal>s, the voter will vote to grant <literal>requirePermission</literal>s, the voter will vote to grant
access. If the ACL does not contain one of the permissions defined access. If the ACL does not contain one of the permissions defined
@ -252,21 +252,21 @@ boolean supports(Class clazz);
<section> <section>
<title>Custom Voters</title> <title>Custom Voters</title>
<para>It is also possible to implement a custom <para>It is also possible to implement a custom
<literal>AccessDecisionVoter</literal>. Several examples are provided <interfacename>AccessDecisionVoter</interfacename>. Several examples are provided
in Spring Security unit tests, including in Spring Security unit tests, including
<literal>ContactSecurityVoter</literal> and <literal>ContactSecurityVoter</literal> and
<literal>DenyVoter</literal>. The <literal>DenyVoter</literal>. The
<literal>ContactSecurityVoter</literal> abstains from voting decisions <literal>ContactSecurityVoter</literal> abstains from voting decisions
where a <literal>CONTACT_OWNED_BY_CURRENT_USER</literal> where a <literal>CONTACT_OWNED_BY_CURRENT_USER</literal>
<literal>ConfigAttribute</literal> is not found. If voting, it queries <literal>ConfigAttribute</literal> is not found. If voting, it queries
the <literal>MethodInvocation</literal> to extract the owner of the the <classname>MethodInvocation</classname> to extract the owner of the
<literal>Contact</literal> object that is subject of the method call. <literal>Contact</literal> object that is subject of the method call.
It votes to grant access if the <literal>Contact</literal> owner It votes to grant access if the <literal>Contact</literal> owner
matches the principal presented in the matches the principal presented in the
<literal>Authentication</literal> object. It could have just as easily <interfacename>Authentication</interfacename> object. It could have just as easily
compared the <literal>Contact</literal> owner with some compared the <literal>Contact</literal> owner with some
<literal>GrantedAuthority</literal> the <interfacename>GrantedAuthority</interfacename> the
<literal>Authentication</literal> object presented. All of this is <interfacename>Authentication</interfacename> object presented. All of this is
achieved with relatively few lines of code and demonstrates the achieved with relatively few lines of code and demonstrates the
flexibility of the authorization model.</para> flexibility of the authorization model.</para>
</section> </section>
@ -276,8 +276,8 @@ boolean supports(Class clazz);
<section xml:id="after-invocation"> <section xml:id="after-invocation">
<info><title>After Invocation Handling</title></info> <info><title>After Invocation Handling</title></info>
<para>Whilst the <literal>AccessDecisionManager</literal> is called by <para>Whilst the <interfacename>AccessDecisionManager</interfacename> is called by
the <literal>AbstractSecurityInterceptor</literal> before proceeding the <classname>AbstractSecurityInterceptor</classname> before proceeding
with the secure object invocation, some applications need a way of with the secure object invocation, some applications need a way of
modifying the object actually returned by the secure object modifying the object actually returned by the secure object
invocation. Whilst you could easily implement your own AOP concern to invocation. Whilst you could easily implement your own AOP concern to
@ -317,21 +317,21 @@ boolean supports(Class clazz);
<para>Please be aware that if you're using <para>Please be aware that if you're using
<literal>AfterInvocationManager</literal>, you will still need <literal>AfterInvocationManager</literal>, you will still need
configuration attributes that allow the configuration attributes that allow the
<literal>MethodSecurityInterceptor</literal>'s <classname>MethodSecurityInterceptor</classname>'s
<literal>AccessDecisionManager</literal> to allow an operation. If <interfacename>AccessDecisionManager</interfacename> to allow an operation. If
you're using the typical Spring Security included you're using the typical Spring Security included
<literal>AccessDecisionManager</literal> implementations, having no <interfacename>AccessDecisionManager</interfacename> implementations, having no
configuration attributes defined for a particular secure method configuration attributes defined for a particular secure method
invocation will cause each <literal>AccessDecisionVoter</literal> to invocation will cause each <interfacename>AccessDecisionVoter</interfacename> to
abstain from voting. In turn, if the abstain from voting. In turn, if the
<literal>AccessDecisionManager</literal> property <interfacename>AccessDecisionManager</interfacename> property
"<literal>allowIfAllAbstainDecisions</literal>" is "<literal>allowIfAllAbstainDecisions</literal>" is
<literal>false</literal>, an <literal>AccessDeniedException</literal> <literal>false</literal>, an <literal>AccessDeniedException</literal>
will be thrown. You may avoid this potential issue by either (i) will be thrown. You may avoid this potential issue by either (i)
setting "<literal>allowIfAllAbstainDecisions</literal>" to setting "<literal>allowIfAllAbstainDecisions</literal>" to
<literal>true</literal> (although this is generally not recommended) <literal>true</literal> (although this is generally not recommended)
or (ii) simply ensure that there is at least one configuration or (ii) simply ensure that there is at least one configuration
attribute that an <literal>AccessDecisionVoter</literal> will vote to attribute that an <interfacename>AccessDecisionVoter</interfacename> will vote to
grant access for. This latter (recommended) approach is usually grant access for. This latter (recommended) approach is usually
achieved through a <literal>ROLE_USER</literal> or achieved through a <literal>ROLE_USER</literal> or
<literal>ROLE_AUTHENTICATED</literal> configuration attribute</para> <literal>ROLE_AUTHENTICATED</literal> configuration attribute</para>
@ -357,8 +357,8 @@ boolean supports(Class clazz);
<para>Quite often, only principals with permission to read the <para>Quite often, only principals with permission to read the
<literal>Contact</literal> should be allowed to obtain it. In this <literal>Contact</literal> should be allowed to obtain it. In this
situation the <literal>AccessDecisionManager</literal> approach situation the <interfacename>AccessDecisionManager</interfacename> approach
provided by the <literal>AbstractSecurityInterceptor</literal> will provided by the <classname>AbstractSecurityInterceptor</classname> will
not suffice. This is because the identity of the not suffice. This is because the identity of the
<literal>Contact</literal> is all that is available before the <literal>Contact</literal> is all that is available before the
secure object is invoked. The secure object is invoked. The
@ -381,10 +381,10 @@ boolean supports(Class clazz);
<literal>AclEntryAfterInvocationProvider</literal>. The provider <literal>AclEntryAfterInvocationProvider</literal>. The provider
will thrown an <literal>AccessDeniedException</literal> if one of will thrown an <literal>AccessDeniedException</literal> if one of
the listed <literal>requirePermission</literal>s is not held by the the listed <literal>requirePermission</literal>s is not held by the
<literal>Authentication</literal>. The <interfacename>Authentication</interfacename>. The
<literal>AclEntryAfterInvocationProvider</literal> queries the <literal>AclEntryAfterInvocationProvider</literal> queries the
<literal>Acl</literal>Service to determine the ACL that applies for <literal>Acl</literal>Service to determine the ACL that applies for
this domain object to this <literal>Authentication</literal>.</para> this domain object to this <interfacename>Authentication</interfacename>.</para>
<para>Similar to the <para>Similar to the
<literal>AclEntryAfterInvocationProvider</literal> is <literal>AclEntryAfterInvocationProvider</literal> is
@ -410,7 +410,7 @@ boolean supports(Class clazz);
must be a <literal>Collection</literal> or array for this provider must be a <literal>Collection</literal> or array for this provider
to operate. It will remove any element if the to operate. It will remove any element if the
<literal>AclManager</literal> indicates the <literal>AclManager</literal> indicates the
<literal>Authentication</literal> does not hold one of the listed <interfacename>Authentication</interfacename> does not hold one of the listed
<literal>requirePermission</literal>s.</para> <literal>requirePermission</literal>s.</para>
<para>The Contacts sample application demonstrates these two <para>The Contacts sample application demonstrates these two
@ -437,8 +437,8 @@ boolean supports(Class clazz);
<para>Quite often, only principals with permission to read the <para>Quite often, only principals with permission to read the
<literal>Contact</literal> should be allowed to obtain it. In this <literal>Contact</literal> should be allowed to obtain it. In this
situation the <literal>AccessDecisionManager</literal> approach situation the <interfacename>AccessDecisionManager</interfacename> approach
provided by the <literal>AbstractSecurityInterceptor</literal> will provided by the <classname>AbstractSecurityInterceptor</classname> will
not suffice. This is because the identity of the not suffice. This is because the identity of the
<literal>Contact</literal> is all that is available before the <literal>Contact</literal> is all that is available before the
secure object is invoked. The secure object is invoked. The
@ -463,10 +463,10 @@ boolean supports(Class clazz);
<literal>BasicAclEntryAfterInvocationProvider</literal>. The <literal>BasicAclEntryAfterInvocationProvider</literal>. The
provider will thrown an <literal>AccessDeniedException</literal> if provider will thrown an <literal>AccessDeniedException</literal> if
one of the listed <literal>requirePermission</literal>s is not held one of the listed <literal>requirePermission</literal>s is not held
by the <literal>Authentication</literal>. The by the <interfacename>Authentication</interfacename>. The
<literal>BasicAclEntryAfterInvocationProvider</literal> queries the <literal>BasicAclEntryAfterInvocationProvider</literal> queries the
<literal>AclManager</literal> to determine the ACL that applies for <literal>AclManager</literal> to determine the ACL that applies for
this domain object to this <literal>Authentication</literal>.</para> this domain object to this <interfacename>Authentication</interfacename>.</para>
<para>Similar to the <para>Similar to the
<literal>BasicAclEntryAfterInvocationProvider</literal> is <literal>BasicAclEntryAfterInvocationProvider</literal> is
@ -492,7 +492,7 @@ boolean supports(Class clazz);
must be a <literal>Collection</literal> or array for this provider must be a <literal>Collection</literal> or array for this provider
to operate. It will remove any element if the to operate. It will remove any element if the
<literal>AclManager</literal> indicates the <literal>AclManager</literal> indicates the
<literal>Authentication</literal> does not hold one of the listed <interfacename>Authentication</interfacename> does not hold one of the listed
<literal>requirePermission</literal>s.</para> <literal>requirePermission</literal>s.</para>
<para>The Contacts sample application demonstrates these two <para>The Contacts sample application demonstrates these two
@ -505,7 +505,7 @@ boolean supports(Class clazz);
<para><literal>AuthorizeTag</literal> is used to include content if <para><literal>AuthorizeTag</literal> is used to include content if
the current principal holds certain the current principal holds certain
<literal>GrantedAuthority</literal>s.</para> <interfacename>GrantedAuthority</interfacename>s.</para>
<para>The following JSP fragment illustrates how to use the <para>The following JSP fragment illustrates how to use the
<literal>AuthorizeTag</literal>:</para> <literal>AuthorizeTag</literal>:</para>

10
src/docbkx/basic-authentication.xml
View File

@ -40,21 +40,21 @@
</programlisting></para> </programlisting></para>
<para>The configured <literal>AuthenticationManager</literal> <para>The configured <interfacename>AuthenticationManager</interfacename>
processes each authentication request. If authentication fails, the processes each authentication request. If authentication fails, the
configured <literal>AuthenticationEntryPoint</literal> will be used to configured <interfacename>AuthenticationEntryPoint</interfacename> will be used to
retry the authentication process. Usually you will use the retry the authentication process. Usually you will use the
<literal>BasicProcessingFilterEntryPoint</literal>, which returns a <literal>BasicProcessingFilterEntryPoint</literal>, which returns a
401 response with a suitable header to retry HTTP Basic 401 response with a suitable header to retry HTTP Basic
authentication. If authentication is successful, the resulting authentication. If authentication is successful, the resulting
<literal>Authentication</literal> object will be placed into the <interfacename>Authentication</interfacename> object will be placed into the
<literal>SecurityContextHolder</literal>.</para> <classname>SecurityContextHolder</classname>.</para>
<para>If the authentication event was successful, or authentication <para>If the authentication event was successful, or authentication
was not attempted because the HTTP header did not contain a supported was not attempted because the HTTP header did not contain a supported
authentication request, the filter chain will continue as normal. The authentication request, the filter chain will continue as normal. The
only time the filter chain will be interrupted is if authentication only time the filter chain will be interrupted is if authentication
fails and the <literal>AuthenticationEntryPoint</literal> is called, fails and the <interfacename>AuthenticationEntryPoint</interfacename> is called,
as discussed in the previous paragraph</para> as discussed in the previous paragraph</para>
</section> </section>
</chapter> </chapter>

38
src/docbkx/cas-auth-provider.xml
View File

@ -71,16 +71,16 @@
<listitem> <listitem>
<para>The user eventually requests a page that is either secure or <para>The user eventually requests a page that is either secure or
one of the beans it uses is secure. Spring Security's one of the beans it uses is secure. Spring Security's
<literal>ExceptionTranslationFilter</literal> will detect the <classname>ExceptionTranslationFilter</classname> will detect the
<literal>AuthenticationException</literal>.</para> <literal>AuthenticationException</literal>.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Because the user's <literal>Authentication</literal> object <para>Because the user's <interfacename>Authentication</interfacename> object
(or lack thereof) caused an (or lack thereof) caused an
<literal>AuthenticationException</literal>, the <literal>AuthenticationException</literal>, the
<literal>ExceptionTranslationFilter</literal> will call the <classname>ExceptionTranslationFilter</classname> will call the
configured <literal>AuthenticationEntryPoint</literal>. If using configured <interfacename>AuthenticationEntryPoint</interfacename>. If using
CAS, this will be the CAS, this will be the
<literal>CasProcessingFilterEntryPoint</literal> class.</para> <literal>CasProcessingFilterEntryPoint</literal> class.</para>
</listitem> </listitem>
@ -126,11 +126,11 @@
<literal>CasProcessingFilter.CAS_STATEFUL_IDENTIFIER</literal>, <literal>CasProcessingFilter.CAS_STATEFUL_IDENTIFIER</literal>,
whilst the credentials will be the service ticket opaque value. whilst the credentials will be the service ticket opaque value.
This authentication request will then be handed to the configured This authentication request will then be handed to the configured
<literal>AuthenticationManager</literal>.</para> <interfacename>AuthenticationManager</interfacename>.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>The <literal>AuthenticationManager</literal> implementation <para>The <interfacename>AuthenticationManager</interfacename> implementation
will be the <literal>ProviderManager</literal>, which is in turn will be the <literal>ProviderManager</literal>, which is in turn
configured with the <literal>CasAuthenticationProvider</literal>. configured with the <literal>CasAuthenticationProvider</literal>.
The <literal>CasAuthenticationProvider</literal> only responds to The <literal>CasAuthenticationProvider</literal> only responds to
@ -205,18 +205,18 @@
<listitem> <listitem>
<para><literal>CasAuthenticationProvider</literal> will next <para><literal>CasAuthenticationProvider</literal> will next
request a <literal>CasAuthoritiesPopulator</literal> to advise the request a <literal>CasAuthoritiesPopulator</literal> to advise the
<literal>GrantedAuthority</literal> objects that apply to the user <interfacename>GrantedAuthority</interfacename> objects that apply to the user
contained in the <literal>TicketResponse</literal>. Spring contained in the <literal>TicketResponse</literal>. Spring
Security includes a <literal>DaoCasAuthoritiesPopulator</literal> Security includes a <literal>DaoCasAuthoritiesPopulator</literal>
which simply uses the <literal>UserDetailsService</literal> which simply uses the <interfacename>UserDetailsService</interfacename>
infrastructure to find the <literal>UserDetails</literal> and infrastructure to find the <interfacename>UserDetails</interfacename> and
their associated <literal>GrantedAuthority</literal>s. Note that their associated <interfacename>GrantedAuthority</interfacename>s. Note that
the password and enabled/disabled status of the password and enabled/disabled status of
<literal>UserDetails</literal> returned by the <interfacename>UserDetails</interfacename> returned by the
<literal>UserDetailsService</literal> are ignored, as the CAS <interfacename>UserDetailsService</interfacename> are ignored, as the CAS
server is responsible for authentication decisions. server is responsible for authentication decisions.
<literal>DaoCasAuthoritiesPopulator</literal> is only concerned <literal>DaoCasAuthoritiesPopulator</literal> is only concerned
with retrieving the <literal>GrantedAuthority</literal>s.</para> with retrieving the <interfacename>GrantedAuthority</interfacename>s.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -224,7 +224,7 @@
<literal>CasAuthenticationProvider</literal> constructs a <literal>CasAuthenticationProvider</literal> constructs a
<literal>CasAuthenticationToken</literal> including the details <literal>CasAuthenticationToken</literal> including the details
contained in the <literal>TicketResponse</literal> and the contained in the <literal>TicketResponse</literal> and the
<literal>GrantedAuthority</literal>s. The <interfacename>GrantedAuthority</interfacename>s. The
<literal>CasAuthenticationToken</literal> contains the hash of a <literal>CasAuthenticationToken</literal> contains the hash of a
key, so that the <literal>CasAuthenticationProvider</literal> key, so that the <literal>CasAuthenticationProvider</literal>
knows it created it.</para> knows it created it.</para>
@ -244,12 +244,12 @@
</listitem> </listitem>
<listitem> <listitem>
<para>As the <literal>Authentication</literal> object is now in <para>As the <interfacename>Authentication</interfacename> object is now in
the well-known location, it is handled like any other the well-known location, it is handled like any other
authentication approach. Usually the authentication approach. Usually the
<literal>HttpSessionContextIntegrationFilter</literal> will be <classname>HttpSessionContextIntegrationFilter</classname> will be
used to associate the <literal>Authentication</literal> object used to associate the <interfacename>Authentication</interfacename> object
with the <literal>SecurityContextHolder</literal> for the duration with the <classname>SecurityContextHolder</classname> for the duration
of each request.</para> of each request.</para>
</listitem> </listitem>
</orderedlist> </orderedlist>
@ -323,7 +323,7 @@
<literal>CasProcessingFilter</literal> needs a reference to it.</para> <literal>CasProcessingFilter</literal> needs a reference to it.</para>
<para>For CAS to operate, the <para>For CAS to operate, the
<literal>ExceptionTranslationFilter</literal> must have its <classname>ExceptionTranslationFilter</classname> must have its
<literal>authenticationEntryPoint</literal> property set to the <literal>authenticationEntryPoint</literal> property set to the
<literal>CasProcessingFilterEntryPoint</literal> bean.</para> <literal>CasProcessingFilterEntryPoint</literal> bean.</para>

8
src/docbkx/channel-security.xml
View File

@ -66,7 +66,7 @@
<bean id="secureChannelProcessor" class="org.springframework.security.securechannel.SecureChannelProcessor"/> <bean id="secureChannelProcessor" class="org.springframework.security.securechannel.SecureChannelProcessor"/>
<bean id="insecureChannelProcessor" class="org.springframework.security.securechannel.InsecureChannelProcessor"/>]]> <bean id="insecureChannelProcessor" class="org.springframework.security.securechannel.InsecureChannelProcessor"/>]]>
</programlisting> </programlisting>
Like <literal>FilterSecurityInterceptor</literal>, Apache Ant Like <classname>FilterSecurityInterceptor</classname>, Apache Ant
style paths are also supported by the style paths are also supported by the
<literal>ChannelProcessingFilter</literal>.</para> <literal>ChannelProcessingFilter</literal>.</para>
@ -146,15 +146,15 @@
<para>To decide whether a security check belongs in a <para>To decide whether a security check belongs in a
<literal>ChannelProcessor</literal> or an <literal>ChannelProcessor</literal> or an
<literal>AccessDecisionVoter</literal>, remember that the former is <interfacename>AccessDecisionVoter</interfacename>, remember that the former is
designed to handle unauthenticated requests, whilst the latter is designed to handle unauthenticated requests, whilst the latter is
designed to handle authenticated requests. The latter therefore has designed to handle authenticated requests. The latter therefore has
access to the granted authorities of the authenticated principal. In access to the granted authorities of the authenticated principal. In
addition, problems detected by a <literal>ChannelProcessor</literal> addition, problems detected by a <literal>ChannelProcessor</literal>
will generally cause an HTTP/HTTPS redirection so its requirements can will generally cause an HTTP/HTTPS redirection so its requirements can
be met, whilst problems detected by an be met, whilst problems detected by an
<literal>AccessDecisionVoter</literal> will ultimately result in an <interfacename>AccessDecisionVoter</interfacename> will ultimately result in an
<literal>AccessDeniedException</literal> (depending on the governing <literal>AccessDeniedException</literal> (depending on the governing
<literal>AccessDecisionManager</literal>).</para> <interfacename>AccessDecisionManager</interfacename>).</para>
</section> </section>
</chapter> </chapter>

84
src/docbkx/common-auth-services.xml
View File

@ -8,8 +8,8 @@
<para>To use Spring Security's authentication services, <para>To use Spring Security's authentication services,
you'll usually need to configure a web filter, together you'll usually need to configure a web filter, together
with an <literal>AuthenticationProvider</literal> and with an <classname>AuthenticationProvider</classname> and
<literal>AuthenticationEntryPoint</literal>. In this section we are <interfacename>AuthenticationEntryPoint</interfacename>. In this section we are
going to explore an example application that needs to support both going to explore an example application that needs to support both
form-based authentication (so a nice HTML page is presented to a form-based authentication (so a nice HTML page is presented to a
user for them to login) and BASIC authentication (so a web service user for them to login) and BASIC authentication (so a web service
@ -81,8 +81,8 @@
each of these authentication mechanisms.</para> each of these authentication mechanisms.</para>
<para>Recall that <para>Recall that
<literal>HttpSessionContextIntegrationFilter</literal> keeps the <classname>HttpSessionContextIntegrationFilter</classname> keeps the
contents of the <literal>SecurityContext</literal> between invocations contents of the <interfacename>SecurityContext</interfacename> between invocations
inside an HTTP session. This means the authentication mechanisms are inside an HTTP session. This means the authentication mechanisms are
only used once, being when the principal initially tries to only used once, being when the principal initially tries to
authenticate. The rest of the time the authentication mechanisms sit authenticate. The rest of the time the authentication mechanisms sit
@ -97,13 +97,13 @@
<para>The major authorization provider for secure objects has <para>The major authorization provider for secure objects has
previously been introduced as previously been introduced as
<literal>AbstractSecurityInterceptor</literal>. This class needs to <classname>AbstractSecurityInterceptor</classname>. This class needs to
have access to an <literal>AuthenticationManager</literal>. It also have access to an <interfacename>AuthenticationManager</interfacename>. It also
has configurable settings to indicate whether an has configurable settings to indicate whether an
<literal>Authentication</literal> object should be re-authenticated on <interfacename>Authentication</interfacename> object should be re-authenticated on
each secure object invocation. By default it just accepts any each secure object invocation. By default it just accepts any
<literal>Authentication</literal> inside the <interfacename>Authentication</interfacename> inside the
<literal>SecurityContextHolder</literal> is authenticated if <classname>SecurityContextHolder</classname> is authenticated if
<literal>Authentication.isAuthenticated()</literal> returns true. This <literal>Authentication.isAuthenticated()</literal> returns true. This
is great for performance, but not ideal if you want to ensure is great for performance, but not ideal if you want to ensure
up-to-the-moment authentication validity. For such cases you'll up-to-the-moment authentication validity. For such cases you'll
@ -112,9 +112,9 @@
property to true.</para> property to true.</para>
<para>You might be asking yourself, "what's this <para>You might be asking yourself, "what's this
<literal>AuthenticationManager</literal>?". We haven't explored it <interfacename>AuthenticationManager</interfacename>?". We haven't explored it
before, but we have discussed the concept of an before, but we have discussed the concept of an
<literal>AuthenticationProvider</literal>. Quite simply, an <classname>AuthenticationProvider</classname>. Quite simply, an
<interfacename>AuthenticationManager</interfacename> is responsible <interfacename>AuthenticationManager</interfacename> is responsible
for passing requests through a chain of AuthenticationProviders. It's for passing requests through a chain of AuthenticationProviders. It's
a little like the filter chain we discussed earlier, although there a little like the filter chain we discussed earlier, although there
@ -137,11 +137,11 @@
<para>It's probably worth mentioning at this point that your <para>It's probably worth mentioning at this point that your
authentication mechanisms (which are usually filters) are also authentication mechanisms (which are usually filters) are also
injected with a reference to the injected with a reference to the
<literal>AuthenticationManager</literal>. So both <interfacename>AuthenticationManager</interfacename>. So both
<literal>AbstractSecurityInterceptor</literal> as well as the <classname>AbstractSecurityInterceptor</classname> as well as the
authentication mechanisms will use the above authentication mechanisms will use the above
<literal>ProviderManager</literal> to poll a list of <literal>ProviderManager</literal> to poll a list of
<literal>AuthenticationProvider</literal>s.</para> <classname>AuthenticationProvider</classname>s.</para>
<para>In our example we have three providers. They are tried in the <para>In our example we have three providers. They are tried in the
order shown (which is implied by the use of a <literal>List</literal> order shown (which is implied by the use of a <literal>List</literal>
@ -161,7 +161,7 @@
limited to) BASIC and form authentication. Equally, some limited to) BASIC and form authentication. Equally, some
authentication mechanisms create an authentication request object authentication mechanisms create an authentication request object
which can only be interpreted by a single type of which can only be interpreted by a single type of
<literal>AuthenticationProvider</literal>. An example of this <classname>AuthenticationProvider</classname>. An example of this
one-to-one mapping would be JA-SIG CAS, which uses the notion of a one-to-one mapping would be JA-SIG CAS, which uses the notion of a
service ticket which can therefore only be authenticated by service ticket which can therefore only be authenticated by
<literal>CasAuthenticationProvider</literal>. A further example of a <literal>CasAuthenticationProvider</literal>. A further example of a
@ -176,11 +176,11 @@
to authenticate is made.</para> to authenticate is made.</para>
<para>After configuring the correct authentication mechanisms in the <para>After configuring the correct authentication mechanisms in the
<literal>FilterChainProxy</literal>, and ensuring that a corresponding <classname>FilterChainProxy</classname>, and ensuring that a corresponding
<literal>AuthenticationProvider</literal> is registered in the <classname>AuthenticationProvider</classname> is registered in the
<literal>ProviderManager</literal>, your last step is to configure an <literal>ProviderManager</literal>, your last step is to configure an
<literal>AuthenticationEntryPoint</literal>. Recall that earlier we <interfacename>AuthenticationEntryPoint</interfacename>. Recall that earlier we
discussed the role of <literal>ExceptionTranslationFilter</literal>, discussed the role of <classname>ExceptionTranslationFilter</classname>,
which is used when HTTP-based requests should receive back an HTTP which is used when HTTP-based requests should receive back an HTTP
header or HTTP redirect in order to start authentication. Continuing header or HTTP redirect in order to start authentication. Continuing
on with our earlier example:</para> on with our earlier example:</para>
@ -202,12 +202,12 @@
<property name="forceHttps">< value="false"/> <property name="forceHttps">< value="false"/>
</bean>]]></programlisting></para> </bean>]]></programlisting></para>
<para>Notice that the <literal>ExceptionTranslationFilter</literal> <para>Notice that the <classname>ExceptionTranslationFilter</classname>
requires two collaborators. The first, requires two collaborators. The first,
<literal>AccessDeniedHandlerImpl</literal>, uses a <literal>AccessDeniedHandlerImpl</literal>, uses a
<literal>RequestDispatcher</literal> forward to display the specified <literal>RequestDispatcher</literal> forward to display the specified
access denied error page. We use a forward so that the access denied error page. We use a forward so that the
<literal>SecurityContextHolder</literal> still contains details of the <classname>SecurityContextHolder</classname> still contains details of the
principal, which may be useful for display to the user (in old principal, which may be useful for display to the user (in old
releases of Spring Security we relied upon the servlet container to releases of Spring Security we relied upon the servlet container to
handle a 403 error message, which lacked this useful contextual handle a 403 error message, which lacked this useful contextual
@ -221,7 +221,7 @@
<literal>AuthenticationProcessinFilterEntryPoint</literal> and the URL <literal>AuthenticationProcessinFilterEntryPoint</literal> and the URL
of the login page. Your application will usually only have one entry of the login page. Your application will usually only have one entry
point, and most authentication approaches define their own specific point, and most authentication approaches define their own specific
<literal>AuthenticationEntryPoint</literal>. Details of which entry <interfacename>AuthenticationEntryPoint</interfacename>. Details of which entry
point to use for each authentication approach is discussed in the point to use for each authentication approach is discussed in the
authentication approach-specific chapters of this reference authentication approach-specific chapters of this reference
guide.</para> guide.</para>
@ -233,43 +233,43 @@
<para>As mentioned in the first part of the reference guide, most <para>As mentioned in the first part of the reference guide, most
authentication providers take advantage of the authentication providers take advantage of the
<literal>UserDetails</literal> and <interfacename>UserDetails</interfacename> and
<literal>UserDetailsService</literal> interfaces. The contract for <interfacename>UserDetailsService</interfacename> interfaces. The contract for
this latter interface consists of a single method:</para> this latter interface consists of a single method:</para>
<para><programlisting> <para><programlisting>
UserDetails loadUserByUsername(String username) throws UsernameNotFoundException, DataAccessException; UserDetails loadUserByUsername(String username) throws UsernameNotFoundException, DataAccessException;
</programlisting></para> </programlisting></para>
<para>The returned <literal>UserDetails</literal> is an interface that <para>The returned <interfacename>UserDetails</interfacename> is an interface that
provides getters that guarantee non-null provision of basic provides getters that guarantee non-null provision of basic
authentication information such as the username, password, granted authentication information such as the username, password, granted
authorities and whether the user is enabled or disabled. Most authorities and whether the user is enabled or disabled. Most
authentication providers will use a authentication providers will use a
<literal>UserDetailsService</literal>, even if the username and <interfacename>UserDetailsService</interfacename>, even if the username and
password are not actually used as part of the authentication decision. password are not actually used as part of the authentication decision.
Generally such providers will be using the returned Generally such providers will be using the returned
<literal>UserDetails</literal> object just for its <interfacename>UserDetails</interfacename> object just for its
<literal>GrantedAuthority[]</literal> information, because some other <literal>GrantedAuthority[]</literal> information, because some other
system (like LDAP or X509 or CAS etc) has undertaken the system (like LDAP or X509 or CAS etc) has undertaken the
responsibility of actually validating the credentials.</para> responsibility of actually validating the credentials.</para>
<para>A single concrete implementation of <para>A single concrete implementation of
<literal>UserDetails</literal> is provided with Spring Security, being <interfacename>UserDetails</interfacename> is provided with Spring Security, being
the <literal>User</literal> class. Spring Security users will need to the <literal>User</literal> class. Spring Security users will need to
decide when writing their <literal>UserDetailsService</literal> what decide when writing their <interfacename>UserDetailsService</interfacename> what
concrete <literal>UserDetails</literal> class to return. In most cases concrete <interfacename>UserDetails</interfacename> class to return. In most cases
<literal>User</literal> will be used directly or subclassed, although <literal>User</literal> will be used directly or subclassed, although
special circumstances (such as object relational mappers) may require special circumstances (such as object relational mappers) may require
users to write their own <literal>UserDetails</literal> implementation users to write their own <interfacename>UserDetails</interfacename> implementation
from scratch. This is not such an unusual situation, and users should from scratch. This is not such an unusual situation, and users should
not hesitate to simply return their normal domain object that not hesitate to simply return their normal domain object that
represents a user of the system. This is especially common given that represents a user of the system. This is especially common given that
<literal>UserDetails</literal> is often used to store additional <interfacename>UserDetails</interfacename> is often used to store additional
principal-related properties (such as their telephone number and email principal-related properties (such as their telephone number and email
address), so that they can be easily used by web views.</para> address), so that they can be easily used by web views.</para>
<para>Given <literal>UserDetailsService</literal> is so simple to <para>Given <interfacename>UserDetailsService</interfacename> is so simple to
implement, it should be easy for users to retrieve authentication implement, it should be easy for users to retrieve authentication
information using a persistence strategy of their choice. Having said information using a persistence strategy of their choice. Having said
that, Spring Security does include a couple of useful base that, Spring Security does include a couple of useful base
@ -278,12 +278,12 @@
<section xml:id="in-memory-service"> <section xml:id="in-memory-service">
<info><title>In-Memory Authentication</title></info> <info><title>In-Memory Authentication</title></info>
<para>Whilst it is easy to use create a custom <para>Whilst it is easy to use create a custom
<literal>UserDetailsService</literal> implementation that extracts <interfacename>UserDetailsService</interfacename> implementation that extracts
information from a persistence engine of choice, many applications information from a persistence engine of choice, many applications
do not require such complexity. This is particularly true if you're do not require such complexity. This is particularly true if you're
undertaking a rapid prototype or just starting integrating Spring undertaking a rapid prototype or just starting integrating Spring
Security, when you don't really want to spend time configuring Security, when you don't really want to spend time configuring
databases or writing <literal>UserDetailsService</literal> databases or writing <interfacename>UserDetailsService</interfacename>
implementations. For this sort of situation, a simple option is to implementations. For this sort of situation, a simple option is to
use the <literal>user-service</literal> element from the security use the <literal>user-service</literal> element from the security
<link xlink:href="#namespace-minimal" >namespace</link>: <link xlink:href="#namespace-minimal" >namespace</link>:
@ -316,7 +316,7 @@
<title>JDBC Authentication</title> <title>JDBC Authentication</title>
</info> </info>
<para>Spring Security also includes a <para>Spring Security also includes a
<literal>UserDetailsService</literal> that can obtain authentication <interfacename>UserDetailsService</interfacename> that can obtain authentication
information from a JDBC data source. Internally Spring JDBC is used, information from a JDBC data source. Internally Spring JDBC is used,
so it avoids the complexity of a fully-featured object relational so it avoids the complexity of a fully-featured object relational
mapper (ORM) just to store user details. If your application does mapper (ORM) just to store user details. If your application does
@ -372,9 +372,9 @@
customisation of the SQL statements. Please refer to the JavaDocs for customisation of the SQL statements. Please refer to the JavaDocs for
details, but note that the class is not intended for complex custom subclasses. details, but note that the class is not intended for complex custom subclasses.
If you have a complex schema or would like a If you have a complex schema or would like a
custom <literal>UserDetails</literal> implementation returned, custom <interfacename>UserDetails</interfacename> implementation returned,
you'd be better off writing your own you'd be better off writing your own
<literal>UserDetailsService</literal>. The base implementation <interfacename>UserDetailsService</interfacename>. The base implementation
provided with Spring Security is intended for typical situations, provided with Spring Security is intended for typical situations,
rather than catering for all possible requirements.</para> rather than catering for all possible requirements.</para>
</section> </section>
@ -403,7 +403,7 @@
<para>In addition, you will need to add the <para>In addition, you will need to add the
<literal>org.springframework.security.concurrent.ConcurrentSessionFilter</literal> <literal>org.springframework.security.concurrent.ConcurrentSessionFilter</literal>
to your <literal>FilterChainProxy</literal>. The to your <classname>FilterChainProxy</classname>. The
<classname>ConcurrentSessionFilter</classname> requires two <classname>ConcurrentSessionFilter</classname> requires two
properties, <literal>sessionRegistry</literal>, which generally points properties, <literal>sessionRegistry</literal>, which generally points
to an instance of <literal>SessionRegistryImpl</literal>, and to an instance of <literal>SessionRegistryImpl</literal>, and
@ -446,7 +446,7 @@
<info><title>Authentication Tag Libraries</title></info> <info><title>Authentication Tag Libraries</title></info>
<para><literal>AuthenticationTag</literal> is used to simply output a <para><literal>AuthenticationTag</literal> is used to simply output a
property of the current <literal>Authentication</literal> object to the web property of the current <interfacename>Authentication</interfacename> object to the web
page.</para> page.</para>
<para>The following JSP fragment illustrates how to use the <para>The following JSP fragment illustrates how to use the
@ -456,8 +456,8 @@
<para>This tag would cause the principal's name to be output. Here we <para>This tag would cause the principal's name to be output. Here we
are assuming the <literal>Authentication.getPrincipal()</literal> is a are assuming the <literal>Authentication.getPrincipal()</literal> is a
<literal>UserDetails</literal> object, which is generally the case <interfacename>UserDetails</interfacename> object, which is generally the case
when using one of Spring Security's stadard <literal>AuthenticationProvider</literal> when using one of Spring Security's stadard <classname>AuthenticationProvider</classname>
implementations.</para> implementations.</para>
</section> </section>
</chapter> </chapter>

24
src/docbkx/container-adapters.xml
View File

@ -48,18 +48,18 @@
<para>As is always the case, the container adapter generated <para>As is always the case, the container adapter generated
<literal>Authentication</literal> object still needs to be <interfacename>Authentication</interfacename> object still needs to be
authenticated by an <literal>AuthenticationManager</literal> when authenticated by an <interfacename>AuthenticationManager</interfacename> when
requested to do so by the requested to do so by the
<literal>AbstractSecurityInterceptor</literal>. The <classname>AbstractSecurityInterceptor</classname>. The
<literal>AuthenticationManager</literal> needs to be certain the <interfacename>AuthenticationManager</interfacename> needs to be certain the
adapter-provided <literal>Authentication</literal> object is valid and adapter-provided <interfacename>Authentication</interfacename> object is valid and
was actually authenticated by a trusted adapter.</para> was actually authenticated by a trusted adapter.</para>
<para>Adapters create <literal>Authentication</literal> objects which <para>Adapters create <interfacename>Authentication</interfacename> objects which
are immutable and implement the <literal>AuthByAdapter</literal> are immutable and implement the <literal>AuthByAdapter</literal>
interface. These objects store the hash of a key that is defined by interface. These objects store the hash of a key that is defined by
the adapter. This allows the <literal>Authentication</literal> object the adapter. This allows the <interfacename>Authentication</interfacename> object
to be validated by the <literal>AuthByAdapterProvider</literal>. This to be validated by the <literal>AuthByAdapterProvider</literal>. This
authentication provider is defined as follows:</para> authentication provider is defined as follows:</para>
@ -80,13 +80,13 @@
<literal>AuthByAdapter</literal> instance that contains a hash code of <literal>AuthByAdapter</literal> instance that contains a hash code of
the key. Later, when an application calls a security interceptor the key. Later, when an application calls a security interceptor
managed resource, the <literal>AuthByAdapter</literal> instance in the managed resource, the <literal>AuthByAdapter</literal> instance in the
<literal>SecurityContext</literal> in the <interfacename>SecurityContext</interfacename> in the
<literal>SecurityContextHolder</literal> will be tested by the <classname>SecurityContextHolder</classname> will be tested by the
application's <literal>AuthByAdapterProvider</literal>. There is no application's <literal>AuthByAdapterProvider</literal>. There is no
requirement for additional authentication providers such as requirement for additional authentication providers such as
<literal>DaoAuthenticationProvider</literal> within the <literal>DaoAuthenticationProvider</literal> within the
application-specific application context, as the only type of application-specific application context, as the only type of
<literal>Authentication</literal> instance that will be presented by <interfacename>Authentication</interfacename> instance that will be presented by
the application is from the container adapter.</para> the application is from the container adapter.</para>
<para>Classloader issues are frequent with containers and the use of <para>Classloader issues are frequent with containers and the use of
@ -206,7 +206,7 @@
<para>In this configuration <literal>acegisecurity.xml</literal> <para>In this configuration <literal>acegisecurity.xml</literal>
contains the spring context definition including all the contains the spring context definition including all the
authentication manager beans. You have to bear in mind though, that authentication manager beans. You have to bear in mind though, that
<literal>SecurityContext</literal> is created and destroyed on each <interfacename>SecurityContext</interfacename> is created and destroyed on each
login request, so the login operation might become costly. login request, so the login operation might become costly.
Alternatively, the second approach is to use Spring singleton Alternatively, the second approach is to use Spring singleton
capabilities through capabilities through
@ -230,7 +230,7 @@
<para>In the above code fragment, <para>In the above code fragment,
<literal>authenticationManager</literal> is a helper property that <literal>authenticationManager</literal> is a helper property that
defines the expected name of the defines the expected name of the
<literal>AuthenticationManager</literal> in case you have several <interfacename>AuthenticationManager</interfacename> in case you have several
defined in the IoC container. The <literal>singletonId</literal> defined in the IoC container. The <literal>singletonId</literal>
property references a bean defined in a property references a bean defined in a
<literal>beanRefFactory.xml</literal> file. This file needs to be <literal>beanRefFactory.xml</literal> file. This file needs to be

22
src/docbkx/dao-auth-provider.xml
View File

@ -6,7 +6,7 @@
<info><title>Overview</title></info> <info><title>Overview</title></info>
<para>Spring Security includes a production-quality <para>Spring Security includes a production-quality
<literal>AuthenticationProvider</literal> implementation called <classname>AuthenticationProvider</classname> implementation called
<literal>DaoAuthenticationProvider</literal>. This authentication <literal>DaoAuthenticationProvider</literal>. This authentication
provider is compatible with all of the authentication mechanisms that provider is compatible with all of the authentication mechanisms that
generate a <literal>UsernamePasswordAuthenticationToken</literal>, and generate a <literal>UsernamePasswordAuthenticationToken</literal>, and
@ -43,8 +43,8 @@
<para>The <literal>PasswordEncoder</literal> and <para>The <literal>PasswordEncoder</literal> and
<literal>SaltSource</literal> are optional. A <literal>SaltSource</literal> are optional. A
<literal>PasswordEncoder</literal> provides encoding and decoding of <literal>PasswordEncoder</literal> provides encoding and decoding of
passwords presented in the <literal>UserDetails</literal> object that passwords presented in the <interfacename>UserDetails</interfacename> object that
is returned from the configured <literal>UserDetailsService</literal>. is returned from the configured <interfacename>UserDetailsService</interfacename>.
A <literal>SaltSource</literal> enables the passwords to be populated A <literal>SaltSource</literal> enables the passwords to be populated
with a "salt", which enhances the security of the passwords in the with a "salt", which enhances the security of the passwords in the
authentication repository. <literal>PasswordEncoder</literal> authentication repository. <literal>PasswordEncoder</literal>
@ -54,15 +54,15 @@
<literal>SystemWideSaltSource</literal> which encodes all passwords <literal>SystemWideSaltSource</literal> which encodes all passwords
with the same salt, and <literal>ReflectionSaltSource</literal>, which with the same salt, and <literal>ReflectionSaltSource</literal>, which
inspects a given property of the returned inspects a given property of the returned
<literal>UserDetails</literal> object to obtain the salt. Please refer <interfacename>UserDetails</interfacename> object to obtain the salt. Please refer
to the JavaDocs for further details on these optional features.</para> to the JavaDocs for further details on these optional features.</para>
<para>In addition to the properties above, the <para>In addition to the properties above, the
<literal>DaoAuthenticationProvider</literal> supports optional caching <literal>DaoAuthenticationProvider</literal> supports optional caching
of <literal>UserDetails</literal> objects. The of <interfacename>UserDetails</interfacename> objects. The
<literal>UserCache</literal> interface enables the <literal>UserCache</literal> interface enables the
<literal>DaoAuthenticationProvider</literal> to place a <literal>DaoAuthenticationProvider</literal> to place a
<literal>UserDetails</literal> object into the cache, and retrieve it <interfacename>UserDetails</interfacename> object into the cache, and retrieve it
from the cache upon subsequent authentication attempts for the same from the cache upon subsequent authentication attempts for the same
username. By default the <literal>DaoAuthenticationProvider</literal> username. By default the <literal>DaoAuthenticationProvider</literal>
uses the <literal>NullUserCache</literal>, which performs no caching. uses the <literal>NullUserCache</literal>, which performs no caching.
@ -105,19 +105,19 @@
<para>A design decision was made not to support account locking in the <para>A design decision was made not to support account locking in the
<literal>DaoAuthenticationProvider</literal>, as doing so would have <literal>DaoAuthenticationProvider</literal>, as doing so would have
increased the complexity of the <literal>UserDetailsService</literal> increased the complexity of the <interfacename>UserDetailsService</interfacename>
interface. For instance, a method would be required to increase the interface. For instance, a method would be required to increase the
count of unsuccessful authentication attempts. Such functionality count of unsuccessful authentication attempts. Such functionality
could be easily provided by leveraging the application event could be easily provided by leveraging the application event
publishing features discussed below.</para> publishing features discussed below.</para>
<para><literal>DaoAuthenticationProvider</literal> returns an <para><literal>DaoAuthenticationProvider</literal> returns an
<literal>Authentication</literal> object which in turn has its <interfacename>Authentication</interfacename> object which in turn has its
<literal>principal</literal> property set. The principal will be <literal>principal</literal> property set. The principal will be
either a <literal>String</literal> (which is essentially the username) either a <literal>String</literal> (which is essentially the username)
or a <literal>UserDetails</literal> object (which was looked up from or a <interfacename>UserDetails</interfacename> object (which was looked up from
the <literal>UserDetailsService</literal>). By default the the <interfacename>UserDetailsService</interfacename>). By default the
<literal>UserDetails</literal> is returned, as this enables <interfacename>UserDetails</interfacename> is returned, as this enables
applications to add extra properties potentially of use in applications to add extra properties potentially of use in
applications, such as the user's full name, email address etc. If applications, such as the user's full name, email address etc. If
using container adapters, or if your applications were written to using container adapters, or if your applications were written to

8
src/docbkx/digest-authentication.xml
View File

@ -107,7 +107,7 @@
</programlisting></para> </programlisting></para>
<para>The configured <literal>UserDetailsService</literal> is needed <para>The configured <interfacename>UserDetailsService</interfacename> is needed
because <literal>DigestProcessingFilter</literal> must have direct because <literal>DigestProcessingFilter</literal> must have direct
access to the clear text password of a user. Digest Authentication access to the clear text password of a user. Digest Authentication
will NOT work if you are using encoded passwords in your DAO. The DAO will NOT work if you are using encoded passwords in your DAO. The DAO
@ -121,14 +121,14 @@
calculations.</para> calculations.</para>
<para>Like <literal>BasicAuthenticationFilter</literal>, if <para>Like <literal>BasicAuthenticationFilter</literal>, if
authentication is successful an <literal>Authentication</literal> authentication is successful an <interfacename>Authentication</interfacename>
request token will be placed into the request token will be placed into the
<literal>SecurityContextHolder</literal>. If the authentication event <classname>SecurityContextHolder</classname>. If the authentication event
was successful, or authentication was not attempted because the HTTP was successful, or authentication was not attempted because the HTTP
header did not contain a Digest Authentication request, the filter header did not contain a Digest Authentication request, the filter
chain will continue as normal. The only time the filter chain will be chain will continue as normal. The only time the filter chain will be
interrupted is if authentication fails and the interrupted is if authentication fails and the
<literal>AuthenticationEntryPoint</literal> is called, as discussed in <interfacename>AuthenticationEntryPoint</interfacename> is called, as discussed in
the previous paragraph.</para> the previous paragraph.</para>
<para>Digest Authentication's RFC offers a range of additional <para>Digest Authentication's RFC offers a range of additional

32
src/docbkx/domain-acls.xml
View File

@ -15,8 +15,8 @@
<literal>org.springframework.security.acls</literal> package.</para> <literal>org.springframework.security.acls</literal> package.</para>
<para>Complex applications often will find the need to define access permissions not simply <para>Complex applications often will find the need to define access permissions not simply
at a web request or method invocation level. Instead, security decisions need to at a web request or method invocation level. Instead, security decisions need to
comprise both who (<literal>Authentication</literal>), where comprise both who (<interfacename>Authentication</interfacename>), where
(<literal>MethodInvocation</literal>) and what (<literal>SomeDomainObject</literal>). In (<classname>MethodInvocation</classname>) and what (<literal>SomeDomainObject</literal>). In
other words, authorization decisions also need to consider the actual domain object other words, authorization decisions also need to consider the actual domain object
instance subject of a method invocation.</para> instance subject of a method invocation.</para>
<para>Imagine you're designing an application for a pet clinic. There will be two main <para>Imagine you're designing an application for a pet clinic. There will be two main
@ -32,21 +32,21 @@
collection within the <literal>Customer</literal> domain object instance to collection within the <literal>Customer</literal> domain object instance to
determine which users have access. By using the determine which users have access. By using the
<literal>SecurityContextHolder.getContext().getAuthentication()</literal>, <literal>SecurityContextHolder.getContext().getAuthentication()</literal>,
you'll be able to access the <literal>Authentication</literal> you'll be able to access the <interfacename>Authentication</interfacename>
object.</para> object.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Write an <literal>AccessDecisionVoter</literal> to enforce the security <para>Write an <interfacename>AccessDecisionVoter</interfacename> to enforce the security
from the <literal>GrantedAuthority[]</literal>s stored in the from the <literal>GrantedAuthority[]</literal>s stored in the
<literal>Authentication</literal> object. This would mean your <interfacename>Authentication</interfacename> object. This would mean your
<literal>AuthenticationManager</literal> would need to populate the <interfacename>AuthenticationManager</interfacename> would need to populate the
<literal>Authentication</literal> with custom <interfacename>Authentication</interfacename> with custom
<literal>GrantedAuthority</literal>[]s representing each of the <interfacename>GrantedAuthority</interfacename>[]s representing each of the
<literal>Customer</literal> domain object instances the principal has <literal>Customer</literal> domain object instances the principal has
access to.</para> access to.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Write an <literal>AccessDecisionVoter</literal> to enforce the security <para>Write an <interfacename>AccessDecisionVoter</interfacename> to enforce the security
and open the target <literal>Customer</literal> domain object directly. This and open the target <literal>Customer</literal> domain object directly. This
would mean your voter needs access to a DAO that allows it to retrieve the would mean your voter needs access to a DAO that allows it to retrieve the
<literal>Customer</literal> object. It would then access the <literal>Customer</literal> object. It would then access the
@ -58,16 +58,16 @@
authorization checking to your business code. The main problems with this include the authorization checking to your business code. The main problems with this include the
enhanced difficulty of unit testing and the fact it would be more difficult to reuse the enhanced difficulty of unit testing and the fact it would be more difficult to reuse the
<literal>Customer</literal> authorization logic elsewhere. Obtaining the <literal>Customer</literal> authorization logic elsewhere. Obtaining the
<literal>GrantedAuthority[]</literal>s from the <literal>Authentication</literal> <literal>GrantedAuthority[]</literal>s from the <interfacename>Authentication</interfacename>
object is also fine, but will not scale to large numbers of object is also fine, but will not scale to large numbers of
<literal>Customer</literal>s. If a user might be able to access 5,000 <literal>Customer</literal>s. If a user might be able to access 5,000
<literal>Customer</literal>s (unlikely in this case, but imagine if it were a popular <literal>Customer</literal>s (unlikely in this case, but imagine if it were a popular
vet for a large Pony Club!) the amount of memory consumed and time required to construct vet for a large Pony Club!) the amount of memory consumed and time required to construct
the <literal>Authentication</literal> object would be undesirable. The final method, the <interfacename>Authentication</interfacename> object would be undesirable. The final method,
opening the <literal>Customer</literal> directly from external code, is probably the opening the <literal>Customer</literal> directly from external code, is probably the
best of the three. It achieves separation of concerns, and doesn't misuse memory or CPU best of the three. It achieves separation of concerns, and doesn't misuse memory or CPU
cycles, but it is still inefficient in that both the cycles, but it is still inefficient in that both the
<literal>AccessDecisionVoter</literal> and the eventual business method itself will <interfacename>AccessDecisionVoter</interfacename> and the eventual business method itself will
perform a call to the DAO responsible for retrieving the <literal>Customer</literal> perform a call to the DAO responsible for retrieving the <literal>Customer</literal>
object. Two accesses per method invocation is clearly undesirable. In addition, with object. Two accesses per method invocation is clearly undesirable. In addition, with
every approach listed you'll need to write your own access control list (ACL) every approach listed you'll need to write your own access control list (ACL)
@ -119,8 +119,8 @@
system ("SID" stands for "security identity"). The only columns are the ID, system ("SID" stands for "security identity"). The only columns are the ID,
a textual representation of the SID, and a flag to indicate whether the a textual representation of the SID, and a flag to indicate whether the
textual representation refers to a prncipal name or a textual representation refers to a prncipal name or a
<literal>GrantedAuthority</literal>. Thus, there is a single row for <interfacename>GrantedAuthority</interfacename>. Thus, there is a single row for
each unique principal or <literal>GrantedAuthority</literal>. When used in each unique principal or <interfacename>GrantedAuthority</interfacename>. When used in
the context of receiving a permission, a SID is generally called a the context of receiving a permission, a SID is generally called a
"recipient".</para> "recipient".</para>
</listitem> </listitem>
@ -193,7 +193,7 @@
<literal>GrantedAuthority[]</literal>s. A level of indirection is provided <literal>GrantedAuthority[]</literal>s. A level of indirection is provided
by the <literal>Sid</literal> interface, which is an abbreviation of "security by the <literal>Sid</literal> interface, which is an abbreviation of "security
identity". Common classes include <literal>PrincipalSid</literal> (to represent identity". Common classes include <literal>PrincipalSid</literal> (to represent
the principal inside an <literal>Authentication</literal> object) and the principal inside an <interfacename>Authentication</interfacename> object) and
<literal>GrantedAuthoritySid</literal>. The security identity information is <literal>GrantedAuthoritySid</literal>. The security identity information is
stored in the ACL_SID table.</para> stored in the ACL_SID table.</para>
</listitem> </listitem>
@ -289,7 +289,7 @@ aclService.updateAcl(acl);
<para>Once you've used the above techniques to store some ACL information in the database, <para>Once you've used the above techniques to store some ACL information in the database,
the next step is to actually use the ACL information as part of authorization decision the next step is to actually use the ACL information as part of authorization decision
logic. You have a number of choices here. You could write your own logic. You have a number of choices here. You could write your own
<literal>AccessDecisionVoter</literal> or <literal>AfterInvocationProvider</literal> <interfacename>AccessDecisionVoter</interfacename> or <literal>AfterInvocationProvider</literal>
that respectively fires before or after a method invocation. Such classes would use that respectively fires before or after a method invocation. Such classes would use
<literal>AclService</literal> to retrieve the relevant ACL and then call <literal>AclService</literal> to retrieve the relevant ACL and then call
<literal>Acl.isGranted(Permission[] permission, Sid[] sids, boolean <literal>Acl.isGranted(Permission[] permission, Sid[] sids, boolean

10
src/docbkx/form-authentication.xml
View File

@ -30,7 +30,7 @@
</bean> ]]> </bean> ]]>
</programlisting></para> </programlisting></para>
<para>The configured <literal>AuthenticationManager</literal> <para>The configured <interfacename>AuthenticationManager</interfacename>
processes each authentication request. If authentication fails, the processes each authentication request. If authentication fails, the
browser will be redirected to the browser will be redirected to the
<literal>authenticationFailureUrl</literal>. The <literal>authenticationFailureUrl</literal>. The
@ -40,15 +40,15 @@
enabling a reason to be provided to the user on the error page.</para> enabling a reason to be provided to the user on the error page.</para>
<para>If authentication is successful, the resulting <para>If authentication is successful, the resulting
<literal>Authentication</literal> object will be placed into the <interfacename>Authentication</interfacename> object will be placed into the
<literal>SecurityContextHolder</literal>.</para> <classname>SecurityContextHolder</classname>.</para>
<para>Once the <literal>SecurityContextHolder</literal> has been <para>Once the <classname>SecurityContextHolder</classname> has been
updated, the browser will need to be redirected to the target URL which updated, the browser will need to be redirected to the target URL which
is usually indicated by the <literal>HttpSession</literal> attribute stored under is usually indicated by the <literal>HttpSession</literal> attribute stored under
<literal>AbstractProcessingFilter.SPRING_SECURITY_TARGET_URL_KEY</literal>. <literal>AbstractProcessingFilter.SPRING_SECURITY_TARGET_URL_KEY</literal>.
This attribute is automatically set by the This attribute is automatically set by the
<literal>ExceptionTranslationFilter</literal> when an <classname>ExceptionTranslationFilter</classname> when an
<literal>AuthenticationException</literal> occurs, so that after login <literal>AuthenticationException</literal> occurs, so that after login
is completed the user can return to what they were originally trying to access. is completed the user can return to what they were originally trying to access.
If for some reason the <literal>HttpSession</literal> does not If for some reason the <literal>HttpSession</literal> does not

10
src/docbkx/jaas-auth-provider.xml
View File

@ -64,7 +64,7 @@ JAASTest {
mechanism). Thus, by the time the authentication request is mechanism). Thus, by the time the authentication request is
delegated through to JAAS, Spring Security's authentication delegated through to JAAS, Spring Security's authentication
mechanism will already have fully-populated an mechanism will already have fully-populated an
<literal>Authentication</literal> object containing all the <interfacename>Authentication</interfacename> object containing all the
information required by the JAAS information required by the JAAS
<literal>LoginModule</literal>.</para> <literal>LoginModule</literal>.</para>
@ -97,9 +97,9 @@ JAASTest {
<para>JAAS works with principals. Even "roles" are represented as <para>JAAS works with principals. Even "roles" are represented as
principals in JAAS. Spring Security, on the other hand, works with principals in JAAS. Spring Security, on the other hand, works with
<literal>Authentication</literal> objects. Each <interfacename>Authentication</interfacename> objects. Each
<literal>Authentication</literal> object contains a single <interfacename>Authentication</interfacename> object contains a single
principal, and multiple <literal>GrantedAuthority</literal>[]s. To principal, and multiple <interfacename>GrantedAuthority</interfacename>[]s. To
facilitate mapping between these different concepts, Spring facilitate mapping between these different concepts, Spring
Security's JAAS package includes an Security's JAAS package includes an
<literal>AuthorityGranter</literal> interface.</para> <literal>AuthorityGranter</literal> interface.</para>
@ -109,7 +109,7 @@ JAASTest {
<literal>String</literal>. The <literal>String</literal>. The
<literal>JaasAuthenticationProvider</literal> then creates a <literal>JaasAuthenticationProvider</literal> then creates a
<literal>JaasGrantedAuthority</literal> (which implements Spring <literal>JaasGrantedAuthority</literal> (which implements Spring
Security’s <literal>GrantedAuthority</literal> interface) containing Security’s <interfacename>GrantedAuthority</interfacename> interface) containing
both the <literal>AuthorityGranter</literal>-returned both the <literal>AuthorityGranter</literal>-returned
<literal>String</literal> and the JAAS principal that the <literal>String</literal> and the JAAS principal that the
<literal>AuthorityGranter</literal> was passed. The <literal>AuthorityGranter</literal> was passed. The

2
src/docbkx/ldap-auth-provider.xml
View File

@ -396,7 +396,7 @@
property. The authenticator would then call the search object to obtain the correct property. The authenticator would then call the search object to obtain the correct
user's DN before attempting to bind as this user.</para> user's DN before attempting to bind as this user.</para>
</section> </section>
<section> <section xml:id="ldap-custom-user-details">
<title>LDAP Attributes and Customized UserDetails</title> <title>LDAP Attributes and Customized UserDetails</title>
<para> <para>
The net result of an authentication using <classname>LdapAuthenticationProvider</classname> is the The net result of an authentication using <classname>LdapAuthenticationProvider</classname> is the

20
src/docbkx/namespace-config.xml
View File

@ -496,7 +496,7 @@
</row> </row>
<row> <row>
<entry> SESSION_CONTEXT_INTEGRATION_FILTER</entry> <entry> SESSION_CONTEXT_INTEGRATION_FILTER</entry>
<entry><literal>HttpSessionContextIntegrationFilter</literal></entry> <entry><classname>HttpSessionContextIntegrationFilter</classname></entry>
<entry><literal>http</literal></entry> <entry><literal>http</literal></entry>
</row> </row>
<row> <row>
@ -536,7 +536,7 @@
</row> </row>
<row> <row>
<entry> REMEMBER_ME_FILTER </entry> <entry> REMEMBER_ME_FILTER </entry>
<entry><literal>RememberMeProcessingFilter</literal></entry> <entry><classname>RememberMeProcessingFilter</classname></entry>
<entry><literal>http/remember-me</literal></entry> <entry><literal>http/remember-me</literal></entry>
</row> </row>
<row> <row>
@ -546,7 +546,7 @@
</row> </row>
<row> <row>
<entry> EXCEPTION_TRANSLATION_FILTER </entry> <entry> EXCEPTION_TRANSLATION_FILTER </entry>
<entry><literal>ExceptionTranslationFilter</literal></entry> <entry><classname>ExceptionTranslationFilter</classname></entry>
<entry><literal>http</literal></entry> <entry><literal>http</literal></entry>
</row> </row>
<row> <row>
@ -556,7 +556,7 @@
</row> </row>
<row> <row>
<entry> FILTER_SECURITY_INTERCEPTOR </entry> <entry> FILTER_SECURITY_INTERCEPTOR </entry>
<entry><literal>FilterSecurityInterceptor</literal></entry> <entry><classname>FilterSecurityInterceptor</classname></entry>
<entry><literal>http</literal></entry> <entry><literal>http</literal></entry>
</row> </row>
<row> <row>
@ -587,8 +587,8 @@
</para> </para>
<para> <para>
Note that you can't replace filters which are created by the use of the <literal>&lt;http&gt;</literal> Note that you can't replace filters which are created by the use of the <literal>&lt;http&gt;</literal>
element itself - <literal>HttpSessionContextIntegrationFilter</literal>, <literal>ExceptionTranslationFilter</literal> or element itself - <classname>HttpSessionContextIntegrationFilter</classname>, <classname>ExceptionTranslationFilter</classname> or
<literal>FilterSecurityInterceptor</literal>. <classname>FilterSecurityInterceptor</classname>.
</para> </para>
</tip> </tip>
<para> <para>
@ -596,11 +596,11 @@
an attempt by an unauthenticated user to access to a secured resource), you will need to add a custom entry point bean too. an attempt by an unauthenticated user to access to a secured resource), you will need to add a custom entry point bean too.
</para> </para>
<section xml:id="ns-entry-point-ref"> <section xml:id="ns-entry-point-ref">
<title>Setting a Custom <literal>AuthenticationEntryPoint</literal></title> <title>Setting a Custom <interfacename>AuthenticationEntryPoint</interfacename></title>
<para> <para>
If you aren't using form login, OpenID or basic authentication through the namespace, you may If you aren't using form login, OpenID or basic authentication through the namespace, you may
want to define an authentication filter and entry point using a traditional bean syntax and link them want to define an authentication filter and entry point using a traditional bean syntax and link them
into the namespace, as we've just seen. The corresponding <literal>AuthenticationEntryPoint</literal> can be set using the into the namespace, as we've just seen. The corresponding <interfacename>AuthenticationEntryPoint</interfacename> can be set using the
<literal>entry-point-ref</literal> attribute on the <literal>&lt;http&gt;</literal> element. <literal>entry-point-ref</literal> attribute on the <literal>&lt;http&gt;</literal> element.
</para> </para>
<para> <para>
@ -763,9 +763,9 @@
<para> <para>
We've touched on the idea that the namespace configuration automatically registers an authentication manager bean for We've touched on the idea that the namespace configuration automatically registers an authentication manager bean for
you. This is an instance of Spring Security's <classname>ProviderManager</classname> class, which you may already you. This is an instance of Spring Security's <classname>ProviderManager</classname> class, which you may already
be familiar with if you've used the framework before. You can't use a custom <literal>AuthenticationProvider</literal> if you are be familiar with if you've used the framework before. You can't use a custom <classname>AuthenticationProvider</classname> if you are
using either HTTP or method security through the namespace, but this should not be a problem as you have full control over using either HTTP or method security through the namespace, but this should not be a problem as you have full control over
the <literal>AuthenticationProvider</literal>s that are used. the <classname>AuthenticationProvider</classname>s that are used.
</para> </para>
<para> <para>
You may want to register additional <classname>AuthenticationProvider</classname> beans with the <classname>ProviderManager</classname> You may want to register additional <classname>AuthenticationProvider</classname> beans with the <classname>ProviderManager</classname>

2
src/docbkx/preauth.xml
View File

@ -112,7 +112,7 @@
<section> <section>
<title>PreAuthenticatedProcessingFilterEntryPoint</title> <title>PreAuthenticatedProcessingFilterEntryPoint</title>
<para> <para>
The <literal>AuthenticationEntryPoint</literal> was discussed in the <link xlink:href="#tech-auth-entry-point">technical The <interfacename>AuthenticationEntryPoint</interfacename> was discussed in the <link xlink:href="#tech-auth-entry-point">technical
overview</link> chapter. Normally it is responsible for kick-starting the authentication process for an unauthenticated user overview</link> chapter. Normally it is responsible for kick-starting the authentication process for an unauthenticated user
(when they try to access a protected resource), but in the pre-authenticated case this doesn't apply. You would only (when they try to access a protected resource), but in the pre-authenticated case this doesn't apply. You would only
configure the <classname>ExceptionTranslationFilter</classname> with an instance of this class if you aren't configure the <classname>ExceptionTranslationFilter</classname> with an instance of this class if you aren't

16
src/docbkx/remember-me-authentication.xml
View File

@ -95,7 +95,7 @@
<literal>AuthenticationProcessingFilter</literal>, and is implemented <literal>AuthenticationProcessingFilter</literal>, and is implemented
via hooks in the <literal>AbstractProcessingFilter</literal> via hooks in the <literal>AbstractProcessingFilter</literal>
superclass. The hooks will invoke a concrete superclass. The hooks will invoke a concrete
<literal>RememberMeServices</literal> at the appropriate times. The <interfacename>RememberMeServices</interfacename> at the appropriate times. The
interface looks like this: interface looks like this:
<programlisting> <programlisting>
Authentication autoLogin(HttpServletRequest request, HttpServletResponse response); Authentication autoLogin(HttpServletRequest request, HttpServletResponse response);
@ -107,9 +107,9 @@
<literal>AbstractProcessingFilter</literal> only calls the <literal>AbstractProcessingFilter</literal> only calls the
<literal>loginFail()</literal> and <literal>loginSuccess()</literal> <literal>loginFail()</literal> and <literal>loginSuccess()</literal>
methods. The <literal>autoLogin()</literal> method is called by methods. The <literal>autoLogin()</literal> method is called by
<literal>RememberMeProcessingFilter</literal> whenever the <classname>RememberMeProcessingFilter</classname> whenever the
<literal>SecurityContextHolder</literal> does not contain an <classname>SecurityContextHolder</classname> does not contain an
<literal>Authentication</literal>. This interface therefore provides <interfacename>Authentication</interfacename>. This interface therefore provides
the underlying remember-me implementation with sufficient the underlying remember-me implementation with sufficient
notification of authentication-related events, and delegates to the notification of authentication-related events, and delegates to the
implementation whenever a candidate web request might contain a cookie implementation whenever a candidate web request might contain a cookie
@ -130,7 +130,7 @@
UserDetailsService from which it can retrieve the username and UserDetailsService from which it can retrieve the username and
password for signature comparison purposes, and generate the password for signature comparison purposes, and generate the
<literal>RememberMeAuthenticationToken</literal> to contain the <literal>RememberMeAuthenticationToken</literal> to contain the
correct <literal>GrantedAuthority</literal>[]s. Some sort of logout correct <interfacename>GrantedAuthority</interfacename>[]s. Some sort of logout
command should be provided by the application that invalidates the cookie if command should be provided by the application that invalidates the cookie if
the user requests this. <classname>TokenBasedRememberMeServices</classname> also implements Spring Security's the user requests this. <classname>TokenBasedRememberMeServices</classname> also implements Spring Security's
<interfacename>LogoutHandler</interfacename> interface so can be used with <classname>LogoutFilter</classname> <interfacename>LogoutHandler</interfacename> interface so can be used with <classname>LogoutFilter</classname>
@ -155,13 +155,13 @@
</bean> </bean>
]]> ]]>
</programlisting>Don't forget to add your </programlisting>Don't forget to add your
<literal>RememberMeServices</literal> implementation to your <interfacename>RememberMeServices</interfacename> implementation to your
<literal>AuthenticationProcessingFilter.setRememberMeServices()</literal> <literal>AuthenticationProcessingFilter.setRememberMeServices()</literal>
property, include the property, include the
<literal>RememberMeAuthenticationProvider</literal> in your <literal>RememberMeAuthenticationProvider</literal> in your
<literal>AuthenticationManager.setProviders()</literal> list, and add <literal>AuthenticationManager.setProviders()</literal> list, and add
<literal>RememberMeProcessingFilter</literal> into your <classname>RememberMeProcessingFilter</classname> into your
<literal>FilterChainProxy</literal> (typically immediately after your <classname>FilterChainProxy</classname> (typically immediately after your
<literal>AuthenticationProcessingFilter</literal>).</para> <literal>AuthenticationProcessingFilter</literal>).</para>
</section> </section>
<section> <section>

36
src/docbkx/runas-auth-provider.xml
View File

@ -4,27 +4,27 @@
<section xml:id="runas-overview"> <section xml:id="runas-overview">
<info><title>Overview</title></info> <info><title>Overview</title></info>
<para>The <literal>AbstractSecurityInterceptor</literal> is able to <para>The <classname>AbstractSecurityInterceptor</classname> is able to
temporarily replace the <literal>Authentication</literal> object in temporarily replace the <interfacename>Authentication</interfacename> object in
the <literal>SecurityContext</literal> and the <interfacename>SecurityContext</interfacename> and
<literal>SecurityContextHolder</literal> during the secure object <classname>SecurityContextHolder</classname> during the secure object
callback phase. This only occurs if the original callback phase. This only occurs if the original
<literal>Authentication</literal> object was successfully processed by <interfacename>Authentication</interfacename> object was successfully processed by
the <literal>AuthenticationManager</literal> and the <interfacename>AuthenticationManager</interfacename> and
<literal>AccessDecisionManager</literal>. The <interfacename>AccessDecisionManager</interfacename>. The
<literal>RunAsManager</literal> will indicate the replacement <literal>RunAsManager</literal> will indicate the replacement
<literal>Authentication</literal> object, if any, that should be used <interfacename>Authentication</interfacename> object, if any, that should be used
during the <literal>SecurityInterceptorCallback</literal>.</para> during the <literal>SecurityInterceptorCallback</literal>.</para>
<para>By temporarily replacing the <literal>Authentication</literal> <para>By temporarily replacing the <interfacename>Authentication</interfacename>
object during the secure object callback phase, the secured invocation object during the secure object callback phase, the secured invocation
will be able to call other objects which require different will be able to call other objects which require different
authentication and authorization credentials. It will also be able to authentication and authorization credentials. It will also be able to
perform any internal security checks for specific perform any internal security checks for specific
<literal>GrantedAuthority</literal> objects. Because Spring Security <interfacename>GrantedAuthority</interfacename> objects. Because Spring Security
provides a number of helper classes that automatically configure provides a number of helper classes that automatically configure
remoting protocols based on the contents of the remoting protocols based on the contents of the
<literal>SecurityContextHolder</literal>, these run-as replacements <classname>SecurityContextHolder</classname>, these run-as replacements
are particularly useful when calling remote web services</para> are particularly useful when calling remote web services</para>
</section> </section>
@ -38,12 +38,12 @@
</programlisting> </programlisting>
</para> </para>
<para>The first method returns the <literal>Authentication</literal> <para>The first method returns the <interfacename>Authentication</interfacename>
object that should replace the existing object that should replace the existing
<literal>Authentication</literal> object for the duration of the <interfacename>Authentication</interfacename> object for the duration of the
method invocation. If the method returns <literal>null</literal>, it method invocation. If the method returns <literal>null</literal>, it
indicates no replacement should be made. The second method is used by indicates no replacement should be made. The second method is used by
the <literal>AbstractSecurityInterceptor</literal> as part of its the <classname>AbstractSecurityInterceptor</classname> as part of its
startup validation of configuration attributes. The startup validation of configuration attributes. The
<literal>supports(Class)</literal> method is called by a security <literal>supports(Class)</literal> method is called by a security
interceptor implementation to ensure the configured interceptor implementation to ensure the configured
@ -59,7 +59,7 @@
<literal>ConfigAttribute</literal> is found, the replacement <literal>ConfigAttribute</literal> is found, the replacement
<literal>RunAsUserToken</literal> will contain the same principal, <literal>RunAsUserToken</literal> will contain the same principal,
credentials and granted authorities as the original credentials and granted authorities as the original
<literal>Authentication</literal> object, along with a new <interfacename>Authentication</interfacename> object, along with a new
<literal>GrantedAuthorityImpl</literal> for each <literal>GrantedAuthorityImpl</literal> for each
<literal>RUN_AS_</literal> <literal>ConfigAttribute</literal>. Each <literal>RUN_AS_</literal> <literal>ConfigAttribute</literal>. Each
new <literal>GrantedAuthorityImpl</literal> will be prefixed with new <literal>GrantedAuthorityImpl</literal> will be prefixed with
@ -70,10 +70,10 @@
<literal>ROLE_RUN_AS_SERVER</literal> granted authority.</para> <literal>ROLE_RUN_AS_SERVER</literal> granted authority.</para>
<para>The replacement <literal>RunAsUserToken</literal> is just like <para>The replacement <literal>RunAsUserToken</literal> is just like
any other <literal>Authentication</literal> object. It needs to be any other <interfacename>Authentication</interfacename> object. It needs to be
authenticated by the <literal>AuthenticationManager</literal>, authenticated by the <interfacename>AuthenticationManager</interfacename>,
probably via delegation to a suitable probably via delegation to a suitable
<literal>AuthenticationProvider</literal>. The <classname>AuthenticationProvider</classname>. The
<literal>RunAsImplAuthenticationProvider</literal> performs such <literal>RunAsImplAuthenticationProvider</literal> performs such
authentication. It simply accepts as valid any authentication. It simply accepts as valid any
<literal>RunAsUserToken</literal> presented.</para> <literal>RunAsUserToken</literal> presented.</para>

2
src/docbkx/samples.xml
View File

@ -92,7 +92,7 @@
currently logged on user are displayed, and only users with currently logged on user are displayed, and only users with
<literal>ROLE_SUPERVISOR</literal> are granted access to delete their <literal>ROLE_SUPERVISOR</literal> are granted access to delete their
contacts. Behind the scenes, the contacts. Behind the scenes, the
<literal>MethodSecurityInterceptor</literal> is securing the business <classname>MethodSecurityInterceptor</classname> is securing the business
objects. </para> objects. </para>
<para>The application allows you to modify the access control lists associated <para>The application allows you to modify the access control lists associated
with different contacts. Be sure to give this a try and understand how with different contacts. Be sure to give this a try and understand how

54
src/docbkx/secured-objects.xml
View File

@ -7,7 +7,7 @@
</info> </info>
<para> <para>
Prior to Spring Security 2.0, securing <literal>MethodInvocation</literal>s needed quite a Prior to Spring Security 2.0, securing <classname>MethodInvocation</classname>s needed quite a
lot of boiler plate configuration. Now the recommended approach for method security lot of boiler plate configuration. Now the recommended approach for method security
is to use <link xlink:href="#ns-method-security">namespace configuration</link>. is to use <link xlink:href="#ns-method-security">namespace configuration</link>.
This way the method security infrastructure beans are configured automatically for you so you don't really need to This way the method security infrastructure beans are configured automatically for you so you don't really need to
@ -67,7 +67,7 @@
security interceptors in the same application, with security interceptors in the same application, with
<literal>AspectJSecurityInterceptor</literal> being used for domain <literal>AspectJSecurityInterceptor</literal> being used for domain
object instance security and the AOP Alliance object instance security and the AOP Alliance
<literal>MethodSecurityInterceptor</literal> being used for services <classname>MethodSecurityInterceptor</classname> being used for services
layer security.</para> layer security.</para>
<para>Let's first consider how the <para>Let's first consider how the
@ -92,11 +92,11 @@
<literal>AspectJSecurityInterceptor</literal> is exactly the same as <literal>AspectJSecurityInterceptor</literal> is exactly the same as
the AOP Alliance security interceptor. Indeed the two interceptors can the AOP Alliance security interceptor. Indeed the two interceptors can
share the same <literal>objectDefinitionSource</literal>, as the share the same <literal>objectDefinitionSource</literal>, as the
<literal>ObjectDefinitionSource</literal> works with <interfacename>ObjectDefinitionSource</interfacename> works with
<literal>java.lang.reflect.Method</literal>s rather than an AOP <literal>java.lang.reflect.Method</literal>s rather than an AOP
library-specific class. Of course, your access decisions have access library-specific class. Of course, your access decisions have access
to the relevant AOP library-specific invocation (ie to the relevant AOP library-specific invocation (ie
<literal>MethodInvocation</literal> or <literal>JoinPoint</literal>) <classname>MethodInvocation</classname> or <literal>JoinPoint</literal>)
and as such can consider a range of addition criteria when making and as such can consider a range of addition criteria when making
access decisions (such as method arguments).</para> access decisions (such as method arguments).</para>
@ -178,7 +178,7 @@ public void afterPropertiesSet() throws Exception {
<info><title>FilterInvocation Security Interceptor</title></info> <info><title>FilterInvocation Security Interceptor</title></info>
<para>To secure <classname>FilterInvocation</classname>s, developers need <para>To secure <classname>FilterInvocation</classname>s, developers need
to add a <literal>FilterSecurityInterceptor</literal> to their filter chain. to add a <classname>FilterSecurityInterceptor</classname> to their filter chain.
A typical configuration example is provided below:</para> A typical configuration example is provided below:</para>
<para>In the application context you will need to configure three <para>In the application context you will need to configure three
@ -217,43 +217,43 @@ public void afterPropertiesSet() throws Exception {
the filter will call the AuthenticationEntryPoint to commence the the filter will call the AuthenticationEntryPoint to commence the
authentication process (e.g. a user login).</para> authentication process (e.g. a user login).</para>
<para>The <literal>AuthenticationEntryPoint</literal> will be called <para>The <interfacename>AuthenticationEntryPoint</interfacename> will be called
if the user requests a secure HTTP resource but they are not if the user requests a secure HTTP resource but they are not
authenticated. The class handles presenting the appropriate response authenticated. The class handles presenting the appropriate response
to the user so that authentication can begin. Three concrete to the user so that authentication can begin. Three concrete
implementations are provided with Spring Security: implementations are provided with Spring Security:
<literal>AuthenticationProcessingFilterEntryPoint</literal> for <classname>AuthenticationProcessingFilterEntryPoint</classname> for
commencing a form-based authentication, commencing a form-based authentication,
<literal>BasicProcessingFilterEntryPoint</literal> for commencing a <literal>BasicProcessingFilterEntryPoint</literal> for commencing a
HTTP Basic authentication process, and HTTP Basic authentication process, and
<literal>CasProcessingFilterEntryPoint</literal> for commencing a <literal>CasProcessingFilterEntryPoint</literal> for commencing a
JA-SIG Central Authentication Service (CAS) login. The JA-SIG Central Authentication Service (CAS) login. The
<literal>AuthenticationProcessingFilterEntryPoint</literal> and <classname>AuthenticationProcessingFilterEntryPoint</classname> and
<literal>CasProcessingFilterEntryPoint</literal> have optional <literal>CasProcessingFilterEntryPoint</literal> have optional
properties related to forcing the use of HTTPS, so please refer to the properties related to forcing the use of HTTPS, so please refer to the
JavaDocs if you require this.</para> JavaDocs if you require this.</para>
<para><literal>FilterSecurityInterceptor</literal> is responsible for <para><classname>FilterSecurityInterceptor</classname> is responsible for
handling the security of HTTP resources. Like any other security handling the security of HTTP resources. Like any other security
interceptor, it requires a reference to an interceptor, it requires a reference to an
<literal>AuthenticationManager</literal> and an <interfacename>AuthenticationManager</interfacename> and an
<literal>AccessDecisionManager</literal>, which are both discussed in <interfacename>AccessDecisionManager</interfacename>, which are both discussed in
separate sections below. The separate sections below. The
<literal>FilterSecurityInterceptor</literal> is also configured with <classname>FilterSecurityInterceptor</classname> is also configured with
configuration attributes that apply to different HTTP URL requests. A configuration attributes that apply to different HTTP URL requests. A
full discussion of configuration attributes is provided in the High full discussion of configuration attributes is provided in the High
Level Design section of this document.</para> Level Design section of this document.</para>
<para>The <literal>FilterSecurityInterceptor</literal> can be <para>The <classname>FilterSecurityInterceptor</classname> can be
configured with configuration attributes in two ways. The first, configured with configuration attributes in two ways. The first,
which is shown above, is using the <literal>&lt;filter-invocation-definition-source&gt;</literal> which is shown above, is using the <literal>&lt;filter-invocation-definition-source&gt;</literal>
namespace element. This is similar to the <literal>&lt;filter-chain-map&gt;</literal> namespace element. This is similar to the <literal>&lt;filter-chain-map&gt;</literal>
used to configure a <literal>FilterChainProxy</literal> but the <literal>&lt;intercept-url&gt;</literal> used to configure a <classname>FilterChainProxy</classname> but the <literal>&lt;intercept-url&gt;</literal>
child elements only use the <literal>pattern</literal> and <literal>access</literal> attributes. child elements only use the <literal>pattern</literal> and <literal>access</literal> attributes.
The second is by writing your own The second is by writing your own
<literal>ObjectDefinitionSource</literal>, although this is beyond the <interfacename>ObjectDefinitionSource</interfacename>, although this is beyond the
scope of this document. Irrespective of the approach used, the scope of this document. Irrespective of the approach used, the
<literal>ObjectDefinitionSource</literal> is responsible for returning <interfacename>ObjectDefinitionSource</interfacename> is responsible for returning
a <literal>ConfigAttributeDefinition</literal> object that contains a <literal>ConfigAttributeDefinition</literal> object that contains
all of the configuration attributes associated with a single secure all of the configuration attributes associated with a single secure
HTTP URL.</para> HTTP URL.</para>
@ -261,24 +261,24 @@ public void afterPropertiesSet() throws Exception {
<para>It should be noted that the <para>It should be noted that the
<literal>FilterSecurityInterceptor.setObjectDefinitionSource()</literal> <literal>FilterSecurityInterceptor.setObjectDefinitionSource()</literal>
method actually expects an instance of method actually expects an instance of
<literal>FilterInvocationDefinitionSource</literal>. This is a marker <interfacename>FilterInvocationDefinitionSource</interfacename>. This is a marker
interface which subclasses <literal>ObjectDefinitionSource</literal>. interface which subclasses <interfacename>ObjectDefinitionSource</interfacename>.
It simply denotes the <literal>ObjectDefinitionSource</literal> It simply denotes the <interfacename>ObjectDefinitionSource</interfacename>
understands <literal>FilterInvocation</literal>s. In the interests of understands <classname>FilterInvocation</classname>s. In the interests of
simplicity we'll continue to refer to the simplicity we'll continue to refer to the
<literal>FilterInvocationDefinitionSource</literal> as an <interfacename>FilterInvocationDefinitionSource</interfacename> as an
<literal>ObjectDefinitionSource</literal>, as the distinction is of <interfacename>ObjectDefinitionSource</interfacename>, as the distinction is of
little relevance to most users of the little relevance to most users of the
<literal>FilterSecurityInterceptor</literal>.</para> <classname>FilterSecurityInterceptor</classname>.</para>
<para>When using the namespace option to configure the interceptor, <para>When using the namespace option to configure the interceptor,
commas are used to delimit the different configuration commas are used to delimit the different configuration
attributes that apply to each HTTP URL. Each configuration attribute attributes that apply to each HTTP URL. Each configuration attribute
is assigned into its own <literal>SecurityConfig</literal> object. The is assigned into its own <literal>SecurityConfig</literal> object. The
<literal>SecurityConfig</literal> object is discussed in the High <literal>SecurityConfig</literal> object is discussed in the High
Level Design section. The <literal>ObjectDefinitionSource</literal> Level Design section. The <interfacename>ObjectDefinitionSource</interfacename>
created by the property editor, created by the property editor,
<literal>FilterInvocationDefinitionSource</literal>, matches <interfacename>FilterInvocationDefinitionSource</interfacename>, matches
configuration attributes against <literal>FilterInvocations</literal> configuration attributes against <literal>FilterInvocations</literal>
based on expression evaluation of the request URL. Two standard based on expression evaluation of the request URL. Two standard
expression syntaxes are supported. The default is to treat all expression syntaxes are supported. The default is to treat all
@ -317,10 +317,10 @@ public void afterPropertiesSet() throws Exception {
<para>As with other security interceptors, the <para>As with other security interceptors, the
<literal>validateConfigAttributes</literal> property is observed. When <literal>validateConfigAttributes</literal> property is observed. When
set to <literal>true</literal> (the default), at startup time the set to <literal>true</literal> (the default), at startup time the
<literal>FilterSecurityInterceptor</literal> will evaluate if the <classname>FilterSecurityInterceptor</classname> will evaluate if the
provided configuration attributes are valid. It does this by checking provided configuration attributes are valid. It does this by checking
each configuration attribute can be processed by either the each configuration attribute can be processed by either the
<literal>AccessDecisionManager</literal> or the <interfacename>AccessDecisionManager</interfacename> or the
<literal>RunAsManager</literal>. If neither of these can process a <literal>RunAsManager</literal>. If neither of these can process a
given configuration attribute, an exception is thrown.</para> given configuration attribute, an exception is thrown.</para>
</section> </section>

8
src/docbkx/siteminder-auth-provider.xml
View File

@ -49,7 +49,7 @@
&lt;/bean&gt;</programlisting></para> &lt;/bean&gt;</programlisting></para>
<para>In our example above, the bean is being provided an <para>In our example above, the bean is being provided an
<literal>AuthenticationManager</literal>, as is normally needed by <interfacename>AuthenticationManager</interfacename>, as is normally needed by
authentication mechanisms. Several URLs are also specified, with the authentication mechanisms. Several URLs are also specified, with the
values being self-explanatory. It's important to also specify the HTTP values being self-explanatory. It's important to also specify the HTTP
header that Spring Security should inspect. If you additionally want header that Spring Security should inspect. If you additionally want
@ -61,15 +61,15 @@
<literal>SiteminderAuthenticationProvider</literal> <literal>SiteminderAuthenticationProvider</literal>
configured against your <literal>ProviderManager</literal> in order to configured against your <literal>ProviderManager</literal> in order to
use the Siteminder authentication mechanism. Normally an use the Siteminder authentication mechanism. Normally an
<literal>AuthenticationProvider</literal> expects the password <classname>AuthenticationProvider</classname> expects the password
property to match what it retrieves from the property to match what it retrieves from the
<literal>UserDetailsSource</literal>, but in this case, authentication <literal>UserDetailsSource</literal>, but in this case, authentication
has already been handled by Siteminder, so password property is not has already been handled by Siteminder, so password property is not
even relevant. This may sound like a security weakness, but remember even relevant. This may sound like a security weakness, but remember
that users have to authenticate with Siteminder before your that users have to authenticate with Siteminder before your
application ever receives the requests, so the purpose of your custom application ever receives the requests, so the purpose of your custom
<literal>UserDetailsService</literal> should simply be to build the <interfacename>UserDetailsService</interfacename> should simply be to build the
complete <literal>Authentication</literal> object (ie with suitable complete <interfacename>Authentication</interfacename> object (ie with suitable
<literal>GrantedAuthority[]</literal>s).</para> <literal>GrantedAuthority[]</literal>s).</para>
<para>Advanced tip and word to the wise: If you additionally want to <para>Advanced tip and word to the wise: If you additionally want to

4
src/docbkx/springsecurity.xml
View File

@ -150,7 +150,7 @@
in the <link xlink:href="#technical-overview">Technical Overview</link> chapter. in the <link xlink:href="#technical-overview">Technical Overview</link> chapter.
In this part of the reference guide we will examine individual In this part of the reference guide we will examine individual
authentication mechanisms and their corresponding authentication mechanisms and their corresponding
<literal>AuthenticationProvider</literal>s. We'll also look at how to <classname>AuthenticationProvider</classname>s. We'll also look at how to
configure authentication more generally, including if you have several configure authentication more generally, including if you have several
authentication approaches that need to be chained together.</para> authentication approaches that need to be chained together.</para>
<para> <para>
@ -213,7 +213,7 @@
in a consistent and simple way.</para> in a consistent and simple way.</para>
<para>In this part we'll explore the different <para>In this part we'll explore the different
<literal>AbstractSecurityInterceptor</literal> implementations, which <classname>AbstractSecurityInterceptor</classname> implementations, which
were introduced in Part I. We then move on to explore how to fine-tune were introduced in Part I. We then move on to explore how to fine-tune
authorization through use of domain access control lists.</para> authorization through use of domain access control lists.</para>
</partintro> </partintro>

64
src/docbkx/supporting-infrastructure.xml
View File

@ -86,7 +86,7 @@
are using your own customized versions of classes.</para> are using your own customized versions of classes.</para>
<para>In this case, you have a choice in how these filters are added to your web application, in that you can use either <para>In this case, you have a choice in how these filters are added to your web application, in that you can use either
Spring's <literal>DelegatingFilterProxy</literal> or Spring's <literal>DelegatingFilterProxy</literal> or
<literal>FilterChainProxy</literal>. We'll look at both below.</para> <classname>FilterChainProxy</classname>. We'll look at both below.</para>
<para>When using <literal>DelegatingFilterProxy</literal>, you will see <para>When using <literal>DelegatingFilterProxy</literal>, you will see
something like this in the web.xml file: something like this in the web.xml file:
@ -135,14 +135,14 @@
for more information</para> for more information</para>
<para>Rather than using <literal>DelegatingFilterProxy</literal>, we <para>Rather than using <literal>DelegatingFilterProxy</literal>, we
strongly recommend that you use <literal>FilterChainProxy</literal> instead. strongly recommend that you use <classname>FilterChainProxy</classname> instead.
Whilst <literal>DelegatingFilterProxy</literal> is a very useful class, Whilst <literal>DelegatingFilterProxy</literal> is a very useful class,
the problem is that the number of lines of code required for the problem is that the number of lines of code required for
<literal>&lt;filter&gt;</literal> and <literal>&lt;filter&gt;</literal> and
<literal>&lt;filter-mapping&gt;</literal> entries in <literal>&lt;filter-mapping&gt;</literal> entries in
<literal>web.xml</literal> explodes when using more than a few <literal>web.xml</literal> explodes when using more than a few
filters. To overcome this issue, Spring Security provides a filters. To overcome this issue, Spring Security provides a
<literal>FilterChainProxy</literal> class. It is wired using a <classname>FilterChainProxy</classname> class. It is wired using a
<literal>DelegatingFilterProxy</literal> (just like in the example above), <literal>DelegatingFilterProxy</literal> (just like in the example above),
but the target class is but the target class is
<literal>org.springframework.security.util.FilterChainProxy</literal>. <literal>org.springframework.security.util.FilterChainProxy</literal>.
@ -162,9 +162,9 @@
</programlisting></para> </programlisting></para>
<para>You may notice similarities with the way <para>You may notice similarities with the way
<literal>FilterSecurityInterceptor</literal> is declared. Both regular <classname>FilterSecurityInterceptor</classname> is declared. Both regular
expressions and Ant Paths are supported, and the most specific URIs expressions and Ant Paths are supported, and the most specific URIs
appear first. At runtime the <literal>FilterChainProxy</literal> will appear first. At runtime the <classname>FilterChainProxy</classname> will
locate the first URI pattern that matches the current web request and the list locate the first URI pattern that matches the current web request and the list
of filter beans specified by the <literal>filters</literal> attribute of filter beans specified by the <literal>filters</literal> attribute
will be applied to that request. The filters will be invoked in the order will be applied to that request. The filters will be invoked in the order
@ -172,28 +172,28 @@
which is applied to a particular URL.</para> which is applied to a particular URL.</para>
<para>You may have noticed we have declared two <para>You may have noticed we have declared two
<literal>HttpSessionContextIntegrationFilter</literal>s in the filter <classname>HttpSessionContextIntegrationFilter</classname>s in the filter
chain (<literal>ASC</literal> is short for chain (<literal>ASC</literal> is short for
<literal>allowSessionCreation</literal>, a property of <literal>allowSessionCreation</literal>, a property of
<literal>HttpSessionContextIntegrationFilter</literal>). As web <classname>HttpSessionContextIntegrationFilter</classname>). As web
services will never present a <literal>jsessionid</literal> on future services will never present a <literal>jsessionid</literal> on future
requests, creating <literal>HttpSession</literal>s for such user requests, creating <literal>HttpSession</literal>s for such user
agents would be wasteful. If you had a high-volume application which agents would be wasteful. If you had a high-volume application which
required maximum scalability, we recommend you use the approach shown required maximum scalability, we recommend you use the approach shown
above. For smaller applications, using a single above. For smaller applications, using a single
<literal>HttpSessionContextIntegrationFilter</literal> (with its <classname>HttpSessionContextIntegrationFilter</classname> (with its
default <literal>allowSessionCreation</literal> as default <literal>allowSessionCreation</literal> as
<literal>true</literal>) would likely be sufficient.</para> <literal>true</literal>) would likely be sufficient.</para>
<para>In relation to lifecycle issues, the <para>In relation to lifecycle issues, the
<literal>FilterChainProxy</literal> will always delegate <classname>FilterChainProxy</classname> will always delegate
<literal>init(FilterConfig)</literal> and <literal>destroy()</literal> <literal>init(FilterConfig)</literal> and <literal>destroy()</literal>
methods through to the underlaying <literal>Filter</literal>s if such methods through to the underlaying <literal>Filter</literal>s if such
methods are called against <literal>FilterChainProxy</literal> itself. methods are called against <classname>FilterChainProxy</classname> itself.
In this case, <literal>FilterChainProxy</literal> guarantees to only In this case, <classname>FilterChainProxy</classname> guarantees to only
initialize and destroy each <literal>Filter</literal> once, initialize and destroy each <literal>Filter</literal> once,
irrespective of how many times it is declared by the irrespective of how many times it is declared by the
<literal>FilterInvocationDefinitionSource</literal>. You control the <interfacename>FilterInvocationDefinitionSource</interfacename>. You control the
overall choice as to whether these methods are called or not via the overall choice as to whether these methods are called or not via the
<literal>targetFilterLifecycle</literal> initialization parameter of the <literal>targetFilterLifecycle</literal> initialization parameter of the
<literal>DelegatingFilterProxy</literal> that proxies <literal>DelegatingFilterProxy</literal> that proxies
@ -222,17 +222,17 @@
<listitem> <listitem>
<para><literal>ConcurrentSessionFilter</literal>, because it <para><literal>ConcurrentSessionFilter</literal>, because it
doesn't use any <literal>SecurityContextHolder</literal> doesn't use any <classname>SecurityContextHolder</classname>
functionality but needs to update the functionality but needs to update the
<literal>SessionRegistry</literal> to reflect ongoing requests <interfacename>SessionRegistry</interfacename> to reflect ongoing requests
from the principal</para> from the principal</para>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>HttpSessionContextIntegrationFilter</literal>, so a <para><classname>HttpSessionContextIntegrationFilter</classname>, so a
<literal>SecurityContext</literal> can be setup in the <interfacename>SecurityContext</interfacename> can be setup in the
<literal>SecurityContextHolder</literal> at the beginning of a web <classname>SecurityContextHolder</classname> at the beginning of a web
request, and any changes to the <literal>SecurityContext</literal> request, and any changes to the <interfacename>SecurityContext</interfacename>
can be copied to the <literal>HttpSession</literal> when the web can be copied to the <literal>HttpSession</literal> when the web
request ends (ready for use with the next web request)</para> request ends (ready for use with the next web request)</para>
</listitem> </listitem>
@ -243,8 +243,8 @@
<literal>CasProcessingFilter</literal>, <literal>CasProcessingFilter</literal>,
<literal>BasicProcessingFilter, HttpRequestIntegrationFilter, <literal>BasicProcessingFilter, HttpRequestIntegrationFilter,
JbossIntegrationFilter</literal> etc - so that the JbossIntegrationFilter</literal> etc - so that the
<literal>SecurityContextHolder</literal> can be modified to <classname>SecurityContextHolder</classname> can be modified to
contain a valid <literal>Authentication</literal> request contain a valid <interfacename>Authentication</interfacename> request
token</para> token</para>
</listitem> </listitem>
@ -257,46 +257,46 @@
</listitem> </listitem>
<listitem> <listitem>
<para><literal>RememberMeProcessingFilter</literal>, so that if no <para><classname>RememberMeProcessingFilter</classname>, so that if no
earlier authentication processing mechanism updated the earlier authentication processing mechanism updated the
<literal>SecurityContextHolder</literal>, and the request presents <classname>SecurityContextHolder</classname>, and the request presents
a cookie that enables remember-me services to take place, a a cookie that enables remember-me services to take place, a
suitable remembered suitable remembered
<literal>Authentication</literal> object will <interfacename>Authentication</interfacename> object will
be put there</para> be put there</para>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>AnonymousProcessingFilter</literal>, so that if no <para><literal>AnonymousProcessingFilter</literal>, so that if no
earlier authentication processing mechanism updated the earlier authentication processing mechanism updated the
<literal>SecurityContextHolder</literal>, an anonymous <classname>SecurityContextHolder</classname>, an anonymous
<literal>Authentication</literal> object will be put there</para> <interfacename>Authentication</interfacename> object will be put there</para>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>ExceptionTranslationFilter</literal>, to catch any <para><classname>ExceptionTranslationFilter</classname>, to catch any
Spring Security exceptions so that either an HTTP error response Spring Security exceptions so that either an HTTP error response
can be returned or an appropriate can be returned or an appropriate
<literal>AuthenticationEntryPoint</literal> can be launched</para> <interfacename>AuthenticationEntryPoint</interfacename> can be launched</para>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>FilterSecurityInterceptor</literal>, to protect web <para><classname>FilterSecurityInterceptor</classname>, to protect web
URIs</para> URIs</para>
</listitem> </listitem>
</orderedlist> </orderedlist>
<para>All of the above filters use <para>All of the above filters use
<literal>DelegatingFilterProxy</literal> or <literal>DelegatingFilterProxy</literal> or
<literal>FilterChainProxy</literal>. It is recommended that a single <classname>FilterChainProxy</classname>. It is recommended that a single
<literal>DelegatingFilterProxy</literal> proxy through to a single <literal>DelegatingFilterProxy</literal> proxy through to a single
<literal>FilterChainProxy</literal> for each application, with that <classname>FilterChainProxy</classname> for each application, with that
<literal>FilterChainProxy</literal> defining all of Spring Security <classname>FilterChainProxy</classname> defining all of Spring Security
filters.</para> filters.</para>
<para>If you're using SiteMesh, ensure Spring Security filters execute <para>If you're using SiteMesh, ensure Spring Security filters execute
before the SiteMesh filters are called. This enables the before the SiteMesh filters are called. This enables the
<literal>SecurityContextHolder</literal> to be populated in time for <classname>SecurityContextHolder</classname> to be populated in time for
use by SiteMesh decorators</para> use by SiteMesh decorators</para>
</section> </section>

210
src/docbkx/technical-overview.xml
View File

@ -45,10 +45,10 @@
SecurityContextHolder, SecurityContext and Authentication Objects SecurityContextHolder, SecurityContext and Authentication Objects
</title> </title>
<para>The most fundamental object is <para>The most fundamental object is
<literal>SecurityContextHolder</literal>. This is where we store <classname>SecurityContextHolder</classname>. This is where we store
details of the present security context of the application, which details of the present security context of the application, which
includes details of the principal currently using the application. By includes details of the principal currently using the application. By
default the <literal>SecurityContextHolder</literal> uses a default the <classname>SecurityContextHolder</classname> uses a
<literal>ThreadLocal</literal> to store these details, which means <literal>ThreadLocal</literal> to store these details, which means
that the security context is always available to methods in the same that the security context is always available to methods in the same
thread of execution, even if the security context is not explicitly thread of execution, even if the security context is not explicitly
@ -70,17 +70,17 @@
You can change the mode from the default You can change the mode from the default
<literal>SecurityContextHolder.MODE_THREADLOCAL</literal> in two ways. <literal>SecurityContextHolder.MODE_THREADLOCAL</literal> in two ways.
The first is to set a system property. Alternatively, call a static The first is to set a system property. Alternatively, call a static
method on <literal>SecurityContextHolder</literal>. Most applications method on <classname>SecurityContextHolder</classname>. Most applications
won't need to change from the default, but if you do, take a look at won't need to change from the default, but if you do, take a look at
the JavaDocs for <literal>SecurityContextHolder</literal> to learn the JavaDocs for <classname>SecurityContextHolder</classname> to learn
more.</para> more.</para>
<para>Inside the <literal>SecurityContextHolder</literal> we store <para>Inside the <classname>SecurityContextHolder</classname> we store
details of the principal currently interacting with the application. details of the principal currently interacting with the application.
Spring Security uses an <literal>Authentication</literal> object to Spring Security uses an <interfacename>Authentication</interfacename> object to
represent this information. Whilst you won't normally need to create represent this information. Whilst you won't normally need to create
an <literal>Authentication</literal> object yourself, it is fairly an <interfacename>Authentication</interfacename> object yourself, it is fairly
common for users to query the <literal>Authentication</literal> common for users to query the <interfacename>Authentication</interfacename>
object. You can use the following code block - from anywhere in your object. You can use the following code block - from anywhere in your
application - to obtain the name of the authenticated user, for example:</para> application - to obtain the name of the authenticated user, for example:</para>
@ -95,14 +95,14 @@ if (obj instanceof UserDetails) {
<para>The above code introduces a number of interesting relationships <para>The above code introduces a number of interesting relationships
and key objects. First, you will notice that there is an intermediate and key objects. First, you will notice that there is an intermediate
object between <literal>SecurityContextHolder</literal> and object between <classname>SecurityContextHolder</classname> and
<literal>Authentication</literal>. The <interfacename>Authentication</interfacename>. The
<literal>SecurityContextHolder.getContext()</literal> method is <literal>SecurityContextHolder.getContext()</literal> method is
actually returning a <literal>SecurityContext</literal>. actually returning a <interfacename>SecurityContext</interfacename>.
<!-- Commented out as Captcha sandboxed <!-- Commented out as Captcha sandboxed
Spring Spring
Security uses a few different <literal>SecurityContext</literal> Security uses a few different <interfacename>SecurityContext</interfacename>
implementations, such as if we need to store special information implementations, such as if we need to store special information
related to a request that is not principal-specific. related to a request that is not principal-specific.
@ -111,7 +111,7 @@ if (obj instanceof UserDetails) {
current request came from a human user or not. Because such a decision current request came from a human user or not. Because such a decision
has nothing at all to do with the principal the request may or may not has nothing at all to do with the principal the request may or may not
be authenticated as, we store it in the be authenticated as, we store it in the
<literal>SecurityContext</literal>. --> <interfacename>SecurityContext</interfacename>. -->
</para> </para>
</section> </section>
@ -119,40 +119,40 @@ if (obj instanceof UserDetails) {
<title>The UserDetailsService</title> <title>The UserDetailsService</title>
<para>Another item to note from the above code fragment is that you <para>Another item to note from the above code fragment is that you
can obtain a principal from the <literal>Authentication</literal> can obtain a principal from the <interfacename>Authentication</interfacename>
object. The principal is just an <literal>Object</literal>. Most of object. The principal is just an <literal>Object</literal>. Most of
the time this can be cast into a <literal>UserDetails</literal> the time this can be cast into a <interfacename>UserDetails</interfacename>
object. <literal>UserDetails</literal> is a central interface in object. <interfacename>UserDetails</interfacename> is a central interface in
Spring Security. It represents a principal, but in an extensible and Spring Security. It represents a principal, but in an extensible and
application-specific way. Think of <literal>UserDetails</literal> as application-specific way. Think of <interfacename>UserDetails</interfacename> as
the adapter between your own user database and what Spring Security the adapter between your own user database and what Spring Security
needs inside the <literal>SecurityContextHolder</literal>. Being a needs inside the <classname>SecurityContextHolder</classname>. Being a
representation of something from your own user database, quite often representation of something from your own user database, quite often
you will cast the <literal>UserDetails</literal> to the original you will cast the <interfacename>UserDetails</interfacename> to the original
object that your application provided, so you can call object that your application provided, so you can call
business-specific methods (like <literal>getEmail()</literal>, business-specific methods (like <literal>getEmail()</literal>,
<literal>getEmployeeNumber()</literal> and so on).</para> <literal>getEmployeeNumber()</literal> and so on).</para>
<para>By now you're probably wondering, so when do I provide a <para>By now you're probably wondering, so when do I provide a
<literal>UserDetails</literal> object? How do I do that? I thought you <interfacename>UserDetails</interfacename> object? How do I do that? I thought you
said this thing was declarative and I didn't need to write any Java said this thing was declarative and I didn't need to write any Java
code - what gives? The short answer is that there is a special code - what gives? The short answer is that there is a special
interface called <literal>UserDetailsService</literal>. The only interface called <interfacename>UserDetailsService</interfacename>. The only
method on this interface accepts a <literal>String</literal>-based method on this interface accepts a <literal>String</literal>-based
username argument and returns a <literal>UserDetails</literal>. Most username argument and returns a <interfacename>UserDetails</interfacename>. Most
authentication providers that ship with Spring Security delegate to a authentication providers that ship with Spring Security delegate to a
<literal>UserDetailsService</literal> as part of the authentication <interfacename>UserDetailsService</interfacename> as part of the authentication
process. The <literal>UserDetailsService</literal> is used to build process. The <interfacename>UserDetailsService</interfacename> is used to build
the <literal>Authentication</literal> object that is stored in the the <interfacename>Authentication</interfacename> object that is stored in the
<literal>SecurityContextHolder</literal>. The good news is that we <classname>SecurityContextHolder</classname>. The good news is that we
provide a number of <literal>UserDetailsService</literal> provide a number of <interfacename>UserDetailsService</interfacename>
implementations, including one that uses an in-memory map and another implementations, including one that uses an in-memory map and another
that uses JDBC. Most users tend to write their own, though, with such that uses JDBC. Most users tend to write their own, though, with such
implementations often simply sitting on top of an existing Data Access implementations often simply sitting on top of an existing Data Access
Object (DAO) that represents their employees, customers, or other Object (DAO) that represents their employees, customers, or other
users of the enterprise application. Remember the advantage that users of the enterprise application. Remember the advantage that
whatever your UserDetailsService returns can always be obtained from whatever your UserDetailsService returns can always be obtained from
the <literal>SecurityContextHolder</literal>, as per the above code the <classname>SecurityContextHolder</classname>, as per the above code
fragment.</para> fragment.</para>
</section> </section>
@ -161,23 +161,23 @@ if (obj instanceof UserDetails) {
<title>GrantedAuthority</title> <title>GrantedAuthority</title>
<para>Besides the principal, another important method provided by <para>Besides the principal, another important method provided by
<literal>Authentication</literal> is <interfacename>Authentication</interfacename> is
<literal>getAuthorities(</literal>). This method provides an array of <literal>getAuthorities(</literal>). This method provides an array of
<literal>GrantedAuthority</literal> objects. A <interfacename>GrantedAuthority</interfacename> objects. A
<literal>GrantedAuthority</literal> is, not surprisingly, an authority <interfacename>GrantedAuthority</interfacename> is, not surprisingly, an authority
that is granted to the principal. Such authorities are usually that is granted to the principal. Such authorities are usually
"roles", such as <literal>ROLE_ADMINISTRATOR</literal> or "roles", such as <literal>ROLE_ADMINISTRATOR</literal> or
<literal>ROLE_HR_SUPERVISOR</literal>. These roles are later on <literal>ROLE_HR_SUPERVISOR</literal>. These roles are later on
configured for web authorization, method authorization and domain configured for web authorization, method authorization and domain
object authorization. Other parts of Spring Security are capable of object authorization. Other parts of Spring Security are capable of
interpreting these authorities, and expect them to be present. interpreting these authorities, and expect them to be present.
<literal>GrantedAuthority</literal> objects are usually loaded by the <interfacename>GrantedAuthority</interfacename> objects are usually loaded by the
<literal>UserDetailsService</literal>.</para> <interfacename>UserDetailsService</interfacename>.</para>
<para>Usually the <literal>GrantedAuthority</literal> objects are <para>Usually the <interfacename>GrantedAuthority</interfacename> objects are
application-wide permissions. They are not specific to a given domain application-wide permissions. They are not specific to a given domain
object. Thus, you wouldn't likely have a object. Thus, you wouldn't likely have a
<literal>GrantedAuthority</literal> to represent a permission to <interfacename>GrantedAuthority</interfacename> to represent a permission to
<literal>Employee</literal> object number 54, because if there are <literal>Employee</literal> object number 54, because if there are
thousands of such authorities you would quickly run out of memory (or, thousands of such authorities you would quickly run out of memory (or,
at the very least, cause the application to take a long time to at the very least, cause the application to take a long time to
@ -186,16 +186,16 @@ if (obj instanceof UserDetails) {
domain object security capabilities for this purpose.</para> domain object security capabilities for this purpose.</para>
<para>Last but not least, sometimes you will need to store the <para>Last but not least, sometimes you will need to store the
<literal>SecurityContext</literal> between HTTP requests. Other times <interfacename>SecurityContext</interfacename> between HTTP requests. Other times
the principal will re-authenticate on every request, although most of the principal will re-authenticate on every request, although most of
the time it will be stored. The the time it will be stored. The
<literal>HttpSessionContextIntegrationFilter</literal> is responsible <classname>HttpSessionContextIntegrationFilter</classname> is responsible
for storing a <literal>SecurityContext</literal> between HTTP for storing a <interfacename>SecurityContext</interfacename> between HTTP
requests. As suggested by the name of the class, the requests. As suggested by the name of the class, the
<literal>HttpSession</literal> is used to store this information. You <literal>HttpSession</literal> is used to store this information. You
should never interact directly with the <literal>HttpSession</literal> should never interact directly with the <literal>HttpSession</literal>
for security purposes. There is simply no justification for doing so - for security purposes. There is simply no justification for doing so -
always use the <literal>SecurityContextHolder</literal> always use the <classname>SecurityContextHolder</classname>
instead.</para> instead.</para>
</section> </section>
@ -208,41 +208,41 @@ if (obj instanceof UserDetails) {
<itemizedlist spacing="compact"> <itemizedlist spacing="compact">
<listitem> <listitem>
<para><literal>SecurityContextHolder</literal>, to provide any <para><classname>SecurityContextHolder</classname>, to provide any
type access to the <literal>SecurityContext</literal>.</para> type access to the <interfacename>SecurityContext</interfacename>.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>SecurityContext</literal>, to hold the <para><interfacename>SecurityContext</interfacename>, to hold the
<literal>Authentication</literal> and possibly request-specific <interfacename>Authentication</interfacename> and possibly request-specific
security information.</para> security information.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>HttpSessionContextIntegrationFilter</literal>, to <para><classname>HttpSessionContextIntegrationFilter</classname>, to
store the <literal>SecurityContext</literal> in the store the <interfacename>SecurityContext</interfacename> in the
<literal>HttpSession</literal> between web requests.</para> <literal>HttpSession</literal> between web requests.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>Authentication</literal>, to represent the <para><interfacename>Authentication</interfacename>, to represent the
principal in a Spring Security-specific manner.</para> principal in a Spring Security-specific manner.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>GrantedAuthority</literal>, to reflect the <para><interfacename>GrantedAuthority</interfacename>, to reflect the
application-wide permissions granted to a principal.</para> application-wide permissions granted to a principal.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>UserDetails</literal>, to provide the necessary <para><interfacename>UserDetails</interfacename>, to provide the necessary
information to build an Authentication object from your information to build an Authentication object from your
application's DAOs.</para> application's DAOs.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>UserDetailsService</literal>, to create a <para><interfacename>UserDetailsService</interfacename>, to create a
<literal>UserDetails</literal> when passed in a <interfacename>UserDetails</interfacename> when passed in a
<literal>String</literal>-based username (or certificate ID or <literal>String</literal>-based username (or certificate ID or
alike).</para> alike).</para>
</listitem> </listitem>
@ -321,37 +321,37 @@ if (obj instanceof UserDetails) {
<para>Spring Security has distinct classes responsible for most of the <para>Spring Security has distinct classes responsible for most of the
steps described above. The main participants (in the order that they steps described above. The main participants (in the order that they
are used) are the <literal>ExceptionTranslationFilter</literal>, an are used) are the <classname>ExceptionTranslationFilter</classname>, an
<literal>AuthenticationEntryPoint</literal>, an authentication <interfacename>AuthenticationEntryPoint</interfacename>, an authentication
mechanism, and an <literal>AuthenticationProvider</literal>.</para> mechanism, and an <classname>AuthenticationProvider</classname>.</para>
<section> <section>
<title>ExceptionTranslationFilter</title> <title>ExceptionTranslationFilter</title>
<para><literal>ExceptionTranslationFilter</literal> is a Spring <para><classname>ExceptionTranslationFilter</classname> is a Spring
Security filter that has responsibility for detecting any Spring Security filter that has responsibility for detecting any Spring
Security exceptions that are thrown. Such exceptions will generally be Security exceptions that are thrown. Such exceptions will generally be
thrown by an <literal>AbstractSecurityInterceptor</literal>, which is thrown by an <classname>AbstractSecurityInterceptor</classname>, which is
the main provider of authorization services. We will discuss the main provider of authorization services. We will discuss
<literal>AbstractSecurityInterceptor</literal> in the next section, <classname>AbstractSecurityInterceptor</classname> in the next section,
but for now we just need to know that it produces Java exceptions and but for now we just need to know that it produces Java exceptions and
knows nothing about HTTP or how to go about authenticating a knows nothing about HTTP or how to go about authenticating a
principal. Instead the <literal>ExceptionTranslationFilter</literal> principal. Instead the <classname>ExceptionTranslationFilter</classname>
offers this service, with specific responsibility for either returning offers this service, with specific responsibility for either returning
error code 403 (if the principal has been authenticated and therefore error code 403 (if the principal has been authenticated and therefore
simply lacks sufficient access - as per step seven above), or simply lacks sufficient access - as per step seven above), or
launching an <literal>AuthenticationEntryPoint</literal> (if the launching an <interfacename>AuthenticationEntryPoint</interfacename> (if the
principal has not been authenticated and therefore we need to go principal has not been authenticated and therefore we need to go
commence step three).</para> commence step three).</para>
</section> </section>
<section xml:id="tech-auth-entry-point"> <section xml:id="tech-auth-entry-point">
<title>AuthenticationEntryPoint</title> <title>AuthenticationEntryPoint</title>
<para>The <literal>AuthenticationEntryPoint</literal> is responsible <para>The <interfacename>AuthenticationEntryPoint</interfacename> is responsible
for step three in the above list. As you can imagine, each web for step three in the above list. As you can imagine, each web
application will have a default authentication strategy (well, this application will have a default authentication strategy (well, this
can be configured like nearly everything else in Spring Security, but can be configured like nearly everything else in Spring Security, but
let's keep it simple for now). Each major authentication system will let's keep it simple for now). Each major authentication system will
have its own <literal>AuthenticationEntryPoint</literal> have its own <interfacename>AuthenticationEntryPoint</interfacename>
implementation, which takes actions such as described in step implementation, which takes actions such as described in step
three.</para> three.</para>
@ -363,7 +363,7 @@ if (obj instanceof UserDetails) {
authentication details from a user agent (usually a web browser), and authentication details from a user agent (usually a web browser), and
that name is "authentication mechanism". After the authentication that name is "authentication mechanism". After the authentication
details are collected from the user agent, an details are collected from the user agent, an
"<literal>Authentication</literal> request" object is built and then "<interfacename>Authentication</interfacename> request" object is built and then
presented to an presented to an
<interfacename>AuthenticationProvider</interfacename>.</para> <interfacename>AuthenticationProvider</interfacename>.</para>
</section> </section>
@ -371,31 +371,31 @@ if (obj instanceof UserDetails) {
<section> <section>
<title>AuthenticationProvider</title> <title>AuthenticationProvider</title>
<para>The last player in the Spring Security authentication process is <para>The last player in the Spring Security authentication process is
an <literal>AuthenticationProvider</literal>. Quite simply, it is an <classname>AuthenticationProvider</classname>. Quite simply, it is
responsible for taking an <literal>Authentication</literal> request responsible for taking an <interfacename>Authentication</interfacename> request
object and deciding whether or not it is valid. The provider will object and deciding whether or not it is valid. The provider will
either throw an exception or return a fully populated either throw an exception or return a fully populated
<literal>Authentication</literal> object. Remember our good friends, <interfacename>Authentication</interfacename> object. Remember our good friends,
<literal>UserDetails</literal> and <interfacename>UserDetails</interfacename> and
<literal>UserDetailsService</literal>? If not, head back to the <interfacename>UserDetailsService</interfacename>? If not, head back to the
previous section and refresh your memory. Most previous section and refresh your memory. Most
<literal>AuthenticationProvider</literal>s will ask a <classname>AuthenticationProvider</classname>s will ask a
<literal>UserDetailsService</literal> to provide a <interfacename>UserDetailsService</interfacename> to provide a
<literal>UserDetails</literal> object. As mentioned earlier, most <interfacename>UserDetails</interfacename> object. As mentioned earlier, most
application will provide their own application will provide their own
<literal>UserDetailsService</literal>, although some will be able to <interfacename>UserDetailsService</interfacename>, although some will be able to
use the JDBC or in-memory implementation that ships with Spring use the JDBC or in-memory implementation that ships with Spring
Security. The resultant <literal>UserDetails</literal> object - and Security. The resultant <interfacename>UserDetails</interfacename> object - and
particularly the <literal>GrantedAuthority[]</literal>s contained particularly the <literal>GrantedAuthority[]</literal>s contained
within the <literal>UserDetails</literal> object - will be used when within the <interfacename>UserDetails</interfacename> object - will be used when
building the fully populated <literal>Authentication</literal> building the fully populated <interfacename>Authentication</interfacename>
object.</para> object.</para>
<para>After the authentication mechanism receives back the <para>After the authentication mechanism receives back the
fully-populated <literal>Authentication</literal> object, it will deem fully-populated <interfacename>Authentication</interfacename> object, it will deem
the request valid, put the <literal>Authentication</literal> into the the request valid, put the <interfacename>Authentication</interfacename> into the
<literal>SecurityContextHolder</literal>, and cause the original <classname>SecurityContextHolder</classname>, and cause the original
request to be retried (step seven above). If, on the other hand, the request to be retried (step seven above). If, on the other hand, the
<literal>AuthenticationProvider</literal> rejected the request, the <classname>AuthenticationProvider</classname> rejected the request, the
authentication mechanism will ask the user agent to retry (step two authentication mechanism will ask the user agent to retry (step two
above).</para> above).</para>
@ -405,11 +405,11 @@ if (obj instanceof UserDetails) {
<title>Setting the SecurityContextHolder Contents Directly</title> <title>Setting the SecurityContextHolder Contents Directly</title>
<para>Whilst this describes the typical authentication workflow, the <para>Whilst this describes the typical authentication workflow, the
good news is that Spring Security doesn't mind how you put an good news is that Spring Security doesn't mind how you put an
<literal>Authentication</literal> inside the <interfacename>Authentication</interfacename> inside the
<literal>SecurityContextHolder</literal>. The only critical <classname>SecurityContextHolder</classname>. The only critical
requirement is that the <literal>SecurityContextHolder</literal> requirement is that the <classname>SecurityContextHolder</classname>
contains an <literal>Authentication</literal> that represents a contains an <interfacename>Authentication</interfacename> that represents a
principal before the <literal>AbstractSecurityInterceptor</literal> principal before the <classname>AbstractSecurityInterceptor</classname>
needs to authorize a request.</para> needs to authorize a request.</para>
<para>You can (and many users do) write their own filters or MVC <para>You can (and many users do) write their own filters or MVC
@ -474,22 +474,22 @@ if (obj instanceof UserDetails) {
<title>AbstractSecurityInterceptor</title> <title>AbstractSecurityInterceptor</title>
<para>Each secure object type supported by Spring Security has its own class, <para>Each secure object type supported by Spring Security has its own class,
which is a subclass of <literal>AbstractSecurityInterceptor</literal>. which is a subclass of <classname>AbstractSecurityInterceptor</classname>.
Importantly, by the time the <literal>AbstractSecurityInterceptor</literal> is called, the Importantly, by the time the <classname>AbstractSecurityInterceptor</classname> is called, the
<literal>SecurityContextHolder</literal> will contain a valid <classname>SecurityContextHolder</classname> will contain a valid
<literal>Authentication</literal> if the principal has been <interfacename>Authentication</interfacename> if the principal has been
authenticated.</para> authenticated.</para>
<para><literal>AbstractSecurityInterceptor</literal> provides a <para><classname>AbstractSecurityInterceptor</classname> provides a
consistent workflow for handling secure object requests, typically: consistent workflow for handling secure object requests, typically:
<orderedlist> <orderedlist>
<listitem><para>Look up the "configuration attributes" associated with the <listitem><para>Look up the "configuration attributes" associated with the
present request</para></listitem> present request</para></listitem>
<listitem><para>Submitting the secure object, current <literal>Authentication</literal> <listitem><para>Submitting the secure object, current <interfacename>Authentication</interfacename>
and configuration attributes to the <literal>AccessDecisionManager</literal> for and configuration attributes to the <interfacename>AccessDecisionManager</interfacename> for
an authorization decision</para></listitem> an authorization decision</para></listitem>
<listitem><para>Optionally change the <literal>Authentication</literal> under which the invocation <listitem><para>Optionally change the <interfacename>Authentication</interfacename> under which the invocation
takes place</para></listitem> takes place</para></listitem>
<listitem><para>Allow the secure object to proceed (assuming access was granted)</para></listitem> <listitem><para>Allow the secure object to proceed (assuming access was granted)</para></listitem>
<listitem><para>Call the <literal>AfterInvocationManager</literal> if configured, once the invocation <listitem><para>Call the <literal>AfterInvocationManager</literal> if configured, once the invocation
@ -501,9 +501,9 @@ if (obj instanceof UserDetails) {
<title>What are Configuration Attributes?</title> <title>What are Configuration Attributes?</title>
<para> <para>
A "configuration attribute" can be thought of as a String that has special meaning to the classes used by A "configuration attribute" can be thought of as a String that has special meaning to the classes used by
<literal>AbstractSecurityInterceptor</literal>. They may be simple role names or have more complex meaning, depending on the <classname>AbstractSecurityInterceptor</classname>. They may be simple role names or have more complex meaning, depending on the
how sophisticated the <literal>AccessDecisionManager</literal> implementation is. how sophisticated the <interfacename>AccessDecisionManager</interfacename> implementation is.
The <literal>AbstractSecurityInterceptor</literal> is configured with an <literal>ObjectDefinitionSource</literal> which The <classname>AbstractSecurityInterceptor</classname> is configured with an <interfacename>ObjectDefinitionSource</interfacename> which
it uses to look up the attributes for a secure object. Usually this configuration will be hidden from the user. Configuration it uses to look up the 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 attributes on secured URLs (using the 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> syntax). namespace <literal>&lt;intercept-url&gt;</literal> syntax).
@ -512,14 +512,14 @@ if (obj instanceof UserDetails) {
<section> <section>
<title>RunAsManager</title> <title>RunAsManager</title>
<para>Assuming <literal>AccessDecisionManager</literal> decides to <para>Assuming <interfacename>AccessDecisionManager</interfacename> decides to
allow the request, the <literal>AbstractSecurityInterceptor</literal> allow the request, the <classname>AbstractSecurityInterceptor</classname>
will normally just proceed with the request. Having said that, on rare will normally just proceed with the request. Having said that, on rare
occasions users may want to replace the occasions users may want to replace the
<literal>Authentication</literal> inside the <interfacename>Authentication</interfacename> inside the
<literal>SecurityContext</literal> with a different <interfacename>SecurityContext</interfacename> with a different
<literal>Authentication</literal>, which is handled by the <interfacename>Authentication</interfacename>, which is handled by the
<literal>AccessDecisionManager</literal> calling a <interfacename>AccessDecisionManager</interfacename> calling a
<literal>RunAsManager</literal>. This might be useful in reasonably <literal>RunAsManager</literal>. This might be useful in reasonably
unusual situations, such as if a services layer method needs to call a unusual situations, such as if a services layer method needs to call a
remote system and present a different identity. Because Spring remote system and present a different identity. Because Spring
@ -532,18 +532,18 @@ if (obj instanceof UserDetails) {
<title>AfterInvocationManager</title> <title>AfterInvocationManager</title>
<para>Following the secure object proceeding and then returning - <para>Following the secure object proceeding and then returning -
which may mean a method invocation completing or a filter chain which may mean a method invocation completing or a filter chain
proceeding - the <literal>AbstractSecurityInterceptor</literal> gets proceeding - the <classname>AbstractSecurityInterceptor</classname> gets
one final chance to handle the invocation. At this stage the one final chance to handle the invocation. At this stage the
<literal>AbstractSecurityInterceptor</literal> is interested in <classname>AbstractSecurityInterceptor</classname> is interested in
possibly modifying the return object. We might want this to happen possibly modifying the return object. We might want this to happen
because an authorization decision couldn't be made "on the way in" to because an authorization decision couldn't be made "on the way in" to
a secure object invocation. Being highly pluggable, a secure object invocation. Being highly pluggable,
<literal>AbstractSecurityInterceptor</literal> will pass control to an <classname>AbstractSecurityInterceptor</classname> will pass control to an
<literal>AfterInvocationManager</literal> to actually modify the <literal>AfterInvocationManager</literal> to actually modify the
object if needed. This class can even entirely replace the object, or object if needed. This class can even entirely replace the object, or
throw an exception, or not change it in any way.</para> throw an exception, or not change it in any way.</para>
<para><literal>AbstractSecurityInterceptor</literal> and its related objects <para><classname>AbstractSecurityInterceptor</classname> and its related objects
are shown in <xref linkend="abstract-security-interceptor"/>. are shown in <xref linkend="abstract-security-interceptor"/>.
<figure xml:id="abstract-security-interceptor"> <figure xml:id="abstract-security-interceptor">
@ -570,9 +570,9 @@ if (obj instanceof UserDetails) {
around advice semantics) is capable of being made into a secure around advice semantics) is capable of being made into a secure
object. Having said that, most Spring applications will simply use the object. Having said that, most Spring applications will simply use the
three currently supported secure object types (AOP Alliance three currently supported secure object types (AOP Alliance
<literal>MethodInvocation</literal>, AspectJ <classname>MethodInvocation</classname>, AspectJ
<literal>JoinPoint</literal> and web request <literal>JoinPoint</literal> and web request
<literal>FilterInvocation</literal>) with complete <classname>FilterInvocation</classname>) with complete
transparency.</para> transparency.</para>
</section> </section>
</section> </section>

2
src/docbkx/x509-auth-provider.xml
View File

@ -34,7 +34,7 @@
<listitem> <listitem>
<para><literal>subject-principal-regex</literal>. The regular expression used to <para><literal>subject-principal-regex</literal>. The regular expression used to
extract a username from the certificate's subject name. The default value is extract a username from the certificate's subject name. The default value is
shown above. This is the username which will be passed to the <literal>UserDetailsService</literal> to load the authorities for the shown above. This is the username which will be passed to the <interfacename>UserDetailsService</interfacename> to load the authorities for the
user.</para> user.</para>
</listitem> </listitem>
<listitem> <listitem>