Tomcat tomcat-users.xml configuration example

This article describes the configuration of the tomcat-users.xml file forApache Tomcat 7 web server. tomcat-users.xml is the default user database for container-managed authentication in Tomcat.

1. Web Application Security Concepts

1.1. Authentication

To access a restricted resource on the server, Tomcat challenges a user to produce user details to confirm that they are who they say they are.

1.2. Authorization

Once a user is authenticated, the server determines whether this user is authorized to access the restricted resource requested.

1.3. Realm

A realm is a repository of user information; it is an abstraction of the data store – text file, JDBC database or a JNDI resource. This
has the following information: username, password and the roles which are assigned to the users.

Both of the authentication and authorization make up the security policy of a server. Tomcat uses realms to implement container-managed security and enforce specific security policies.

1.4. Container Managed Security

Container managed security provides enforcing and implementing security policies on the web server.

• Also known as declarative security (for authentication and authorization)
• Defined in Java Servlet specification
• Relieves the programmer to write security related code (though they can if they want to)
• Provides consistency over multiple applications

2. tomcat-users.xml

Tomcat configuration files are found in the directory: CATALINA_HOME/conf (where CATALINA_HOME environment variable is the Tomcat installation directory). The main configuration file is server.xml. tomcat-users.xml is one of the configuration files.

An example of the tomcat-users.xml file is shown below:

1	<?xml version='1.0' encoding='utf-8'?>

2	<tomcat-users>

3	<role rolename="tomcat"/>

4	<role rolename="role1"/>

5	<user username="tomcat" password="tomcat" roles="tomcat"/>

6	<user username="both" password="tomcat" roles="tomcat,role1"/>

7	<user username="role1" password="tomcat" roles="role1"/>

8	</tomcat-users>

<tomcat-users>: This is the root element. This has two nested elements: role and user.

<role>: Each role that a user can play is defined with a <role> element. The attribute rolename specifies the name.
<user>: Each user has a <user> entry. This has three required attributes: username, password and roles. Note that a user can have more than one role.

• username – Username this user must log on with.
• password – Password this user must log on with (in clear text).
• roles – Comma-delimited list of the role names associated with this user.

NOTE: For a newly installed Tomcat 7 web server, the role and user entries were commented in the tomcat-users.xml.

3. Realms

Configure Tomcat to support container managed security by connecting to an existing 「database」 of usernames, passwords, and user roles. This is required in case of using a web application that includes one or more <security-constraint>elements, and a <login-config> element defining how users are required to authenticate themselves.

Servlet Specification describes a portable mechanism for applications to declare their security requirements (in the web.xmldeployment descriptor). There is no portable API defining the interface between a servlet container and the associated user and role information.

To 「connect」 a servlet container to some existing authentication database or mechanism that already exists in the production environment – 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,DataSourceRealm, JNDIRealm, UserDatabaseRealm, MemoryRealm and JAASRealm.

UserDatabaseRealm and MemoryRealm access or refer to the tomcat-users.xml file.

3.1. MemoryRealm

Accesses authentication information stored in an in-memory object collection, which is initialized from an XML document (tomcat-users.xml).

MemoryRealm is a simple demonstration implementation of the Tomcat Realm interface; it is not designed for production use. At start-up time, MemoryRealm loads information about all users, and their corresponding roles, from an XML document (by default, this document is loaded from $CATALINA_BASE/conf/tomcat-users.xml). Changes to the data in this file are not recognized until Tomcat is restarted.

To configure MemoryRealm, create a <Realm> element and nest it in $CATALINA_BASE/conf/server.xml file. The <Realm>element can be nested inside any one of the following Container elements: Engine (this realm will be shared across all web applications on all virtual hosts), Host (this realm will be shared across all web applications for this virtual host), or Context(this realm will be used only for this web application).

1	<Realm className="org.apache.catalina.realm.MemoryRealm" />

• className attribute: This is a required attribute. This is the Java class name of the implementation to use. This class must implement the org.apache.catalina.Realm interface.
• pathname attribute: If no path-name is specified, the default value is CATALINA_HOME/conf/tomcat-users.xml. Absolute or relative (to $CATALINA_BASE) path-name to the XML file containing our user information.

NOTE: The CATALINA_BASE environment variable specifies location of the root directory of the 「active configuration」 of Tomcat. It is optional to define this variable. It defaults to be equal to CATALINA_HOME.

3.2. UserDatabaseRealm

Accesses authentication information stored in an UserDatabase JNDI resource, which is typically backed by an XML document (tomcat-users.xml).

UserDatabaseRealm is an implementation of the Tomcat Realm interface that uses a JNDI resource to store user information. By default, the JNDI resource is backed by an XML file. It is not designed for large-scale production use. At start-up time, the UserDatabaseRealm loads information about all users, and their corresponding roles, from an XML document (by default, this document is loaded from $CATALINA_BASE/conf/tomcat-users.xml). The users, their passwords and their roles may all be editing dynamically; Tomcat provides MBeans that may be accessed via JMX for this purpose. Changes may be saved and will be reflected in the XML file.

To configure UserDatabaseRealm, create a <Realm> element and nest it in your $CATALINA_BASE/conf/server.xml file.

1	<Realm className="org.apache.catalina.realm.UserDatabaseRealm" resourceName="UserDatabase"/>

resourceName attribute: The name of the global UserDatabase resource that this realm will use for user, password and role information. This attribute value is also defined as follows in server.xml:

1	<Resource name="UserDatabase" auth="Container"

2	type="org.apache.catalina.UserDatabase"

3	description="User database that can be updated and saved"

4	factory="org.apache.catalina.users.MemoryUserDatabaseFactory"

5	pathname="conf/tomcat-users.xml">

6	</Resource>

NOTE: The name and location of the tomcat-users.xml file can be changed.

4. The Manager Application

Tomcat manager application is provided as part of the Tomcat distribution and is stored in theCATALINA_HOME/webapps/manager directory by default. It’s a special web application that allows manage other web applications while the Tomcat server is running. One can, for example, deploy, undeploy, start, and stop web applications on the server using this tool.

By default, access to the manager application is disabled; this can be accessed only by an authenticated user. The default realm for the manager application is tomcat-users.xml.

To set up the manager application, add a user with the manager role to this file. The role manager names can be found in the web.xml file of the Manager web application. One of the available roles is manager-gui – provides access to the HTML interface. For example, add the manager role and then alter an existing user (such as tomcat), as follows:

1	<role rolename="manager-gui"/>

2	<user username="tomcat" password="tomcat" roles="tomcat, manager-gui"/>

Access the manager application by one of the ways:

• http://localhost:8080/ and click the 「Manager App」 button
• http://localhost:8080/manager/html

This will prompt for the user name and password. Enter the values from the tomcat-users.xml.