Package org.apache.catalina.realm

## Class JNDIRealm

- 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`, `Contained`, `GSSRealm`, `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 cannot 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.

  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 | Description
    --- | --- | ---
    `protected static class` | `JNDIRealm.JNDIConnection` | Class holding the connection to the directory plus the associated non thread safe message formats.
    `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`

  - ### Field Summary

    Fields
    Modifier and Type | Field | 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 SynchronizedStack<JNDIRealm.JNDIConnection>` | `connectionPool` | Connection pool.
    `protected int` | `connectionPoolSize` | The pool size limit.
    `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 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` | Deprecated. This will be removed in Tomcat 9 onwards.
    `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.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 JNDIRealm.JNDIConnection` | `singleConnection` | Non pooled connection to our directory server.
    `protected java.util.concurrent.locks.Lock` | `singleConnectionLock` | The lock to ensure single connection thread safety.
    `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` | `useContextClassLoader` | Whether to use context ClassLoader or default ClassLoader.
    `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.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 boolean` | `userSubtree` | Should we search the entire subtree for matching users?

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

      `allRolesMode, container, containerLog, 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 | Description
    --- | ---
    `JNDIRealm()` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `java.security.Principal` | `authenticate​(java.lang.String username)` | Return the Principal associated with the specified username, 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`.
    `java.security.Principal` | `authenticate​(java.lang.String username, java.lang.String clientDigest, java.lang.String nonce, java.lang.String nc, java.lang.String cnonce, java.lang.String qop, java.lang.String realm, java.lang.String md5a2)` | Try to authenticate with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 2617 (which is a superset of RFC 2069).
    `java.security.Principal` | `authenticate​(java.security.cert.X509Certificate[] certs)` | Return the Principal associated with the specified chain of X509 client certificates.
    `java.security.Principal` | `authenticate​(JNDIRealm.JNDIConnection connection, 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​(org.ietf.jgss.GSSContext gssContext, boolean storeCred)` | Try to authenticate using a `GSSContext`
    `java.security.Principal` | `authenticate​(org.ietf.jgss.GSSName gssName, org.ietf.jgss.GSSCredential gssCredential)` | Try to authenticate using a `GSSName`
    `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​(JNDIRealm.JNDIConnection connection)` | Close any open connection to the directory server for this Realm.
    `protected void` | `closePooledConnections()` | Close all pooled connections.
    `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 static java.lang.String` | `convertToHexEscape​(java.lang.String input)` |
    `protected JNDIRealm.JNDIConnection` | `create()` | Create a new connection wrapper, along with the message formats.
    `protected java.lang.String` | `doAttributeValueEscaping​(java.lang.String input)` | Implements the necessary escaping to represent an attribute value as a String as per RFC 4514.
    `protected java.lang.String` | `doFilterEscaping​(java.lang.String inString)` | Given an LDAP search string, returns the string with certain characters escaped according to RFC 2254 guidelines.
    `protected java.lang.String` | `doRFC2254Encoding​(java.lang.String inString)` | Deprecated. Will be removed in Tomcat 10.1.x onwards
    `protected JNDIRealm.JNDIConnection` | `get()` | Open (if necessary) and return a connection to the configured directory server for this Realm.
    `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()` |
    `int` | `getConnectionPoolSize()` |
    `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.
    `boolean` | `getForceDnHexEscape()` |
    `javax.net.ssl.HostnameVerifier` | `getHostnameVerifier()` |
    `java.lang.String` | `getHostnameVerifierClassName()` |
    `protected java.lang.String` | `getName()` | Deprecated.
    `protected java.lang.String` | `getPassword​(java.lang.String username)` | Get the password for the specified user.
    `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)` | Get the principal associated with the specified user name.
    `protected java.security.Principal` | `getPrincipal​(JNDIRealm.JNDIConnection connection, java.lang.String username, org.ietf.jgss.GSSCredential gssCredential)` | Get the principal associated with the specified certificate.
    `protected java.security.Principal` | `getPrincipal​(org.ietf.jgss.GSSName gssName, org.ietf.jgss.GSSCredential gssCredential)` | Get the principal associated with the specified `GSSName`.
    `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​(JNDIRealm.JNDIConnection connection, 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​(JNDIRealm.JNDIConnection connection, 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​(JNDIRealm.JNDIConnection connection, 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​(JNDIRealm.JNDIConnection connection, 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​(JNDIRealm.JNDIConnection connection, 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​(JNDIRealm.JNDIConnection connection, 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` | `isAvailable()` | Return the availability of the realm for authentication.
    `boolean` | `isRoleSearchAsUser()` |
    `boolean` | `isUseContextClassLoader()` | Returns whether to use the context or default ClassLoader.
    `boolean` | `isUseDelegatedCredential()` |
    `boolean` | `isUserSearchAsUser()` |
    `protected void` | `open​(JNDIRealm.JNDIConnection connection)` | Create a new connection to the directory server.
    `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​(JNDIRealm.JNDIConnection connection)` | 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` | `setConnectionPoolSize​(int connectionPoolSize)` | Set the connection pool size
    `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` | `setForceDnHexEscape​(boolean forceDnHexEscape)` |
    `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` | `setUseContextClassLoader​(boolean useContext)` | Sets whether to use the context or default ClassLoader.
    `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, backgroundProcess, Digest, findSecurityConstraints, getAllRolesMode, getContainer, getCredentialHandler, getDigest, getDomainInternal, getObjectNameKeyProperties, getPrincipal, getRealmPath, getRealmSuffix, getRoles, getServer, getTransportGuaranteeRedirectStatus, getValidate, getX509UsernameRetrieverClassName, hasMessageDigest, hasResourcePermission, hasRole, hasRoleInternal, hasUserDataPermission, initInternal, isStripRealmForGss, main, removePropertyChangeListener, setAllRolesMode, setContainer, setCredentialHandler, 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, getThrowOnFailure, init, removeLifecycleListener, setState, setState, setThrowOnFailure, 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.

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

          @Deprecated
          protected static final java.lang.String name

      Deprecated.
      This will be removed in Tomcat 9 onwards.
      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.

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

    - #### roleBase

          protected java.lang.String roleBase

      The base element for role searches.

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

    - #### singleConnection

          protected JNDIRealm.JNDIConnection singleConnection

      Non pooled connection to our directory server.

    - #### singleConnectionLock

          protected final java.util.concurrent.locks.Lock singleConnectionLock

      The lock to ensure single connection thread safety.

    - #### connectionPool

          protected SynchronizedStack<JNDIRealm.JNDIConnection> connectionPool

      Connection pool.

    - #### connectionPoolSize

          protected int connectionPoolSize

      The pool size limit. If 1, pooling is not used.

    - #### useContextClassLoader

          protected boolean useContextClassLoader

      Whether to use context ClassLoader or default ClassLoader. True means use context ClassLoader, and True is the default value.

  - ### Constructor Detail

    - #### JNDIRealm

          public JNDIRealm()

  - ### Method Detail

    - #### getForceDnHexEscape

          public boolean getForceDnHexEscape()

    - #### setForceDnHexEscape

          public void setForceDnHexEscape​(boolean forceDnHexEscape)

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

    - #### getConnectionPoolSize

          public int getConnectionPoolSize()

      Returns:
        the connection pool size, or the default value 1 if pooling is disabled

    - #### setConnectionPoolSize

          public void setConnectionPoolSize​(int connectionPoolSize)

      Set the connection pool size
      Parameters:
        `connectionPoolSize` - the new pool size

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

    - #### setUseContextClassLoader

          public void setUseContextClassLoader​(boolean useContext)

      Sets whether to use the context or default ClassLoader. True means use context ClassLoader.
      Parameters:
        `useContext` - True means use context ClassLoader

    - #### isUseContextClassLoader

          public boolean isUseContextClassLoader()

      Returns whether to use the context or default ClassLoader. True means to use the context ClassLoader.
      Returns:
        The value of useContextClassLoader

    - #### 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​(JNDIRealm.JNDIConnection connection,
                                                      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:
        `connection` - 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

    - #### authenticate

          public java.security.Principal authenticate​(java.lang.String username)

      Description copied from class: `RealmBase`
      Return the Principal associated with the specified username, if there is one; otherwise return `null`.
      Specified by:
        `authenticate` in interface `Realm`
      Overrides:
        `authenticate` in class `RealmBase`
      Parameters:
        `username` - Username of the Principal to look up
      Returns:
        the associated principal, or `null` if none is associated.

    - #### authenticate

          public java.security.Principal authenticate​(java.lang.String username,
                                                      java.lang.String clientDigest,
                                                      java.lang.String nonce,
                                                      java.lang.String nc,
                                                      java.lang.String cnonce,
                                                      java.lang.String qop,
                                                      java.lang.String realm,
                                                      java.lang.String md5a2)

      Description copied from class: `RealmBase`
      Try to authenticate with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 2617 (which is a superset of RFC 2069).
      Specified by:
        `authenticate` in interface `Realm`
      Overrides:
        `authenticate` in class `RealmBase`
      Parameters:
        `username` - Username of the Principal to look up
        `clientDigest` - Digest which has been submitted by the client
        `nonce` - Unique (or supposedly unique) token which has been used for this request
        `nc` - the nonce counter
        `cnonce` - the client chosen nonce
        `qop` - the "quality of protection" (`nc` and `cnonce` will only be used, if `qop` is not `null`).
        `realm` - Realm name
        `md5a2` - Second MD5 digest used to calculate the digest : MD5(Method + ":" + uri)
      Returns:
        the associated principal, or `null` if there is none.

    - #### authenticate

          public java.security.Principal authenticate​(java.security.cert.X509Certificate[] certs)

      Description copied from class: `RealmBase`
      Return the Principal associated with the specified chain of X509 client certificates. If there is none, return `null`.
      Specified by:
        `authenticate` in interface `Realm`
      Overrides:
        `authenticate` in class `RealmBase`
      Parameters:
        `certs` - Array of client certificates, with the first one in the array being the certificate of the client itself.
      Returns:
        the associated principal, or `null` if there is none

    - #### authenticate

          public java.security.Principal authenticate​(org.ietf.jgss.GSSContext gssContext,
                                                      boolean storeCred)

      Description copied from class: `RealmBase`
      Try to authenticate using a `GSSContext`
      Specified by:
        `authenticate` in interface `Realm`
      Overrides:
        `authenticate` in class `RealmBase`
      Parameters:
        `gssContext` - The gssContext processed by the `Authenticator`.
        `storeCred` - Should the realm attempt to store the delegated credentials in the returned Principal?
      Returns:
        the associated principal, or `null` if there is none

    - #### authenticate

          public java.security.Principal authenticate​(org.ietf.jgss.GSSName gssName,
                                                      org.ietf.jgss.GSSCredential gssCredential)

      Description copied from class: `RealmBase`
      Try to authenticate using a `GSSName`
      Specified by:
        `authenticate` in interface `GSSRealm`
      Overrides:
        `authenticate` in class `RealmBase`
      Parameters:
        `gssName` - The `GSSName` of the principal to look up
        `gssCredential` - The `GSSCredential` of the principal, may be `null`
      Returns:
        the associated principal, or `null` if there is none

    - #### getUser

          protected JNDIRealm.User getUser​(JNDIRealm.JNDIConnection connection,
                                           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:
        `connection` - 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(JNDIConnection, String, String, int)`

    - #### getUser

          protected JNDIRealm.User getUser​(JNDIRealm.JNDIConnection connection,
                                           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:
        `connection` - 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(JNDIConnection, String, String, int)`

    - #### getUser

          protected JNDIRealm.User getUser​(JNDIRealm.JNDIConnection connection,
                                           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:
        `connection` - 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​(JNDIRealm.JNDIConnection connection,
                                                    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:
        `connection` - 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​(JNDIRealm.JNDIConnection connection,
                                                   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:
        `connection` - 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​(JNDIRealm.JNDIConnection connection,
                                                              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:
        `connection` - 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​(JNDIRealm.JNDIConnection connection)

      Close any open connection to the directory server for this Realm.
      Parameters:
        `connection` - The directory context to be closed

    - #### closePooledConnections

          protected void closePooledConnections()

      Close all pooled connections.

    - #### getName

          @Deprecated
          protected java.lang.String getName()

      Deprecated.
      Specified by:
        `getName` in class `RealmBase`
      Returns:
        a short name for this Realm implementation, for use in log messages.

    - #### 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​(org.ietf.jgss.GSSName gssName,
                                                         org.ietf.jgss.GSSCredential gssCredential)

      Description copied from class: `RealmBase`
      Get the principal associated with the specified `GSSName`.
      Overrides:
        `getPrincipal` in class `RealmBase`
      Parameters:
        `gssName` - The GSS name
        `gssCredential` - the GSS credential of the principal
      Returns:
        the principal associated with the given user name.

    - #### getPrincipal

          protected java.security.Principal getPrincipal​(java.lang.String username,
                                                         org.ietf.jgss.GSSCredential gssCredential)

      Description copied from class: `RealmBase`
      Get the principal associated with the specified user name.
      Overrides:
        `getPrincipal` in class `RealmBase`
      Parameters:
        `username` - The user name
        `gssCredential` - the GSS credential of the principal
      Returns:
        the principal associated with the given user name.

    - #### getPrincipal

          protected java.security.Principal getPrincipal​(JNDIRealm.JNDIConnection connection,
                                                         java.lang.String username,
                                                         org.ietf.jgss.GSSCredential gssCredential)
                                                  throws javax.naming.NamingException

      Get the principal associated with the specified certificate.
      Parameters:
        `connection` - 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

    - #### get

          protected JNDIRealm.JNDIConnection get()
                                          throws javax.naming.NamingException

      Open (if necessary) and return a connection to the configured directory server for this Realm.
      Returns:
        the connection
      Throws:
        `javax.naming.NamingException` - if a directory server error occurs

    - #### release

          protected void release​(JNDIRealm.JNDIConnection connection)

      Release our use of this connection so that it can be recycled.
      Parameters:
        `connection` - The directory context to release

    - #### create

          protected JNDIRealm.JNDIConnection create()

      Create a new connection wrapper, along with the message formats.
      Returns:
        the new connection

    - #### open

          protected void open​(JNDIRealm.JNDIConnection connection)
                       throws javax.naming.NamingException

      Create a new connection to the directory server.
      Parameters:
        `connection` - The directory server connection wrapper
      Throws:
        `javax.naming.NamingException` - if a directory server error occurs

    - #### isAvailable

          public boolean isAvailable()

      Description copied from interface: `Realm`
      Return the availability of the realm for authentication.
      Specified by:
        `isAvailable` in interface `Realm`
      Overrides:
        `isAvailable` in class `RealmBase`
      Returns:
        `true` if the realm is able to perform authentication

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

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

          @Deprecated
          protected java.lang.String doRFC2254Encoding​(java.lang.String inString)

      Deprecated.
      Will be removed in Tomcat 10.1.x onwards
      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

    - #### doFilterEscaping

          protected java.lang.String doFilterEscaping​(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

    - #### doAttributeValueEscaping

          protected java.lang.String doAttributeValueEscaping​(java.lang.String input)

      Implements the necessary escaping to represent an attribute value as a String as per RFC 4514.
      Parameters:
        `input` - The original attribute value
      Returns:
        The string representation of the attribute value

    - #### convertToHexEscape

          protected static java.lang.String convertToHexEscape​(java.lang.String input)