Catalina Functional Specifications

The purpose of the JNDIRealm implementation is to provide a mechanism by which Tomcat can acquire information needed to authenticate web application users, and define their security roles, from a directory server or other service accessed via JNDI APIs. For integration with Catalina, this class must implement the org.apache.catalina.Realm interface.

This specification reflects a combination of functionality that is already present in the org.apache.catalina.realm.JNDIRealm class, as well as requirements for enhancements that have been discussed. Where appropriate, requirements statements are marked [Current] and [Requested] to distinguish them.

The current status of this functional specification is PROPOSED. It has not yet been discussed and agreed to on the TOMCAT-DEV mailing list.

The code in the current version of JNDIRealm, and the ideas expressed in this functional specification, are the results of contributions from many individuals, including (alphabetically):

• Holman, John <j.g.holman@qmw.ac.uk>
• Lockhart, Ellen <elockhart@home.com>
• McClanahan, Craig <craigmcc@apache.org>

The implementation of this functionality depends on the following external specifications:

• Java Naming and Directory Interface (version 1.2.1 or later)

The implementation of this functionality shall conform to the following requirements:

• Be realized in one or more implementation classes.
• Implement the org.apache.catalina.Realm interface. [Current]
• Implement the org.apache.catalina.Lifecycle interface. [Current]
• Subclass the org.apache.catalina.realm.RealmBase base class.
• Live in the org.apache.catalina.realm package. [Current]
• Support a configurable debugging detail level. [Current]
• Log debugging and operational messages (suitably internationalized) via the getContainer().log() method. [Current]

The following environmental dependencies must be met in order for JNDIRealm to operate correctly:

• The desire to utilize JNDIRealm must be registered in $CATALINA_BASE/conf/server.xml, in a <Realm> element that is nested inside a corresponding <Engine>, <Host>, or <Context> element.
• If the Administrator Login operational mode is selected, the configured administrator username and password must be configured in the corresponding directory server.
• If the Username Login operational mode is selected, the corresponding directory server must be configured to accept logins with the username and password that will be passed to JNDIRealm by the appropriate Authenticator.

Correct operation of JNDIRealm depends on the following specific features of the surrounding container:

• Interactions with JNDIRealm will be initiated by the appropriate Authenticator implementation, based on the login method that is selected.

The completed JNDIRealm must support two major operational modes in order to support all of the required use cases. For the purposes of this document, the modes are called administrator login and Username Login. They are described further in the following paragraphs.

For Administrator Login mode, JNDIRealm will be configured to establish one or more connections (using a connection pool) to an appropriate directory server, using JNDI APIs, under a "system administrator" username and password. This is similar to the approach normally used to configure JDBCRealm to access authentication and access control information in a database. It is assumed that the system administrator username and password that are configured provide sufficient privileges within the directory server to read (but not modify) the username, password, and assigned roles for each valid user of the web application associated with this Realm. The password can be stored in cleartext, or in one of the digested modes supported by the org.apache.catalina.realm.RealmBase base class.

For Username Login mode, JNDIRealm does not normally remain connected to the directory server. Instead, whenever a user is to be authenticated, a connection to the directory server (using the username and password received from the authenticator) is attempted. If this connection is successful, the user is assumed to be successfully authenticated. This connection is then utilized to read the corresponding security roles associated with this user, and the connection is then broken.

NOTE - Username Login mode cannot be used if you have selected login method DIGEST in your web application deployment descriptor (web.xml) file. This restriction exists because the cleartext password is never available to the container, so it is not possible to bind to the directory server using the user's username and password.

Because these operational modes work so differently, the functionality for each mode will be described separately. Whether or not both modes are actually supported by a single class (versus a class per mode) is an implementation detail left to the designer.

NOTE - The current implementation only implements part of the Administrator Lookup mode requirements. It does not support the Username Lookup mode at all, at this point.

Configurable Properties

The implementation shall support the following properties that can be configured with JavaBeans property setters:

• connectionURL - URL of the directory server we will be contacting.
• contextFactory - Fully qualified class name of the JNDI context factory used to retrieve our InitialContext. [com.sun.jndi.ldap.LdapCtxFactory]
• Additional configuration properties required to establish the appropriate connection. [Requested]
• Connection pool configuration properties. [Requested]
• Configuration properties defining how a particular user is authenticated. The following capabilities should be supported:
  • Substitute the specified username into a string. [Requested]
  • Retrieve the distinguished name (DN) of an authorized user via an LDAP search string with a replacement placeholder for the username, and comparison of the password to a configurable attribute retrieved from the search result. [Current]
• Configuration properties defining how the roles associated with a particular authenticated user can be retrieved. The following approaches should be supported:
  • Retrieve a specified attribute (possibly multi-valued) from an LDAP search expression, with a replacement placeholder for the DN of the user. [Current]
  • Retrieve a set of role names that are defined implicitly (by selecting principals that match a search pattern) rather than explicitly (by finding a particular attribute value). [Requested]

Lifecycle Functionality

The following processing must be performed when the start() method is called:

• Establish a connection to the configured directory server, using the configured system administrator username and password. [Current]
• Configure and establish a connection pool of connections to the directory server. [Requested]

The following processing must be performed when the stop() method is called:

• Close any opened connections to the directory server.

Method authenticate() Functionality

When authenticate() is called, the following processing is required:

• Acquire the one and only connection [Current] or acquire a connection from the connection pool [Requested].
• Authenticate the user by retrieving the user's Distinguished Name, based on the specified username and password.
• If the user was not authenticated, release the allocated connection and return null.
• Acquire a List of the security roles assigned to the authenticated user.
• Construct a new instance of class org.apache.catalina.realm.GenericPrincipal, passing as constructor arguments: this realm instance, the authenticated username, and a List of the security roles associated with this user.
• WARNING - Do not attempt to cache and reuse previous GenericPrincipal objects for a particular user, because the information in the directory server might have changed since the last time this user was authenticated.
• Return the newly constructed GenericPrincipal.

Method hasRole() Functionality

When hasRole() is called, the following processing is required:

• The principal that is passed as an argument SHOULD be one that we returned (instanceof class org.apache.catalina.realm.GenericPrincipal, with a realm property that is equal to our instance.
• If the passed principal meets these criteria, check the specified role against the list returned by getRoles(), and return true if the specified role is included; otherwise, return false.
• If the passed principal does not meet these criteria, return false.

Configurable Properties

The implementation shall support the following properties that can be configured with JavaBeans property setters:

• connectionURL - URL of the directory server we will be contacting.
• contextFactory - Fully qualified class name of the JNDI context factory used to retrieve our InitialContext. [com.sun.jndi.ldap.LdapCtxFactory]
• Additional configuration properties required to establish the appropriate connection. [Requested]
• Connection pool configuration properties. [Requested]
• Configuration properties defining if and how a user might be looked up before binding to the directory server. The following approaches should be supported:
  • No previous lookup is required - username specified by the user is the same as that used to authenticate to the directory server.
  • Substitute the specified username into a string.
  • Search the directory server based on configured criteria to retrieve the distinguished name of the user, then attempt to bind with that distinguished name.
• Configuration properties defining how the roles associated with a particular authenticated user can be retrieved. The following approaches should be supported:
  • Retrieve a specified attribute (possibly multi-valued) from an LDAP search expression, with a replacement placeholder for the DN of the user. [Current]

Lifecycle Functionality

The following processing must be performed when the start() method is called:

• None required.

The following processing must be performed when the stop() method is called:

• None required.

Method authenticate() Functionality

When authenticate() is called, the following processing is required:

• Attempt to bind to the directory server, using the username and password provided by the user.
• If the user was not authenticated, release the allocated connection and return null.
• Acquire a List of the security roles assigned to the authenticated user.
• Construct a new instance of class org.apache.catalina.realm.GenericPrincipal, passing as constructor arguments: this realm instance, the authenticated username, and a List of the security roles associated with this user.
• WARNING - Do not attempt to cache and reuse previous GenericPrincipal objects for a particular user, because the information in the directory server might have changed since the last time this user was authenticated.
• Return the newly constructed GenericPrincipal.

Method hasRole() Functionality

When hasRole() is called, the following processing is required:

• The principal that is passed as an argument SHOULD be one that we returned (instanceof class org.apache.catalina.realm.GenericPrincipal, with a realm property that is equal to our instance.
• If the passed principal meets these criteria, check the specified role against the list returned by getRoles(), and return true if the specified role is included; otherwise, return false.
• If the passed principal does not meet these criteria, return false.