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

SEC-1106: Added section on hierarchical roles to manual.

This commit is contained in:
Luke Taylor 2010-05-18 16:43:55 +01:00
parent 9bdf7efd27
commit 5aab06775e
1 changed files with 46 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

117
docs/manual/src/docbook/authorization-common.xml
View File

@ -294,75 +294,50 @@ boolean supports(Class clazz);
<literal>AfterInvocationProvider</literal>s.</para> <literal>AfterInvocationProvider</literal>s.</para>
</section> --> </section> -->
</section> </section>
<!-- TODO: Move taglibs to a separate chapter which describes them all <section xml:id="authz-hierarchical-roles">
<section xml:id="authorization-taglibs"> <title>Hierarchical Roles</title>
<info> <para>
<title>Authorization Tag Libraries</title> It is a common requirement that a particular role in an application should automatically
</info> <quote>include</quote> other roles. For example, in an application which has the concept of
<para><literal>AuthorizeTag</literal> is used to include content if the current principal holds an <quote>admin</quote> and a <quote>user</quote> role, you may want an admin to be able to
certain <interfacename>GrantedAuthority</interfacename>s.</para> do everything a normal user can. To achieve this, you can either make sure that all admin users
<para>The following JSP fragment illustrates how to use the are also assigned the <quote>user</quote> role. Alternatively, you can modify every access constraint
<literal>AuthorizeTag</literal>:</para> which requires the <quote>user</quote> role to also include the <quote>admin</quote> role.
<para> This can get quite complicated if you have a lot of different roles in your application.
<programlisting> </para>
<![CDATA[ <para>
<security:authorize ifAllGranted="ROLE_SUPERVISOR"> The use of a role-hierarchy allows you to configure which roles (or authorities) should include others.
<td> An extended version of Spring Security's <link xlink:href="#authz-role-voter"><classname>RoleVoter</classname></link>,
<a href="del.htm?id=<c:out value="${contact.id}"/>">Del</a> <classname>RoleHierarchyVoter</classname>, is configured with a <interfacename>RoleHierarchy</interfacename>,
</td> from which it obtains all the <quote>reachable authorities</quote> which the user is assigned.
</security:authorize> A typical configuration might look like this:
]]></programlisting> <programlisting><![CDATA[
</para> <bean id="roleVoter" class="org.springframework.security.access.vote.RoleHierarchyVoter">
<para>This tag would cause the tag's body to be output if the principal has been granted <constructor-arg ref="roleHierarchy" />
ROLE_SUPERVISOR.</para> </class>
<para>The <literal>security:authorize</literal> tag declares the following attributes:</para> <bean id="roleHierarchy"
<para> class="org.springframework.security.access.hierarchicalroles.RoleHierarchyImpl">
<itemizedlist spacing="compact"> <property name="hierarchy">
<listitem> ROLE_ADMIN > ROLE_STAFF
<para><literal>ifAllGranted</literal>: All the listed roles must be granted for the tag to ROLE_STAFF > ROLE_USER
output its body.</para> ROLE_USER > ROLE_GUEST
</listitem> </property>
<listitem> </bean>]]>
<para><literal>ifAnyGranted</literal>: Any of the listed roles must be granted for the tag </programlisting>
to output its body.</para> Here we have four roles in a hierarchy <literal>ROLE_ADMIN => ROLE_STAFF => ROLE_USER => ROLE_GUEST</literal>.
</listitem> A user who is authenticated with <literal>ROLE_ADMIN</literal>, will behave as if they have all four roles when
<listitem> security contraints are evaluated against an <interfacename>AccessDecisionManager</interfacename> cconfigured
<para><literal>ifNotGranted</literal>: None of the listed roles must be granted for the with the above <classname>RoleHierarchyVoter</classname>. The <literal>&gt;</literal> symbol can be thought of
tag to output its body.</para> as meaning <quote>includes</quote>.
</listitem> </para>
</itemizedlist> <para>
</para> Role hierarchies offer a convenient means of simplifying the access-control configuration data for your
<para>You'll note that in each attribute you can list multiple roles. Simply separate the roles application and/or reducing the number of authorities which you need to assign to a user. For more
using a comma. The <literal>authorize</literal> tag ignores whitespace in attributes.</para> complex requirements you may wish to define a logical mapping between the specific access-rights your
<para>The tag library logically ANDs all of it's parameters together. This means that if you application requires and the roles that are assigned to users, translating between the two when loading
combine two or more attributes, all attributes must be true for the tag to output it's body. the user information.
Don't add an <literal>ifAllGranted="ROLE_SUPERVISOR"</literal>, followed by an <!-- TODO: Extend when authority-mapping layer is added -->
<literal>ifNotGranted="ROLE_SUPERVISOR"</literal>, or you'll be surprised to never see the </para>
tag's body.</para> </section>
<para>By requiring all attributes to return true, the authorize tag allows you to create more
complex authorization scenarios. For example, you could declare an
<literal>ifAllGranted="ROLE_SUPERVISOR"</literal> and an
<literal>ifNotGranted="ROLE_NEWBIE_SUPERVISOR"</literal> in the same tag, in order to
prevent new supervisors from seeing the tag body. However it would no doubt be simpler to use
<literal>ifAllGranted="ROLE_EXPERIENCED_SUPERVISOR"</literal> rather than inserting NOT
conditions into your design.</para>
<para>One last item: the tag verifies the authorizations in a specific order: first
<literal>ifNotGranted</literal>, then <literal>ifAllGranted</literal>, and finally,
<literal>if AnyGranted</literal>.</para>
<para><literal>AccessControlListTag</literal> is used to include content if the current
principal has an ACL to the indicated domain object.</para>
<para>The following JSP fragment illustrates how to use the
<literal>AccessControlListTag</literal>: <programlisting><![CDATA[
<security:accesscontrollist domainObject="${contact}" hasPermission="8,16">
<td><a href="<c:url value="del.htm"><c:param name="contactId" value="${contact.id}"/></c:url>">Del</a></td>
</security:accesscontrollist>
]]></programlisting> This tag would cause the tag's body to be output if the principal holds either
permission 16 or permission 1 for the "contact" domain object. The numbers are actually
integers that are used with <literal>BasePermission</literal> bit masking. Please refer to the
ACL section of this reference guide to understand more about the ACL capabilities of Spring
Security.</para>
<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> -->
</chapter> </chapter>