org.apache.shiro.realm.ldap
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.JndiLdapRealm
 ldapRealm.contextFactory.url = ldap://localhost:389
 ldapRealm.contextFactory.authenticationMechanism = DIGEST-MD5
 

and

 [main]
 ldapRealm = org.apache.shiro.realm.ldap.JndiLdapRealm
 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.JndiLdapRealm
 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 Summary

protected static String	DEFAULT_CONTEXT_FACTORY_CLASS_NAME
protected static String	DEFAULT_REFERRAL
protected static String	SIMPLE_AUTHENTICATION_MECHANISM_NAME
protected static String	SUN_CONNECTION_POOLING_PROPERTY The Sun LDAP property used to enable connection pooling.

Constructor Summary

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 Summary

protected LdapContext	createLdapContext(Hashtable env) Creates and returns a new InitialLdapContext instance.
String	getAuthenticationMechanism() Returns the type of LDAP authentication mechanism to use when connecting to the LDAP server.
String	getContextFactoryClassName() Sets the name of the ContextFactory class to use.
Map	getEnvironment() Returns the base JNDI environment template to use when acquiring an LDAP connection (an LdapContext).
LdapContext	getLdapContext(Object principal, Object credentials) This implementation returns an LdapContext based on the configured JNDI/LDAP environment configuration.
LdapContext	getLdapContext(String username, String password) 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.
String	getReferral() Returns the LDAP referral behavior when creating a connection.
LdapContext	getSystemLdapContext() This implementation delegates to getLdapContext(Object, Object) using the systemUsername and systemPassword properties as arguments.
String	getSystemPassword() Returns the password of the systemUsername that will be used when creating an LDAP connection used for authorization queries.
String	getSystemUsername() Returns the system username that will be used when creating an LDAP connection used for authorization queries.
String	getUrl() Returns the LDAP url to connect to.
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.
boolean	isPoolingEnabled() Returns whether or not connection pooling should be used when possible and appropriate.
void	setAuthenticationMechanism(String authenticationMechanism) Sets the type of LDAP authentication mechanism to use when connecting to the LDAP server.
void	setContextFactoryClassName(String contextFactoryClassName) The name of the ContextFactory class to use.
void	setEnvironment(Map env) Sets the base JNDI environment template to use when acquiring LDAP connections.
void	setPoolingEnabled(boolean poolingEnabled) Sets whether or not connection pooling should be used when possible and appropriate.
void	setReferral(String referral) Sets the LDAP referral behavior when creating a connection.
void	setSystemPassword(String systemPassword) Sets the password of the systemUsername that will be used when creating an LDAP connection used for authorization queries.
void	setSystemUsername(String systemUsername) Sets the system username that will be used when creating an LDAP connection used for authorization queries.
void	setUrl(String url) The LDAP url to connect to.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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

DEFAULT_CONTEXT_FACTORY_CLASS_NAME

protected static final String DEFAULT_CONTEXT_FACTORY_CLASS_NAME

See Also:

Constant Field Values

SIMPLE_AUTHENTICATION_MECHANISM_NAME

protected static final String SIMPLE_AUTHENTICATION_MECHANISM_NAME

See Also:

Constant Field Values

DEFAULT_REFERRAL

protected static final String DEFAULT_REFERRAL

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

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:

http://download-llnw.oracle.com/javase/tutorial/jndi/ldap/auth_mechs.html

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:

http://download-llnw.oracle.com/javase/tutorial/jndi/ldap/auth_mechs.html

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.

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

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