Package org.apache.catalina.realm

Class JNDIRealm

  • All Implemented Interfaces:
    javax.management.MBeanRegistration, Contained, 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

    • 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

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

      • singleConnectionLock

        protected final java.util.concurrent.locks.Lock singleConnectionLock
        The lock to ensure single connection thread safety.

      • 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 Realm
        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.

      • 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)

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

      • 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)