<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>
    <section>
        <title>Declaring the Taglib</title>
        <para>To use any of the tags, you must have the security taglib declared in your JSP:
            <programlisting language="xml">
    <![CDATA[<%@ taglib prefix="sec" uri="http://www.springframework.org/security/tags" %>]]>
</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-web">web-security
            expression</link>, specified in the <literal>access</literal> attribute of the tag. The
            expression evaluation will be delegated to the
            <interfacename>SecurityExpressionHandler&lt;FilterInvocation&gt;</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 language="xml">&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 language="xml">&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>
        <para>The boolean result of evaluating the tag (whether it grants or denies access) can be
            stored in a page context scope variable by setting the <literal>var</literal> attribute
            to the variable name, avoiding the need for duplicating and re-evaluating the condition
            at other points in the page.</para>
        <section>
            <title>Disabling Tag Authorization for Testing</title>
            <para>Hiding a link in a page for unauthorized users doesn't prevent them from accessing
                the URL. They could just type it into their browser directly, for example. As part
                of your testing process, you may want to reveal the hidden areas in order to check
                that links really are secured at the back end. If you set the system property
                    <literal>spring.security.disableUISecurity</literal> to <literal>true</literal>,
                the <literal>authorize</literal> tag will still run but will not hide its contents.
                By default it will also surround the content with <literal>&lt;span
                    class="securityHiddenUI">...&lt;/span></literal> tags. This allows you to
                display <quote>hidden</quote> content with a particular CSS style such as a
                different background colour. Try running the <quote>tutorial</quote> sample
                application with this property enabled, for example.</para>
            <para>You can also set the properties <literal>spring.security.securedUIPrefix</literal>
                and <literal>spring.security.securedUISuffix</literal> if you want to change
                surrounding text from the default <literal>span</literal> tags (or use empty strings
                to remove it completely).</para>
        </section>
    </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 language="xml">&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.

&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>
        <para>This tag also supports the <literal>var</literal> attribute, in the same way as the
            <literal>authorize</literal> tag.</para>
    </section>
</chapter>
