Links Administrative Apps Internal Servlets Realm Implementations | JNDIRealmOverview |
Introduction |
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>
|
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_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 .
|
Container Dependencies |
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.
|
|
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 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.
|
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 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 .
|
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:
The following processing must be performed when the stop()
method is called:
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 .
|
|
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 :
|
|