spring-security/docs/manual/src/docbook/preauth.xml

<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="preauth"
  xmlns:xlink="http://www.w3.org/1999/xlink">
  <info>
    <title>Pre-Authentication Scenarios</title>
  </info>
  <para> There are situations where you want to use Spring Security for authorization, but the user
    has already been reliably authenticated by some external system prior to accessing the
    application. We refer to these situations as <quote>pre-authenticated</quote> scenarios.
    Examples include X.509, Siteminder and authentication by the J2EE container in which the
    application is running. When using pre-authentication, Spring Security has to
          <orderedlist><listitem><para>Identify the user making the request.
          </para></listitem><listitem><para>Obtain the authorities for the
      user.</para></listitem></orderedlist>The details will depend on the external authentication
    mechanism. A user might be identified by their certificate information in the case of X.509, or
    by an HTTP request header in the case of Siteminder. If relying on container authentication, the
    user will be identified by calling the <methodname>getUserPrincipal()</methodname> method on the
    incoming HTTP request. In some cases, the external mechanism may supply role/authority
    information for the user but in others the authorities must be obtained from a separate source,
    such as a <interfacename>UserDetailsService</interfacename>. </para>
  <section>
    <title>Pre-Authentication Framework Classes</title>
    <para> Because most pre-authentication mechanisms follow the same pattern, Spring Security has a
      set of classes which provide an internal framework for implementing pre-authenticated
      authentication providers. This removes duplication and allows new implementations to be added
      in a structured fashion, without having to write everything from scratch. You don't need to
      know about these classes if you want to use something like <link xlink:href="#x509">X.509
        authentication</link>, as it already has a namespace configuration option which is simpler
      to use and get started with. If you need to use explicit bean configuration or are planning on
      writing your own implementation then an understanding of how the provided implementations work
      will be useful. You will find classes under the
        <package>org.springframework.security.web.authentication.preauth</package>. We just provide
      an outline here so you should consult the Javadoc and source where appropriate. </para>
    <section>
      <title>AbstractPreAuthenticatedProcessingFilter</title>
      <para> This class will check the current contents of the security context and, if empty, it
        will attempt to extract user information from the HTTP request and submit it to the
          <interfacename>AuthenticationManager</interfacename>. Subclasses override the following
        methods to obtain this information:
        <programlisting language="java">
  protected abstract Object getPreAuthenticatedPrincipal(HttpServletRequest request);
  
  protected abstract Object getPreAuthenticatedCredentials(HttpServletRequest request);
</programlisting>
        After calling these, the filter will create a
          <classname>PreAuthenticatedAuthenticationToken</classname> containing the returned data
        and submit it for authentication. By <quote>authentication</quote> here, we really just mean
        further processing to perhaps load the user's authorities, but the standard Spring Security
        authentication architecture is followed. </para>
    </section>
    <section>
      <title>AbstractPreAuthenticatedAuthenticationDetailsSource</title>
      <para> Like other Spring Security authentication filters, the pre-authentication filter has an
          <literal>authenticationDetailsSource</literal> property which by default will create a
          <classname>WebAuthenticationDetails</classname> object to store additional information
        such as the session-identifier and originating IP address in the <literal>details</literal>
        property of the <interfacename>Authentication</interfacename> object. In cases where user
        role information can be obtained from the pre-authentication mechanism, the data is also
        stored in this property. Subclasses of
          <classname>AbstractPreAuthenticatedAuthenticationDetailsSource</classname> use an extended
        details object which implements the
          <interfacename>GrantedAuthoritiesContainer</interfacename> interface, thus enabling the
        authentication provider to read the authorities which were externally allocated to the user.
        We'll look at a concrete example next. </para>
      <section xml:id="j2ee-preauth-details">
        <title>J2eeBasedPreAuthenticatedWebAuthenticationDetailsSource</title>
        <para> If the filter is configured with an <literal>authenticationDetailsSource</literal>
          which is an instance of this class, the authority information is obtained by calling the
            <methodname>isUserInRole(String role)</methodname> method for each of a pre-determined
          set of <quote>mappable roles</quote>. The class gets these from a configured
            <interfacename>MappableAttributesRetriever</interfacename>. Possible implementations
          include hard-coding a list in the application context and reading the role information
          from the <literal>&lt;security-role&gt;</literal> information in a
            <filename>web.xml</filename> file. The pre-authentication sample application uses the
          latter approach. </para>
        <para>There is an additional stage where the roles (or attributes) are mapped to Spring
          Security <interfacename>GrantedAuthority</interfacename> objects using a configured
            <interfacename>Attributes2GrantedAuthoritiesMapper</interfacename>. The default will
          just add the usual <literal>ROLE_</literal> prefix to the names, but it gives you full
          control over the behaviour. </para>
      </section>
    </section>
    <section>
      <title>PreAuthenticatedAuthenticationProvider</title>
      <para> The pre-authenticated provider has little more to do than load the
          <interfacename>UserDetails</interfacename> object for the user. It does this by delegating
        to a <interfacename>AuthenticationUserDetailsService</interfacename>. The latter is similar
        to the standard <interfacename>UserDetailsService</interfacename> but takes an
          <interfacename>Authentication</interfacename> object rather than just user name:
        <programlisting language="java">
  public interface AuthenticationUserDetailsService {
    UserDetails loadUserDetails(Authentication token) throws UsernameNotFoundException;
  }  
</programlisting>
        This interface may have also other uses but with pre-authentication it allows access to the
        authorities which were packaged in the <interfacename>Authentication</interfacename> object,
        as we saw in the previous section. The
          <classname>PreAuthenticatedGrantedAuthoritiesUserDetailsService</classname> class does
        this. Alternatively, it may delegate to a standard
          <interfacename>UserDetailsService</interfacename> via the
          <classname>UserDetailsByNameServiceWrapper</classname> implementation. </para>
    </section>
    <section>
      <title>Http403ForbiddenEntryPoint</title>
      <para> The <interfacename>AuthenticationEntryPoint</interfacename> was discussed in the <link
          xlink:href="#tech-intro-auth-entry-point">technical overview</link> chapter. Normally it
        is responsible for kick-starting the authentication process for an unauthenticated user
        (when they try to access a protected resource), but in the pre-authenticated case this
        doesn't apply. You would only configure the
          <classname>ExceptionTranslationFilter</classname> with an instance of this class if you
        aren't using pre-authentication in combination with other authentication mechanisms. It will
        be called if the user is rejected by the
          <classname>AbstractPreAuthenticatedProcessingFilter</classname> resulting in a null
        authentication. It always returns a <literal>403</literal>-forbidden response code if
        called. </para>
    </section>
  </section>
  <section>
    <title>Concrete Implementations</title>
    <para> X.509 authentication is covered in its <link xlink:href="#x509">own chapter</link>. Here
      we'll look at some classes which provide support for other pre-authenticated scenarios. </para>
    <section>
      <title>Request-Header Authentication (Siteminder)</title>
      <para> An external authentication system may supply information to the application by setting
        specific headers on the HTTP request. A well known example of this is Siteminder, which
        passes the username in a header called <literal>SM_USER</literal>. This mechanism is
        supported by the class <classname>RequestHeaderAuthenticationFilter</classname> which simply
        extracts the username from the header. It defaults to using the name
          <literal>SM_USER</literal> as the header name. See the Javadoc for more details. </para>
      <tip>
        <para>Note that when using a system like this, the framework performs no authentication
          checks at all and it is <emphasis>extremely</emphasis> important that the external system
          is configured properly and protects all access to the application. If an attacker is able
          to forge the headers in their original request without this being detected then they could
          potentially choose any username they wished. </para>
      </tip>
      <section>
        <title>Siteminder Example Configuration</title>
        <para> A typical configuration using this filter would look like this: <programlisting><![CDATA[
  <security:http>
    <!-- Additional http configuration omitted -->
    <security:custom-filter ref="siteminderFilter" />
  </security:http>
  
	<bean id="siteminderFilter" class=
"org.springframework.security.web.authentication.preauth.header.RequestHeaderAuthenticationFilter">
    <property name="principalRequestHeader" value="SM_USER"/>
    <property name="authenticationManager" ref="authenticationManager" />
  </bean>

  <bean id="preauthAuthProvider"
class="org.springframework.security.web.authentication.preauth.PreAuthenticatedAuthenticationProvider">
    <property name="preAuthenticatedUserDetailsService">
      <bean id="userDetailsServiceWrapper" 
          class="org.springframework.security.core.userdetails.UserDetailsByNameServiceWrapper">
        <property name="userDetailsService" ref="userDetailsService"/>
      </bean>    
    </property>
	</bean>
	
	<security:authentication-manager alias="authenticationManager">
	  <security:authentication-provider ref="preauthAuthProvider" />
	</security-authentication-manager>
]]>  
</programlisting> We've assumed here that the security namespace is being used for
          configuration (hence the user of the <literal>custom-filter</literal>,
            <literal>authentication-manager</literal> and
            <literal>custom-authentication-provider</literal> elements (you can read more about them
          in the <link xlink:href="ns-config">namespace chapter</link>). You would leave these out
          of a traditional bean configuration. It's also assumed that you have added a
            <interfacename>UserDetailsService</interfacename> (called
            <quote>userDetailsService</quote>) to your configuration to load the user's roles.
        </para>
      </section>
    </section>
    <section>
      <title>J2EE Container Authentication</title>
      <para> The class <classname>J2eePreAuthenticatedProcessingFilter</classname> will extract the
        username from the <literal>userPrincipal</literal> property of the
          <interfacename>HttpServletRequest</interfacename>. Use of this filter would usually be
        combined with the use of J2EE roles as described above in <xref
          linkend="j2ee-preauth-details"/>. </para>
      <para> There is a sample application in the codebase which uses this approach, so get hold of
        the code from subversion and have a look at the application context file if you are
        interested. The code is in the <filename>samples/preauth</filename> directory. </para>
    </section>
  </section>
</chapter>