Package org.apache.shiro.realm.ldap

Class JndiLdapContextFactory

  • All Implemented Interfaces:
    LdapContextFactory
    public class JndiLdapContextFactory
extends Object
implements LdapContextFactory
    LdapContextFactory implementation using the default Sun/Oracle JNDI Ldap API, utilizing JNDI environment properties and an InitialContext.

    Configuration

    This class basically wraps a default template JNDI environment properties Map. This properties map is the base configuration template used to acquire JNDI LdapContext connections at runtime. The getLdapContext(Object, Object) method implementation merges this default template with other properties accessible at runtime only (for example per-method principals and credentials). The constructed runtime map is the one used to acquire the LdapContext.

    The template can be configured directly via the getEnvironment()/setEnvironment(java.util.Map) properties directly if necessary, but it is usually more convenient to use the supporting wrapper get/set methods for various environment properties. These wrapper methods interact with the environment template on your behalf, leaving your configuration cleaner and easier to understand.

    For example, consider the following two identical configurations: 
     [main]
 ldapRealm = org.apache.shiro.realm.ldap.DefaultLdapRealm
 ldapRealm.contextFactory.url = ldap://localhost:389
 ldapRealm.contextFactory.authenticationMechanism = DIGEST-MD5
    and 
     [main]
 ldapRealm = org.apache.shiro.realm.ldap.DefaultLdapRealm
 ldapRealm.contextFactory.environment[java.naming.provider.url] = ldap://localhost:389
 ldapRealm.contextFactory.environment[java.naming.security.authentication] = DIGEST-MD5
    As you can see, the 2nd configuration block is a little more difficult to read and also requires knowledge of the underlying JNDI Context property keys. The first is easier to read and understand.

    Note that occasionally it will be necessary to use the latter configuration style to set environment properties where no corresponding wrapper method exists. In this case, the hybrid approach is still a little easier to read. For example: 
     [main]
 ldapRealm = org.apache.shiro.realm.ldap.DefaultLdapRealm
 ldapRealm.contextFactory.url = ldap://localhost:389
 ldapRealm.contextFactory.authenticationMechanism = DIGEST-MD5
 ldapRealm.contextFactory.environment[some.other.obscure.jndi.key] = some value
    Since:
    1.1

    • Field Detail

      • SUN_CONNECTION_POOLING_PROPERTY

        protected static final String SUN_CONNECTION_POOLING_PROPERTY
        The Sun LDAP property used to enable connection pooling. This is used in the default implementation to enable LDAP connection pooling.
        See Also:
        Constant Field Values

      • SIMPLE_AUTHENTICATION_MECHANISM_NAME

        protected static final String SIMPLE_AUTHENTICATION_MECHANISM_NAME
        See Also:
        Constant Field Values

    • Constructor Detail

      • JndiLdapContextFactory

        public JndiLdapContextFactory()
        Default no-argument constructor that initializes the backing environment template with the contextFactoryClassName equal to com.sun.jndi.ldap.LdapCtxFactory (the Sun/Oracle default) and the default referral behavior to follow.

    • Method Detail

      • setContextFactoryClassName

        public void setContextFactoryClassName(String contextFactoryClassName)
        The name of the ContextFactory class to use. This defaults to the SUN LDAP JNDI implementation but can be overridden to use custom LDAP factories.

        This is a wrapper method for setting the JNDI environment's Context.INITIAL_CONTEXT_FACTORY property.
        Parameters:
        contextFactoryClassName - the context factory that should be used.

      • getContextFactoryClassName

        public String getContextFactoryClassName()
        Sets the name of the ContextFactory class to use. This defaults to the SUN LDAP JNDI implementation but can be overridden to use custom LDAP factories.

        This is a wrapper method for getting the JNDI environment's Context.INITIAL_CONTEXT_FACTORY property.
        Returns:
        the name of the ContextFactory class to use.

      • getEnvironment

        public Map getEnvironment()
        Returns the base JNDI environment template to use when acquiring an LDAP connection (an LdapContext). This property is the base configuration template to use for all connections. This template is then merged with appropriate runtime values as necessary in the getLdapContext(Object, Object) implementation. The merged environment instance is what is used to acquire the LdapContext at runtime.

        Most other get/set methods in this class act as thin proxy wrappers that interact with this property. The benefit of using them is you have an easier-to-use configuration mechanism compared to setting map properties based on JNDI context keys.
        Returns:
        the base JNDI environment template to use when acquiring an LDAP connection (an LdapContext)

      • setEnvironment

        public void setEnvironment(Map env)
        Sets the base JNDI environment template to use when acquiring LDAP connections. It is typically more common to use the other get/set methods in this class to set individual environment settings rather than use this method, but it is available for advanced users that want full control over the base JNDI environment settings.

        Note that this template only represents the base/default environment settings. It is then merged with appropriate runtime values as necessary in the getLdapContext(Object, Object) implementation. The merged environment instance is what is used to acquire the connection (LdapContext) at runtime.
        Parameters:
        env - the base JNDI environment template to use when acquiring LDAP connections.

      • isPoolingEnabled

        public boolean isPoolingEnabled()
        Returns whether or not connection pooling should be used when possible and appropriate. This property is NOT backed by the environment template like most other properties in this class. It is a flag to indicate that pooling is preferred. The default value is true.

        However, pooling will only actually be enabled if this property is true and the connection being created is for the systemUsername user. Connection pooling is not used for general authentication attempts by application end-users because the probability of re-use for that same user-specific connection after an authentication attempt is extremely low.

        If this attribute is true and it has been determined that the connection is being made with the systemUsername, the getLdapContext(Object, Object) implementation will set the Sun/Oracle-specific com.sun.jndi.ldap.connect.pool environment property to "true". This means setting this property is only likely to work if using the Sun/Oracle default context factory class (i.e. not using a custom contextFactoryClassName).
        Returns:
        whether or not connection pooling should be used when possible and appropriate

      • setPoolingEnabled

        public void setPoolingEnabled(boolean poolingEnabled)
        Sets whether or not connection pooling should be used when possible and appropriate. This property is NOT a wrapper to the environment template like most other properties in this class. It is a flag to indicate that pooling is preferred. The default value is true.

        However, pooling will only actually be enabled if this property is true and the connection being created is for the systemUsername user. Connection pooling is not used for general authentication attempts by application end-users because the probability of re-use for that same user-specific connection after an authentication attempt is extremely low.

        If this attribute is true and it has been determined that the connection is being made with the systemUsername, the getLdapContext(Object, Object) implementation will set the Sun/Oracle-specific com.sun.jndi.ldap.connect.pool environment property to "true". This means setting this property is only likely to work if using the Sun/Oracle default context factory class (i.e. not using a custom contextFactoryClassName).
        Parameters:
        poolingEnabled - whether or not connection pooling should be used when possible and appropriate

      • setReferral

        public void setReferral(String referral)
        Sets the LDAP referral behavior when creating a connection. Defaults to follow. See the Sun/Oracle LDAP referral documentation for more.
        Parameters:
        referral - the referral property.
        See Also:
        Referrals in JNDI

      • getReferral

        public String getReferral()
        Returns the LDAP referral behavior when creating a connection. Defaults to follow. See the Sun/Oracle LDAP referral documentation for more.
        Returns:
        the LDAP referral behavior when creating a connection.
        See Also:
        Referrals in JNDI

      • setUrl

        public void setUrl(String url)
        The LDAP url to connect to. (e.g. ldap://<ldapDirectoryHostname>:<port>). This must be configured.
        Parameters:
        url - the LDAP url to connect to. (e.g. ldap://<ldapDirectoryHostname>:<port>)

      • getUrl

        public String getUrl()
        Returns the LDAP url to connect to. (e.g. ldap://<ldapDirectoryHostname>:<port>). This must be configured.
        Returns:
        the LDAP url to connect to. (e.g. ldap://<ldapDirectoryHostname>:<port>)

      • setSystemPassword

        public void setSystemPassword(String systemPassword)
        Sets the password of the systemUsername that will be used when creating an LDAP connection used for authorization queries.

        Note that setting this property is not required if the calling LDAP Realm does not perform authorization checks.
        Parameters:
        systemPassword - the password of the systemUsername that will be used when creating an LDAP connection used for authorization queries.

      • getSystemPassword

        public String getSystemPassword()
        Returns the password of the systemUsername that will be used when creating an LDAP connection used for authorization queries.

        Note that setting this property is not required if the calling LDAP Realm does not perform authorization checks.
        Returns:
        the password of the systemUsername that will be used when creating an LDAP connection used for authorization queries.

      • setSystemUsername

        public void setSystemUsername(String systemUsername)
        Sets the system username that will be used when creating an LDAP connection used for authorization queries. The user must have the ability to query for authorization data for any application user.

        Note that setting this property is not required if the calling LDAP Realm does not perform authorization checks.
        Parameters:
        systemUsername - the system username that will be used when creating an LDAP connection used for authorization queries.

      • getSystemUsername

        public String getSystemUsername()
        Returns the system username that will be used when creating an LDAP connection used for authorization queries. The user must have the ability to query for authorization data for any application user.

        Note that setting this property is not required if the calling LDAP Realm does not perform authorization checks.
        Returns:
        the system username that will be used when creating an LDAP connection used for authorization queries.

      • getLdapContext

        @Deprecated
public LdapContext getLdapContext(String username,
                                  String password)
                           throws NamingException
        Deprecated.
        the getLdapContext(Object, Object) method should be used in all cases to ensure more than String principals and credentials can be used. Shiro no longer calls this method - it will be removed before the 2.0 release.
        Deprecated - use getLdapContext(Object, Object) instead. This will be removed before Apache Shiro 2.0.
        Specified by:
        getLdapContext in interface LdapContextFactory
        Parameters:
        username - the username to use when creating the connection.
        password - the password to use when creating the connection.
        Returns:
        a LdapContext bound using the given username and password.
        Throws:
        NamingException - if there is an error creating the context.

      • isPoolingConnections

        protected boolean isPoolingConnections(Object principal)
        Returns true if LDAP connection pooling should be used when acquiring a connection based on the specified account principal, false otherwise.

        This implementation returns true only if isPoolingEnabled() and the principal equals the getSystemUsername(). The reasoning behind this is that connection pooling is not desirable for general authentication attempts by application end-users because the probability of re-use for that same user-specific connection after an authentication attempt is extremely low.
        Parameters:
        principal - the principal under which the connection will be made
        Returns:
        true if LDAP connection pooling should be used when acquiring a connection based on the specified account principal, false otherwise.

      • getLdapContext

        public LdapContext getLdapContext(Object principal,
                                  Object credentials)
                           throws NamingException,
                                  IllegalStateException
        This implementation returns an LdapContext based on the configured JNDI/LDAP environment configuration. The environnmet (Map) used at runtime is created by merging the default/configured environment template with some runtime values as necessary (e.g. a principal and credential available at runtime only).

        After the merged Map instance is created, the LdapContext connection is created and returned.
        Specified by:
        getLdapContext in interface LdapContextFactory
        Parameters:
        principal - the principal to use when acquiring a connection to the LDAP directory
        credentials - the credentials (password, X.509 certificate, etc) to use when acquiring a connection to the LDAP directory
        Returns:
        the acquired LdapContext connection bound using the specified principal and credentials.
        Throws:
        NamingException
        IllegalStateException

      • createLdapContext

        protected LdapContext createLdapContext(Hashtable env)
                                 throws NamingException
        Creates and returns a new InitialLdapContext instance. This method exists primarily to support testing where a mock LdapContext can be returned instead of actually creating a connection, but subclasses are free to provide a different implementation if necessary.
        Parameters:
        env - the JNDI environment settings used to create the LDAP connection
        Returns:
        an LdapConnection
        Throws:
        NamingException - if a problem occurs creating the connection

      • validateAuthenticationInfo

        protected void validateAuthenticationInfo(Hashtable<String,Object> environment)
                                   throws AuthenticationException
        Validates the configuration in the JNDI environment settings and throws an exception if a problem exists.

        This implementation will throw a AuthenticationException if the authentication mechanism is set to 'simple', the principal is non-empty, and the credentials are empty (as per rfc4513 section-5.1.2).
        Parameters:
        environment - the JNDI environment settings to be validated
        Throws:
        AuthenticationException - if a configuration problem is detected