Apache Tomcat 10 配置参考 (10.1.23) - Realm 组件

Realm 组件

简介

Realm 元素表示一个“数据库”，其中包含分配给这些用户的用户名、密码和角色（类似于 Unix 组）。Realm 的不同实现允许 Catalina 集成到已经创建和维护此类身份验证信息的各种环境中，然后利用该信息来实现 Servlet 规范中描述的容器管理安全。

Catalina 容器（引擎、主机或上下文）最多只能包含一个 Realm 元素（尽管如果 Realm 支持，则此 Realm 本身可能包含多个嵌套 Realm）。此外，与引擎或主机关联的 Realm 会自动被低级别容器继承，除非低级别容器明确定义自己的 Realm。如果未为引擎配置 Realm，则会为引擎自动配置Null Realm的实例。

有关 Web 应用程序中容器管理安全以及配置和使用标准 Realm 组件实现的更多详细信息，请参阅容器管理安全指南。

以下描述使用变量名 $CATALINA_BASE 来引用大多数相对路径所针对的基本目录。如果您没有通过设置 CATALINA_BASE 目录为多个实例配置 Tomcat，那么 $CATALINA_BASE 将设置为 $CATALINA_HOME 的值，即您安装 Tomcat 的目录。

属性

通用属性

Realm 的所有实现都支持以下属性

属性	说明
`className`	要使用的实现的 Java 类名。此类必须实现 `org.apache.catalina.Realm` 接口。

与大多数 Catalina 组件不同，有几个标准的 Realm 实现可用。因此，className 属性必须用于选择要使用的实现。

DataSource 数据库 Realm - org.apache.catalina.realm.DataSourceRealm

DataSource 数据库 Realm 将 Tomcat 连接到关系数据库，通过 JNDI 命名 JDBC DataSource 访问该数据库，以查找用户名、密码及其关联的角色。由于每次需要时都会进行查找，因此对数据库的更改将立即反映在用于验证新登录的信息中。

JDBC Realm 使用单个数据库连接。这要求基于 realm 的身份验证必须同步，即一次只能进行一个身份验证。对于基于 realm 的身份验证量很大的应用程序，这可能成为瓶颈。

DataSource 数据库 Realm 支持同时进行基于 realm 的身份验证，并允许底层 JDBC DataSource 处理数据库连接池等优化。

一组丰富的附加属性允许您配置 JNDI JDBC DataSource 的名称，以及用于检索所需信息的数据表和列名称

属性	说明
`allRolesMode`	此属性控制在处理 web.xml 中的授权约束时如何处理特殊角色名称 ``。默认情况下，使用规范兼容的值 `strict`，这意味着用户必须被分配 web.xml 中定义的一个角色。替代值是 `authOnly`，这意味着用户必须经过身份验证，但不会检查分配的角色，以及 `strictAuthOnly`，这意味着用户必须经过身份验证，并且不会检查分配的角色，除非在 web.xml 中定义了角色，在这种情况下，用户必须至少被分配其中一个角色。当此属性的值为`authOnly`或`strictAuthOnly`时，roleNameCol和userRoleTable*属性变为可选。如果这两个属性被忽略，此 Realm 将不会加载用户的角色。
`dataSourceName`	此 Realm 的 JNDI JDBC DataSource 的名称。
`localDataSource`	当 realm 嵌套在 Context 元素中时，这允许 realm 使用为 Context 定义的 DataSource，而不是全局 DataSource。如果未指定，则默认为`false`：使用全局 DataSource。
`roleNameCol`	“用户角色”表中包含分配给相应用户的角色名称的列的名称。此属性在大多数配置中是必需的。有关可以忽略此属性的罕见情况，请参见allRolesMode属性。
`transportGuaranteeRedirectStatus`	当容器需要发出 HTTP 重定向以满足配置的传输保证的要求时使用的 HTTP 状态代码。不验证提供的状态代码。如果未指定，则使用默认值`302`。
`stripRealmForGss`	通过 GSS-API 验证用户时，此属性控制是否从用户名末尾移除任何“@...”字符。如果未指定，则默认为`true`。
`userCredCol`	“用户”表中包含用户凭证（即密码）的列的名称。如果指定了`CredentialHandler`，此组件将假定密码已使用指定的算法进行编码。否则，将假定它们是明文。
`userNameCol`	“用户”和“用户角色”表中包含用户用户名的列的名称。
`userRoleTable`	“用户角色”表的名称，该表必须包含由`userNameCol`和`roleNameCol`属性命名的列。此属性在大多数配置中是必需的。有关可以忽略此属性的罕见情况，请参见allRolesMode属性。
`userTable`	“用户”表的名称，该表必须包含由`userNameCol`和`userCredCol`属性命名的列。
`X509UsernameRetrieverClassName`	使用 X509 客户端证书时，这指定用于从证书中检索用户名的类名。该类必须实现`org.apache.catalina.realm.X509UsernameRetriever`接口。默认情况下，使用证书的 SubjectDN 作为用户名。

有关使用 DataSource 数据库 Realm 组件设置容器管理的安全性的更多信息，请参见DataSource Realm 操作指南。

JNDI 目录 Realm - org.apache.catalina.realm.JNDIRealm

JNDI 目录 Realm将 Tomcat 连接到通过适当的 JNDI 驱动程序访问的 LDAP 目录，该目录存储用户名、密码及其关联的角色。对目录的更改会立即反映在用于验证新登录的信息中。

目录 realm 支持使用 LDAP 进行身份验证的多种方法

领域可以使用模式来确定用户目录条目的识别名称 (DN)，或搜索目录来找到该条目。
领域可以通过使用用户条目的 DN 和用户提供的密码绑定到目录，或通过从用户条目中检索密码并在本地执行比较来对用户进行身份验证。
角色可以在目录中表示为通过目录搜索找到的显式条目（例如用户是其成员的组条目），作为用户条目中属性的值，或两者兼有。

一组丰富的附加属性允许您配置所需的行为以及与基础目录的连接，以及用于从目录中检索信息的元素和属性名称

属性	说明
`adCompat`	Microsoft Active Directory 经常返回引用。在对 NamingEnumerations 进行迭代时，这些引用会导致 PartialResultExceptions。如果您希望我们忽略这些异常，请将此属性设置为“true”。遗憾的是，没有稳定的方法来检测异常是否真正来自 AD 引用。默认值为“false”。
`allRolesMode`	此属性控制在处理 web.xml 中的授权约束时如何处理特殊角色名称 `*`。默认情况下，使用规范兼容的值 `strict`，这意味着用户必须被分配 web.xml 中定义的一个角色。替代值是 `authOnly`，这意味着用户必须经过身份验证，但不会检查分配的角色，以及 `strictAuthOnly`，这意味着用户必须经过身份验证，并且不会检查分配的角色，除非在 web.xml 中定义了角色，在这种情况下，用户必须至少被分配其中一个角色。
`alternateURL`	如果无法在 `connectionURL` 上与提供程序建立套接字连接，将尝试使用 `alternateURL`。
`authentication`	指定要使用的身份验证类型的字符串。可以使用“none”、“simple”、“strong”或特定于提供程序的定义。如果未提供值，则使用提供程序的默认值。
`cipherSuites`	尝试使用 StartTLS 打开安全连接时，指定允许哪些密码套件。允许的密码套件由逗号分隔的列表指定。默认情况下，使用 JVM 的密码套件。
`commonRole`	除了从 LDAP 检索的角色外，分配给每个成功通过身份验证的用户的角色名称。如果未指定，则仅使用通过 LDAP 检索的角色。
`connectionName`	在为 LDAP 搜索操作建立与目录的连接时要使用的目录用户名。如果未指定，则建立匿名连接，这通常足够，除非您指定 `userPassword` 属性。
`connectionPassword`	在为 LDAP 搜索操作建立与目录的连接时要使用的目录密码。如果未指定，则建立匿名连接，这通常足够，除非您指定 `userPassword` 属性。
`connectionPoolSize`	JNDI 领域可以使用与目录服务器的连接池，以避免阻塞单个连接。此属性值是最大池大小。如果未指定，它将使用 `1`，这意味着将使用单个连接。
`connectionTimeout`	在建立与 LDAP 目录的连接时要使用的超时（以毫秒为单位）。如果未指定，则使用 5000（5 秒）的值。
`connectionURL`	在建立与目录的连接时传递给 JNDI 驱动程序的连接 URL。
`contextFactory`	用于获取我们的 JNDI `InitialContext` 的工厂类的完全限定 Java 类名。默认情况下，假定将使用标准 JNDI LDAP 提供程序。
`derefAliases`	指定在搜索操作期间如何取消引用别名的字符串。允许的值为“always”、“never”、“finding”和“searching”。如果未指定，则使用“always”。
`forceDnHexEscape`	`true` 的设置强制在专有名称的字符串表示形式中使用 `\nn` 形式进行转义。这可以避免使用 Active Directory 的领域的问题，当使用 `\nn` 形式时，Active Directory 似乎对可选转义更宽容。如果未指定，将使用默认值 `false`。
`hostnameVerifierClassName`	在使用 StartTLS 保护与 ldap 服务器的连接时用于主机名验证的类的名称。默认构造函数将用于构造验证器类的实例。默认情况下，仅接受根据 ldap 服务器的对等证书有效的那些主机名。
`protocol`	指定要使用的 TLS 协议的字符串。如果未给出，则使用 Java 运行时的默认值。
`readTimeout`	尝试从与目录的连接中读取时使用的超时（以毫秒为单位）。如果未指定，则使用默认值 5000（5 秒）。
`referrals`	我们如何处理 JNDI 引用？允许的值为“ignore”、“follow”或“throw”（有关更多信息，请参见 javax.naming.Context.REFERRAL）。Microsoft Active Directory 经常返回引用。如果您需要遵循它们，请将引用设置为“follow”。注意：如果您的 DNS 不是 AD 的一部分，则 LDAP 客户端库可能会尝试在 DNS 中解析您的域名以查找另一个 LDAP 服务器。
`roleBase`	用于执行角色搜索的基目录条目。如果未指定，将使用目录上下文中顶层元素。如果指定，它可以选择包含模式替换“{0}”..“{n}”，对应于用户专有名称的名称部分（由 `javax.naming.Name.get()` 返回）。
`roleName`	角色搜索找到的目录条目中包含角色名称的属性的名称。此外，您可以使用 `userRoleName` 属性指定用户条目中包含其他角色名称的属性的名称。如果未指定 `roleName`，则不会执行角色搜索，并且仅从用户的条目中获取角色。
`roleNested`	如果您希望将角色嵌套到角色中，请将其设置为 `true`。当执行角色搜索并且此属性的值为 `true` 时，将重复执行搜索以找到直接或间接属于用户的全部角色。如果未指定，则使用默认值 `false`。
`roleSearch`	用于执行角色搜索的 LDAP 筛选器表达式。使用 `{0}` 替换经过验证用户的用户专有名称 (DN)，和/或 `{1}` 替换用户名，和/或 `{2}` 替换经过验证用户的用户目录条目中属性的值。提供 `{2}` 值的属性名称由 `userRoleAttribute` 属性配置。当 `roleNested` 属性为 `true` 时，此筛选器表达式还将用于递归搜索间接属于此用户的其他角色。为了找到与新找到的角色匹配的角色，使用以下值：`{0}` 由新找到的角色的专有名称替换，`{1}` 和 `{2}` 均由角色名称替换（请参阅 `roleName` 属性）。`userRoleAttribute` 属性不适用于此搜索。如果未指定此属性，则不会执行角色搜索，并且仅从 `userRoleName` 属性指定的用户的条目中的属性获取角色。
`roleSearchAsUser`	在搜索用户角色时，是否应以当前正在验证的用户身份执行搜索？如果为 false，则如果指定了 `connectionName` 和 `connectionPassword`，将使用它们，否则使用匿名。如果未指定，则使用默认值 `false`。请注意，在使用委派凭据访问目录时，此属性始终被忽略，并且使用委派凭据执行搜索。
`roleSubtree`	如果您希望搜索由 `roleBase` 属性指定的元素的整个子树以查找与用户关联的角色条目，请将其设置为 `true`。默认值 `false` 仅导致搜索顶级。
`sizeLimit`	使用 `userSearch` 属性时，指定要返回的最大记录数。如果未指定，则使用默认值 `0`，表示没有限制。
`spnegoDelegationQop`	当 JNDI 领域与 SPNEGO 验证器一起使用并且 `useDelegatedCredential` 为 `true` 时，此属性控制在验证后用于与 LDAP 服务器建立连接的 QOP（保护质量）。此值用于为 LDAP 连接设置 `javax.security.sasl.qop` 环境属性。此属性应是从 `auth-conf`、`auth-int` 和 `auth` 中选出的值的逗号分隔列表。有关更多详细信息，请参阅 Java 文档。默认值为 `auth-conf`。
`sslProtocol`	指定在使用 StartTLS 连接时应使用哪个 ssl 协议。默认情况下，由 jre 决定。如果您需要更多控制，可以指定要使用的 `SSLSocketFactory`。
`sslSocketFactory`	指定在使用 StartTLS 连接到 ldap 服务器时要使用的 `SSLSocketFactory`。将使用默认构造函数构造该类的实例。如果未给出类名，将使用默认 jre `SSLSocketFactory`。
`stripRealmForGss`	通过 GSS-API 验证用户时，此属性控制是否从用户名末尾移除任何“@...”字符。如果未指定，则默认为`true`。
`timeLimit`	指定使用 `userSearch` 属性时等待返回记录的时间（以毫秒为单位）。如果未指定，则使用默认值 `0`，表示没有限制。
`transportGuaranteeRedirectStatus`	当容器需要发出 HTTP 重定向以满足配置的传输保证的要求时使用的 HTTP 状态代码。不验证提供的状态代码。如果未指定，则使用默认值`302`。
`useContextClassLoader`	指示 JNDIRealm 在为 JNDI 提供程序打开连接时使用上下文类加载器。默认值为 `true`。要使用容器的类加载器加载类，请指定 `false`。
`useDelegatedCredential`	当 JNDIRealm 与 SPNEGO 身份验证器一起使用时，用户可能可以使用委派凭据。如果存在此类凭据，此属性控制是否使用它们连接到目录。如果未指定，则使用默认值 `true`。
`userBase`	使用 `userSearch` 表达式执行用户搜索的基本元素。如果您使用 `userPattern` 表达式，则不使用。
`userPassword`	包含用户密码的用户条目中的属性名称。如果您指定此值，JNDIRealm 将使用由 `connectionName` 和 `connectionPassword` 属性指定的值绑定到目录，并检索相应的属性以与由正在验证的用户指定的值进行比较。如果您未指定此值，JNDIRealm 将尝试使用用户条目的 DN 和用户提供的密码简单绑定到目录，成功的绑定将被解释为已验证的用户。
`userPattern`	用户目录条目的可分辨名称 (DN) 的模式，其中 `{0}` 标记实际用户名应插入的位置。当可分辨名称包含用户名并且对所有用户而言都是相同的时，可以使用此属性代替 `userSearch`、`userSubtree` 和 `userBase`。请注意，在使用委派凭据访问目录时，此属性始终被忽略，而 `userSearch`、`userSubtree` 和 `userBase` 始终被用作替代。
`userRoleName`	用户目录条目中包含分配给此用户的角色名称的零个或多个值的属性的名称。此外，您可以使用 `roleName` 属性指定从通过搜索目录找到的各个角色条目中检索的属性的名称。如果未指定 `userRoleName`，则用户的所有角色都派生自角色搜索。
`userRoleAttribute`	用户目录条目中包含在搜索角色时希望使用的值的属性的名称。这对于 RFC 2307 特别有用，其中角色 memberUid 可以是用户的 `uid` 或 `uidNumber`。此值将在您的角色搜索过滤器表达式中标记为 `{2}`。此值将不可用于嵌套角色搜索。
`userSearch`	在搜索用户的目录条目时使用的 LDAP 过滤器表达式，其中 `{0}` 标记应插入实际用户名的位置。使用此属性（以及 `userBase` 和 `userSubtree` 属性）代替 `userPattern` 在目录中搜索用户的条目。
`userSearchAsUser`	在搜索用户的条目时，是否应以当前正在进行身份验证的用户身份执行搜索？如果为 false，则如果指定了 `connectionName` 和 `connectionPassword`，将使用它们，否则将使用匿名。如果未指定，则使用默认值 `false`。请注意，在使用委派凭据访问目录时，此属性始终被忽略，并且使用委派凭据执行搜索。
`userSubtree`	如果要搜索由 `userBase` 属性指定的元素的整个子树以查找用户的条目，请将其设置为 `true`。默认值 `false` 仅导致搜索顶级。如果您正在使用 `userPattern` 表达式，则不会使用它。
`useStartTls`	如果要使用 StartTLS 来保护与 ldap 服务器的连接，请将其设置为 `true`。默认值为 `false`。
`X509UsernameRetrieverClassName`	使用 X509 客户端证书时，这指定用于从证书中检索用户名的类名。该类必须实现`org.apache.catalina.realm.X509UsernameRetriever`接口。默认情况下，使用证书的 SubjectDN 作为用户名。

有关使用 JNDI 目录领域组件设置容器托管安全性的更多信息，请参阅容器托管安全指南。

UserDatabase Realm - org.apache.catalina.realm.UserDatabaseRealm

用户数据库领域是基于通过为此 Tomcat 实例配置的全局 JNDI 资源提供的 UserDatabase 资源的领域实现。

UserDatabase 领域实现支持以下附加属性

属性	说明
`allRolesMode`	此属性控制在处理 web.xml 中的授权约束时如何处理特殊角色名称 `*`。默认情况下，使用规范兼容的值 `strict`，这意味着用户必须被分配 web.xml 中定义的一个角色。替代值是 `authOnly`，这意味着用户必须经过身份验证，但不会检查分配的角色，以及 `strictAuthOnly`，这意味着用户必须经过身份验证，并且不会检查分配的角色，除非在 web.xml 中定义了角色，在这种情况下，用户必须至少被分配其中一个角色。
`localJndiResource`	当领域嵌套在 Context 元素中时，这允许领域使用为 Context 定义的 UserDatabase，而不是全局 UserDatabase。如果未指定，则默认值为 `false`：使用全局 UserDatabase。
`resourceName`	此领域将用于用户、密码和角色信息的全局 `UserDatabase` 资源的名称。
`useStaticPrincipal`	如果需要，这允许使用与数据库断开的静态 `Principal` 实例。这使得经过身份验证的 principals 的行为等同于其他领域的行为。如果计划使用序列化，最好将其设置为 `true`，因为在序列化时，principal 将始终被此等效的静态 principal 替换。如果未指定，则默认值为 `false`：使用连接到 UserDatabase 的 Principal。
`transportGuaranteeRedirectStatus`	当容器需要发出 HTTP 重定向以满足配置的传输保证的要求时使用的 HTTP 状态代码。不验证提供的状态代码。如果未指定，则使用默认值`302`。
`X509UsernameRetrieverClassName`	使用 X509 客户端证书时，这指定用于从证书中检索用户名的类名。该类必须实现`org.apache.catalina.realm.X509UsernameRetriever`接口。默认情况下，使用证书的 SubjectDN 作为用户名。

有关使用 UserDatabase Realm 组件设置容器管理安全性的更多信息，请参阅容器管理安全性指南；有关如何配置 UserDatabase 资源的更多信息，请参阅 JNDI 资源操作方法。

基于内存的 Realm - org.apache.catalina.realm.MemoryRealm

基于内存的 Realm 是一种从 XML 格式读取用户信息并将其表示为内存中 Java 对象集合的简单 Realm 实现。此实现仅用于启动并运行容器管理安全性，不适用于生产用途。因此，当基础数据文件的内容发生更改时，没有更新内存中用户集合的机制。

基于内存的 Realm 实现支持以下附加属性

属性	说明
`allRolesMode`	此属性控制在处理 web.xml 中的授权约束时如何处理特殊角色名称 `*`。默认情况下，使用规范兼容的值 `strict`，这意味着用户必须被分配 web.xml 中定义的一个角色。替代值是 `authOnly`，这意味着用户必须经过身份验证，但不会检查分配的角色，以及 `strictAuthOnly`，这意味着用户必须经过身份验证，并且不会检查分配的角色，除非在 web.xml 中定义了角色，在这种情况下，用户必须至少被分配其中一个角色。
`pathname`	包含我们用户信息的 XML 文件的 URL、绝对路径或相对路径（到 $CATALINA_BASE）。有关所需的 XML 元素格式的详细信息，请参见下文。如果未指定 pathname，则默认值为 `conf/tomcat-users.xml`。
`stripRealmForGss`	通过 GSS-API 验证用户时，此属性控制是否从用户名末尾移除任何“@...”字符。如果未指定，则默认为`true`。
`transportGuaranteeRedirectStatus`	当容器需要发出 HTTP 重定向以满足配置的传输保证的要求时使用的 HTTP 状态代码。不验证提供的状态代码。如果未指定，则使用默认值`302`。
`X509UsernameRetrieverClassName`	使用 X509 客户端证书时，这指定用于从证书中检索用户名的类名。该类必须实现`org.apache.catalina.realm.X509UsernameRetriever`接口。默认情况下，使用证书的 SubjectDN 作为用户名。

pathname 属性引用的 XML 文档必须符合以下要求

根（外部）元素必须是 <tomcat-users>。
每个授权用户必须由嵌套在根元素内的单个 XML 元素 <user> 表示。
每个 <user> 元素必须具有以下属性
- username - 此用户的用户名（在此文件中必须唯一）。
  为了兼容性，允许将 name 用作此属性的备用名称。
- password - 此用户的密码（明文）。
- roles - 分配给此用户的角色名称的逗号分隔列表。

有关使用基于内存的 Realm 组件设置容器管理安全性的更多信息，请参阅容器管理安全性指南。

JAAS Realm - org.apache.catalina.realm.JAASRealm

JAASRealm 是 Tomcat Realm 接口的一个实现，它通过 Java 身份验证和授权服务 (JAAS) 框架对用户进行身份验证，该框架现在作为标准 J2SE API 的一部分提供。

使用 JAASRealm 使开发人员能够将几乎任何可以想象的安全领域与 Tomcat 的 CMA 结合起来。

JAASRealm 是 Tomcat 的 J2EE v1.4 基于 JAAS 的 J2EE 身份验证框架的原型，基于 JCP 规范请求 196，以增强容器管理的安全性和促进“可插入”身份验证机制，其实现与容器无关。

基于 JAAS 登录模块和主体（请参阅 javax.security.auth.spi.LoginModule 和 javax.security.Principal），您可以开发自己的安全机制或包装其他第三方机制，以与 Tomcat 实现的 CMA 集成。

JAAS Realm 实现支持以下附加属性

属性	说明
`allRolesMode`	此属性控制在处理 web.xml 中的授权约束时如何处理特殊角色名称 `*`。默认情况下，使用规范兼容的值 `strict`，这意味着用户必须被分配 web.xml 中定义的一个角色。替代值是 `authOnly`，这意味着用户必须经过身份验证，但不会检查分配的角色，以及 `strictAuthOnly`，这意味着用户必须经过身份验证，并且不会检查分配的角色，除非在 web.xml 中定义了角色，在这种情况下，用户必须至少被分配其中一个角色。
`appName`	在登录配置文件中配置的应用程序名称（JAAS LoginConfig）。如果未指定 `appName`，则从放置它的容器的名称派生，例如 `Catalina` 或 `ROOT`。如果该领域未放置在任何容器中，则默认为 `Tomcat`。
`userClassNames`	您为用户 `Principals` 制作的类的名称的逗号分隔列表。
`configFile`	与此 Realm 一起使用的 JAAS 配置文件的名称。它将使用 `ClassLoader#getResource(String)` 进行搜索，因此可以将配置捆绑在 Web 应用程序中。如果未指定，将使用默认的 JVM 全局 JAAS 配置。
`roleClassNames`	您为角色 `Principals` 制作的类的名称的逗号分隔列表。
`stripRealmForGss`	通过 GSS-API 验证用户时，此属性控制是否从用户名末尾移除任何“@...”字符。如果未指定，则默认为`true`。
`transportGuaranteeRedirectStatus`	当容器需要发出 HTTP 重定向以满足配置的传输保证的要求时使用的 HTTP 状态代码。不验证提供的状态代码。如果未指定，则使用默认值`302`。
`useContextClassLoader`	指示 JAASRealm 使用上下文类加载器加载用户指定的 `LoginModule` 类和关联的 `Principal` 类。默认值为 `true`，这与 Tomcat 5 的工作方式向后兼容。要使用容器的类加载器加载类，请指定 `false`。
`X509UsernameRetrieverClassName`	使用 X509 客户端证书时，这指定用于从证书中检索用户名的类名。该类必须实现`org.apache.catalina.realm.X509UsernameRetriever`接口。默认情况下，使用证书的 SubjectDN 作为用户名。

请参阅容器管理的安全指南，以获取有关使用 JAAS Realm 组件设置容器管理的安全性的更多信息。

组合 Realm - org.apache.catalina.realm.CombinedRealm

CombinedRealm 是 Tomcat Realm 接口的一个实现，它通过一个或多个子 Realm 对用户进行身份验证。

使用 CombinedRealm 使开发人员能够组合相同或不同类型的多个 Realm。这可用于针对不同的源进行身份验证，在某个 Realm 失败时提供回退，或用于需要多个 Realm 的任何其他目的。

子 Realm 通过在定义 CombinedRealm 的 Realm 元素内嵌套 Realm 元素来定义。将按列出的顺序针对每个 Realm 尝试进行身份验证。针对任何 Realm 的身份验证都足以对用户进行身份验证。经过身份验证的用户及其关联的角色将取自成功对用户进行身份验证的第一个 Realm。

请参阅容器管理的安全指南以获取有关使用 CombinedRealm 组件设置容器管理的安全性的更多信息。

CombinedRealm 实现支持以下附加属性。

属性说明

allRolesMode

此属性控制在处理 web.xml 中的授权约束时如何处理特殊角色名称 *。默认情况下，使用规范兼容的值 strict，这意味着用户必须被分配 web.xml 中定义的一个角色。替代值是 authOnly，这意味着用户必须经过身份验证，但不会检查分配的角色，以及 strictAuthOnly，这意味着用户必须经过身份验证，并且不会检查分配的角色，除非在 web.xml 中定义了角色，在这种情况下，用户必须至少被分配其中一个角色。

transportGuaranteeRedirectStatus

当容器需要发出 HTTP 重定向以满足配置的传输保证的要求时使用的 HTTP 状态代码。不验证提供的状态代码。如果未指定，则使用默认值302。

锁定 Realm - org.apache.catalina.realm.LockOutRealm

LockOutRealm 是 Tomcat Realm 接口的一个实现，它扩展了 CombinedRealm 以提供锁定功能，以便在给定时间段内存在过多失败的身份验证尝试时提供用户锁定机制。

为了确保正确操作，此 Realm 中存在合理程度的同步。

此 Realm 不需要修改基础 Realm 或关联的用户存储机制。它通过记录所有失败的登录来实现此目的，包括不存在用户的登录。为了防止通过故意使用无效用户发出请求（从而导致此缓存增长）来进行 DOS 攻击，已对失败身份验证的用户列表的大小进行了限制。

子 Realm 通过在定义 LockOutRealm 的 Realm 元素内嵌套 Realm 元素来定义。将按列出的顺序针对每个 Realm 尝试进行身份验证。针对任何 Realm 的身份验证都足以对用户进行身份验证。

LockOutRealm 实现支持以下附加属性。

属性	说明
`allRolesMode`	此属性控制在处理 web.xml 中的授权约束时如何处理特殊角色名称 `*`。默认情况下，使用规范兼容的值 `strict`，这意味着用户必须被分配 web.xml 中定义的一个角色。替代值是 `authOnly`，这意味着用户必须经过身份验证，但不会检查分配的角色，以及 `strictAuthOnly`，这意味着用户必须经过身份验证，并且不会检查分配的角色，除非在 web.xml 中定义了角色，在这种情况下，用户必须至少被分配其中一个角色。
`cacheRemovalWarningTime`	如果失败的用户在缓存中至少存在此时间段（以秒为单位）之前因缓存太大而从缓存中移除，则会记录一条警告消息。默认为 3600（1 小时）。
`cacheSize`	将失败身份验证的用户数保留在缓存中。随着时间的推移，缓存将增长到此大小，并且可能不会缩小。默认为 1000。
`failureCount`	用户连续失败身份验证的次数，然后被锁定。默认为 5。
`lockOutTime`	用户因身份验证失败次数过多而被锁定的时间（以秒为单位）。默认为 300（5 分钟）。在锁定时间内进一步的身份验证失败将导致锁定计时器重置为零，从而有效地延长锁定时间。锁定期间有效的身份验证尝试不会成功，但也不会重置锁定时间。
`transportGuaranteeRedirectStatus`	当容器需要发出 HTTP 重定向以满足配置的传输保证的要求时使用的 HTTP 状态代码。不验证提供的状态代码。如果未指定，则使用默认值`302`。

有关使用 LockOutRealm 组件设置容器管理安全性的更多信息，请参阅容器管理安全指南。

Null Realm - org.apache.catalina.realm.NullRealm

NullRealm 是 Tomcat Realm 接口的最小实现，当尝试验证用户名和关联凭据时，它始终返回 null。当未指定其他 Realm 时，它旨在用作默认 Realm 实现。

NullRealm 实现支持以下其他属性。

属性	说明
`transportGuaranteeRedirectStatus`	当容器需要发出 HTTP 重定向以满足配置的传输保证的要求时使用的 HTTP 状态代码。不验证提供的状态代码。如果未指定，则使用默认值`302`。

经过身份验证的用户 Realm - org.apache.catalina.realm.AuthenticatedUserRealm

AuthenticatedUserRealm 旨在与身份验证器实现（SSLAuthenticator、SpnegoAuthenticator）一起使用，这些实现对用户进行身份验证并获取用户凭据。经过身份验证的主体始终从呈现给用户的用户名创建，无需进一步验证。

注意：将此 Realm 与不验证所提供凭据的身份验证器实现一起使用是不安全的。

AuthenticatedUserRealm 实现支持以下其他属性。

属性	说明
`transportGuaranteeRedirectStatus`	当容器需要发出 HTTP 重定向以满足配置的传输保证的要求时使用的 HTTP 状态代码。不验证提供的状态代码。如果未指定，则使用默认值`302`。

嵌套组件

您可以通过在 Realm 元素内嵌套相应的元素来嵌套以下组件

CombinedRealm 实现 - 如果您使用的是 CombinedRealm 实现 或扩展 CombinedRealm 的 Realm，例如 LockOutRealm，则可以在其中嵌套一个或多个 <Realm> 元素。
CredentialHandler - 您可以在 Realm 中最多嵌套一个此元素的实例。这将配置凭据处理程序，该处理程序将用于验证所提供的凭据与 Realm 存储的凭据。如果未指定，将配置默认的 MessageDigestCredentialHandler。

特殊功能

有关为虚拟主机配置单点登录支持的信息，请参阅单点登录。