diff --git a/docs/manual/src/docbook/taglibs.xml b/docs/manual/src/docbook/taglibs.xml index 1e6e48720e..5135eba55a 100644 --- a/docs/manual/src/docbook/taglibs.xml +++ b/docs/manual/src/docbook/taglibs.xml @@ -1,36 +1,92 @@ - JSP Tag Libraries - - - Spring Security has its own taglib which provides basic support for accessing security information - and applying security constraints in JSPs. - - + Spring Security has its own taglib which provides basic support for accessing security + information and applying security constraints in JSPs.
Declaring the Taglib To use any of the tags, you must have the security taglib declared in your JSP: - - + ]]> - - - +
-
The <literal>authorize</literal> Tag - - 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 The legacy options from Spring Security 2.0 are also supported, - but discouraged.. The first approach uses a web-security expression, - specified in the access attribute of the tag. - - + 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 + The legacy options from Spring Security 2.0 are also supported, but + discouraged. + . The first approach uses a web-security + expression, specified in the access attribute of the tag. + The expression evaluation will be delegated to the + WebSecurityExpressionHandlder defined in the + application context (you should have web expressions enabled in your + <http> namespace configuration to make sure this service is + available). So, for example, you might + have<sec:authorize access="hasRole('supervisor')"> + +This content will only be visible to users who have +the "supervisor" authority in their list of <tt>GrantedAuthority</tt>s. + +</sec:authorize> + 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<sec:authorize url="/admin"> + +This content will only be visible to users who are authorized to send requests to the "/admin" URL. + +</sec:authorize>To + use this tag there must also be an instance of + WebInvocationPrivilegeEvaluator in your application + context. If you are using the namespace, one will automatically be registered. This is + an instance of DefaultWebInvocationPrivilegeEvaluator, 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 intercept-url declarations + within the <http> 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 method attribute, supplying the HTTP + method, for a more specific match.
- - +
+ The <literal>authentication</literal>Tag + This tag allows access to the current Authentication + object stored in the security context. It renders a property of the object directly in + the JSP. So, for example, if the principal property of the + Authentication is an instance of Spring Security's + UserDetails object, then using + <sec:authentication property="principal.username" /> will + render the name of the current user. + 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 + Authentication object in your MVC controller (by + calling SecurityContextHolder.getContext().getAuthentication()) and add the + data directly to your model for rendering by the view. +
+
+ The <literal>accesscontrollist</literal> Tag + 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<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. - \ No newline at end of file +</sec:accesscontrollist> + The permissions are passed to the PermissionFactory + defined in the application context, converting them to ACL + Permission 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 + READ or WRITE. If no + PermissionFactory is found, an instance of + DefaultPermissionFactory will be used. The + AclServicefrom the application context will be used + to load the Acl instance for the supplied object. The + Acl will be invoked with the required permissions to + check if any of them are granted. +
+