Catalina Functional Specifications (9.0.22) - MemoryRealm
Author: Craig McClanahan

## MemoryRealm

### Table of Contents

- Overview
  1. Introduction
  2. External Specifications
  3. Implementation Requirements
- Dependencies
  1. Environmental Dependencies
  2. Container Dependencies
- Functionality
  1. Overview of Operation
  2. Detailed Functional Requirements
- Testable Assertions

### Overview

#### 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.

#### External Specifications

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

- None

#### 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 to the assertions implied by the functionality requirements listed above, the following additional assertions shall be tested to validate the behavior of `MemoryRealm`:

### Comments

Notice: This comments section collects your suggestions on improving documentation for Apache Tomcat.
If you have trouble and need help, read Find Help page and ask your question on the tomcat-users mailing list. Do not ask such questions here. This is not a Q&A section.
The Apache Comments System is explained here. Comments may be removed by our moderators if they are either implemented or considered invalid/off-topic.