/*

  * Licensed to the Apache Software Foundation (ASF) under one

  * or more contributor license agreements.  See the NOTICE file

  * distributed with this work for additional information

  * regarding copyright ownership.  The ASF licenses this file

  * to you under the Apache License, Version 2.0 (the

  * "License"); you may not use this file except in compliance

  * with the License.  You may obtain a copy of the License at

  *

  *     http://www.apache.org/licenses/LICENSE-2.0

  *

  * Unless required by applicable law or agreed to in writing,

  * software distributed under the License is distributed on an

  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY

  * KIND, either express or implied.  See the License for the

  * specific language governing permissions and limitations

  * under the License.

  */

 package org.apache.shiro.authc.pam;

 import org.apache.shiro.authc.*;

 import org.apache.shiro.realm.Realm;

 import org.apache.shiro.subject.PrincipalCollection;

 import org.apache.shiro.util.CollectionUtils;

 import org.slf4j.Logger;

 import org.slf4j.LoggerFactory;

 import java.util.Collection;

 /**

  * A {@code ModularRealmAuthenticator} delgates account lookups to a pluggable (modular) collection of

  * {@link Realm}s.  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'.

  * <p/>

  * Using this Authenticator allows you to "plug-in" your own

  * {@code Realm}s as you see fit.  Common realms are those based on accessing

  * LDAP, relational databases, file systems, etc.

  * <p/>

  * 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

  * {@link Realm#getAuthenticationInfo(org.apache.shiro.authc.AuthenticationToken)} method.

  * <p/>

  * 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

  * {@link #setAuthenticationStrategy(AuthenticationStrategy) AuthenticationStrategy}, which

  * you can inject as a property of this class.

  * <p/>

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

  * <p/>

  * As most multi-realm applications require at least one Realm authenticates successfully, the default

  * implementation is the {@link AtLeastOneSuccessfulStrategy}.

  *

  * @see #setRealms

  * @see AtLeastOneSuccessfulStrategy

  * @see AllSuccessfulStrategy

  * @see FirstSuccessfulStrategy

  * @since 0.1

  */

 public class ModularRealmAuthenticator extends AbstractAuthenticator {

     /*--------------------------------------------

     |             C O N S T A N T S             |

     ============================================*/

     private static final Logger log = LoggerFactory.getLogger(ModularRealmAuthenticator.class);

     /*--------------------------------------------

     |    I N S T A N C E   V A R I A B L E S    |

     ============================================*/

     /**

      * List of realms that will be iterated through when a user authenticates.

      */

     private Collection<Realm> realms;

     /**

      * The authentication strategy to use during authentication attempts, defaults to a

      * {@link org.apache.shiro.authc.pam.AtLeastOneSuccessfulStrategy} instance.

      */

     private AuthenticationStrategy authenticationStrategy;

     /*--------------------------------------------

     |         C O N S T R U C T O R S           |

     ============================================*/

     /**

      * Default no-argument constructor which

      * {@link #setAuthenticationStrategy(AuthenticationStrategy) enables}  an

      * {@link org.apache.shiro.authc.pam.AtLeastOneSuccessfulStrategy} by default.

      */

     public ModularRealmAuthenticator() {

         this.authenticationStrategy = new AtLeastOneSuccessfulStrategy();

     }

     /*--------------------------------------------

     |  A C C E S S O R S / M O D I F I E R S    |

     ============================================*/

     /**

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

      *

      * @param realms the realms to consult during authentication attempts.

      */

     public void setRealms(Collection<Realm> realms) {

         this.realms = realms;

     }

     /**

      * Returns the realm(s) used by this {@code Authenticator} during an authentication attempt.

      *

      * @return the realm(s) used by this {@code Authenticator} during an authentication attempt.

      */

     protected Collection<Realm> getRealms() {

         return this.realms;

     }

     /**

      * Returns the {@code 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.

      * <p/>

      * Unless overridden by

      * the {@link #setAuthenticationStrategy(AuthenticationStrategy)} method, the default implementation

      * is the {@link org.apache.shiro.authc.pam.AtLeastOneSuccessfulStrategy}.

      *

      * @return the {@code AuthenticationStrategy} utilized by this modular authenticator during a log-in attempt.

      * @since 0.2

      */

     public AuthenticationStrategy getAuthenticationStrategy() {

         return authenticationStrategy;

     }

     /**

      * Allows overriding the default {@code AuthenticationStrategy} utilized during multi-realm log-in attempts.

      * This object is only used when two or more Realms are configured.

      *

      * @param authenticationStrategy the strategy implementation to use during log-in attempts.

      * @since 0.2

      */

     public void setAuthenticationStrategy(AuthenticationStrategy authenticationStrategy) {

         this.authenticationStrategy = authenticationStrategy;

     }

     /*--------------------------------------------

     |               M E T H O D S               |

     /**

      * Used by the internal {@link #doAuthenticate} implementation to ensure that the {@code realms} property

      * has been set.  The default implementation ensures the property is not null and not empty.

      *

      * @throws IllegalStateException if the {@code realms} property is configured incorrectly.

      */

     protected void assertRealmsConfigured() throws IllegalStateException {

         Collection<Realm> realms = getRealms();

         if (CollectionUtils.isEmpty(realms)) {

             String msg = "Configuration error:  No realms have been configured!  One or more realms must be " +

                     "present to execute an authentication attempt.";

             throw new IllegalStateException(msg);

         }

     }

     /**

      * Performs the authentication attempt by interacting with the single configured realm, which is significantly

      * simpler than performing multi-realm logic.

      *

      * @param realm the realm to consult for AuthenticationInfo.

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

      * @return the AuthenticationInfo associated with the user account corresponding to the specified {@code token}

      */

     protected AuthenticationInfo doSingleRealmAuthentication(Realm realm, AuthenticationToken token) {

         if (!realm.supports(token)) {

             String msg = "Realm [" + realm + "] does not support authentication token [" +

                     token + "].  Please ensure that the appropriate Realm implementation is " +

                     "configured correctly or that the realm accepts AuthenticationTokens of this type.";

             throw new UnsupportedTokenException(msg);

         }

         AuthenticationInfo info = realm.getAuthenticationInfo(token);

         if (info == null) {

             String msg = "Realm [" + realm + "] was unable to find account data for the " +

                     "submitted AuthenticationToken [" + token + "].";

             throw new UnknownAccountException(msg);

         }

         return info;

     }

     /**

      * Performs the multi-realm authentication attempt by calling back to a {@link AuthenticationStrategy} object

      * as each realm is consulted for {@code AuthenticationInfo} for the specified {@code token}.

      *

      * @param realms the multiple realms configured on this Authenticator instance.

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

      * @return an aggregated AuthenticationInfo instance representing account data across all the successfully

      *         consulted realms.

      */

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

         AuthenticationStrategy strategy = getAuthenticationStrategy();

         AuthenticationInfo aggregate = strategy.beforeAllAttempts(realms, token);

         if (log.isTraceEnabled()) {

             log.trace("Iterating through {} realms for PAM authentication", realms.size());

         }

         for (Realm realm : realms) {

             aggregate = strategy.beforeAttempt(realm, token, aggregate);

             if (realm.supports(token)) {

                 log.trace("Attempting to authenticate token [{}] using realm [{}]", token, realm);

                 AuthenticationInfo info = null;

                 Throwable t = null;

                 try {

                     info = realm.getAuthenticationInfo(token);

                 } catch (Throwable throwable) {

                     t = throwable;

                     if (log.isWarnEnabled()) {

                         String msg = "Realm [" + realm + "] threw an exception during a multi-realm authentication attempt:";

                         log.warn(msg, t);

                     }

                 }

                 aggregate = strategy.afterAttempt(realm, token, info, aggregate, t);

             } else {

                 log.debug("Realm [{}] does not support token {}.  Skipping realm.", realm, token);

             }

         }

         aggregate = strategy.afterAllAttempts(token, aggregate);

         return aggregate;

     }

     /**

      * Attempts to authenticate the given token by iterating over the internal collection of

      * {@link Realm}s.  For each realm, first the {@link Realm#supports(org.apache.shiro.authc.AuthenticationToken)}

      * method will be called to determine if the realm supports the {@code authenticationToken} method argument.

      * <p/>

      * If a realm does support

      * the token, its {@link Realm#getAuthenticationInfo(org.apache.shiro.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 {@code null},

      * the next realm will be consulted.  If no realms support the token or all supporting realms return null,

      * an {@link AuthenticationException} will be thrown to indicate that the user could not be authenticated.

      * <p/>

      * After all realms have been consulted, the information from each realm is aggregated into a single

      * {@link AuthenticationInfo} object and returned.

      *

      * @param authenticationToken the token containing the authentication principal and credentials for the

      *                            user being authenticated.

      * @return account information attributed to the authenticated user.

      * @throws IllegalStateException   if no realms have been configured at the time this method is invoked

      * @throws AuthenticationException if the user could not be authenticated or the user is denied authentication

      *                                 for the given principal and credentials.

      */

     protected AuthenticationInfo doAuthenticate(AuthenticationToken authenticationToken) throws AuthenticationException {

         assertRealmsConfigured();

         Collection<Realm> realms = getRealms();

         if (realms.size() == 1) {

             return doSingleRealmAuthentication(realms.iterator().next(), authenticationToken);

         } else {

             return doMultiRealmAuthentication(realms, authenticationToken);

         }

     }

     /**

      * First calls <code>super.onLogout(principals)</code> to ensure a logout notification is issued, and for each

      * wrapped {@code Realm} that implements the {@link LogoutAware LogoutAware} interface, calls

      * <code>((LogoutAware)realm).onLogout(principals)</code> to allow each realm the opportunity to perform

      * logout/cleanup operations during an user-logout.

      * <p/>

      * Shiro's Realm implementations all implement the {@code LogoutAware} interface by default and can be

      * overridden for realm-specific logout logic.

      *

      * @param principals the application-specific Subject/user identifier.

      */

     public void onLogout(PrincipalCollection principals) {

         super.onLogout(principals);

         Collection<Realm> realms = getRealms();

         if (!CollectionUtils.isEmpty(realms)) {

             for (Realm realm : realms) {

                 if (realm instanceof LogoutAware) {

                     ((LogoutAware) realm).onLogout(principals);

                 }

             }

         }

     }

 }