Package org.springframework.security.authentication.jaas

# Class JaasAuthenticationProvider

java.lang.Object
org.springframework.security.authentication.jaas.AbstractJaasAuthenticationProvider
org.springframework.security.authentication.jaas.JaasAuthenticationProvider

All Implemented Interfaces:
  `EventListener`, `org.springframework.beans.factory.Aware`, `org.springframework.beans.factory.InitializingBean`, `org.springframework.context.ApplicationEventPublisherAware`, `org.springframework.context.ApplicationListener<SessionDestroyedEvent>`, `AuthenticationProvider`

public class JaasAuthenticationProvider extends AbstractJaasAuthenticationProvider
An `AuthenticationProvider` implementation that retrieves user details from a JAAS login configuration.

This `AuthenticationProvider` is capable of validating `UsernamePasswordAuthenticationToken` requests contain the correct username and password.

This implementation is backed by a JAAS configuration. The loginConfig property must be set to a given JAAS configuration file. This setter accepts a Spring `Resource` instance. It should point to a JAAS configuration file containing an index matching the `loginContextName` property.

For example: If this JaasAuthenticationProvider were configured in a Spring WebApplicationContext the xml to set the loginConfiguration could be as follows...

     <property name="loginConfig">
       <value>/WEB-INF/login.conf</value>
     </property>

The loginContextName should coincide with a given index in the loginConfig specified. The loginConfig file used in the JUnit tests appears as the following...

     JAASTest {
       org.springframework.security.authentication.jaas.TestLoginModule required;
     };

Using the example login configuration above, the loginContextName property would be set as JAASTest...

      <property name="loginContextName"> <value>JAASTest</value> </property>

When using JAAS login modules as the authentication source, sometimes the LoginContext will require CallbackHandlers. The JaasAuthenticationProvider uses an internal CallbackHandler to wrap the `JaasAuthenticationCallbackHandler`s configured in the ApplicationContext. When the LoginContext calls the internal CallbackHandler, control is passed to each `JaasAuthenticationCallbackHandler` for each Callback passed.

`JaasAuthenticationCallbackHandler`s are passed to the JaasAuthenticationProvider through the `callbackHandlers` property.

     <property name="callbackHandlers">
       <list>
         <bean class="org.springframework.security.authentication.jaas.TestCallbackHandler"/>
         <bean class="org.springframework.security.authentication.jaas.JaasNameCallbackHandler"/>
         <bean class="org.springframework.security.authentication.jaas.JaasPasswordCallbackHandler"/>
      </list>
     </property>

After calling LoginContext.login(), the JaasAuthenticationProvider will retrieve the returned Principals from the Subject (LoginContext.getSubject().getPrincipals). Each returned principal is then passed to the configured `AuthorityGranter`s. An AuthorityGranter is a mapping between a returned Principal, and a role name. If an AuthorityGranter wishes to grant an Authorization a role, it returns that role name from it's `AuthorityGranter.grant(java.security.Principal)` method. The returned role will be applied to the Authorization object as a `GrantedAuthority`.

AuthorityGranters are configured in spring xml as follows...

     <property name="authorityGranters">
       <list>
         <bean class="org.springframework.security.authentication.jaas.TestAuthorityGranter"/>
       </list>
      </property>

A configuration note: The JaasAuthenticationProvider uses the security properties "login.config.url.X" to configure jaas. If you would like to customize the way Jaas gets configured, create a subclass of this and override the `configureJaas(Resource)` method.

## Field Summary

Fields
Modifier and Type
Field
Description
`protected static final org.apache.commons.logging.Log`
`log`

## Constructor Summary

Constructors
Constructor
Description
`JaasAuthenticationProvider()`

## Method Summary

Modifier and Type
Method
Description
`void`
`afterPropertiesSet()`
Validates the required properties are set.
`protected void`
`configureJaas(org.springframework.core.io.Resource loginConfig)`
Hook method for configuring Jaas.
`protected LoginContext`
`createLoginContext(CallbackHandler handler)`
Creates the LoginContext to be used for authentication.
`org.springframework.core.io.Resource`
`getLoginConfig()`
`protected void`
`publishFailureEvent(UsernamePasswordAuthenticationToken token, AuthenticationException ase)`
Publishes the `JaasAuthenticationFailedEvent`.
`void`
`setLoginConfig(org.springframework.core.io.Resource loginConfig)`
Set the JAAS login configuration file.
`void`
`setRefreshConfigurationOnStartup(boolean refresh)`
If set, a call to `Configuration#refresh()` will be made by `#configureJaas(Resource)` method.

### Methods inherited from class org.springframework.security.authentication.jaas.AbstractJaasAuthenticationProvider

`authenticate, getApplicationEventPublisher, handleLogout, onApplicationEvent, publishSuccessEvent, setApplicationEventPublisher, setAuthorityGranters, setCallbackHandlers, setLoginContextName, setLoginExceptionResolver, supports`

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

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

### Methods inherited from interface org.springframework.context.ApplicationListener

`supportsAsyncExecution`

## Field Details

### log

protected static final org.apache.commons.logging.Log log

## Constructor Details

### JaasAuthenticationProvider

public JaasAuthenticationProvider()

## Method Details

### afterPropertiesSet

public void afterPropertiesSet() throws Exception
Description copied from class: `AbstractJaasAuthenticationProvider`
Validates the required properties are set. In addition, if `AbstractJaasAuthenticationProvider.setCallbackHandlers(JaasAuthenticationCallbackHandler[])` has not been called with valid handlers, initializes to use `JaasNameCallbackHandler` and `JaasPasswordCallbackHandler`.

Specified by:
  `afterPropertiesSet` in interface `org.springframework.beans.factory.InitializingBean`
Overrides:
  `afterPropertiesSet` in class `AbstractJaasAuthenticationProvider`
Throws:
  `Exception`

### createLoginContext

protected LoginContext createLoginContext(CallbackHandler handler) throws LoginException
Description copied from class: `AbstractJaasAuthenticationProvider`
Creates the LoginContext to be used for authentication.

Specified by:
  `createLoginContext` in class `AbstractJaasAuthenticationProvider`
Parameters:
  `handler` - The CallbackHandler that should be used for the LoginContext (never `null`).
Returns:
  the LoginContext to use for authentication.
Throws:
  `LoginException`

### configureJaas

protected void configureJaas(org.springframework.core.io.Resource loginConfig) throws IOException
Hook method for configuring Jaas.

Parameters:
  `loginConfig` - URL to Jaas login configuration
Throws:
  `IOException` - if there is a problem reading the config resource.

### publishFailureEvent

protected void publishFailureEvent(UsernamePasswordAuthenticationToken token, AuthenticationException ase)
Publishes the `JaasAuthenticationFailedEvent`. Can be overridden by subclasses for different functionality

Overrides:
  `publishFailureEvent` in class `AbstractJaasAuthenticationProvider`
Parameters:
  `token` - The authentication token being processed
  `ase` - The exception that caused the authentication failure

### getLoginConfig

public org.springframework.core.io.Resource getLoginConfig()

### setLoginConfig

public void setLoginConfig(org.springframework.core.io.Resource loginConfig)
Set the JAAS login configuration file.

Parameters:
  `loginConfig` -
See Also:
  - JAAS Reference

### setRefreshConfigurationOnStartup

public void setRefreshConfigurationOnStartup(boolean refresh)
If set, a call to `Configuration#refresh()` will be made by `#configureJaas(Resource)` method. Defaults to `true`.

Parameters:
  `refresh` - set to `false` to disable reloading of the configuration. May be useful in some environments.
See Also:
  - SEC-1320