Gecko [ edgpens.lpkmn.gov.my ]

Name	Size	Permission
.mad-root	0 B	-rw-rw-rw-
ajp.html	53.52 KB	-rw-rw-rw-
automatic-deployment.html	78.04 KB	-rw-rw-rw-
cluster-channel.html	12.05 KB	-rw-rw-rw-
cluster-deployer.html	10.31 KB	-rw-rw-rw-
cluster-interceptor.html	32.31 KB	-rw-rw-rw-
cluster-listener.html	8.6 KB	-rw-rw-rw-
cluster-manager.html	26.82 KB	-rw-rw-rw-
cluster-membership.html	14.12 KB	-rw-rw-rw-
cluster-receiver.html	16.68 KB	-rw-rw-rw-
cluster-sender.html	18 KB	-rw-rw-rw-
cluster-valve.html	16.63 KB	-rw-rw-rw-
cluster.html	16.29 KB	-rw-rw-rw-
context.html	96.03 KB	-rw-rw-rw-
engine.html	18.48 KB	-rw-rw-rw-
executor.html	11.98 KB	-rw-rw-rw-
filter.html	114.75 KB	-rw-rw-rw-
globalresources.html	18.98 KB	-rw-rw-rw-
host.html	41.36 KB	-rw-rw-rw-
http.html	95.74 KB	-rw-rw-rw-
index.html	8.73 KB	-rw-rw-rw-
jar-scanner.html	11.84 KB	-rw-rw-rw-
listeners.html	45.44 KB	-rw-rw-rw-
loader.html	15.9 KB	-rw-rw-rw-
manager.html	39.54 KB	-rw-rw-rw-
realm.html	75.08 KB	-rw-rw-rw-
resources.html	12.17 KB	-rw-rw-rw-
server.html	10.82 KB	-rw-rw-rw-
service.html	9.92 KB	-rw-rw-rw-
sessionidgenerator.html	10.85 KB	-rw-rw-rw-
systemprops.html	50.22 KB	-rw-rw-rw-
valve.html	129.69 KB	-rw-rw-rw-

Code Editor : realm.html

<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 7 Configuration Reference (7.0.107) - The Realm Component</title><meta name="author" content="Craig R. McClanahan"><style type="text/css" media="print">
 .noPrint {display: none;}
 td#mainBody {width: 100%;}
</style><style type="text/css">
code {background-color:rgb(224,255,255);padding:0 0.1em;}
code.attributeName, code.propertyName {background-color:transparent;}

table {
 border-collapse: collapse;
 text-align: left;
}
table *:not(table) {
 /* Prevent border-collapsing for table child elements like <div> */
 border-collapse: separate;
}

th {
  text-align: left;
}

div.codeBox pre code, code.attributeName, code.propertyName, code.noHighlight, .noHighlight code {
 background-color: transparent;
}
div.codeBox {
 overflow: auto;
 margin: 1em 0;
}
div.codeBox pre {
 margin: 0;
 padding: 4px;
 border: 1px solid #999;
 border-radius: 5px;
 background-color: #eff8ff;
 display: table; /* To prevent <pre>s from taking the complete available width. */
 /*
 When it is officially supported, use the following CSS instead of display: table
 to prevent big <pre>s from exceeding the browser window:
 max-width: available;
 width: min-content;
 */
}

div.codeBox pre.wrap {
  white-space: pre-wrap;
}

table.defaultTable tr, table.detail-table tr {
    border: 1px solid #CCC;
}

table.defaultTable tr:nth-child(even), table.detail-table tr:nth-child(even) {
    background-color: #FAFBFF;
}

table.defaultTable tr:nth-child(odd), table.detail-table tr:nth-child(odd) {
    background-color: #EEEFFF;
}

table.defaultTable th, table.detail-table th {
  background-color: #88b;
  color: #fff;
}

table.defaultTable th, table.defaultTable td, table.detail-table th, table.detail-table td {
  padding: 5px 8px;
}

p.notice {
 border: 1px solid rgb(255, 0, 0);
 background-color: rgb(238, 238, 238);
 color: rgb(0, 51, 102);
 padding: 0.5em;
 margin: 1em 2em 1em 1em;
}
</style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><tr><td><a href="https://tomcat.apache.org/"><img src="../images/tomcat.gif" align="right" alt="
 The Apache Tomcat Servlet/JSP Container
 " border="0"></a></td><td><h1>Apache Tomcat 7</h1>Version 7.0.107, Nov 18 2020</td><td><a href="http://www.apache.org/"><img src="../images/asf-logo.svg" align="right" alt="Apache Logo" border="0" style="width: 266px;height: 83px;"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><td width="20%" valign="top" nowrap class="noPrint">Links<ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Config Ref. Home</a></li><li><a href="https://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul>Top Level Elements<ul><li><a href="server.html">Server</a></li><li><a href="service.html">Service</a></li></ul>Executors<ul><li><a href="executor.html">Executor</a></li></ul>Connectors<ul><li><a href="http.html">HTTP</a></li><li><a href="ajp.html">AJP</a></li></ul>Containers<ul><li><a href="context.html">Context</a></li><li><a href="engine.html">Engine</a></li><li><a href="host.html">Host</a></li><li><a href="cluster.html">Cluster</a></li></ul>Nested Components<ul><li><a href="globalresources.html">Global Resources</a></li><li><a href="jar-scanner.html">JarScanner</a></li><li><a href="listeners.html">Listeners</a></li><li><a href="loader.html">Loader</a></li><li><a href="manager.html">Manager</a></li><li><a href="realm.html">Realm</a></li><li><a href="resources.html">Resources</a></li><li><a href="sessionidgenerator.html">SessionIdGenerator</a></li><li><a href="valve.html">Valve</a></li></ul>Cluster Elements<ul><li><a href="cluster.html">Cluster</a></li><li><a href="cluster-manager.html">Manager</a></li><li><a href="cluster-channel.html">Channel</a></li><li><a href="cluster-membership.html">Channel/Membership</a></li><li><a href="cluster-sender.html">Channel/Sender</a></li><li><a href="cluster-receiver.html">Channel/Receiver</a></li><li><a href="cluster-interceptor.html">Channel/Interceptor</a></li><li><a href="cluster-valve.html">Valve</a></li><li><a href="cluster-deployer.html">Deployer</a></li><li><a href="cluster-listener.html">ClusterListener</a></li></ul>web.xml<ul><li><a href="filter.html">Filter</a></li></ul>Other<ul><li><a href="systemprops.html">System properties</a></li></ul></td><td width="80%" valign="top" align="left" id="mainBody"><h1>The Realm Component</h1><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><a name="Table of Contents"></a><a name="Table_of_Contents">Table of Contents</a></td></tr><tr><td><blockquote>
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Attributes">Attributes</a><ol><li><a href="#Common_Attributes">Common Attributes</a></li><li><a href="#DataSource_Database_Realm_-_org.apache.catalina.realm.DataSourceRealm">DataSource Database Realm - org.apache.catalina.realm.DataSourceRealm</a></li><li><a href="#JNDI_Directory_Realm_-_org.apache.catalina.realm.JNDIRealm">JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm</a></li><li><a href="#UserDatabase_Realm_-_org.apache.catalina.realm.UserDatabaseRealm">UserDatabase Realm - org.apache.catalina.realm.UserDatabaseRealm</a></li><li><a href="#Memory_Based_Realm_-_org.apache.catalina.realm.MemoryRealm">Memory Based Realm - org.apache.catalina.realm.MemoryRealm</a></li><li><a href="#JAAS_Realm_-_org.apache.catalina.realm.JAASRealm">JAAS Realm - org.apache.catalina.realm.JAASRealm</a></li><li><a href="#Combined_Realm_-_org.apache.catalina.realm.CombinedRealm">Combined Realm - org.apache.catalina.realm.CombinedRealm</a></li><li><a href="#LockOut_Realm_-_org.apache.catalina.realm.LockOutRealm">LockOut Realm - org.apache.catalina.realm.LockOutRealm</a></li><li><a href="#Null_Realm_-_org.apache.catalina.realm.NullRealm">Null Realm - org.apache.catalina.realm.NullRealm</a></li><li><a href="#JDBC_Database_Realm_-_org.apache.catalina.realm.JDBCRealm">JDBC Database Realm - org.apache.catalina.realm.JDBCRealm</a></li></ol></li><li><a href="#Nested_Components">Nested Components</a></li><li><a href="#Special_Features">Special Features</a></li></ul>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><a name="Introduction">Introduction</a></td></tr><tr><td><blockquote>

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 (<a href="engine.html">Engine</a>,
 <a href="host.html">Host</a>, or <a href="context.html">Context</a>) 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
 <a href="#Null_Realm_-_org.apache.catalina.realm.NullRealm">Null Realm</a>
 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
 <a href="../realm-howto.html">Container-Managed Security Guide</a>.

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.

</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><a name="Attributes">Attributes</a></td></tr><tr><td><blockquote>

<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><a name="Common Attributes"></a><a name="Common_Attributes">Common Attributes</a></td></tr><tr><td><blockquote>

All implementations of Realm
 support the following attributes:

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

</blockquote></td></tr></table>

<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><a name="DataSource Database Realm - org.apache.catalina.realm.DataSourceRealm"></a><a name="DataSource_Database_Realm_-_org.apache.catalina.realm.DataSourceRealm">DataSource Database Realm - org.apache.catalina.realm.DataSourceRealm</a></td></tr><tr><td><blockquote>

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:

See the <a href="../realm-howto.html#DataSourceRealm">
 DataSource Realm HOW-TO</a> for more information on setting up container
 managed security using the DataSource Database Realm component.

</blockquote></td></tr></table>

<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><a name="JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm"></a><a name="JNDI_Directory_Realm_-_org.apache.catalina.realm.JNDIRealm">JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm</a></td></tr><tr><td><blockquote>

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:

<ul>
 <li>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.
 </li>

<li>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.
 </li>

<li>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.
 </li>
 </ul>

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:

<table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264">Attribute</th><th width="85%" bgcolor="#023264">Description</th></tr><tr><td align="left" valign="center"><code class="attributeName">adCompat</code></td><td align="left" valign="center">
 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".
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">allRolesMode</code></td><td align="left" valign="center">
 This attribute controls how the special role name <code>*</code> is
 handled when processing authorization constraints in web.xml. By
 default, the specification compliant value of <code>strict</code> is
 used which means that the user must be assigned one of the roles defined
 in web.xml. The alternative values are <code>authOnly</code> which means
 that the user must be authenticated but no check is made for assigned
 roles and <code>strictAuthOnly</code> 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.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">alternateURL</code></td><td align="left" valign="center">
 If a socket connection can not be made to the provider at
 the <code>connectionURL</code> an attempt will be made to use the
 <code>alternateURL</code>.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">authentication</code></td><td align="left" valign="center">
 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.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">cipherSuites</code></td><td align="left" valign="center">
 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.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">commonRole</code></td><td align="left" valign="center">
 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.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">connectionName</code></td><td align="left" valign="center">
 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 <code>userPassword</code>
 property.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">connectionPassword</code></td><td align="left" valign="center">
 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 <code>userPassword</code>
 property.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">connectionTimeout</code></td><td align="left" valign="center">
 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.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">connectionURL</code></td><td align="left" valign="center">
 The connection URL to be passed to the JNDI driver when
 establishing a connection to the directory.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">contextFactory</code></td><td align="left" valign="center">
 Fully qualified Java class name of the factory class used
 to acquire our JNDI <code>InitialContext</code>. By default,
 assumes that the standard JNDI LDAP provider will be utilized.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">derefAliases</code></td><td align="left" valign="center">
 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.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">digest</code></td><td align="left" valign="center">
 The digest algorithm to apply to the plaintext password offered
 by the user before comparing it with the value retrieved from the
 directory. Valid values are those accepted for the algorithm name
 by the <code>java.security.MessageDigest</code> class. If not
 specified the plaintext password is assumed to be retrieved. Not
 required unless <code>userPassword</code> is specified
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">forceDnHexEscape</code></td><td align="left" valign="center">
 A setting of <code>true</code> forces escaping in the String
 representation of a distinguished name to use the <code>\nn</code> form.
 This may avoid issues with realms using Active Directory which appears
 to be more tolerant of optional escaping when the <code>\nn</code> form
 is used. If not specified, the default of <code>false</code> will be
 used.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">hostnameVerifierClassName</code></td><td align="left" valign="center">
 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.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">protocol</code></td><td align="left" valign="center">
 A string specifying the security protocol to use. If not given
 the providers default is used.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">readTimeout</code></td><td align="left" valign="center">
 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.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">referrals</code></td><td align="left" valign="center">
 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.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">roleBase</code></td><td align="left" valign="center">
 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
 <code>javax.naming.Name.get()</code>).
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">roleName</code></td><td align="left" valign="center">
 The name of the attribute that contains role names in the
 directory entries found by a role search. In addition you can
 use the <code>userRoleName</code> property to specify the name
 of an attribute, in the user's entry, containing additional
 role names.
 If <code>roleName</code> is not specified a role
 search does not take place, and roles are taken only from the
 user's entry.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">roleNested</code></td><td align="left" valign="center">
 Set to <code>true</code> if you want to nest roles into roles.
 When a role search is performed and the value of this property is
 <code>true</code>, 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 <code>false</code> is used.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">roleSearch</code></td><td align="left" valign="center">
 The LDAP filter expression used for performing role
 searches.

Use <code>{0}</code> to substitute the distinguished name (DN)
 of the user, and/or <code>{1}</code> to substitute the username,
 and/or <code>{2}</code> 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 <code>{2}</code>
 is configured by the <code>userRoleAttribute</code> property.

When <code>roleNested</code> property is <code>true</code>,
 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:
 <code>{0}</code> is substituted by the distinguished name of the newly
 found role, and both <code>{1}</code> and <code>{2}</code> are
 substituted by the name of the role (see the <code>roleName</code>
 property). The <code>userRoleAttribute</code> 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 <code>userRoleName</code> property.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">roleSearchAsUser</code></td><td align="left" valign="center">
 When searching for user roles, should the search be performed as the
 user currently being authenticated? If false,
 <code>connectionName</code> and <code>connectionPassword</code> will be
 used if specified, else an anonymous. If not specified, the default
 value of <code>false</code> 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.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">roleSubtree</code></td><td align="left" valign="center">
 Set to <code>true</code> if you want to search the entire
 subtree of the element specified by the <code>roleBase</code>
 property for role entries associated with the user. The
 default value of <code>false</code> causes only the top level
 to be searched.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">sizeLimit</code></td><td align="left" valign="center">
 Specifies the maximum number of records to return when using the
 <code>userSearch</code> attribute. If not specified, the default of
 <code>0</code> is used which indicates no limit.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">spnegoDelegationQop</code></td><td align="left" valign="center">
 When the JNDI Realm is used with the SPNEGO authenticator and
 <code>useDelegatedCredential</code> is <code>true</code> 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
 <code>javax.security.sasl.qop</code> environment property for the LDAP
 connection. This attribute should be a comma-separated list of values
 selected from <code>auth-conf</code>, <code>auth-int</code> and
 <code>auth</code>. See <a href="http://docs.oracle.com/javase/7/docs/api/javax/security/sasl/Sasl.html#QOP" rel="nofollow">Java documentation</a> for more details.
 The default value is <code>auth-conf</code>.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">sslProtocol</code></td><td align="left" valign="center">
 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 <code>SSLSocketFactory</code> to use.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">sslSocketFactory</code></td><td align="left" valign="center">
 Specifies which <code>SSLSocketFactory</code> 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 <code>SSLSocketFactory</code> will be used.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">stripRealmForGss</code></td><td align="left" valign="center">
 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 <code>true</code>.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">timeLimit</code></td><td align="left" valign="center">
 Specifies the time (in milliseconds) to wait for records to be
 returned when using the <code>userSearch</code> attribute. If not
 specified, the default of <code>0</code> is used which indicates no
 limit.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">transportGuaranteeRedirectStatus</code></td><td align="left" valign="center">
 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 <code>302</code> is used.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">useDelegatedCredential</code></td><td align="left" valign="center">
 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
 <code>true</code> is used.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">userBase</code></td><td align="left" valign="center">
 The base element for user searches performed using the
 <code>userSearch</code> expression. Not used if you are using
 the <code>userPattern</code> expression.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">userPassword</code></td><td align="left" valign="center">
 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
 <code>connectionName</code> and
 <code>connectionPassword</code> 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.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">userPattern</code></td><td align="left" valign="center">
 Pattern for the distinguished name (DN) of the user's
 directory entry, with <code>{0}</code> marking where the
 actual username should be inserted. You can use this property
 instead of <code>userSearch</code>, <code>userSubtree</code>
 and <code>userBase</code> 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 <code>userSearch</code>,
 <code>userSubtree</code> and <code>userBase</code> are always
 used instead.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">userRoleName</code></td><td align="left" valign="center">
 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
 <code>roleName</code> property to specify the name of an
 attribute to be retrieved from individual role entries found
 by searching the directory. If <code>userRoleName</code> is
 not specified all the roles for a user derive from the role
 search.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">userRoleAttribute</code></td><td align="left" valign="center">
 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 <code>uid</code> or the
 <code>uidNumber</code> of the user. This value will be
 marked as <code>{2}</code> in your role search filter expression.
 This value will NOT be available for nested role searches.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">userSearch</code></td><td align="left" valign="center">
 The LDAP filter expression to use when searching for a
 user's directory entry, with <code>{0}</code> marking where
 the actual username should be inserted. Use this property
 (along with the <code>userBase</code> and
 <code>userSubtree</code> properties) instead of
 <code>userPattern</code> to search the directory for the
 user's entry.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">userSearchAsUser</code></td><td align="left" valign="center">
 When searching for a user's entry, should the search be performed as
 the user currently being authenticated? If false,
 <code>connectionName</code> and <code>connectionPassword</code> will be
 used if specified, else an anonymous. If not specified, the default
 value of <code>false</code> 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.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">userSubtree</code></td><td align="left" valign="center">
 Set to <code>true</code> if you want to search the entire
 subtree of the element specified by the <code>userBase</code>
 property for the user's entry. The default value of
 <code>false</code> causes only the top level to be searched.
 Not used if you are using the <code>userPattern</code>
 expression.
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">useStartTls</code></td><td align="left" valign="center">
 Set to <code>true</code> if you want to use StartTLS for securing
 the connection to the ldap server. The default value is <code>false</code>.
 
 </td></tr><tr><td align="left" valign="center"><code class="attributeName">X509UsernameRetrieverClassName</code></td><td align="left" valign="center">
 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
 <code>org.apache.catalina.realm.X509UsernameRetriever</code>
 interface. The default is to use the certificate's SubjectDN
 as the username.
 </td></tr></table>

See the <a href="../realm-howto.html">Container-Managed Security Guide</a> for more
 information on setting up container managed security using the
 JNDI Directory Realm component.

</blockquote></td></tr></table>

<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><a name="UserDatabase Realm - org.apache.catalina.realm.UserDatabaseRealm"></a><a name="UserDatabase_Realm_-_org.apache.catalina.realm.UserDatabaseRealm">UserDatabase Realm - org.apache.catalina.realm.UserDatabaseRealm</a></td></tr><tr><td><blockquote>

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:

See the
 <a href="../realm-howto.html">Container-Managed Security Guide</a> for more
 information on setting up container managed security using the UserDatabase
 Realm component and the
 <a href="../jndi-resources-howto.html">JNDI resources how-to</a> for more
 information on how to configure a UserDatabase resource.

</blockquote></td></tr></table>

<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><a name="Memory Based Realm - org.apache.catalina.realm.MemoryRealm"></a><a name="Memory_Based_Realm_-_org.apache.catalina.realm.MemoryRealm">Memory Based Realm - org.apache.catalina.realm.MemoryRealm</a></td></tr><tr><td><blockquote>

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:

The XML document referenced by the <code>pathname</code> attribute must
 conform to the following requirements:
 <ul>
 <li>The root (outer) element must be <code>&lt;tomcat-users&gt;</code>.
 </li>
 <li>Each authorized user must be represented by a single XML element
 <code>&lt;user&gt;</code>, nested inside the root element.</li>
 <li>Each <code>&lt;user&gt;</code> element must have the following
 attributes:
 <ul>
 <li>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.</li>
 <li>password - Password of this user (in
 clear text).</li>
 <li>roles - Comma-delimited list of the role names
 assigned to this user.</li>
 </ul></li>
 </ul>

See the <a href="../realm-howto.html">Container-Managed Security Guide</a> for more
 information on setting up container managed security using the
 Memory Based Realm component.

</blockquote></td></tr></table>

<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><a name="JAAS Realm - org.apache.catalina.realm.JAASRealm"></a><a name="JAAS_Realm_-_org.apache.catalina.realm.JAASRealm">JAAS Realm - org.apache.catalina.realm.JAASRealm</a></td></tr><tr><td><blockquote>

JAASRealm is an implementation of the Tomcat
 <code>Realm</code> interface that authenticates users through the Java
 Authentication &amp; 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 <a href="https://www.jcp.org/en/jsr/detail?id=196">JCP Specification Request
 196</a> 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 <code>javax.security.auth.spi.LoginModule</code> and
 <code>javax.security.Principal</code>), 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:

See the <a href="../realm-howto.html">Container-Managed Security
 Guide</a> for more information on setting up container managed security
 using the JAAS Realm component.

</blockquote></td></tr></table>

<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><a name="Combined Realm - org.apache.catalina.realm.CombinedRealm"></a><a name="Combined_Realm_-_org.apache.catalina.realm.CombinedRealm">Combined Realm - org.apache.catalina.realm.CombinedRealm</a></td></tr><tr><td><blockquote>

CombinedRealm is an implementation of the Tomcat
 <code>Realm</code> 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 <code>Realm</code> elements inside the
 <code>Realm</code> element that defines the CombinedRealm. Authentication
 will be attempted against each <code>Realm</code> 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 <a href="../realm-howto.html">Container-Managed Security
 Guide</a> for more information on setting up container managed security
 using the CombinedRealm component.

The CombinedRealm implementation supports the following additional
 attributes.

<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><a name="LockOut Realm - org.apache.catalina.realm.LockOutRealm"></a><a name="LockOut_Realm_-_org.apache.catalina.realm.LockOutRealm">LockOut Realm - org.apache.catalina.realm.LockOutRealm</a></td></tr><tr><td><blockquote>

LockOutRealm is an implementation of the Tomcat
 <code>Realm</code> 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 <code>Realm</code> elements inside the
 <code>Realm</code> element that defines the LockOutRealm. Authentication
 will be attempted against each <code>Realm</code> 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.

See the <a href="../realm-howto.html">Container-Managed Security
 Guide</a> for more information on setting up container managed security
 using the LockOutRealm component.

</blockquote></td></tr></table>

<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><a name="Null Realm - org.apache.catalina.realm.NullRealm"></a><a name="Null_Realm_-_org.apache.catalina.realm.NullRealm">Null Realm - org.apache.catalina.realm.NullRealm</a></td></tr><tr><td><blockquote>

NullRealm is a minimal implementation of the Tomcat
 <code>Realm</code> 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.

</blockquote></td></tr></table>

<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><a name="JDBC Database Realm - org.apache.catalina.realm.JDBCRealm"></a><a name="JDBC_Database_Realm_-_org.apache.catalina.realm.JDBCRealm">JDBC Database Realm - org.apache.catalina.realm.JDBCRealm</a></td></tr><tr><td><blockquote>

The JDBC Database Realm has been deprecated and will be removed
 in Tomcat 10 onwards. Use the DataSourceRealm instead.

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:

See the <a href="../realm-howto.html">Container-Managed Security Guide</a> for more
 information on setting up container managed security using the
 JDBC Database Realm component.

</blockquote></td></tr></table>

</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><a name="Nested Components"></a><a name="Nested_Components">Nested Components</a></td></tr><tr><td><blockquote>

<h3>CombinedRealm Implementation</h3>

If you are using the CombinedRealm Implementation or a Realm
 that extends the CombinedRealm, e.g. the LockOutRealm,
 &lt;Realm&gt; elements may be nested inside it.

<h3>Other Realm Implementations</h3>

No other Realm implementation supports nested components.

</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><a name="Special Features"></a><a name="Special_Features">Special Features</a></td></tr><tr><td><blockquote>

See <a href="host.html">Single Sign On</a> for information about
 configuring Single Sign On support for a virtual host.

</blockquote></td></tr></table></td></tr><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><td colspan="2"><div align="center">
 Copyright &copy; 1999-2020, Apache Software Foundation
 </div></td></tr></table></body></html>

${this.title}

Code Editor : realm.html