org.springframework.security.authentication.dao
Class AbstractUserDetailsAuthenticationProvider

java.lang.Object
  extended by org.springframework.security.authentication.dao.AbstractUserDetailsAuthenticationProvider
All Implemented Interfaces:
InitializingBean, MessageSourceAware, AuthenticationProvider
Direct Known Subclasses:
DaoAuthenticationProvider

public abstract class AbstractUserDetailsAuthenticationProvider
extends Object
implements AuthenticationProvider, InitializingBean, MessageSourceAware

A base AuthenticationProvider that allows subclasses to override and work with UserDetails objects. The class is designed to respond to UsernamePasswordAuthenticationToken authentication requests.

Upon successful validation, a UsernamePasswordAuthenticationToken will be created and returned to the caller. The token will include as its principal either a String representation of the username, or the UserDetails that was returned from the authentication repository. Using String is appropriate if a container adapter is being used, as it expects String representations of the username. Using UserDetails is appropriate if you require access to additional properties of the authenticated user, such as email addresses, human-friendly names etc. As container adapters are not recommended to be used, and UserDetails implementations provide additional flexibility, by default a UserDetails is returned. To override this default, set the setForcePrincipalAsString(boolean) to true.

Caching is handled by storing the UserDetails object being placed in the UserCache. This ensures that subsequent requests with the same username can be validated without needing to query the UserDetailsService. It should be noted that if a user appears to present an incorrect password, the UserDetailsService will be queried to confirm the most up-to-date password was used for comparison. Caching is only likely to be required for stateless applications. In a normal web application, for example, the SecurityContext is stored in the user's session and the user isn't reauthenticated on each request. The default cache implementation is therefore NullUserCache.


Field Summary
protected  boolean hideUserNotFoundExceptions
           
protected  org.apache.commons.logging.Log logger
           
protected  MessageSourceAccessor messages
           
 
Constructor Summary
AbstractUserDetailsAuthenticationProvider()
           
 
Method Summary
protected abstract  void additionalAuthenticationChecks(UserDetails userDetails, UsernamePasswordAuthenticationToken authentication)
          Allows subclasses to perform any additional checks of a returned (or cached) UserDetails for a given authentication request.
 void afterPropertiesSet()
           
 Authentication authenticate(Authentication authentication)
          Performs authentication with the same contract as AuthenticationManager.authenticate(Authentication).
protected  Authentication createSuccessAuthentication(Object principal, Authentication authentication, UserDetails user)
          Creates a successful Authentication object.
protected  void doAfterPropertiesSet()
           
protected  UserDetailsChecker getPostAuthenticationChecks()
           
protected  UserDetailsChecker getPreAuthenticationChecks()
           
 UserCache getUserCache()
           
 boolean isForcePrincipalAsString()
           
 boolean isHideUserNotFoundExceptions()
           
protected abstract  UserDetails retrieveUser(String username, UsernamePasswordAuthenticationToken authentication)
          Allows subclasses to actually retrieve the UserDetails from an implementation-specific location, with the option of throwing an AuthenticationException immediately if the presented credentials are incorrect (this is especially useful if it is necessary to bind to a resource as the user in order to obtain or generate a UserDetails).
 void setForcePrincipalAsString(boolean forcePrincipalAsString)
           
 void setHideUserNotFoundExceptions(boolean hideUserNotFoundExceptions)
          By default the AbstractUserDetailsAuthenticationProvider throws a BadCredentialsException if a username is not found or the password is incorrect.
 void setMessageSource(MessageSource messageSource)
           
 void setPostAuthenticationChecks(UserDetailsChecker postAuthenticationChecks)
           
 void setPreAuthenticationChecks(UserDetailsChecker preAuthenticationChecks)
          Sets the policy will be used to verify the status of the loaded UserDetails before validation of the credentials takes place.
 void setUserCache(UserCache userCache)
           
 boolean supports(Class<? extends Object> authentication)
          Returns true if this AuthenticationProvider supports the indicated Authentication object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

logger

protected final org.apache.commons.logging.Log logger

messages

protected MessageSourceAccessor messages

hideUserNotFoundExceptions

protected boolean hideUserNotFoundExceptions
Constructor Detail

AbstractUserDetailsAuthenticationProvider

public AbstractUserDetailsAuthenticationProvider()
Method Detail

additionalAuthenticationChecks

protected abstract void additionalAuthenticationChecks(UserDetails userDetails,
                                                       UsernamePasswordAuthenticationToken authentication)
                                                throws AuthenticationException
Allows subclasses to perform any additional checks of a returned (or cached) UserDetails for a given authentication request. Generally a subclass will at least compare the Authentication.getCredentials() with a UserDetails.getPassword(). If custom logic is needed to compare additional properties of UserDetails and/or UsernamePasswordAuthenticationToken, these should also appear in this method.

Parameters:
userDetails - as retrieved from the retrieveUser(String, UsernamePasswordAuthenticationToken) or UserCache
authentication - the current request that needs to be authenticated
Throws:
AuthenticationException - AuthenticationException if the credentials could not be validated (generally a BadCredentialsException, an AuthenticationServiceException)

afterPropertiesSet

public final void afterPropertiesSet()
                              throws Exception
Specified by:
afterPropertiesSet in interface InitializingBean
Throws:
Exception

authenticate

public Authentication authenticate(Authentication authentication)
                            throws AuthenticationException
Description copied from interface: AuthenticationProvider
Performs authentication with the same contract as AuthenticationManager.authenticate(Authentication).

Specified by:
authenticate in interface AuthenticationProvider
Parameters:
authentication - the authentication request object.
Returns:
a fully authenticated object including credentials. May return null if the AuthenticationProvider is unable to support authentication of the passed Authentication object. In such a case, the next AuthenticationProvider that supports the presented Authentication class will be tried.
Throws:
AuthenticationException - if authentication fails.

createSuccessAuthentication

protected Authentication createSuccessAuthentication(Object principal,
                                                     Authentication authentication,
                                                     UserDetails user)
Creates a successful Authentication object.

Protected so subclasses can override.

Subclasses will usually store the original credentials the user supplied (not salted or encoded passwords) in the returned Authentication object.

Parameters:
principal - that should be the principal in the returned object (defined by the isForcePrincipalAsString() method)
authentication - that was presented to the provider for validation
user - that was loaded by the implementation
Returns:
the successful authentication token

doAfterPropertiesSet

protected void doAfterPropertiesSet()
                             throws Exception
Throws:
Exception

getUserCache

public UserCache getUserCache()

isForcePrincipalAsString

public boolean isForcePrincipalAsString()

isHideUserNotFoundExceptions

public boolean isHideUserNotFoundExceptions()

retrieveUser

protected abstract UserDetails retrieveUser(String username,
                                            UsernamePasswordAuthenticationToken authentication)
                                     throws AuthenticationException
Allows subclasses to actually retrieve the UserDetails from an implementation-specific location, with the option of throwing an AuthenticationException immediately if the presented credentials are incorrect (this is especially useful if it is necessary to bind to a resource as the user in order to obtain or generate a UserDetails).

Subclasses are not required to perform any caching, as the AbstractUserDetailsAuthenticationProvider will by default cache the UserDetails. The caching of UserDetails does present additional complexity as this means subsequent requests that rely on the cache will need to still have their credentials validated, even if the correctness of credentials was assured by subclasses adopting a binding-based strategy in this method. Accordingly it is important that subclasses either disable caching (if they want to ensure that this method is the only method that is capable of authenticating a request, as no UserDetails will ever be cached) or ensure subclasses implement additionalAuthenticationChecks(UserDetails, UsernamePasswordAuthenticationToken) to compare the credentials of a cached UserDetails with subsequent authentication requests.

Most of the time subclasses will not perform credentials inspection in this method, instead performing it in additionalAuthenticationChecks(UserDetails, UsernamePasswordAuthenticationToken) so that code related to credentials validation need not be duplicated across two methods.

Parameters:
username - The username to retrieve
authentication - The authentication request, which subclasses may need to perform a binding-based retrieval of the UserDetails
Returns:
the user information (never null - instead an exception should the thrown)
Throws:
AuthenticationException - if the credentials could not be validated (generally a BadCredentialsException, an AuthenticationServiceException or UsernameNotFoundException)

setForcePrincipalAsString

public void setForcePrincipalAsString(boolean forcePrincipalAsString)

setHideUserNotFoundExceptions

public void setHideUserNotFoundExceptions(boolean hideUserNotFoundExceptions)
By default the AbstractUserDetailsAuthenticationProvider throws a BadCredentialsException if a username is not found or the password is incorrect. Setting this property to false will cause UsernameNotFoundExceptions to be thrown instead for the former. Note this is considered less secure than throwing BadCredentialsException for both exceptions.

Parameters:
hideUserNotFoundExceptions - set to false if you wish UsernameNotFoundExceptions to be thrown instead of the non-specific BadCredentialsException (defaults to true)

setMessageSource

public void setMessageSource(MessageSource messageSource)
Specified by:
setMessageSource in interface MessageSourceAware

setUserCache

public void setUserCache(UserCache userCache)

supports

public boolean supports(Class<? extends Object> authentication)
Description copied from interface: AuthenticationProvider
Returns true if this AuthenticationProvider supports the indicated Authentication object.

Returning true does not guarantee an AuthenticationProvider will be able to authenticate the presented instance of the Authentication class. It simply indicates it can support closer evaluation of it. An AuthenticationProvider can still return null from the AuthenticationProvider.authenticate(Authentication) method to indicate another AuthenticationProvider should be tried.

Selection of an AuthenticationProvider capable of performing authentication is conducted at runtime the ProviderManager.

Specified by:
supports in interface AuthenticationProvider
Returns:
true if the implementation can more closely evaluate the Authentication class presented

getPreAuthenticationChecks

protected UserDetailsChecker getPreAuthenticationChecks()

setPreAuthenticationChecks

public void setPreAuthenticationChecks(UserDetailsChecker preAuthenticationChecks)
Sets the policy will be used to verify the status of the loaded UserDetails before validation of the credentials takes place.

Parameters:
preAuthenticationChecks - strategy to be invoked prior to authentication.

getPostAuthenticationChecks

protected UserDetailsChecker getPostAuthenticationChecks()

setPostAuthenticationChecks

public void setPostAuthenticationChecks(UserDetailsChecker postAuthenticationChecks)