Cwikius-Spring
/
spring-security
mirror of https://github.com/spring-projects/spring-security.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Completed initial draft of taglibs chapter

This commit is contained in:
Luke Taylor 2009-12-15 00:03:04 +00:00
parent 3a24ddfb43
commit efb9ab4ff8
1 changed files with 79 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

102
docs/manual/src/docbook/taglibs.xml
View File

@ -1,36 +1,92 @@
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="taglibs"
xmlns:xlink="http://www.w3.org/1999/xlink">
<title>JSP Tag Libraries</title>
<para>
Spring Security has its own taglib which provides basic support for accessing security information
and applying security constraints in JSPs.
</para>
<para> Spring Security has its own taglib which provides basic support for accessing security
information and applying security constraints in JSPs. </para>
<section>
<title>Declaring the Taglib</title>
<para>To use any of the tags, you must have the security taglib declared in your JSP:
<programlisting>
<programlisting>
<![CDATA[<%@ taglib prefix="sec" uri="http://www.springframework.org/security/tags" %>]]>
</programlisting>
</para>
</programlisting></para>
</section>
<section>
<title>The <literal>authorize</literal> Tag</title>
<para>
This tag is used to determine whether its contents should be evaluated or not. In Spring Security
3.0, it can be used in two ways <footnote><para>The legacy options from Spring Security 2.0 are also supported,
but discouraged.</para></footnote>. The first approach uses a <link xlink:href="el-access-we">web-security expression</link>,
specified in the <literal>access</literal> attribute of the tag.
</para>
<para> This tag is used to determine whether its contents should be evaluated or not. In
Spring Security 3.0, it can be used in two ways <footnote>
<para>The legacy options from Spring Security 2.0 are also supported, but
discouraged.</para>
</footnote>. The first approach uses a <link xlink:href="el-access-we">web-security
expression</link>, specified in the <literal>access</literal> attribute of the tag.
The expression evaluation will be delegated to the
<interfacename>WebSecurityExpressionHandlder</interfacename> defined in the
application context (you should have web expressions enabled in your
<literal>&lt;http></literal> namespace configuration to make sure this service is
available). So, for example, you might
have<programlisting>&lt;sec:authorize access="hasRole('supervisor')">
This content will only be visible to users who have
the "supervisor" authority in their list of &lt;tt>GrantedAuthority&lt;/tt>s.
&lt;/sec:authorize></programlisting></para>
<para>A common requirement is to only show a particular link, if the user is actually
allowed to click it. How can we determine in advance whether something will be allowed?
This tag can also operate in an alternative mode which allows you to define a particular
URL as an attribute. If the user is allowed to invoke that URL, then the tag body will
be evaluated, otherwise it will be skipped. So you might have something
like<programlisting>&lt;sec:authorize url="/admin">
This content will only be visible to users who are authorized to send requests to the "/admin" URL.
&lt;/sec:authorize></programlisting>To
use this tag there must also be an instance of
<interfacename>WebInvocationPrivilegeEvaluator</interfacename> in your application
context. If you are using the namespace, one will automatically be registered. This is
an instance of <classname>DefaultWebInvocationPrivilegeEvaluator</classname>, which
creates a dummy web request for the supplied URL and invokes the security interceptor to
see whether the request would succeed or fail. This allows you to delegate to the
access-control setup you defined using <literal>intercept-url</literal> declarations
within the <literal>&lt;http></literal> namespace configuration and saves having to
duplicate the information (such as the required roles) within your JSPs. This approach
can also be combined with a <literal>method</literal> attribute, supplying the HTTP
method, for a more specific match.</para>
</section>
<section>
<title>The <literal>authentication</literal>Tag</title>
<para>This tag allows access to the current <interfacename>Authentication</interfacename>
object stored in the security context. It renders a property of the object directly in
the JSP. So, for example, if the <literal>principal</literal> property of the
<interfacename>Authentication</interfacename> is an instance of Spring Security's
<interfacename>UserDetails</interfacename> object, then using
<literal>&lt;sec:authentication property="principal.username" /></literal> will
render the name of the current user.</para>
<para>Of course, it isn't necessary to use JSP tags for this kind of thing and some people
prefer to keep as little logic as possible in the view. You can access the
<interfacename>Authentication</interfacename> object in your MVC controller (by
calling <code>SecurityContextHolder.getContext().getAuthentication()</code>) and add the
data directly to your model for rendering by the view.</para>
</section>
<section>
<title>The <literal>accesscontrollist</literal> Tag</title>
<para>This tag is only valid when used with Spring Security's ACL module. It checks a
comma-separated list of required permissions for a specified domain object. If the
current user has any of those permissions, then the tag body will be evaluated. If they
don't, it will be skipped. An example might
be<programlisting>&lt;sec:accesscontrollist hasPermission="1,2" domainObject="someObject">
This will be shown if the user has either of the permissions represented by the values "1" or "2" on the given object.
</chapter>
&lt;/sec:accesscontrollist></programlisting></para>
<para>The permissions are passed to the <interfacename>PermissionFactory</interfacename>
defined in the application context, converting them to ACL
<interfacename>Permission</interfacename> instances, so they may be any format which
is supported by the factory - they don't have to be integers, they could be strings like
<literal>READ</literal> or <literal>WRITE</literal>. If no
<interfacename>PermissionFactory</interfacename> is found, an instance of
<classname>DefaultPermissionFactory</classname> will be used. The
<interfacename>AclService</interfacename>from the application context will be used
to load the <interfacename>Acl</interfacename> instance for the supplied object. The
<interfacename>Acl</interfacename> will be invoked with the required permissions to
check if any of them are granted.</para>
</section>
</chapter>