| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <!DOCTYPE document [ |
| <!ENTITY project SYSTEM "project.xml"> |
| ]> |
| <document url="realm.html"> |
| |
| &project; |
| |
| <properties> |
| <author email="craigmcc@apache.org">Craig R. McClanahan</author> |
| <title>The Realm Component</title> |
| </properties> |
| |
| <body> |
| |
| <section name="Table of Contents"> |
| <toc/> |
| </section> |
| |
| <section name="Introduction"> |
| |
| <p>A <strong>Realm</strong> element represents a "database" of usernames, |
| passwords, and <em>roles</em> (similar to Unix <em>groups</em>) 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 |
| <em>Container Managed Security</em> as described in the Servlet |
| Specification.</p> |
| |
| <p>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.</p> |
| |
| <p>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>. |
| </p> |
| |
| <p><em>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.</em></p> |
| |
| </section> |
| |
| |
| <section name="Attributes"> |
| |
| <subsection name="Common Attributes"> |
| |
| <p>All implementations of <strong>Realm</strong> |
| support the following attributes:</p> |
| |
| <attributes> |
| |
| <attribute name="className" required="true"> |
| <p>Java class name of the implementation to use. This class must |
| implement the <code>org.apache.catalina.Realm</code> interface.</p> |
| </attribute> |
| |
| </attributes> |
| |
| <p>Unlike most Catalina components, there are several standard |
| <strong>Realm</strong> implementations available. As a result, |
| the <code>className</code> attribute MUST be used to select the |
| implementation you wish to use.</p> |
| |
| </subsection> |
| |
| |
| <subsection name="JDBC Database Realm - org.apache.catalina.realm.JDBCRealm"> |
| |
| <p>The <strong>JDBC Database Realm</strong> 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.</p> |
| |
| <p>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:</p> |
| |
| <attributes> |
| |
| <attribute name="allRolesMode" required="false"> |
| <p>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.</p> |
| <p>When this attribute has the value of <code>authOnly</code> or |
| <code>strictAuthOnly</code>, the <strong>roleNameCol</strong> and |
| <strong>userRoleTable</strong> attributes become optional. If those two |
| attributes are omitted, the user's roles will not be loaded by this |
| Realm.</p> |
| </attribute> |
| |
| <attribute name="connectionName" required="true"> |
| <p>The database username to use when establishing the JDBC |
| connection.</p> |
| </attribute> |
| |
| <attribute name="connectionPassword" required="true"> |
| <p>The database password to use when establishing the JDBC |
| connection.</p> |
| </attribute> |
| |
| <attribute name="connectionURL" required="true"> |
| <p>The connection URL to be passed to the JDBC driver when |
| establishing a database connection.</p> |
| </attribute> |
| |
| <attribute name="digest" required="false"> |
| <p>The name of the <code>MessageDigest</code> algorithm used |
| to encode user passwords stored in the database. If not specified, |
| user passwords are assumed to be stored in clear-text.</p> |
| <p>This attribute is deprecated. Set the algorithm on a nested |
| <strong>CredentialHandler</strong> element instead.</p> |
| </attribute> |
| |
| <attribute name="digestEncoding" required="false"> |
| <p>The charset for encoding digests. If not specified, the platform |
| default will be used.</p> |
| <p>This attribute is deprecated. Set the encoding on a nested |
| <strong>CredentialHandler</strong> element instead.</p> |
| </attribute> |
| |
| <attribute name="driverName" required="true"> |
| <p>Fully qualified Java class name of the JDBC driver to be |
| used to connect to the authentication database.</p> |
| </attribute> |
| |
| <attribute name="roleNameCol" required="false"> |
| <p>Name of the column, in the "user roles" table, which contains |
| a role name assigned to the corresponding user.</p> |
| <p>This attribute is <strong>required</strong> in majority of |
| configurations. See <strong>allRolesMode</strong> attribute for |
| a rare case when it can be omitted.</p> |
| </attribute> |
| |
| <attribute name="stripRealmForGss" required="false"> |
| <p>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>.</p> |
| </attribute> |
| |
| <attribute name="transportGuaranteeRedirectStatus" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="userCredCol" required="true"> |
| <p>Name of the column, in the "users" table, which contains |
| the user's credentials (i.e. password). If a value for the |
| <code>digest</code> attribute is specified, this component |
| will assume that the passwords have been encoded with the |
| specified algorithm. Otherwise, they will be assumed to be |
| in clear text.</p> |
| </attribute> |
| |
| <attribute name="userNameCol" required="true"> |
| <p>Name of the column, in the "users" and "user roles" table, |
| that contains the user's username.</p> |
| </attribute> |
| |
| <attribute name="userRoleTable" required="false"> |
| <p>Name of the "user roles" table, which must contain columns |
| named by the <code>userNameCol</code> and <code>roleNameCol</code> |
| attributes.</p> |
| <p>This attribute is <strong>required</strong> in majority of |
| configurations. See <strong>allRolesMode</strong> attribute for |
| a rare case when it can be omitted.</p> |
| </attribute> |
| |
| <attribute name="userTable" required="true"> |
| <p>Name of the "users" table, which must contain columns named |
| by the <code>userNameCol</code> and <code>userCredCol</code> |
| attributes.</p> |
| </attribute> |
| |
| <attribute name="X509UsernameRetrieverClassName" required="false"> |
| <p>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.</p> |
| </attribute> |
| </attributes> |
| |
| <p>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.</p> |
| |
| </subsection> |
| |
| |
| <subsection name="DataSource Database Realm - org.apache.catalina.realm.DataSourceRealm"> |
| |
| <p>The <strong>DataSource Database Realm</strong> 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.</p> |
| |
| <p>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.</p> |
| |
| <p>The DataSource Database Realm supports simultaneous realm based |
| authentications and allows the underlying JDBC DataSource to |
| handle optimizations like database connection pooling.</p> |
| |
| <p>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:</p> |
| |
| <attributes> |
| |
| <attribute name="allRolesMode" required="false"> |
| <p>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.</p> |
| <p>When this attribute has the value of <code>authOnly</code> or |
| <code>strictAuthOnly</code>, the <strong>roleNameCol</strong> and |
| <strong>userRoleTable</strong> attributes become optional. If those two |
| attributes are omitted, the user's roles will not be loaded by this |
| Realm.</p> |
| </attribute> |
| |
| <attribute name="dataSourceName" required="true"> |
| <p>The name of the JNDI JDBC DataSource for this Realm.</p> |
| </attribute> |
| |
| <attribute name="digest" required="false"> |
| <p>The name of the <code>MessageDigest</code> algorithm used |
| to encode user passwords stored in the database. If not specified, |
| user passwords are assumed to be stored in clear-text.</p> |
| <p>This attribute is deprecated. Set the algorithm on a nested |
| <strong>CredentialHandler</strong> element instead.</p> |
| </attribute> |
| |
| <attribute name="localDataSource" required="false"> |
| <p>When the realm is nested inside a Context element, this allows the |
| realm to use a DataSource defined for the Context rather than a global |
| DataSource. If not specified, the default is <code>false</code>: use a |
| global DataSource.</p> |
| </attribute> |
| |
| <attribute name="roleNameCol" required="false"> |
| <p>Name of the column, in the "user roles" table, which contains |
| a role name assigned to the corresponding user.</p> |
| <p>This attribute is <strong>required</strong> in majority of |
| configurations. See <strong>allRolesMode</strong> attribute for |
| a rare case when it can be omitted.</p> |
| </attribute> |
| |
| <attribute name="transportGuaranteeRedirectStatus" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="stripRealmForGss" required="false"> |
| <p>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>.</p> |
| </attribute> |
| |
| <attribute name="userCredCol" required="true"> |
| <p>Name of the column, in the "users" table, which contains |
| the user's credentials (i.e. password). If a value for the |
| <code>digest</code> attribute is specified, this component |
| will assume that the passwords have been encoded with the |
| specified algorithm. Otherwise, they will be assumed to be |
| in clear text.</p> |
| </attribute> |
| |
| <attribute name="userNameCol" required="true"> |
| <p>Name of the column, in the "users" and "user roles" table, |
| that contains the user's username.</p> |
| </attribute> |
| |
| <attribute name="userRoleTable" required="false"> |
| <p>Name of the "user roles" table, which must contain columns |
| named by the <code>userNameCol</code> and <code>roleNameCol</code> |
| attributes.</p> |
| <p>This attribute is <strong>required</strong> in majority of |
| configurations. See <strong>allRolesMode</strong> attribute for |
| a rare case when it can be omitted.</p> |
| </attribute> |
| |
| <attribute name="userTable" required="true"> |
| <p>Name of the "users" table, which must contain columns named |
| by the <code>userNameCol</code> and <code>userCredCol</code> |
| attributes.</p> |
| </attribute> |
| |
| <attribute name="X509UsernameRetrieverClassName" required="false"> |
| <p>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.</p> |
| </attribute> |
| </attributes> |
| |
| <p>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.</p> |
| |
| </subsection> |
| |
| |
| <subsection name="JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm"> |
| |
| <p>The <strong>JNDI Directory Realm</strong> 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.</p> |
| |
| |
| <p>The directory realm supports a variety of approaches to using |
| LDAP for authentication:</p> |
| |
| <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> |
| |
| <p> 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:</p> |
| |
| <attributes> |
| |
| <attribute name="adCompat" required="false"> |
| <p>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".</p> |
| </attribute> |
| |
| <attribute name="allRolesMode" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="alternateURL" required="false"> |
| <p>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>.</p> |
| </attribute> |
| |
| <attribute name="authentication" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="cipherSuites" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="commonRole" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="connectionName" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="connectionPassword" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="connectionTimeout" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="connectionURL" required="true"> |
| <p>The connection URL to be passed to the JNDI driver when |
| establishing a connection to the directory.</p> |
| </attribute> |
| |
| <attribute name="contextFactory" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="derefAliases" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="digest" required="false"> |
| <p>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</p> |
| <p>This attribute is deprecated. Set the algorithm on a nested |
| <strong>CredentialHandler</strong> element instead.</p> |
| </attribute> |
| |
| <attribute name="hostnameVerifierClassName" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="protocol" required="false"> |
| <p>A string specifying the security protocol to use. If not given |
| the providers default is used.</p> |
| </attribute> |
| |
| <attribute name="referrals" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="roleBase" required="false"> |
| <p>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>).</p> |
| </attribute> |
| |
| <attribute name="roleName" required="false"> |
| <p>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.</p> |
| <p>If <code>roleName</code> is not specified a role |
| search does not take place, and roles are taken only from the |
| user's entry.</p> |
| </attribute> |
| |
| <attribute name="roleNested" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="roleSearch" required="false"> |
| <p>The LDAP filter expression used for performing role |
| searches.</p> |
| |
| <p>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.</p> |
| |
| <p>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.</p> |
| |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="roleSearchAsUser" required="false"> |
| <p> 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.</p> |
| </attribute> |
| |
| <attribute name="roleSubtree" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="sizeLimit" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="spnegoDelegationQop" required="false"> |
| <p>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.</p> |
| <p>The default value is <code>auth-conf</code>.</p> |
| </attribute> |
| |
| <attribute name="sslProtocol" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="sslSocketFactory" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="stripRealmForGss" required="false"> |
| <p>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>.</p> |
| </attribute> |
| |
| <attribute name="timeLimit" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="transportGuaranteeRedirectStatus" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="useDelegatedCredential" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="userBase" required="false"> |
| <p>The base element for user searches performed using the |
| <code>userSearch</code> expression. Not used if you are using |
| the <code>userPattern</code> expression.</p> |
| </attribute> |
| |
| <attribute name="userPassword" required="false"> |
| <p>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 |
| <strong>not</strong> 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.</p> |
| </attribute> |
| |
| <attribute name="userPattern" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="userRoleName" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="userRoleAttribute" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="userSearch" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="userSearchAsUser" required="false"> |
| <p> 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.</p> |
| </attribute> |
| |
| <attribute name="userSubtree" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="useStartTls" required="false"> |
| <p>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>. |
| </p> |
| </attribute> |
| |
| <attribute name="X509UsernameRetrieverClassName" required="false"> |
| <p>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.</p> |
| </attribute> |
| </attributes> |
| |
| <p>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.</p> |
| |
| </subsection> |
| |
| |
| <subsection name="UserDatabase Realm - org.apache.catalina.realm.UserDatabaseRealm"> |
| |
| <p>The <strong>UserDatabase Realm</strong> is a Realm implementation |
| that is based on a UserDatabase resource made available through the global |
| JNDI resources configured for this Tomcat instance.</p> |
| |
| <p>The UserDatabase Realm implementation supports the following |
| additional attributes:</p> |
| |
| <attributes> |
| |
| <attribute name="allRolesMode" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="resourceName" required="true"> |
| <p>The name of the global <code>UserDatabase</code> resource |
| that this realm will use for user, password and role information.</p> |
| </attribute> |
| |
| <attribute name="transportGuaranteeRedirectStatus" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="X509UsernameRetrieverClassName" required="false"> |
| <p>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.</p> |
| </attribute> |
| </attributes> |
| |
| <p>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.</p> |
| |
| </subsection> |
| |
| |
| <subsection name="Memory Based Realm - org.apache.catalina.realm.MemoryRealm"> |
| |
| <p>The <strong>Memory Based Realm</strong> 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.</p> |
| |
| <p>The Memory Based Realm implementation supports the following |
| additional attributes:</p> |
| |
| <attributes> |
| |
| <attribute name="allRolesMode" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="digest" required="false"> |
| <p>The digest algorithm used to store passwords in non-plaintext |
| formats. Valid values are those accepted for the algorithm name by the |
| <code>java.security.MessageDigest</code> class. If not specified, |
| passwords are stored in clear text.</p> |
| <p>This attribute is deprecated. Set the algorithm on a nested |
| <strong>CredentialHandler</strong> element instead.</p> |
| </attribute> |
| |
| <attribute name="pathname" required="false"> |
| <p>URL, absolute path or relative path (to $CATALINA_BASE) for the XML |
| file containing our user information. See below for details on the |
| XML element format required. If no pathname is specified, the |
| default value is <code>conf/tomcat-users.xml</code>.</p> |
| </attribute> |
| |
| <attribute name="stripRealmForGss" required="false"> |
| <p>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>.</p> |
| </attribute> |
| |
| <attribute name="transportGuaranteeRedirectStatus" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="X509UsernameRetrieverClassName" required="false"> |
| <p>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.</p> |
| </attribute> |
| </attributes> |
| |
| <p>The XML document referenced by the <code>pathname</code> attribute must |
| conform to the following requirements:</p> |
| <ul> |
| <li>The root (outer) element must be <code><tomcat-users></code>. |
| </li> |
| <li>Each authorized user must be represented by a single XML element |
| <code><user></code>, nested inside the root element.</li> |
| <li>Each <code><user></code> element must have the following |
| attributes: |
| <ul> |
| <li><strong>username</strong> - Username of this user (must be unique |
| within this file).<br/> |
| For compatibility, it is allowed to use <strong>name</strong> as an |
| alternative name for this attribute.</li> |
| <li><strong>password</strong> - Password of this user (in |
| clear text).</li> |
| <li><strong>roles</strong> - Comma-delimited list of the role names |
| assigned to this user.</li> |
| </ul></li> |
| </ul> |
| |
| <p>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.</p> |
| |
| </subsection> |
| |
| |
| <subsection name="JAAS Realm - org.apache.catalina.realm.JAASRealm"> |
| |
| <p><strong>JAASRealm</strong> is an implementation of the Tomcat |
| <code>Realm</code> interface that authenticates users through the Java |
| Authentication & Authorization Service (JAAS) framework which is now |
| provided as part of the standard J2SE API.</p> |
| |
| <p>Using JAASRealm gives the developer the ability to combine practically |
| any conceivable security realm with Tomcat's CMA.</p> |
| |
| <p>JAASRealm is prototype for Tomcat of the JAAS-based J2EE authentication |
| framework for J2EE v1.4, based on the <a |
| href="http://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.</p> |
| |
| <p>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.</p> |
| |
| <p>The JAAS Realm implementation supports the following additional |
| attributes:</p> |
| |
| <attributes> |
| |
| <attribute name="allRolesMode" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="appName" required="true"> |
| <p>The name of the application as configured in your login configuration |
| file |
| (<a href="http://docs.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/LoginConfigFile.html">JAAS LoginConfig</a>).</p> |
| </attribute> |
| |
| <attribute name="userClassNames" required="true"> |
| <p>A comma-separated list of the names of the classes that you have made |
| for your user <code>Principals</code>.</p> |
| </attribute> |
| |
| <attribute name="configFile" required="false"> |
| <p>The name of a JAAS configuration file to use with this Realm. It will |
| be searched for using <code>ClassLoader#getResource(String)</code> so it |
| is possible for the configuration to be bundled within a web |
| application. If not specified, the default JVM global JAAS configuration |
| will be used.</p> |
| </attribute> |
| |
| <attribute name="roleClassNames" required="false"> |
| <p>A comma-separated list of the names of the classes that you have made |
| for your role <code>Principals</code>.</p> |
| </attribute> |
| |
| <attribute name="stripRealmForGss" required="false"> |
| <p>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>.</p> |
| </attribute> |
| |
| <attribute name="transportGuaranteeRedirectStatus" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="useContextClassLoader" required="false"> |
| <p>Instructs JAASRealm to use the context class loader for loading the |
| user-specified <code>LoginModule</code> class and associated |
| <code>Principal</code> classes. The default value is <code>true</code>, |
| which is backwards-compatible with the way Tomcat 5 works. To load |
| classes using the container's classloader, specify |
| <code>false</code>.</p> |
| </attribute> |
| |
| <attribute name="X509UsernameRetrieverClassName" required="false"> |
| <p>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.</p> |
| </attribute> |
| </attributes> |
| |
| <p>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.</p> |
| |
| </subsection> |
| |
| |
| <subsection name="Combined Realm - org.apache.catalina.realm.CombinedRealm"> |
| |
| <p><strong>CombinedRealm</strong> is an implementation of the Tomcat |
| <code>Realm</code> interface that authenticates users through one or more |
| sub-Realms.</p> |
| |
| <p>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.</p> |
| |
| <p>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.</p> |
| |
| <p>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.</p> |
| |
| <p>The CombinedRealm implementation supports the following additional |
| attributes.</p> |
| |
| <attributes> |
| |
| <attribute name="allRolesMode" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="transportGuaranteeRedirectStatus" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| </attributes> |
| </subsection> |
| |
| |
| <subsection name="LockOut Realm - org.apache.catalina.realm.LockOutRealm"> |
| |
| <p><strong>LockOutRealm</strong> 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.</p> |
| |
| <p>To ensure correct operation, there is a reasonable degree of |
| synchronization in this Realm.</p> |
| |
| <p>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.</p> |
| |
| <p>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.</p> |
| |
| <p>The LockOutRealm implementation supports the following additional |
| attributes.</p> |
| |
| <attributes> |
| <attribute name="allRolesMode" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| <attribute name="cacheRemovalWarningTime" required="false"> |
| <p>If a failed user is removed from the cache because the cache is too |
| big before it has been in the cache for at least this period of time (in |
| seconds) a warning message will be logged. Defaults to 3600 (1 hour).</p> |
| </attribute> |
| |
| <attribute name="cacheSize" required="false"> |
| <p>Number of users that have failed authentication to keep in cache. Over |
| time the cache will grow to this size and may not shrink. Defaults to |
| 1000.</p> |
| </attribute> |
| |
| <attribute name="failureCount" required="false"> |
| <p>The number of times in a row a user has to fail authentication to be |
| locked out. Defaults to 5.</p> |
| </attribute> |
| |
| <attribute name="lockOutTime" required="false"> |
| <p>The time (in seconds) a user is locked out for after too many |
| authentication failures. Defaults to 300 (5 minutes). Further |
| authentication failures during the lock out time will cause the lock out |
| timer to reset to zero, effectively extending the lock out time. Valid |
| authentication attempts during the lock out period will not succeed but |
| will also not reset the lock out time.</p> |
| </attribute> |
| |
| <attribute name="transportGuaranteeRedirectStatus" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| </attributes> |
| |
| <p>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.</p> |
| |
| </subsection> |
| |
| <subsection name="Null Realm - org.apache.catalina.realm.NullRealm"> |
| |
| <p><strong>NullRealm</strong> 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.</p> |
| |
| <p>The NullRealm implementation supports the following additional |
| attributes.</p> |
| |
| <attributes> |
| |
| <attribute name="transportGuaranteeRedirectStatus" required="false"> |
| <p>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.</p> |
| </attribute> |
| |
| </attributes> |
| |
| </subsection> |
| |
| </section> |
| |
| |
| <section name="Nested Components"> |
| |
| <p>You can nest the following components by nesting the corresponding element |
| inside your <strong>Realm</strong> element:</p> |
| <ul> |
| <li><strong>CombinedRealm Implementation</strong> - If you are using the |
| <em>CombinedRealm Implementation</em> or a Realm |
| that extends the CombinedRealm, e.g. the LockOutRealm, one or more |
| <strong><Realm></strong> elements may be nested inside it.</li> |
| <li><a href="credentialhandler.html"><strong>CredentialHandler</strong></a> - |
| You may nest at most one instance of this element inside a Realm. This |
| configures the credential handler that will be used to validate provided |
| credentials with those stored by the Realm. If not specified a default |
| <em>MessageDigestCredentialHandler</em> will be configured.</li> |
| </ul> |
| |
| </section> |
| |
| |
| <section name="Special Features"> |
| |
| <p>See <a href="host.html">Single Sign On</a> for information about |
| configuring Single Sign On support for a virtual host.</p> |
| |
| </section> |
| |
| |
| </body> |
| |
| |
| </document> |
