Apache Tomcat 11 設定リファレンス (11.0.8)

Realm コンポーネント

はじめに

Realm 要素は、ユーザー名、パスワード、およびそれらのユーザーに割り当てられたロール (Unix のグループに類似) の "データベース" を表します。Realm のさまざまな実装により、Catalina を、このような認証情報が既に作成および維持されている環境に統合し、その情報を使用して、サーブレット仕様で説明されているように、コンテナ管理セキュリティを実装できます。

Catalina コンテナ (Engine, Host, または Context) には、Realm 要素を 1 つしか含めることができません (ただし、Realm でサポートされている場合、この 1 つの Realm 自体に複数のネストされた Realm を含めることができます)。さらに、Engine または Host に関連付けられた Realm は、下位レベルのコンテナが独自の Realm を明示的に定義しない限り、下位レベルのコンテナに自動的に継承されます。Engine に対して Realm が構成されていない場合、Null Realm のインスタンスが Engine に自動的に構成されます。

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 は、単一の DB 接続を使用します。これには、Realm ベースの認証を同期する必要があります。つまり、一度に実行できる認証は 1 つだけです。これは、Realm ベースの認証の量が多いアプリケーションのボトルネックになる可能性があります。

DataSource データベース Realm は、同時 Realm ベースの認証をサポートし、基になる JDBC DataSource がデータベース接続プーリングなどの最適化を処理できるようにします。

追加の豊富な属性セットにより、JNDI JDBC DataSource の名前、および必要な情報の取得に使用されるテーブルと列の名前を構成できます。

属性	説明
`allRolesMode`	この属性は、web.xml での承認制約の処理時に、特別なロール名 `` がどのように処理されるかを制御します。デフォルトでは、仕様に準拠した値の `strict` が使用されます。これは、ユーザーが web.xml で定義されたロールのいずれかを割り当てられている必要があることを意味します。代替値は、ユーザーが認証されている必要があるが、割り当てられたロールのチェックは行われないことを意味する `authOnly` と、ユーザーが認証されている必要があり、割り当てられたロールのチェックは行われないが、web.xml でロールが定義されている場合は、ユーザーがそれらのロールの少なくとも 1 つを割り当てられている必要があることを意味する `strictAuthOnly` です。この属性の値が `authOnly` または `strictAuthOnly` の場合、roleNameCol* および userRoleTable 属性はオプションになります。これらの 2 つの属性が省略された場合、ユーザーのロールはこの Realm によってロードされません。
`dataSourceName`	この Realm の JNDI JDBC DataSource の名前。
`localDataSource`	Realm が Context 要素内にネストされている場合、これにより、Realm はグローバル DataSource ではなく Context に対して定義された 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 How-To を参照してください。

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` と、ユーザーが認証されている必要があり、割り当てられたロールのチェックは行われないが、web.xml でロールが定義されている場合は、ユーザーがそれらのロールの少なくとも 1 つを割り当てられている必要があることを意味する `strictAuthOnly` です。
`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` 形式を使用するように強制します。これにより、`\nn` 形式を使用する場合にオプションのエスケープに対してより寛容であるように見える Active Directory を使用する Realm での問題を回避できます。指定されていない場合、デフォルトの `false` が使用されます。
`hostnameVerifierClassName`	ldap サーバーへの接続を保護するために StartTLS を使用する場合にホスト名の検証に使用するクラスの名前。デフォルトのコンストラクターは、検証クラスのインスタンスを構築するために使用されます。デフォルトでは、ldap サーバーのピア証明書に従って有効なホスト名のみが受け入れられます。
`protocol`	使用する TLS プロトコルを指定する文字列。指定されていない場合、Java ランタイムのデフォルトが使用されます。
`readTimeout`	ディレクトリへの接続からの読み取りを試みるときに使用するタイムアウト (ミリ秒単位)。指定されていない場合、デフォルトの 5000 (5 秒) が使用されます。
`referrals`	JNDI 参照をどのように処理しますか? 許可される値は、"ignore"、"follow"、または "throw" です (詳細については、javax.naming.Context.REFERRAL を参照してください)。Microsoft Active Directory は、多くの場合、参照を返します。参照に従う必要がある場合は、参照を "follow" に設定します。注意: DNS が AD の一部でない場合、LDAP クライアントライブラリは、別の LDAP サーバーを見つけるために DNS でドメイン名を解決しようとする可能性があります。
`roleBase`	ロール検索を実行するためのベースディレクトリエンティティ。指定されていない場合、ディレクトリコンテキスト内の最上位要素が使用されます。指定されている場合は、オプションで、ユーザーの識別名の名前部分に対応するパターン置換 "{0}".." {n}" を含めることができます (`javax.naming.Name.get()` によって返されるもの)。
`roleName`	ロール検索によって見つかったディレクトリエンティティのロール名を含む属性の名前。さらに、`userRoleName` プロパティを使用して、ユーザーのエントリで、追加のロール名を含む属性の名前を指定できます。 `roleName` が指定されていない場合、ロール検索は行われず、ロールはユーザーのエントリからのみ取得されます。
`roleNested`	ロールをロールにネストする場合は、`true` に設定します。ロール検索が実行され、このプロパティの値が `true` の場合、検索は再帰的に繰り返され、ユーザーに直接または間接的に属するすべてのロールが検索されます。指定されていない場合、デフォルト値の `false` が使用されます。
`roleSearch`	ロール検索の実行に使用される LDAP フィルター式。認証されたユーザーのディレクトリエンティティから、ユーザーの識別名 (DN) を置換するには `{0}` を使用し、ユーザー名を置換するには `{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 (Quality of Protection) を制御します。この値は、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`	JNDI プロバイダーの接続を開くときに、JNDIRealm にコンテキストクラスローダーを使用するように指示します。デフォルト値は `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`	ロールの検索時に使用する値を含む、ユーザーのディレクトリエントリ内の属性の名前。これは、ロール memberUid がユーザーの `uid` または `uidNumber` になる可能性がある RFC 2307 で特に役立ちます。この値は、ロール検索フィルター式で `{2}` としてマークされます。この値は、ネストされたロール検索では使用できません。
`userSearch`	ユーザーのディレクトリエントリを検索するときに使用する LDAP フィルター式。`{0}` は、実際のユーザー名を挿入する場所を示します。`userPattern` の代わりに、このプロパティ (`userBase` プロパティおよび `userSubtree` プロパティと組み合わせて) を使用して、ディレクトリでユーザーのエントリを検索します。
`userSearchAsUser`	ユーザーのエントリを検索するときに、検索は現在認証されているユーザーとして実行する必要がありますか? false の場合、`connectionName` と `connectionPassword` が指定されている場合はそれらが使用され、指定されていない場合は匿名接続が使用されます。指定されていない場合、デフォルト値の `false` が使用されます。委任された資格情報を使用してディレクトリにアクセスする場合、この属性は常に無視され、委任された資格情報を使用して検索が実行されることに注意してください。
`userSubtree`	`userBase` プロパティで指定された要素のサブツリー全体を、ユーザーのエントリに対して検索する場合は、`true` に設定します。デフォルト値の `false` では、最上位レベルのみが検索されます。`userPattern` 式を使用している場合は使用されません。
`useStartTls`	ldap サーバーへの接続を保護するために StartTLS を使用する場合は、`true` に設定します。デフォルト値は `false` です。
`X509UsernameRetrieverClassName`	X509 クライアント証明書を使用する場合、これは、証明書からユーザー名を取得するために使用されるクラス名を指定します。クラスは、`org.apache.catalina.realm.X509UsernameRetriever` インターフェースを実装する必要があります。デフォルトでは、証明書の SubjectDN をユーザー名として使用します。

JNDI ディレクトリ Realm コンポーネントを使用したコンテナ管理セキュリティの設定の詳細については、コンテナ管理セキュリティガイドを参照してください。

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

UserDatabase Realm は、この Tomcat インスタンス用に構成されたグローバル JNDI リソースを介して利用可能になる UserDatabase リソースに基づいた Realm 実装です。

UserDatabase Realm 実装は、次の追加の属性をサポートしています。

属性	説明
`allRolesMode`	この属性は、web.xml での承認制約の処理時に、特別なロール名 `*` がどのように処理されるかを制御します。デフォルトでは、仕様に準拠した値の `strict` が使用されます。これは、ユーザーが web.xml で定義されたロールのいずれかを割り当てられている必要があることを意味します。代替値は、ユーザーが認証されている必要があるが、割り当てられたロールのチェックは行われないことを意味する `authOnly` と、ユーザーが認証されている必要があり、割り当てられたロールのチェックは行われないが、web.xml でロールが定義されている場合は、ユーザーがそれらのロールの少なくとも 1 つを割り当てられている必要があることを意味する `strictAuthOnly` です。
`localJndiResource`	Realm が Context 要素内にネストされている場合、これにより、Realm はグローバル UserDatabase ではなく Context に対して定義された 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 は、XML 形式からユーザー情報を読み取り、それをメモリ内の Java オブジェクトのコレクションとして表す単純な Realm 実装です。この実装は、コンテナ管理セキュリティを立ち上げて実行することのみを目的としており、本番環境での使用を目的としていません。そのため、基になるデータファイルの内容が変更されたときにメモリ内のユーザーコレクションを更新するメカニズムはありません。

メモリベース Realm 実装は、次の追加の属性をサポートしています。

属性	説明
`allRolesMode`	この属性は、web.xml での承認制約の処理時に、特別なロール名 `*` がどのように処理されるかを制御します。デフォルトでは、仕様に準拠した値の `strict` が使用されます。これは、ユーザーが web.xml で定義されたロールのいずれかを割り当てられている必要があることを意味します。代替値は、ユーザーが認証されている必要があるが、割り当てられたロールのチェックは行われないことを意味する `authOnly` と、ユーザーが認証されている必要があり、割り当てられたロールのチェックは行われないが、web.xml でロールが定義されている場合は、ユーザーがそれらのロールの少なくとも 1 つを割り当てられている必要があることを意味する `strictAuthOnly` です。
`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 は、Java Authentication & Authorization Service (JAAS) フレームワーク (現在は標準の J2SE API の一部として提供されています) を介してユーザーを認証する Tomcat Realm インターフェースの実装です。

JAASRealm を使用すると、開発者は考えられるほぼすべてのセキュリティ Realm を Tomcat の CMA と組み合わせることができます。

JAASRealm は、JCP Specification Request 196 に基づいて、コンテナ管理セキュリティを強化し、実装がコンテナに依存しない「プラグ可能な」認証メカニズムを推進するための J2EE v1.4 の JAAS ベースの J2EE 認証フレームワークの Tomcat のプロトタイプです。

JAASログインモジュールとプリンシパル（javax.security.auth.spi.LoginModule および javax.security.Principalを参照）に基づいて、Tomcatによって実装されるCMAと統合するために、独自のセキュリティメカニズムを開発したり、別のサードパーティ製メカニズムをラップしたりできます。

JAAS Realmの実装は、以下の追加属性をサポートしています。

属性	説明
`allRolesMode`	この属性は、web.xml での承認制約の処理時に、特別なロール名 `*` がどのように処理されるかを制御します。デフォルトでは、仕様に準拠した値の `strict` が使用されます。これは、ユーザーが web.xml で定義されたロールのいずれかを割り当てられている必要があることを意味します。代替値は、ユーザーが認証されている必要があるが、割り当てられたロールのチェックは行われないことを意味する `authOnly` と、ユーザーが認証されている必要があり、割り当てられたロールのチェックは行われないが、web.xml でロールが定義されている場合は、ユーザーがそれらのロールの少なくとも 1 つを割り当てられている必要があることを意味する `strictAuthOnly` です。
`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インターフェースの実装であり、1つ以上のサブRealmを介してユーザーを認証します。

CombinedRealmを使用すると、開発者は同じタイプまたは異なるタイプの複数のRealmを組み合わせることができます。これは、異なるソースに対して認証したり、Realmが失敗した場合のフォールバックを提供したり、複数のRealmを必要とするその他の目的に使用できます。

サブリソースは、CombinedRealmを定義するRealm要素内にRealm要素をネストすることによって定義されます。認証は、リストされている順に各Realmに対して試行されます。Realmに対する認証は、ユーザーを認証するのに十分です。認証されたユーザーと、それに関連付けられたロールは、ユーザーの認証に成功した最初のRealmから取得されます。

CombinedRealmコンポーネントを使用したコンテナ管理セキュリティのセットアップの詳細については、コンテナ管理セキュリティガイドを参照してください。

CombinedRealmの実装は、次の追加属性をサポートしています。

属性説明

allRolesMode

この属性は、web.xml での承認制約の処理時に、特別なロール名 * がどのように処理されるかを制御します。デフォルトでは、仕様に準拠した値の strict が使用されます。これは、ユーザーが web.xml で定義されたロールのいずれかを割り当てられている必要があることを意味します。代替値は、ユーザーが認証されている必要があるが、割り当てられたロールのチェックは行われないことを意味する authOnly と、ユーザーが認証されている必要があり、割り当てられたロールのチェックは行われないが、web.xml でロールが定義されている場合は、ユーザーがそれらのロールの少なくとも 1 つを割り当てられている必要があることを意味する strictAuthOnly です。

transportGuaranteeRedirectStatus

構成されたトランスポート保証の要件を満たすために、コンテナが HTTP リダイレクトを発行する必要がある場合に使用する HTTP ステータスコード。提供されたステータスコードは検証されません。指定されていない場合、デフォルト値の 302 が使用されます。

LockOut Realm - org.apache.catalina.realm.LockOutRealm

LockOutRealmは、Tomcat Realmインターフェースの実装であり、CombinedRealmを拡張してロックアウト機能を提供し、一定期間に認証試行が多すぎる場合にユーザーロックアウトメカニズムを提供します。

正しく動作するように、このRealmにはある程度の同期があります。

このRealmでは、基になるRealmまたは関連するユーザーストレージメカニズムを変更する必要はありません。これは、存在しないユーザーのものを含む、すべての失敗したログインを記録することで実現されます。無効なユーザーで意図的にリクエストを作成することによってDOSを防止するために（したがって、このキャッシュが拡大します）、認証に失敗したユーザーのリストのサイズは制限されています。

サブリソースは、LockOutRealmを定義するRealm要素内にRealm要素をネストすることによって定義されます。認証は、リストされている順に各Realmに対して試行されます。Realmに対する認証は、ユーザーを認証するのに十分です。

LockOutRealmの実装は、次の追加属性をサポートしています。

属性	説明
`allRolesMode`	この属性は、web.xml での承認制約の処理時に、特別なロール名 `*` がどのように処理されるかを制御します。デフォルトでは、仕様に準拠した値の `strict` が使用されます。これは、ユーザーが web.xml で定義されたロールのいずれかを割り当てられている必要があることを意味します。代替値は、ユーザーが認証されている必要があるが、割り当てられたロールのチェックは行われないことを意味する `authOnly` と、ユーザーが認証されている必要があり、割り当てられたロールのチェックは行われないが、web.xml でロールが定義されている場合は、ユーザーがそれらのロールの少なくとも 1 つを割り当てられている必要があることを意味する `strictAuthOnly` です。
`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は、追加の検証なしに、提示されたユーザー名から常に作成されます。

注：提供された資格情報を検証しないAuthenticator実装でこのRealmを使用するのは安全ではありません。

AuthenticatedUserRealmの実装は、次の追加属性をサポートしています。

属性	説明
`transportGuaranteeRedirectStatus`	構成されたトランスポート保証の要件を満たすために、コンテナが HTTP リダイレクトを発行する必要がある場合に使用する HTTP ステータスコード。提供されたステータスコードは検証されません。指定されていない場合、デフォルト値の `302` が使用されます。

ネストされたコンポーネント

Realm要素内に対応する要素をネストすることにより、次のコンポーネントをネストできます。

CombinedRealmの実装 - CombinedRealmの実装、またはCombinedRealmを拡張するRealm（例：LockOutRealm）を使用している場合、1つ以上の<Realm>要素をその内部にネストできます。
CredentialHandler - Realm内にこの要素のインスタンスを最大で1つネストできます。これにより、提供された資格情報をRealmによって保存された資格情報と検証するために使用される資格情報ハンドラーが構成されます。指定されていない場合は、デフォルトのMessageDigestCredentialHandlerが構成されます。

特別な機能

仮想ホストのシングルサインオンサポートの構成については、シングルサインオンを参照してください。