JNDIRealm
Overview
Introduction
The purpose of the JNDIRealm implementation is to provide a mechanism by which Tomcat 5 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>
External Specifications
The implementation of this functionality depends on the following external specifications:
- Java Naming and Directory Interface (version 1.2.1 or later)
Implementation Requirements
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]
Dependencies
Environmental Dependencies
The following environmental dependencies must be met in order for JNDIRealm to operate correctly:
- The desire to utilize JNDIRealm must be registered in
$CATALINA_HOME/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 appropriateAuthenticator
.
Container Dependencies
Correct operation of JNDIRealm depends on the following specific features of the surrounding container:
- Interactions with
JNDIRealm
will be initiated by the appropriateAuthenticator
implementation, based on the login method that is selected.JNDIRealm
must have the JNDI API classes available to it. For a JDK 1.2 container, that meansjndi.jar
and the appropriate implementation (such asldap.jar
) must be placed in theserver/lib
directory.
Functionality
Operational Modes
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 configureJDBCRealm
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 thisRealm
. The password can be stored in cleartext, or in one of the digested modes supported by theorg.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.
Administrator Login Mode Functionality
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 aList
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 classorg.apache.catalina.realm.GenericPrincipal
, with arealm
property that is equal to our instance.- If the passed
principal
meets these criteria, check the specified role against the list returned bygetRoles()
, and returntrue
if the specified role is included; otherwise, returnfalse
.- If the passed
principal
does not meet these criteria, returnfalse
.
Username Login Mode Functionality
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 aList
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 classorg.apache.catalina.realm.GenericPrincipal
, with arealm
property that is equal to our instance.- If the passed
principal
meets these criteria, check the specified role against the list returned bygetRoles()
, and returntrue
if the specified role is included; otherwise, returnfalse
.- If the passed
principal
does not meet these criteria, returnfalse
.
Testable Assertions
In addition the the assertions implied by the functionality requirements
listed above, the following additional assertions shall be tested to
validate the behavior of JNDIRealm
: