001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.apache.shiro.authc.pam;
020
021import org.apache.shiro.authc.*;
022import org.apache.shiro.realm.Realm;
023import org.apache.shiro.subject.PrincipalCollection;
024import org.apache.shiro.util.CollectionUtils;
025import org.slf4j.Logger;
026import org.slf4j.LoggerFactory;
027
028import java.util.Collection;
029
030/**
031 * A {@code ModularRealmAuthenticator} delgates account lookups to a pluggable (modular) collection of
032 * {@link Realm}s.  This enables PAM (Pluggable Authentication Module) behavior in Shiro.
033 * In addition to authorization duties, a Shiro Realm can also be thought of a PAM 'module'.
034 * <p/>
035 * Using this Authenticator allows you to &quot;plug-in&quot; your own
036 * {@code Realm}s as you see fit.  Common realms are those based on accessing
037 * LDAP, relational databases, file systems, etc.
038 * <p/>
039 * If only one realm is configured (this is often the case for most applications), authentication success is naturally
040 * only dependent upon invoking this one Realm's
041 * {@link Realm#getAuthenticationInfo(org.apache.shiro.authc.AuthenticationToken)} method.
042 * <p/>
043 * But if two or more realms are configured, PAM behavior is implemented by iterating over the collection of realms
044 * and interacting with each over the course of the authentication attempt.  As this is more complicated, this
045 * authenticator allows customized behavior for interpreting what happens when interacting with multiple realms - for
046 * example, you might require all realms to be successful during the attempt, or perhaps only at least one must be
047 * successful, or some other interpretation.  This customized behavior can be performed via the use of a
048 * {@link #setAuthenticationStrategy(AuthenticationStrategy) AuthenticationStrategy}, which
049 * you can inject as a property of this class.
050 * <p/>
051 * The strategy object provides callback methods that allow you to
052 * determine what constitutes a success or failure in a multi-realm (PAM) scenario.  And because this only makes sense
053 * in a mult-realm scenario, the strategy object is only utilized when more than one Realm is configured.
054 * <p/>
055 * As most multi-realm applications require at least one Realm authenticates successfully, the default
056 * implementation is the {@link AtLeastOneSuccessfulStrategy}.
057 *
058 * @see #setRealms
059 * @see AtLeastOneSuccessfulStrategy
060 * @see AllSuccessfulStrategy
061 * @see FirstSuccessfulStrategy
062 * @since 0.1
063 */
064public class ModularRealmAuthenticator extends AbstractAuthenticator {
065
066    /*--------------------------------------------
067    |             C O N S T A N T S             |
068    ============================================*/
069    private static final Logger log = LoggerFactory.getLogger(ModularRealmAuthenticator.class);
070
071    /*--------------------------------------------
072    |    I N S T A N C E   V A R I A B L E S    |
073    ============================================*/
074    /**
075     * List of realms that will be iterated through when a user authenticates.
076     */
077    private Collection<Realm> realms;
078
079    /**
080     * The authentication strategy to use during authentication attempts, defaults to a
081     * {@link org.apache.shiro.authc.pam.AtLeastOneSuccessfulStrategy} instance.
082     */
083    private AuthenticationStrategy authenticationStrategy;
084
085    /*--------------------------------------------
086    |         C O N S T R U C T O R S           |
087    ============================================*/
088
089    /**
090     * Default no-argument constructor which
091     * {@link #setAuthenticationStrategy(AuthenticationStrategy) enables}  an
092     * {@link org.apache.shiro.authc.pam.AtLeastOneSuccessfulStrategy} by default.
093     */
094    public ModularRealmAuthenticator() {
095        this.authenticationStrategy = new AtLeastOneSuccessfulStrategy();
096    }
097
098    /*--------------------------------------------
099    |  A C C E S S O R S / M O D I F I E R S    |
100    ============================================*/
101
102    /**
103     * Sets all realms used by this Authenticator, providing PAM (Pluggable Authentication Module) configuration.
104     *
105     * @param realms the realms to consult during authentication attempts.
106     */
107    public void setRealms(Collection<Realm> realms) {
108        this.realms = realms;
109    }
110
111    /**
112     * Returns the realm(s) used by this {@code Authenticator} during an authentication attempt.
113     *
114     * @return the realm(s) used by this {@code Authenticator} during an authentication attempt.
115     */
116    protected Collection<Realm> getRealms() {
117        return this.realms;
118    }
119
120    /**
121     * Returns the {@code AuthenticationStrategy} utilized by this modular authenticator during a multi-realm
122     * log-in attempt.  This object is only used when two or more Realms are configured.
123     * <p/>
124     * Unless overridden by
125     * the {@link #setAuthenticationStrategy(AuthenticationStrategy)} method, the default implementation
126     * is the {@link org.apache.shiro.authc.pam.AtLeastOneSuccessfulStrategy}.
127     *
128     * @return the {@code AuthenticationStrategy} utilized by this modular authenticator during a log-in attempt.
129     * @since 0.2
130     */
131    public AuthenticationStrategy getAuthenticationStrategy() {
132        return authenticationStrategy;
133    }
134
135    /**
136     * Allows overriding the default {@code AuthenticationStrategy} utilized during multi-realm log-in attempts.
137     * This object is only used when two or more Realms are configured.
138     *
139     * @param authenticationStrategy the strategy implementation to use during log-in attempts.
140     * @since 0.2
141     */
142    public void setAuthenticationStrategy(AuthenticationStrategy authenticationStrategy) {
143        this.authenticationStrategy = authenticationStrategy;
144    }
145
146    /*--------------------------------------------
147    |               M E T H O D S               |
148
149    /**
150     * Used by the internal {@link #doAuthenticate} implementation to ensure that the {@code realms} property
151     * has been set.  The default implementation ensures the property is not null and not empty.
152     *
153     * @throws IllegalStateException if the {@code realms} property is configured incorrectly.
154     */
155
156    protected void assertRealmsConfigured() throws IllegalStateException {
157        Collection<Realm> realms = getRealms();
158        if (CollectionUtils.isEmpty(realms)) {
159            String msg = "Configuration error:  No realms have been configured!  One or more realms must be " +
160                    "present to execute an authentication attempt.";
161            throw new IllegalStateException(msg);
162        }
163    }
164
165    /**
166     * Performs the authentication attempt by interacting with the single configured realm, which is significantly
167     * simpler than performing multi-realm logic.
168     *
169     * @param realm the realm to consult for AuthenticationInfo.
170     * @param token the submitted AuthenticationToken representing the subject's (user's) log-in principals and credentials.
171     * @return the AuthenticationInfo associated with the user account corresponding to the specified {@code token}
172     */
173    protected AuthenticationInfo doSingleRealmAuthentication(Realm realm, AuthenticationToken token) {
174        if (!realm.supports(token)) {
175            String msg = "Realm [" + realm + "] does not support authentication token [" +
176                    token + "].  Please ensure that the appropriate Realm implementation is " +
177                    "configured correctly or that the realm accepts AuthenticationTokens of this type.";
178            throw new UnsupportedTokenException(msg);
179        }
180        AuthenticationInfo info = realm.getAuthenticationInfo(token);
181        if (info == null) {
182            String msg = "Realm [" + realm + "] was unable to find account data for the " +
183                    "submitted AuthenticationToken [" + token + "].";
184            throw new UnknownAccountException(msg);
185        }
186        return info;
187    }
188
189    /**
190     * Performs the multi-realm authentication attempt by calling back to a {@link AuthenticationStrategy} object
191     * as each realm is consulted for {@code AuthenticationInfo} for the specified {@code token}.
192     *
193     * @param realms the multiple realms configured on this Authenticator instance.
194     * @param token  the submitted AuthenticationToken representing the subject's (user's) log-in principals and credentials.
195     * @return an aggregated AuthenticationInfo instance representing account data across all the successfully
196     *         consulted realms.
197     */
198    protected AuthenticationInfo doMultiRealmAuthentication(Collection<Realm> realms, AuthenticationToken token) {
199
200        AuthenticationStrategy strategy = getAuthenticationStrategy();
201
202        AuthenticationInfo aggregate = strategy.beforeAllAttempts(realms, token);
203
204        if (log.isTraceEnabled()) {
205            log.trace("Iterating through {} realms for PAM authentication", realms.size());
206        }
207
208        for (Realm realm : realms) {
209
210            aggregate = strategy.beforeAttempt(realm, token, aggregate);
211
212            if (realm.supports(token)) {
213
214                log.trace("Attempting to authenticate token [{}] using realm [{}]", token, realm);
215
216                AuthenticationInfo info = null;
217                Throwable t = null;
218                try {
219                    info = realm.getAuthenticationInfo(token);
220                } catch (Throwable throwable) {
221                    t = throwable;
222                    if (log.isWarnEnabled()) {
223                        String msg = "Realm [" + realm + "] threw an exception during a multi-realm authentication attempt:";
224                        log.warn(msg, t);
225                    }
226                }
227
228                aggregate = strategy.afterAttempt(realm, token, info, aggregate, t);
229
230            } else {
231                log.debug("Realm [{}] does not support token {}.  Skipping realm.", realm, token);
232            }
233        }
234
235        aggregate = strategy.afterAllAttempts(token, aggregate);
236
237        return aggregate;
238    }
239
240
241    /**
242     * Attempts to authenticate the given token by iterating over the internal collection of
243     * {@link Realm}s.  For each realm, first the {@link Realm#supports(org.apache.shiro.authc.AuthenticationToken)}
244     * method will be called to determine if the realm supports the {@code authenticationToken} method argument.
245     * <p/>
246     * If a realm does support
247     * the token, its {@link Realm#getAuthenticationInfo(org.apache.shiro.authc.AuthenticationToken)}
248     * method will be called.  If the realm returns a non-null account, the token will be
249     * considered authenticated for that realm and the account data recorded.  If the realm returns {@code null},
250     * the next realm will be consulted.  If no realms support the token or all supporting realms return null,
251     * an {@link AuthenticationException} will be thrown to indicate that the user could not be authenticated.
252     * <p/>
253     * After all realms have been consulted, the information from each realm is aggregated into a single
254     * {@link AuthenticationInfo} object and returned.
255     *
256     * @param authenticationToken the token containing the authentication principal and credentials for the
257     *                            user being authenticated.
258     * @return account information attributed to the authenticated user.
259     * @throws IllegalStateException   if no realms have been configured at the time this method is invoked
260     * @throws AuthenticationException if the user could not be authenticated or the user is denied authentication
261     *                                 for the given principal and credentials.
262     */
263    protected AuthenticationInfo doAuthenticate(AuthenticationToken authenticationToken) throws AuthenticationException {
264        assertRealmsConfigured();
265        Collection<Realm> realms = getRealms();
266        if (realms.size() == 1) {
267            return doSingleRealmAuthentication(realms.iterator().next(), authenticationToken);
268        } else {
269            return doMultiRealmAuthentication(realms, authenticationToken);
270        }
271    }
272
273    /**
274     * First calls <code>super.onLogout(principals)</code> to ensure a logout notification is issued, and for each
275     * wrapped {@code Realm} that implements the {@link LogoutAware LogoutAware} interface, calls
276     * <code>((LogoutAware)realm).onLogout(principals)</code> to allow each realm the opportunity to perform
277     * logout/cleanup operations during an user-logout.
278     * <p/>
279     * Shiro's Realm implementations all implement the {@code LogoutAware} interface by default and can be
280     * overridden for realm-specific logout logic.
281     *
282     * @param principals the application-specific Subject/user identifier.
283     */
284    public void onLogout(PrincipalCollection principals) {
285        super.onLogout(principals);
286        Collection<Realm> realms = getRealms();
287        if (!CollectionUtils.isEmpty(realms)) {
288            for (Realm realm : realms) {
289                if (realm instanceof LogoutAware) {
290                    ((LogoutAware) realm).onLogout(principals);
291                }
292            }
293        }
294    }
295}