spring-security/src/docbkx/siteminder-auth-provider.xml

<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="siteminder"><info><title>Siteminder Authentication Mechanism</title></info>


<section xml:id="siteminder-overview"><info><title>Overview</title></info>
    
    
    <para>Siteminder is a commercial single sign on solution by Computer
        Associates.</para>
    
    <para>Spring Security provides a filter,
        <literal>SiteminderAuthenticationProcessingFilter</literal> and
        provider, <literal>SiteminderAuthenticationProvider</literal> that can
        be used to process requests that have been pre-authenticated by
        Siteminder. This filter assumes that you're using Siteminder for
        <emphasis>authentication</emphasis>, and that you're using Spring
        Security for <emphasis>authorization</emphasis>. The use of Siteminder
        for <emphasis>authorization</emphasis> is not yet directly supported
        by Spring Security.</para>
    
    <para>When using Siteminder, an agent is setup on your web server to
        intercept a principal's first call to your application. The agent
        redirects the web request to a single sign-on login page, and once
        authenticated, your application receives the request. Inside the HTTP
        request is a header - such as <literal>SM_USER</literal> - which
        identifies the authenticated principal (please refer to your
        organization's "single sign-on" group for header details in your
        particular configuration).</para>
</section>

<section xml:id="siteminder-config"><info><title>Configuration</title></info>
    
    
    <para>The first step in setting up Spring Security's Siteminder
        support is to define the authentication mechanism that will inspect
        the HTTP header discussed earlier. It will be responsible for
        generating a <literal>UsernamePasswordAuthenticationToken</literal>
        that is later sent to the
        <literal>SiteminderAuthenticationProvider</literal>. Let's look at an
        example:</para>
    
    <para><programlisting>&lt;bean id="authenticationProcessingFilter"
        class="org.springframework.security.ui.webapp.SiteminderAuthenticationProcessingFilter"&gt;
        &lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
        &lt;property name="authenticationFailureUrl"&gt;&lt;value&gt;/login.jsp?login_error=1&lt;/value&gt;&lt;/property&gt;
        &lt;property name="defaultTargetUrl"&gt;&lt;value&gt;/security.do?method=getMainMenu&lt;/value&gt;&lt;/property&gt;
        &lt;property name="filterProcessesUrl"&gt;&lt;value&gt;/j_spring_security_check&lt;/value&gt;&lt;/property&gt;
        &lt;property name="siteminderUsernameHeaderKey"&gt;&lt;value&gt;SM_USER&lt;/value&gt;&lt;/property&gt;
        &lt;property name="formUsernameParameterKey"&gt;&lt;value&gt;j_username&lt;/value&gt;&lt;/property&gt;
        &lt;/bean&gt;</programlisting></para>
    
    <para>In our example above, the bean is being provided an
        <literal>AuthenticationManager</literal>, as is normally needed by
        authentication mechanisms. Several URLs are also specified, with the
        values being self-explanatory. It's important to also specify the HTTP
        header that Spring Security should inspect. If you additionally want
        to support form-based authentication (i.e. in your development
        environment where Siteminder is not installed), specify the form's
        username parameter as well - just don't do this in production!</para>
    
    <para>Note that you'll need a
        <literal>SiteminderAuthenticationProvider</literal>
        configured against your <literal>ProviderManager</literal> in order to
        use the Siteminder authentication mechanism. Normally an
        <literal>AuthenticationProvider</literal> expects the password
        property to match what it retrieves from the
        <literal>UserDetailsSource</literal>, but in this case, authentication
        has already been handled by Siteminder, so password property is not
        even relevant. This may sound like a security weakness, but remember
        that users have to authenticate with Siteminder before your
        application ever receives the requests, so the purpose of your custom
        <literal>UserDetailsService</literal> should simply be to build the
        complete <literal>Authentication</literal> object (ie with suitable
        <literal>GrantedAuthority[]</literal>s).</para>
    
    <para>Advanced tip and word to the wise: If you additionally want to
        support form-based authentication in your development environment
        (where Siteminder is typically not installed), specify the form's
        username parameter as well. Just don't do this in production!</para>
</section>
</chapter>