Cwikius-Spring/spring-security
1
0
Fork 0
mirror of https://github.com/spring-projects/spring-security.git synced 2025-07-05 10:12:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
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

109
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>
<title>Authorization Tag Libraries</title>
</info>
<para><literal>AuthorizeTag</literal> is used to include content if the current principal holds
certain <interfacename>GrantedAuthority</interfacename>s.</para>
<para>The following JSP fragment illustrates how to use the
<literal>AuthorizeTag</literal>:</para>
<para> <para>
<programlisting> It is a common requirement that a particular role in an application should automatically
<![CDATA[ <quote>include</quote> other roles. For example, in an application which has the concept of
<security:authorize ifAllGranted="ROLE_SUPERVISOR"> an <quote>admin</quote> and a <quote>user</quote> role, you may want an admin to be able to
<td> do everything a normal user can. To achieve this, you can either make sure that all admin users
<a href="del.htm?id=<c:out value="${contact.id}"/>">Del</a> are also assigned the <quote>user</quote> role. Alternatively, you can modify every access constraint
</td> which requires the <quote>user</quote> role to also include the <quote>admin</quote> role.
</security:authorize> This can get quite complicated if you have a lot of different roles in your application.
]]></programlisting>
</para> </para>
<para>This tag would cause the tag's body to be output if the principal has been granted
ROLE_SUPERVISOR.</para>
<para>The <literal>security:authorize</literal> tag declares the following attributes:</para>
<para> <para>
<itemizedlist spacing="compact"> The use of a role-hierarchy allows you to configure which roles (or authorities) should include others.
<listitem> An extended version of Spring Security's <link xlink:href="#authz-role-voter"><classname>RoleVoter</classname></link>,
<para><literal>ifAllGranted</literal>: All the listed roles must be granted for the tag to <classname>RoleHierarchyVoter</classname>, is configured with a <interfacename>RoleHierarchy</interfacename>,
output its body.</para> from which it obtains all the <quote>reachable authorities</quote> which the user is assigned.
</listitem> A typical configuration might look like this:
<listitem> <programlisting><![CDATA[
<para><literal>ifAnyGranted</literal>: Any of the listed roles must be granted for the tag <bean id="roleVoter" class="org.springframework.security.access.vote.RoleHierarchyVoter">
to output its body.</para> <constructor-arg ref="roleHierarchy" />
</listitem> </class>
<listitem> <bean id="roleHierarchy"
<para><literal>ifNotGranted</literal>: None of the listed roles must be granted for the class="org.springframework.security.access.hierarchicalroles.RoleHierarchyImpl">
tag to output its body.</para> <property name="hierarchy">
</listitem> ROLE_ADMIN > ROLE_STAFF
</itemizedlist> ROLE_STAFF > ROLE_USER
ROLE_USER > ROLE_GUEST
</property>
</bean>]]>
</programlisting>
Here we have four roles in a hierarchy <literal>ROLE_ADMIN => ROLE_STAFF => ROLE_USER => ROLE_GUEST</literal>.
A user who is authenticated with <literal>ROLE_ADMIN</literal>, will behave as if they have all four roles when
security contraints are evaluated against an <interfacename>AccessDecisionManager</interfacename> cconfigured
with the above <classname>RoleHierarchyVoter</classname>. The <literal>&gt;</literal> symbol can be thought of
as meaning <quote>includes</quote>.
</para> </para>
<para>You'll note that in each attribute you can list multiple roles. Simply separate the roles <para>
using a comma. The <literal>authorize</literal> tag ignores whitespace in attributes.</para> Role hierarchies offer a convenient means of simplifying the access-control configuration data for your
<para>The tag library logically ANDs all of it's parameters together. This means that if you application and/or reducing the number of authorities which you need to assign to a user. For more
combine two or more attributes, all attributes must be true for the tag to output it's body. complex requirements you may wish to define a logical mapping between the specific access-rights your
Don't add an <literal>ifAllGranted="ROLE_SUPERVISOR"</literal>, followed by an application requires and the roles that are assigned to users, translating between the two when loading
<literal>ifNotGranted="ROLE_SUPERVISOR"</literal>, or you'll be surprised to never see the the user information.
tag's body.</para> <!-- TODO: Extend when authority-mapping layer is added -->
<para>By requiring all attributes to return true, the authorize tag allows you to create more </para>
complex authorization scenarios. For example, you could declare an </section>
<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>