Apache Tomcat 9 Configuration Reference (9.0.37)

The Realm Component

Introduction
Attributes
Nested Components
Special Features

Introduction

A Realm element represents a "database" of usernames, passwords, and roles (similar to Unix groups) assigned to those users. Different implementations of Realm allow Catalina to be integrated into environments where such authentication information is already being created and maintained, and then utilize that information to implement Container Managed Security as described in the Servlet Specification.

A Catalina container (Engine, Host, or Context) may contain no more than one Realm element (although if supported by the Realm this one Realm may itself contain multiple nested Realms). In addition, the Realm associated with an Engine or a Host is automatically inherited by lower-level containers unless the lower level container explicitly defines its own Realm. If no Realm is configured for the Engine, an instance of the Null Realm will be configured for the Engine automatically.

For more in-depth information about container managed security in web applications, as well as more information on configuring and using the standard realm component implementations, please see the Container-Managed Security Guide.

The description below uses the variable name $CATALINA_BASE to refer the base directory against which most relative paths are resolved. If you have not configured Tomcat for multiple instances by setting a CATALINA_BASE directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME, the directory into which you have installed Tomcat.

Attributes

Common Attributes

All implementations of Realm support the following attributes:

Attribute	Description
`className`	Java class name of the implementation to use. This class must implement the `org.apache.catalina.Realm` interface.

Unlike most Catalina components, there are several standard Realm implementations available. As a result, the className attribute MUST be used to select the implementation you wish to use.

JDBC Database Realm - org.apache.catalina.realm.JDBCRealm

The JDBC Database Realm connects Tomcat to a relational database, accessed through an appropriate JDBC driver, to perform lookups of usernames, passwords, and their associated roles. Because the lookup is done each time that it is required, changes to the database will be immediately reflected in the information used to authenticate new logins.

A rich set of additional attributes lets you configure the required connection to the underlying database, as well as the table and column names used to retrieve the required information:

Attribute	Description
`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. When this attribute has the value of `authOnly` or `strictAuthOnly`, the roleNameCol* and userRoleTable attributes become optional. If those two attributes are omitted, the user's roles will not be loaded by this Realm.
`connectionName`	The database username to use when establishing the JDBC connection.
`connectionPassword`	The database password to use when establishing the JDBC connection.
`connectionURL`	The connection URL to be passed to the JDBC driver when establishing a database connection.
`driverName`	Fully qualified Java class name of the JDBC driver to be used to connect to the authentication database.
`roleNameCol`	Name of the column, in the "user roles" table, which contains a role name assigned to the corresponding user. This attribute is required in majority of configurations. See allRolesMode attribute for a rare case when it can be omitted.
`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.
`userCredCol`	Name of the column, in the "users" table, which contains the user's credentials (i.e. password). If a `CredentialHandler` is specified, this component will assume that the passwords have been encoded with the specified algorithm. Otherwise, they will be assumed to be in clear text.
`userNameCol`	Name of the column, in the "users" and "user roles" table, that contains the user's username.
`userRoleTable`	Name of the "user roles" table, which must contain columns named by the `userNameCol` and `roleNameCol` attributes. This attribute is required in majority of configurations. See allRolesMode attribute for a rare case when it can be omitted.
`userTable`	Name of the "users" table, which must contain columns named by the `userNameCol` and `userCredCol` attributes.
`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 JDBC Database Realm component.

DataSource Database Realm - org.apache.catalina.realm.DataSourceRealm

The DataSource Database Realm connects Tomcat to a relational database, accessed through a JNDI named JDBC DataSource to perform lookups of usernames, passwords, and their associated roles. Because the lookup is done each time that it is required, changes to the database will be immediately reflected in the information used to authenticate new logins.

The JDBC Realm uses a single db connection. This requires that realm based authentication be synchronized, i.e. only one authentication can be done at a time. This could be a bottleneck for applications with high volumes of realm based authentications.

The DataSource Database Realm supports simultaneous realm based authentications and allows the underlying JDBC DataSource to handle optimizations like database connection pooling.

A rich set of additional attributes lets you configure the name of the JNDI JDBC DataSource, as well as the table and column names used to retrieve the required information:

Attribute	Description
`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. When this attribute has the value of `authOnly` or `strictAuthOnly`, the roleNameCol* and userRoleTable attributes become optional. If those two attributes are omitted, the user's roles will not be loaded by this Realm.
`dataSourceName`	The name of the JNDI JDBC DataSource for this Realm.
`localDataSource`	When the realm is nested inside a Context element, this allows the realm to use a DataSource defined for the Context rather than a global DataSource. If not specified, the default is `false`: use a global DataSource.
`roleNameCol`	Name of the column, in the "user roles" table, which contains a role name assigned to the corresponding user. This attribute is required in majority of configurations. See allRolesMode attribute for a rare case when it can be omitted.
`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.
`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`.
`userCredCol`	Name of the column, in the "users" table, which contains the user's credentials (i.e. password). If a `CredentialHandler` is specified, this component will assume that the passwords have been encoded with the specified algorithm. Otherwise, they will be assumed to be in clear text.
`userNameCol`	Name of the column, in the "users" and "user roles" table, that contains the user's username.
`userRoleTable`	Name of the "user roles" table, which must contain columns named by the `userNameCol` and `roleNameCol` attributes. This attribute is required in majority of configurations. See allRolesMode attribute for a rare case when it can be omitted.
`userTable`	Name of the "users" table, which must contain columns named by the `userNameCol` and `userCredCol` attributes.
`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 DataSource Realm How-To for more information on setting up container managed security using the DataSource Database Realm component.

JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm

The JNDI Directory Realm connects Tomcat to an LDAP Directory, accessed through an appropriate JNDI driver, that stores usernames, passwords, and their associated roles. Changes to the directory are immediately reflected in the information used to authenticate new logins.

The directory realm supports a variety of approaches to using LDAP for authentication:

The realm can either use a pattern to determine the distinguished name (DN) of the user's directory entry, or search the directory to locate that entry.
The realm can authenticate the user either by binding to the directory with the DN of the user's entry and the password presented by the user, or by retrieving the password from the user's entry and performing a comparison locally.
Roles may be represented in the directory as explicit entries found by a directory search (e.g. group entries of which the user is a member), as the values of an attribute in the user's entry, or both.

A rich set of additional attributes lets you configure the required behaviour as well as the connection to the underlying directory and the element and attribute names used to retrieve information from the directory:

Attribute	Description
`adCompat`	Microsoft Active Directory often returns referrals. When iterating over NamingEnumerations these lead to PartialResultExceptions. If you want us to ignore those exceptions, set this attribute to "true". Unfortunately there's no stable way to detect, if the Exceptions really come from an AD referral. The default value is "false".
`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.
`alternateURL`	If a socket connection cannot be made to the provider at the `connectionURL` an attempt will be made to use the `alternateURL`.
`authentication`	A string specifying the type of authentication to use. "none", "simple", "strong" or a provider specific definition can be used. If no value is given the providers default is used.
`cipherSuites`	Specify which cipher suites are allowed when trying to open a secured connection using StartTLS. The allowed cipher suites are specified by a comma separated list. The default is to use the cipher suites of the JVM.
`commonRole`	A role name assigned to each successfully authenticated user in addition to the roles retrieved from LDAP. If not specified, only the roles retrieved via LDAP are used.
`connectionName`	The directory username to use when establishing a connection to the directory for LDAP search operations. If not specified an anonymous connection is made, which is often sufficient unless you specify the `userPassword` property.
`connectionPassword`	The directory password to use when establishing a connection to the directory for LDAP search operations. If not specified an anonymous connection is made, which is often sufficient unless you specify the `userPassword` property.
`connectionTimeout`	The timeout in milliseconds to use when establishing the connection to the LDAP directory. If not specified, a value of 5000 (5 seconds) is used.
`connectionURL`	The connection URL to be passed to the JNDI driver when establishing a connection to the directory.
`contextFactory`	Fully qualified Java class name of the factory class used to acquire our JNDI `InitialContext`. By default, assumes that the standard JNDI LDAP provider will be utilized.
`derefAliases`	A string specifying how aliases are to be dereferenced during search operations. The allowed values are "always", "never", "finding" and "searching". If not specified, "always" is used.
`forceDnHexEscape`	A setting of `true` forces escaping in the String representation of a distinguished name to use the `\nn` form. This may avoid issues with realms using Active Directory which appears to be more tolerant of optional escaping when the `\nn` form is used. If not specified, the default of `false` will be used.
`hostnameVerifierClassName`	The name of the class to use for hostname verification when using StartTLS for securing the connection to the ldap server. The default constructor will be used to construct an instance of the verifier class. The default is to accept only those hostnames, that are valid according to the peer certificate of the ldap server.
`protocol`	A string specifying the security protocol to use. If not given the providers default is used.
`readTimeout`	The timeout, in milliseconds, to use when trying to read from a connection to the directory. If not specified, the default of 5000 (5 seconds) is used.
`referrals`	How do we handle JNDI referrals? Allowed values are "ignore", "follow", or "throw" (see javax.naming.Context.REFERRAL for more information). Microsoft Active Directory often returns referrals. If you need to follow them set referrals to "follow". Caution: if your DNS is not part of AD, the LDAP client lib might try to resolve your domain name in DNS to find another LDAP server.
`roleBase`	The base directory entry for performing role searches. If not specified the top-level element in the directory context will be used. If specified it may optionally include pattern replacements "{0}".."{n}" corresponding to the name parts of the user's distinguished name (as returned by `javax.naming.Name.get()`).
`roleName`	The name of the attribute that contains role names in the directory entries found by a role search. In addition you can use the `userRoleName` property to specify the name of an attribute, in the user's entry, containing additional role names. If `roleName` is not specified a role search does not take place, and roles are taken only from the user's entry.
`roleNested`	Set to `true` if you want to nest roles into roles. When a role search is performed and the value of this property is `true`, the search will be repeated recursively to find all the roles that belong to the user either directly or indirectly. If not specified, the default value of `false` is used.
`roleSearch`	The LDAP filter expression used for performing role searches. Use `{0}` to substitute the distinguished name (DN) of the user, and/or `{1}` to substitute the username, and/or `{2}` for the value of an attribute from the user's directory entry, of the authenticated user. The name of the attribute that provides the value for `{2}` is configured by the `userRoleAttribute` property. When `roleNested` property is `true`, this filter expression will be also used to recursively search for other roles, which indirectly belong to this user. To find the roles that match the newly found role, the following values are used: `{0}` is substituted by the distinguished name of the newly found role, and both `{1}` and `{2}` are substituted by the name of the role (see the `roleName` property). The `userRoleAttribute` property is not applicable to this search. If this property is not specified, a role search does not take place and roles are taken only from the attribute in the user's entry specified by the `userRoleName` property.
`roleSearchAsUser`	When searching for user roles, should the search be performed as the user currently being authenticated? If false, `connectionName` and `connectionPassword` will be used if specified, else an anonymous. If not specified, the default value of `false` is used. Note that when accessing the directory using delegated credentials, this attribute is always ignored and the search is performed using the delegated credentials.
`roleSubtree`	Set to `true` if you want to search the entire subtree of the element specified by the `roleBase` property for role entries associated with the user. The default value of `false` causes only the top level to be searched.
`sizeLimit`	Specifies the maximum number of records to return when using the `userSearch` attribute. If not specified, the default of `0` is used which indicates no limit.
`spnegoDelegationQop`	When the JNDI Realm is used with the SPNEGO authenticator and `useDelegatedCredential` is `true` this attribute controls the QOP (Quality of Protection) that should be used for the connection to the LDAP server after authentication. This value is used to set the `javax.security.sasl.qop` environment property for the LDAP connection. This attribute should be a comma-separated list of values selected from `auth-conf`, `auth-int` and `auth`. See Java documentation for more details. The default value is `auth-conf`.
`sslProtocol`	Specifies which ssl protocol should be used, when connecting with StartTLS. The default is to let the jre decide. If you need even more control, you can specify the `SSLSocketFactory` to use.
`sslSocketFactory`	Specifies which `SSLSocketFactory` to use when connecting to the ldap server using StartTLS. An instance of the class will be constructed using the default constructor. If none class name is given the default jre `SSLSocketFactory` will be used.
`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`.
`timeLimit`	Specifies the time (in milliseconds) to wait for records to be returned when using the `userSearch` attribute. If not specified, the default of `0` is used which indicates no limit.
`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.
`useDelegatedCredential`	When the JNDIRealm is used with the SPNEGO authenticator, delegated credentials for the user may be available. If such credentials are present, this attribute controls whether or not they are used to connect to the directory. If not specified, the default value of `true` is used.
`userBase`	The base element for user searches performed using the `userSearch` expression. Not used if you are using the `userPattern` expression.
`userPassword`	Name of the attribute in the user's entry containing the user's password. If you specify this value, JNDIRealm will bind to the directory using the values specified by `connectionName` and `connectionPassword` properties, and retrieve the corresponding attribute for comparison to the value specified by the user being authenticated. If you do not specify this value, JNDIRealm will attempt a simple bind to the directory using the DN of the user's entry and the password presented by the user, with a successful bind being interpreted as an authenticated user.
`userPattern`	Pattern for the distinguished name (DN) of the user's directory entry, with `{0}` marking where the actual username should be inserted. You can use this property instead of `userSearch`, `userSubtree` and `userBase` when the distinguished name contains the username and is otherwise the same for all users. Note that when accessing the directory using delegated credentials, this attribute is always ignored and `userSearch`, `userSubtree` and `userBase` are always used instead.
`userRoleName`	The name of an attribute in the user's directory entry containing zero or more values for the names of roles assigned to this user. In addition you can use the `roleName` property to specify the name of an attribute to be retrieved from individual role entries found by searching the directory. If `userRoleName` is not specified all the roles for a user derive from the role search.
`userRoleAttribute`	The name of an attribute in the user's directory entry containing the value that you wish to use when you search for roles. This is especially useful for RFC 2307 where the role memberUid can be the `uid` or the `uidNumber` of the user. This value will be marked as `{2}` in your role search filter expression. This value will NOT be available for nested role searches.
`userSearch`	The LDAP filter expression to use when searching for a user's directory entry, with `{0}` marking where the actual username should be inserted. Use this property (along with the `userBase` and `userSubtree` properties) instead of `userPattern` to search the directory for the user's entry.
`userSearchAsUser`	When searching for a user's entry, should the search be performed as the user currently being authenticated? If false, `connectionName` and `connectionPassword` will be used if specified, else an anonymous. If not specified, the default value of `false` is used. Note that when accessing the directory using delegated credentials, this attribute is always ignored and the search is performed using the delegated credentials.
`userSubtree`	Set to `true` if you want to search the entire subtree of the element specified by the `userBase` property for the user's entry. The default value of `false` causes only the top level to be searched. Not used if you are using the `userPattern` expression.
`useStartTls`	Set to `true` if you want to use StartTLS for securing the connection to the ldap server. The default value is `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 JNDI Directory Realm component.

UserDatabase Realm - org.apache.catalina.realm.UserDatabaseRealm

The UserDatabase Realm is a Realm implementation that is based on a UserDatabase resource made available through the global JNDI resources configured for this Tomcat instance.

The UserDatabase Realm implementation supports the following additional attributes:

Attribute	Description
`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.
`resourceName`	The name of the global `UserDatabase` resource that this realm will use for user, password and role information.
`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.

See the Container-Managed Security Guide for more information on 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:

Attribute	Description
`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.
`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:

Attribute	Description
`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.

Attribute Description

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.

Attribute	Description
`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.

Attribute	Description
`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.

Authenticated User Realm - org.apache.catalina.realm.AuthenticatedUserRealm

AuthenticatedUserRealm is intended for use with Authenticator implementations (SSLAuthenticator, SpnegoAuthenticator) that authenticate the user as well as obtain the user credentials. An authenticated Principal is always created from the user name presented to without further validation.

Note: It is unsafe to use this Realm with Authenticator implementations that do not validate the provided credentials.

The AuthenticatedUserRealm implementation supports the following additional attributes.

Attribute	Description
`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

You can nest the following components by nesting the corresponding element inside your Realm element:

CombinedRealm Implementation - If you are using the CombinedRealm Implementation or a Realm that extends the CombinedRealm, e.g. the LockOutRealm, one or more <Realm> elements may be nested inside it.
CredentialHandler - You may nest at most one instance of this element inside a Realm. This configures the credential handler that will be used to validate provided credentials with those stored by the Realm. If not specified a default MessageDigestCredentialHandler will be configured.

Special Features

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