| <?xml version="1.0"?> |
| <!DOCTYPE document [ |
| <!ENTITY project SYSTEM "project.xml"> |
| ]> |
| <document url="realm-howto.html"> |
| |
| &project; |
| |
| <properties> |
| <author email="craigmcc@apache.org">Craig R. McClanahan</author> |
| <author email="yoavs@apache.org">Yoav Shapira</author> |
| <author email="arjaquith@mindspring.com">Andrew R. Jaquith</author> |
| <title>Realm Configuration HOW-TO</title> |
| </properties> |
| |
| <body> |
| |
| |
| <section name="Table of Contents"> |
| |
| <p> |
| <a href="#Quick Start">Quick Start</a><br /> |
| <blockquote> |
| <a href="#What is a Realm?">What is a Realm?</a><br /> |
| <a href="#Configuring a Realm">Configuring a Realm</a><br /> |
| </blockquote> |
| <a href="#Common Features">Common Features</a><br /> |
| <blockquote> |
| <a href="#Digested Passwords">Digested Passwords</a><br /> |
| <a href="#Example Application">Example Application</a><br /> |
| <a href="#Manager Application">Manager Application</a><br /> |
| <a href="#Realm Logging">Logging Within Realms</a><br /> |
| </blockquote> |
| <a href="#Standard Realm Implementations"> |
| Standard Realm Implementations</a><br /> |
| <blockquote> |
| <a href="#JDBCRealm">JDBCRealm</a><br /> |
| <a href="#DataSourceRealm">DataSourceRealm</a><br /> |
| <a href="#JNDIRealm">JNDIRealm</a><br /> |
| <a href="#MemoryRealm">MemoryRealm</a><br /> |
| <a href="#JAASRealm">JAASRealm</a><br /> |
| <a href="#UserDatabaseRealm">UserDatabaseRealm</a><br /> |
| </blockquote> |
| </p> |
| |
| </section> |
| |
| <section name="Quick Start"> |
| |
| <p>This document describes how to configure Tomcat to support <em>container |
| managed security</em>, by connecting to an existing "database" of usernames, |
| passwords, and user roles. You only need to care about this if you are using |
| a web application that includes one or more |
| <code><security-constraint></code> elements, and a |
| <code><login-config></code> element defining how users are required |
| to authenticate themselves. If you are not utilizing these features, you can |
| safely skip this document.</p> |
| |
| <p>For fundamental background information about container managed security, |
| see the <a href="http://java.sun.com/products/servlet/download.html">Servlet |
| Specification (Version 2.4)</a>, Section 12.</p> |
| |
| <p>For information about utilizing the <em>Single Sign On</em> feature of |
| Tomcat 5 (allowing a user to authenticate themselves once across the entire |
| set of web applications associated with a virtual host), see |
| <a href="config/host.html#Single Sign On">here</a>.</p> |
| |
| </section> |
| |
| |
| <section name="Overview"> |
| |
| |
| <subsection name="What is a Realm?"> |
| |
| <p>A <strong>Realm</strong> 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 <em>roles</em> associated with each valid user. |
| You can think of roles as similar to <em>groups</em> 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.</p> |
| |
| <p>Although the Servlet Specification describes a portable mechanism for |
| applications to <em>declare</em> their security requirements (in the |
| <code>web.xml</code> 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 desireable to "connect" |
| a servlet container to some existing authentication database or mechanism |
| that already exists in the production environment. Therefore, Tomcat 5 |
| defines a Java interface (<code>org.apache.catalina.Realm</code>) that |
| can be implemented by "plug in" components to establish this connection. |
| Five standard plug-ins are provided, supporting connections to various |
| sources of authentication information:</p> |
| <ul> |
| <li><a href="#JDBCRealm">JDBCRealm</a> - Accesses authentication information |
| stored in a relational database, accessed via a JDBC driver.</li> |
| <li><a href="#DataSourceRealm">DataSourceRealm</a> - Accesses authentication |
| information stored in a relational database, accessed via a named JNDI |
| JDBC DataSource.</li> |
| <li><a href="#JNDIRealm">JNDIRealm</a> - Accesses authentication information |
| stored in an LDAP based directory server, accessed via a JNDI provider. |
| </li> |
| <li><a href="#MemoryRealm">MemoryRealm</a> - Accesses authentication |
| information stored in an in-memory object collection, which is initialized |
| from an XML document (<code>conf/tomcat-users.xml</code>).</li> |
| <li><a href="#JAASRealm">JAASRealm</a> - Accesses authentication information |
| through the Java Authentication & Authorization Service (JAAS) |
| framework.</li> |
| </ul> |
| |
| <p>It is also possible to write your own <code>Realm</code> implementation, |
| and integrate it with Tomcat 5. To do so, you need to: |
| <ul> |
| <li>Implement <code>org.apache.catalina.Realm</code>,</li> |
| <li>Place your compiled realm in $CATALINA_HOME/server/lib,</li> |
| <li>Declare your realm as described in the "Configuring a Realm" section below,</li> |
| <li>Declare your realm to the <a href="mbeans-descriptor-howto.html">MBeans Descriptor</a>.</li> |
| </ul> |
| </p> |
| |
| </subsection> |
| |
| |
| <subsection name="Configuring a Realm"> |
| |
| <p>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 <code>conf/server.xml</code> |
| configuration file, that looks something like this:</p> |
| |
| <source> |
| <Realm className="... class name for this implementation" |
| ... other attributes for this implementation .../> |
| </source> |
| |
| <p>The <code><Realm></code> element can be nested inside any one of |
| of the following <code>Container</code> 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): |
| </p> |
| <ul> |
| <li><em>Inside an <Engine> element</em> - 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 <code><Host></code> |
| or <code><Context></code> element.</li> |
| <li><em>Inside a <Host> element</em> - 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 <code><Context></code> |
| element.</li> |
| <li><em>Inside a <Context> element</em> - This Realm will be used ONLY |
| for THIS web application.</li> |
| </ul> |
| |
| |
| </subsection> |
| |
| |
| </section> |
| |
| |
| <section name="Common Features"> |
| |
| |
| <subsection name="Digested Passwords"> |
| |
| <p>For each of the standard <code>Realm</code> implementations, the |
| user's password (by default) is stored in clear text. In many |
| environments, this is undesireable because casual observers of the |
| authentication data can collect enough information to log on |
| successfully, and impersonate other users. To avoid this problem, the |
| standard implementations support the concept of <em>digesting</em> |
| user passwords. This allows the stored version of the passwords to be |
| encoded (in a form that is not easily reversible), but that the |
| <code>Realm</code> implementation can still utilize for |
| authentication.</p> |
| |
| <p>When a standard realm authenticates by retrieving the stored |
| password and comparing it with the value presented by the user, you |
| can select digested passwords by specifying the <code>digest</code> |
| attribute on your <code><Realm></code> element. The value for |
| this attribute must be one of the digest algorithms supported by the |
| <code>java.security.MessageDigest</code> class (SHA, MD2, or MD5). |
| When you select this option, the contents of the password that is |
| stored in the <code>Realm</code> must be the cleartext version of the |
| password, as digested by the specified algorithm.</p> |
| |
| <p>When the <code>authenticate()</code> method of the Realm is called, the |
| (cleartext) password specified by the user is itself digested by the same |
| algorithm, and the result is compared with the value returned by the |
| <code>Realm</code>. An equal match implies that the cleartext version of the |
| original password is the same as the one presented by the user, so that this |
| user should be authorized.</p> |
| |
| <p>To calculate the digested value of a cleartext password, two convenience |
| techniques are supported:</p> |
| <ul> |
| <li>If you are writing an application that needs to calculate digested |
| passwords dynamically, call the static <code>Digest()</code> method of the |
| <code>org.apache.catalina.realm.RealmBase</code> class, passing the |
| cleartext password and the digest algorithm name as arguments. This |
| method will return the digested password.</li> |
| <li>If you want to execute a command line utility to calculate the digested |
| password, simply execute |
| <source> |
| java org.apache.catalina.realm.RealmBase \ |
| -a {algorithm} {cleartext-password} |
| </source> |
| and the digested version of this cleartext password will be returned to |
| standard output.</li> |
| </ul> |
| |
| <p>If using digested passwords with DIGEST authentication, the cleartext used |
| to generate the digest is different. In the examples above |
| <code>{cleartext-password}</code> must be replaced with |
| <code>{username}:{realm}:{cleartext-password}</code>. For example, in a |
| development environment this might take the form |
| <code>testUser:localhost:8080:testPassword</code>.</p> |
| |
| <p>To use either of the above techniques, the |
| <code>$CATALINA_HOME/server/lib/catalina.jar</code> file will need to be |
| on your class path to make the <code>RealmBase</code> class available. In |
| addition, you will need the JMX jar and the commons-logging jar (either |
| commons-logging-api.jar or commons-logging.jar). Both of these are included |
| with the Tomcat distribution. |
| </p> |
| |
| <p>Non-ASCII usernames and/or passwords are supported using |
| <source>java org.apache.catalina.realm.RealmBase \ |
| -a {algorithm} -e {encoding} {input} |
| </source> |
| but care is required to ensure that the non-ASCII input is |
| correctly passed to the digester. |
| The digester returns <code>{input}:{digest}</code>. If the input appears |
| corrupted in the return, the digest will be invalid.</p> |
| |
| </subsection> |
| |
| |
| |
| <subsection name="Example Application"> |
| |
| <p>The example application shipped with Tomcat 5 includes an area that is |
| protected by a security constraint, utilizing form-based login. To access it, |
| point your browser at |
| <a href="http://localhost:8080/jsp-examples/security/protected/">http://localhost:8080/jsp-examples/security/protected/</a> |
| and log on with one of the usernames and passwords described for the default |
| <a href="#MemoryRealm">MemoryRealm</a>.</p> |
| |
| </subsection> |
| |
| |
| <subsection name="Manager Application"> |
| |
| <p>If you wish to use the <a href="manager-howto.html">Manager Application</a> |
| to deploy and undeploy applications in a running Tomcat 5 installation, you |
| MUST add the "manager" role to at least one username in your selected Realm |
| implementation. This is because the manager web application itself uses a |
| security constraint that requires role "manager" to access ANY request URI |
| within that application.</p> |
| |
| <p>For security reasons, no username in the default Realm (i.e. using |
| <code>conf/tomcat-users.xml</code> is assigned the "manager" role. Therfore, |
| no one will be able to utilize the features of this application until the |
| Tomcat administrator specifically assigns this role to one or more users.</p> |
| |
| </subsection> |
| |
| <subsection name="Realm Logging"> |
| |
| <p>Debugging and exception messages logged by a <code>Realm</code> will |
| be recorded by the logging configuration associated with the container |
| for the realm: its surrounding <a href="config/context.html">Context</a>, |
| <a href="config/host.html">Host</a>, or |
| <a href="config/engine.html">Engine</a>.</p> |
| |
| </subsection> |
| |
| </section> |
| |
| |
| <section name="Standard Realm Implementations"> |
| |
| <subsection name="JDBCRealm"> |
| |
| <h3>Introduction</h3> |
| |
| <p><strong>JDBCRealm</strong> is an implementation of the Tomcat 5 |
| <code>Realm</code> interface that looks up users in a relational database |
| accessed via a JDBC driver. There is substantial configuration flexibility |
| that lets you adapt to existing table and column names, as long as your |
| database structure conforms to the following requirements:</p> |
| <ul> |
| <li>There must be a table, referenced below as the <em>users</em> table, |
| that contains one row for every valid user that this <code>Realm</code> |
| should recognize.</li> |
| <li>The <em>users</em> table must contain at least two columns (it may |
| contain more if your existing applications required it): |
| <ul> |
| <li>Username to be recognized by Tomcat when the user logs in.</li> |
| <li>Password to be recognized by Tomcat when the user logs in. |
| This value may in cleartext or digested - see below for more |
| information.</li> |
| </ul></li> |
| <li>There must be a table, referenced below as the <em>user roles</em> table, |
| that contains one row for every valid role that is assigned to a |
| particular user. It is legal for a user to have zero, one, or more than |
| one valid role.</li> |
| <li>The <em>user roles</em> table must contain at least two columns (it may |
| contain more if your existing applications required it): |
| <ul> |
| <li>Username to be recognized by Tomcat (same value as is specified |
| in the <em>users</em> table).</li> |
| <li>Role name of a valid role associated with this user.</li> |
| </ul></li> |
| </ul> |
| |
| <h3>Quick Start</h3> |
| |
| <p>To set up Tomcat to use JDBCRealm, you will need to follow these steps:</p> |
| <ol> |
| <li>If you have not yet done so, create tables and columns in your database |
| that conform to the requirements described above.</li> |
| <li>Configure a database username and password for use by Tomcat, that has |
| at least read only access to the tables described above. (Tomcat will |
| never attempt to write to these tables.)</li> |
| <li>Place a copy of the JDBC driver you will be using inside the |
| <code>$CATALINA_HOME/server/lib</code> directory (if you do not need it |
| visible to web applications) or <code>$CATALINA_HOME/common/lib</code> |
| (if it will be used both by Tomcat 5 <em>and</em> by your apps). |
| Note that <strong>only</strong> JAR files are recognized!</li> |
| <li>Set up a <code><Realm></code> element, as described below, in your |
| <code>$CATALINA_HOME/conf/server.xml</code> file.</li> |
| <li>Restart Tomcat 5 if it is already running.</li> |
| </ol> |
| |
| <h3>Realm Element Attributes</h3> |
| |
| <p>To configure a JDBCRealm, you must create a <code><Realm></code> |
| element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file, |
| as described <a href="#Configuring a Realm">above</a>. The attributes supported |
| by this Realm are listed in the <a href="config/realm.html">Realm configuration |
| documentation</a>.</p> |
| |
| <h3>Example</h3> |
| |
| <p>An example SQL script to create the needed tables might look something |
| like this (adapt the syntax as required for your particular database):</p> |
| <source> |
| create table users ( |
| user_name varchar(15) not null primary key, |
| user_pass varchar(15) not null |
| ); |
| |
| create table user_roles ( |
| user_name varchar(15) not null, |
| role_name varchar(15) not null, |
| primary key (user_name, role_name) |
| ); |
| </source> |
| |
| <p>Example <code>Realm</code> elements are included (commented out) in the |
| default <code>$CATALINA_HOME/conf/server.xml</code> file. Here's an example |
| for using a MySQL database called "authority", configured with the tables |
| described above, and accessed with username "dbuser" and password "dbpass":</p> |
| <source> |
| <Realm className="org.apache.catalina.realm.JDBCRealm" debug="99" |
| driverName="org.gjt.mm.mysql.Driver" |
| connectionURL="jdbc:mysql://localhost/authority?user=dbuser&amp;password=dbpass" |
| userTable="users" userNameCol="user_name" userCredCol="user_pass" |
| userRoleTable="user_roles" roleNameCol="role_name"/> |
| </source> |
| |
| <h3>Additional Notes</h3> |
| |
| <p>JDBCRealm operates according to the following rules:</p> |
| <ul> |
| <li>When a user attempts to access a protected resource for the first time, |
| Tomcat 5 will call the <code>authenticate()</code> method of this |
| <code>Realm</code>. Thus, any changes you have made to the database |
| directly (new users, changed passwords or roles, etc.) will be immediately |
| reflected.</li> |
| <li>Once a user has been authenticated, the user (and his or her associated |
| roles) are cached within Tomcat for the duration of the user's login. |
| (For FORM-based authentication, that means until the session times out or |
| is invalidated; for BASIC authentication, that means until the user |
| closes their browser). The cached user is <strong>not</strong> saved and |
| restored across sessions serialisations. Any changes to the database |
| information for an already authenticated user will <strong>not</strong> be |
| reflected until the next time that user logs on again.</li> |
| <li>Administering the information in the <em>users</em> and <em>user roles</em> |
| table is the responsibility of your own applications. Tomcat does not |
| provide any built-in capabilities to maintain users and roles.</li> |
| </ul> |
| |
| </subsection> |
| |
| |
| <subsection name="DataSourceRealm"> |
| |
| <h3>Introduction</h3> |
| |
| <p><strong>DataSourceRealm</strong> is an implementation of the Tomcat 5 |
| <code>Realm</code> interface that looks up users in a relational database |
| accessed via a JNDI named JDBC DataSource. There is substantial configuration |
| flexibility that lets you adapt to existing table and column names, as long |
| as your database structure conforms to the following requirements:</p> |
| <ul> |
| <li>There must be a table, referenced below as the <em>users</em> table, |
| that contains one row for every valid user that this <code>Realm</code> |
| should recognize.</li> |
| <li>The <em>users</em> table must contain at least two columns (it may |
| contain more if your existing applications required it): |
| <ul> |
| <li>Username to be recognized by Tomcat when the user logs in.</li> |
| <li>Password to be recognized by Tomcat when the user logs in. |
| This value may in cleartext or digested - see below for more |
| information.</li> |
| </ul></li> |
| <li>There must be a table, referenced below as the <em>user roles</em> table, |
| that contains one row for every valid role that is assigned to a |
| particular user. It is legal for a user to have zero, one, or more than |
| one valid role.</li> |
| <li>The <em>user roles</em> table must contain at least two columns (it may |
| contain more if your existing applications required it): |
| <ul> |
| <li>Username to be recognized by Tomcat (same value as is specified |
| in the <em>users</em> table).</li> |
| <li>Role name of a valid role associated with this user.</li> |
| </ul></li> |
| </ul> |
| |
| <h3>Quick Start</h3> |
| |
| <p>To set up Tomcat to use DataSourceRealm, you will need to follow these steps:</p> |
| <ol> |
| <li>If you have not yet done so, create tables and columns in your database |
| that conform to the requirements described above.</li> |
| <li>Configure a database username and password for use by Tomcat, that has |
| at least read only access to the tables described above. (Tomcat will |
| never attempt to write to these tables.)</li> |
| <li>Configure a JNDI named JDBC DataSource for your database. Refer to the |
| <a href="jndi-datasource-examples-howto.html">JNDI DataSource Example HOW-TO</a> |
| for information on how to configure a JNDI named JDBC DataSource.</li> |
| <li>Set up a <code><Realm></code> element, as described below, in your |
| <code>$CATALINA_HOME/conf/server.xml</code> file.</li> |
| <li>Restart Tomcat 5 if it is already running.</li> |
| </ol> |
| |
| <h3>Realm Element Attributes</h3> |
| |
| <p>To configure a DataSourceRealm, you must create a <code><Realm></code> |
| element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file, |
| as described <a href="#Configuring a Realm">above</a>. The attributes supported |
| by this Realm are listed in the <a href="config/realm.html">Realm configuration |
| documentation</a>.</p> |
| |
| <h3>Example</h3> |
| |
| <p>An example SQL script to create the needed tables might look something |
| like this (adapt the syntax as required for your particular database):</p> |
| <source> |
| create table users ( |
| user_name varchar(15) not null primary key, |
| user_pass varchar(15) not null |
| ); |
| |
| create table user_roles ( |
| user_name varchar(15) not null, |
| role_name varchar(15) not null, |
| primary key (user_name, role_name) |
| ); |
| </source> |
| |
| <p>Here is an example for using a MySQL database called "authority", configured |
| with the tables described above, and accessed with the JNDI JDBC DataSource with |
| name "java:/comp/env/jdbc/authority".</p> |
| <source> |
| <Realm className="org.apache.catalina.realm.DataSourceRealm" debug="99" |
| dataSourceName="jdbc/authority" |
| userTable="users" userNameCol="user_name" userCredCol="user_pass" |
| userRoleTable="user_roles" roleNameCol="role_name"/> |
| </source> |
| |
| <h3>Additional Notes</h3> |
| |
| <p>DataSourceRealm operates according to the following rules:</p> |
| <ul> |
| <li>When a user attempts to access a protected resource for the first time, |
| Tomcat 5 will call the <code>authenticate()</code> method of this |
| <code>Realm</code>. Thus, any changes you have made to the database |
| directly (new users, changed passwords or roles, etc.) will be immediately |
| reflected.</li> |
| <li>Once a user has been authenticated, the user (and his or her associated |
| roles) are cached within Tomcat for the duration of the user's login. |
| (For FORM-based authentication, that means until the session times out or |
| is invalidated; for BASIC authentication, that means until the user |
| closes their browser). The cached user is <strong>not</strong> saved and |
| restored across sessions serialisations. Any changes to the database |
| information for an already authenticated user will <strong>not</strong> be |
| reflected until the next time that user logs on again.</li> |
| <li>Administering the information in the <em>users</em> and <em>user roles</em> |
| table is the responsibility of your own applications. Tomcat does not |
| provide any built-in capabilities to maintain users and roles.</li> |
| </ul> |
| |
| </subsection> |
| |
| |
| <subsection name="JNDIRealm"> |
| |
| <h3>Introduction</h3> |
| |
| <p><strong>JNDIRealm</strong> is an implementation of the Tomcat 5 |
| <code>Realm</code> interface that looks up users in an LDAP directory |
| server accessed by a JNDI provider (typically, the standard LDAP |
| provider that is available with the JNDI API classes). The realm |
| supports a variety of approaches to using a directory for |
| authentication.</p> |
| |
| <h4>Connecting to the directory</h4> |
| |
| <p>The realm's connection to the directory is defined by the |
| <strong>connectionURL</strong> configuration attribute. This is a URL |
| whose format is defined by the JNDI provider. It is usually an LDAP |
| URL that specifies the domain name of the directory server to connect |
| to, and optionally the port number and distinguished name (DN) of the |
| required root naming context.</p> |
| |
| <p>If you have more than one provider you can configure an |
| <strong>alternateURL</strong>. If a socket connection can not be |
| made to the provider at the <strong>connectionURL</strong> an |
| attempt will be made to use the <strong>alternateURL</strong>.</p> |
| |
| <p>When making a connection in order to search the directory and |
| retrieve user and role information, the realm authenticates itself to |
| the directory with the username and password specified by the |
| <strong>connectionName</strong> and |
| <strong>connectionPassword</strong> properties. If these properties |
| are not specified the connection is anonymous. This is sufficient in |
| many cases. |
| </p> |
| |
| |
| <h4>Selecting the user's directory entry</h4> |
| |
| <p>Each user that can be authenticated must be represented in the |
| directory by an individual entry that corresponds to an element in the |
| initial <code>DirContext</code> defined by the |
| <strong>connectionURL</strong> attribute. This user entry must have an |
| attribute containing the username that is presented for |
| authentication.</p> |
| |
| <p>Often the distinguished name of the user's entry contains the |
| username presented for authentication but is otherwise the same for |
| all users. In this case the <strong>userPattern</strong> attribute may |
| be used to specify the DN, with "{0}" marking where |
| the username should be substituted.</p> |
| |
| <p>Otherwise the realm must search the directory to find a unique entry |
| containing the username. The following attributes configure this |
| search: |
| |
| <ul> |
| <li><strong>userBase</strong> - the entry that is the base of |
| the subtree containing users. If not specified, the search |
| base is the top-level context.</li> |
| |
| <li><strong>userSubtree</strong> - the search scope. Set to |
| <code>true</code> if you wish to search the entire subtree |
| rooted at the <strong>userBase</strong> entry. The default value |
| of <code>false</code> requests a single-level search |
| including only the top level.</li> |
| |
| <li><strong>userSearch</strong> - pattern specifying the LDAP |
| search filter to use after substitution of the username.</li> |
| |
| </ul> |
| </p> |
| |
| |
| <h4>Authenticating the user</h4> |
| |
| <ul> |
| <li> |
| <p><b>Bind mode</b></p> |
| |
| <p>By default the realm authenticates a user by binding to |
| the directory with the DN of the entry for that user and the password |
| presented by the user. If this simple bind succeeds the user is considered to |
| be authenticated.</p> |
| |
| <p>For security reasons a directory may store a digest of the user's |
| password rather than the clear text version (see <a href="#Digested |
| Passwords">Digested Passwords</a> for more information). In that case, |
| as part of the simple bind operation the directory automatically |
| computes the correct digest of the plaintext password presented by the |
| user before validating it against the stored value. In bind mode, |
| therefore, the realm is not involved in digest processing. The |
| <strong>digest</strong> attribute is not used, and will be ignored if |
| set.</p> |
| </li> |
| |
| <li> |
| <p><b>Comparison mode</b></p> |
| <p>Alternatively, the realm may retrieve the stored |
| password from the directory and compare it explicitly with the value |
| presented by the user. This mode is configured by setting the |
| <strong>userPassword</strong> attribute to the name of a directory |
| attribute in the user's entry that contains the password.</p> |
| |
| <p>Comparison mode has some disadvantages. First, the |
| <strong>connectionName</strong> and |
| <strong>connectionPassword</strong> attributes must be configured to |
| allow the realm to read users' passwords in the directory. For |
| security reasons this is generally undesirable; indeed many directory |
| implementations will not allow even the directory manager to read |
| these passwords. In addition, the realm must handle password digests |
| itself, including variations in the algorithms used and ways of |
| representing password hashes in the directory. However, the realm may |
| sometimes need access to the stored password, for example to support |
| HTTP Digest Access Authentication (RFC 2069). (Note that HTTP digest |
| authentication is different from the storage of password digests in |
| the repository for user information as discussed above). |
| </p> |
| </li> |
| </ul> |
| |
| <h4>Assigning roles to the user</h4> |
| |
| <p>The directory realm supports two approaches to the representation |
| of roles in the directory:</p> |
| |
| <ul> |
| <li> |
| <p><b>Roles as explicit directory entries</b></p> |
| |
| <p>Roles may be represented by explicit directory entries. A role |
| entry is usually an LDAP group entry with one attribute |
| containing the name of the role and another whose values are the |
| distinguished names or usernames of the users in that role. The |
| following attributes configure a directory search to |
| find the names of roles associated with the authenticated user:</p> |
| |
| <ul> |
| <li><strong>roleBase</strong> - the base entry for the role search. |
| If not specified, the search base is the top-level directory |
| context.</li> |
| |
| <li><strong>roleSubtree</strong> - the search |
| scope. Set to <code>true</code> if you wish to search the entire |
| subtree rooted at the <code>roleBase</code> entry. The default |
| value of <code>false</code> requests a single-level search |
| including the top level only.</li> |
| |
| <li><strong>roleSearch</strong> - the LDAP search filter for |
| selecting role entries. It optionally includes pattern |
| replacements "{0}" for the distinguished name and/or "{1}" for the |
| username of the authenticated user.</li> |
| |
| <li><strong>roleName</strong> - the attribute in a role entry |
| containing the name of that role.</li> |
| |
| </ul> |
| |
| </li> |
| </ul> |
| |
| <ul> |
| <li> |
| <p><b>Roles as an attribute of the user entry</b></p> |
| |
| <p>Role names may also be held as the values of an attribute in the |
| user's directory entry. Use <strong>userRoleName</strong> to specify |
| the name of this attribute.</p> |
| |
| </li> |
| </ul> |
| <p>A combination of both approaches to role representation may be used.</p> |
| |
| <h3>Quick Start</h3> |
| |
| <p>To set up Tomcat to use JNDIRealm, you will need to follow these steps:</p> |
| <ol> |
| <li>Make sure your directory server is configured with a schema that matches |
| the requirements listed above.</li> |
| <li>If required, configure a username and password for use by Tomcat, that has |
| read only access to the information described above. (Tomcat will |
| never attempt to modify this information.)</li> |
| <li>Place a copy of the JNDI driver you will be using (typically |
| <code>ldap.jar</code> available with JNDI) inside the |
| <code>$CATALINA_HOME/server/lib</code> directory (if you do not need it |
| visible to web applications) or <code>$CATALINA_HOME/common/lib</code> |
| (if it will be used both by Tomcat 5 <em>and</em> by your apps).</li> |
| <li>Set up a <code><Realm></code> element, as described below, in your |
| <code>$CATALINA_HOME/conf/server.xml</code> file.</li> |
| <li>Restart Tomcat 5 if it is already running.</li> |
| </ol> |
| |
| <h3>Realm Element Attributes</h3> |
| |
| <p>To configure a JNDIRealm, you must create a <code><Realm></code> |
| element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file, |
| as described <a href="#Configuring a Realm">above</a>. The attributes supported |
| by this Realm are listed in the <a href="config/realm.html">Realm configuration |
| documentation</a>.</p> |
| |
| <h3>Example</h3> |
| |
| <p>Creation of the appropriate schema in your directory server is beyond the |
| scope of this document, because it is unique to each directory server |
| implementation. In the examples below, we will assume that you are using a |
| distribution of the OpenLDAP directory server (version 2.0.11 or later), which |
| can be downloaded from |
| <a href="http://www.openldap.org">http://www.openldap.org</a>. Assume that |
| your <code>slapd.conf</code> file contains the following settings |
| (among others):</p> |
| <source> |
| database ldbm |
| suffix dc="mycompany",dc="com" |
| rootdn "cn=Manager,dc=mycompany,dc=com" |
| rootpw secret |
| </source> |
| |
| <p>We will assume for <code>connectionURL</code> that the directory |
| server runs on the same machine as Tomcat. See <a |
| href="http://java.sun.com/products/jndi/docs.html">http://java.sun.com/products/jndi/docs.html</a> |
| for more information about configuring and using the JNDI LDAP |
| provider.</p> |
| |
| <p>Next, assume that this directory server has been populated with elements |
| as shown below (in LDIF format):</p> |
| |
| <source> |
| |
| # Define top-level entry |
| dn: dc=mycompany,dc=com |
| objectClass: dcObject |
| dc:mycompany |
| |
| # Define an entry to contain people |
| # searches for users are based on this entry |
| dn: ou=people,dc=mycompany,dc=com |
| objectClass: organizationalUnit |
| ou: people |
| |
| # Define a user entry for Janet Jones |
| dn: uid=jjones,ou=people,dc=mycompany,dc=com |
| objectClass: inetOrgPerson |
| uid: jjones |
| sn: jones |
| cn: janet jones |
| mail: j.jones@mycompany.com |
| userPassword: janet |
| |
| # Define a user entry for Fred Bloggs |
| dn: uid=fbloggs,ou=people,dc=mycompany,dc=com |
| objectClass: inetOrgPerson |
| uid: fbloggs |
| sn: bloggs |
| cn: fred bloggs |
| mail: f.bloggs@mycompany.com |
| userPassword: fred |
| |
| # Define an entry to contain LDAP groups |
| # searches for roles are based on this entry |
| dn: ou=groups,dc=mycompany,dc=com |
| objectClass: organizationalUnit |
| ou: groups |
| |
| # Define an entry for the "tomcat" role |
| dn: cn=tomcat,ou=groups,dc=mycompany,dc=com |
| objectClass: groupOfUniqueNames |
| cn: tomcat |
| uniqueMember: uid=jjones,ou=people,dc=mycompany,dc=com |
| uniqueMember: uid=fbloggs,ou=people,dc=mycompany,dc=com |
| |
| # Define an entry for the "role1" role |
| dn: cn=role1,ou=groups,dc=mycompany,dc=com |
| objectClass: groupOfUniqueNames |
| cn: role1 |
| uniqueMember: uid=fbloggs,ou=people,dc=mycompany,dc=com |
| </source> |
| |
| <p>An example <code>Realm</code> element for the OpenLDAP directory |
| server configured as described above might look like this, assuming |
| that users use their uid (e.g. jjones) to login to the |
| application and that an anonymous connection is sufficient to search |
| the directory and retrieve role information:</p> |
| |
| <source> |
| <Realm className="org.apache.catalina.realm.JNDIRealm" debug="99" |
| connectionURL="ldap://localhost:389" |
| userPattern="uid={0},ou=people,dc=mycompany,dc=com" |
| roleBase="ou=groups,dc=mycompany,dc=com" |
| roleName="cn" |
| roleSearch="(uniqueMember={0})" |
| /> |
| </source> |
| |
| <p>With this configuration, the realm will determine the user's |
| distinguished name by substituting the username into the |
| <code>userPattern</code>, authenticate by binding to the directory |
| with this DN and the password received from the user, and search the |
| directory to find the user's roles.</p> |
| |
| <p>Now suppose that users are expected to enter their email address |
| rather than their userid when logging in. In this case the realm must |
| search the directory for the user's entry. (A search is also necessary |
| when user entries are held in multiple subtrees corresponding perhaps |
| to different organizational units or company locations).</p> |
| |
| <p>Further, suppose that in addition to the group entries you want to |
| use an attribute of the user's entry to hold roles. Now the entry for |
| Janet Jones might read as follows:</p> |
| |
| <source> |
| dn: uid=jjones,ou=people,dc=mycompany,dc=com |
| objectClass: inetOrgPerson |
| uid: jjones |
| sn: jones |
| cn: janet jones |
| mail: j.jones@mycompany.com |
| memberOf: role2 |
| memberOf: role3 |
| userPassword: janet |
| </source> |
| |
| <p> This realm configuration would satisfy the new requirements:</p> |
| |
| <source> |
| <Realm className="org.apache.catalina.realm.JNDIRealm" debug="99" |
| connectionURL="ldap://localhost:389" |
| userBase="ou=people,dc=mycompany,dc=com" |
| userSearch="(mail={0})" |
| userRoleName="memberOf" |
| roleBase="ou=groups,dc=mycompany,dc=com" |
| roleName="cn" |
| roleSearch="(uniqueMember={0})" |
| /> |
| </source> |
| |
| <p>Now when Janet Jones logs in as "j.jones@mycompany.com", the realm |
| searches the directory for a unique entry with that value as its mail |
| attribute and attempts to bind to the directory as |
| <code>uid=jjones,ou=people,dc=mycompany,dc=com</code> with the given |
| password. If authentication succeeds, she is assigned three roles: |
| "role2" and "role3", the values of the "memberOf" attribute in her |
| directory entry, and "tomcat", the value of the "cn" attribute in the |
| only group entry of which she is a member.</p> |
| |
| <p>Finally, to authenticate the user by retrieving |
| the password from the directory and making a local comparison in the |
| realm, you might use a realm configuration like this:</p> |
| |
| <source> |
| <Realm className="org.apache.catalina.realm.JNDIRealm" debug="99" |
| connectionName="cn=Manager,dc=mycompany,dc=com" |
| connectionPassword="secret" |
| connectionURL="ldap://localhost:389" |
| userPassword="userPassword" |
| userPattern="uid={0},ou=people,dc=mycompany,dc=com" |
| roleBase="ou=groups,dc=mycompany,dc=com" |
| roleName="cn" |
| roleSearch="(uniqueMember={0})" |
| /> |
| </source> |
| |
| <p>However, as discussed above, the default bind mode for |
| authentication is usually to be preferred.</p> |
| |
| <h3>Additional Notes</h3> |
| |
| <p>JNDIRealm operates according to the following rules:</p> |
| <ul> |
| <li>When a user attempts to access a protected resource for the first time, |
| Tomcat 5 will call the <code>authenticate()</code> method of this |
| <code>Realm</code>. Thus, any changes you have made to the directory |
| (new users, changed passwords or roles, etc.) will be immediately |
| reflected.</li> |
| <li>Once a user has been authenticated, the user (and his or her associated |
| roles) are cached within Tomcat for the duration of the user's login. |
| (For FORM-based authentication, that means until the session times out or |
| is invalidated; for BASIC authentication, that means until the user |
| closes their browser). The cached user is <strong>not</strong> saved and |
| restored across sessions serialisations. Any changes to the directory |
| information for an already authenticated user will <strong>not</strong> be |
| reflected until the next time that user logs on again.</li> |
| <li>Administering the information in the directory server |
| is the responsibility of your own applications. Tomcat does not |
| provide any built-in capabilities to maintain users and roles.</li> |
| </ul> |
| |
| </subsection> |
| |
| |
| <subsection name="MemoryRealm"> |
| |
| <h3>Introduction</h3> |
| |
| <p><strong>MemoryRealm</strong> is a simple demonstration implementation of the |
| Tomcat 5 <code>Realm</code> interface. It is not designed for production use. |
| At startup time, MemoryRealm loads information about all users, and their |
| corresponding roles, from an XML document (by default, this document is loaded from <code>$CATALINA_HOME/conf/tomcat-users.xml</code>). Changes to the data |
| in this file are not recognized until Tomcat is restarted.</p> |
| |
| <h3>Realm Element Attributes</h3> |
| |
| <p>To configure a MemoryRealm, you must create a <code><Realm></code> |
| element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file, |
| as described <a href="#Configuring a Realm">above</a>. The attributes supported |
| by this Realm are listed in the <a href="config/realm.html">Realm configuration |
| documentation</a>.</p> |
| |
| <h3>User File Format</h3> |
| |
| <p>The users file (by default, <code>conf/tomcat-users.xml</code> must be an |
| XML document, with a root element <code><tomcat-users></code>. Nested |
| inside the root element will be a <code><user></code> element for each |
| valid user, consisting of the following attributes:</p> |
| <ul> |
| <li><strong>name</strong> - Username this user must log on with.</li> |
| <li><strong>password</strong> - Password this user must log on with (in |
| clear text if the <code>digest</code> attribute was not set on the |
| <code><Realm></code> element, or digested appropriately as |
| described <a href="#Digested Passwords">here</a> otherwise).</li> |
| <li><strong>roles</strong> - Comma-delimited list of the role names |
| associated with this user.</li> |
| </ul> |
| |
| <h3>Example</h3> |
| |
| <p>The default contents of the |
| <code>conf/tomcat-users.xml</code> file is:</p> |
| <source> |
| <tomcat-users> |
| <user name="tomcat" password="tomcat" roles="tomcat" /> |
| <user name="role1" password="tomcat" roles="role1" /> |
| <user name="both" password="tomcat" roles="tomcat,role1" /> |
| </tomcat-users> |
| </source> |
| |
| <h3>Additional Notes</h3> |
| |
| <p>MemoryRealm operates according to the following rules:</p> |
| <ul> |
| <li>When Tomcat first starts up, it loads all defined users and their |
| associated information from the users file. Changes to the data in |
| this file will <strong>not</strong> be recognized until Tomcat is |
| restarted.</li> |
| <li>When a user attempts to access a protected resource for the first time, |
| Tomcat 5 will call the <code>authenticate()</code> method of this |
| <code>Realm</code>.</li> |
| <li>Once a user has been authenticated, the user (and his or her associated |
| roles) are cached within Tomcat for the duration of the user's login. |
| (For FORM-based authentication, that means until the session times out or |
| is invalidated; for BASIC authentication, that means until the user |
| closes their browser). The cached user is <strong>not</strong> saved and |
| restored across sessions serialisations.</li> |
| <li>Administering the information in the users file is the responsibility |
| of your application. Tomcat does not |
| provide any built-in capabilities to maintain users and roles.</li> |
| </ul> |
| |
| </subsection> |
| |
| |
| <subsection name="UserDatabaseRealm"> |
| |
| <h3>Introduction</h3> |
| |
| <p><strong>UserDatabaseRealm</strong> is an implementation of the |
| Tomcat <code>Realm</code> interface. Information about all users, and their |
| corresponding roles, is obtained from a JNDI resource that implements the |
| <code>UserDatabase</code> interface.</p> |
| |
| <h3>Realm Element Attributes</h3> |
| |
| <p>To configure a UserDatabaseRealm, you must create a <code><Realm></code> |
| element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file, |
| as described <a href="#Configuring a Realm">above</a>. The attributes supported |
| by this Realm are listed in the <a href="config/realm.html">Realm configuration |
| documentation</a>.</p> |
| |
| <h3>Example</h3> |
| |
| <p>The default installation of Tomcat 5 is configured with a |
| UserDatabaseRealm nested inside the <code><Engine></code> element, so that |
| it applies to all virtual hosts and web applications. This realm uses the |
| same <code>tomcat-users.xml</code> as the MemoryRealm.</p> |
| |
| </subsection> |
| |
| |
| <subsection name="JAASRealm"> |
| |
| <h3>Introduction</h3> |
| |
| <p><strong>JAASRealm</strong> is an implementation of the Tomcat |
| 4 <code>Realm</code> interface that authenticates users through the Java |
| Authentication & Authorization Service (JAAS) framework, a Java |
| package that is available as an optional package in Java 2 SDK 1.3 and |
| is fully integrated as of SDK 1.4 .</p> |
| <p>Using JAASRealm gives the developer the ability to combine |
| practically any conceivable security realm with Tomcat's CMA. </p> |
| <p>JAASRealm is prototype for Tomcat of the proposed JAAS-based |
| J2EE authentication framework for J2EE v1.4, based on the <a |
| href="http://www.jcp.org/en/jsr/detail?id=196">JCP Specification |
| Request 196</a> to enhance container-managed security and promote |
| 'pluggable' authentication mechanisms whose implementations would be |
| container-independent. |
| </p> |
| <p>Based on the JAAS login module and principal (see <code>javax.security.auth.spi.LoginModule</code> |
| and <code>javax.security.Principal</code>), you can develop your own |
| security mechanism or wrap another third-party mechanism for |
| integration with the CMA as implemented by Tomcat. |
| </p> |
| |
| <h3>Quick Start</h3> |
| <p>To set up Tomcat to use JAASRealm with your own JAAS login module, |
| you will need to follow these steps:</p> |
| <ol> |
| <li>Write your own LoginModule, User and Role classes based |
| on JAAS (see |
| <a href="http://java.sun.com/j2se/1.4.1/docs/guide/security/jaas/tutorials/GeneralAcnOnly.html">the |
| JAAS Authentication Tutorial</a> and |
| <a href="http://java.sun.com/j2se/1.4.1/docs/guide/security/jaas/JAASLMDevGuide.html">the JAAS Login Module |
| Developer's Guide</a>) to be managed by the JAAS Login |
| Context (<code>javax.security.auth.login.LoginContext</code>) |
| When developing your LoginModule, note that JAASRealm's built-in <code>CallbackHandler</code> |
| +only recognizes the <code>NameCallback</code> and <code>PasswordCallback</code> at present. |
| </li> |
| <li>Although not specified in JAAS, you should create |
| seperate classes to distinguish between users and roles, extending <code>javax.security.Principal</code>, |
| so that Tomcat can tell which Principals returned from your login |
| module are users and which are roles (see <code>org.apache.catalina.realm.JAASRealm</code>). |
| Regardless, the first Principal returned is <em>always</em> treated as the user Principal. |
| </li> |
| <li>Place the compiled classes on Tomcat's classpath |
| </li> |
| <li>Set up a login.config file for Java (see <a |
| href="http://java.sun.com/j2se/1.4.1/docs/guide/security/jaas/tutorials/LoginConfigFile.html">JAAS |
| LoginConfig file</a>) and tell Tomcat where to find it by specifying |
| its location to the JVM, for instance by setting the environment |
| variable: <code>JAVA_OPTS=-DJAVA_OPTS=-Djava.security.auth.login.config==$CATALINA_HOME/conf/jaas.config</code></li> |
| |
| <li>Configure your security-constraints in your web.xml for |
| the resources you want to protect</li> |
| <li>Configure the JAASRealm module in your server.xml </li> |
| <li>Restart Tomcat 5 if it is already running.</li> |
| </ol> |
| |
| |
| <h3>Realm Element Attributes</h3> |
| |
| <p>To configure a JAASRealm, you must create a <code><Realm></code> |
| element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file, |
| as described <a href="#Configuring a Realm">above</a>. The attributes supported |
| by this Realm are listed in the <a href="config/realm.html">Realm configuration |
| documentation</a>.</p> |
| |
| <h3>Example</h3> |
| |
| <p>Here is an example of how your server.xml snippet should look.</p> |
| |
| <source> |
| <Realm className="org.apache.catalina.realm.JAASRealm" |
| appName="MyFooRealm" |
| userClassNames="org.foobar.realm.FooUser" |
| roleClassNames="org.foobar.realm.FooRole" |
| debug="99"/> |
| </source> |
| |
| <p>It is the responsibility of your login module to create and save User and |
| Role objects representing Principals for the user |
| (<code>javax.security.auth.Subject</code>). If your login module doesn't |
| create a user object but also doesn't throw a login exception, then the |
| Tomcat CMA will break and you will be left at the |
| http://localhost:8080/myapp/j_security_check URI or at some other |
| unspecified location.</p> |
| |
| <p>The flexibility of the JAAS approach is two-fold: </p> |
| <ul> |
| <li>you can carry out whatever processing you require behind |
| the scenes in your own login module.</li> |
| <li>you can plug in a completely different LoginModule by changing the configuration |
| and restarting the server, without any code changes to your application.</li> |
| </ul> |
| |
| <h3>Additional Notes</h3> |
| <ul> |
| <li>When a user attempts to access a protected resource for |
| the first time, Tomcat 5 will call the <code>authenticate()</code> |
| method of this <code>Realm</code>. Thus, any changes you have made in |
| the security mechanism directly (new users, changed passwords or |
| roles, etc.) will be immediately reflected.</li> |
| <li>Once a user has been authenticated, the user (and his or |
| her associated roles) are cached within Tomcat for the duration of |
| the user's login. For FORM-based authentication, that means until |
| the session times out or is invalidated; for BASIC authentication, |
| that means until the user closes their browser. Any changes to the |
| security information for an already authenticated user will <strong>not</strong> |
| be reflected until the next time that user logs on again.</li> |
| <li>As with other <code>Realm</code> implementations, digested passwords |
| are supported if the <code><Realm></code> element in <code>server.xml</code> |
| contains a <code>digest</code> attribute; JAASRealm's <code>CallbackHandler</code> |
| will digest the password prior to passing it back to the <code>LoginModule</code></li> |
| </ul> |
| |
| </subsection> |
| |
| |
| </section> |
| |
| </body> |
| |
| </document> |