Tomcat tomcat-users.xml configuration example
This article describes the configuration of the
tomcat-users.xml file for Apache Tomcat 7 web server.
tomcat-users.xml is the default user database for container-managed authentication in Tomcat.
1. Web Application Security Concepts
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.
Once a user is authenticated, the server determines whether this user is authorized to access the restricted resource requested.
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
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
tomcat-users.xml is one of the configuration files.
An example of the
tomcat-users.xml file is shown below:
<?xml version='1.0' encoding='utf-8'?> <tomcat-users> <role rolename="tomcat"/> <role rolename="role1"/> <user username="tomcat" password="tomcat" roles="tomcat"/> <user username="both" password="tomcat" roles="tomcat,role1"/> <user username="role1" password="tomcat" roles="role1"/> </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:
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
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.xml deployment 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:
MemoryRealm access or refer to the
Accesses authentication information stored in an in-memory object collection, which is initialized from an XML document (
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.
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).
<Realm className="org.apache.catalina.realm.MemoryRealm" />
classNameattribute: This is a required attribute. This is the Java class name of the implementation to use. This class must implement the
pathnameattribute: 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.
Accesses authentication information stored in an
UserDatabase JNDI resource, which is typically backed by an XML document (
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.
UserDatabaseRealm, create a
<Realm> element and nest it in your
<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
<Resource name="UserDatabase" auth="Container" type="org.apache.catalina.UserDatabase" description="User database that can be updated and saved" factory="org.apache.catalina.users.MemoryUserDatabaseFactory" pathname="conf/tomcat-users.xml"> </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 the
CATALINA_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
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:
<role rolename="manager-gui"/> <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
This will prompt for the user name and password. Enter the values from the