Package org.springframework.security.authentication

# Class ProviderManager

java.lang.Object
org.springframework.security.authentication.ProviderManager

All Implemented Interfaces:
  `org.springframework.beans.factory.Aware`, `org.springframework.beans.factory.InitializingBean`, `org.springframework.context.MessageSourceAware`, `AuthenticationManager`

public class ProviderManager extends Object implements AuthenticationManager, org.springframework.context.MessageSourceAware, org.springframework.beans.factory.InitializingBean
Iterates an `Authentication` request through a list of `AuthenticationProvider`s.

`AuthenticationProvider`s are usually tried in order until one provides a non-null response. A non-null response indicates the provider had authority to decide on the authentication request and no further providers are tried. If a subsequent provider successfully authenticates the request, the earlier authentication exception is disregarded and the successful authentication will be used. If no subsequent provider provides a non-null response, or a new `AuthenticationException`, the last `AuthenticationException` received will be used. If no provider returns a non-null response, or indicates it can even process an `Authentication`, the `ProviderManager` will throw a `ProviderNotFoundException`. A parent `AuthenticationManager` can also be set, and this will also be tried if none of the configured providers can perform the authentication. This is intended to support namespace configuration options though and is not a feature that should normally be required.

The exception to this process is when a provider throws an `AccountStatusException`, in which case no further providers in the list will be queried. Post-authentication, the credentials will be cleared from the returned `Authentication` object, if it implements the `CredentialsContainer` interface. This behaviour can be controlled by modifying the `eraseCredentialsAfterAuthentication` property.

## Event Publishing

Authentication event publishing is delegated to the configured `AuthenticationEventPublisher` which defaults to a null implementation which doesn't publish events, so if you are configuring the bean yourself you must inject a publisher bean if you want to receive events. The standard implementation is `DefaultAuthenticationEventPublisher` which maps common exceptions to events (in the case of authentication failure) and publishes an `AuthenticationSuccessEvent` if authentication succeeds. If you are using the namespace then an instance of this bean will be used automatically by the `<http>` configuration, so you will receive events from the web part of your application automatically.

Note that the implementation also publishes authentication failure events when it obtains an authentication result (or an exception) from the "parent" `AuthenticationManager` if one has been set. So in this situation, the parent should not generally be configured to publish events or there will be duplicates.

See Also:
  - `DefaultAuthenticationEventPublisher`

## Field Summary

Fields
Modifier and Type
Field
Description
`protected org.springframework.context.support.MessageSourceAccessor`
`messages`

## Constructor Summary

Constructors
Constructor
Description
`ProviderManager(List<AuthenticationProvider> providers)`
Construct a `ProviderManager` using the given `AuthenticationProvider`s
`ProviderManager(List<AuthenticationProvider> providers, AuthenticationManager parent)`
Construct a `ProviderManager` using the provided parameters
`ProviderManager(AuthenticationProvider... providers)`
Construct a `ProviderManager` using the given `AuthenticationProvider`s

## Method Summary

Modifier and Type
Method
Description
`void`
`afterPropertiesSet()`
`Authentication`
`authenticate(Authentication authentication)`
Attempts to authenticate the passed `Authentication` object.
`List<AuthenticationProvider>`
`getProviders()`
`boolean`
`isEraseCredentialsAfterAuthentication()`
`void`
`setAuthenticationEventPublisher(AuthenticationEventPublisher eventPublisher)`
`void`
`setEraseCredentialsAfterAuthentication(boolean eraseSecretData)`
If set to, a resulting `Authentication` which implements the `CredentialsContainer` interface will have its `eraseCredentials` method called before it is returned from the `authenticate()` method.
`void`
`setMessageSource(org.springframework.context.MessageSource messageSource)`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### messages

protected org.springframework.context.support.MessageSourceAccessor messages

## Constructor Details

### ProviderManager

public ProviderManager(AuthenticationProvider... providers)
Construct a `ProviderManager` using the given `AuthenticationProvider`s

Parameters:
  `providers` - the `AuthenticationProvider`s to use

### ProviderManager

public ProviderManager(List<AuthenticationProvider> providers)
Construct a `ProviderManager` using the given `AuthenticationProvider`s

Parameters:
  `providers` - the `AuthenticationProvider`s to use

### ProviderManager

public ProviderManager(List<AuthenticationProvider> providers, AuthenticationManager parent)
Construct a `ProviderManager` using the provided parameters

Parameters:
  `providers` - the `AuthenticationProvider`s to use
  `parent` - a parent `AuthenticationManager` to fall back to

## Method Details

### afterPropertiesSet

public void afterPropertiesSet()

Specified by:
  `afterPropertiesSet` in interface `org.springframework.beans.factory.InitializingBean`

### authenticate

public Authentication authenticate(Authentication authentication) throws AuthenticationException
Attempts to authenticate the passed `Authentication` object.

The list of `AuthenticationProvider`s will be successively tried until an `AuthenticationProvider` indicates it is capable of authenticating the type of `Authentication` object passed. Authentication will then be attempted with that `AuthenticationProvider`.

If more than one `AuthenticationProvider` supports the passed `Authentication` object, the first one able to successfully authenticate the `Authentication` object determines the `result`, overriding any possible `AuthenticationException` thrown by earlier supporting `AuthenticationProvider`s. On successful authentication, no subsequent `AuthenticationProvider`s will be tried. If authentication was not successful by any supporting `AuthenticationProvider` the last thrown `AuthenticationException` will be rethrown.

Specified by:
  `authenticate` in interface `AuthenticationManager`
Parameters:
  `authentication` - the authentication request object.
Returns:
  a fully authenticated object including credentials.
Throws:
  `AuthenticationException` - if authentication fails.

### getProviders

public List<AuthenticationProvider> getProviders()

### setMessageSource

public void setMessageSource(org.springframework.context.MessageSource messageSource)

Specified by:
  `setMessageSource` in interface `org.springframework.context.MessageSourceAware`

### setAuthenticationEventPublisher

public void setAuthenticationEventPublisher(AuthenticationEventPublisher eventPublisher)

### setEraseCredentialsAfterAuthentication

public void setEraseCredentialsAfterAuthentication(boolean eraseSecretData)
If set to, a resulting `Authentication` which implements the `CredentialsContainer` interface will have its `eraseCredentials` method called before it is returned from the `authenticate()` method.

Parameters:
  `eraseSecretData` - set to false to retain the credentials data in memory. Defaults to true.

### isEraseCredentialsAfterAuthentication

public boolean isEraseCredentialsAfterAuthentication()