## org.apache.catalina.realm
Class JNDIRealm

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

All Implemented Interfaces:
  Lifecycle, 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://issues.apache.org/bugzilla/show_bug.cgi?id=11210 . With luck, Netscape has updated their provider code and this is not an issue.

Version:
  $Revision: 466595 $ $Date: 2006-10-21 23:24:41 +0100 (Sat, 21 Oct 2006) $
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.
`static java.lang.String` `DEREF_ALIASES` Constant that holds the name of the environment property for specifying the manner in which aliases should be dereferenced.
`protected java.lang.String` `derefAliases` How aliases should be dereferenced during search operations.
`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, debug, digest, digestEncoding, lifecycle, md, md5Encoder, md5Helper, sm, started, support, 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.
`java.lang.String` `getDerefAliases()` Return the derefAliases setting to be used.
`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(javax.naming.directory.DirContext context, java.lang.String username)` Return the Principal associated with the given 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` `setDerefAliases(java.lang.String derefAliases)` Set the value for derefAliases to be used when searching the directory.
`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, digest, Digest, findLifecycleListeners, getContainer, getDebug, getDigest, getDigest, getDigestEncoding, getInfo, getPrincipal, getValidate, hasMessageDigest, hasRole, log, log, main, removeLifecycleListener, removePropertyChangeListener, setContainer, setDebug, setDigest, setDigestEncoding, 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.

### derefAliases

    protected java.lang.String derefAliases

  How aliases should be dereferenced during search operations.

### DEREF_ALIASES

    public static final java.lang.String DEREF_ALIASES

  Constant that holds the name of the environment property for specifying the manner in which aliases should be dereferenced.

  See Also:
    Constant Field Values

### 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

### getDerefAliases

    public java.lang.String getDerefAliases()

  Return the derefAliases setting to be used.

### setDerefAliases

    public void setDerefAliases(java.lang.String derefAliases)

  Set the value for derefAliases to be used when searching the directory.

  Parameters:
    `derefAliases` - New value of property derefAliases.

### 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`

### getPrincipal

    protected java.security.Principal getPrincipal(javax.naming.directory.DirContext context,
                                                   java.lang.String username)
                                            throws javax.naming.NamingException

  Return the Principal associated with the given user name.

  Throws:
    `javax.naming.NamingException`

### 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:
    The escaped string

Copyright © 2000-2002 Apache Software Foundation. All Rights Reserved.