1
0
mirror of synced 2026-08-05 17:57:15 +00:00

Doc updates.

This commit is contained in:
Luke Taylor
2009-11-24 09:29:22 +00:00
parent 46ef4239ca
commit cd6711d21a
9 changed files with 483 additions and 452 deletions
@@ -488,8 +488,8 @@
configuration as web security, but this can be overridden as explained above <xref
xlink:href="#nsa-access-decision-manager-ref"/>, using the same attribute. </para>
<section>
<title>The <literal>&lt;secured-annotations&gt;</literal> and
<literal>&lt;jsr250-annotations&gt;</literal> Attributes</title>
<title>The <literal>secured-annotations</literal> and
<literal>jsr250-annotations</literal> Attributes</title>
<para> Setting these to "true" will enable support for Spring Security's own
<literal>@Secured</literal> annotations and JSR-250 annotations, respectively. They are
both disabled by default. Use of JSR-250 annotations also adds a
@@ -221,12 +221,15 @@ boolean supports(Class clazz);
that there is at least one configuration attribute that an
<interfacename>AccessDecisionVoter</interfacename> will vote to grant access for. This
latter (recommended) approach is usually achieved through a <literal>ROLE_USER</literal> or
<literal>ROLE_AUTHENTICATED</literal> configuration attribute</para>
<literal>ROLE_AUTHENTICATED</literal> configuration attribute.</para>
<!-- TODO: Move to ACL section and add reference here -->
<!--
<section xml:id="after-invocation-acl-aware">
<info>
<title>ACL-Aware AfterInvocationProviders</title>
</info>
<!-- TODO: Move to ACL section and add reference here -->
<para>A common services layer method we've all written at one stage or another looks like
this:</para>
<para>
@@ -279,8 +282,10 @@ boolean supports(Class clazz);
<literal>requirePermission</literal>s.</para>
<para>The Contacts sample application demonstrates these two
<literal>AfterInvocationProvider</literal>s.</para>
</section>
</section> -->
</section>
<!-- TODO: Move taglibs to a separate chapter which describes them all
<section xml:id="authorization-taglibs">
<info>
<title>Authorization Tag Libraries</title>
@@ -350,5 +355,5 @@ boolean supports(Class clazz);
<para><literal>AclTag</literal> is part of the old ACL module and should be considered
deprecated. For the sake of historical reference, works exactly the samae as
<literal>AccessControlListTag</literal>.</para>
</section>
</section> -->
</chapter>
+76 -3
View File
@@ -97,9 +97,8 @@
returned from the configured <interfacename>UserDetailsService</interfacename>. A
<interfacename>SaltSource</interfacename> enables the passwords to be populated
with a "salt", which enhances the security of the passwords in the authentication
repository. These will be discussed in more detail in ???.
<!-- TODO: Add sections on password encoding and user caching to advaced topics -->
</para>
repository. These will be discussed in more detail <link
xlink:href="core-services-password-encodin">below</link>. </para>
</section>
</section>
<section>
@@ -203,4 +202,78 @@
-->
</section>
</section>
<section xml:id="core-services-password-encoding">
<title>Password Encoding</title>
<para>Spring Security's <interfacename>PasswordEncoder</interfacename> interface is used to
support the use of passwords which are encoded in some way in persistent storage. This
will normally mean that the passwords are <quote>hashed</quote> using a digest alogirthm
such as MD5 or SHA.</para>
<section>
<title>What is a hash?</title>
<para>Password hashing is not unique to Spring Security but is a common source of
confusion for users who are not familiar with the concept. A hash (or digest)
algorithm is a one-way function which produces a piece of fixed-length output data
(the hash) from some input data, such as a password. As an example, the MD5 hash of
the string <quote>password</quote> (in hexadecimal) is
<programlisting>
5f4dcc3b5aa765d61d8327deb882cf99
</programlisting> A hash is
<quote>one-way</quote> in the sense that it is very difficult (effectively
impossible) to obtain the original input given the hash value, or indeed any
possible input which would produce that hash value. This property makes hash values
very useful for authentication purposes. They can be stored in your user database as
an alternative to plaintext passwords and even if the values are compromised they do
not immediately reveal a password which can be used to login. Note that this also
means you have no way of recovering the password once it is encoded.</para>
</section>
<section>
<title>Adding Salt to a Hash</title>
<para> One potential problem with the use of password hashes that it is relatively easy
to get round the one-way property of the hash if a common word is used for the
input. For example, if you search for the hash value
<literal>5f4dcc3b5aa765d61d8327deb882cf99</literal> using google, you will
quickly find the original word <quote>password</quote>. In a similar way, an
attacker can build a dictionary of hashes from a standard word list and use this to
lookup the original password. One way to help prevent this is to have a suitably
strong password policy to try to prevent common words from being used. Another is to
use a <quote>salt</quote> when calculating the hashes. This is an additional string
of known data for each user which is combined with the password before calculating
the hash. Ideally the data should be as random as possible, but in practice any salt
value is usually preferable to none. Spring Security has a
<interfacename>SaltSource</interfacename> interface which can be used by an
authentication provider to generate a salt value for a particular user. Using a salt
means that an attacker has to build a separate dictionary of hashes for each salt
value, making the attack more complicated (but not impossible).</para>
</section>
<section>
<title> Hashing and Authentication</title>
<para>When an authentication provider (such as Spring Security's
<classname>DaoAuthenticationProvider</classname> needs to check the password in
a submitted authentication request against the known value for a user, and the
stored password is encoded in some way, then the submitted value must be encoded
using exactly the same algorithm. It's up to you to check that these are compatible
as Spring Security has no control over the persistent values. If you add password
hashing to your authentication configuration in Spring Security, and your database
contains plaintext passwords, then there is no way authentication can succeed. Even
if you are aware that your database is using MD5 to encode the passwords, for
example, and your application is configured to use Spring Security's
<classname>Md5PasswordEncoder</classname>, there are still things that can go
wrong. The database may have the passwords encoded in Base 64, for example while the
enocoder is using hexadecimal strings (the default)<footnote><para>You can configure
the encoder to use Base 64 instead of hex by setting the
<literal>encodeHashAsBase64</literal> property to
<literal>true</literal>. Check the Javadoc for
<classname>MessageDigestPasswordEncoder</classname> and its parent
classes for more information.</para></footnote>. Alternatively your database
may be using upper-case while the output from the encoder is lower-case. Make sure
you write a test to check the output from your configured password encoder with a
known password and salt combination and check that it matches the database value
before going further and attempting to authenticate through your application. For
more information on the default method for merging salt and password, see the
Javadoc for <classname>BasePasswordEncoder</classname>. If you want to generate
encoded passwords directly in Java for storage in your user database, then you can
use the <methodname>encodePassword</methodname> method on the
<interfacename>PasswordEncoder</interfacename>.</para>
</section>
</section>
</chapter>
+48
View File
@@ -0,0 +1,48 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="el-access"
xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Expression-Based Access Control</title>
<para> Spring Security 3.0 introduced the ability to use Spring EL expressions as an
authorization mechanism in addition to the simple use of configuration attributes and
access-decision voters which have seen before. Expression-based access control is built on
the same architecture but allows complicated boolean logic to be encapsulated in a single
expression. </para>
<section xml:id="el-access-web">
<title>Web Security Expressions</title>
<para> To use expressions to secure individual URLs, you would first need to set the
<literal>use-expressions</literal> attribute in the <literal>&lt;http></literal>
element to <literal>true</literal>. Spring Security will then expect the
<literal>access</literal> attributes of the <literal>&lt;intercept-url></literal>
elements to contain Spring EL expressions. The expressions should evaluate to a boolean,
defining whether access should be allowed or not. For example:<programlisting><![CDATA[
<http use-expressions="true">
<intercept-url pattern="/admin*"
access="hasRole('admin') and hasIpAddress('192.168.1.0/24')"/>
...
</http>
]]></programlisting>Here we have defined that the "admin" area of an application should only be
available to users who have the granted authority <quote>admin</quote> and whose IP
address matches a local subnet. The expressions <literal>hasRole</literal> and
<literal>hasIpAddress</literal> are both built in expressions, which are defined by
the <classname>WebSecurityExpressionRoot</classname> class, an instance of which is used
as the expression root object when evaluation web-access expressions. See the
documentation for Spring EL in the main Spring Framework reference if you want to know
more about the details of expression evaluation. This object also directly exposed the
<interfacename>HttpServletRequest</interfacename> object under the name
<quote>request</quote> so you can invoke the request directly in an
expression.</para>
<para>If expressions are being used, a <classname>WebExpressionVoter</classname> will be
added to the <interfacename>AccessDecisionManager</interfacename> which is used by the
namespace. So if you aren't using the namespace and want to use expressions, you will
have to add one of these to your configuration.</para>
</section>
<section>
<title>Method Security Expressions</title>
<para>Method security expressions in Spring Security 3.0 are supported through the use of
special annotations which allow pre and post-invocation authorization checks.
Expressions can also be used to filter collections or arrays, based on the permissions
of the principal invoking the method. Values can be removed from a collection argument
prior to the invocation of the method or, post-invocation, a returned collection can be
filtered to remove items to which the user should not have access.</para>
</section>
</chapter>
+28 -9
View File
@@ -461,7 +461,11 @@
<user name="http://jimi.hendrix.myopenid.com/" password="notused"
authorities="ROLE_USER" />
]]></programlisting> You should be able to login using the <literal>myopenid.com</literal> site to
authenticate. </para>
authenticate. It is also possible to select a specific
<interfacename>UserDetailsService</interfacename> bean for use OpenID by setting the
<literal>user-service-ref</literal> attribute on the <literal>openid-login</literal>
element. See the previous section on <link xlink:href="#ns-auth-providers">authentication
providers</link> for more information. </para>
</section>
<section xml:id="ns-custom-filters">
<title>Adding in Your Own Filters</title>
@@ -564,10 +568,11 @@
<title>Method Security</title>
<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 native <literal>@Secured</literal> annotation. 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>
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>
<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
@@ -581,9 +586,7 @@
</programlisting> Adding an annotation to a method (on an class or interface) would then limit
the access to that method accordingly. Spring Security's native annotation support defines a
set of attributes for the method. These will be passed to the
<interfacename>AccessDecisionManager</interfacename> for it to make the actual decision.
This example is taken from the <link xlink:href="#tutorial-sample">tutorial sample</link>,
which is a good starting point if you want to use method security in your application:
<interfacename>AccessDecisionManager</interfacename> for it to make the actual decision:
<programlisting language="java">
public interface BankService {
@@ -597,6 +600,22 @@
public Account post(Account account, double amount);
}
</programlisting></para>
<para>To use the new expression-based syntax, you would use <programlisting><![CDATA[
<global-method-security pre-post-annotations="enabled" />
]]></programlisting>and the equivalent Java code would
be<programlisting language="java">
public interface BankService {
@PreAuthorize("isAnonymous()")
public Account readAccount(Long id);
@PreAuthorize("isAnonymous()")
public Account[] findAccounts();
@PreAuthorize("hasAuthority('ROLE_TELLER')")
public Account post(Account account, double amount);
}
</programlisting></para>
<section xml:id="ns-protect-pointcut">
<title>Adding Security Pointcuts using <literal>protect-pointcut</literal></title>
<para> The use of <literal>protect-pointcut</literal> is particularly powerful, as it allows
@@ -642,7 +661,7 @@
...
</global-method-security>
]]></programlisting></para>
<para> The syntax for web security is the same, but on the <literal>http</literal> element: <programlisting language="xml"><![CDATA[
<para> The syntax for web security is the same, but on the <literal>http</literal> element: <programlisting language="xml"><![CDATA[
<http access-decision-manager-ref="myAccessDecisionManagerBean">
...
</http>
@@ -159,6 +159,7 @@
</partintro>
<xi:include href="authorization-common.xml"/>
<xi:include href="secured-objects.xml"/>
<xi:include href="el-access.xml"/>
</part>
<part xml:id="advanced-topics">
<title>Advanced Topics</title>
+45 -80
View File
@@ -111,15 +111,15 @@ if (principal instanceof UserDetails) {
<para> On successful authentication, <interfacename>UserDetails</interfacename> is used to
build the <interfacename>Authentication</interfacename> object that is stored in the
<classname>SecurityContextHolder</classname> (more on this <link
xlink:href="#tech-intro-authentication">below</link>). The good news is that we
provide a number of <interfacename>UserDetailsService</interfacename> implementations,
including one that uses an in-memory map (<classname>InMemoryDaoImpl</classname>) and
another that uses JDBC (<classname>JdbcDaoImpl</classname>). Most users tend to
write their own, though, with their implementations often simply sitting on top of an
existing Data Access Object (DAO) that represents their employees, customers, or other users
of the application. Remember the advantage that whatever your
<interfacename>UserDetailsService</interfacename> returns can always be obtained from the
<classname>SecurityContextHolder</classname> using the above code fragment. </para>
xlink:href="#tech-intro-authentication">below</link>). The good news is that we provide a
number of <interfacename>UserDetailsService</interfacename> implementations, including one
that uses an in-memory map (<classname>InMemoryDaoImpl</classname>) and another that uses
JDBC (<classname>JdbcDaoImpl</classname>). Most users tend to write their own, though, with
their implementations often simply sitting on top of an existing Data Access Object (DAO)
that represents their employees, customers, or other users of the application. Remember the
advantage that whatever your <interfacename>UserDetailsService</interfacename> returns can
always be obtained from the <classname>SecurityContextHolder</classname> using the above
code fragment. </para>
</section>
<section xml:id="tech-granted-authority">
<title>GrantedAuthority</title>
@@ -189,50 +189,31 @@ 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,29 +465,17 @@ 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
@@ -518,9 +487,9 @@ Successfully authenticated. Security context contains: \
<classname>AbstractSecurityInterceptor</classname> is configured with a
<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
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>
syntax).</para>
</section>
<section>
<title>RunAsManager</title>
@@ -551,14 +520,10 @@ 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>