JNDIRealm (Apache Tomcat 8.0.53 API Documentation)

java.lang.Object
- org.apache.catalina.util.LifecycleBase
- - org.apache.catalina.util.LifecycleMBeanBase
  - - org.apache.catalina.realm.RealmBase
    - - org.apache.catalina.realm.JNDIRealm

All Implemented Interfaces:

javax.management.MBeanRegistration, JmxEnabled, 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, and/or "{2}" the value of an attribute from the user's directory entry (the attribute is specified by the userRoleAttribute property), 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.
- A default role can be assigned to each user that was successfully authenticated by setting the commonRole property to the name of this role. The role doesn't have to exist in the directory.
- If the directory server contains nested roles, you can search for them by setting roleNested to true. The default value is false, so role searches will not find nested roles.
- 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: https://bz.apache.org/bugzilla/show_bug.cgi?id=11210 . With luck, Netscape has updated their provider code and this is not an issue.
Author:

John Holman, Craig R. McClanahan

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

protected static class JNDIRealm.User
A protected class representing a User
- Nested classes/interfaces inherited from class org.apache.catalina.realm.RealmBase
  RealmBase.AllRolesMode
- Nested classes/interfaces inherited from interface org.apache.catalina.Lifecycle
  Lifecycle.SingleUse

Nested Classes
Modifier and Type	Class and Description
`protected static class`	`JNDIRealm.User` A protected class representing a User

Field Summary

Fields
Modifier and Type	Field and Description
`protected boolean`	`adCompat` Should we ignore PartialResultExceptions when iterating over NamingEnumerations?
`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 java.lang.String`	`commonRole` Add this role to every authenticated user
`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`	`connectionTimeout` The timeout, in milliseconds, to use when trying to create a connection to the directory.
`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.
`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`	`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`	`readTimeout` The timeout, in milliseconds, to use when trying to read from a connection to the directory.
`protected java.lang.String`	`referrals` How should we handle referrals?
`protected java.lang.String`	`roleBase` The base element for role searches.
`protected java.text.MessageFormat`	`roleBaseFormat` The MessageFormat object associated with the current `roleBase`.
`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 boolean`	`roleNested` Should we look for nested group in order to determine roles?
`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`	`roleSearchAsUser` When searching for user roles, should the search be performed as the user currently being authenticated?
`protected boolean`	`roleSubtree` Should we search the entire subtree for matching memberships?
`protected long`	`sizeLimit` The sizeLimit (also known as the countLimit) to use when the realm is configured with `userSearch`.
`protected java.lang.String`	`spnegoDelegationQop` The QOP that should be used for the connection to the LDAP server after authentication.
`protected int`	`timeLimit` The timeLimit (in milliseconds) to use when the realm is configured with `userSearch`.
`protected boolean`	`useDelegatedCredential` Should delegated credentials from the SPNEGO authenticator be used if available
`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`	`userRoleAttribute` The name of the attribute inside the users directory entry where the value will be taken to search for roles This attribute is not used during a nested search
`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
allRolesMode, container, containerLog, digest, digestEncoding, md, md5Helper, realmPath, sm, stripRealmForGss, support, validate, x509UsernameRetriever, x509UsernameRetrieverClassName

Fields inherited from class org.apache.catalina.util.LifecycleMBeanBase
mserver

Fields inherited from interface org.apache.catalina.Lifecycle
AFTER_DESTROY_EVENT, AFTER_INIT_EVENT, AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_DESTROY_EVENT, BEFORE_INIT_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, CONFIGURE_START_EVENT, CONFIGURE_STOP_EVENT, PERIODIC_EVENT, START_EVENT, STOP_EVENT

Constructor Summary

Constructors
Constructor and Description

JNDIRealm()

Constructors
Constructor and Description
`JNDIRealm()`

Method Summary

Methods
Modifier and Type	Method and Description
`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, JNDIRealm.User user, java.lang.String credentials)` Check credentials by binding to the directory as the user
`protected boolean`	`checkCredentials(javax.naming.directory.DirContext context, JNDIRealm.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, JNDIRealm.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.
`boolean`	`getAdCompat()`
`java.lang.String`	`getAlternateURL()` Getter for property alternateURL.
`java.lang.String`	`getAuthentication()`
`java.lang.String`	`getCommonRole()`
`java.lang.String`	`getConnectionName()`
`java.lang.String`	`getConnectionPassword()`
`java.lang.String`	`getConnectionTimeout()`
`java.lang.String`	`getConnectionURL()`
`java.lang.String`	`getContextFactory()`
`java.lang.String`	`getDerefAliases()`
`protected java.util.Hashtable<java.lang.String,java.lang.String>`	`getDirectoryContextEnvironment()` Create our directory context configuration.
`protected java.lang.String`	`getDistinguishedName(javax.naming.directory.DirContext context, java.lang.String base, javax.naming.directory.SearchResult result)` Returns the distinguished name of a search result.
`javax.net.ssl.HostnameVerifier`	`getHostnameVerifier()`
`java.lang.String`	`getHostnameVerifierClassName()`
`protected java.lang.String`	`getName()`
`protected java.lang.String`	`getPassword(java.lang.String username)` Get the password for the specified user.
`protected java.security.Principal`	`getPrincipal(javax.naming.directory.DirContext context, java.lang.String username, org.ietf.jgss.GSSCredential gssCredential)` Get the principal associated with the specified certificate.
`protected java.security.Principal`	`getPrincipal(java.lang.String username)` Get the principal associated with the specified certificate.
`protected java.security.Principal`	`getPrincipal(java.lang.String username, org.ietf.jgss.GSSCredential gssCredential)`
`java.lang.String`	`getProtocol()`
`java.lang.String`	`getReadTimeout()`
`java.lang.String`	`getReferrals()`
`java.lang.String`	`getRoleBase()`
`java.lang.String`	`getRoleName()`
`boolean`	`getRoleNested()`
`protected java.util.List<java.lang.String>`	`getRoles(javax.naming.directory.DirContext context, JNDIRealm.User user)` Return a List of roles associated with the given User.
`java.lang.String`	`getRoleSearch()`
`boolean`	`getRoleSubtree()`
`long`	`getSizeLimit()`
`java.lang.String`	`getSpnegoDelegationQop()`
`int`	`getTimeLimit()`
`protected JNDIRealm.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`.
`protected JNDIRealm.User`	`getUser(javax.naming.directory.DirContext context, java.lang.String username, java.lang.String credentials)` Return a User object containing information about the user with the specified username, if found in the directory; otherwise return `null`.
`protected JNDIRealm.User`	`getUser(javax.naming.directory.DirContext context, java.lang.String username, java.lang.String credentials, int curUserPattern)` 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()`
`protected JNDIRealm.User`	`getUserByPattern(javax.naming.directory.DirContext context, java.lang.String username, java.lang.String[] attrIds, java.lang.String dn)` Use the distinguished name to locate the directory entry for the user with the specified username and return a User object; otherwise return `null`.
`protected JNDIRealm.User`	`getUserByPattern(javax.naming.directory.DirContext context, java.lang.String username, java.lang.String credentials, java.lang.String[] attrIds, int curUserPattern)` 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 JNDIRealm.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()`
`java.lang.String`	`getUserPattern()`
`java.lang.String`	`getUserRoleAttribute()`
`java.lang.String`	`getUserRoleName()`
`java.lang.String`	`getUserSearch()`
`boolean`	`getUserSubtree()`
`boolean`	`getUseStartTls()`
`boolean`	`isRoleSearchAsUser()`
`boolean`	`isUseDelegatedCredential()`
`boolean`	`isUserSearchAsUser()`
`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`	`setAdCompat(boolean adCompat)` How do we handle PartialResultExceptions?
`void`	`setAlternateURL(java.lang.String alternateURL)` Setter for property alternateURL.
`void`	`setAuthentication(java.lang.String authentication)` Set the type of authentication to use.
`void`	`setCipherSuites(java.lang.String suites)` Set the allowed cipher suites when opening a connection using StartTLS.
`void`	`setCommonRole(java.lang.String commonRole)` Set the common role
`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`	`setConnectionTimeout(java.lang.String timeout)` Set the connection timeout.
`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`	`setHostnameVerifierClassName(java.lang.String verifierClassName)` Set the `HostnameVerifier` to be used when opening connections using StartTLS.
`void`	`setProtocol(java.lang.String protocol)` Set the protocol for this Realm.
`void`	`setReadTimeout(java.lang.String timeout)` Set the read timeout.
`void`	`setReferrals(java.lang.String referrals)` How do we handle JNDI referrals?
`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`	`setRoleNested(boolean roleNested)` Set the "search subtree for roles" flag.
`void`	`setRoleSearch(java.lang.String roleSearch)` Set the message format pattern for selecting roles in this Realm.
`void`	`setRoleSearchAsUser(boolean roleSearchAsUser)`
`void`	`setRoleSubtree(boolean roleSubtree)` Set the "search subtree for roles" flag.
`void`	`setSizeLimit(long sizeLimit)`
`void`	`setSpnegoDelegationQop(java.lang.String spnegoDelegationQop)`
`void`	`setSslProtocol(java.lang.String protocol)` Set the ssl protocol to be used for connections using StartTLS.
`void`	`setSslSocketFactoryClassName(java.lang.String factoryClassName)` Set the `SSLSocketFactory` to be used when opening connections using StartTLS.
`void`	`setTimeLimit(int timeLimit)`
`void`	`setUseDelegatedCredential(boolean useDelegatedCredential)`
`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`	`setUserRoleAttribute(java.lang.String userRoleAttribute)`
`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`	`setUserSearchAsUser(boolean userSearchAsUser)`
`void`	`setUserSubtree(boolean userSubtree)` Set the "search subtree for users" flag.
`void`	`setUseStartTls(boolean useStartTls)` Flag whether StartTLS should be used when connecting to the ldap server
`protected void`	`startInternal()` Prepare for the beginning of active use of the public methods of this component and implement the requirements of `LifecycleBase.startInternal()`.
`protected void`	`stopInternal()` Gracefully terminate the active use of the public methods of this component and implement the requirements of `LifecycleBase.stopInternal()`.

Methods inherited from class org.apache.catalina.realm.RealmBase
addPropertyChangeListener, authenticate, authenticate, authenticate, authenticate, backgroundProcess, compareCredentials, digest, Digest, findSecurityConstraints, getAllRolesMode, getContainer, getCredentialHandler, getDigest, getDigest, getDigestCharset, getDigestEncoding, getDomainInternal, getObjectNameKeyProperties, getPrincipal, getRealmPath, getRealmSuffix, getServer, getTransportGuaranteeRedirectStatus, getValidate, getX509UsernameRetrieverClassName, hasMessageDigest, hasResourcePermission, hasRole, hasUserDataPermission, initInternal, isStripRealmForGss, main, removePropertyChangeListener, setAllRolesMode, setContainer, setCredentialHandler, setDigest, setDigestEncoding, setRealmPath, setStripRealmForGss, setTransportGuaranteeRedirectStatus, setValidate, setX509UsernameRetrieverClassName, toString

Methods inherited from class org.apache.catalina.util.LifecycleMBeanBase
destroyInternal, getDomain, getObjectName, postDeregister, postRegister, preDeregister, preRegister, register, setDomain, unregister

Methods inherited from class org.apache.catalina.util.LifecycleBase
addLifecycleListener, destroy, findLifecycleListeners, fireLifecycleEvent, getState, getStateName, init, removeLifecycleListener, setState, setState, start, stop

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, 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
  - 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.
  - adCompat
```
protected boolean adCompat
```
    Should we ignore PartialResultExceptions when iterating over NamingEnumerations? Microsoft Active Directory often returns referrals, which lead to PartialResultExceptions. Unfortunately there's no stable way to detect, if the Exceptions really come from an AD referral. Set to true to ignore PartialResultExceptions.
  - referrals
```
protected java.lang.String referrals
```
    How should we handle referrals? Microsoft Active Directory often returns referrals. If you need to follow them set referrals to "follow". Caution: if your DNS is not part of AD, the LDAP client lib might try to resolve your domain name in DNS to find another LDAP server.
  - 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.
  - userRoleAttribute
```
protected java.lang.String userRoleAttribute
```
    The name of the attribute inside the users directory entry where the value will be taken to search for roles This attribute is not used during a nested search
  - 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.
  - roleBaseFormat
```
protected java.text.MessageFormat roleBaseFormat
```
    The MessageFormat object associated with the current roleBase.
  - 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. The "{1}" and "{2}" are described in the Configuration Reference.
  - roleSubtree
```
protected boolean roleSubtree
```
    Should we search the entire subtree for matching memberships?
  - roleNested
```
protected boolean roleNested
```
    Should we look for nested group in order to determine roles?
  - roleSearchAsUser
```
protected boolean roleSearchAsUser
```
    When searching for user roles, should the search be performed as the user currently being authenticated? If false, connectionName and connectionPassword will be used if specified, else an anonymous connection will be used.
  - 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.
  - commonRole
```
protected java.lang.String commonRole
```
    Add this role to every authenticated user
  - connectionTimeout
```
protected java.lang.String connectionTimeout
```
    The timeout, in milliseconds, to use when trying to create a connection to the directory. The default is 5000 (5 seconds).
  - readTimeout
```
protected java.lang.String readTimeout
```
    The timeout, in milliseconds, to use when trying to read from a connection to the directory. The default is 5000 (5 seconds).
  - sizeLimit
```
protected long sizeLimit
```
    The sizeLimit (also known as the countLimit) to use when the realm is configured with userSearch. Zero for no limit.
  - timeLimit
```
protected int timeLimit
```
    The timeLimit (in milliseconds) to use when the realm is configured with userSearch. Zero for no limit.
  - useDelegatedCredential
```
protected boolean useDelegatedCredential
```
    Should delegated credentials from the SPNEGO authenticator be used if available
  - spnegoDelegationQop
```
protected java.lang.String spnegoDelegationQop
```
    The QOP that should be used for the connection to the LDAP server after authentication. This value is used to set the javax.security.sasl.qop environment property for the LDAP connection.
- Constructor Detail
  - JNDIRealm
```
public JNDIRealm()
```
- Method Detail
  - getAuthentication
```
public java.lang.String getAuthentication()
```
    Returns:
    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()
```
    Returns:
    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()
```
    Returns:
    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()
```
    Returns:
    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()
```
    Returns:
    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()
```
    Returns:
    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()
```
    Returns:
    the protocol to be used.
  - setProtocol
```
public void setProtocol(java.lang.String protocol)
```
    Set the protocol for this Realm.
    
    Parameters:
    protocol - The new protocol.
  - getAdCompat
```
public boolean getAdCompat()
```
    Returns:
    the current settings for handling PartialResultExceptions
  - setAdCompat
```
public void setAdCompat(boolean adCompat)
```
    How do we handle PartialResultExceptions? True: ignore all PartialResultExceptions.
    
    Parameters:
    adCompat - true to ignore partial results
  - 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).
    
    Parameters:
    referrals - The referral handling
  - getUserBase
```
public java.lang.String getUserBase()
```
    Returns:
    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()
```
    Returns:
    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
  - isUserSearchAsUser
```
public boolean isUserSearchAsUser()
```
  - setUserSearchAsUser
```
public void setUserSearchAsUser(boolean userSearchAsUser)
```
  - getUserSubtree
```
public boolean getUserSubtree()
```
    Returns:
    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()
```
    Returns:
    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()
```
    Returns:
    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()
```
    Returns:
    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()
```
    Returns:
    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
  - isRoleSearchAsUser
```
public boolean isRoleSearchAsUser()
```
  - setRoleSearchAsUser
```
public void setRoleSearchAsUser(boolean roleSearchAsUser)
```
  - getRoleSubtree
```
public boolean getRoleSubtree()
```
    Returns:
    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
  - getRoleNested
```
public boolean getRoleNested()
```
    Returns:
    the "The nested group search flag" flag.
  - setRoleNested
```
public void setRoleNested(boolean roleNested)
```
    Set the "search subtree for roles" flag.
    
    Parameters:
    roleNested - The nested group search flag
  - getUserPassword
```
public java.lang.String getUserPassword()
```
    Returns:
    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
  - getUserRoleAttribute
```
public java.lang.String getUserRoleAttribute()
```
  - setUserRoleAttribute
```
public void setUserRoleAttribute(java.lang.String userRoleAttribute)
```
  - getUserPattern
```
public java.lang.String getUserPattern()
```
    Returns:
    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.
  - getCommonRole
```
public java.lang.String getCommonRole()
```
    Returns:
    the common role
  - setCommonRole
```
public void setCommonRole(java.lang.String commonRole)
```
    Set the common role
    
    Parameters:
    commonRole - The common role
  - getConnectionTimeout
```
public java.lang.String getConnectionTimeout()
```
    Returns:
    the connection timeout.
  - setConnectionTimeout
```
public void setConnectionTimeout(java.lang.String timeout)
```
    Set the connection timeout.
    
    Parameters:
    timeout - The new connection timeout
  - getReadTimeout
```
public java.lang.String getReadTimeout()
```
    Returns:
    the read timeout.
  - setReadTimeout
```
public void setReadTimeout(java.lang.String timeout)
```
    Set the read timeout.
    
    Parameters:
    timeout - The new read timeout
  - getSizeLimit
```
public long getSizeLimit()
```
  - setSizeLimit
```
public void setSizeLimit(long sizeLimit)
```
  - getTimeLimit
```
public int getTimeLimit()
```
  - setTimeLimit
```
public void setTimeLimit(int timeLimit)
```
  - isUseDelegatedCredential
```
public boolean isUseDelegatedCredential()
```
  - setUseDelegatedCredential
```
public void setUseDelegatedCredential(boolean useDelegatedCredential)
```
  - getSpnegoDelegationQop
```
public java.lang.String getSpnegoDelegationQop()
```
  - setSpnegoDelegationQop
```
public void setSpnegoDelegationQop(java.lang.String spnegoDelegationQop)
```
  - getUseStartTls
```
public boolean getUseStartTls()
```
    Returns:
    flag whether to use StartTLS for connections to the ldap server
  - setUseStartTls
```
public void setUseStartTls(boolean useStartTls)
```
    Flag whether StartTLS should be used when connecting to the ldap server
    
    Parameters:
    useStartTls - true when StartTLS should be used. Default is false.
  - setCipherSuites
```
public void setCipherSuites(java.lang.String suites)
```
    Set the allowed cipher suites when opening a connection using StartTLS. The cipher suites are expected as a comma separated list.
    
    Parameters:
    suites - comma separated list of allowed cipher suites
  - getHostnameVerifierClassName
```
public java.lang.String getHostnameVerifierClassName()
```
    Returns:
    name of the HostnameVerifier class used for connections using StartTLS, or the empty string, if the default verifier should be used.
  - setHostnameVerifierClassName
```
public void setHostnameVerifierClassName(java.lang.String verifierClassName)
```
    Set the HostnameVerifier to be used when opening connections using StartTLS. An instance of the given class name will be constructed using the default constructor.
    
    Parameters:
    verifierClassName - class name of the HostnameVerifier to be constructed
  - getHostnameVerifier
```
public javax.net.ssl.HostnameVerifier getHostnameVerifier()
```
    Returns:
    the HostnameVerifier to use for peer certificate verification when opening connections using StartTLS.
  - setSslSocketFactoryClassName
```
public void setSslSocketFactoryClassName(java.lang.String factoryClassName)
```
    Set the SSLSocketFactory to be used when opening connections using StartTLS. An instance of the factory with the given name will be created using the default constructor. The SSLSocketFactory can also be set using setSslProtocol(String).
    
    Parameters:
    factoryClassName - class name of the factory to be constructed
  - setSslProtocol
```
public void setSslProtocol(java.lang.String protocol)
```
    Set the ssl protocol to be used for connections using StartTLS.
    
    Parameters:
    protocol - one of the allowed ssl protocol names
  - 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
    
    Returns:
    the associated principal, or null if there is none.
  - 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
    
    Returns:
    the associated principal, or null if there is none.
    
    Throws:
    
    javax.naming.NamingException - if a directory server error occurs
  - getUser
```
protected JNDIRealm.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.
    
    Parameters:
    context - The directory context
    username - Username to be looked up
    
    Returns:
    the User object
    
    Throws:
    
    javax.naming.NamingException - if a directory server error occurs
    See Also:
    getUser(DirContext, String, String, int)
  - getUser
```
protected JNDIRealm.User getUser(javax.naming.directory.DirContext context,
                     java.lang.String username,
                     java.lang.String credentials)
                          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.
    
    Parameters:
    context - The directory context
    username - Username to be looked up
    credentials - User credentials (optional)
    
    Returns:
    the User object
    
    Throws:
    
    javax.naming.NamingException - if a directory server error occurs
    See Also:
    getUser(DirContext, String, String, int)
  - getUser
```
protected JNDIRealm.User getUser(javax.naming.directory.DirContext context,
                     java.lang.String username,
                     java.lang.String credentials,
                     int curUserPattern)
                          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
    credentials - User credentials (optional)
    curUserPattern - Index into userPatternFormatArray
    
    Returns:
    the User object
    
    Throws:
    
    javax.naming.NamingException - if a directory server error occurs
  - getUserByPattern
```
protected JNDIRealm.User getUserByPattern(javax.naming.directory.DirContext context,
                              java.lang.String username,
                              java.lang.String[] attrIds,
                              java.lang.String dn)
                                   throws javax.naming.NamingException
```
    Use the distinguished name 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
    dn - Distinguished name of the user retrieve.
    
    Returns:
    the User object
    
    Throws:
    
    javax.naming.NamingException - if a directory server error occurs
  - getUserByPattern
```
protected JNDIRealm.User getUserByPattern(javax.naming.directory.DirContext context,
                              java.lang.String username,
                              java.lang.String credentials,
                              java.lang.String[] attrIds,
                              int curUserPattern)
                                   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
    credentials - User credentials (optional)
    attrIds - String[]containing names of attributes to
    curUserPattern - Index into userPatternFormatArray
    
    Returns:
    the User object
    
    Throws:
    
    javax.naming.NamingException - if a directory server error occurs
    See Also:
    getUserByPattern(DirContext, String, String[], String)
  - getUserBySearch
```
protected JNDIRealm.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.
    
    Returns:
    the User object
    
    Throws:
    
    javax.naming.NamingException - if a directory server error occurs
  - checkCredentials
```
protected boolean checkCredentials(javax.naming.directory.DirContext context,
                       JNDIRealm.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
    
    Returns:
    true if the credentials are validated
    
    Throws:
    
    javax.naming.NamingException - if a directory server error occurs
  - compareCredentials
```
protected boolean compareCredentials(javax.naming.directory.DirContext context,
                         JNDIRealm.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
    
    Returns:
    true if the credentials are validated
    
    Throws:
    
    javax.naming.NamingException - if a directory server error occurs
  - bindAsUser
```
protected boolean bindAsUser(javax.naming.directory.DirContext context,
                 JNDIRealm.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
    
    Returns:
    true if the credentials are validated
    
    Throws:
    
    javax.naming.NamingException - if a directory server error occurs
  - getRoles
```
protected java.util.List<java.lang.String> getRoles(javax.naming.directory.DirContext context,
                                        JNDIRealm.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
    
    Returns:
    the list of role names
    
    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()
```
    Specified by:
    
    getName in class RealmBase
    
    Returns:
    a short name for this Realm implementation.
  - getPassword
```
protected java.lang.String getPassword(java.lang.String username)
```
    Get the password for the specified user.
    
    Specified by:
    
    getPassword in class RealmBase
    
    Parameters:
    username - The user name
    
    Returns:
    the password associated with the given principal's user name.
  - getPrincipal
```
protected java.security.Principal getPrincipal(java.lang.String username)
```
    Get the principal associated with the specified certificate.
    
    Specified by:
    
    getPrincipal in class RealmBase
    
    Parameters:
    username - The user name
    
    Returns:
    the Principal associated with the given certificate.
  - getPrincipal
```
protected java.security.Principal getPrincipal(java.lang.String username,
                                   org.ietf.jgss.GSSCredential gssCredential)
```
    Overrides:
    
    getPrincipal in class RealmBase
  - getPrincipal
```
protected java.security.Principal getPrincipal(javax.naming.directory.DirContext context,
                                   java.lang.String username,
                                   org.ietf.jgss.GSSCredential gssCredential)
                                        throws javax.naming.NamingException
```
    Get the principal associated with the specified certificate.
    
    Parameters:
    context - The directory context
    username - The user name
    gssCredential - The credentials
    
    Returns:
    the Principal associated with the given certificate.
    
    Throws:
    
    javax.naming.NamingException - if a directory server error occurs
  - 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.
    
    Returns:
    the directory context
    
    Throws:
    
    javax.naming.NamingException - if a directory server error occurs
  - getDirectoryContextEnvironment
```
protected java.util.Hashtable<java.lang.String,java.lang.String> 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
  - startInternal
```
protected void startInternal()
                      throws LifecycleException
```
    Prepare for the beginning of active use of the public methods of this component and implement the requirements of LifecycleBase.startInternal().
    
    Overrides:
    
    startInternal in class RealmBase
    
    Throws:
    
    LifecycleException - if this component detects a fatal error that prevents this component from being used
  - stopInternal
```
protected void stopInternal()
                     throws LifecycleException
```
    Gracefully terminate the active use of the public methods of this component and implement the requirements of LifecycleBase.stopInternal().
    
    Overrides:
    
    stopInternal 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
    
    Returns:
    a parsed string array
  - 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
  - getDistinguishedName
```
protected java.lang.String getDistinguishedName(javax.naming.directory.DirContext context,
                                    java.lang.String base,
                                    javax.naming.directory.SearchResult result)
                                         throws javax.naming.NamingException
```
    Returns the distinguished name of a search result.
    
    Parameters:
    context - Our DirContext
    base - The base DN
    result - The search result
    
    Returns:
    String containing the distinguished name
    
    Throws:
    
    javax.naming.NamingException - if a directory server error occurs

Class JNDIRealm

Nested Class Summary

Nested classes/interfaces inherited from class org.apache.catalina.realm.RealmBase

Nested classes/interfaces inherited from interface org.apache.catalina.Lifecycle

Field Summary

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

Fields inherited from class org.apache.catalina.util.LifecycleMBeanBase

Fields inherited from interface org.apache.catalina.Lifecycle

Constructor Summary

Method Summary

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

Methods inherited from class org.apache.catalina.util.LifecycleMBeanBase

Methods inherited from class org.apache.catalina.util.LifecycleBase

Methods inherited from class java.lang.Object

Field Detail

authentication

connectionName

connectionPassword

connectionURL

context

contextFactory

derefAliases

DEREF_ALIASES

name

protocol

adCompat

referrals

userBase

userSearch

userSearchFormat

userSubtree

userPassword

userRoleAttribute

userPatternArray

userPattern

userPatternFormatArray

roleBase

roleBaseFormat

roleFormat

userRoleName

roleName

roleSearch

roleSubtree

roleNested

roleSearchAsUser

alternateURL

connectionAttempt

commonRole

connectionTimeout

readTimeout

sizeLimit

timeLimit

useDelegatedCredential

spnegoDelegationQop

Constructor Detail

JNDIRealm

Method Detail

getAuthentication

setAuthentication

getConnectionName

setConnectionName

getConnectionPassword

setConnectionPassword

getConnectionURL

setConnectionURL

getContextFactory

setContextFactory

getDerefAliases

setDerefAliases

getProtocol

setProtocol

getAdCompat

setAdCompat

getReferrals

setReferrals

getUserBase

setUserBase

getUserSearch

setUserSearch

isUserSearchAsUser