org.apache.catalina.realm
Class JNDIRealm

java.lang.Object
  org.apache.catalina.realm.RealmBase
      org.apache.catalina.realm.JNDIRealm

All Implemented Interfaces:

Lifecycle, javax.management.MBeanRegistration, Realm

public class JNDIRealm

extends RealmBase

Implementation of Realm that works with a directory server accessed via the Java Naming and Directory Interface (JNDI) APIs. The following constraints are imposed on the data structure in the underlying directory server:

• Each user that can be authenticated is represented by an individual element in the top level DirContext that is accessed via the connectionURL property.
• If a socket connection can not be made to the connectURL an attempt will be made to use the alternateURL if it exists.
• Each user element has a distinguished name that can be formed by substituting the presented username into a pattern configured by the userPattern property.
• Alternatively, if the userPattern property is not specified, a unique element can be located by searching the directory context. In this case:
  • The userSearch pattern specifies the search filter after substitution of the username.
  • The userBase property can be set to the element that is the base of the subtree containing users. If not specified, the search base is the top-level context.
  • The userSubtree property can be set to true if you wish to search the entire subtree of the directory context. The default value of false requests a search of only the current level.
• The user may be authenticated by binding to the directory with the username and password presented. This method is used when the userPassword property is not specified.
• The user may be authenticated by retrieving the value of an attribute from the directory and comparing it explicitly with the value presented by the user. This method is used when the userPassword property is specified, in which case:
  • The element for this user must contain an attribute named by the userPassword property.
  • The value of the user password attribute is either a cleartext String, or the result of passing a cleartext String through the RealmBase.digest() method (using the standard digest support included in RealmBase).
  • The user is considered to be authenticated if the presented credentials (after being passed through RealmBase.digest()) are equal to the retrieved value for the user password attribute.
• Each group of users that has been assigned a particular role may be represented by an individual element in the top level DirContext that is accessed via the connectionURL property. This element has the following characteristics:
  • The set of all possible groups of interest can be selected by a search pattern configured by the roleSearch property.
  • The roleSearch pattern optionally includes pattern replacements "{0}" for the distinguished name, and/or "{1}" for the username, of the authenticated user for which roles will be retrieved.
  • The roleBase property can be set to the element that is the base of the search for matching roles. If not specified, the entire context will be searched.
  • The roleSubtree property can be set to true if you wish to search the entire subtree of the directory context. The default value of false requests a search of only the current level.
  • The element includes an attribute (whose name is configured by the roleName property) containing the name of the role represented by this element.
• In addition, roles may be represented by the values of an attribute in the user's element whose name is configured by the userRoleName property.
• Note that the standard <security-role-ref> element in the web application deployment descriptor allows applications to refer to roles programmatically by names other than those used in the directory server itself.

TODO - Support connection pooling (including message format objects) so that authenticate() does not have to be synchronized.

WARNING - There is a reported bug against the Netscape provider code (com.netscape.jndi.ldap.LdapContextFactory) with respect to successfully authenticated a non-existing user. The report is here: http://nagoya.apache.org/bugzilla/show_bug.cgi?id=11210 . With luck, Netscape has updated their provider code and this is not an issue.

Version:

$Revision: 1.12 $ $Date: 2004/05/26 15:51:14 $

Author:

John Holman, Craig R. McClanahan

Field Summary

protected java.lang.String	alternateURL An alternate URL, to which, we should connect if connectionURL fails.
protected java.lang.String	authentication The type of authentication to use
protected int	connectionAttempt The number of connection attempts.
protected java.lang.String	connectionName The connection username for the server we will contact.
protected java.lang.String	connectionPassword The connection password for the server we will contact.
protected java.lang.String	connectionURL The connection URL for the server we will contact.
protected javax.naming.directory.DirContext	context The directory context linking us to our directory server.
protected java.lang.String	contextFactory The JNDI context factory used to acquire our InitialContext.
protected int	curUserPattern The current user pattern to be used for lookup and binding of a user.
protected static java.lang.String	info Descriptive information about this Realm implementation.
protected static java.lang.String	name Descriptive information about this Realm implementation.
protected java.lang.String	protocol The protocol that will be used in the communication with the directory server.
protected java.lang.String	referrals How should we handle referrals? Microsoft Active Directory can't handle the default case, so an application authenticating against AD must set referrals to "follow".
protected java.lang.String	roleBase The base element for role searches.
protected java.text.MessageFormat	roleFormat The MessageFormat object associated with the current roleSearch.
protected java.lang.String	roleName The name of the attribute containing roles held elsewhere
protected java.lang.String	roleSearch The message format used to select roles for a user, with "{0}" marking the spot where the distinguished name of the user goes.
protected boolean	roleSubtree Should we search the entire subtree for matching memberships?
protected java.lang.String	userBase The base element for user searches.
protected java.lang.String	userPassword The attribute name used to retrieve the user password.
protected java.lang.String	userPattern The message format used to form the distinguished name of a user, with "{0}" marking the spot where the specified username goes.
protected java.lang.String[]	userPatternArray A string of LDAP user patterns or paths, ":"-separated These will be used to form the distinguished name of a user, with "{0}" marking the spot where the specified username goes.
protected java.text.MessageFormat[]	userPatternFormatArray An array of MessageFormat objects associated with the current userPatternArray.
protected java.lang.String	userRoleName The name of an attribute in the user's entry containing roles for that user
protected java.lang.String	userSearch The message format used to search for a user, with "{0}" marking the spot where the username goes.
protected java.text.MessageFormat	userSearchFormat The MessageFormat object associated with the current userSearch.
protected boolean	userSubtree Should we search the entire subtree for matching users?

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

container, controller, debug, digest, domain, host, 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

JNDIRealm()

Method Summary

java.security.Principal	authenticate(javax.naming.directory.DirContext context, java.lang.String username, java.lang.String credentials) Return the Principal associated with the specified username and credentials, if there is one; otherwise return null.
java.security.Principal	authenticate(java.lang.String username, java.lang.String credentials) Return the Principal associated with the specified username and credentials, if there is one; otherwise return null.
protected boolean	bindAsUser(javax.naming.directory.DirContext context, org.apache.catalina.realm.User user, java.lang.String credentials) Check credentials by binding to the directory as the user
protected boolean	checkCredentials(javax.naming.directory.DirContext context, org.apache.catalina.realm.User user, java.lang.String credentials) Check whether the given User can be authenticated with the given credentials.
protected void	close(javax.naming.directory.DirContext context) Close any open connection to the directory server for this Realm.
protected boolean	compareCredentials(javax.naming.directory.DirContext context, org.apache.catalina.realm.User info, java.lang.String credentials) Check whether the credentials presented by the user match those retrieved from the directory.
protected java.lang.String	doRFC2254Encoding(java.lang.String inString) Given an LDAP search string, returns the string with certain characters escaped according to RFC 2254 guidelines.
java.lang.String	getAlternateURL() Getter for property alternateURL.
java.lang.String	getAuthentication() Return the type of authentication to use.
java.lang.String	getConnectionName() Return the connection username for this Realm.
java.lang.String	getConnectionPassword() Return the connection password for this Realm.
java.lang.String	getConnectionURL() Return the connection URL for this Realm.
java.lang.String	getContextFactory() Return the JNDI context factory for this Realm.
protected java.util.Hashtable	getDirectoryContextEnvironment() Create our directory context configuration.
protected java.lang.String	getName() Return a short name for this Realm implementation.
protected java.lang.String	getPassword(java.lang.String username) Return the password associated with the given principal's user name.
protected java.security.Principal	getPrincipal(java.lang.String username) Return the Principal associated with the given user name.
java.lang.String	getProtocol() Return the protocol to be used.
java.lang.String	getReferrals() Returns the current settings for handling JNDI referrals.
java.lang.String	getRoleBase() Return the base element for role searches.
java.lang.String	getRoleName() Return the role name attribute name for this Realm.
protected java.util.List	getRoles(javax.naming.directory.DirContext context, org.apache.catalina.realm.User user) Return a List of roles associated with the given User.
java.lang.String	getRoleSearch() Return the message format pattern for selecting roles in this Realm.
boolean	getRoleSubtree() Return the "search subtree for roles" flag.
protected org.apache.catalina.realm.User	getUser(javax.naming.directory.DirContext context, java.lang.String username) Return a User object containing information about the user with the specified username, if found in the directory; otherwise return null.
java.lang.String	getUserBase() Return the base element for user searches.
protected org.apache.catalina.realm.User	getUserByPattern(javax.naming.directory.DirContext context, java.lang.String username, java.lang.String[] attrIds) Use the UserPattern configuration attribute to locate the directory entry for the user with the specified username and return a User object; otherwise return null.
protected org.apache.catalina.realm.User	getUserBySearch(javax.naming.directory.DirContext context, java.lang.String username, java.lang.String[] attrIds) Search the directory to return a User object containing information about the user with the specified username, if found in the directory; otherwise return null.
java.lang.String	getUserPassword() Return the password attribute used to retrieve the user password.
java.lang.String	getUserPattern() Return the message format pattern for selecting users in this Realm.
java.lang.String	getUserRoleName() Return the user role name attribute name for this Realm.
java.lang.String	getUserSearch() Return the message format pattern for selecting users in this Realm.
boolean	getUserSubtree() Return the "search subtree for users" flag.
protected javax.naming.directory.DirContext	open() Open (if necessary) and return a connection to the configured directory server for this Realm.
protected java.lang.String[]	parseUserPatternString(java.lang.String userPatternString) Given a string containing LDAP patterns for user locations (separated by parentheses in a pseudo-LDAP search string format - "(location1)(location2)", returns an array of those paths.
protected void	release(javax.naming.directory.DirContext context) Release our use of this connection so that it can be recycled.
void	setAlternateURL(java.lang.String alternateURL) Setter for property alternateURL.
void	setAuthentication(java.lang.String authentication) Set the type of authentication to use.
void	setConnectionName(java.lang.String connectionName) Set the connection username for this Realm.
void	setConnectionPassword(java.lang.String connectionPassword) Set the connection password for this Realm.
void	setConnectionURL(java.lang.String connectionURL) Set the connection URL for this Realm.
void	setContextFactory(java.lang.String contextFactory) Set the JNDI context factory for this Realm.
void	setProtocol(java.lang.String protocol) Set the protocol for this Realm.
void	setReferrals(java.lang.String referrals) How do we handle JNDI referrals? ignore, follow, or throw (see javax.naming.Context.REFERRAL for more information).
void	setRoleBase(java.lang.String roleBase) Set the base element for role searches.
void	setRoleName(java.lang.String roleName) Set the role name attribute name for this Realm.
void	setRoleSearch(java.lang.String roleSearch) Set the message format pattern for selecting roles in this Realm.
void	setRoleSubtree(boolean roleSubtree) Set the "search subtree for roles" flag.
void	setUserBase(java.lang.String userBase) Set the base element for user searches.
void	setUserPassword(java.lang.String userPassword) Set the password attribute used to retrieve the user password.
void	setUserPattern(java.lang.String userPattern) Set the message format pattern for selecting users in this Realm.
void	setUserRoleName(java.lang.String userRoleName) Set the user role name attribute name for this Realm.
void	setUserSearch(java.lang.String userSearch) Set the message format pattern for selecting users in this Realm.
void	setUserSubtree(boolean userSubtree) Set the "search subtree for users" flag.
void	start() Prepare for active use of the public methods of this Component.
void	stop() Gracefully shut down active use of the public methods of this Component.

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

Methods inherited from class java.lang.Object

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

Field Detail

authentication

protected java.lang.String authentication

The type of authentication to use

connectionName

protected java.lang.String connectionName

The connection username for the server we will contact.

connectionPassword

protected java.lang.String connectionPassword

The connection password for the server we will contact.

connectionURL

protected java.lang.String connectionURL

The connection URL for the server we will contact.

context

protected javax.naming.directory.DirContext context

The directory context linking us to our directory server.

contextFactory

protected java.lang.String contextFactory

The JNDI context factory used to acquire our InitialContext. By default, assumes use of an LDAP server using the standard JNDI LDAP provider.

info

protected static final java.lang.String info

Descriptive information about this Realm implementation.

See Also:

Constant Field Values

name

protected static final java.lang.String name

Descriptive information about this Realm implementation.

See Also:

Constant Field Values

protocol

protected java.lang.String protocol

The protocol that will be used in the communication with the directory server.

referrals

protected java.lang.String referrals

How should we handle referrals? Microsoft Active Directory can't handle the default case, so an application authenticating against AD must set referrals to "follow".

userBase

protected java.lang.String userBase

The base element for user searches.

userSearch

protected java.lang.String userSearch

The message format used to search for a user, with "{0}" marking the spot where the username goes.

userSearchFormat

protected java.text.MessageFormat userSearchFormat

The MessageFormat object associated with the current userSearch.

userSubtree

protected boolean userSubtree

Should we search the entire subtree for matching users?

userPassword

protected java.lang.String userPassword

The attribute name used to retrieve the user password.

userPatternArray

protected java.lang.String[] userPatternArray

A string of LDAP user patterns or paths, ":"-separated These will be used to form the distinguished name of a user, with "{0}" marking the spot where the specified username goes. This is similar to userPattern, but allows for multiple searches for a user.

userPattern

protected java.lang.String userPattern

The message format used to form the distinguished name of a user, with "{0}" marking the spot where the specified username goes.

userPatternFormatArray

protected java.text.MessageFormat[] userPatternFormatArray

An array of MessageFormat objects associated with the current userPatternArray.

roleBase

protected java.lang.String roleBase

The base element for role searches.

roleFormat

protected java.text.MessageFormat roleFormat

The MessageFormat object associated with the current roleSearch.

userRoleName

protected java.lang.String userRoleName

The name of an attribute in the user's entry containing roles for that user

roleName

protected java.lang.String roleName

The name of the attribute containing roles held elsewhere

roleSearch

protected java.lang.String roleSearch

The message format used to select roles for a user, with "{0}" marking the spot where the distinguished name of the user goes.

roleSubtree

protected boolean roleSubtree

Should we search the entire subtree for matching memberships?

alternateURL

protected java.lang.String alternateURL

An alternate URL, to which, we should connect if connectionURL fails.

connectionAttempt

protected int connectionAttempt

The number of connection attempts. If greater than zero we use the alternate url.

curUserPattern

protected int curUserPattern

The current user pattern to be used for lookup and binding of a user.

Constructor Detail

JNDIRealm

public JNDIRealm()

Method Detail

getAuthentication

public java.lang.String getAuthentication()

Return the type of authentication to use.

setAuthentication

public void setAuthentication(java.lang.String authentication)

Set the type of authentication to use.

Parameters:

authentication - The authentication

getConnectionName

public java.lang.String getConnectionName()

Return the connection username for this Realm.

setConnectionName

public void setConnectionName(java.lang.String connectionName)

Set the connection username for this Realm.

Parameters:

connectionName - The new connection username

getConnectionPassword

public java.lang.String getConnectionPassword()

Return the connection password for this Realm.

setConnectionPassword

public void setConnectionPassword(java.lang.String connectionPassword)

Set the connection password for this Realm.

Parameters:

connectionPassword - The new connection password

getConnectionURL

public java.lang.String getConnectionURL()

Return the connection URL for this Realm.

setConnectionURL

public void setConnectionURL(java.lang.String connectionURL)

Set the connection URL for this Realm.

Parameters:

connectionURL - The new connection URL

getContextFactory

public java.lang.String getContextFactory()

Return the JNDI context factory for this Realm.

setContextFactory

public void setContextFactory(java.lang.String contextFactory)

Set the JNDI context factory for this Realm.

Parameters:

contextFactory - The new context factory

getProtocol

public java.lang.String getProtocol()

Return the protocol to be used.

setProtocol

public void setProtocol(java.lang.String protocol)

Set the protocol for this Realm.

Parameters:

protocol - The new protocol.

getReferrals

public java.lang.String getReferrals()

Returns the current settings for handling JNDI referrals.

setReferrals

public void setReferrals(java.lang.String referrals)

How do we handle JNDI referrals? ignore, follow, or throw (see javax.naming.Context.REFERRAL for more information).

getUserBase

public java.lang.String getUserBase()

Return the base element for user searches.

setUserBase

public void setUserBase(java.lang.String userBase)

Set the base element for user searches.

Parameters:

userBase - The new base element

getUserSearch

public java.lang.String getUserSearch()

Return the message format pattern for selecting users in this Realm.

setUserSearch

public void setUserSearch(java.lang.String userSearch)

Set the message format pattern for selecting users in this Realm.

Parameters:

userSearch - The new user search pattern

getUserSubtree

public boolean getUserSubtree()

Return the "search subtree for users" flag.

setUserSubtree

public void setUserSubtree(boolean userSubtree)

Set the "search subtree for users" flag.

Parameters:

userSubtree - The new search flag

getUserRoleName

public java.lang.String getUserRoleName()

Return the user role name attribute name for this Realm.

setUserRoleName

public void setUserRoleName(java.lang.String userRoleName)

Set the user role name attribute name for this Realm.

Parameters:

userRoleName - The new userRole name attribute name

getRoleBase

public java.lang.String getRoleBase()

Return the base element for role searches.

setRoleBase

public void setRoleBase(java.lang.String roleBase)

Set the base element for role searches.

Parameters:

roleBase - The new base element

getRoleName

public java.lang.String getRoleName()

Return the role name attribute name for this Realm.

setRoleName

public void setRoleName(java.lang.String roleName)

Set the role name attribute name for this Realm.

Parameters:

roleName - The new role name attribute name

getRoleSearch

public java.lang.String getRoleSearch()

Return the message format pattern for selecting roles in this Realm.

setRoleSearch

public void setRoleSearch(java.lang.String roleSearch)

Set the message format pattern for selecting roles in this Realm.

Parameters:

roleSearch - The new role search pattern

getRoleSubtree

public boolean getRoleSubtree()

Return the "search subtree for roles" flag.

setRoleSubtree

public void setRoleSubtree(boolean roleSubtree)

Set the "search subtree for roles" flag.

Parameters:

roleSubtree - The new search flag

getUserPassword

public java.lang.String getUserPassword()

Return the password attribute used to retrieve the user password.

setUserPassword

public void setUserPassword(java.lang.String userPassword)

Set the password attribute used to retrieve the user password.

Parameters:

userPassword - The new password attribute

getUserPattern

public java.lang.String getUserPattern()

Return the message format pattern for selecting users in this Realm.

setUserPattern

public void setUserPattern(java.lang.String userPattern)

Set the message format pattern for selecting users in this Realm. This may be one simple pattern, or multiple patterns to be tried, separated by parentheses. (for example, either "cn={0}", or "(cn={0})(cn={0},o=myorg)" Full LDAP search strings are also supported, but only the "OR", "|" syntax, so "(|(cn={0})(cn={0},o=myorg))" is also valid. Complex search strings with &, etc are NOT supported.

Parameters:

userPattern - The new user pattern

getAlternateURL

public java.lang.String getAlternateURL()

Getter for property alternateURL.

Returns:

Value of property alternateURL.

setAlternateURL

public void setAlternateURL(java.lang.String alternateURL)

Setter for property alternateURL.

Parameters:

alternateURL - New value of property alternateURL.

authenticate

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

Return the Principal associated with the specified username and credentials, if there is one; otherwise return null. If there are any errors with the JDBC connection, executing the query or anything we return null (don't authenticate). This event is also logged, and the connection will be closed so that a subsequent request will automatically re-open it.

Specified by:

authenticate in interface Realm

Overrides:

authenticate in class RealmBase

Parameters:

username - Username of the Principal to look up

credentials - Password or other credentials to use in authenticating this username

authenticate

public java.security.Principal authenticate(javax.naming.directory.DirContext context,
                                            java.lang.String username,
                                            java.lang.String credentials)
                                     throws javax.naming.NamingException

Return the Principal associated with the specified username and credentials, if there is one; otherwise return null.

Parameters:

context - The directory context

username - Username of the Principal to look up

credentials - Password or other credentials to use in authenticating this username

Throws:

javax.naming.NamingException - if a directory server error occurs

getUser

protected org.apache.catalina.realm.User getUser(javax.naming.directory.DirContext context,
                                                 java.lang.String username)
                                          throws javax.naming.NamingException

Return a User object containing information about the user with the specified username, if found in the directory; otherwise return null. If the userPassword configuration attribute is specified, the value of that attribute is retrieved from the user's directory entry. If the userRoleName configuration attribute is specified, all values of that attribute are retrieved from the directory entry.

Parameters:

context - The directory context

username - Username to be looked up

Throws:

javax.naming.NamingException - if a directory server error occurs

getUserByPattern

protected org.apache.catalina.realm.User getUserByPattern(javax.naming.directory.DirContext context,
                                                          java.lang.String username,
                                                          java.lang.String[] attrIds)
                                                   throws javax.naming.NamingException

Use the UserPattern configuration attribute to locate the directory entry for the user with the specified username and return a User object; otherwise return null.

Parameters:

context - The directory context

username - The username

attrIds - String[]containing names of attributes to retrieve.

Throws:

javax.naming.NamingException - if a directory server error occurs

getUserBySearch

protected org.apache.catalina.realm.User getUserBySearch(javax.naming.directory.DirContext context,
                                                         java.lang.String username,
                                                         java.lang.String[] attrIds)
                                                  throws javax.naming.NamingException

Search the directory to return a User object containing information about the user with the specified username, if found in the directory; otherwise return null.

Parameters:

context - The directory context

username - The username

attrIds - String[]containing names of attributes to retrieve.

Throws:

javax.naming.NamingException - if a directory server error occurs

checkCredentials

protected boolean checkCredentials(javax.naming.directory.DirContext context,
                                   org.apache.catalina.realm.User user,
                                   java.lang.String credentials)
                            throws javax.naming.NamingException

Check whether the given User can be authenticated with the given credentials. If the userPassword configuration attribute is specified, the credentials previously retrieved from the directory are compared explicitly with those presented by the user. Otherwise the presented credentials are checked by binding to the directory as the user.

Parameters:

context - The directory context

user - The User to be authenticated

credentials - The credentials presented by the user

Throws:

javax.naming.NamingException - if a directory server error occurs

compareCredentials

protected boolean compareCredentials(javax.naming.directory.DirContext context,
                                     org.apache.catalina.realm.User info,
                                     java.lang.String credentials)
                              throws javax.naming.NamingException

Check whether the credentials presented by the user match those retrieved from the directory.

Parameters:

context - The directory context

info - The User to be authenticated

credentials - Authentication credentials

Throws:

javax.naming.NamingException - if a directory server error occurs

bindAsUser

protected boolean bindAsUser(javax.naming.directory.DirContext context,
                             org.apache.catalina.realm.User user,
                             java.lang.String credentials)
                      throws javax.naming.NamingException

Check credentials by binding to the directory as the user

Parameters:

context - The directory context

user - The User to be authenticated

credentials - Authentication credentials

Throws:

javax.naming.NamingException - if a directory server error occurs

getRoles

protected java.util.List getRoles(javax.naming.directory.DirContext context,
                                  org.apache.catalina.realm.User user)
                           throws javax.naming.NamingException

Return a List of roles associated with the given User. Any roles present in the user's directory entry are supplemented by a directory search. If no roles are associated with this user, a zero-length List is returned.

Parameters:

context - The directory context we are searching

user - The User to be checked

Throws:

javax.naming.NamingException - if a directory server error occurs

close

protected void close(javax.naming.directory.DirContext context)

Close any open connection to the directory server for this Realm.

Parameters:

context - The directory context to be closed

getName

protected java.lang.String getName()

Return a short name for this Realm implementation.

Specified by:

getName in class RealmBase

getPassword

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

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

Specified by:

getPassword in class RealmBase

getPrincipal

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

Return the Principal associated with the given user name.

Specified by:

getPrincipal in class RealmBase

open

protected javax.naming.directory.DirContext open()
                                          throws javax.naming.NamingException

Open (if necessary) and return a connection to the configured directory server for this Realm.

Throws:

javax.naming.NamingException - if a directory server error occurs

getDirectoryContextEnvironment

protected java.util.Hashtable getDirectoryContextEnvironment()

Create our directory context configuration.

Returns:

java.util.Hashtable the configuration for the directory context.

release

protected void release(javax.naming.directory.DirContext context)

Release our use of this connection so that it can be recycled.

Parameters:

context - The directory context to release

start

public void start()
           throws LifecycleException

Prepare for active use of the public methods of this Component.

Specified by:

start in interface Lifecycle

Overrides:

start in class RealmBase

Throws:

LifecycleException - if this component detects a fatal error that prevents it from being started

stop

public void stop()
          throws LifecycleException

Gracefully shut down active use of the public methods of this Component.

Specified by:

stop in interface Lifecycle

Overrides:

stop in class RealmBase

Throws:

LifecycleException - if this component detects a fatal error that needs to be reported

parseUserPatternString

protected java.lang.String[] parseUserPatternString(java.lang.String userPatternString)

Given a string containing LDAP patterns for user locations (separated by parentheses in a pseudo-LDAP search string format - "(location1)(location2)", returns an array of those paths. Real LDAP search strings are supported as well (though only the "|" "OR" type).

Parameters:

userPatternString - - a string LDAP search paths surrounded by parentheses

doRFC2254Encoding

protected java.lang.String doRFC2254Encoding(java.lang.String inString)

Given an LDAP search string, returns the string with certain characters escaped according to RFC 2254 guidelines. The character mapping is as follows: char -> Replacement --------------------------- * -> \2a ( -> \28 ) -> \29 \ -> \5c \0 -> \00

Parameters:

inString - string to escape according to RFC 2254 guidelines

Returns:

String the escaped/encoded result