SEC-1178: Updates to EL docs
This commit is contained in:
Luke Taylor
parent
e9402fa0f9
commit
30b7000875
|
|
@ -6,7 +6,87 @@
|
|||
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>
|
||||
expression.</para>
|
||||
<section>
|
||||
<title>Overview</title>
|
||||
<para>Spring Security uses Spring EL for expression support and you should look at how that
|
||||
works if you are interested in understanding the topic in more depth. Expressions are
|
||||
evaluated with a <quote>root object</quote> as part of the evaluation context. Spring
|
||||
Security uses specific classes for web and method security as the root object, in order
|
||||
to provide built-in expressions and access to values such as the current
|
||||
principal.</para>
|
||||
<section>
|
||||
<title>Common Built-In Expressions</title>
|
||||
<para>The base class for expression root objects is
|
||||
<classname>SecurityExpressionRoot</classname>. This provides some common
|
||||
expressions which are available in both web and method security.</para>
|
||||
<table frame="none">
|
||||
<title>Common built-in expressions</title>
|
||||
<tgroup cols="2">
|
||||
<colspec colname="c1" colnum="1" colwidth="1.0*"/>
|
||||
<colspec colname="c2" colnum="2" colwidth="2.0*"/>
|
||||
<thead>
|
||||
<row>
|
||||
<entry>Expression</entry>
|
||||
<entry>Description</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><literal>hasRole([role])</literal></entry>
|
||||
<entry>Returns <literal>true</literal> if the current principal has the
|
||||
specified role.</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><literal>hasAnyRole([role1,role2])</literal></entry>
|
||||
<entry>Returns <literal>true</literal> if the current principal has any
|
||||
of the supplied roles (given as a comma-separated list of
|
||||
strings)</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><literal>principal</literal></entry>
|
||||
<entry>Allows direct access to the principal object representing the
|
||||
current user</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><literal>authentication</literal></entry>
|
||||
<entry>Allows direct access to the current
|
||||
<interfacename>Authentication</interfacename> object obtained
|
||||
from the <interfacename>SecurityContext</interfacename></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><literal>permitAll</literal></entry>
|
||||
<entry>Always evaluates to <literal>true</literal></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><literal>denyAll</literal></entry>
|
||||
<entry>Always evaluates to <literal>false</literal></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><literal>isAnonymous()</literal></entry>
|
||||
<entry>Returns <literal>true</literal> if the current principal is an
|
||||
anonymous user</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><literal>isRememberMe()</literal></entry>
|
||||
<entry>Returns <literal>true</literal> if the current principal is a
|
||||
remember-me user</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><literal>isAuthenticated()</literal></entry>
|
||||
<entry>Returns <literal>true</literal> if the user is not
|
||||
anonymous</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><literal>isFullyAuthenticated()</literal></entry>
|
||||
<entry>Returns <literal>true</literal> if the user is not an anonyous or
|
||||
a remember-me user</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
</section>
|
||||
</section>
|
||||
<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
|
||||
|
|
@ -20,16 +100,16 @@
|
|||
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
|
||||
]]></programlisting>Here we have defined that the <quote>admin</quote> area of an application
|
||||
(defined by the URL pattern) should only be available to users who have the granted
|
||||
authority <quote>admin</quote> and whose IP address matches a local subnet. We've
|
||||
already seen the built-in <literal>hasRole</literal> expression in the previous section.
|
||||
The expression <literal>hasIpAddress</literal> is an additional built-in expression
|
||||
which is specific to web security. It is defined by the
|
||||
<classname>WebSecurityExpressionRoot</classname> class, an instance of which is used
|
||||
as the expression root object when evaluation web-access expressions. This object also
|
||||
directly exposed the <interfacename>HttpServletRequest</interfacename> object under the
|
||||
name <literal>request</literal> 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
|
||||
|
|
@ -38,11 +118,76 @@
|
|||
</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>
|
||||
<para>Method security is a bit more complicated than a simple allow or deny rule. Spring
|
||||
Security 3.0 introduced some new annotations in order to allow comprehensive support for
|
||||
the use of expressions.</para>
|
||||
<section>
|
||||
<title><literal>@Pre</literal> and <literal>@Post</literal> Annotations</title>
|
||||
<para>There are four annotations which support expression attributes to allow pre and
|
||||
post-invocation authorization checks and also to support filtering of submitted
|
||||
collection arguments or return values. They are <literal>@PreAuthorize</literal>,
|
||||
<literal>@PreFilter</literal>, <literal>@PostAuthorize</literal> and
|
||||
<literal>@PostFilter</literal>. Their use is enabled through the
|
||||
<literal>global-method-security</literal> namespace
|
||||
element:<programlisting><![CDATA[<global-method-security pre-post-annotations="enabled"/>]]></programlisting></para>
|
||||
<section>
|
||||
<title>Access Control using <literal>@PreAuthorize</literal> and
|
||||
<literal>@PostAuthorize</literal></title>
|
||||
<para>The most obviously useful annotation is <literal>@PreAuthorize</literal> which
|
||||
decides whether a method can actually be invoked or not. For example (from the
|
||||
<quote>Contacts</quote> sample
|
||||
application)<programlisting> @PreAuthorize("hasRole('ROLE_USER')")
|
||||
public void create(Contact contact);</programlisting>which
|
||||
means that access will only be allowed for users with the role "ROLE_USER".
|
||||
Obviously the same thing could easily be achieved using a traditional
|
||||
configuration and a simple configuration attribute for the required role. But
|
||||
what
|
||||
about:<programlisting> @PreAuthorize("hasPermission(#contact, 'admin')")
|
||||
public void deletePermission(Contact contact, Sid recipient, Permission permission);</programlisting>Here
|
||||
we're actually using a method argument as part of the expression to decide
|
||||
whether the current user has the <quote>admin</quote>permission for the given
|
||||
contact. The built-in <literal>hasPermission()</literal> expression is linked
|
||||
into the Spring Security ACL module through the application context. You can
|
||||
access any of the method arguments by name as expression variables, provided
|
||||
your code has debug information compiled in. Any Spring-EL functionality is
|
||||
available within the expression, so you can also access properties on the
|
||||
arguments. For example, if you wanted a particular method to only allow access
|
||||
to a user whose username matched that of the contact, you could write</para>
|
||||
<programlisting> @PreAuthorize("#contact.name == principal.name)")
|
||||
public void doSomething(Contact contact);</programlisting>
|
||||
<para>Here we are accessing another built–in expression, which is the
|
||||
<literal>principal</literal> of the current Spring Security
|
||||
<interfacename>Authentication</interfacename> object obtained from the
|
||||
security context. You can also access the
|
||||
<interfacename>Authentication</interfacename> object itself directly using
|
||||
the expression name <literal>authentication</literal>.</para>
|
||||
<para>Less commonly, you may wish to perform an access-control check after the
|
||||
method has been invoked. This can be achieved using the
|
||||
<literal>@PostAuthorize</literal> annotation. To access the return value
|
||||
from a method, use the built–in name <literal>returnObject</literal> in the
|
||||
expression.</para>
|
||||
</section>
|
||||
<section>
|
||||
<title>Filtering using <literal>@PreFilter</literal> and
|
||||
<literal>@PostFilter</literal></title>
|
||||
<para>As you may already be aware, Spring Security supports filtering of collections
|
||||
and arrays and this can now be achieved using expressions. This is most commonly
|
||||
performed on the return value of a method. For
|
||||
example:<programlisting> @PreAuthorize("hasRole('ROLE_USER')")
|
||||
@PostFilter("hasPermission(filterObject, 'read') or hasPermission(filterObject, 'admin')")
|
||||
public List<Contact> getAll();</programlisting>When
|
||||
using the <literal>@PostFilter</literal> annotation, Spring Security iterates
|
||||
through the returned collection and removes any elements for which the supplied
|
||||
expression is false. The name <literal>filterObject</literal> refers to the
|
||||
current object in the collection. You can also filter before the method call,
|
||||
using <literal>@PreFilter</literal>, though this is a less common requirement.
|
||||
The syntax is just the same, but if there is more than one argument which is a
|
||||
collection type then you have to select one by name using the
|
||||
<literal>filterTarget</literal> property of this annotation.</para>
|
||||
<para>Note that filtering is obviously not a substitute for tuning your data
|
||||
retrieval queries. If you are filtering large collections and removing many of
|
||||
the entries then this is likely to be inefficient.</para>
|
||||
</section>
|
||||
</section>
|
||||
</section>
|
||||
</chapter>
|
||||
|
|
|
|||
Loading…
Reference in New Issue