Ref manual content and docbook improvements
This commit is contained in:
Luke Taylor
parent
282bfc3151
commit
fdc9c5fd08
|
|
@ -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><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>
|
||||
|
|
|
|||
|
|
@ -22,15 +22,16 @@
|
|||
<para> The <literal><http></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><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><intercept-url></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><intercept-url></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><port-mappings></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><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><port-mappings></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><protect-pointcut></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><protect-pointcut></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><after-invocation-provider></literal> Element</title>
|
||||
|
|
|
|||
|
|
@ -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<ConfigAttribute> 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 |
|
|
@ -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><http></literal> element is the parent for all web-related namespace
|
||||
functionality. The <literal><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><intercept-url></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 <http> 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><http></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><authentication-provider></literal> element creates a
|
||||
<classname>DaoAuthenticationProvider</classname> bean and the
|
||||
<literal><user-service></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><http></literal> configuration, so the <literal><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><http></literal> configuration, so the
|
||||
<literal><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><session-management></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><session-management></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><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><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><global-method-security></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>
|
||||
|
|
|
|||
|
|
@ -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><remember-me></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>
|
||||
|
|
|
|||
|
|
@ -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"/>
|
||||
|
|
|
|||
|
|
@ -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><intercept-url></literal>
|
||||
syntax).</para>
|
||||
attributes on secured URLs. For example, when we saw something like
|
||||
<literal><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>
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
|
|||
|
|
@ -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'"/>
|
||||
|
|
|
|||
Loading…
Reference in New Issue