diff --git a/docs/reference/src/index.xml b/docs/reference/src/index.xml index b5815d59b1..7fb3b9a9e1 100644 --- a/docs/reference/src/index.xml +++ b/docs/reference/src/index.xml @@ -1,4 +1,4 @@ - + @@ -910,32 +910,115 @@ public boolean supports(ConfigAttribute attribute); - - Authorization Tag Library + + Authorization Tag Library - The Acegi Security System for Spring comes bundled with a - JSP tag library that eases JSP writing. + The Acegi Security System for Spring comes bundled with a + JSP tag library that eases JSP writing. - - Installation - + This library simply wraps some bits of Java code, for + easy reuse. The tag library also allows the JSP developer to + determine if a principal has, doesn't have or has any of a + specified set of roles. - - Usage + + Usage - The following JSP fragment illustrates how to use the - authz taglib: + The following JSP fragment illustrates how to use the + authz taglib: - <authz:authorize ifAllGranted="ROLE_SUPERVISOR"> - <td> - <A HREF="del.htm?id=<c:out value="${contact.id}"/>">Del</A> - </td> -</authz:authorize> + + <authz:authorize ifAllGranted="ROLE_SUPERVISOR"> + <td> + <A HREF="del.htm?id=<c:out value="${contact.id}"/>">Del</A> + </td> +</authz:authorize> + - What this code says is: if the pricipal has been granted - ROLE_SUPERVISOR, allow the tag's body to be output. - - + This code was copied from the Contacts sample + application. + + What this code says is: if the pricipal has been granted + ROLE_SUPERVISOR, allow the tag's body to be output. + + + + Installation + + Installation is a simple matter-simply copy the + acegi-security-taglib.jar file to your application's + WEB-INF/lib folder. The tag library includes it's TLD, + which makes it easier to work with JSP 1.2+ containers. + + If you are using a JSP 1.1 container, you will need to + declare the JSP tag library in your application's web.xml file, + with code such as this: + + + <taglib> + <taglib-uri>http://acegisecurity.sf.net/authz</taglib-uri> + <taglib-location>/WEB-INF/authz.tld</taglib-location> +</taglib> + + + You will also need to extract the authz.tld file from + the acegi-security-taglib.jar file. Use a regular Zip tool, + or use Java's JAR utility. + + + + Reference + + The + authz:authorize tag declares the + following attributes: + + + + + + ifAllGranted: All the listed + roles must be granted for the tag to output it's + body. + + + ifAnyGranted: Any of the + listed roles must be granted for the tag to output + it's body. + + + ifNotGranted: None of the + listed roles must be granted for the tag to output + it's body. + + + + + You'll note that in each attribute you can list multiple + roles. Simply separate the roles using a comma. The + authorize tag ignores whitespace in + attributes. + + The tag library logically ANDs all of it's parameters + together. This means that if you combine two or more + attributes, they all must be true for the tag to output it's + body. Don't add an + ifAllGranted="ROLE_SUPERVISOR", followed by + an ifNotGranted="ROLE_SUPERVISOR", or + you'll be surprised to never see the tag's body. + + One last item: the tag verifies the authorizations in a + specific order: first ifNotGranted, then + ifAllGranted, and finally, + ifAnyGranted. + + + This might or might not be important to you, depending + on how your authorization scheme is defined, but it allows you + to express concepts like: principal is a SUPERVISOR, but not + a NEWBIE_SUPERVISOR. + +