| /* |
| * 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); |
| } |
| } |
| } |
| } |
| } |
