setting up container managed security using the UserDatabase Realm component and the JNDI resources how-to for more information on how to configure a UserDatabase resource.

Memory Based Realm - org.apache.catalina.realm.MemoryRealm

The Memory Based Realm is a simple Realm implementation that reads user information from an XML format, and represents it as a collection of Java objects in memory. This implementation is intended solely to get up and running with container managed security - it is NOT intended for production use. As such, there are no mechanisms for updating the in-memory collection of users when the content of the underlying data file is changed.

The Memory Based Realm implementation supports the following additional attributes:

AttributeDescription
allRolesMode

This attribute controls how the special role name * is handled when processing authorization constraints in web.xml. By default, the specification compliant value of strict is used which means that the user must be assigned one of the roles defined in web.xml. The alternative values are authOnly which means that the user must be authenticated but no check is made for assigned roles and strictAuthOnly which means that the user must be authenticated and no check will be made for assigned roles unless roles are defined in web.xml in which case the user must be assigned at least one of those roles.

digest

The digest algorithm used to store passwords in non-plaintext formats. Valid values are those accepted for the algorithm name by the java.security.MessageDigest class. If not specified, passwords are stored in clear text.

pathname

URL, absolute path or relative path (to $CATALINA_BASE) for the XML file containing our user information. See below for details on the XML element format required. If no pathname is specified, the default value is conf/tomcat-users.xml.

stripRealmForGss

When processing users authenticated via the GSS-API, this attribute controls if any "@..." is removed from the end of the user name. If not specified, the default is true.

transportGuaranteeRedirectStatus

The HTTP status code to use when the container needs to issue an HTTP redirect to meet the requirements of a configured transport guarantee. The provided status code is not validated. If not specified, the default value of 302 is used.

X509UsernameRetrieverClassName

When using X509 client certificates, this specifies the class name that will be used to retrieve the user name from the certificate. The class must implement the org.apache.catalina.realm.X509UsernameRetriever interface. The default is to use the certificate's SubjectDN as the username.

The XML document referenced by the pathname attribute must conform to the following requirements:

  • The root (outer) element must be <tomcat-users>.
  • Each authorized user must be represented by a single XML element <user>, nested inside the root element.
  • Each <user> element must have the following attributes:
    • username - Username of this user (must be unique within this file).
      For compatibility, it is allowed to use name as an alternative name for this attribute.
    • password - Password of this user (in clear text).
    • roles - Comma-delimited list of the role names assigned to this user.

See the Container-Managed Security Guide for more information on setting up container managed security using the Memory Based Realm component.

JAAS Realm - org.apache.catalina.realm.JAASRealm

JAASRealm is an implementation of the Tomcat Realm interface that authenticates users through the Java Authentication & Authorization Service (JAAS) framework which is now provided as part of the standard J2SE API.

Using JAASRealm gives the developer the ability to combine practically any conceivable security realm with Tomcat's CMA.

JAASRealm is prototype for Tomcat of the JAAS-based J2EE authentication framework for J2EE v1.4, based on the JCP Specification Request 196 to enhance container-managed security and promote 'pluggable' authentication mechanisms whose implementations would be container-independent.

Based on the JAAS login module and principal (see javax.security.auth.spi.LoginModule and javax.security.Principal), you can develop your own security mechanism or wrap another third-party mechanism for integration with the CMA as implemented by Tomcat.

The JAAS Realm implementation supports the following additional attributes:

AttributeDescription
allRolesMode

This attribute controls how the special role name * is handled when processing authorization constraints in web.xml. By default, the specification compliant value of strict is used which means that the user must be assigned one of the roles defined in web.xml. The alternative values are authOnly which means that the user must be authenticated but no check is made for assigned roles and strictAuthOnly which means that the user must be authenticated and no check will be made for assigned roles unless roles are defined in web.xml in which case the user must be assigned at least one of those roles.

appName

The name of the application as configured in your login configuration file (JAAS LoginConfig).

If not specified appName is derived from the Container's name it is placed in, for example Catalina or ROOT. If the realm is not placed in any Container, the default is Tomcat.

userClassNames

A comma-separated list of the names of the classes that you have made for your user Principals.

configFile

The name of a JAAS configuration file to use with this Realm. It will be searched for using ClassLoader#getResource(String) so it is possible for the configuration to be bundled within a web application. If not specified, the default JVM global JAAS configuration will be used.

roleClassNames

A comma-separated list of the names of the classes that you have made for your role Principals.

stripRealmForGss

When processing users authenticated via the GSS-API, this attribute controls if any "@..." is removed from the end of the user name. If not specified, the default is true.

transportGuaranteeRedirectStatus

The HTTP status code to use when the container needs to issue an HTTP redirect to meet the requirements of a configured transport guarantee. The provided status code is not validated. If not specified, the default value of 302 is used.

useContextClassLoader

Instructs JAASRealm to use the context class loader for loading the user-specified LoginModule class and associated Principal classes. The default value is true, which is backwards-compatible with the way Tomcat 5 works. To load classes using the container's classloader, specify false.

X509UsernameRetrieverClassName

When using X509 client certificates, this specifies the class name that will be used to retrieve the user name from the certificate. The class must implement the org.apache.catalina.realm.X509UsernameRetriever interface. The default is to use the certificate's SubjectDN as the username.

See the Container-Managed Security Guide for more information on setting up container managed security using the JAAS Realm component.

Combined Realm - org.apache.catalina.realm.CombinedRealm

CombinedRealm is an implementation of the Tomcat Realm interface that authenticates users through one or more sub-Realms.

Using CombinedRealm gives the developer the ability to combine multiple Realms of the same or different types. This can be used to authenticate against different sources, provide fall back in case one Realm fails or for any other purpose that requires multiple Realms.

Sub-realms are defined by nesting Realm elements inside the Realm element that defines the CombinedRealm. Authentication will be attempted against each Realm in the order they are listed. Authentication against any Realm will be sufficient to authenticate the user. The authenticated user, and their associated roles, will be taken from the first Realm that successfully authenticates the user.

See the Container-Managed Security Guide for more information on setting up container managed security using the CombinedRealm component.

The CombinedRealm implementation supports the following additional attributes.

AttributeDescription
allRolesMode

This attribute controls how the special role name * is handled when processing authorization constraints in web.xml. By default, the specification compliant value of strict is used which means that the user must be assigned one of the roles defined in web.xml. The alternative values are authOnly which means that the user must be authenticated but no check is made for assigned roles and strictAuthOnly which means that the user must be authenticated and no check will be made for assigned roles unless roles are defined in web.xml in which case the user must be assigned at least one of those roles.

transportGuaranteeRedirectStatus

The HTTP status code to use when the container needs to issue an HTTP redirect to meet the requirements of a configured transport guarantee. The provided status code is not validated. If not specified, the default value of 302 is used.

LockOut Realm - org.apache.catalina.realm.LockOutRealm

LockOutRealm is an implementation of the Tomcat Realm interface that extends the CombinedRealm to provide lock out functionality to provide a user lock out mechanism if there are too many failed authentication attempts in a given period of time.

To ensure correct operation, there is a reasonable degree of synchronization in this Realm.

This Realm does not require modification to the underlying Realms or the associated user storage mechanisms. It achieves this by recording all failed logins, including those for users that do not exist. To prevent a DOS by deliberating making requests with invalid users (and hence causing this cache to grow) the size of the list of users that have failed authentication is limited.

Sub-realms are defined by nesting Realm elements inside the Realm element that defines the LockOutRealm. Authentication will be attempted against each Realm in the order they are listed. Authentication against any Realm will be sufficient to authenticate the user.

The LockOutRealm implementation supports the following additional attributes.

AttributeDescription
allRolesMode

This attribute controls how the special role name * is handled when processing authorization constraints in web.xml. By default, the specification compliant value of strict is used which means that the user must be assigned one of the roles defined in web.xml. The alternative values are authOnly which means that the user must be authenticated but no check is made for assigned roles and strictAuthOnly which means that the user must be authenticated and no check will be made for assigned roles unless roles are defined in web.xml in which case the user must be assigned at least one of those roles.

cacheRemovalWarningTime

If a failed user is removed from the cache because the cache is too big before it has been in the cache for at least this period of time (in seconds) a warning message will be logged. Defaults to 3600 (1 hour).

cacheSize

Number of users that have failed authentication to keep in cache. Over time the cache will grow to this size and may not shrink. Defaults to 1000.

failureCount

The number of times in a row a user has to fail authentication to be locked out. Defaults to 5.

lockOutTime

The time (in seconds) a user is locked out for after too many authentication failures. Defaults to 300 (5 minutes). Further authentication failures during the lock out time will cause the lock out timer to reset to zero, effectively extending the lock out time. Valid authentication attempts during the lock out period will not succeed but will also not reset the lock out time.

transportGuaranteeRedirectStatus

The HTTP status code to use when the container needs to issue an HTTP redirect to meet the requirements of a configured transport guarantee. The provided status code is not validated. If not specified, the default value of 302 is used.

See the Container-Managed Security Guide for more information on setting up container managed security using the LockOutRealm component.

Null Realm - org.apache.catalina.realm.NullRealm

NullRealm is a minimal implementation of the Tomcat Realm interface that always returns null when an attempt is made to validate a user name and associated credentials. It is intended to be used as a default Realm implementation when no other Realm is specified.

The NullRealm implementation supports the following additional attributes.

AttributeDescription
transportGuaranteeRedirectStatus

The HTTP status code to use when the container needs to issue an HTTP redirect to meet the requirements of a configured transport guarantee. The provided status code is not validated. If not specified, the default value of 302 is used.

Nested Components

CombinedRealm Implementation

If you are using the CombinedRealm Implementation or a Realm that extends the CombinedRealm, e.g. the LockOutRealm, <Realm> elements may be nested inside it.

Other Realm Implementations

No other Realm implementation supports nested components.

Special Features

See Single Sign On for information about configuring Single Sign On support for a virtual host.

Comments

Notice: This comments section collects your suggestions on improving documentation for Apache Tomcat.

If you have trouble and need help, read Find Help page and ask your question on the tomcat-users mailing list. Do not ask such questions here. This is not a Q&A section.

The Apache Comments System is explained here. Comments may be removed by our moderators if they are either implemented or considered invalid/off-topic.

Copyright © 1999-2019, Apache Software Foundation