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 屬性必須用於選取您要使用的實作。

資料庫 Realm - org.apache.catalina.realm.DataSourceRealm

資料庫資料源 Realm 將 Tomcat 連線到關聯式資料庫，透過 JNDI 名稱 JDBC 資料源存取，以執行使用者名稱、密碼及其關聯角色的查詢。由於每次需要時都會執行查詢，因此資料庫的變更會立即反映在用於驗證新登入資訊中。

JDBC Realm 使用單一 db 連線。這需要基於 realm 的驗證進行同步，亦即一次只能執行一個驗證。這可能是大量基於 realm 的驗證應用程式的瓶頸。

資料庫資料源 Realm 支援同時進行基於 realm 的驗證，並允許底層 JDBC 資料源處理最佳化，例如資料庫連線池。

豐富的附加屬性讓您可以設定 JNDI JDBC 資料源的名稱，以及用於擷取所需資訊的表格和欄位名稱

屬性	說明
`allRolesMode`	此屬性控制在處理 web.xml 中的授權限制時，如何處理特殊角色名稱 ``。預設情況下，使用符合規格的值 `strict`，表示使用者必須指派為 web.xml 中定義的角色之一。其他值為 `authOnly`，表示使用者必須經過驗證，但不會檢查指派的角色，以及 `strictAuthOnly`，表示使用者必須經過驗證，且不會檢查指派的角色，除非在 web.xml 中定義角色，否則使用者必須指派為其中至少一個角色。當此屬性具有 `authOnly` 或 `strictAuthOnly` 值時，roleNameCol* 和 userRoleTable 屬性會變成選用的。如果省略這兩個屬性，此 Realm 將不會載入使用者的角色。
`dataSourceName`	此領域的 JNDI JDBC DataSource 的名稱。
`localDataSource`	當領域巢狀在 Context 元素中時，這允許領域使用為 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 領域操作指南，以取得有關使用 DataSource 資料庫領域元件設定容器管理安全性進一步的資訊。

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

JNDI 目錄領域將 Tomcat 連接到透過適當 JNDI 驅動程式存取的 LDAP 目錄，其中儲存使用者名稱、密碼及其關聯的角色。目錄的變更會立即反映在用於驗證新登入的資訊中。

目錄領域支援使用 LDAP 進行驗證的各種方法

領域可以使用模式來判斷使用者的目錄條目的識別名稱 (DN)，或搜尋目錄以找到該條目。
領域可以透過繫結至目錄（使用使用者的條目 DN 和使用者提供的密碼）或透過從使用者的條目中擷取密碼並在本地執行比較來驗證使用者。
角色可以表示在目錄中，作為透過目錄搜尋找到的明確條目（例如使用者為其成員的群組條目）、作為使用者條目中屬性的值，或同時作為兩者。

豐富的附加屬性集讓您可以設定所需的行為，以及連線至基礎目錄和用於從目錄中擷取資訊的元素和屬性名稱

屬性	說明
`adCompat`	Microsoft Active Directory 經常傳回轉介。在 NamingEnumerations 上進行反覆運算時，這些會導致 PartialResultExceptions。如果您希望我們忽略這些例外狀況，請將此屬性設定為「true」。遺憾的是，沒有穩定的方法可以偵測例外狀況是否真的來自 AD 轉介。預設值為「false」。
`allRolesMode`	此屬性控制在處理 web.xml 中的授權限制時，如何處理特殊角色名稱 `*`。預設情況下，使用符合規格的值 `strict`，表示使用者必須指派為 web.xml 中定義的角色之一。其他值為 `authOnly`，表示使用者必須經過驗證，但不會檢查指派的角色，以及 `strictAuthOnly`，表示使用者必須經過驗證，且不會檢查指派的角色，除非在 web.xml 中定義角色，否則使用者必須指派為其中至少一個角色。
`alternateURL`	如果無法在 `connectionURL` 上對提供者建立 socket 連線，系統會嘗試使用 `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` 形式時，它似乎更能容忍選擇性跳脫。如果未指定，將使用預設值 `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 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 驗證器一起使用時，使用者的委派憑證可能可用。如果存在此類憑證，此屬性會控制是否使用它們連線至目錄。如果未指定，將使用預設值 `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 - org.apache.catalina.realm.UserDatabaseRealm

使用者資料庫領域是基於透過為此 Tomcat 執行個體設定的全球 JNDI 資源而提供的使用者資料庫資源的領域實作。

使用者資料庫領域實作支援下列其他屬性

屬性	說明
`allRolesMode`	此屬性控制在處理 web.xml 中的授權限制時，如何處理特殊角色名稱 `*`。預設情況下，使用符合規格的值 `strict`，表示使用者必須指派為 web.xml 中定義的角色之一。其他值為 `authOnly`，表示使用者必須經過驗證，但不會檢查指派的角色，以及 `strictAuthOnly`，表示使用者必須經過驗證，且不會檢查指派的角色，除非在 web.xml 中定義角色，否則使用者必須指派為其中至少一個角色。
`localJndiResource`	當領域巢狀在 Context 元素中時，這允許領域使用為 Context 定義的使用者資料庫，而不是全球使用者資料庫。如果未指定，則預設為 `false`：使用全球使用者資料庫。
`resourceName`	此領域將用於使用者、密碼和角色資訊的全球 `UserDatabase` 資源名稱。
`useStaticPrincipal`	這允許在需要時使用與資料庫斷開連線的靜態 `Principal` 實例。這使得經過驗證的原則行為等同於其他領域。如果計畫使用序列化，最好將此設定為 `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

基於記憶體的領域是一個簡單的領域實作，它從 XML 格式讀取使用者資訊，並將其表示為記憶體中 Java 物件的集合。此實作僅用於啟動並執行容器管理安全性，而非用於生產用途。因此，當基礎資料檔案的內容變更時，沒有任何機制可以更新記憶體中的使用者集合。

基於記憶體的領域實作支援下列其他屬性

屬性	說明
`allRolesMode`	此屬性控制在處理 web.xml 中的授權限制時，如何處理特殊角色名稱 `*`。預設情況下，使用符合規格的值 `strict`，表示使用者必須指派為 web.xml 中定義的角色之一。其他值為 `authOnly`，表示使用者必須經過驗證，但不會檢查指派的角色，以及 `strictAuthOnly`，表示使用者必須經過驗證，且不會檢查指派的角色，除非在 web.xml 中定義角色，否則使用者必須指派為其中至少一個角色。
`路徑名稱`	包含我們使用者資訊的 XML 檔案的 URL、絕對路徑或相對路徑（到 $CATALINA_BASE）。有關所需 XML 元素格式的詳細資訊，請參閱下方。如果未指定路徑名稱，預設值為 `conf/tomcat-users.xml`。
`stripRealmForGss`	在處理透過 GSS-API 驗證的使用者時，此屬性控制是否從使用者名稱結尾移除任何「@...」。如果未指定，預設為 `true`。
`transportGuaranteeRedirectStatus`	當容器需要發出 HTTP 重新導向以符合已組態傳輸保證的要求時要使用的 HTTP 狀態碼。不會驗證所提供的狀態碼。如果未指定，將使用預設值 `302`。
`X509UsernameRetrieverClassName`	在使用 X509 用戶端憑證時，這會指定用於從憑證中擷取使用者名稱的類別名稱。此類別必須實作 `org.apache.catalina.realm.X509UsernameRetriever` 介面。預設為使用憑證的 SubjectDN 作為使用者名稱。

路徑名稱 屬性所引用的 XML 文件必須符合下列需求

根（外部）元素必須為 <tomcat-users>。
每個授權使用者都必須由單一 XML 元素 <user> 表示，並嵌套在根元素內。
每個 <user> 元素都必須具有下列屬性
- 使用者名稱 - 此使用者的使用者名稱（在此檔案中必須是唯一的）。
  為了相容性，允許使用名稱作為此屬性的替代名稱。
- 密碼 - 此使用者的密碼（明文）。
- 角色 - 指派給此使用者的角色名稱的逗號分隔清單。

有關使用基於記憶體的領域元件設定容器管理安全性的更多資訊，請參閱容器管理安全性指南。

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`。如果 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 或相關使用者儲存機制。它透過記錄所有失敗登入（包括不存在使用者的登入）來達成此目的。為防止透過故意提出無效使用者要求（並因此導致此快取成長）來進行阻斷服務攻擊，已驗證失敗使用者的清單大小受到限制。

子 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 用於驗證使用者並取得使用者資格的 Authenticator 實作 (SSLAuthenticator、SpnegoAuthenticator)。驗證的 Principal 始終從使用者名稱建立，而無需進一步驗證。

注意：將此 Realm 與未驗證所提供資格的 Authenticator 實作一起使用是不安全的。

AuthenticatedUserRealm 實作支援下列其他屬性。

屬性	說明
`transportGuaranteeRedirectStatus`	當容器需要發出 HTTP 重新導向以符合已組態傳輸保證的要求時要使用的 HTTP 狀態碼。不會驗證所提供的狀態碼。如果未指定，將使用預設值 `302`。

巢狀組件

您可以在 Realm 元素中巢狀對應元素，以巢狀下列元件

CombinedRealm 實作 - 如果您使用的是 CombinedRealm 實作 或延伸 CombinedRealm 的 Realm，例如 LockOutRealm，則可以在其中巢狀一個或多個 <Realm> 元素。
CredentialHandler - 您可以在 Realm 中巢狀此元素的一個執行個體。這會設定資格處理常式，它會用來驗證所提供的資格與 Realm 儲存的資格。如果未指定，會設定預設的 MessageDigestCredentialHandler。

特殊功能

請參閱單一登入，以取得關於為虛擬主機設定單一登入支援的資訊。