Unlike most Catalina components, there are several standard
Realm implementations available. As a result,
the className attribute MUST be used to select the
implementation you wish to use.
JDBC Database Realm (org.apache.catalina.realm.JDBCRealm)
The JDBC Database Realm connects Catalina to
a relational database, accessed through an appropriate JDBC driver,
to perform lookups of usernames, passwords, and their associated
roles. Because the lookup is done each time that it is required,
changes to the database will be immediately reflected in the
information used to authenticate new logins.
A rich set of additional attributes lets you configure the required
connection to the underlying database, as well as the table and
column names used to retrieve the required information:
| Attribute | Description |
|---|
connectionName |
The database username to use when establishing the JDBC
connection.
|
connectionPassword |
The database password to use when establishing the JDBC
connection.
|
connectionURL |
The connection URL to be passed to the JDBC driver when
establishing a database connection.
|
driverName |
Fully qualified Java class name of the JDBC driver to be used to
connect to the authentication database. Consult the documentation for
your JDBC driver for the appropriate value.
|
roleNameCol |
Name of the column, in the "user roles" table, which contains
a role name assigned to the corresponding user.
|
userCredCol |
Name of the column, in the "users" table, which contains the user's
credentials (i.e. password). If a value for the digest
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.
|
userNameCol |
Name of the column, in the "users" and "user roles" table,
that contains the user's username.
|
userRoleTable |
表名，它的每一行包含指派给某一特定用户名称的一个角色。这个表格必须至少包括那些由userNameCol和roleNameCol属性定名的列。
|
userTable |
表名，它的每一行包含一个可被Tomcat识别的用户名称。这个表格必须至少包括那些由userNameCol 和 userCredCol 属性定名的列。
|
See the Container-Managed Security Guide for more
information on setting up container managed security using the
JDBC Database Realm component.
DataSource Database Realm (org.apache.catalina.realm.DataSourceRealm)
The DataSource Database Realm connects Catalina to
a relational database, accessed through a JNDI named JDBC DataSource
to perform lookups of usernames, passwords, and their associated
roles. Because the lookup is done each time that it is required,
changes to the database will be immediately reflected in the
information used to authenticate new logins.
The JDBC Realm uses a single db connection. This requires that
realm based authentication be synchronized, i.e. only one authentication
can be done at a time. This could be a bottleneck for applications
with high volumes of realm based authentications.
The DataSource Database Realm supports simultaneous realm based
authentications and allows the underlying JDBC DataSource to
handle optimizations like database connection pooling.
A rich set of additional attributes lets you configure the name
of the JNDI JDBC DataSource, as well as the table and
column names used to retrieve the required information:
| Attribute | Description |
|---|
dataSourceName |
你的数据库需要的一个叫做JDBC DataSource的JNDI。如果这个DataSource对于上下文来说是局部的话，这个名字与java:/comp/env相关，否则这个名字应该和定义全球性DataSource的名字相映射。
|
localDataSource |
当这个realm被套嵌在一个Context元素里边，就允许这个realm使用为这个Context定义的DataSource，而不是全球性DataSource 。如果没有指定，默认值是false：使用全球性DataSource 。
|
roleNameCol |
Name of the column, in the "user roles" table, which contains
a role name assigned to the corresponding user.
|
userCredCol |
Name of the column, in the "users" table, which contains the user's
credentials (i.e. password). If a value for the digest
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.
|
userNameCol |
Name of the column, in the "users" and "user roles" table,
that contains the user's username.
|
userRoleTable |
表名，它的每一行包含指派给某一特定用户名称的一个角色。这个表格必须至少包括那些由userNameCol和roleNameCol属性定名的列。
|
userTable |
表名，它的每一行包含一个可被Tomcat识别的用户名称。这个表格必须至少包括那些由userNameCol 和 userCredCol 属性定名的列。
|
See the
DataSource Realm HOW-TO for more information on setting up container
managed security using the DataSource Database Realm component.
JNDI Directory Realm (org.apache.catalina.realm.JNDIRealm)
The JNDI Directory Realm connects Catalina to
an LDAP Directory, accessed through an appropriate JNDI driver,
that stores usernames, passwords, and their associated
roles. Changes to the directory are immediately reflected in the
information used to authenticate new logins.
The directory realm supports a variety of approaches to using
LDAP for authentication:
- The realm can either use a pattern to determine the
distinguished name (DN) of the user's directory entry, or search
the directory to locate that entry.
- The realm can authenticate the user either by binding to the
directory with the DN of the user's entry and the password
presented by the user, or by retrieving the password from the
user's entry and performing a comparison locally.
- Roles may be represented in the directory as explicit entries
found by a directory search (e.g. group entries of which the user
is a member), as the values of an attribute in the user's entry,
or both.
A rich set of additional attributes lets you configure the
required behaviour as well as the connection to the underlying
directory and the element and attribute names used to retrieve
information from the directory:
| Attribute | Description |
|---|
alternateURL |
If a socket connection can not be made to the provider at
the connectionURL an attempt will be made to use the
alternateURL.
|
authentication |
A string specifying the type of authentication to use.
"none", "simple", "strong" or a provider specific definition
can be used. If no value is given the providers default is used.
|
connectionName |
建立与LDAP search操作目录的连接时使用的目录用户名。如果没有指定，就使用无名的连接，除非你指定了userPassword属性，通常这就足够了。
|
connectionPassword |
建立与LDAP search操作目录的连接时使用的目录密码。如果没有指定，就使用无名的连接，除非你指定了userPassword属性，通常这就足够了。
|
connectionURL |
在建立与目录的连接时传递给JNDI驱动的连接URL。
|
contextFactory |
Fully qualified Java class name of the factory class used
to acquire our JNDI InitialContext. By default,
assumes that the standard JNDI LDAP provider will be utilized
(com.sun.jndi.ldap.LdapCtxFactory).
|
derefAliases |
A string specifying how aliases are to be dereferenced during
search operations. The allowed values are "always", "never",
"finding" and "searching". If not specified, "always" is used.
|
protocol |
A string specifying the security protocol to use. If not given
the providers default is used.
|
roleBase |
The base directory entry for performing role searches. If
not specified the top-level element in the directory context
will be used.
|
roleName |
属性的名字,它包含被角色搜寻查找到的目录输入里的角色名字。另外，你可以在包含有额外的角色名字的用户输入里使用userRoleName property来指定一个attribute的名字。如果roleName没有被指定，角色搜寻就不会发生，只能从用户的输入里得到角色。
|
roleSearch |
用来执行角色搜寻的LDAP过滤器表达式，后面紧跟着由java.text.MessageFormat类支持的语法。使用{0}来代替用户的独特名字(distinguished name (DN))，并且/或者用{1}来代替用户名(username)。如果没有被指定，角色搜寻就不发生，角色就由userRoleName property指定的用户输入里的属性来决定。
|
roleSubtree |
在查找与用户相关的角色输入时，如果你想搜寻roleBase property指定的元素的整个subtree，设值为true。默认值为false，它仅仅使得顶层元素被搜寻。
|
userBase |
通过使用userSearch表达式来执行的用户搜寻基本元素。如果没有指定，目录context里的顶层元素将被使用。如果你在使用userPattern表达式，就不用使用它。
|
userPassword |
Name of the attribute in the user's entry containing the user's
password. If you specify this value, JNDIRealm will bind to the
directory using the values specified by connectionName and
connectionPassword properties, and retrieve the
corresponding attribute for comparison to the value specified by the
user being authenticated. If the digest attribute is set,
the specified digest algorithm is applied to the password offered by the
user before comparing it with the value retrieved from the directory. If
you do not specify this value, JNDIRealm will attempt a
simple bind to the directory using the DN of the user's entry and the
password presented by the user, with a successful bind being interpreted
as an authenticated user.
|
userPattern |
Pattern for the distinguished name (DN) of the user's directory
entry, following the syntax supported by the
java.text.MessageFormat class. with {0}
marking where the actual username should be inserted. You can use this
property instead of userSearch, userSubtree
and userBase when the distinguished name contains
the username and is otherwise the same for all users.
|
userRoleName |
用户目录输入中的一个属性名，该属性包含了零个或多个指定给用户的角色名称的值。另外，可以使用roleName属性来指定属性名，这个属性可以通过搜索目录在单独的角色输入里得到。如果不指定userRoleName，用户的所有角色通过角色搜索得到。
|
userSearch |
搜索用户目录输入时，使用的LDAP过滤器表达式，{0}代表实际用户名应该在什么地方被插入。使用这个userSearch属性(和userBase以及userSubtree属性一起)，而不是userPattern，来搜索目录寻找用户的输入。
|
userSubtree |
如果想要搜索由userBase属性指定的元素的整个subtree，设为true，缺省值为false，即仅仅是顶级元素被搜索。如果使用userPattern表达式，则不使用这个属性。
|
See the Container-Managed Security Guide for more
information on setting up container managed security using the
JNDI Directory Realm component.
Memory Based Realm (org.apache.catalina.realm.MemoryRealm)
The Memory Based Realm is a simple Realm implementation
that reads user information from an XML format, and represents it as a
collection of Java objects in memory. This implementation is intended
solely to get up and running with container managed security - it is NOT
intended for production use. As such, there are no mechanisms for
updating the in-memory collection of users when the content of the
underlying data file is changed.
The Memory Based Realm implementation supports the following
additional attributes:
| Attribute | Description |
|---|
pathname |
Absolute or relative (to $CATALINA_HOME) pathname to the XML file
containing our user information. See below for details on the
XML element format required. If no pathname is specified, the
default value is conf/tomcat-users.xml.
|
The XML document referenced by the pathname attribute must
conform to the following requirements:
- The root (outer) element must be
<tomcat-users>.
- Each authorized user must be represented by a single XML element
<user>, nested inside the root element.
- Each
<user> element must have the following
attributes:
- name - Username of this user (must be unique
within this file).
- password - Password of this user (in
clear text).
- roles - Comma-delimited list of the role names
assigned to this user.
See the Container-Managed Security Guide for more
information on setting up container managed security using the
Memory Based Realm component.
User Database Realm (org.apache.catalina.realm.UserDatabaseRealm)
The User Database Realm is Realm implementation
that is based on an implementation of the UserDatabase
interface that is made available through the global JNDI resources
configured for this Tomcat instance.
The User Database Realm implementation supports the following
additional attributes:
| Attribute | Description |
|---|
resourceName |
The global JNDI name of the UserDatabase resource
used by this Realm.
|
See the Container-Managed Security Guide for more
information on setting up container managed security using the
UserDatabase Realm component.
JAAS Realm (org.apache.catalina.realm.JAASRealm)
The JAAS Realm implementation supports the following additional
attributes:
| Attribute | Description |
|---|
appName |
你在login配置文件中(
JAAS LoginConfig)配置的应用程序名。
|
userClassNames |
由逗号分隔开的，你为你的用户Principals制作的类名列单。
|
roleClassNames |
由逗号分隔开的，你为你的角色Principals制作的类名列单。
|
useContextClassLoader |
Instructs JAASRealm to use the context class loader for loading the
user-specified LoginModule class and associated
Principal classes. The default value is true,
which is backwards-compatible with the way Tomcat 4 works. To load
classes using the container's classloader, specify false.
|
See the Container-Managed Security
Guide for more information on setting up container managed security
using the JASS Realm component.
