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     */
019    package org.apache.shiro.authc.pam;
020    
021    import org.apache.shiro.authc.*;
022    import org.apache.shiro.realm.Realm;
023    import org.apache.shiro.subject.PrincipalCollection;
024    import org.apache.shiro.util.CollectionUtils;
025    import org.slf4j.Logger;
026    import org.slf4j.LoggerFactory;
027    
028    import 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     */
064    public 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.isDebugEnabled()) {
223                            String msg = "Realm [" + realm + "] threw an exception during a multi-realm authentication attempt:";
224                            log.debug(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    }