Class JndiLdapContextFactory

java.lang.Object
org.apache.shiro.realm.ldap.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 Details

  • Constructor Details

  • Method Details

    • setAuthenticationMechanism

      public void setAuthenticationMechanism(String authenticationMechanism)
      Sets the type of LDAP authentication mechanism to use when connecting to the LDAP server. This is a wrapper method for setting the JNDI environment template's Context.SECURITY_AUTHENTICATION property.

      "none" (i.e. anonymous) and "simple" authentications are supported automatically and don't need to be configured via this property. However, if you require a different mechanism, such as a SASL or External mechanism, you must configure that explicitly via this property. See the JNDI LDAP Authentication Mechanisms for more information.

      Parameters:
      authenticationMechanism - the type of LDAP authentication to perform.
      See Also:

    • getAuthenticationMechanism

      public String getAuthenticationMechanism()
      Returns the type of LDAP authentication mechanism to use when connecting to the LDAP server. This is a wrapper method for getting the JNDI environment template's Context.SECURITY_AUTHENTICATION property.

      If this property remains un-configured (i.e. null indicating the setAuthenticationMechanism(String) method wasn't used), this indicates that the default JNDI "none" (anonymous) and "simple" authentications are supported automatically. Any non-null value returned represents an explicitly configured mechanism (e.g. a SASL or external mechanism). See the JNDI LDAP Authentication Mechanisms for more information.

      Returns:
      the type of LDAP authentication mechanism to use when connecting to the LDAP server.
      See Also:

    • 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:

    • 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:

    • 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.

    • getSystemLdapContext

      public LdapContext getSystemLdapContext() throws NamingException
      This implementation delegates to getLdapContext(Object, Object) using the systemUsername and systemPassword properties as arguments.
      Specified by:
      getSystemLdapContext in interface LdapContextFactory
      Returns:
      the system LdapContext
      Throws:
      NamingException - if there is a problem connecting to the LDAP directory

    • 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 environment (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