org.jsecurity.authc.pam
Class ModularRealmAuthenticator

java.lang.Object
  org.jsecurity.authc.AbstractAuthenticator
      org.jsecurity.authc.pam.ModularRealmAuthenticator

All Implemented Interfaces:

AuthenticationListenerRegistrar, Authenticator, LogoutAware

public class ModularRealmAuthenticator
extends AbstractAuthenticator

A ModularRealmAuthenticator delgates account lookups to a pluggable (modular) collection of Realms. This enables PAM (Pluggable Authentication Module) behavior in JSecurity. In addition to authorization duties, a JSecurity Realm can also be thought of a PAM 'module'.

Using this Authenticator allows you to "plug-in" your own Realms as you see fit. Common realms are those based on accessing LDAP, relational databases, file systems, etc.

If only one realm is configured (this is often the case for most applications), authentication success is naturally only dependent upon invoking this one Realm's Realm.getAuthenticationInfo(org.jsecurity.authc.AuthenticationToken) method.

But if two or more realms are configured, PAM behavior is implemented by iterating over the collection of realms and interacting with each over the course of the authentication attempt. As this is more complicated, this authenticator allows customized behavior for interpreting what happens when interacting with multiple realms - for example, you might require all realms to be successful during the attempt, or perhaps only at least one must be successful, or some other interpretation. This customized behavior can be performed via the use of a ModularAuthenticationStrategy, which you can inject as a property of this class.

The strategy object provides callback methods that allow you to determine what constitutes a success or failure in a multi-realm (PAM) scenario. And because this only makes sense in a mult-realm scenario, the strategy object is only utilized when more than one Realm is configured.

For greater security in a multi-realm configuration, unless overridden, the default implementation is the AllSuccessfulModularAuthenticationStrategy

Since:

0.1

Author:

Jeremy Haile, Les Hazlewood

See Also:

setRealms(java.util.Collection), AllSuccessfulModularAuthenticationStrategy, AtLeastOneSuccessfulModularAuthenticationStrategy

Constructor Summary

ModularRealmAuthenticator()
Default no-argument constructor which enables a AllSuccessfulModularAuthenticationStrategy by default.

ModularRealmAuthenticator(List<Realm> realms)
Constructor which initializes this Authenticator with multiple realms that will be consulted during an authentication attempt, effectively enabling PAM (Pluggable Authentication Module) behavior according to the configured ModularAuthenticationStrategy.

ModularRealmAuthenticator(Realm realm)
Constructor which initializes this Authenticator with a single realm to use during an authentiation attempt.

Method Summary

protected void	assertRealmsConfigured() Used by the internal doAuthenticate(org.jsecurity.authc.AuthenticationToken) implementation to ensure that the realms property has been set.
protected AuthenticationInfo	doAuthenticate(AuthenticationToken authenticationToken) Attempts to authenticate the given token by iterating over the internal collection of Realms.
protected AuthenticationInfo	doMultiRealmAuthentication(Collection<Realm> realms, AuthenticationToken token) Performs the multi-realm authentication attempt by calling back to a ModularAuthenticationStrategy object as each realm is consulted for AuthenticationInfo for the specified token.
protected AuthenticationInfo	doSingleRealmAuthentication(Realm realm, AuthenticationToken token) Performs the authentication attempt by interacting with the single configured realm, which is significantly simpler than performing multi-realm logic.
ModularAuthenticationStrategy	getModularAuthenticationStrategy() Returns the ModularAuthenticationStrategy utilized by this modular authenticator during a multi-realm log-in attempt.
protected Collection<Realm>	getRealms() Returns the realm(s) used by this Authenticator during an authentication attempt.
void	onLogout(PrincipalCollection principals) First calls super.onLogout(principals) to ensure a logout notification is issued, and for each wrapped Realm that implements the LogoutAware interface, calls ((LogoutAware)realm).onLogout(principals) to allow each realm the opportunity to perform logout/cleanup operations during an user-logout.
void	setModularAuthenticationStrategy(ModularAuthenticationStrategy modularAuthenticationStrategy) Allows overriding the default ModularAuthenticationStrategy utilized during multi-realm log-in attempts.
void	setRealm(Realm realm) Convenience setter for single-realm environments (fairly common).
void	setRealms(Collection<Realm> realms) Sets all realms used by this Authenticator, providing PAM (Pluggable Authentication Module) configuration.

Methods inherited from class org.jsecurity.authc.AbstractAuthenticator

add, authenticate, notifyFailure, notifyLogout, notifySuccess, remove, setAuthenticationListeners

Methods inherited from class java.lang.Object

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

Constructor Detail

ModularRealmAuthenticator

public ModularRealmAuthenticator()

Default no-argument constructor which enables a AllSuccessfulModularAuthenticationStrategy by default.

ModularRealmAuthenticator

public ModularRealmAuthenticator(Realm realm)

Constructor which initializes this Authenticator with a single realm to use during an authentiation attempt. Because this would set a single realm, no modularAuthenticationStrategy would be used during authentication attempts.

Parameters:

realm - the realm to consult during an authentication attempt.

ModularRealmAuthenticator

public ModularRealmAuthenticator(List<Realm> realms)

Constructor which initializes this Authenticator with multiple realms that will be consulted during an authentication attempt, effectively enabling PAM (Pluggable Authentication Module) behavior according to the configured ModularAuthenticationStrategy.

Parameters:

realms - the realms to consult during an authentication attempt.

Method Detail

setRealm

public void setRealm(Realm realm)

Convenience setter for single-realm environments (fairly common). This method just wraps the realm in a collection and then calls setRealms(java.util.Collection).

Parameters:

realm - the realm to consult during authentication attempts.

setRealms

public void setRealms(Collection<Realm> realms)

Sets all realms used by this Authenticator, providing PAM (Pluggable Authentication Module) configuration.

Parameters:

realms - the realms to consult during authentication attempts.

getRealms

protected Collection<Realm> getRealms()

Returns the realm(s) used by this Authenticator during an authentication attempt.

Returns:

the realm(s) used by this Authenticator during an authentication attempt.

getModularAuthenticationStrategy

public ModularAuthenticationStrategy getModularAuthenticationStrategy()

Returns the ModularAuthenticationStrategy utilized by this modular authenticator during a multi-realm log-in attempt. This object is only used when two or more Realms are configured.

Unless overridden by the setModularAuthenticationStrategy(ModularAuthenticationStrategy) method, the default implementation is the AllSuccessfulModularAuthenticationStrategy.

Returns:

the ModularAuthenticationStrategy utilized by this modular authenticator during a log-in attempt.

Since:

0.2

setModularAuthenticationStrategy

public void setModularAuthenticationStrategy(ModularAuthenticationStrategy modularAuthenticationStrategy)

Allows overriding the default ModularAuthenticationStrategy utilized during multi-realm log-in attempts. This object is only used when two or more Realms are configured.

Parameters:

modularAuthenticationStrategy - the strategy implementation to use during log-in attempts.

Since:

0.2

assertRealmsConfigured

protected void assertRealmsConfigured()
                               throws IllegalStateException

Used by the internal doAuthenticate(org.jsecurity.authc.AuthenticationToken) implementation to ensure that the realms property has been set. The default implementation ensures the property is not null and not empty.

Throws:

IllegalStateException - if the realms property is configured incorrectly.

doSingleRealmAuthentication

protected AuthenticationInfo doSingleRealmAuthentication(Realm realm,
                                                         AuthenticationToken token)

Performs the authentication attempt by interacting with the single configured realm, which is significantly simpler than performing multi-realm logic.

Parameters:

realm - the realm to consult for AuthenticationInfo.

token - the submitted AuthenticationToken representing the subject's (user's) log-in principals and credentials.

Returns:

the AuthenticationInfo associated with the user account corresponding to the specified token

doMultiRealmAuthentication

protected AuthenticationInfo doMultiRealmAuthentication(Collection<Realm> realms,
                                                        AuthenticationToken token)

Performs the multi-realm authentication attempt by calling back to a ModularAuthenticationStrategy object as each realm is consulted for AuthenticationInfo for the specified token.

Parameters:

realms - the multiple realms configured on this Authenticator instance.

token - the submitted AuthenticationToken representing the subject's (user's) log-in principals and credentials.

Returns:

an aggregated AuthenticationInfo instance representing account data across all the successfully consulted realms.

doAuthenticate

protected AuthenticationInfo doAuthenticate(AuthenticationToken authenticationToken)
                                     throws AuthenticationException

Attempts to authenticate the given token by iterating over the internal collection of Realms. For each realm, first the Realm.supports(org.jsecurity.authc.AuthenticationToken) method will be called to determine if the realm supports the authenticationToken method argument. If a realm does support the token, its Realm.getAuthenticationInfo(org.jsecurity.authc.AuthenticationToken) method will be called. If the realm returns a non-null account, the token will be considered authenticated for that realm and the account data recorded. If the realm returns null, the next realm will be consulted. If no realms support the token or all supporting realms return null, an AuthenticationException will be thrown to indicate that the user could not be authenticated.

After all realms have been consulted, the information from each realm is aggregated into a single AuthenticationInfo object and returned.

Specified by:

doAuthenticate in class AbstractAuthenticator

Parameters:

authenticationToken - the token containing the authentication principal and credentials for the user being authenticated.

Returns:

account information attributed to the authenticated user.

Throws:

AuthenticationException - if the user could not be authenticated or the user is denied authentication for the given principal and credentials.

onLogout

public void onLogout(PrincipalCollection principals)

First calls super.onLogout(principals) to ensure a logout notification is issued, and for each wrapped Realm that implements the LogoutAware interface, calls ((LogoutAware)realm).onLogout(principals) to allow each realm the opportunity to perform logout/cleanup operations during an user-logout.

JSecurity's Realm implementations all implement the LogoutAware interface by default and can be overridden for realm-specific logout logic.

Specified by:

onLogout in interface LogoutAware

Overrides:

onLogout in class AbstractAuthenticator

Parameters:

principals - the application-specific Subject/user identifier.