Package org.apache.shiro.authc.pam

Class ModularRealmAuthenticator

  • All Implemented Interfaces:
    Authenticator, LogoutAware
    public class ModularRealmAuthenticator
extends AbstractAuthenticator
    A ModularRealmAuthenticator delegates account lookups to a pluggable (modular) collection of Realms. This enables PAM (Pluggable Authentication Module) behavior in Shiro. In addition to authorization duties, a Shiro 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.apache.shiro.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 AuthenticationStrategy, 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 multi-realm scenario, the strategy object is only utilized when more than one Realm is configured.

    As most multi-realm applications require at least one Realm authenticates successfully, the default implementation is the AtLeastOneSuccessfulStrategy.
    Since:
    0.1
    See Also:
    setRealms(java.util.Collection<org.apache.shiro.realm.Realm>), AtLeastOneSuccessfulStrategy, AllSuccessfulStrategy, FirstSuccessfulStrategy

    • Method Detail

      • 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.

      • getAuthenticationStrategy

        public AuthenticationStrategy getAuthenticationStrategy()
        Returns the AuthenticationStrategy 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 setAuthenticationStrategy(AuthenticationStrategy) method, the default implementation is the AtLeastOneSuccessfulStrategy.
        Returns:
        the AuthenticationStrategy utilized by this modular authenticator during a log-in attempt.
        Since:
        0.2

      • setAuthenticationStrategy

        public void setAuthenticationStrategy(AuthenticationStrategy authenticationStrategy)
        Allows overriding the default AuthenticationStrategy utilized during multi-realm log-in attempts. This object is only used when two or more Realms are configured.
        Parameters:
        authenticationStrategy - the strategy implementation to use during log-in attempts.
        Since:
        0.2

      • 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 AuthenticationStrategy 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.

      • 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.

        Shiro'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.