/*

  * 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.realm.ldap;

 import org.apache.shiro.authc.AuthenticationException;

 import org.apache.shiro.authc.AuthenticationInfo;

 import org.apache.shiro.authc.AuthenticationToken;

 import org.apache.shiro.authc.SimpleAuthenticationInfo;

 import org.apache.shiro.authc.credential.AllowAllCredentialsMatcher;

 import org.apache.shiro.authz.AuthorizationException;

 import org.apache.shiro.authz.AuthorizationInfo;

 import org.apache.shiro.ldap.UnsupportedAuthenticationMechanismException;

 import org.apache.shiro.realm.AuthorizingRealm;

 import org.apache.shiro.subject.PrincipalCollection;

 import org.apache.shiro.util.StringUtils;

 import org.slf4j.Logger;

 import org.slf4j.LoggerFactory;

 import javax.naming.AuthenticationNotSupportedException;

 import javax.naming.NamingException;

 import javax.naming.ldap.LdapContext;

 /**

  * An LDAP {@link org.apache.shiro.realm.Realm Realm} implementation utilizing Sun's/Oracle's

  * <a href="http://download-llnw.oracle.com/javase/tutorial/jndi/ldap/jndi.html">JNDI API as an LDAP API</a>.  This is

  * Shiro's default implementation for supporting LDAP, as using the JNDI API has been a common approach for Java LDAP

  * support for many years.

  * <p/>

  * This realm implementation and its backing {@link JndiLdapContextFactory} should cover 99% of all Shiro-related LDAP

  * authentication and authorization needs.  However, if it does not suit your needs, you might want to look into

  * creating your own realm using an alternative, perhaps more robust, LDAP communication API, such as the

  * <a href="http://directory.apache.org/api/">Apache LDAP API</a>.

  * <h2>Authentication</h2>

  * During an authentication attempt, if the submitted {@code AuthenticationToken}'s

  * {@link org.apache.shiro.authc.AuthenticationToken#getPrincipal() principal} is a simple username, but the

  * LDAP directory expects a complete User Distinguished Name (User DN) to establish a connection, the

  * {@link #setUserDnTemplate(String) userDnTemplate} property must be configured.  If not configured,

  * the property will pass the simple username directly as the User DN, which is often incorrect in most LDAP

  * environments (maybe Microsoft ActiveDirectory being the exception).

  * <h2>Authorization</h2>

  * By default, authorization is effectively disabled due to the default

  * {@link #doGetAuthorizationInfo(org.apache.shiro.subject.PrincipalCollection)} implementation returning {@code null}.

  * If you wish to perform authorization based on an LDAP schema, you must subclass this one

  * and override that method to reflect your organization's data model.

  * <h2>Configuration</h2>

  * This class primarily provides the {@link #setUserDnTemplate(String) userDnTemplate} property to allow you to specify

  * the your LDAP server's User DN format.  Most other configuration is performed via the nested

  * {@link LdapContextFactory contextFactory} property.

  * <p/>

  * For example, defining this realm in Shiro .ini:

  * <pre>

  * [main]

  * ldapRealm = org.apache.shiro.realm.ldap.JndiLdapRealm

  * ldapRealm.userDnTemplate = uid={0},ou=users,dc=mycompany,dc=com

  * ldapRealm.contextFactory.url = ldap://ldapHost:389

  * ldapRealm.contextFactory.authenticationMechanism = DIGEST-MD5

  * ldapRealm.contextFactory.environment[some.obscure.jndi.key] = some value

  * ...

  * </pre>

  * The default {@link #setContextFactory contextFactory} instance is a {@link JndiLdapContextFactory}.  See that

  * class's JavaDoc for more information on configuring the LDAP connection as well as specifying JNDI environment

  * properties as necessary.

  *

  * @see JndiLdapContextFactory

  *

  * @since 1.1

  */

 public class JndiLdapRealm extends AuthorizingRealm {

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

     //The zero index currently means nothing, but could be utilized in the future for other substitution techniques.

     private static final String USERDN_SUBSTITUTION_TOKEN = "{0}";

     private String userDnPrefix;

     private String userDnSuffix;

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

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

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

     /**

      * The LdapContextFactory instance used to acquire {@link javax.naming.ldap.LdapContext LdapContext}'s at runtime

      * to acquire connections to the LDAP directory to perform authentication attempts and authorizatino queries.

      */

     private LdapContextFactory contextFactory;

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

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

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

     /**

      * Default no-argument constructor that defaults the internal {@link LdapContextFactory} instance to a

      * {@link JndiLdapContextFactory}.

      */

     public JndiLdapRealm() {

         //Credentials Matching is not necessary - the LDAP directory will do it automatically:

         setCredentialsMatcher(new AllowAllCredentialsMatcher());

         //Any Object principal and Object credentials may be passed to the LDAP provider, so accept any token:

         setAuthenticationTokenClass(AuthenticationToken.class);

         this.contextFactory = new JndiLdapContextFactory();

     }

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

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

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

     /**

      * Returns the User DN prefix to use when building a runtime User DN value or {@code null} if no

      * {@link #getUserDnTemplate() userDnTemplate} has been configured.  If configured, this value is the text that

      * occurs before the {@link #USERDN_SUBSTITUTION_TOKEN} in the {@link #getUserDnTemplate() userDnTemplate} value.

      *

      * @return the the User DN prefix to use when building a runtime User DN value or {@code null} if no

      *         {@link #getUserDnTemplate() userDnTemplate} has been configured.

      */

     protected String getUserDnPrefix() {

         return userDnPrefix;

     }

     /**

      * Returns the User DN suffix to use when building a runtime User DN value.  or {@code null} if no

      * {@link #getUserDnTemplate() userDnTemplate} has been configured.  If configured, this value is the text that

      * occurs after the {@link #USERDN_SUBSTITUTION_TOKEN} in the {@link #getUserDnTemplate() userDnTemplate} value.

      *

      * @return the User DN suffix to use when building a runtime User DN value or {@code null} if no

      *         {@link #getUserDnTemplate() userDnTemplate} has been configured.

      */

     protected String getUserDnSuffix() {

         return userDnSuffix;

     }

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

     |               M E T H O D S               |

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

     /**

      * Sets the User Distinguished Name (DN) template to use when creating User DNs at runtime.  A User DN is an LDAP

      * fully-qualified unique user identifier which is required to establish a connection with the LDAP

      * directory to authenticate users and query for authorization information.

      * <h2>Usage</h2>

      * User DN formats are unique to the LDAP directory's schema, and each environment differs - you will need to

      * specify the format corresponding to your directory.  You do this by specifying the full User DN as normal, but

      * but you use a <b>{@code {0}}</b> placeholder token in the string representing the location where the

      * user's submitted principal (usually a username or uid) will be substituted at runtime.

      * <p/>

      * For example,  if your directory

      * uses an LDAP {@code uid} attribute to represent usernames, the User DN for the {@code jsmith} user may look like

      * this:

      * <p/>

      * <pre>uid=jsmith,ou=users,dc=mycompany,dc=com</pre>

      * <p/>

      * in which case you would set this property with the following template value:

      * <p/>

      * <pre>uid=<b>{0}</b>,ou=users,dc=mycompany,dc=com</pre>

      * <p/>

      * If no template is configured, the raw {@code AuthenticationToken}

      * {@link AuthenticationToken#getPrincipal() principal} will be used as the LDAP principal.  This is likely

      * incorrect as most LDAP directories expect a fully-qualified User DN as opposed to the raw uid or username.  So,

      * ensure you set this property to match your environment!

      *

      * @param template the User Distinguished Name template to use for runtime substitution

      * @throws IllegalArgumentException if the template is null, empty, or does not contain the

      *                                  {@code {0}} substitution token.

      * @see LdapContextFactory#getLdapContext(Object,Object)

      */

     public void setUserDnTemplate(String template) throws IllegalArgumentException {

         if (!StringUtils.hasText(template)) {

             String msg = "User DN template cannot be null or empty.";

             throw new IllegalArgumentException(msg);

         }

         int index = template.indexOf(USERDN_SUBSTITUTION_TOKEN);

         if (index < 0) {

             String msg = "User DN template must contain the '" +

                     USERDN_SUBSTITUTION_TOKEN + "' replacement token to understand where to " +

                     "insert the runtime authentication principal.";

             throw new IllegalArgumentException(msg);

         }

         String prefix = template.substring(0, index);

         String suffix = template.substring(prefix.length() + USERDN_SUBSTITUTION_TOKEN.length());

         if (log.isDebugEnabled()) {

             log.debug("Determined user DN prefix [{}] and suffix [{}]", prefix, suffix);

         }

         this.userDnPrefix = prefix;

         this.userDnSuffix = suffix;

     }

     /**

      * Returns the User Distinguished Name (DN) template to use when creating User DNs at runtime - see the

      * {@link #setUserDnTemplate(String) setUserDnTemplate} JavaDoc for a full explanation.

      *

      * @return the User Distinguished Name (DN) template to use when creating User DNs at runtime.

      */

     public String getUserDnTemplate() {

         return getUserDn(USERDN_SUBSTITUTION_TOKEN);

     }

     /**

      * Returns the LDAP User Distinguished Name (DN) to use when acquiring an

      * {@link javax.naming.ldap.LdapContext LdapContext} from the {@link LdapContextFactory}.

      * <p/>

      * If the the {@link #getUserDnTemplate() userDnTemplate} property has been set, this implementation will construct

      * the User DN by substituting the specified {@code principal} into the configured template.  If the

      * {@link #getUserDnTemplate() userDnTemplate} has not been set, the method argument will be returned directly

      * (indicating that the submitted authentication token principal <em>is</em> the User DN).

      *

      * @param principal the principal to substitute into the configured {@link #getUserDnTemplate() userDnTemplate}.

      * @return the constructed User DN to use at runtime when acquiring an {@link javax.naming.ldap.LdapContext}.

      * @throws IllegalArgumentException if the method argument is null or empty

      * @throws IllegalStateException    if the {@link #getUserDnTemplate userDnTemplate} has not been set.

      * @see LdapContextFactory#getLdapContext(Object, Object)

      */

     protected String getUserDn(String principal) throws IllegalArgumentException, IllegalStateException {

         if (!StringUtils.hasText(principal)) {

             throw new IllegalArgumentException("User principal cannot be null or empty for User DN construction.");

         }

         String prefix = getUserDnPrefix();

         String suffix = getUserDnSuffix();

         if (prefix == null && suffix == null) {

             log.debug("userDnTemplate property has not been configured, indicating the submitted " +

                     "AuthenticationToken's principal is the same as the User DN.  Returning the method argument " +

                     "as is.");

             return principal;

         }

         int prefixLength = prefix != null ? prefix.length() : 0;

         int suffixLength = suffix != null ? suffix.length() : 0;

         StringBuilder sb = new StringBuilder(prefixLength + principal.length() + suffixLength);

         if (prefixLength > 0) {

             sb.append(prefix);

         }

         sb.append(principal);

         if (suffixLength > 0) {

             sb.append(suffix);

         }

         return sb.toString();

     }

     /**

      * Sets the LdapContextFactory instance used to acquire connections to the LDAP directory during authentication

      * attempts and authorization queries.  Unless specified otherwise, the default is a {@link JndiLdapContextFactory}

      * instance.

      *

      * @param contextFactory the LdapContextFactory instance used to acquire connections to the LDAP directory during

      *                       authentication attempts and authorization queries

      */

     @SuppressWarnings({"UnusedDeclaration"})

     public void setContextFactory(LdapContextFactory contextFactory) {

         this.contextFactory = contextFactory;

     }

     /**

      * Returns the LdapContextFactory instance used to acquire connections to the LDAP directory during authentication

      * attempts and authorization queries.  Unless specified otherwise, the default is a {@link JndiLdapContextFactory}

      * instance.

      *

      * @return the LdapContextFactory instance used to acquire connections to the LDAP directory during

      *         authentication attempts and authorization queries

      */

     public LdapContextFactory getContextFactory() {

         return this.contextFactory;

     }

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

     |               M E T H O D S                |

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

     /**

      * Delegates to {@link #queryForAuthenticationInfo(org.apache.shiro.authc.AuthenticationToken, LdapContextFactory)},

      * wrapping any {@link NamingException}s in a Shiro {@link AuthenticationException} to satisfy the parent method

      * signature.

      *

      * @param token the authentication token containing the user's principal and credentials.

      * @return the {@link AuthenticationInfo} acquired after a successful authentication attempt

      * @throws AuthenticationException if the authentication attempt fails or if a

      *                                 {@link NamingException} occurs.

      */

     protected AuthenticationInfo doGetAuthenticationInfo(AuthenticationToken token) throws AuthenticationException {

         AuthenticationInfo info;

         try {

             info = queryForAuthenticationInfo(token, getContextFactory());

         } catch (AuthenticationNotSupportedException e) {

             String msg = "Unsupported configured authentication mechanism";

             throw new UnsupportedAuthenticationMechanismException(msg, e);

         } catch (javax.naming.AuthenticationException e) {

             throw new AuthenticationException("LDAP authentication failed.", e);

         } catch (NamingException e) {

             String msg = "LDAP naming error while attempting to authenticate user.";

             throw new AuthenticationException(msg, e);

         }

         return info;

     }

     protected AuthorizationInfo doGetAuthorizationInfo(PrincipalCollection principals) {

         AuthorizationInfo info;

         try {

             info = queryForAuthorizationInfo(principals, getContextFactory());

         } catch (NamingException e) {

             String msg = "LDAP naming error while attempting to retrieve authorization for user [" + principals + "].";

             throw new AuthorizationException(msg, e);

         }

         return info;

     }

     /**

      * Returns the principal to use when creating the LDAP connection for an authentication attempt.

      * <p/>

      * This implementation uses a heuristic: it checks to see if the specified token's

      * {@link AuthenticationToken#getPrincipal() principal} is a {@code String}, and if so,

      * {@link #getUserDn(String) converts it} from what is

      * assumed to be a raw uid or username {@code String} into a User DN {@code String}.  Almost all LDAP directories

      * expect the authentication connection to present a User DN and not an unqualified username or uid.

      * <p/>

      * If the token's {@code principal} is not a String, it is assumed to already be in the format supported by the

      * underlying {@link LdapContextFactory} implementation and the raw principal is returned directly.

      *

      * @param token the {@link AuthenticationToken} submitted during the authentication process

      * @return the User DN or raw principal to use to acquire the LdapContext.

      * @see LdapContextFactory#getLdapContext(Object, Object)

      */

     protected Object getLdapPrincipal(AuthenticationToken token) {

         Object principal = token.getPrincipal();

         if (principal instanceof String) {

             String sPrincipal = (String) principal;

             return getUserDn(sPrincipal);

         }

         return principal;

     }

     /**

      * This implementation opens an LDAP connection using the token's

      * {@link #getLdapPrincipal(org.apache.shiro.authc.AuthenticationToken) discovered principal} and provided

      * {@link AuthenticationToken#getCredentials() credentials}.  If the connection opens successfully, the

      * authentication attempt is immediately considered successful and a new

      * {@link AuthenticationInfo} instance is

      * {@link #createAuthenticationInfo(org.apache.shiro.authc.AuthenticationToken, Object, Object, javax.naming.ldap.LdapContext) created}

      * and returned.  If the connection cannot be opened, either because LDAP authentication failed or some other

      * JNDI problem, an {@link NamingException} will be thrown.

      *

      * @param token              the submitted authentication token that triggered the authentication attempt.

      * @param ldapContextFactory factory used to retrieve LDAP connections.

      * @return an {@link AuthenticationInfo} instance representing the authenticated user's information.

      * @throws NamingException if any LDAP errors occur.

      */

     protected AuthenticationInfo queryForAuthenticationInfo(AuthenticationToken token,

                                                             LdapContextFactory ldapContextFactory)

             throws NamingException {

         Object principal = token.getPrincipal();

         Object credentials = token.getCredentials();

         log.debug("Authenticating user '{}' through LDAP", principal);

         principal = getLdapPrincipal(token);

         LdapContext ctx = null;

         try {

             ctx = ldapContextFactory.getLdapContext(principal, credentials);

             //context was opened successfully, which means their credentials were valid.  Return the AuthenticationInfo:

             return createAuthenticationInfo(token, principal, credentials, ctx);

         } finally {

             LdapUtils.closeContext(ctx);

         }

     }

     /**

      * Returns the {@link AuthenticationInfo} resulting from a Subject's successful LDAP authentication attempt.

      * <p/>

      * This implementation ignores the {@code ldapPrincipal}, {@code ldapCredentials}, and the opened

      * {@code ldapContext} arguments and merely returns an {@code AuthenticationInfo} instance mirroring the

      * submitted token's principal and credentials.  This is acceptable because this method is only ever invoked after

      * a successful authentication attempt, which means the provided principal and credentials were correct, and can

      * be used directly to populate the (now verified) {@code AuthenticationInfo}.

      * <p/>

      * Subclasses however are free to override this method for more advanced construction logic.

      *

      * @param token           the submitted {@code AuthenticationToken} that resulted in a successful authentication

      * @param ldapPrincipal   the LDAP principal used when creating the LDAP connection.  Unlike the token's

      *                        {@link AuthenticationToken#getPrincipal() principal}, this value is usually a constructed

      *                        User DN and not a simple username or uid.  The exact value is depending on the

      *                        configured

      *                        <a href="http://download-llnw.oracle.com/javase/tutorial/jndi/ldap/auth_mechs.html">

      *                        LDAP authentication mechanism</a> in use.

      * @param ldapCredentials the LDAP credentials used when creating the LDAP connection.

      * @param ldapContext     the LdapContext created that resulted in a successful authentication.  It can be used

      *                        further by subclasses for more complex operations.  It does not need to be closed -

      *                        it will be closed automatically after this method returns.

      * @return the {@link AuthenticationInfo} resulting from a Subject's successful LDAP authentication attempt.

      * @throws NamingException if there was any problem using the {@code LdapContext}

      */

     @SuppressWarnings({"UnusedDeclaration"})

     protected AuthenticationInfo createAuthenticationInfo(AuthenticationToken token, Object ldapPrincipal,

                                                           Object ldapCredentials, LdapContext ldapContext)

             throws NamingException {

         return new SimpleAuthenticationInfo(token.getPrincipal(), token.getCredentials(), getName());

     }

     /**

      * Method that should be implemented by subclasses to build an

      * {@link AuthorizationInfo} object by querying the LDAP context for the

      * specified principal.</p>

      *

      * @param principals          the principals of the Subject whose AuthenticationInfo should be queried from the LDAP server.

      * @param ldapContextFactory factory used to retrieve LDAP connections.

      * @return an {@link AuthorizationInfo} instance containing information retrieved from the LDAP server.

      * @throws NamingException if any LDAP errors occur during the search.

      */

     protected AuthorizationInfo queryForAuthorizationInfo(PrincipalCollection principals,

                                                           LdapContextFactory ldapContextFactory) throws NamingException {

         return null;

     }

 }