Ref manual content and docbook improvements

This commit is contained in:
Luke Taylor 2009-12-12 21:21:59 +00:00
parent 282bfc3151
commit fdc9c5fd08
16 changed files with 497 additions and 304 deletions

View File

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

View File

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

View File

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

Binary file not shown.

Before

Width:  |  Height:  |  Size: 3.9 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 9.7 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 4.2 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 14 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 5.4 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 8.7 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 36 KiB

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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