com.sun.slamd.realm
Class LDAPRealm

java.lang.Object
  org.apache.catalina.realm.RealmBase
      com.sun.slamd.realm.LDAPRealm

All Implemented Interfaces:

org.apache.catalina.Lifecycle, javax.management.MBeanRegistration, org.apache.catalina.Realm

public class LDAPRealm

extends org.apache.catalina.realm.RealmBase

This class implements a Tomcat Realm that allows authentication against an LDAP directory server. It overcomes many of the limitations of the JNDIRealm implementation provided by default (e.g., this version does not require the login ID attribute to be included in the DN), implements caching (so that it's not necessary to query the directory every time a new page is loaded), and provides support for verifying that the user is a member of a specified static group, dynamic group, or role in addition to verifying that the credentials are valid.

The configurable parameters for this realm are:

• ldapHost -- The address of the directory server in which the user entries are stored. This is required to have a value.
• ldapPort -- The port number of the directory server in which the user entries are stored. This value must be between 1 and 65535.
• bindDN -- The DN that should be used to bind to the directory to find user entries and make membership determinations. If left blank, then those operations will be performed anonymously.
• bindPassword -- The password for the bind DN. If left blank, then the search and membership determination will be performed anonymously.
• userBase -- The DN of the base entry below which user entries exist in the directory server. This is required to have a value. If a membership DN is specified, then it does not need to be below this base.
• membershipDN -- The DN of a static group, dynamic group, or role in which a user must be a member in order to be authenticated. If this is left blank, then no membership check will be performed (i.e., any user that is in the directory and provides a valid password will be granted access).
• loginIDAttribute -- The name of the LDAP attribute that will be queried to find user entries based on the value of the login ID provided.
• useSSL -- Indicates whether the communication with the LDAP directory server will use SSL. The value must be either "true" or "false".
• blindTrust -- Indicates whether to blindly trust any SSL certificate presented by the directory server. The value must be either "true" or "false".
• sslKeyStore -- The location of the JSSE key store file to use if SSL is enabled.
• sslKeyPassword -- The password to use when accessing the JSSE key store if SSL is enabled.
• sslTrustStore -- The location of the JSSE trust store file to use if SSL is enabled.
• sslTrustPassword -- The password to use when accessing the JSSE trust store if SSL is enabled.

Field Summary

protected java.lang.String	bindDN The DN that will be used to bind to the user directory to find user accounts.
protected java.lang.String	bindPassword The password for the bind DN.
protected boolean	blindTrust The flag that indicates whether to blindly trust any SSL certificate presented by the directory server.
static int	CACHE_CLEANUP_INTERVAL The interval in milliseconds over which the cache needs to be cleaned.
static int	CACHE_EXPIRATION_TIME The length of time in milliseconds that user information should stay in the user cache before being reloaded from the directory.
protected java.lang.String	ldapHost The address to use when connecting to the user directory.
protected java.lang.String	ldapPort The port number that will be used to contact the user directory.
protected java.lang.String	loginIDAttribute The name of the LDAP attribute that will be used to find user entries based on the provided user name.
static java.lang.String	MEMBER_URL_ATTRIBUTE The name of the LDAP attribute that holds the LDAP URL used to hold the criteria for membership in a dynamic group.
static int	MEMBERSHIP_TYPE_DYNAMIC The membership type that will be used if the user should be verified as a member of a dynamic group.
static int	MEMBERSHIP_TYPE_NONE The membership type that will be used if no membership determination is to be made.
static int	MEMBERSHIP_TYPE_ROLE The membership type that will be used if the user should be verified as a member of a role.
static int	MEMBERSHIP_TYPE_STATIC The membership type that will be used if the user should be verified as a member of a static group.
static int	MEMBERSHIP_TYPE_UNKNOWN The membership type that will be used if the entry for the membership DN has not yet been retrieved to determine the type of entry.
protected java.lang.String	membershipDN The DN of a static group, dynamic group, or role in which a user must be a member in order to be successfully authenticated.
static java.lang.String[]	NO_ATTRS The set of attributes to return if no attributes are needed from the user's entry.
static java.lang.String	ROLE_ATTRIBUTE The name of the LDAP attribute that contains the list of roles for which a user is a member.
static java.lang.String[]	ROLE_ATTRS The set of attributes to return if only the role is needed from the user's entry.
static java.lang.String	SSL_KEY_PASSWORD_PROPERTY The system property used to specify the password for the JSSE key store.
static java.lang.String	SSL_KEY_STORE_PROPERTY The system property used to specify the location of the JSSE key store.
static java.lang.String	SSL_TRUST_PASSWORD_PROPERTY The system property used to specify the password for the JSSE trust store.
static java.lang.String	SSL_TRUST_STORE_PROPERTY The system property used to specify the location of the JSSE trust store.
protected java.lang.String	sslKeyPassword The password to use when accessing the JSSE key store.
protected java.lang.String	sslKeyStore The location of the JSSE key store to use for SSL communication with the directory.
protected java.lang.String	sslTrustPassword The password to use when accessing the JSSE trust store.
protected java.lang.String	sslTrustStore The location of the JSSE trust store to use for SSL communication with the directory.
protected java.lang.String	userBase The DN under which user entries exist in the user directory.
protected java.util.Hashtable	userCache A hashtable containing cached credential information so that we don't have to go to the directory server for every request.
protected boolean	useSSL The flag that indicates whether SSL will be used to communicate with the directory server.

Fields inherited from class org.apache.catalina.realm.RealmBase

container, controller, debug, digest, domain, host, info, initialized, lifecycle, md, md5Encoder, md5Helper, mserver, oname, path, sm, started, support, type, validate

Fields inherited from interface org.apache.catalina.Lifecycle

AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, START_EVENT, STOP_EVENT

Constructor Summary

LDAPRealm()

Method Summary

java.security.Principal	authenticate(java.lang.String username, java.lang.String credentials) Retrieves the Principal associated with the specified username and credentials.
java.lang.String	getBindDN() Retrieves the DN that will be used to connect to the user directory to find user entries.
java.lang.String	getBindPassword() Retrieves the password to use for the bind DN.
boolean	getBlindTrust() Indicates whether to blindly trust any SSL certificate presented by the directory server.
java.lang.String	getLdapHost() Retrieves the address to use for the user directory server.
int	getLdapPort() Retrieves the port number for the user directory server.
java.lang.String	getLoginIDAttribute() Retrieves the name of the LDAP attribute that will be used to find user entries based on the provided user name.
java.lang.String	getMembershipDN() Retrieves the DN of the static group, dynamic group, or role entry for which a user must be a member in order to be authenticated.
protected java.lang.String	getName() Retrieves a short name for this Realm implementation, for use in log messages.
protected java.lang.String	getPassword(java.lang.String username) Retrieves the password associated with the given principal's user name.
protected java.security.Principal	getPrincipal(java.lang.String username) Retrieves the Principal associated with the given user name.
java.lang.String	getSslKeyPassword() Retrieves the password that will be used to access the JSSE key store.
java.lang.String	getSslKeyStore() Retrieves the location of the JSSE key store that is to be used for SSL communication.
java.lang.String	getSslTrustPassword() Retrieves the password that will be used to access the JSSE trust store.
java.lang.String	getSslTrustStore() Retrieves the location of the JSSE trust store that is to be used for SSL communication.
java.lang.String	getUserBase() Retrieves the location in the user directory under which user entries may be found.
boolean	getUseSSL() Indicates whether SSL will be used to communicate with the directory server.
void	setBindDN(java.lang.String bindDN) Specifies the DN that will be used to connect to the user directory to find user entries.
void	setBindPassword(java.lang.String bindPassword) Specifies the password to use for the bind DN.
void	setBlindTrust(java.lang.String blindTrust) Specifies whether to blindly trust any SSL certificate presented by the directory server.
void	setLdapHost(java.lang.String ldapHost) Specifies the address to use for the user directory server.
void	setLdapPort(int ldapPort) Specifies the port number for the user directory server.
void	setLdapPort(java.lang.String ldapPort) Specifies the port number for the user directory server.
void	setLoginIDAttribute(java.lang.String loginIDAttribute) Specifies the name of the LDAP attribute that will be used to find user entries based on the provided user name.
void	setMembershipDN(java.lang.String membershipDN) Specifies the DN of the static group, dynamic group, or role entry for which a user must be a member in order to be authenticated.
void	setSslKeyPassword(java.lang.String sslKeyPassword) Specifies the password used to access the JSSE key store.
void	setSslKeyStore(java.lang.String sslKeyStore) Specifies the location of the JSSE key store that is to be used for SSL communication.
void	setSslTrustPassword(java.lang.String sslTrustPassword) Specifies the password used to access the JSSE trust store.
void	setSslTrustStore(java.lang.String sslTrustStore) Specifies the location of the JSSE trust store that is to be used for SSL communication.
void	setUserBase(java.lang.String userBase) Specifies the location in the user directory under which user entries may be found.
void	setUseSSL(java.lang.String useSSL) Specifies whether to use SSL to communicate with the directory server.
void	stop() Shuts down this realm and releases the resources associated with it.

Methods inherited from class org.apache.catalina.realm.RealmBase

addLifecycleListener, addPropertyChangeListener, authenticate, authenticate, authenticate, destroy, digest, Digest, findLifecycleListeners, findSecurityConstraints, getContainer, getController, getDebug, getDigest, getDigest, getDomain, getInfo, getObjectName, getType, getValidate, hasMessageDigest, hasResourcePermission, hasRole, hasUserDataPermission, init, log, log, main, postDeregister, postRegister, preDeregister, preRegister, removeLifecycleListener, removePropertyChangeListener, setContainer, setController, setDebug, setDigest, setValidate, start

Methods inherited from class java.lang.Object

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

Field Detail

CACHE_CLEANUP_INTERVAL

public static final int CACHE_CLEANUP_INTERVAL

The interval in milliseconds over which the cache needs to be cleaned.

See Also:

Constant Field Values

CACHE_EXPIRATION_TIME

public static final int CACHE_EXPIRATION_TIME

The length of time in milliseconds that user information should stay in the user cache before being reloaded from the directory.

See Also:

Constant Field Values

MEMBERSHIP_TYPE_UNKNOWN

public static final int MEMBERSHIP_TYPE_UNKNOWN

The membership type that will be used if the entry for the membership DN has not yet been retrieved to determine the type of entry.

See Also:

Constant Field Values

MEMBERSHIP_TYPE_NONE

public static final int MEMBERSHIP_TYPE_NONE

The membership type that will be used if no membership determination is to be made.

See Also:

Constant Field Values

MEMBERSHIP_TYPE_STATIC

public static final int MEMBERSHIP_TYPE_STATIC

The membership type that will be used if the user should be verified as a member of a static group.

See Also:

Constant Field Values

MEMBERSHIP_TYPE_DYNAMIC

public static final int MEMBERSHIP_TYPE_DYNAMIC

The membership type that will be used if the user should be verified as a member of a dynamic group.

See Also:

Constant Field Values

MEMBERSHIP_TYPE_ROLE

public static final int MEMBERSHIP_TYPE_ROLE

The membership type that will be used if the user should be verified as a member of a role.

See Also:

Constant Field Values

MEMBER_URL_ATTRIBUTE

public static final java.lang.String MEMBER_URL_ATTRIBUTE

The name of the LDAP attribute that holds the LDAP URL used to hold the criteria for membership in a dynamic group.

See Also:

Constant Field Values

ROLE_ATTRIBUTE

public static final java.lang.String ROLE_ATTRIBUTE

The name of the LDAP attribute that contains the list of roles for which a user is a member.

See Also:

Constant Field Values

SSL_KEY_STORE_PROPERTY

public static final java.lang.String SSL_KEY_STORE_PROPERTY

The system property used to specify the location of the JSSE key store.

See Also:

Constant Field Values

SSL_KEY_PASSWORD_PROPERTY

public static final java.lang.String SSL_KEY_PASSWORD_PROPERTY

The system property used to specify the password for the JSSE key store.

See Also:

Constant Field Values

SSL_TRUST_STORE_PROPERTY

public static final java.lang.String SSL_TRUST_STORE_PROPERTY

The system property used to specify the location of the JSSE trust store.

See Also:

Constant Field Values

SSL_TRUST_PASSWORD_PROPERTY

public static final java.lang.String SSL_TRUST_PASSWORD_PROPERTY

The system property used to specify the password for the JSSE trust store.

See Also:

Constant Field Values

ROLE_ATTRS

public static final java.lang.String[] ROLE_ATTRS

The set of attributes to return if only the role is needed from the user's entry.

NO_ATTRS

public static final java.lang.String[] NO_ATTRS

The set of attributes to return if no attributes are needed from the user's entry.

useSSL

protected boolean useSSL

The flag that indicates whether SSL will be used to communicate with the directory server.

blindTrust

protected boolean blindTrust

The flag that indicates whether to blindly trust any SSL certificate presented by the directory server.

userCache

protected java.util.Hashtable userCache

A hashtable containing cached credential information so that we don't have to go to the directory server for every request.

bindDN

protected java.lang.String bindDN

The DN that will be used to bind to the user directory to find user accounts.

bindPassword

protected java.lang.String bindPassword

The password for the bind DN.

ldapHost

protected java.lang.String ldapHost

The address to use when connecting to the user directory.

ldapPort

protected java.lang.String ldapPort

The port number that will be used to contact the user directory.

loginIDAttribute

protected java.lang.String loginIDAttribute

The name of the LDAP attribute that will be used to find user entries based on the provided user name.

membershipDN

protected java.lang.String membershipDN

The DN of a static group, dynamic group, or role in which a user must be a member in order to be successfully authenticated.

sslKeyPassword

protected java.lang.String sslKeyPassword

The password to use when accessing the JSSE key store.

sslKeyStore

protected java.lang.String sslKeyStore

The location of the JSSE key store to use for SSL communication with the directory.

sslTrustPassword

protected java.lang.String sslTrustPassword

The password to use when accessing the JSSE trust store.

sslTrustStore

protected java.lang.String sslTrustStore

The location of the JSSE trust store to use for SSL communication with the directory.

userBase

protected java.lang.String userBase

The DN under which user entries exist in the user directory.

Constructor Detail

LDAPRealm

public LDAPRealm()

Method Detail

getBindDN

public java.lang.String getBindDN()

Retrieves the DN that will be used to connect to the user directory to find user entries.

Returns:

The DN that will be used to connect to the user directory to find user entries.

setBindDN

public void setBindDN(java.lang.String bindDN)

Specifies the DN that will be used to connect to the user directory to find user entries.

Parameters:

bindDN - The DN that will be used to connect to the user directory to find user entries.

getBindPassword

public java.lang.String getBindPassword()

Retrieves the password to use for the bind DN.

Returns:

The password to use for the bind DN.

setBindPassword

public void setBindPassword(java.lang.String bindPassword)

Specifies the password to use for the bind DN.

Parameters:

bindPassword - THe password to use for the bind DN.

getLdapHost

public java.lang.String getLdapHost()

Retrieves the address to use for the user directory server.

Returns:

The address to use for the user directory server.

setLdapHost

public void setLdapHost(java.lang.String ldapHost)

Specifies the address to use for the user directory server.

Parameters:

ldapHost - The address to use for the user directory server.

getLdapPort

public int getLdapPort()

Retrieves the port number for the user directory server.

Returns:

The port number for the user directory server.

setLdapPort

public void setLdapPort(int ldapPort)

Specifies the port number for the user directory server.

Parameters:

ldapPort - The port number for the user directory server.

setLdapPort

public void setLdapPort(java.lang.String ldapPort)

Specifies the port number for the user directory server.

Parameters:

ldapPort - The port number for the user directory server.

getLoginIDAttribute

public java.lang.String getLoginIDAttribute()

Retrieves the name of the LDAP attribute that will be used to find user entries based on the provided user name.

Returns:

The name of the LDAP attribute that will be used to find user entries based on the provided user name.

setLoginIDAttribute

public void setLoginIDAttribute(java.lang.String loginIDAttribute)

Specifies the name of the LDAP attribute that will be used to find user entries based on the provided user name.

Parameters:

loginIDAttribute - The name of the LDAP attribute that will be used to find user entries based on the provided user name.

getUserBase

public java.lang.String getUserBase()

Retrieves the location in the user directory under which user entries may be found.

Returns:

The location in the user directory under which user entries may be found.

setUserBase

public void setUserBase(java.lang.String userBase)

Specifies the location in the user directory under which user entries may be found.

Parameters:

userBase - The location in the user directory under which user entries may be found.

getMembershipDN

public java.lang.String getMembershipDN()

Retrieves the DN of the static group, dynamic group, or role entry for which a user must be a member in order to be authenticated.

Returns:

The DN of the static group, dynamic group, or role entry for which a user must be a member in order to be authenticated.

setMembershipDN

public void setMembershipDN(java.lang.String membershipDN)

Specifies the DN of the static group, dynamic group, or role entry for which a user must be a member in order to be authenticated.

Parameters:

membershipDN - The DN of the static group, dynamic group, or role entry for which a user must be a member in order to be authenticated.

getUseSSL

public boolean getUseSSL()

Indicates whether SSL will be used to communicate with the directory server.

Returns:

true if SSL will be used to communicate with the directory server, or false if not.

setUseSSL

public void setUseSSL(java.lang.String useSSL)

Specifies whether to use SSL to communicate with the directory server. If SSL is to be used, then the value specified must be "true".

Parameters:

useSSL - The string that specifies whether to use SSL to communicate with the directory server.

getBlindTrust

public boolean getBlindTrust()

Indicates whether to blindly trust any SSL certificate presented by the directory server.

Returns:

true if the certificate should be blindly trusted, or false if not.

setBlindTrust

public void setBlindTrust(java.lang.String blindTrust)

Specifies whether to blindly trust any SSL certificate presented by the directory server.

Parameters:

blindTrust - The string that specifies whether to blindly trust any SSL certificate.

setSslKeyStore

public void setSslKeyStore(java.lang.String sslKeyStore)

Specifies the location of the JSSE key store that is to be used for SSL communication.

Parameters:

sslKeyStore - The location of the JSSE key store that is to be used for SSL communication.

getSslKeyStore

public java.lang.String getSslKeyStore()

Retrieves the location of the JSSE key store that is to be used for SSL communication.

Returns:

The location of the JSSE key store that is to be used for SSL communication.

setSslKeyPassword

public void setSslKeyPassword(java.lang.String sslKeyPassword)

Specifies the password used to access the JSSE key store.

Parameters:

sslKeyPassword - The password used to access the JSSE key store.

getSslKeyPassword

public java.lang.String getSslKeyPassword()

Retrieves the password that will be used to access the JSSE key store.

Returns:

The password that will be used to access the JSSE key store.

setSslTrustStore

public void setSslTrustStore(java.lang.String sslTrustStore)

Specifies the location of the JSSE trust store that is to be used for SSL communication.

Parameters:

sslTrustStore - The location of the JSSE trust store that is to be used for SSL communication.

getSslTrustStore

public java.lang.String getSslTrustStore()

Retrieves the location of the JSSE trust store that is to be used for SSL communication.

Returns:

The location of the JSSE trust store that is to be used for SSL communication.

setSslTrustPassword

public void setSslTrustPassword(java.lang.String sslTrustPassword)

Specifies the password used to access the JSSE trust store.

Parameters:

sslTrustPassword - The password used to access the JSSE trust store.

getSslTrustPassword

public java.lang.String getSslTrustPassword()

Retrieves the password that will be used to access the JSSE trust store.

Returns:

The password that will be used to access the JSSE trust store.

authenticate

public java.security.Principal authenticate(java.lang.String username,
                                            java.lang.String credentials)

Retrieves the Principal associated with the specified username and credentials. If no user could be found with the specified username, or if the provided credentials are invalid, then null will be returned.

Parameters:

username - The provided username that will be used to find the user entry.

credentials - The credentials that will be used to authenticate the user.

Returns:

The Principal associated with the specified username and credentials.

stop

public void stop()

Shuts down this realm and releases the resources associated with it.

getName

protected java.lang.String getName()

Retrieves a short name for this Realm implementation, for use in log messages.

Returns:

A short name for this Realm implementation, for use in log messages.

getPassword

protected java.lang.String getPassword(java.lang.String username)

Retrieves the password associated with the given principal's user name.

Parameters:

username - The name of the user for which to retrieve the password.

Returns:

The password associated with the given principal's user name.

getPrincipal

protected java.security.Principal getPrincipal(java.lang.String username)

Retrieves the Principal associated with the given user name.

Parameters:

username - The name of the user for which to retrieve the Principal.

Returns:

The Principal associated with the given user name.