Pre-Authentication Scenarios

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 AuthenticationManager. Subclasses override the following methods to obtain this information:

  protected abstract Object getPreAuthenticatedPrincipal(HttpServletRequest request);
  
  protected abstract Object getPreAuthenticatedCredentials(HttpServletRequest request);

After calling these, the filter will create a PreAuthenticatedAuthenticationToken containing the returned data and submit it for authentication. By “authentication” here, we really just mean further processing to perhaps load the user's authorities, but the standard Spring Security authentication architecture is followed.

Like other Spring Security authentication filters, the pre-authentication filter has an authenticationDetailsSource property which by default will create a WebAuthenticationDetails object to store additional information such as the session-identifier and originating IP address in the details property of the Authentication 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 AbstractPreAuthenticatedAuthenticationDetailsSource use an extended details object which implements the GrantedAuthoritiesContainer 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.

The pre-authenticated provider has little more to do than load the UserDetails object for the user. It does this by delegating to a AuthenticationUserDetailsService. The latter is similar to the standard UserDetailsService but takes an Authentication object rather than just user name:

  public interface AuthenticationUserDetailsService {
    UserDetails loadUserDetails(Authentication token) throws UsernameNotFoundException;
  }  

This interface may have also other uses but with pre-authentication it allows access to the authorities which were packaged in the Authentication object, as we saw in the previous section. The PreAuthenticatedGrantedAuthoritiesUserDetailsService class does this. Alternatively, it may delegate to a standard UserDetailsService via the UserDetailsByNameServiceWrapper implementation.

The AuthenticationEntryPoint was discussed in the technical overview 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 ExceptionTranslationFilter 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 AbstractPreAuthenticatedProcessingFilter resulting in a null authentication. It always returns a 403-forbidden response code if called.

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 is Siteminder, which passes the username in a header called SM_USER. This mechanism is supported by the class RequestHeaderPreAuthenticatedProcessingFilter which simply extracts the username from the header. It defaults to using the name SM_USER as the header name. See the Javadoc for more details.

	<bean id="siteminderFilter"
      class="org.springframework.security.ui.preauth.header.RequestHeaderPreAuthenticatedProcessingFilter">
    <security:custom-filter position="PRE_AUTH_FILTER" />
    <property name="principalRequestHeader" value="SM_USER"/>
    <property name="authenticationManager" ref="authenticationManager" />
  </bean>

  <bean id="preauthAuthProvider"
      class="org.springframework.security.providers.preauth.PreAuthenticatedAuthenticationProvider">
    <security:custom-authentication-provider />      
    <property name="preAuthenticatedUserDetailsService">
      <bean id="userDetailsServiceWrapper" 
            class="org.springframework.security.userdetails.UserDetailsByNameServiceWrapper">
        <property name="userDetailsService" ref="userDetailsService"/>
      </bean>    
    </property>
	</bean>
	
	<security:authentication-manager alias="authenticationManager" />
  

The class J2eePreAuthenticatedProcessingFilter will extract the username from the userPrincipal property of the HttpServletRequest. use of this filter would usually be combined with the use of J2EE roles as described above in Section 16.1.2.1, “J2eeBasedPreAuthenticatedWebAuthenticationDetailsSource”.