Details | Last modification | View Log | RSS feed
| Rev | Author | Line No. | Line |
|---|---|---|---|
| 771 | blopes | 1 | <!DOCTYPE html SYSTEM "about:legacy-compat"> |
| 2 | <html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><link href="../images/docs-stylesheet.css" rel="stylesheet" type="text/css"><title>Apache Tomcat 9 Configuration Reference (9.0.112) - The Realm Component</title></head><body><div id="wrapper"><header><div id="header"><div><div><div class="logo noPrint"><a href="https://tomcat.apache.org/"><img alt="Tomcat Home" src="../images/tomcat.png"></a></div><div style="height: 1px;"></div><div class="asfLogo noPrint"><a href="https://www.apache.org/" target="_blank"><img src="../images/asf-logo.svg" alt="The Apache Software Foundation" style="width: 266px; height: 83px;"></a></div><h1>Apache Tomcat 9 Configuration Reference</h1><div class="versionInfo"> |
||
| 3 | Version 9.0.112, |
||
| 4 | <time datetime="2025-11-06">Nov 6 2025</time></div><div style="height: 1px;"></div><div style="clear: left;"></div></div></div></div></header><div id="middle"><div><div id="mainLeft" class="noprint"><div><nav><div><h2>Links</h2><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Config Ref. Home</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul></div><div><h2>Top Level Elements</h2><ul><li><a href="server.html">Server</a></li><li><a href="service.html">Service</a></li></ul></div><div><h2>Executors</h2><ul><li><a href="executor.html">Executor</a></li></ul></div><div><h2>Connectors</h2><ul><li><a href="http.html">HTTP/1.1</a></li><li><a href="http2.html">HTTP/2</a></li><li><a href="ajp.html">AJP</a></li></ul></div><div><h2>Containers</h2><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></div><div><h2>Nested Components</h2><ul><li><a href="cookie-processor.html">CookieProcessor</a></li><li><a href="credentialhandler.html">CredentialHandler</a></li><li><a href="globalresources.html">Global Resources</a></li><li><a href="jar-scanner.html">JarScanner</a></li><li><a href="jar-scan-filter.html">JarScanFilter</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></div><div><h2>Cluster Elements</h2><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></div><div><h2>web.xml</h2><ul><li><a href="filter.html">Filter</a></li></ul></div><div><h2>Other</h2><ul><li><a href="runtime-attributes.html">Runtime attributes</a></li><li><a href="systemprops.html">System properties</a></li><li><a href="jaspic.html">JASPIC</a></li></ul></div></nav></div></div><div id="mainRight"><div id="content"><h2>The Realm Component</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text"> |
||
| 5 | <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="#Authenticated_User_Realm_-_org.apache.catalina.realm.AuthenticatedUserRealm">Authenticated User Realm - org.apache.catalina.realm.AuthenticatedUserRealm</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> |
||
| 6 | </div><h3 id="Introduction">Introduction</h3><div class="text"> |
||
| 7 | |||
| 8 | <p>A <strong>Realm</strong> element represents a "database" of usernames, |
||
| 9 | passwords, and <em>roles</em> (similar to Unix <em>groups</em>) assigned |
||
| 10 | to those users. Different implementations of Realm allow Catalina to be |
||
| 11 | integrated into environments where such authentication information is already |
||
| 12 | being created and maintained, and then utilize that information to implement |
||
| 13 | <em>Container Managed Security</em> as described in the Servlet |
||
| 14 | Specification.</p> |
||
| 15 | |||
| 16 | <p>A Catalina container (<a href="engine.html">Engine</a>, |
||
| 17 | <a href="host.html">Host</a>, or <a href="context.html">Context</a>) may |
||
| 18 | contain no more than one Realm element (although if supported by the Realm |
||
| 19 | this one Realm may itself contain multiple nested Realms). In addition, the |
||
| 20 | Realm associated with an Engine or a Host is automatically inherited by |
||
| 21 | lower-level containers unless the lower level container explicitly defines its |
||
| 22 | own Realm. If no Realm is configured for the Engine, an instance of the |
||
| 23 | <a href="#Null_Realm_-_org.apache.catalina.realm.NullRealm">Null Realm</a> |
||
| 24 | will be configured for the Engine automatically.</p> |
||
| 25 | |||
| 26 | <p>For more in-depth information about container managed security in web |
||
| 27 | applications, as well as more information on configuring and using the |
||
| 28 | standard realm component implementations, please see the |
||
| 29 | <a href="../realm-howto.html">Container-Managed Security Guide</a>. |
||
| 30 | </p> |
||
| 31 | |||
| 32 | <p><em>The description below uses the variable name $CATALINA_BASE to refer the |
||
| 33 | base directory against which most relative paths are resolved. If you have |
||
| 34 | not configured Tomcat for multiple instances by setting a CATALINA_BASE |
||
| 35 | directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME, |
||
| 36 | the directory into which you have installed Tomcat.</em></p> |
||
| 37 | |||
| 38 | </div><h3 id="Attributes">Attributes</h3><div class="text"> |
||
| 39 | |||
| 40 | <div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text"> |
||
| 41 | |||
| 42 | <p>All implementations of <strong>Realm</strong> |
||
| 43 | support the following attributes:</p> |
||
| 44 | |||
| 45 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 46 | Attribute |
||
| 47 | </th><th style="width: 85%;"> |
||
| 48 | Description |
||
| 49 | </th></tr><tr id="Attributes_Common Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td> |
||
| 50 | <p>Java class name of the implementation to use. This class must |
||
| 51 | implement the <code>org.apache.catalina.Realm</code> interface.</p> |
||
| 52 | </td></tr></table> |
||
| 53 | |||
| 54 | <p>Unlike most Catalina components, there are several standard |
||
| 55 | <strong>Realm</strong> implementations available. As a result, |
||
| 56 | the <code>className</code> attribute MUST be used to select the |
||
| 57 | implementation you wish to use.</p> |
||
| 58 | |||
| 59 | </div></div> |
||
| 60 | |||
| 61 | |||
| 62 | <div class="subsection"><h4 id="DataSource_Database_Realm_-_org.apache.catalina.realm.DataSourceRealm">DataSource Database Realm - org.apache.catalina.realm.DataSourceRealm</h4><div class="text"> |
||
| 63 | |||
| 64 | <p>The <strong>DataSource Database Realm</strong> connects Tomcat to |
||
| 65 | a relational database, accessed through a JNDI named JDBC DataSource |
||
| 66 | to perform lookups of usernames, passwords, and their associated |
||
| 67 | roles. Because the lookup is done each time that it is required, |
||
| 68 | changes to the database will be immediately reflected in the |
||
| 69 | information used to authenticate new logins.</p> |
||
| 70 | |||
| 71 | <p>The JDBC Realm uses a single db connection. This requires that |
||
| 72 | realm based authentication be synchronized, i.e. only one authentication |
||
| 73 | can be done at a time. This could be a bottleneck for applications |
||
| 74 | with high volumes of realm based authentications.</p> |
||
| 75 | |||
| 76 | <p>The DataSource Database Realm supports simultaneous realm based |
||
| 77 | authentications and allows the underlying JDBC DataSource to |
||
| 78 | handle optimizations like database connection pooling.</p> |
||
| 79 | |||
| 80 | <p>A rich set of additional attributes lets you configure the name |
||
| 81 | of the JNDI JDBC DataSource, as well as the table and |
||
| 82 | column names used to retrieve the required information:</p> |
||
| 83 | |||
| 84 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 85 | Attribute |
||
| 86 | </th><th style="width: 85%;"> |
||
| 87 | Description |
||
| 88 | </th></tr><tr id="Attributes_DataSource Database Realm - org.apache.catalina.realm.DataSourceRealm_allRolesMode"><td><code class="attributeName">allRolesMode</code></td><td> |
||
| 89 | <p>This attribute controls how the special role name <code>*</code> is |
||
| 90 | handled when processing authorization constraints in web.xml. By |
||
| 91 | default, the specification compliant value of <code>strict</code> is |
||
| 92 | used which means that the user must be assigned one of the roles defined |
||
| 93 | in web.xml. The alternative values are <code>authOnly</code> which means |
||
| 94 | that the user must be authenticated but no check is made for assigned |
||
| 95 | roles and <code>strictAuthOnly</code> which means that the user must be |
||
| 96 | authenticated and no check will be made for assigned roles unless roles |
||
| 97 | are defined in web.xml in which case the user must be assigned at least |
||
| 98 | one of those roles.</p> |
||
| 99 | <p>When this attribute has the value of <code>authOnly</code> or |
||
| 100 | <code>strictAuthOnly</code>, the <strong>roleNameCol</strong> and |
||
| 101 | <strong>userRoleTable</strong> attributes become optional. If those two |
||
| 102 | attributes are omitted, the user's roles will not be loaded by this |
||
| 103 | Realm.</p> |
||
| 104 | </td></tr><tr id="Attributes_DataSource Database Realm - org.apache.catalina.realm.DataSourceRealm_dataSourceName"><td><strong><code class="attributeName">dataSourceName</code></strong></td><td> |
||
| 105 | <p>The name of the JNDI JDBC DataSource for this Realm.</p> |
||
| 106 | </td></tr><tr id="Attributes_DataSource Database Realm - org.apache.catalina.realm.DataSourceRealm_localDataSource"><td><code class="attributeName">localDataSource</code></td><td> |
||
| 107 | <p>When the realm is nested inside a Context element, this allows the |
||
| 108 | realm to use a DataSource defined for the Context rather than a global |
||
| 109 | DataSource. If not specified, the default is <code>false</code>: use a |
||
| 110 | global DataSource.</p> |
||
| 111 | </td></tr><tr id="Attributes_DataSource Database Realm - org.apache.catalina.realm.DataSourceRealm_roleNameCol"><td><code class="attributeName">roleNameCol</code></td><td> |
||
| 112 | <p>Name of the column, in the "user roles" table, which contains |
||
| 113 | a role name assigned to the corresponding user.</p> |
||
| 114 | <p>This attribute is <strong>required</strong> in majority of |
||
| 115 | configurations. See <strong>allRolesMode</strong> attribute for |
||
| 116 | a rare case when it can be omitted.</p> |
||
| 117 | </td></tr><tr id="Attributes_DataSource Database Realm - org.apache.catalina.realm.DataSourceRealm_transportGuaranteeRedirectStatus"><td><code class="attributeName">transportGuaranteeRedirectStatus</code></td><td> |
||
| 118 | <p>The HTTP status code to use when the container needs to issue an HTTP |
||
| 119 | redirect to meet the requirements of a configured transport |
||
| 120 | guarantee. The provided status code is not validated. If not |
||
| 121 | specified, the default value of <code>302</code> is used.</p> |
||
| 122 | </td></tr><tr id="Attributes_DataSource Database Realm - org.apache.catalina.realm.DataSourceRealm_stripRealmForGss"><td><code class="attributeName">stripRealmForGss</code></td><td> |
||
| 123 | <p>When processing users authenticated via the GSS-API, this attribute |
||
| 124 | controls if any "@..." is removed from the end of the user |
||
| 125 | name. If not specified, the default is <code>true</code>.</p> |
||
| 126 | </td></tr><tr id="Attributes_DataSource Database Realm - org.apache.catalina.realm.DataSourceRealm_userCredCol"><td><strong><code class="attributeName">userCredCol</code></strong></td><td> |
||
| 127 | <p>Name of the column, in the "users" table, which contains |
||
| 128 | the user's credentials (i.e. password). If a |
||
| 129 | <code>CredentialHandler</code> is specified, this component |
||
| 130 | will assume that the passwords have been encoded with the |
||
| 131 | specified algorithm. Otherwise, they will be assumed to be |
||
| 132 | in clear text.</p> |
||
| 133 | </td></tr><tr id="Attributes_DataSource Database Realm - org.apache.catalina.realm.DataSourceRealm_userNameCol"><td><strong><code class="attributeName">userNameCol</code></strong></td><td> |
||
| 134 | <p>Name of the column, in the "users" and "user roles" table, |
||
| 135 | that contains the user's username.</p> |
||
| 136 | </td></tr><tr id="Attributes_DataSource Database Realm - org.apache.catalina.realm.DataSourceRealm_userRoleTable"><td><code class="attributeName">userRoleTable</code></td><td> |
||
| 137 | <p>Name of the "user roles" table, which must contain columns |
||
| 138 | named by the <code>userNameCol</code> and <code>roleNameCol</code> |
||
| 139 | attributes.</p> |
||
| 140 | <p>This attribute is <strong>required</strong> in majority of |
||
| 141 | configurations. See <strong>allRolesMode</strong> attribute for |
||
| 142 | a rare case when it can be omitted.</p> |
||
| 143 | </td></tr><tr id="Attributes_DataSource Database Realm - org.apache.catalina.realm.DataSourceRealm_userTable"><td><strong><code class="attributeName">userTable</code></strong></td><td> |
||
| 144 | <p>Name of the "users" table, which must contain columns named |
||
| 145 | by the <code>userNameCol</code> and <code>userCredCol</code> |
||
| 146 | attributes.</p> |
||
| 147 | </td></tr><tr id="Attributes_DataSource Database Realm - org.apache.catalina.realm.DataSourceRealm_X509UsernameRetrieverClassName"><td><code class="attributeName">X509UsernameRetrieverClassName</code></td><td> |
||
| 148 | <p>When using X509 client certificates, this specifies the class name |
||
| 149 | that will be used to retrieve the user name from the certificate. |
||
| 150 | The class must implement the |
||
| 151 | <code>org.apache.catalina.realm.X509UsernameRetriever</code> |
||
| 152 | interface. The default is to use the certificate's SubjectDN |
||
| 153 | as the username.</p> |
||
| 154 | </td></tr></table> |
||
| 155 | |||
| 156 | <p>See the <a href="../realm-howto.html#DataSourceRealm"> |
||
| 157 | DataSource Realm How-To</a> for more information on setting up container |
||
| 158 | managed security using the DataSource Database Realm component.</p> |
||
| 159 | |||
| 160 | </div></div> |
||
| 161 | |||
| 162 | |||
| 163 | <div class="subsection"><h4 id="JNDI_Directory_Realm_-_org.apache.catalina.realm.JNDIRealm">JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm</h4><div class="text"> |
||
| 164 | |||
| 165 | <p>The <strong>JNDI Directory Realm</strong> connects Tomcat to |
||
| 166 | an LDAP Directory, accessed through an appropriate JNDI driver, |
||
| 167 | that stores usernames, passwords, and their associated |
||
| 168 | roles. Changes to the directory are immediately reflected in the |
||
| 169 | information used to authenticate new logins.</p> |
||
| 170 | |||
| 171 | <p>The directory realm supports a variety of approaches to using |
||
| 172 | LDAP for authentication:</p> |
||
| 173 | |||
| 174 | <ul> |
||
| 175 | <li>The realm can either use a pattern to determine the |
||
| 176 | distinguished name (DN) of the user's directory entry, or search |
||
| 177 | the directory to locate that entry. |
||
| 178 | </li> |
||
| 179 | |||
| 180 | <li>The realm can authenticate the user either by binding to the |
||
| 181 | directory with the DN of the user's entry and the password |
||
| 182 | presented by the user, or by retrieving the password from the |
||
| 183 | user's entry and performing a comparison locally. |
||
| 184 | </li> |
||
| 185 | |||
| 186 | <li>Roles may be represented in the directory as explicit entries |
||
| 187 | found by a directory search (e.g. group entries of which the user |
||
| 188 | is a member), as the values of an attribute in the user's entry, |
||
| 189 | or both. |
||
| 190 | </li> |
||
| 191 | </ul> |
||
| 192 | |||
| 193 | <p> A rich set of additional attributes lets you configure the |
||
| 194 | required behaviour as well as the connection to the underlying |
||
| 195 | directory and the element and attribute names used to retrieve |
||
| 196 | information from the directory:</p> |
||
| 197 | |||
| 198 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 199 | Attribute |
||
| 200 | </th><th style="width: 85%;"> |
||
| 201 | Description |
||
| 202 | </th></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_adCompat"><td><code class="attributeName">adCompat</code></td><td> |
||
| 203 | <p>Microsoft Active Directory often returns referrals. |
||
| 204 | When iterating over NamingEnumerations these lead to |
||
| 205 | PartialResultExceptions. If you want us to ignore those exceptions, |
||
| 206 | set this attribute to "true". Unfortunately there's no stable way |
||
| 207 | to detect, if the Exceptions really come from an AD referral. |
||
| 208 | The default value is "false".</p> |
||
| 209 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_allRolesMode"><td><code class="attributeName">allRolesMode</code></td><td> |
||
| 210 | <p>This attribute controls how the special role name <code>*</code> is |
||
| 211 | handled when processing authorization constraints in web.xml. By |
||
| 212 | default, the specification compliant value of <code>strict</code> is |
||
| 213 | used which means that the user must be assigned one of the roles defined |
||
| 214 | in web.xml. The alternative values are <code>authOnly</code> which means |
||
| 215 | that the user must be authenticated but no check is made for assigned |
||
| 216 | roles and <code>strictAuthOnly</code> which means that the user must be |
||
| 217 | authenticated and no check will be made for assigned roles unless roles |
||
| 218 | are defined in web.xml in which case the user must be assigned at least |
||
| 219 | one of those roles.</p> |
||
| 220 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_alternateURL"><td><code class="attributeName">alternateURL</code></td><td> |
||
| 221 | <p>If a socket connection cannot be made to the provider at |
||
| 222 | the <code>connectionURL</code> an attempt will be made to use the |
||
| 223 | <code>alternateURL</code>.</p> |
||
| 224 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_authentication"><td><code class="attributeName">authentication</code></td><td> |
||
| 225 | <p>A string specifying the type of authentication to use. "none", |
||
| 226 | "simple", "strong" or a provider specific definition can be used. If the |
||
| 227 | provider specific mechanism "GSSAPI" is specified and supported by the |
||
| 228 | provider, there are some circumstances, such as handling calls to |
||
| 229 | <code>HttpServletRequest.login(String username, String password)</code>, |
||
| 230 | where "GSSAPI" will not be used and the user will be |
||
| 231 | authenticated as described in <code>userPassword</code>. If no value is |
||
| 232 | given, the providers default is used.</p> |
||
| 233 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_cipherSuites"><td><code class="attributeName">cipherSuites</code></td><td> |
||
| 234 | <p>Specify which cipher suites are allowed when trying to open |
||
| 235 | a secured connection using StartTLS. The allowed cipher suites |
||
| 236 | are specified by a comma separated list. The default is to use the |
||
| 237 | cipher suites of the JVM.</p> |
||
| 238 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_commonRole"><td><code class="attributeName">commonRole</code></td><td> |
||
| 239 | <p>A role name assigned to each successfully authenticated user in |
||
| 240 | addition to the roles retrieved from LDAP. If not specified, only |
||
| 241 | the roles retrieved via LDAP are used.</p> |
||
| 242 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_connectionName"><td><code class="attributeName">connectionName</code></td><td> |
||
| 243 | <p>The directory username to use when establishing a |
||
| 244 | connection to the directory for LDAP search operations. If not |
||
| 245 | specified an anonymous connection is made, which is often |
||
| 246 | sufficient unless you specify the <code>userPassword</code> |
||
| 247 | property.</p> |
||
| 248 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_connectionPassword"><td><code class="attributeName">connectionPassword</code></td><td> |
||
| 249 | <p>The directory password to use when establishing a |
||
| 250 | connection to the directory for LDAP search operations. If not |
||
| 251 | specified an anonymous connection is made, which is often |
||
| 252 | sufficient unless you specify the <code>userPassword</code> |
||
| 253 | property.</p> |
||
| 254 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_connectionPoolSize"><td><code class="attributeName">connectionPoolSize</code></td><td> |
||
| 255 | <p>The JNDI realm can use a pool of connections to the directory server |
||
| 256 | to avoid blocking on a single connection. This attribute value is the |
||
| 257 | maximum pool size. If not specified, it will use <code>1</code>, which |
||
| 258 | means a single connection will be used.</p> |
||
| 259 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_connectionTimeout"><td><code class="attributeName">connectionTimeout</code></td><td> |
||
| 260 | <p>The timeout in milliseconds to use when establishing the connection |
||
| 261 | to the LDAP directory. If not specified, a value of 5000 (5 seconds) is |
||
| 262 | used.</p> |
||
| 263 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_connectionURL"><td><strong><code class="attributeName">connectionURL</code></strong></td><td> |
||
| 264 | <p>The connection URL to be passed to the JNDI driver when |
||
| 265 | establishing a connection to the directory.</p> |
||
| 266 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_contextFactory"><td><code class="attributeName">contextFactory</code></td><td> |
||
| 267 | <p>Fully qualified Java class name of the factory class used |
||
| 268 | to acquire our JNDI <code>InitialContext</code>. By default, |
||
| 269 | assumes that the standard JNDI LDAP provider will be utilized.</p> |
||
| 270 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_derefAliases"><td><code class="attributeName">derefAliases</code></td><td> |
||
| 271 | <p>A string specifying how aliases are to be dereferenced during |
||
| 272 | search operations. The allowed values are "always", "never", |
||
| 273 | "finding" and "searching". If not specified, "always" is used.</p> |
||
| 274 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_forceDnHexEscape"><td><code class="attributeName">forceDnHexEscape</code></td><td> |
||
| 275 | <p>A setting of <code>true</code> forces escaping in the String |
||
| 276 | representation of a distinguished name to use the <code>\nn</code> form. |
||
| 277 | This may avoid issues with realms using Active Directory which appears |
||
| 278 | to be more tolerant of optional escaping when the <code>\nn</code> form |
||
| 279 | is used. If not specified, the default of <code>false</code> will be |
||
| 280 | used.</p> |
||
| 281 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_hostnameVerifierClassName"><td><code class="attributeName">hostnameVerifierClassName</code></td><td> |
||
| 282 | <p>The name of the class to use for hostname verification when |
||
| 283 | using StartTLS for securing the connection to the ldap server. |
||
| 284 | The default constructor will be used to construct an instance of |
||
| 285 | the verifier class. The default is to accept only those hostnames, |
||
| 286 | that are valid according to the peer certificate of the ldap |
||
| 287 | server.</p> |
||
| 288 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_protocol"><td><code class="attributeName">protocol</code></td><td> |
||
| 289 | <p>A string specifying the TLS protocol to use. If not given, the |
||
| 290 | Java runtime's default is used.</p> |
||
| 291 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_readTimeout"><td><code class="attributeName">readTimeout</code></td><td> |
||
| 292 | <p>The timeout, in milliseconds, to use when trying to read from a |
||
| 293 | connection to the directory. If not specified, the default of 5000 |
||
| 294 | (5 seconds) is used.</p> |
||
| 295 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_referrals"><td><code class="attributeName">referrals</code></td><td> |
||
| 296 | <p>How do we handle JNDI referrals? Allowed values are |
||
| 297 | "ignore", "follow", or "throw" (see javax.naming.Context.REFERRAL |
||
| 298 | for more information). |
||
| 299 | Microsoft Active Directory often returns referrals. |
||
| 300 | If you need to follow them set referrals to "follow". |
||
| 301 | Caution: if your DNS is not part of AD, the LDAP client lib might try |
||
| 302 | to resolve your domain name in DNS to find another LDAP server.</p> |
||
| 303 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_roleBase"><td><code class="attributeName">roleBase</code></td><td> |
||
| 304 | <p>The base directory entry for performing role searches. If not |
||
| 305 | specified the top-level element in the directory context will be used. |
||
| 306 | If specified it may optionally include pattern replacements |
||
| 307 | "{0}".."{n}" corresponding to the name parts of the |
||
| 308 | user's distinguished name (as returned by |
||
| 309 | <code>javax.naming.Name.get()</code>).</p> |
||
| 310 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_roleName"><td><code class="attributeName">roleName</code></td><td> |
||
| 311 | <p>The name of the attribute that contains role names in the |
||
| 312 | directory entries found by a role search. In addition you can |
||
| 313 | use the <code>userRoleName</code> property to specify the name |
||
| 314 | of an attribute, in the user's entry, containing additional |
||
| 315 | role names.</p> |
||
| 316 | <p>If <code>roleName</code> is not specified a role |
||
| 317 | search does not take place, and roles are taken only from the |
||
| 318 | user's entry.</p> |
||
| 319 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_roleNested"><td><code class="attributeName">roleNested</code></td><td> |
||
| 320 | <p>Set to <code>true</code> if you want to nest roles into roles. |
||
| 321 | When a role search is performed and the value of this property is |
||
| 322 | <code>true</code>, the search will be repeated recursively to find |
||
| 323 | all the roles that belong to the user either directly or indirectly. |
||
| 324 | If not specified, the default value of <code>false</code> is used.</p> |
||
| 325 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_roleSearch"><td><code class="attributeName">roleSearch</code></td><td> |
||
| 326 | <p>The LDAP filter expression used for performing role |
||
| 327 | searches.</p> |
||
| 328 | |||
| 329 | <p>Use <code>{0}</code> to substitute the distinguished name (DN) |
||
| 330 | of the user, and/or <code>{1}</code> to substitute the username, |
||
| 331 | and/or <code>{2}</code> for the value of an attribute from the |
||
| 332 | user's directory entry, of the authenticated user. |
||
| 333 | The name of the attribute that provides the value for <code>{2}</code> |
||
| 334 | is configured by the <code>userRoleAttribute</code> property.</p> |
||
| 335 | |||
| 336 | <p>When <code>roleNested</code> property is <code>true</code>, |
||
| 337 | this filter expression will be also used to recursively search for |
||
| 338 | other roles, which indirectly belong to this user. To find the |
||
| 339 | roles that match the newly found role, the following values |
||
| 340 | are used: |
||
| 341 | <code>{0}</code> is substituted by the distinguished name of the newly |
||
| 342 | found role, and both <code>{1}</code> and <code>{2}</code> are |
||
| 343 | substituted by the name of the role (see the <code>roleName</code> |
||
| 344 | property). The <code>userRoleAttribute</code> property is not |
||
| 345 | applicable to this search.</p> |
||
| 346 | |||
| 347 | <p>If this property is not specified, a role search does not take |
||
| 348 | place and roles are taken only from the attribute in the user's entry |
||
| 349 | specified by the <code>userRoleName</code> property.</p> |
||
| 350 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_roleSearchAsUser"><td><code class="attributeName">roleSearchAsUser</code></td><td> |
||
| 351 | <p> When searching for user roles, should the search be performed as the |
||
| 352 | user currently being authenticated? If false, |
||
| 353 | <code>connectionName</code> and <code>connectionPassword</code> will be |
||
| 354 | used if specified, else an anonymous. If not specified, the default |
||
| 355 | value of <code>false</code> is used. Note that when accessing the |
||
| 356 | directory using delegated credentials, this attribute is always ignored |
||
| 357 | and the search is performed using the delegated credentials.</p> |
||
| 358 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_roleSubtree"><td><code class="attributeName">roleSubtree</code></td><td> |
||
| 359 | <p>Set to <code>true</code> if you want to search the entire |
||
| 360 | subtree of the element specified by the <code>roleBase</code> |
||
| 361 | property for role entries associated with the user. The |
||
| 362 | default value of <code>false</code> causes only the top level |
||
| 363 | to be searched.</p> |
||
| 364 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_sizeLimit"><td><code class="attributeName">sizeLimit</code></td><td> |
||
| 365 | <p>Specifies the maximum number of records to return when using the |
||
| 366 | <code>userSearch</code> attribute. If not specified, the default of |
||
| 367 | <code>0</code> is used which indicates no limit.</p> |
||
| 368 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_spnegoDelegationQop"><td><code class="attributeName">spnegoDelegationQop</code></td><td> |
||
| 369 | <p>When the JNDI Realm is used with the SPNEGO authenticator and |
||
| 370 | <code>useDelegatedCredential</code> is <code>true</code> this attribute |
||
| 371 | controls the QOP (Quality of Protection) that should be used for |
||
| 372 | the connection to the LDAP |
||
| 373 | server after authentication. This value is used to set the |
||
| 374 | <code>javax.security.sasl.qop</code> environment property for the LDAP |
||
| 375 | connection. This attribute should be a comma-separated list of values |
||
| 376 | selected from <code>auth-conf</code>, <code>auth-int</code> and |
||
| 377 | <code>auth</code>. See <a href="https://docs.oracle.com/javase/8/docs/api/javax/security/sasl/Sasl.html#QOP" rel="nofollow">Java documentation</a> for more details.</p> |
||
| 378 | <p>The default value is <code>auth-conf</code>.</p> |
||
| 379 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_sslProtocol"><td><code class="attributeName">sslProtocol</code></td><td> |
||
| 380 | <p>Specifies which ssl protocol should be used, when connecting with |
||
| 381 | StartTLS. The default is to let the jre decide. If you need even more |
||
| 382 | control, you can specify the <code>SSLSocketFactory</code> to use.</p> |
||
| 383 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_sslSocketFactory"><td><code class="attributeName">sslSocketFactory</code></td><td> |
||
| 384 | <p>Specifies which <code>SSLSocketFactory</code> to use when connecting |
||
| 385 | to the ldap server using StartTLS. An instance of the class will be |
||
| 386 | constructed using the default constructor. If none class name is given |
||
| 387 | the default jre <code>SSLSocketFactory</code> will be used.</p> |
||
| 388 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_stripRealmForGss"><td><code class="attributeName">stripRealmForGss</code></td><td> |
||
| 389 | <p>When processing users authenticated via the GSS-API, this attribute |
||
| 390 | controls if any "@..." is removed from the end of the user |
||
| 391 | name. If not specified, the default is <code>true</code>.</p> |
||
| 392 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_timeLimit"><td><code class="attributeName">timeLimit</code></td><td> |
||
| 393 | <p>Specifies the time (in milliseconds) to wait for records to be |
||
| 394 | returned when using the <code>userSearch</code> attribute. If not |
||
| 395 | specified, the default of <code>0</code> is used which indicates no |
||
| 396 | limit.</p> |
||
| 397 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_transportGuaranteeRedirectStatus"><td><code class="attributeName">transportGuaranteeRedirectStatus</code></td><td> |
||
| 398 | <p>The HTTP status code to use when the container needs to issue an HTTP |
||
| 399 | redirect to meet the requirements of a configured transport |
||
| 400 | guarantee. The provided status code is not validated. If not |
||
| 401 | specified, the default value of <code>302</code> is used.</p> |
||
| 402 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_useContextClassLoader"><td><code class="attributeName">useContextClassLoader</code></td><td> |
||
| 403 | <p>Instructs JNDIRealm to use the context class loader when opening the |
||
| 404 | connection for the JNDI provider. The default value is |
||
| 405 | <code>true</code>. To load classes using the container's classloader, |
||
| 406 | specify <code>false</code>.</p> |
||
| 407 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_useDelegatedCredential"><td><code class="attributeName">useDelegatedCredential</code></td><td> |
||
| 408 | <p>When the JNDIRealm is used with the SPNEGO authenticator, delegated |
||
| 409 | credentials for the user may be available. If such credentials are |
||
| 410 | present, this attribute controls whether or not they are used to |
||
| 411 | connect to the directory. If delegated credentials are present but not |
||
| 412 | used because this attribute is <code>false</code>, the behaviour will be |
||
| 413 | as described in <code>roleSearchAsUser</code>, <code>userPattern</code> |
||
| 414 | and <code>userSearchAsUser</code> when delegated credentials are not |
||
| 415 | used. If not specified, the default value of <code>true</code> is |
||
| 416 | used.</p> |
||
| 417 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_userBase"><td><code class="attributeName">userBase</code></td><td> |
||
| 418 | <p>The base element for user searches performed using the |
||
| 419 | <code>userSearch</code> expression. Not used if you are using |
||
| 420 | the <code>userPattern</code> expression.</p> |
||
| 421 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_userPassword"><td><code class="attributeName">userPassword</code></td><td> |
||
| 422 | <p>Name of the attribute in the user's entry containing the |
||
| 423 | user's password. If you specify this value, JNDIRealm will |
||
| 424 | bind to the directory using the values specified by |
||
| 425 | <code>connectionName</code> and |
||
| 426 | <code>connectionPassword</code> properties, and retrieve the |
||
| 427 | corresponding attribute for comparison to the value specified |
||
| 428 | by the user being authenticated. If you do |
||
| 429 | <strong>not</strong> specify this value, JNDIRealm will |
||
| 430 | attempt a simple bind to the directory using the DN of the |
||
| 431 | user's entry and the password presented by the user, with a |
||
| 432 | successful bind being interpreted as an authenticated |
||
| 433 | user.</p> |
||
| 434 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_userPattern"><td><code class="attributeName">userPattern</code></td><td> |
||
| 435 | <p>Pattern for the distinguished name (DN) of the user's |
||
| 436 | directory entry, with <code>{0}</code> marking where the |
||
| 437 | actual username should be inserted. You can use this property |
||
| 438 | instead of <code>userSearch</code>, <code>userSubtree</code> |
||
| 439 | and <code>userBase</code> when the distinguished name contains |
||
| 440 | the username and is otherwise the same for all users. Note that |
||
| 441 | when accessing the directory using delegated credentials, this |
||
| 442 | attribute is always ignored and <code>userSearch</code>, |
||
| 443 | <code>userSubtree</code> and <code>userBase</code> are always |
||
| 444 | used instead.</p> |
||
| 445 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_userRoleName"><td><code class="attributeName">userRoleName</code></td><td> |
||
| 446 | <p>The name of an attribute in the user's directory entry |
||
| 447 | containing zero or more values for the names of roles assigned |
||
| 448 | to this user. In addition you can use the |
||
| 449 | <code>roleName</code> property to specify the name of an |
||
| 450 | attribute to be retrieved from individual role entries found |
||
| 451 | by searching the directory. If <code>userRoleName</code> is |
||
| 452 | not specified all the roles for a user derive from the role |
||
| 453 | search.</p> |
||
| 454 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_userRoleAttribute"><td><code class="attributeName">userRoleAttribute</code></td><td> |
||
| 455 | <p>The name of an attribute in the user's directory entry |
||
| 456 | containing the value that you wish to use when you search for |
||
| 457 | roles. This is especially useful for RFC 2307 where |
||
| 458 | the role memberUid can be the <code>uid</code> or the |
||
| 459 | <code>uidNumber</code> of the user. This value will be |
||
| 460 | marked as <code>{2}</code> in your role search filter expression. |
||
| 461 | This value will NOT be available for nested role searches.</p> |
||
| 462 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_userSearch"><td><code class="attributeName">userSearch</code></td><td> |
||
| 463 | <p>The LDAP filter expression to use when searching for a |
||
| 464 | user's directory entry, with <code>{0}</code> marking where |
||
| 465 | the actual username should be inserted. Use this property |
||
| 466 | (along with the <code>userBase</code> and |
||
| 467 | <code>userSubtree</code> properties) instead of |
||
| 468 | <code>userPattern</code> to search the directory for the |
||
| 469 | user's entry.</p> |
||
| 470 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_userSearchAsUser"><td><code class="attributeName">userSearchAsUser</code></td><td> |
||
| 471 | <p> When searching for a user's entry, should the search be performed as |
||
| 472 | the user currently being authenticated? If false, |
||
| 473 | <code>connectionName</code> and <code>connectionPassword</code> will be |
||
| 474 | used if specified, else an anonymous. If not specified, the default |
||
| 475 | value of <code>false</code> is used. Note that when accessing the |
||
| 476 | directory using delegated credentials, this attribute is always ignored |
||
| 477 | and the search is performed using the delegated credentials.</p> |
||
| 478 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_userSubtree"><td><code class="attributeName">userSubtree</code></td><td> |
||
| 479 | <p>Set to <code>true</code> if you want to search the entire |
||
| 480 | subtree of the element specified by the <code>userBase</code> |
||
| 481 | property for the user's entry. The default value of |
||
| 482 | <code>false</code> causes only the top level to be searched. |
||
| 483 | Not used if you are using the <code>userPattern</code> |
||
| 484 | expression.</p> |
||
| 485 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_useStartTls"><td><code class="attributeName">useStartTls</code></td><td> |
||
| 486 | <p>Set to <code>true</code> if you want to use StartTLS for securing |
||
| 487 | the connection to the ldap server. The default value is <code>false</code>. |
||
| 488 | </p> |
||
| 489 | </td></tr><tr id="Attributes_JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm_X509UsernameRetrieverClassName"><td><code class="attributeName">X509UsernameRetrieverClassName</code></td><td> |
||
| 490 | <p>When using X509 client certificates, this specifies the class name |
||
| 491 | that will be used to retrieve the user name from the certificate. |
||
| 492 | The class must implement the |
||
| 493 | <code>org.apache.catalina.realm.X509UsernameRetriever</code> |
||
| 494 | interface. The default is to use the certificate's SubjectDN |
||
| 495 | as the username.</p> |
||
| 496 | </td></tr></table> |
||
| 497 | |||
| 498 | <p>See the <a href="../realm-howto.html">Container-Managed Security Guide</a> for more |
||
| 499 | information on setting up container managed security using the |
||
| 500 | JNDI Directory Realm component.</p> |
||
| 501 | |||
| 502 | </div></div> |
||
| 503 | |||
| 504 | |||
| 505 | <div class="subsection"><h4 id="UserDatabase_Realm_-_org.apache.catalina.realm.UserDatabaseRealm">UserDatabase Realm - org.apache.catalina.realm.UserDatabaseRealm</h4><div class="text"> |
||
| 506 | |||
| 507 | <p>The <strong>UserDatabase Realm</strong> is a Realm implementation |
||
| 508 | that is based on a UserDatabase resource made available through the global |
||
| 509 | JNDI resources configured for this Tomcat instance.</p> |
||
| 510 | |||
| 511 | <p>The UserDatabase Realm implementation supports the following |
||
| 512 | additional attributes:</p> |
||
| 513 | |||
| 514 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 515 | Attribute |
||
| 516 | </th><th style="width: 85%;"> |
||
| 517 | Description |
||
| 518 | </th></tr><tr id="Attributes_UserDatabase Realm - org.apache.catalina.realm.UserDatabaseRealm_allRolesMode"><td><code class="attributeName">allRolesMode</code></td><td> |
||
| 519 | <p>This attribute controls how the special role name <code>*</code> is |
||
| 520 | handled when processing authorization constraints in web.xml. By |
||
| 521 | default, the specification compliant value of <code>strict</code> is |
||
| 522 | used which means that the user must be assigned one of the roles defined |
||
| 523 | in web.xml. The alternative values are <code>authOnly</code> which means |
||
| 524 | that the user must be authenticated but no check is made for assigned |
||
| 525 | roles and <code>strictAuthOnly</code> which means that the user must be |
||
| 526 | authenticated and no check will be made for assigned roles unless roles |
||
| 527 | are defined in web.xml in which case the user must be assigned at least |
||
| 528 | one of those roles.</p> |
||
| 529 | </td></tr><tr id="Attributes_UserDatabase Realm - org.apache.catalina.realm.UserDatabaseRealm_localJndiResource"><td><code class="attributeName">localJndiResource</code></td><td> |
||
| 530 | <p>When the realm is nested inside a Context element, this allows the |
||
| 531 | realm to use a UserDatabase defined for the Context rather than a global |
||
| 532 | UserDatabase. If not specified, the default is <code>false</code>: use a |
||
| 533 | global UserDatabase.</p> |
||
| 534 | </td></tr><tr id="Attributes_UserDatabase Realm - org.apache.catalina.realm.UserDatabaseRealm_resourceName"><td><strong><code class="attributeName">resourceName</code></strong></td><td> |
||
| 535 | <p>The name of the global <code>UserDatabase</code> resource |
||
| 536 | that this realm will use for user, password and role information.</p> |
||
| 537 | </td></tr><tr id="Attributes_UserDatabase Realm - org.apache.catalina.realm.UserDatabaseRealm_useStaticPrincipal"><td><code class="attributeName">useStaticPrincipal</code></td><td> |
||
| 538 | <p>This allows using a static <code>Principal</code> instance |
||
| 539 | disconnected from the database if needed. This makes the behavior of |
||
| 540 | authenticated principals equivalent to that of the other realms. |
||
| 541 | If there is a plan to use serialization, it is best to set this to |
||
| 542 | <code>true</code> as the principal will always be replaced by this |
||
| 543 | equivalent static principal when serializing. |
||
| 544 | If not specified, the default is <code>false</code>: use a |
||
| 545 | Principal connected to the UserDatabase.</p> |
||
| 546 | </td></tr><tr id="Attributes_UserDatabase Realm - org.apache.catalina.realm.UserDatabaseRealm_transportGuaranteeRedirectStatus"><td><code class="attributeName">transportGuaranteeRedirectStatus</code></td><td> |
||
| 547 | <p>The HTTP status code to use when the container needs to issue an HTTP |
||
| 548 | redirect to meet the requirements of a configured transport |
||
| 549 | guarantee. The provided status code is not validated. If not |
||
| 550 | specified, the default value of <code>302</code> is used.</p> |
||
| 551 | </td></tr><tr id="Attributes_UserDatabase Realm - org.apache.catalina.realm.UserDatabaseRealm_X509UsernameRetrieverClassName"><td><code class="attributeName">X509UsernameRetrieverClassName</code></td><td> |
||
| 552 | <p>When using X509 client certificates, this specifies the class name |
||
| 553 | that will be used to retrieve the user name from the certificate. |
||
| 554 | The class must implement the |
||
| 555 | <code>org.apache.catalina.realm.X509UsernameRetriever</code> |
||
| 556 | interface. The default is to use the certificate's SubjectDN |
||
| 557 | as the username.</p> |
||
| 558 | </td></tr></table> |
||
| 559 | |||
| 560 | <p>See the |
||
| 561 | <a href="../realm-howto.html">Container-Managed Security Guide</a> for more |
||
| 562 | information on setting up container managed security using the UserDatabase |
||
| 563 | Realm component and the |
||
| 564 | <a href="../jndi-resources-howto.html">JNDI resources how-to</a> for more |
||
| 565 | information on how to configure a UserDatabase resource.</p> |
||
| 566 | |||
| 567 | </div></div> |
||
| 568 | |||
| 569 | |||
| 570 | <div class="subsection"><h4 id="Memory_Based_Realm_-_org.apache.catalina.realm.MemoryRealm">Memory Based Realm - org.apache.catalina.realm.MemoryRealm</h4><div class="text"> |
||
| 571 | |||
| 572 | <p>The <strong>Memory Based Realm</strong> is a simple Realm implementation |
||
| 573 | that reads user information from an XML format, and represents it as a |
||
| 574 | collection of Java objects in memory. This implementation is intended |
||
| 575 | solely to get up and running with container managed security - it is NOT |
||
| 576 | intended for production use. As such, there are no mechanisms for |
||
| 577 | updating the in-memory collection of users when the content of the |
||
| 578 | underlying data file is changed.</p> |
||
| 579 | |||
| 580 | <p>The Memory Based Realm implementation supports the following |
||
| 581 | additional attributes:</p> |
||
| 582 | |||
| 583 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 584 | Attribute |
||
| 585 | </th><th style="width: 85%;"> |
||
| 586 | Description |
||
| 587 | </th></tr><tr id="Attributes_Memory Based Realm - org.apache.catalina.realm.MemoryRealm_allRolesMode"><td><code class="attributeName">allRolesMode</code></td><td> |
||
| 588 | <p>This attribute controls how the special role name <code>*</code> is |
||
| 589 | handled when processing authorization constraints in web.xml. By |
||
| 590 | default, the specification compliant value of <code>strict</code> is |
||
| 591 | used which means that the user must be assigned one of the roles defined |
||
| 592 | in web.xml. The alternative values are <code>authOnly</code> which means |
||
| 593 | that the user must be authenticated but no check is made for assigned |
||
| 594 | roles and <code>strictAuthOnly</code> which means that the user must be |
||
| 595 | authenticated and no check will be made for assigned roles unless roles |
||
| 596 | are defined in web.xml in which case the user must be assigned at least |
||
| 597 | one of those roles.</p> |
||
| 598 | </td></tr><tr id="Attributes_Memory Based Realm - org.apache.catalina.realm.MemoryRealm_pathname"><td><code class="attributeName">pathname</code></td><td> |
||
| 599 | <p>URL, absolute path or relative path (to $CATALINA_BASE) for the XML |
||
| 600 | file containing our user information. See below for details on the |
||
| 601 | XML element format required. If no pathname is specified, the |
||
| 602 | default value is <code>conf/tomcat-users.xml</code>.</p> |
||
| 603 | </td></tr><tr id="Attributes_Memory Based Realm - org.apache.catalina.realm.MemoryRealm_stripRealmForGss"><td><code class="attributeName">stripRealmForGss</code></td><td> |
||
| 604 | <p>When processing users authenticated via the GSS-API, this attribute |
||
| 605 | controls if any "@..." is removed from the end of the user |
||
| 606 | name. If not specified, the default is <code>true</code>.</p> |
||
| 607 | </td></tr><tr id="Attributes_Memory Based Realm - org.apache.catalina.realm.MemoryRealm_transportGuaranteeRedirectStatus"><td><code class="attributeName">transportGuaranteeRedirectStatus</code></td><td> |
||
| 608 | <p>The HTTP status code to use when the container needs to issue an HTTP |
||
| 609 | redirect to meet the requirements of a configured transport |
||
| 610 | guarantee. The provided status code is not validated. If not |
||
| 611 | specified, the default value of <code>302</code> is used.</p> |
||
| 612 | </td></tr><tr id="Attributes_Memory Based Realm - org.apache.catalina.realm.MemoryRealm_X509UsernameRetrieverClassName"><td><code class="attributeName">X509UsernameRetrieverClassName</code></td><td> |
||
| 613 | <p>When using X509 client certificates, this specifies the class name |
||
| 614 | that will be used to retrieve the user name from the certificate. |
||
| 615 | The class must implement the |
||
| 616 | <code>org.apache.catalina.realm.X509UsernameRetriever</code> |
||
| 617 | interface. The default is to use the certificate's SubjectDN |
||
| 618 | as the username.</p> |
||
| 619 | </td></tr></table> |
||
| 620 | |||
| 621 | <p>The XML document referenced by the <code>pathname</code> attribute must |
||
| 622 | conform to the following requirements:</p> |
||
| 623 | <ul> |
||
| 624 | <li>The root (outer) element must be <code><tomcat-users></code>. |
||
| 625 | </li> |
||
| 626 | <li>Each authorized user must be represented by a single XML element |
||
| 627 | <code><user></code>, nested inside the root element.</li> |
||
| 628 | <li>Each <code><user></code> element must have the following |
||
| 629 | attributes: |
||
| 630 | <ul> |
||
| 631 | <li><strong>username</strong> - Username of this user (must be unique |
||
| 632 | within this file).<br> |
||
| 633 | For compatibility, it is allowed to use <strong>name</strong> as an |
||
| 634 | alternative name for this attribute.</li> |
||
| 635 | <li><strong>password</strong> - Password of this user (in |
||
| 636 | clear text).</li> |
||
| 637 | <li><strong>roles</strong> - Comma-delimited list of the role names |
||
| 638 | assigned to this user.</li> |
||
| 639 | </ul></li> |
||
| 640 | </ul> |
||
| 641 | |||
| 642 | <p>See the <a href="../realm-howto.html">Container-Managed Security Guide</a> for more |
||
| 643 | information on setting up container managed security using the |
||
| 644 | Memory Based Realm component.</p> |
||
| 645 | |||
| 646 | </div></div> |
||
| 647 | |||
| 648 | |||
| 649 | <div class="subsection"><h4 id="JAAS_Realm_-_org.apache.catalina.realm.JAASRealm">JAAS Realm - org.apache.catalina.realm.JAASRealm</h4><div class="text"> |
||
| 650 | |||
| 651 | <p><strong>JAASRealm</strong> is an implementation of the Tomcat |
||
| 652 | <code>Realm</code> interface that authenticates users through the Java |
||
| 653 | Authentication & Authorization Service (JAAS) framework which is now |
||
| 654 | provided as part of the standard J2SE API.</p> |
||
| 655 | |||
| 656 | <p>Using JAASRealm gives the developer the ability to combine practically |
||
| 657 | any conceivable security realm with Tomcat's CMA.</p> |
||
| 658 | |||
| 659 | <p>JAASRealm is prototype for Tomcat of the JAAS-based J2EE authentication |
||
| 660 | framework for J2EE v1.4, based on the <a href="https://www.jcp.org/en/jsr/detail?id=196">JCP Specification Request |
||
| 661 | 196</a> to enhance container-managed security and promote 'pluggable' |
||
| 662 | authentication mechanisms whose implementations would be |
||
| 663 | container-independent.</p> |
||
| 664 | |||
| 665 | <p>Based on the JAAS login module and principal |
||
| 666 | (see <code>javax.security.auth.spi.LoginModule</code> and |
||
| 667 | <code>javax.security.Principal</code>), you can develop your own security |
||
| 668 | mechanism or wrap another third-party mechanism for integration with the CMA |
||
| 669 | as implemented by Tomcat.</p> |
||
| 670 | |||
| 671 | <p>The JAAS Realm implementation supports the following additional |
||
| 672 | attributes:</p> |
||
| 673 | |||
| 674 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 675 | Attribute |
||
| 676 | </th><th style="width: 85%;"> |
||
| 677 | Description |
||
| 678 | </th></tr><tr id="Attributes_JAAS Realm - org.apache.catalina.realm.JAASRealm_allRolesMode"><td><code class="attributeName">allRolesMode</code></td><td> |
||
| 679 | <p>This attribute controls how the special role name <code>*</code> is |
||
| 680 | handled when processing authorization constraints in web.xml. By |
||
| 681 | default, the specification compliant value of <code>strict</code> is |
||
| 682 | used which means that the user must be assigned one of the roles defined |
||
| 683 | in web.xml. The alternative values are <code>authOnly</code> which means |
||
| 684 | that the user must be authenticated but no check is made for assigned |
||
| 685 | roles and <code>strictAuthOnly</code> which means that the user must be |
||
| 686 | authenticated and no check will be made for assigned roles unless roles |
||
| 687 | are defined in web.xml in which case the user must be assigned at least |
||
| 688 | one of those roles.</p> |
||
| 689 | </td></tr><tr id="Attributes_JAAS Realm - org.apache.catalina.realm.JAASRealm_appName"><td><code class="attributeName">appName</code></td><td> |
||
| 690 | <p>The name of the application as configured in your login configuration |
||
| 691 | file |
||
| 692 | (<a href="http://docs.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/LoginConfigFile.html">JAAS LoginConfig</a>).</p> |
||
| 693 | <p>If not specified <code>appName</code> is derived from the Container's |
||
| 694 | name it is placed in, for example <code>Catalina</code> or <code>ROOT</code>. |
||
| 695 | If the realm is not placed in any Container, the default is <code>Tomcat</code>. |
||
| 696 | </p> |
||
| 697 | </td></tr><tr id="Attributes_JAAS Realm - org.apache.catalina.realm.JAASRealm_userClassNames"><td><strong><code class="attributeName">userClassNames</code></strong></td><td> |
||
| 698 | <p>A comma-separated list of the names of the classes that you have made |
||
| 699 | for your user <code>Principals</code>.</p> |
||
| 700 | </td></tr><tr id="Attributes_JAAS Realm - org.apache.catalina.realm.JAASRealm_configFile"><td><code class="attributeName">configFile</code></td><td> |
||
| 701 | <p>The name of a JAAS configuration file to use with this Realm. It will |
||
| 702 | be searched for using <code>ClassLoader#getResource(String)</code> so it |
||
| 703 | is possible for the configuration to be bundled within a web |
||
| 704 | application. If not specified, the default JVM global JAAS configuration |
||
| 705 | will be used.</p> |
||
| 706 | </td></tr><tr id="Attributes_JAAS Realm - org.apache.catalina.realm.JAASRealm_roleClassNames"><td><code class="attributeName">roleClassNames</code></td><td> |
||
| 707 | <p>A comma-separated list of the names of the classes that you have made |
||
| 708 | for your role <code>Principals</code>.</p> |
||
| 709 | </td></tr><tr id="Attributes_JAAS Realm - org.apache.catalina.realm.JAASRealm_stripRealmForGss"><td><code class="attributeName">stripRealmForGss</code></td><td> |
||
| 710 | <p>When processing users authenticated via the GSS-API, this attribute |
||
| 711 | controls if any "@..." is removed from the end of the user |
||
| 712 | name. If not specified, the default is <code>true</code>.</p> |
||
| 713 | </td></tr><tr id="Attributes_JAAS Realm - org.apache.catalina.realm.JAASRealm_transportGuaranteeRedirectStatus"><td><code class="attributeName">transportGuaranteeRedirectStatus</code></td><td> |
||
| 714 | <p>The HTTP status code to use when the container needs to issue an HTTP |
||
| 715 | redirect to meet the requirements of a configured transport |
||
| 716 | guarantee. The provided status code is not validated. If not |
||
| 717 | specified, the default value of <code>302</code> is used.</p> |
||
| 718 | </td></tr><tr id="Attributes_JAAS Realm - org.apache.catalina.realm.JAASRealm_useContextClassLoader"><td><code class="attributeName">useContextClassLoader</code></td><td> |
||
| 719 | <p>Instructs JAASRealm to use the context class loader for loading the |
||
| 720 | user-specified <code>LoginModule</code> class and associated |
||
| 721 | <code>Principal</code> classes. The default value is <code>true</code>, |
||
| 722 | which is backwards-compatible with the way Tomcat 5 works. To load |
||
| 723 | classes using the container's classloader, specify |
||
| 724 | <code>false</code>.</p> |
||
| 725 | </td></tr><tr id="Attributes_JAAS Realm - org.apache.catalina.realm.JAASRealm_X509UsernameRetrieverClassName"><td><code class="attributeName">X509UsernameRetrieverClassName</code></td><td> |
||
| 726 | <p>When using X509 client certificates, this specifies the class name |
||
| 727 | that will be used to retrieve the user name from the certificate. |
||
| 728 | The class must implement the |
||
| 729 | <code>org.apache.catalina.realm.X509UsernameRetriever</code> |
||
| 730 | interface. The default is to use the certificate's SubjectDN |
||
| 731 | as the username.</p> |
||
| 732 | </td></tr></table> |
||
| 733 | |||
| 734 | <p>See the <a href="../realm-howto.html">Container-Managed Security |
||
| 735 | Guide</a> for more information on setting up container managed security |
||
| 736 | using the JAAS Realm component.</p> |
||
| 737 | |||
| 738 | </div></div> |
||
| 739 | |||
| 740 | |||
| 741 | <div class="subsection"><h4 id="Combined_Realm_-_org.apache.catalina.realm.CombinedRealm">Combined Realm - org.apache.catalina.realm.CombinedRealm</h4><div class="text"> |
||
| 742 | |||
| 743 | <p><strong>CombinedRealm</strong> is an implementation of the Tomcat |
||
| 744 | <code>Realm</code> interface that authenticates users through one or more |
||
| 745 | sub-Realms.</p> |
||
| 746 | |||
| 747 | <p>Using CombinedRealm gives the developer the ability to combine multiple |
||
| 748 | Realms of the same or different types. This can be used to authenticate |
||
| 749 | against different sources, provide fall back in case one Realm fails or for |
||
| 750 | any other purpose that requires multiple Realms.</p> |
||
| 751 | |||
| 752 | <p>Sub-realms are defined by nesting <code>Realm</code> elements inside the |
||
| 753 | <code>Realm</code> element that defines the CombinedRealm. Authentication |
||
| 754 | will be attempted against each <code>Realm</code> in the order they are |
||
| 755 | listed. Authentication against any Realm will be sufficient to authenticate |
||
| 756 | the user. The authenticated user, and their associated roles, will be taken |
||
| 757 | from the first Realm that successfully authenticates the user.</p> |
||
| 758 | |||
| 759 | <p>See the <a href="../realm-howto.html">Container-Managed Security |
||
| 760 | Guide</a> for more information on setting up container managed security |
||
| 761 | using the CombinedRealm component.</p> |
||
| 762 | |||
| 763 | <p>The CombinedRealm implementation supports the following additional |
||
| 764 | attributes.</p> |
||
| 765 | |||
| 766 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 767 | Attribute |
||
| 768 | </th><th style="width: 85%;"> |
||
| 769 | Description |
||
| 770 | </th></tr><tr id="Attributes_Combined Realm - org.apache.catalina.realm.CombinedRealm_allRolesMode"><td><code class="attributeName">allRolesMode</code></td><td> |
||
| 771 | <p>This attribute controls how the special role name <code>*</code> is |
||
| 772 | handled when processing authorization constraints in web.xml. By |
||
| 773 | default, the specification compliant value of <code>strict</code> is |
||
| 774 | used which means that the user must be assigned one of the roles defined |
||
| 775 | in web.xml. The alternative values are <code>authOnly</code> which means |
||
| 776 | that the user must be authenticated but no check is made for assigned |
||
| 777 | roles and <code>strictAuthOnly</code> which means that the user must be |
||
| 778 | authenticated and no check will be made for assigned roles unless roles |
||
| 779 | are defined in web.xml in which case the user must be assigned at least |
||
| 780 | one of those roles.</p> |
||
| 781 | </td></tr><tr id="Attributes_Combined Realm - org.apache.catalina.realm.CombinedRealm_transportGuaranteeRedirectStatus"><td><code class="attributeName">transportGuaranteeRedirectStatus</code></td><td> |
||
| 782 | <p>The HTTP status code to use when the container needs to issue an HTTP |
||
| 783 | redirect to meet the requirements of a configured transport |
||
| 784 | guarantee. The provided status code is not validated. If not |
||
| 785 | specified, the default value of <code>302</code> is used.</p> |
||
| 786 | </td></tr></table> |
||
| 787 | </div></div> |
||
| 788 | |||
| 789 | |||
| 790 | <div class="subsection"><h4 id="LockOut_Realm_-_org.apache.catalina.realm.LockOutRealm">LockOut Realm - org.apache.catalina.realm.LockOutRealm</h4><div class="text"> |
||
| 791 | |||
| 792 | <p><strong>LockOutRealm</strong> is an implementation of the Tomcat |
||
| 793 | <code>Realm</code> interface that extends the CombinedRealm to provide lock |
||
| 794 | out functionality to provide a user lock out mechanism if there are too many |
||
| 795 | failed authentication attempts in a given period of time.</p> |
||
| 796 | |||
| 797 | <p>To ensure correct operation, there is a reasonable degree of |
||
| 798 | synchronization in this Realm.</p> |
||
| 799 | |||
| 800 | <p>This Realm does not require modification to the underlying Realms or the |
||
| 801 | associated user storage mechanisms. It achieves this by recording all failed |
||
| 802 | logins, including those for users that do not exist. To prevent a DOS by |
||
| 803 | deliberating making requests with invalid users (and hence causing this |
||
| 804 | cache to grow) the size of the list of users that have failed authentication |
||
| 805 | is limited.</p> |
||
| 806 | |||
| 807 | <p>Sub-realms are defined by nesting <code>Realm</code> elements inside the |
||
| 808 | <code>Realm</code> element that defines the LockOutRealm. Authentication |
||
| 809 | will be attempted against each <code>Realm</code> in the order they are |
||
| 810 | listed. Authentication against any Realm will be sufficient to authenticate |
||
| 811 | the user.</p> |
||
| 812 | |||
| 813 | <p>The LockOutRealm implementation supports the following additional |
||
| 814 | attributes.</p> |
||
| 815 | |||
| 816 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 817 | Attribute |
||
| 818 | </th><th style="width: 85%;"> |
||
| 819 | Description |
||
| 820 | </th></tr><tr id="Attributes_LockOut Realm - org.apache.catalina.realm.LockOutRealm_allRolesMode"><td><code class="attributeName">allRolesMode</code></td><td> |
||
| 821 | <p>This attribute controls how the special role name <code>*</code> is |
||
| 822 | handled when processing authorization constraints in web.xml. By |
||
| 823 | default, the specification compliant value of <code>strict</code> is |
||
| 824 | used which means that the user must be assigned one of the roles defined |
||
| 825 | in web.xml. The alternative values are <code>authOnly</code> which means |
||
| 826 | that the user must be authenticated but no check is made for assigned |
||
| 827 | roles and <code>strictAuthOnly</code> which means that the user must be |
||
| 828 | authenticated and no check will be made for assigned roles unless roles |
||
| 829 | are defined in web.xml in which case the user must be assigned at least |
||
| 830 | one of those roles.</p> |
||
| 831 | </td></tr><tr id="Attributes_LockOut Realm - org.apache.catalina.realm.LockOutRealm_cacheRemovalWarningTime"><td><code class="attributeName">cacheRemovalWarningTime</code></td><td> |
||
| 832 | <p>If a failed user is removed from the cache because the cache is too |
||
| 833 | big before it has been in the cache for at least this period of time (in |
||
| 834 | seconds) a warning message will be logged. Defaults to 3600 (1 hour).</p> |
||
| 835 | </td></tr><tr id="Attributes_LockOut Realm - org.apache.catalina.realm.LockOutRealm_cacheSize"><td><code class="attributeName">cacheSize</code></td><td> |
||
| 836 | <p>Number of users that have failed authentication to keep in cache. Over |
||
| 837 | time the cache will grow to this size and may not shrink. Defaults to |
||
| 838 | 1000.</p> |
||
| 839 | </td></tr><tr id="Attributes_LockOut Realm - org.apache.catalina.realm.LockOutRealm_failureCount"><td><code class="attributeName">failureCount</code></td><td> |
||
| 840 | <p>The number of times in a row a user has to fail authentication to be |
||
| 841 | locked out. Defaults to 5.</p> |
||
| 842 | </td></tr><tr id="Attributes_LockOut Realm - org.apache.catalina.realm.LockOutRealm_lockOutTime"><td><code class="attributeName">lockOutTime</code></td><td> |
||
| 843 | <p>The time (in seconds) a user is locked out for after too many |
||
| 844 | authentication failures. Defaults to 300 (5 minutes). Further |
||
| 845 | authentication failures during the lock out time will cause the lock out |
||
| 846 | timer to reset to zero, effectively extending the lock out time. Valid |
||
| 847 | authentication attempts during the lock out period will not succeed but |
||
| 848 | will also not reset the lock out time.</p> |
||
| 849 | </td></tr><tr id="Attributes_LockOut Realm - org.apache.catalina.realm.LockOutRealm_transportGuaranteeRedirectStatus"><td><code class="attributeName">transportGuaranteeRedirectStatus</code></td><td> |
||
| 850 | <p>The HTTP status code to use when the container needs to issue an HTTP |
||
| 851 | redirect to meet the requirements of a configured transport |
||
| 852 | guarantee. The provided status code is not validated. If not |
||
| 853 | specified, the default value of <code>302</code> is used.</p> |
||
| 854 | </td></tr></table> |
||
| 855 | |||
| 856 | <p>See the <a href="../realm-howto.html">Container-Managed Security |
||
| 857 | Guide</a> for more information on setting up container managed security |
||
| 858 | using the LockOutRealm component.</p> |
||
| 859 | |||
| 860 | </div></div> |
||
| 861 | |||
| 862 | <div class="subsection"><h4 id="Null_Realm_-_org.apache.catalina.realm.NullRealm">Null Realm - org.apache.catalina.realm.NullRealm</h4><div class="text"> |
||
| 863 | |||
| 864 | <p><strong>NullRealm</strong> is a minimal implementation of the Tomcat |
||
| 865 | <code>Realm</code> interface that always returns null when an attempt is |
||
| 866 | made to validate a user name and associated credentials. It is intended to |
||
| 867 | be used as a default Realm implementation when no other Realm is |
||
| 868 | specified.</p> |
||
| 869 | |||
| 870 | <p>The NullRealm implementation supports the following additional |
||
| 871 | attributes.</p> |
||
| 872 | |||
| 873 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 874 | Attribute |
||
| 875 | </th><th style="width: 85%;"> |
||
| 876 | Description |
||
| 877 | </th></tr><tr id="Attributes_Null Realm - org.apache.catalina.realm.NullRealm_transportGuaranteeRedirectStatus"><td><code class="attributeName">transportGuaranteeRedirectStatus</code></td><td> |
||
| 878 | <p>The HTTP status code to use when the container needs to issue an HTTP |
||
| 879 | redirect to meet the requirements of a configured transport |
||
| 880 | guarantee. The provided status code is not validated. If not |
||
| 881 | specified, the default value of <code>302</code> is used.</p> |
||
| 882 | </td></tr></table> |
||
| 883 | |||
| 884 | </div></div> |
||
| 885 | |||
| 886 | <div class="subsection"><h4 id="Authenticated_User_Realm_-_org.apache.catalina.realm.AuthenticatedUserRealm">Authenticated User Realm - org.apache.catalina.realm.AuthenticatedUserRealm</h4><div class="text"> |
||
| 887 | |||
| 888 | <p><strong>AuthenticatedUserRealm</strong> is intended for use with |
||
| 889 | Authenticator implementations (SSLAuthenticator, SpnegoAuthenticator) that |
||
| 890 | authenticate the user as well as obtain the user credentials. An |
||
| 891 | authenticated Principal is always created from the user name presented to |
||
| 892 | without further validation.</p> |
||
| 893 | <p><strong>Note:</strong> It is unsafe to use this Realm with Authenticator |
||
| 894 | implementations that do not validate the provided credentials.</p> |
||
| 895 | |||
| 896 | <p>The AuthenticatedUserRealm implementation supports the following |
||
| 897 | additional attributes.</p> |
||
| 898 | |||
| 899 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 900 | Attribute |
||
| 901 | </th><th style="width: 85%;"> |
||
| 902 | Description |
||
| 903 | </th></tr><tr id="Attributes_Authenticated User Realm - org.apache.catalina.realm.AuthenticatedUserRealm_transportGuaranteeRedirectStatus"><td><code class="attributeName">transportGuaranteeRedirectStatus</code></td><td> |
||
| 904 | <p>The HTTP status code to use when the container needs to issue an HTTP |
||
| 905 | redirect to meet the requirements of a configured transport |
||
| 906 | guarantee. The provided status code is not validated. If not |
||
| 907 | specified, the default value of <code>302</code> is used.</p> |
||
| 908 | </td></tr></table> |
||
| 909 | |||
| 910 | </div></div> |
||
| 911 | |||
| 912 | <div class="subsection"><h4 id="JDBC_Database_Realm_-_org.apache.catalina.realm.JDBCRealm">JDBC Database Realm - org.apache.catalina.realm.JDBCRealm</h4><div class="text"> |
||
| 913 | |||
| 914 | <p><strong>The JDBC Database Realm has been deprecated and will be removed |
||
| 915 | in Tomcat 10 onwards. Use the DataSourceRealm instead.</strong></p> |
||
| 916 | |||
| 917 | <p>The <strong>JDBC Database Realm</strong> connects Tomcat to |
||
| 918 | a relational database, accessed through an appropriate JDBC driver, |
||
| 919 | to perform lookups of usernames, passwords, and their associated |
||
| 920 | roles. Because the lookup is done each time that it is required, |
||
| 921 | changes to the database will be immediately reflected in the |
||
| 922 | information used to authenticate new logins.</p> |
||
| 923 | |||
| 924 | <p>Note: The <strong>JDBC Database Realm</strong> uses a single connection |
||
| 925 | to the database with synchronisation to prevenbt concurrent usage. It is not |
||
| 926 | recommended for production usage. Use the DataSource Realm instaead.</p> |
||
| 927 | |||
| 928 | <p>A rich set of additional attributes lets you configure the required |
||
| 929 | connection to the underlying database, as well as the table and |
||
| 930 | column names used to retrieve the required information:</p> |
||
| 931 | |||
| 932 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 933 | Attribute |
||
| 934 | </th><th style="width: 85%;"> |
||
| 935 | Description |
||
| 936 | </th></tr><tr id="Attributes_JDBC Database Realm - org.apache.catalina.realm.JDBCRealm_allRolesMode"><td><code class="attributeName">allRolesMode</code></td><td> |
||
| 937 | <p>This attribute controls how the special role name <code>*</code> is |
||
| 938 | handled when processing authorization constraints in web.xml. By |
||
| 939 | default, the specification compliant value of <code>strict</code> is |
||
| 940 | used which means that the user must be assigned one of the roles defined |
||
| 941 | in web.xml. The alternative values are <code>authOnly</code> which means |
||
| 942 | that the user must be authenticated but no check is made for assigned |
||
| 943 | roles and <code>strictAuthOnly</code> which means that the user must be |
||
| 944 | authenticated and no check will be made for assigned roles unless roles |
||
| 945 | are defined in web.xml in which case the user must be assigned at least |
||
| 946 | one of those roles.</p> |
||
| 947 | <p>When this attribute has the value of <code>authOnly</code> or |
||
| 948 | <code>strictAuthOnly</code>, the <strong>roleNameCol</strong> and |
||
| 949 | <strong>userRoleTable</strong> attributes become optional. If those two |
||
| 950 | attributes are omitted, the user's roles will not be loaded by this |
||
| 951 | Realm.</p> |
||
| 952 | </td></tr><tr id="Attributes_JDBC Database Realm - org.apache.catalina.realm.JDBCRealm_connectionName"><td><strong><code class="attributeName">connectionName</code></strong></td><td> |
||
| 953 | <p>The database username to use when establishing the JDBC |
||
| 954 | connection.</p> |
||
| 955 | </td></tr><tr id="Attributes_JDBC Database Realm - org.apache.catalina.realm.JDBCRealm_connectionPassword"><td><strong><code class="attributeName">connectionPassword</code></strong></td><td> |
||
| 956 | <p>The database password to use when establishing the JDBC |
||
| 957 | connection.</p> |
||
| 958 | </td></tr><tr id="Attributes_JDBC Database Realm - org.apache.catalina.realm.JDBCRealm_connectionURL"><td><strong><code class="attributeName">connectionURL</code></strong></td><td> |
||
| 959 | <p>The connection URL to be passed to the JDBC driver when |
||
| 960 | establishing a database connection.</p> |
||
| 961 | </td></tr><tr id="Attributes_JDBC Database Realm - org.apache.catalina.realm.JDBCRealm_driverName"><td><strong><code class="attributeName">driverName</code></strong></td><td> |
||
| 962 | <p>Fully qualified Java class name of the JDBC driver to be |
||
| 963 | used to connect to the authentication database.</p> |
||
| 964 | </td></tr><tr id="Attributes_JDBC Database Realm - org.apache.catalina.realm.JDBCRealm_roleNameCol"><td><code class="attributeName">roleNameCol</code></td><td> |
||
| 965 | <p>Name of the column, in the "user roles" table, which contains |
||
| 966 | a role name assigned to the corresponding user.</p> |
||
| 967 | <p>This attribute is <strong>required</strong> in majority of |
||
| 968 | configurations. See <strong>allRolesMode</strong> attribute for |
||
| 969 | a rare case when it can be omitted.</p> |
||
| 970 | </td></tr><tr id="Attributes_JDBC Database Realm - org.apache.catalina.realm.JDBCRealm_stripRealmForGss"><td><code class="attributeName">stripRealmForGss</code></td><td> |
||
| 971 | <p>When processing users authenticated via the GSS-API, this attribute |
||
| 972 | controls if any "@..." is removed from the end of the user |
||
| 973 | name. If not specified, the default is <code>true</code>.</p> |
||
| 974 | </td></tr><tr id="Attributes_JDBC Database Realm - org.apache.catalina.realm.JDBCRealm_transportGuaranteeRedirectStatus"><td><code class="attributeName">transportGuaranteeRedirectStatus</code></td><td> |
||
| 975 | <p>The HTTP status code to use when the container needs to issue an HTTP |
||
| 976 | redirect to meet the requirements of a configured transport |
||
| 977 | guarantee. The provided status code is not validated. If not |
||
| 978 | specified, the default value of <code>302</code> is used.</p> |
||
| 979 | </td></tr><tr id="Attributes_JDBC Database Realm - org.apache.catalina.realm.JDBCRealm_userCredCol"><td><strong><code class="attributeName">userCredCol</code></strong></td><td> |
||
| 980 | <p>Name of the column, in the "users" table, which contains |
||
| 981 | the user's credentials (i.e. password). If a |
||
| 982 | <code>CredentialHandler</code> is specified, this component |
||
| 983 | will assume that the passwords have been encoded with the |
||
| 984 | specified algorithm. Otherwise, they will be assumed to be |
||
| 985 | in clear text.</p> |
||
| 986 | </td></tr><tr id="Attributes_JDBC Database Realm - org.apache.catalina.realm.JDBCRealm_userNameCol"><td><strong><code class="attributeName">userNameCol</code></strong></td><td> |
||
| 987 | <p>Name of the column, in the "users" and "user roles" table, |
||
| 988 | that contains the user's username.</p> |
||
| 989 | </td></tr><tr id="Attributes_JDBC Database Realm - org.apache.catalina.realm.JDBCRealm_userRoleTable"><td><code class="attributeName">userRoleTable</code></td><td> |
||
| 990 | <p>Name of the "user roles" table, which must contain columns |
||
| 991 | named by the <code>userNameCol</code> and <code>roleNameCol</code> |
||
| 992 | attributes.</p> |
||
| 993 | <p>This attribute is <strong>required</strong> in majority of |
||
| 994 | configurations. See <strong>allRolesMode</strong> attribute for |
||
| 995 | a rare case when it can be omitted.</p> |
||
| 996 | </td></tr><tr id="Attributes_JDBC Database Realm - org.apache.catalina.realm.JDBCRealm_userTable"><td><strong><code class="attributeName">userTable</code></strong></td><td> |
||
| 997 | <p>Name of the "users" table, which must contain columns named |
||
| 998 | by the <code>userNameCol</code> and <code>userCredCol</code> |
||
| 999 | attributes.</p> |
||
| 1000 | </td></tr><tr id="Attributes_JDBC Database Realm - org.apache.catalina.realm.JDBCRealm_X509UsernameRetrieverClassName"><td><code class="attributeName">X509UsernameRetrieverClassName</code></td><td> |
||
| 1001 | <p>When using X509 client certificates, this specifies the class name |
||
| 1002 | that will be used to retrieve the user name from the certificate. |
||
| 1003 | The class must implement the |
||
| 1004 | <code>org.apache.catalina.realm.X509UsernameRetriever</code> |
||
| 1005 | interface. The default is to use the certificate's SubjectDN |
||
| 1006 | as the username.</p> |
||
| 1007 | </td></tr></table> |
||
| 1008 | |||
| 1009 | <p>See the <a href="../realm-howto.html">Container-Managed Security Guide</a> for more |
||
| 1010 | information on setting up container managed security using the |
||
| 1011 | JDBC Database Realm component.</p> |
||
| 1012 | |||
| 1013 | </div></div> |
||
| 1014 | |||
| 1015 | </div><h3 id="Nested_Components">Nested Components</h3><div class="text"> |
||
| 1016 | |||
| 1017 | <p>You can nest the following components by nesting the corresponding element |
||
| 1018 | inside your <strong>Realm</strong> element:</p> |
||
| 1019 | <ul> |
||
| 1020 | <li><strong>CombinedRealm Implementation</strong> - If you are using the |
||
| 1021 | <em>CombinedRealm Implementation</em> or a Realm |
||
| 1022 | that extends the CombinedRealm, e.g. the LockOutRealm, one or more |
||
| 1023 | <strong><Realm></strong> elements may be nested inside it.</li> |
||
| 1024 | <li><a href="credentialhandler.html"><strong>CredentialHandler</strong></a> - |
||
| 1025 | You may nest at most one instance of this element inside a Realm. This |
||
| 1026 | configures the credential handler that will be used to validate provided |
||
| 1027 | credentials with those stored by the Realm. If not specified a default |
||
| 1028 | <em>MessageDigestCredentialHandler</em> will be configured.</li> |
||
| 1029 | </ul> |
||
| 1030 | |||
| 1031 | </div><h3 id="Special_Features">Special Features</h3><div class="text"> |
||
| 1032 | |||
| 1033 | <p>See <a href="host.html">Single Sign On</a> for information about |
||
| 1034 | configuring Single Sign On support for a virtual host.</p> |
||
| 1035 | |||
| 1036 | </div></div></div></div></div><footer><div id="footer"> |
||
| 1037 | Copyright © 1999-2025, The Apache Software Foundation |
||
| 1038 | <br> |
||
| 1039 | Apache Tomcat, Tomcat, Apache, the Apache Tomcat logo and the Apache logo |
||
| 1040 | are either registered trademarks or trademarks of the Apache Software |
||
| 1041 | Foundation. |
||
| 1042 | </div></footer></div></body></html> |