Apache Tomcat 11 配置参考 (11.0.8) - Realm 组件

Realm 组件

介绍

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

一个 Catalina 容器（Engine、Host 或 Context）最多只能包含一个 Realm 元素（尽管如果 Realm 支持，此 Realm 本身可能包含多个嵌套 Realm）。此外，与 Engine 或 Host 相关联的 Realm 会自动被下级容器继承，除非下级容器明确定义了自己的 Realm。如果没有为 Engine 配置 Realm，将自动为 Engine 配置一个空 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 连接到 LDAP 目录，通过适当的 JNDI 驱动程序访问，该目录存储用户名、密码及其关联的角色。对目录的更改会立即反映在用于认证新登录的信息中。

目录 Realm 支持多种使用 LDAP 进行认证的方法

Realm 可以使用模式来确定用户目录条目的专有名称 (DN)，或搜索目录以找到该条目。
Realm 可以通过使用用户条目的 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”或提供者特定的定义都可以使用。如果指定了提供者特定的机制“GSSAPI”并且提供者支持它，在某些情况下（例如处理对 `HttpServletRequest.login(String username, String password)` 的调用），将不会使用“GSSAPI”，用户将按照 `userPassword` 中描述的方式进行认证。如果未给定值，则使用提供者的默认值。
`cipherSuites`	指定在使用 StartTLS 尝试打开安全连接时允许哪些密码套件。允许的密码套件以逗号分隔列表指定。默认是使用 JVM 的密码套件。
`commonRole`	除了从 LDAP 检索到的角色之外，分配给每个成功认证用户的角色名称。如果未指定，则仅使用通过 LDAP 检索到的角色。
`connectionName`	用于在建立与目录的连接以进行 LDAP 搜索操作时使用的目录用户名。如果未指定，则建立匿名连接，这通常足够，除非您指定了 `userPassword` 属性。
`connectionPassword`	用于在建立与目录的连接以进行 LDAP 搜索操作时使用的目录密码。如果未指定，则建立匿名连接，这通常足够，除非您指定了 `userPassword` 属性。
`connectionPoolSize`	JNDI Realm 可以使用连接池连接到目录服务器，以避免阻塞单个连接。此属性值是最大连接池大小。如果未指定，它将使用 `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 的 Realm 相关的问题，Active Directory 在使用 `\nn` 形式时似乎对可选转义更宽容。如果未指定，将使用默认值 `false`。
`hostnameVerifierClassName`	使用 StartTLS 保护与 LDAP 服务器的连接时用于主机名验证的类名。将使用默认构造函数构造验证器类的实例。默认只接受根据 LDAP 服务器的对等证书有效的主机名。
`protocol`	指定要使用的 TLS 协议的字符串。如果未给定，则使用 Java 运行时的默认值。
`readTimeout`	尝试从与目录的连接中读取时要使用的超时时间（毫秒）。如果未指定，则使用默认值 5000（5 秒）。
`referrals`	我们如何处理 JNDI 引用？允许的值为“ignore”、“follow”或“throw”（有关更多信息，请参阅 javax.naming.Context.REFERRAL）。Microsoft Active Directory 经常返回引用。如果您需要跟随它们，请将 referrals 设置为“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 Realm 与 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 认证器一起使用时，用户的委派凭据可能可用。如果存在此类凭据，此属性控制是否使用它们连接到目录。如果委派凭据存在但由于此属性为 `false` 而未使用，则行为将如 `roleSearchAsUser`、`userPattern` 和 `userSearchAsUser` 中所述（当未使用委派凭据时）。如果未指定，默认值为 `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 目录 Realm 组件设置容器管理安全的更多信息，请参阅容器管理安全指南。

用户数据库 Realm - org.apache.catalina.realm.UserDatabaseRealm

UserDatabase Realm 是一个 Realm 实现，它基于通过为该 Tomcat 实例配置的全局 JNDI 资源提供的 UserDatabase 资源。

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

属性	描述
`allRolesMode`	此属性控制在处理 web.xml 中的授权约束时如何处理特殊角色名 `*`。默认情况下，使用符合规范的值 `strict`，这意味着用户必须被分配 web.xml 中定义的角色之一。替代值包括 `authOnly`，这意味着用户必须经过认证但不检查分配的角色，以及 `strictAuthOnly`，这意味着用户必须经过认证，并且除非在 web.xml 中定义了角色，否则不检查分配的角色，在这种情况下用户必须被分配至少一个这些角色。
`localJndiResource`	当 Realm 嵌套在 Context 元素内时，这允许 Realm 使用为 Context 定义的 UserDatabase，而不是全局 UserDatabase。如果未指定，默认值为 `false`：使用全局 UserDatabase。
`resourceName`	此 Realm 将用于用户信息、密码和角色信息的全局 `UserDatabase` 资源的名称。
`useStaticPrincipal`	如果需要，这允许使用与数据库断开连接的静态 `Principal` 实例。这使得已认证主体的行为与其他 Realm 的行为等效。如果计划使用序列化，最好将其设置为 `true`，因为在序列化时，主体将始终被此等效的静态主体替换。如果未指定，默认值为 `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 是一个简单的 Realm 实现，它从 XML 格式读取用户信息，并将其表示为内存中的 Java 对象集合。此实现仅用于快速启动和运行容器管理安全功能——它不适用于生产环境。因此，当底层数据文件内容更改时，没有机制可以更新内存中的用户集合。

基于内存的 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 使开发人员能够将几乎任何可想象的安全 Realm 与 Tomcat 的 CMA 结合起来。

JAASRealm 是 Tomcat 中基于 JAAS 的 J2EE v1.4 认证框架的原型，基于 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`。如果 Realm 未放置在任何容器中，默认值为 `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 组件设置容器管理安全的更多信息，请参阅容器管理安全指南。

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

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

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

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

已认证用户 Realm - org.apache.catalina.realm.AuthenticatedUserRealm

AuthenticatedUserRealm 旨在与 Authenticator 实现（SSLAuthenticator、SpnegoAuthenticator）一起使用，这些实现既认证用户又获取用户凭据。已认证的 Principal 始终从提供的用户名创建，无需进一步验证。

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

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

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

嵌套组件

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

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

特殊功能

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