Tomcat 10.1.19 · org.apache.catalina.realm.JNDIRealm

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.

Nested and Inner Type Summary

Modifier and Type	Class and 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

Field Summary

Modifier and Type	Field and Description
protected boolean	adCompat Should we ignore PartialResultExceptions when iterating over NamingEnumerations?
protected String	alternateURL An alternate URL, to which, we should connect if connectionURL fails.
protected String	authentication The type of authentication to use
private String	cipherSuites Comma separated list of cipher suites to use for StartTLS.
private String[]	cipherSuitesArray The list of enabled cipher suites used for establishing tls connections.
protected String	commonRole Add this role to every authenticated user
protected int	connectionAttempt The number of connection attempts.
protected String	connectionName The connection username for the server we will contact.
protected 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 String	connectionTimeout The timeout, in milliseconds, to use when trying to create a connection to the directory.
protected String	connectionURL The connection URL for the server we will contact.
protected String	contextFactory The JNDI context factory used to acquire our InitialContext.
public static final String	DEREF_ALIASES Constant that holds the name of the environment property for specifying the manner in which aliases should be dereferenced.
protected String	derefAliases How aliases should be dereferenced during search operations.
private boolean	forceDnHexEscape
private HostnameVerifier	hostnameVerifier Verifier for hostnames in a StartTLS secured connection.
private String	hostNameVerifierClassName Name of the class of the `HostnameVerifier`.
protected String	protocol The protocol that will be used in the communication with the directory server.
protected String	readTimeout The timeout, in milliseconds, to use when trying to read from a connection to the directory.
protected String	referrals How should we handle referrals?
protected String	roleBase The base element for role searches.
protected 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 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 final 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 String	spnegoDelegationQop The QOP that should be used for the connection to the LDAP server after authentication.
private String	sslProtocol The ssl Protocol which will be used by StartTLS.
private SSLSocketFactory	sslSocketFactory `SSLSocketFactory` to use when connection with StartTLS enabled.
private String	sslSocketFactoryClassName Name of the class of the `SSLSocketFactory`.
protected int	timeLimit The timeLimit (in milliseconds) to use when the realm is configured with `userSearch`.
private StartTlsResponse	tls
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 String	userBase The base element for user searches.
protected String	userPassword The attribute name used to retrieve the user password.
protected 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 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 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 String	userRoleName The name of an attribute in the user's entry containing roles for that user
protected String	userSearch The message format used to search for a user, with "{0}" marking the spot where the username goes.
private boolean	userSearchAsUser When searching for users, should the search be performed as the user currently being authenticated?
protected boolean	userSubtree Should we search the entire subtree for matching users?
private boolean	useStartTls Whether to use TLS for connections

Inherited from org.apache.catalina.realm.RealmBase:: allRolesMode container containerLog realmPath sm stripRealmForGss support USER_ATTRIBUTES_DELIMITER USER_ATTRIBUTES_WILDCARD userAttributes userAttributesList validate x509UsernameRetriever x509UsernameRetrieverClassName

Constructor Summary

Access	Constructor and Description
public	JNDIRealm()

Method Summary

Modifier and Type	Method and Description
private ArrayList<String>	Returns: the list of attribute values addAttributeValues(String Attribute name attrId, Attributes Attributes containing the new values attrs, ArrayList<String> ArrayList containing values found so far values) Add values of a specified attribute to a list
public Principal	authenticate(String Username of the Principal to look up username, String Password or other credentials to use in authenticating this username credentials) Overrides org.apache.catalina.realm.RealmBase.authenticate. Implements org.apache.catalina.Realm.authenticate. Try to authenticate using the specified username and credentials.
public Principal	Returns: the associated principal, or `null` if there is none. authenticate(JNDIRealm.JNDIConnection The directory context connection, String Username of the Principal to look up username, String Password or other credentials to use in authenticating this username credentials) Return the Principal associated with the specified username and credentials, if there is one; otherwise return `null`.
public Principal	authenticate(String Username of the Principal to look up username) Overrides org.apache.catalina.realm.RealmBase.authenticate. Implements org.apache.catalina.Realm.authenticate. Try to authenticate with the specified username.
public Principal	authenticate(String Username of the Principal to look up username, String Digest which has been submitted by the client clientDigest, String Unique (or supposedly unique) token which has been used for this request nonce, String the nonce counter nc, String the client chosen nonce cnonce, String the "quality of protection" (`nc` and `cnonce` will only be used, if `qop` is not `null`). qop, String Realm name realm, String Second digest calculated as digest(Method + ":" + uri) digestA2, String The message digest algorithm to use algorithm) Overrides org.apache.catalina.realm.RealmBase.authenticate. Overrides default org.apache.catalina.Realm.authenticate. Try to authenticate with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 7616.
public Principal	authenticate(X509Certificate[] Array of client certificates, with the first one in the array being the certificate of the client itself. certs) Overrides org.apache.catalina.realm.RealmBase.authenticate. Implements org.apache.catalina.Realm.authenticate. Try to authenticate using a chain of `X509Certificate`s.
public Principal	authenticate(GSSContext The gssContext processed by the `Authenticator`. gssContext, boolean Should the realm attempt to store the delegated credentials in the returned Principal? storeCred) Overrides org.apache.catalina.realm.RealmBase.authenticate. Implements org.apache.catalina.Realm.authenticate. Try to authenticate using a `GSSContext`.
public Principal	authenticate(GSSName The `GSSName` of the principal to look up gssName, GSSCredential The `GSSCredential` of the principal, may be `null` gssCredential) Overrides org.apache.catalina.realm.RealmBase.authenticate. Implements org.apache.catalina.Realm.authenticate. Try to authenticate using a `GSSName`.
protected boolean	Returns: `true` if the credentials are validated bindAsUser(DirContext The directory context context, JNDIRealm.User The User to be authenticated user, String Authentication credentials credentials) Check credentials by binding to the directory as the user
protected boolean	Returns: `true` if the credentials are validated checkCredentials(DirContext The directory context context, JNDIRealm.User The User to be authenticated user, String The credentials presented by the user credentials) Check whether the given User can be authenticated with the given credentials.
protected void	close(JNDIRealm.JNDIConnection The directory context to be closed connection) Close any open connection to the directory server for this Realm.
protected void	closePooledConnections() Close all pooled connections.
protected boolean	Returns: `true` if the credentials are validated compareCredentials(DirContext The directory context context, JNDIRealm.User The User to be authenticated info, String Authentication credentials credentials) Check whether the credentials presented by the user match those retrieved from the directory.
private Object	constructInstance(String className)
protected static String	convertToHexEscape(String input)
protected JNDIRealm.JNDIConnection	Returns: the new connection create() Create a new connection wrapper, along with the message formats.
private DirContext	createDirContext(Hashtable<String, String> env)
private SSLSocketFactory	createSSLContextFactoryFromProtocol(String protocol)
private SSLSocketFactory	createSSLSocketFactoryFromClassName(String className)
private DirContext	Returns: configured `LdapContext` createTlsDirContext(Hashtable<String, String> Environment to use for context creation env) Create a tls enabled LdapContext and set the StartTlsResponse tls instance variable.
protected String	Returns: The string representation of the attribute value doAttributeValueEscaping(String The original attribute value input) Implements the necessary escaping to represent an attribute value as a String as per RFC 4514.
protected String	Returns: String the escaped/encoded result doFilterEscaping(String string to escape according to RFC 2254 guidelines inString) Given an LDAP search string, returns the string with certain characters escaped according to RFC 2254 guidelines.
protected JNDIRealm.JNDIConnection	Returns: the connection get() Open (if necessary) and return a connection to the configured directory server for this Realm.
public boolean	Returns: the current settings for handling PartialResultExceptions getAdCompat()
public String	Returns: Value of property alternateURL. getAlternateURL() Getter for property alternateURL.
private String	Returns: the attribute value getAttributeValue(String Attribute name attrId, Attributes Attributes containing the required value attrs) Return a String representing the value of the specified attribute.
public String	Returns: the type of authentication to use. getAuthentication()
private String[]	Returns: list of the allowed cipher suites when connections are made using StartTLS getCipherSuitesArray()
public String	Returns: the common role getCommonRole()
public String	Returns: the connection username for this Realm. getConnectionName()
public String	Returns: the connection password for this Realm. getConnectionPassword()
public int	Returns: the connection pool size, or the default value 1 if pooling is disabled getConnectionPoolSize()
public String	Returns: the connection timeout. getConnectionTimeout()
public String	Returns: the connection URL for this Realm. getConnectionURL()
public String	Returns: the JNDI context factory for this Realm. getContextFactory()
public String	Returns: the derefAliases setting to be used. getDerefAliases()
protected Hashtable<String, String>	Returns: java.util.Hashtable the configuration for the directory context. getDirectoryContextEnvironment() Create our directory context configuration.
protected String	Returns: String containing the distinguished name getDistinguishedName(DirContext Our DirContext context, String The base DN base, SearchResult The search result result) Returns the distinguished name of a search result.
public boolean	getForceDnHexEscape()
public HostnameVerifier	Returns: the `HostnameVerifier` to use for peer certificate verification when opening connections using StartTLS. getHostnameVerifier()
public String	Returns: name of the `HostnameVerifier` class used for connections using StartTLS, or the empty string, if the default verifier should be used. getHostnameVerifierClassName()
protected String	Returns: the password associated with the given principal's user name. getPassword(String The user name username) Implements abstract org.apache.catalina.realm.RealmBase.getPassword. Get the password for the specified user.
protected Principal	Returns: the Principal associated with the given certificate. getPrincipal(String The user name username) Implements abstract org.apache.catalina.realm.RealmBase.getPrincipal. Get the principal associated with the specified certificate.
protected Principal	getPrincipal(GSSName The GSS name gssName, GSSCredential the GSS credential of the principal gssCredential) Overrides org.apache.catalina.realm.RealmBase.getPrincipal. Get the principal associated with the specified `GSSName`.
protected Principal	getPrincipal(String username, GSSCredential gssCredential)
protected Principal	Returns: the Principal associated with the given certificate. getPrincipal(JNDIRealm.JNDIConnection The directory context connection, String The user name username, GSSCredential The credentials gssCredential) Get the principal associated with the specified certificate.
public String	Returns: the protocol to be used. getProtocol()
public String	Returns: the read timeout. getReadTimeout()
public String	Returns: the current settings for handling JNDI referrals. getReferrals()
public String	Returns: the base element for role searches. getRoleBase()
public String	Returns: the role name attribute name for this Realm. getRoleName()
public boolean	Returns: the "The nested group search flag" flag. getRoleNested()
protected List<String>	Returns: the list of role names getRoles(JNDIRealm.JNDIConnection The directory context we are searching connection, JNDIRealm.User The User to be checked user) Return a List of roles associated with the given User.
public String	Returns: the message format pattern for selecting roles in this Realm. getRoleSearch()
public boolean	Returns: the "search subtree for roles" flag. getRoleSubtree()
public long	getSizeLimit()
public String	getSpnegoDelegationQop()
private SSLSocketFactory	getSSLSocketFactory()
private String[]	Returns: the list of supported ssl protocols by the default `SSLContext` getSupportedSslProtocols()
public int	getTimeLimit()
protected JNDIRealm.User	Returns: the User object getUser(JNDIRealm.JNDIConnection The directory context connection, String Username to be looked up 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	Returns: the User object getUser(JNDIRealm.JNDIConnection The directory context connection, String Username to be looked up username, String User credentials (optional) 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	Returns: the User object getUser(JNDIRealm.JNDIConnection The directory context connection, String Username to be looked up username, String User credentials (optional) credentials, int Index into userPatternFormatArray curUserPattern) Return a User object containing information about the user with the specified username, if found in the directory; otherwise return `null`.
public String	Returns: the base element for user searches. getUserBase()
protected JNDIRealm.User	Returns: the User object getUserByPattern(DirContext The directory context context, String The username username, String[] String[]containing names of attributes to attrIds, String Distinguished name of the user retrieve. 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	Returns: the User object getUserByPattern(JNDIRealm.JNDIConnection The directory context connection, String The username username, String User credentials (optional) credentials, String[] String[]containing names of attributes to attrIds, int Index into userPatternFormatArray 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	Returns: the User object getUserBySearch(JNDIRealm.JNDIConnection The directory context connection, String The username username, String[] String[]containing names of attributes to retrieve. 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`.
public String	Returns: the password attribute used to retrieve the user password. getUserPassword()
public String	Returns: the message format pattern for selecting users in this Realm. getUserPattern()
public String	getUserRoleAttribute()
public String	Returns: the user role name attribute name for this Realm. getUserRoleName()
public String	Returns: the message format pattern for selecting users in this Realm. getUserSearch()
public boolean	Returns: the "search subtree for users" flag. getUserSubtree()
public boolean	Returns: flag whether to use StartTLS for connections to the ldap server getUseStartTls()
public boolean	isAvailable() Overrides default org.apache.catalina.Realm.isAvailable. Return the availability of the realm for authentication.
public boolean	isRoleSearchAsUser()
public boolean	Returns: The value of useContextClassLoader isUseContextClassLoader() Returns whether to use the context or default ClassLoader.
public boolean	isUseDelegatedCredential()
public boolean	isUserSearchAsUser()
protected void	open(JNDIRealm.JNDIConnection The directory server connection wrapper connection) Create a new connection to the directory server.
protected String[]	Returns: a parsed string array parseUserPatternString(String - a string LDAP search paths surrounded by parentheses 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 The directory context to release connection) Release our use of this connection so that it can be recycled.
private void	restoreEnvironmentParameter(DirContext context, String parameterName, Hashtable<?, ?> preservedEnvironment)
private NamingEnumeration<SearchResult>	Returns: enumeration with all found entries searchAsUser(DirContext context to search on context, JNDIRealm.User user to bind on user, String base to start the search from base, String filter to use for the search filter, SearchControls controls to use for the search controls, boolean `true` when the search should be done as user, or `false` for using the default credentials searchAsUser) Perform the search on the context as the `dn`, when `searchAsUser` is `true`, otherwise search the context with the default credentials.
public void	setAdCompat(boolean `true` to ignore partial results adCompat) How do we handle PartialResultExceptions?
public void	setAlternateURL(String New value of property alternateURL. alternateURL) Setter for property alternateURL.
public void	setAuthentication(String The authentication authentication) Set the type of authentication to use.
public void	setCipherSuites(String comma separated list of allowed cipher suites suites) Set the allowed cipher suites when opening a connection using StartTLS.
public void	setCommonRole(String The common role commonRole) Set the common role
public void	setConnectionName(String The new connection username connectionName) Set the connection username for this Realm.
public void	setConnectionPassword(String The new connection password connectionPassword) Set the connection password for this Realm.
public void	setConnectionPoolSize(int the new pool size connectionPoolSize) Set the connection pool size
public void	setConnectionTimeout(String The new connection timeout timeout) Set the connection timeout.
public void	setConnectionURL(String The new connection URL connectionURL) Set the connection URL for this Realm.
public void	setContextFactory(String The new context factory contextFactory) Set the JNDI context factory for this Realm.
public void	setDerefAliases(String New value of property derefAliases. derefAliases) Set the value for derefAliases to be used when searching the directory.
public void	setForceDnHexEscape(boolean forceDnHexEscape)
public void	setHostnameVerifierClassName(String class name of the `HostnameVerifier` to be constructed verifierClassName) Set the `HostnameVerifier` to be used when opening connections using StartTLS.
public void	setProtocol(String The new protocol. protocol) Set the protocol for this Realm.
public void	setReadTimeout(String The new read timeout timeout) Set the read timeout.
public void	setReferrals(String The referral handling referrals) How do we handle JNDI referrals?
public void	setRoleBase(String The new base element roleBase) Set the base element for role searches.
public void	setRoleName(String The new role name attribute name roleName) Set the role name attribute name for this Realm.
public void	setRoleNested(boolean The nested group search flag roleNested) Set the "search subtree for roles" flag.
public void	setRoleSearch(String The new role search pattern roleSearch) Set the message format pattern for selecting roles in this Realm.
public void	setRoleSearchAsUser(boolean roleSearchAsUser)
public void	setRoleSubtree(boolean The new search flag roleSubtree) Set the "search subtree for roles" flag.
public void	setSizeLimit(long sizeLimit)
public void	setSpnegoDelegationQop(String spnegoDelegationQop)
public void	setSslProtocol(String one of the allowed ssl protocol names protocol) Set the ssl protocol to be used for connections using StartTLS.
public void	setSslSocketFactoryClassName(String class name of the factory to be constructed factoryClassName) Set the `SSLSocketFactory` to be used when opening connections using StartTLS.
public void	setTimeLimit(int timeLimit)
public void	setUseContextClassLoader(boolean True means use context ClassLoader useContext) Sets whether to use the context or default ClassLoader.
public void	setUseDelegatedCredential(boolean useDelegatedCredential)
public void	setUserBase(String The new base element userBase) Set the base element for user searches.
public void	setUserPassword(String The new password attribute userPassword) Set the password attribute used to retrieve the user password.
public void	setUserPattern(String The new user pattern userPattern) Set the message format pattern for selecting users in this Realm.
public void	setUserRoleAttribute(String userRoleAttribute)
public void	setUserRoleName(String The new userRole name attribute name userRoleName) Set the user role name attribute name for this Realm.
public void	setUserSearch(String The new user search pattern userSearch) Set the message format pattern for selecting users in this Realm.
public void	setUserSearchAsUser(boolean userSearchAsUser)
public void	setUserSubtree(boolean The new search flag userSubtree) Set the "search subtree for users" flag.
public void	setUseStartTls(boolean `true` when StartTLS should be used. Default is `false`. useStartTls) Flag whether StartTLS should be used when connecting to the ldap server
protected void	startInternal() Overrides org.apache.catalina.realm.RealmBase.startInternal. Prepare for the beginning of active use of the public methods of this component and implement the requirements of `org.apache.catalina.util.LifecycleBase#startInternal()`.
protected void	stopInternal() Overrides org.apache.catalina.realm.RealmBase.stopInternal. Gracefully terminate the active use of the public methods of this component and implement the requirements of `org.apache.catalina.util.LifecycleBase#stopInternal()`.
private void	userCredentialsAdd(DirContext DirContext to configure context, String Distinguished name of user dn, String Credentials of user credentials) Configure the context to use the provided credentials for authentication.
private void	userCredentialsRemove(DirContext DirContext to configure context) Configure the context to use `connectionName` and `connectionPassword` if specified or an anonymous connection if those attributes are not specified.

public Class JNDIRealm

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary