Overview of Realm Configuration

What is a Realm?

A Realm is a “database” of usernames and passwords that identify valid users of a web application (or set of web applications), plus an enumeration of the list of roles associated with each valid user. You can think of roles as similar to groups in Unix-like operating systems, because access to specific web application resources is granted to all users possessing a particular role (rather than enumerating the list of associated usernames). A particular user can have any number of roles associated with their username.

Although the Servlet Specification describes a portable mechanism for applications to declare their security requirements (in the web.xml deployment descriptor), there is no portable API defining the interface between a servlet container and the associated user and role information. In many cases, however, it is desirable to “connect” a servlet container to some existing authentication database or mechanism that already exists in the production environment. Therefore, Tomcat defines a Java interface (org.apache.catalina.Realm) that can be implemented by “plug in” components to establish this connection. Six standard plug-ins are provided, supporting connections to various sources of authentication information:

• JDBCRealm – Accesses authentication information stored in a relational database, accessed via a JDBC driver.
• DataSourceRealm – Accesses authentication information stored in a relational database, accessed via a named JNDI JDBC DataSource.
• JNDIRealm – Accesses authentication information stored in an LDAP based directory server, accessed via a JNDI provider.
• UserDatabaseRealm – Accesses authentication information stored in an UserDatabase JNDI resource, which is typically backed by an XML document (conf/tomcat-users.xml).
• MemoryRealm – Accesses authentication information stored in an in-memory object collection, which is initialized from an XML document (conf/tomcat-users.xml).
• JAASRealm – Accesses authentication information through the Java Authentication & Authorization Service (JAAS) framework.

It is also possible to write your own Realm implementation, and integrate it with Tomcat. To do so, you need to:

• Implement org.apache.catalina.Realm,
• Place your compiled realm in $CATALINA_HOME/lib,
• Declare your realm as described in the “Configuring a Realm” section below,
• Declare your realm to the MBeans Descriptor.

Configuring a Realm

Before getting into the details of the standard Realm implementations, it is important to understand, in general terms, how a Realm is configured. In general, you will be adding an XML element to your conf/server.xmlconfiguration file that looks something like this:

<Realm className=”… class name for this implementation”

… other attributes for this implementation …/>

The <Realm> element can be nested inside any one of the following Container elements. The location of the Realm element has a direct impact on the “scope” of that Realm (i.e. which web applications will share the same authentication information):

Inside an <Engine> element – This Realm will be shared across ALL web applications on ALL virtual hosts, UNLESS it is overridden by a Realm element nested inside a subordinate <Host> or <Context> element.

• Inside a <Host> element – This Realm will be shared across ALL web applications for THIS virtual host, UNLESS it is overridden by a Realm element nested inside a subordinate <Context> element.
• Inside a <Context> element – This Realm will be used ONLY for THIS web application.