Links Administrative Apps Internal Servlets Realm Implementations | MemoryRealmOverview |
Introduction |
The purpose of the MemoryRealm 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 simple text-based configuration file in XML format. This is
intended to simplify the initial installation and operation of Tomcat,
without the complexity of configuring a database or directory server
based Realm. It is not intended for production use.
This specification reflects a combination of functionality that is
already present in the org.apache.catalina.realm.MemoryRealm
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.
|
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
MemoryRealm to operate correctly:
- The desire to utilize MemoryRealm must be registered in
$CATALINA_BASE/conf/server.xml , in a
<Realm> element that is nested inside a
corresponding <Engine> , <Host> ,
or <Context> element. (This is already
included in the default server.xml file.)
|
Container Dependencies |
Correct operation of MemoryRealm depends on the following
specific features of the surrounding container:
- Interactions with
MemoryRealm will be initiated by
the appropriate Authenticator implementation, based
on the login method that is selected.
MemoryRealm must have an XML parser compatible with
the JAXP/1.1 APIs available to it. This is normally accomplished
by placing the corresponding JAR files in directory
$CATALINA_HOME/lib .
|
|
Functionality |
Overview of Operation |
The main purpose of MemoryRealm is to allow Catalina to
authenticate users, and look up the corresponding security roles, from
the information found in an XML-format configuration file. The format
of this file is described below. When a MemoryRealm
instance is started, it will read the contents of this XML file and create
an "in memory database" of all the valid users and their associated
security roles.
Each time that Catalina needs to authenticate a user, it will call
the authenticate() method of this Realm implementation,
passing the username and password that were specified by the user. If
we find the user in the database (and match on the password), we accumulate
all of the security roles that are defined for this user, and create a
new GenericPrincipal object to be returned. If the user
is not authenticated, we return null instead. The
GenericUser object caches the set of security roles that
were owned by this user at the time of authentication, so that calls to
isUserInRole() can be answered without going back to the
database every time.
|
Detailed Functional Requirements |
Configurable Properties
The implementation shall support the following properties
that can be configured with JavaBeans property setters:
- Configurable debugging detail level.
- Configurable file pathname (absolute or relative to
$CATALINA_BASE of the XML file containing our
defined users. [conf/tomcat-users.xml ].
Lifecycle Functionality
The following processing must be performed when the start()
method is called:
- Open and parse the specified XML file.
- Create an in-memory database representation of the XML file
contents.
- NOTE - There is no requirement to recognize
subsequent changes to the contents of the XML file.
The following processing must be performed when the stop()
method is called:
- Release object references to the in-memory database representation.
Method authenticate() Functionality
When authenticate() is called, the following processing
is required:
- Select the one and only "user" instance from the in-memory database,
based on matching the specified username. If there is no such
instance, return
null .
- Authenticate the user by comparing the (possibly encrypted) password
value that was received against the password presented by the user.
If there is no match, return
null .
- Construct a new instance of class
org.apache.catalina.realm.GenericPrincipal (if not
already using this as the internal database representation) that
contains the authenticated username and a List of the
security roles associated with this user.
- 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 MemoryRealm :
|
|