<?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="[email protected]">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="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="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
<code>CredentialHandler</code> 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.
</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 cannot 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="connectionPoolSize" required="false">
<p>The JNDI realm can use a pool of connections to the directory server
to avoid blocking on a single connection. This attribute value is the
maximum pool size. If not specified, it will use <code>1</code>, which
means a single connection will be used.</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="forceDnHexEscape" required="false">
<p>A setting of <code>true</code> forces escaping in the String
representation of a distinguished name to use the <code>\nn</code> form.
This may avoid issues with realms using Active Directory which appears
to be more tolerant of optional escaping when the <code>\nn</code> form
is used. If not specified, the default of <code>false</code> will be
used.</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 TLS protocol to use. If not given, the
Java runtime's default is used.
</attribute>
<attribute name="readTimeout" required="false">
<p>The timeout, in milliseconds, to use when trying to read from a
connection to the directory. If not specified, the default of 5000
(5 seconds) is used.</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.
</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="useContextClassLoader" required="false">
<p>Instructs JNDIRealm to use the context class loader when opening the
connection for the JNDI provider. The default value is
<code>true</code>. To load classes using the container's classloader,
specify <code>false</code>.</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 {0} 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.
</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="localJndiResource" required="false">
<p>When the realm is nested inside a Context element, this allows the
realm to use a UserDatabase defined for the Context rather than a global
UserDatabase. If not specified, the default is <code>false</code>: use a
global UserDatabase.</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="useStaticPrincipal" required="false">
<p>This allows using a static <code>Principal</code> instance
disconnected from the database if needed. This makes the behavior of
authenticated prinicipals equivalent to that of the other realms.
If there is a plan to use serialization, it is best to set this to
<code>true</code> as the principal will always be replaced by this
equivalent static principal when serializing.
If not specified, the default is <code>false</code>: use a
Principal connected to the UserDatabase.</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="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>JAASRealm is prototype for Tomcat of the JAAS-based J2EE authentication
framework for J2EE v1.4, based on the <a
href="https://www.jcp.org/en/jsr/detail?id=196">JCP Specification Request
196</a> to enhance container-managed security and promote 'pluggable'
authentication mechanisms whose implementations would be
container-independent.</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="false">
<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>
<p>If not specified <code>appName</code> is derived from the Container's
name it is placed in, for example <code>Catalina</code> or <code>ROOT</code>.
If the realm is not placed in any Container, the default is <code>Tomcat</code>.
</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. The authenticated user, and their associated roles, will be taken
from the first Realm that successfully authenticates 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>
<subsection name="Authenticated User Realm - org.apache.catalina.realm.AuthenticatedUserRealm">
<p><strong>AuthenticatedUserRealm</strong> is intended for use with
Authenticator implementations (SSLAuthenticator, SpnegoAuthenticator) that
authenticate the user as well as obtain the user credentials. An
authenticated Principal is always created from the user name presented to
without further validation.</p>
<p><strong>Note:</strong> It is unsafe to use this Realm with Authenticator
implementations that do not validate the provided credentials.</p>
<p>The AuthenticatedUserRealm 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>
¤ Dauer der Verarbeitung: 0.47 Sekunden
(vorverarbeitet)
¤
|
Haftungshinweis
Die Informationen auf dieser Webseite wurden
nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit,
noch Qualität der bereit gestellten Informationen zugesichert.
Bemerkung:
Die farbliche Syntaxdarstellung ist noch experimentell.
|
