Web single sign-on and access control software security solutions HOME  |   |  BUY  |  CONTACT US 
secure your web

Tomcat Security Overview and Analysis

This document presents an overview of the security features provided with the Apache Jakarta Tomcat servlet container, including suggestions on best practices. Then, an analysis is provided to show how the Cafésoft Access Management System (Cams™) can be integrated with Tomcat to provide enhanced enterprise-wide security that overcomes deficiencies inherent in the servlet and J2EE security model.


Tomcat implements security as specified in the Java servlet specification. This document primarily addresses Tomcat 4.x security, which is compliant with the 2.3 servlet specification. Some information is also provided regarding the forthcoming Tomcat 5.x release, which implements the servlet 2.4 specification. Also, there is some overlap between security requirements defined in the servlet and J2EE specifications. In general, the J2EE specification includes all servlet specification requirements and makes some optional requirements mandatory for a web container to be "J2EE compliant". Tomcat implements most optional servlet specification features but, as an open source project, has not been able to pass the J2EE compliance tests due to J2EE licensing policy (recent changes by Sun may allow this in the near future).

Tomcat Security Scope

As stated in the servlet specification, Tomcat security is primarily concerned with:

  • Authentication - The means by which communicating entities prove their identities to one another.
  • Access control - The means by which requests for resources are limited to users or programs.
  • Integrity - The means used to prove that information has not been modified while in transit.
  • Confidentiality - The means used to ensure that information is understandable only by authorized users.

As defined in the servlet specification, Tomcat security is user role-based and web container (somewhat web application) centric. Hence, Tomcat security scope, by definition in the servlet specification, does not address issues of security integration with other web and application servers.

Declarative and Programmatic Security

The servlet specification classifies Tomcat security into two broad categories:

  • Declarative security is the expression of application security external to the application and is preferred when sufficient as it allows runtime configuration of application security without recoding the application.
  • Programmatic security is used to implement fine-grained access control, enabling application components to become security aware.

It may be easier to think in terms of security you configure in the web application environment (declarative) and security you define within the web application code (programmatic). Each web application configures declarative security in its unique deployment descriptor, web.xml. This is a required XML-formatted configuration file (also called the deployment descriptor) found in each web application's WEB-INF directory. Programmatic security involves using HttpServletRequest API method calls to make business logic decisions within the web application context. For example, you may want to make combo box values dynamic based on a user's identity. The servlet API calls you use are:

  • getRemoteUser - Returns the user name the client used for authentication.
  • isUserInRole - Determines if a remote user is in a specified security role.
  • getUserPrincipal - Returns a java.security.Principal object, which contains the principals name and roles.

Tomcat uses role-based authorization to manage access. With this model, access permissions are granted to an abstract entity called a security role, and access is allowed only to users or groups of users who have that role. For example, the Tomcat distribution includes two administrative web applications that only grant access to users with the "manager" role. The deployment descriptor specifies the type of access granted to each role, but does not specify the role to user or group mappings. That's done in the user repository, which is typically a relational database or LDAP server in production environments, but is another XML-formatted file named tomcat-users.xml by default.

<!-- Define a security constraint on this application -->
    <web-resource-name>Entire Application</web-resource-name>
    <!-- This role is not in the default user directory -->
<!-- Define the login configuration for this application -->
  <realm-name>Tomcat Manager Application</realm-name>
<!-- Security roles referenced by this web application -->
    The role that is required to log in to the Manager Application

Figure 1 - Security snippet from Tomcat Manager's web.xml deployment descriptor

Figure 1.0 shows a security snippet from the Tomcat Manager web application's web.xml file. The security contraint element defines the URL pattern to match for the constraint to apply (in this example the entire web application) and an authentication constraint, which will force the user to authenticate. Access is granted only if an authenticated user has the "manager" role. The login config element defines the type of authentication (more on this next), in this case HTTP basic. And, the roles referenced by the web application.


By default, you do not need to authenticate to access Tomcat resources. Authentication is needed only when specified in the deployment descriptor with the auth-constrain element. You use a web client (typically a web browser) to authenticate with Tomcat using one of the following mechanisms:

HTTP Basic Authentication

When your browser prompts you for a username and password in a dialog box, you are using HTTP basic authentication to logon to a web server. This is also know as browser-based authentication because the web server requests the browser to authenticate you through the HTTP 1.0 protocol. In the dialog box, you also see the name of a realm to which you will be authenticated. The realm does not necessarily reflect a security policy domain, which is also referred to as a realm. Think of an HTTP basic authentication realm as a "database" of usernames and passwords that identify valid users of a web application (or set of web applications), plus a list of the roles associated with each valid user.

Once you enter your username and password, they are base64 encoded and sent by the browser to Tomcat (for both secure and non-secure resources). Tomcat authenticates you, and then reauthenticates each subsequent request against the specified realm. You cannot logout as your username and password remain in browser memory until you exit. Hence, you must exit the browser to "logout".

Because the username and password are not encrypted, and the target server's identity is not authenticated by the browser, basic authentication alone is not secure. You can improve security by using a secure transport mechanism such as HTTPS, or security at the network level such as a VPN. However, if you switch to HTTP (after authenticating with basic authentication and HTTPS), your browser continues to send your username and password with each subsequent request in cleartext until you exit.

HTTP Digest Authentication

HTTP digest authentication is also performed by the browser upon request by the web server and based on a username, password, and realm. However, in this case your password is digested with the secure MD5 algorithm before it is sent by the browser.

You can specify in Tomcat's <realm> element a digest attribute, which must be one of the digest algorithms supported by the java.security.MessageDigest class (SHA, MD2, or MD5). When you select this option, the contents of the password that is stored in the realm must be the digest version of the password. The client must also digest the password using the same algorithm before it is sent. When the realm authenticate() method is called, the password you input is compared with the value returned by the realm and, if equal, you are authenticated.

Because your password is digested, HTTP digest authentication is more secure than basic. However, it does suffer from the same security issues as basic authentication. As it is not supported by popular browsers, HTTP digest authentication is not required by the servlet specification, but it is implemented by Tomcat. As with basic authentication, your credentials are stored in the browser's memory until it is exited.

Form Based Authentication

This is the most popular web authentication mechanism in use. It provides the application developer with the greatest control over the look and feel of the “login screen”, enables closing of user sessions without exiting the browser, and is more secure than basic authentication.

The web application deployment descriptor contains elements to specify a "login form" and an "error page". The HTML login form must contain fields for entering a username and a password, which must be named "j_username" and "j_password", respectively. When you attempt to access a protected resource, Tomcat checks if you are authenticated. If not, the following steps occur:

  1. Tomcat saves the entire HTTP request, then redirects the browser to the configured login form.
  2. You enter your username and password in the login form's "j_username" and "j_password" fields.
  3. The browser posts the form back to the server using the "j_security_check" action.
  4. The container attempts to authenticate the user using the configured security realm.
  5. If authentication fails, the error page is returned with the status code of the response set to 401.
  6. If authentication succeeds, the principal is checked to determine if you have a role authorized to access the resource.
  7. If you are authorized, Tomcat processes the original HTTP request. If authentication fails, or you are not authorized to access the requested resource, the configured error page is returned.

Because your username and password are not encrypted and the target server is not authenticated, form-based authentication using HTTP is not secure. If you are using form-based authentication, you should use a secure transport mechanism such as HTTPS, or security at the network level such as a VPN. However, form-based authentication is more secure than basic authentication when switching back and forth between HTTPS and HTTP as your username and password are not sent with each request.

Another advantage of form-based over basic authentication is that the application can programmatically close your authenticated session, enabling you to logout without restarting your browser. In this respect, calling the HttpSession.invalidate method seems like it should work, but it does not because HTTP sessions are totally independent of authentication (e.g., you can have an HTTP session without authenticating and authenticate without having an HTTP session).

HTTPS Client Authentication

Authentication using HTTPS (HTTP over SSL) enables browsers and web servers to communicate over an encrypted connection. This is a two-way process, meaning that both the server and the browser encrypt all traffic before sending out data. Tomcat uses HTTPS for confidentiality (by encrypting the data) and integrity (which is insured if the message can be decrypted).

Another important aspect of the SSL protocol is authentication. This means that during your initial attempt to communicate with a web server over a secure connection, that server will present your web browser with a set of credentials, in the form of a certificate chain, as proof the site is who and what it claims to be. Though Tomcat supports HTTPS connections and server authentication, it is generally recommended that you off-load SSL connections to a web server like Apache or IIS and use Tomcat as a plugin to process the servlet and JSP requests.

The server may also request a client certificate from your browser, asking for proof that you are who you claim to be. This practice is used more for business-to-business transactions than with individual internet users because of the overhead required to manage certificates. Most SSL-enabled web servers do not request client authentication but if you need it, Tomcat does support it.

Web Application Single Sign-on

As the underlying principals to which roles are mapped are environment specific rather than web application specific, it is desirable to:

  1. Make login mechanisms and policies a property of the web application environment.
  2. Use the same authentication information to represent a principal to all applications in the same container, and
  3. Require re-authentication of users only when a security policy domain boundary has been crossed.

Therefore, a J2EE compliant servlet container is required to track authentication information at the container level (rather than at the web application level). Tomcat enables users authenticated for one web application to access other web applications managed by the same container. However, login configurations must still be specified for each web application, which, depending upon the number of web applications can be difficult to manage (Tomcat also allows each web application to define its own realm). Additionally, Tomcat single sign-on does not address multiple Tomcat servers, other web servers such as Apache, or an application server like JBoss.

Specifying Security Constraints

Deployment descriptor <security-constraint> elements define the permissions and rules for the protected Tomcat resources and include the following XML elements:

  • web-resource-collection - A set of URL patterns and HTTP methods that describe a set of resources to be protected. All requests that contain a URL pattern matched in a web resource collection are subject to the constraint.
  • auth-constraint - A set of security roles (one or more) to which a user must belong to be granted access to resources matched by the web resource collection.
  • user-data-constraint - Describes integrity and confidentiality requirements for the transport layer of the client server.

Hence, the web resource collection defines the resources, the authorization constraint defines the roles to which a user can belong to access the resources, and the data constraints defines if HTTPS should be required.

Enhancing Tomcat Security with Cams

When you arrive at the boundary of Tomcat security, you'll discover that it is generally limited by the scope of the servlet specification and J2EE security. Consequently, Tomcat will not meet the security needs of most heterogenous, multi-server environments. The good news is that you have the Tomcat source and can write security code and implement security in servlets to customize Tomcat. The bad news is that you probably don't have the time, budget, expertise, or even desire to write security code. In addition, embedding low-level security code within applications is considered to be bad practice.

The Cafésoft Access Management System is designed to pickup where Tomcat security stops. Cams flexibly meets the needs of the enterprise by providing a complete web access managment system which spans servers and tiers in a web farm. Cams provides the same security features Tomcat does and more.

From a high-level, you should consider using Cams with Tomcat when you have any of the following needs:

  • You have a web server farm with more than one stand-alone Tomcat server
  • You are using Apache and Tomcat servers and desire integrated security
  • You need centralized security configuration, logging, and events
  • You need a flexible, easy-to-extend security system

Cams offers many unique features that might more closely adhear to your security needs. The following tables show a feature by feature comparison of Tomcat security with and without Cams.


Feature Tomcat Security with Cams Tomcat Security
Form-based authentication Yes, can use the JAAS API to create a new login modules, which plug into Cams via XML configuration files.(user account, pin, social security number, etc.). Source code is provided for included login modules, along with a Cams JAAS Login Module and Cams JAAS Callback Handers documents in the programmer's guide. Yes, username and password only
Custom form-based authentication Yes, use the JAAS API to create a new login modules, which plug into Cams via XML configuration files. Source code is provided for included login modules, along with a Cams JAAS Login Module and Cams JAAS Callback Handers documents in the programmer's guide. No
LDAP user repository Yes Yes
SQL user repository Yes Yes
XML user repository Yes Yes
Custom user repository Yes, use the JAAS API to create a new login modules, which plug into Cams via XML configuration files. Source code is provided for included login modules, along with a Cams JAAS Login Module programmer's guide. No
Single Sign-on to multiple web applications Yes Yes
Single Sign-on to multiple Tomcat servers Yes, Cams provides Single Sign-on across multiple server resources (Tomcat, Apache, and custom) in the same Internet domain. No
Single Sign-on to multiple Tomcat and Apache servers Yes, Cams provides Single Sign-on across multiple server resources (Tomcat, Apache, and custom) in the same Internet domain. No
Single Sign-on to Tomcat from within a Java application Yes, you can use Cams to secure a Java Swing application from the same security policy as you use for Tomcat web applications. If the Swing application uses an HTML browser bean to access web resource, you can then have Single Sign-on within the context of the Java Swing application to Java application resources and web resources. No
Configurable authentication Yes, configure authentication to check multiple repositories using security domains specific Cams login modules with REQUIRED, REQUISITE, SUFFICIENT, OPTIONAL flags to determine overall result. No
Proactive authentication Yes, with Cams you can access the login form directly and authenticate the user before requesting a protected resource. No, only lazy authentication is available.

Access Control

Feature Tomcat Security with Cams Tomcat Security
Users, groups, role-based Yes Yes
Host and IP address Yes, you can use the hostname or IP address to control access to a resource. No
Date/time Yes No
Combine rules with boolean logic Yes, with Cams you can use existing rules and combine them using the Boolean operators AND, OR, and NOT. For example, you can allow access to role "manager" from an internal IP address "192.168.0". No
Deny lists Yes, you can easily use the Boolean NOT condition to create deny lists for users, groups, roles, hostnames, IP addresses, etc. No
Custom rules

Yes, suppose you want to control access to a resource on something other than username and password, like a bank account balance or a membership type. Cams allows you to centrally deploy new rules that are immediately available to all protected servers.

J2EE servlet API programatic security Yes Yes
End to end security Yes, Cams includes support for the Apache web server and Java agent API to enable custom agents to be written. No


Feature Tomcat Security with Cams Tomcat Security
Centralized security policy Yes, with Cams, you create and deploy security rules once at the Cams server. Cams eliminates or minimizes the amount of security code that needs to be written for each web application, thereby reducing development costs, improving security, and improving time-to-market. No, security policy is configured for each web application in web.xml
Security event notification Yes, Cams provides mechanisms to enable custom security event notification. For example, you may want to track a specific user or groups of users. With Cams, you could be notified via email or log a record to a database each time the target users login. No


Feature Tomcat Security with Cams Tomcat Security
Centralized Logging Yes, with Cams all security events are logged to a central location. Using Tomcat, logging is usually on a webapp by webapp basis, with security events mixed in the logs with other events. It is much easier and more meaningful to do security event log analysis with Cams. No
Log failed authentications Yes, both successful and unsuccessful authentications are log in a centralized security domain files. No, only successful authentication is logged.


Feature Tomcat Security with Cams Tomcat Security
Shared session state across servers Yes, though Tomcat continues to create a session for each web application that cannot be shared, each Cams user session is stored within the Cams server. All Cams enabled servers in the same security and Internet domain have access through HTTP request headers to session data from any CGI and Tomcat programming environments. No

Cams gives you all the security features Tomcat does, and a whole lot more. Find out more about Cams by reading the Cams Overview and the Access Management white paper. We recommend that you also take the Cams Tour to interactively learn about Cams and web security in general.