javax.security.auth.login
クラス LoginContext

java.lang.Object
  |
  +--javax.security.auth.login.LoginContext

public class LoginContext

extends Object

LoginContext クラスは、Subject を認証するための基本的なメソッドを記述し、基本となる認証テクノロジに依存しないアプリケーション開発の方法を提供します。Configuration は、アプリケーションで使用される認証テクノロジ (LoginModule) を指定します。そのため、アプリケーション自体に変更を加えることなく、アプリケーションに異なる LoginModule をプラグインすることができます。

このクラスは、プラグイン可能な認証をサポートするだけでなく、スタックされた認証の概念もサポートします。言い換えると、アプリケーションでは LoginModule を 1 つ以上使用するように構成できます。たとえば、1 つのアプリケーションで Kerberos LoginModule とスマートカード LoginModule の両方を構成できます。

通常の呼び出し側は、このクラスを初期化して name と CallbackHandler に渡します。LoginContext では name を Configuration のインデックスとして使用し、使用されている LoginModule や、認証全体が成功するために成功しなければならない LoginModule を判定します。CallbackHandler は基本となる LoginModule に渡され、LoginModule はユーザとのやりとり (グラフィカルユーザインタフェースでユーザ名とパスワードの入力を求めるなど) を行います。

呼び出し側が LoginContext を初期化すると、login メソッドを呼び出して Subject を認証します。この login メソッドは、呼び出し側が指定した name 用に構成された各 LoginModule から login メソッドを呼び出します。そして、各 LoginModule ではそれぞれの認証タイプを実行します (ユーザ名とパスワード、スマートカード PIN 認証など)。認証が失敗した場合に、LoginModule では認証を再試行したり、猶予を与えたりしません。この種の処理は呼び出し側が行います。

認証全体が成功したかどうかにかかわらず、この login メソッドでは、構成された各 LoginModule に対して commit メソッドか abort メソッドを呼び出すことで、2 フェーズの認証プロセスを完了します。認証全体が成功した場合は、各 LoginModule に対して commit メソッドが呼び出され、認証全体が失敗した場合は、各 LoginModule に対して abort メソッドが呼び出されます。成功した各 LoginModule の commit では、関連する Principal (認証された識別情報) と Credential (暗号化鍵などの認証データ) が、Subject と関連付けられます。各 LoginModule の abort メソッドは、先に格納された認証状態をクリーンアップ、または削除/破棄します。

login メソッドが例外をスローすることなく返ってきた場合は、認証全体に成功したことになります。そして、呼び出し側は getSubject メソッドを呼び出すことで、新たに認証された Subject を取得できます。Subject と関連付けられた Principal と Credential は、Subject の getPrincipals、getPublicCredentials、および getPrivateCredentials の各メソッドを呼び出すことで取得できます。

Subject をログアウトさせるには、呼び出し側で logout メソッドを呼び出すだけですみます。login メソッドと同様にこの logout メソッドでは、この LoginContext 用に構成された各 LoginModule の logout メソッドを呼び出します。各 LoginModule の logout メソッドは、状態をクリーンアップし、Subject から Principal と Credential を適切に削除または破棄します。

LoginContext によって呼び出された構成済みの各 LoginModule では、認証を受ける Subject、ユーザと通信するための CallbackHandler、共有 LoginModule 状態、および LoginModule 固有のオプションで初期化されます。LoginContext が Subject に渡されない場合は、自分自身をインスタンス化します。

ユーザの認証に成功した各 LoginModule では、Subject を関連するユーザ情報 (Principal と Credential) で更新します。この Subject は、認証全体が成功した場合に、LoginContext クラスの getSubject メソッドによって返されます。LoginModule は、AccessController.doPrivileged 呼び出しの内部から常に呼び出されます。そのため、セキュリティ上重要な作業 (リモートホストに接続するなど) を実行する LoginModule で、セキュリティ Policy の関連する Permission の付与が必要であっても、LoginModule の呼び出し側に、これらの Permission は必要ありません。

LoginContext では、呼び出しアプリケーションによる認証の再試行をサポートしています。たとえば、ユーザがパスワードを誤って入力した場合、LoginContext の login メソッドを複数回呼び出すことができます。ただし、1 つの LoginContext を複数の Subject を認証するために使用することはできません。別々の Subject を認証するには、別の LoginContext を使用しなければなりません。

同じ LoginContext の複数回呼び出しは、LoginModule の状態や LoginModule 固有のオプションに影響を与えません。

関連項目:

Subject, CallbackHandler, Configuration, LoginModule

コンストラクタの概要

LoginContext(String name)
LoginContext クラスのコンストラクタです。

LoginContext(String name, CallbackHandler callbackHandler)
LoginContext クラスのコンストラクタです。

LoginContext(String name, Subject subject)
LoginContext クラスのコンストラクタです。

LoginContext(String name, Subject subject, CallbackHandler callbackHandler)
LoginContext クラスのコンストラクタです。

メソッドの概要

Subject	getSubject() 認証された Subject を返します。
void	login() 認証を実行し、成功した場合は、Principal と Credential を認証した Subject と関連付けます。
void	logout() Subject をログアウトします。

クラス java.lang.Object から継承したメソッド

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

コンストラクタの詳細

LoginContext

public LoginContext(String name)
             throws LoginException

LoginContext クラスのコンストラクタです。

新しい LoginContext を名前で初期化します。LoginContext では、指定した名前を Configuration のインデックスとして使用し、使用されている LoginModule を判定します。指定した名前が Configuration 内の名前と一致しない場合は、デフォルトの Configuration エントリである other を使用します。other の Configuration エントリがない場合は、LoginException がスローされます。

このコンストラクタでは、CallbackHandler を受け付けません。auth.login.defaultCallbackHandler セキュリティプロパティがデフォルトの CallbackHandler 実装クラスの完全修飾名に設定されている場合、その CallbackHandler がロードされ、基本となる LoginModule に渡されます。セキュリティプロパティが設定されていない場合、基本となる LoginModule はユーザと通信するために使用する CallbackHandler を持たないことになります。そのため、呼び出し側では、構成済みの LoginModule に、ユーザを認証する代替方法があると見なします。

auth.login.defaultCallbackHandler セキュリティプロパティは、<JAVA_HOME>/lib/security/java.security というファイルにある Java セキュリティプロパティファイルで設定します。<JAVA_HOME> は、SDK がインストールされたディレクトリです。

このコンストラクタでは Subject を指定できないため、Subject は Subject 自体をインスタンス化します。

パラメータ:

name - Configuration のインデックスとして使用される名前

例外:

LoginException - 指定した name が Configuration になく、other という Configuration エントリがない場合、あるいは、auth.login.defaultCallbackHandler セキュリティプロパティが設定されているにもかかわらず、実装クラスがロードできなかった場合

LoginContext

public LoginContext(String name,
                    Subject subject)
             throws LoginException

LoginContext クラスのコンストラクタです。

新しい LoginContext オブジェクトを名前と Subject オブジェクトで初期化します。

LoginContext では、名前を Configuration のインデックスとして使用し、使用されている LoginModule を判定します。指定した名前が Configuration 内の名前と一致しない場合は、デフォルトの Configuration エントリである other を使用します。other の Configuration エントリがない場合は、LoginException がスローされます。

このコンストラクタでは、CallbackHandler を受け付けません。auth.login.defaultCallbackHandler セキュリティプロパティがデフォルトの CallbackHandler 実装クラスの完全修飾名に設定されている場合、その CallbackHandler がロードされ、基本となる LoginModule に渡されます。セキュリティプロパティが設定されていない場合、基本となる LoginModule はユーザと通信するために使用する CallbackHandler を持たないことになります。そのため、呼び出し側では、構成済みの LoginModule に、ユーザを認証する代替方法があると見なします。

auth.login.defaultCallbackHandler セキュリティプロパティは、<JAVA_HOME>/lib/security/java.security というファイルにある Java セキュリティプロパティファイルで設定します。<JAVA_HOME> は、SDK がインストールされているディレクトリです。

LoginContext は Subject オブジェクトを構成済みの LoginModule に渡します。これにより、LoginModule は、認証を追加実行したり、新しい Principal と Credential で Subject を更新することができます。

パラメータ:

name - Configuration のインデックスとして使用される名前

subject - 認証対象の Object

例外:

LoginException - 指定した name が Configuration になく、other という Configuration エントリがない場合、指定した subject が null の場合、あるいは、auth.login.defaultCallbackHandler セキュリティプロパティが設定されているにもかかわらず、実装クラスがロードできなかった場合

LoginContext

public LoginContext(String name,
                    CallbackHandler callbackHandler)
             throws LoginException

LoginContext クラスのコンストラクタです。

新しい LoginContext オブジェクトを名前と CallbackHandler オブジェクトで初期化します。

LoginContext では、名前を Configuration のインデックスとして使用し、使用されている LoginModule を判定します。指定した名前が Configuration 内の名前と一致しない場合は、デフォルトの Configuration エントリである other を使用します。other の Configuration エントリがない場合は、LoginException がスローされます。

LoginContext は CallbackHandler オブジェクトを構成済みの LoginModule に渡すため、LoginModule はユーザとやりとりできます。そのため、CallbackHandler オブジェクトでは、LoginModule を、アプリケーションがユーザとやりとりする方法とは無関係なままにできます。この LoginContext はアプリケーションが提供する CallbackHandler を新しい CallbackHandler 実装でラップできます。この新しい CallbackHandler 実装の handle メソッド実装では、アプリケーションが提供する CallbackHandler の handle メソッドの呼び出しを、呼び出し側の現在の AccessControlContext に制約を受けている java.security.AccessController.doPrivileged 呼び出し内で実行します。

このコンストラクタでは Subject を指定できないため、Subject は Subject 自体をインスタンス化します。

パラメータ:

name - Configuration のインデックスとして使用される名前

callbackHandler - LoginModule がユーザとやりとりするために使用する CallbackHandler オブジェクト

例外:

LoginException - 指定した name が Configuration になく、other という Configuration エントリがない場合、あるいは指定した callbackHandler が null の場合

LoginContext

public LoginContext(String name,
                    Subject subject,
                    CallbackHandler callbackHandler)
             throws LoginException

LoginContext クラスのコンストラクタです。

新しい LoginContext オブジェクトを名前、認証を受ける Subject オブジェクト、および CallbackHandler オブジェクトで初期化します。

LoginContext では、名前を Configuration のインデックスとして使用し、使用されている LoginModule を判定します。指定した名前が Configuration 内の名前と一致しない場合は、デフォルトの Configuration エントリである other を使用します。other の Configuration エントリがない場合は、LoginException がスローされます。

LoginContext は Subject オブジェクトを構成済みの LoginModule に渡します。これにより、LoginModule は、認証を追加実行したり、新しい Principal と Credential で Subject を更新することができます。

LoginContext は CallbackHandler オブジェクトを構成済みの LoginModule に渡すため、LoginModule はユーザとやりとりできます。そのため、CallbackHandler オブジェクトでは、LoginModule を、アプリケーションがユーザとやりとりする方法とは無関係なままにできます。この LoginContext はアプリケーションが提供する CallbackHandler を新しい CallbackHandler 実装でラップできます。この新しい CallbackHandler 実装の handle メソッド実装では、アプリケーションが提供する CallbackHandler の handle メソッドの呼び出しを、呼び出し側の現在の AccessControlContext に制約を受けている java.security.AccessController.doPrivileged 呼び出し内で実行します。

パラメータ:

name - Configuration のインデックスとして使用される名前

subject - 認証対象の Object

callbackHandler - LoginModule がユーザとやりとりするために使用する CallbackHandler オブジェクト

例外:

LoginException - 指定した name が Configuration になく、other という Configuration エントリがない場合、指定した subject が null の場合、あるいは指定した callbackHandler が null の場合

メソッドの詳細

login

public void login()
           throws LoginException

認証を実行し、成功した場合は、Principal と Credential を認証した Subject と関連付けます。

このメソッドでは、ログイン Configuration で定義された、LoginContext コンストラクタに渡された name 用に構成された各 LoginModule の login メソッドを呼び出します。そして、各 LoginModule では、それぞれの認証タイプを実行します (ユーザ名とパスワード、スマートカード PIN 認証など)。

このメソッドでは、LoginContext の認証全体が成功した場合 (関連する REQUIRED、REQUISITE、SUFFICIENT、OPTIONAL の各 LoginModule が成功) に構成済みの LoginModule に対して commit メソッドを呼び出すか、認証全体が失敗した場合に構成済みの各 LoginModule に対して abort メソッドを呼び出すことで、2 フェーズの認証プロセスが完了します。認証に成功した場合は、成功した各 LoginModule の commit メソッドによって、関連する Principal と Credential が、Subject と関連付けられます。認証に失敗した場合は、各 LoginModule の abort メソッドによって、元々保存されていた状態を削除または破棄します。

認証プロセスの commit フェーズに失敗すると認証全体が失敗し、このメソッドは構成済みの各 LoginModule に対して abort メソッドを呼び出します。

どのような理由で abort フェーズが失敗しても、login フェーズ中や commit フェーズ中にスローされた元の例外を伝達します。どちらの場合も、認証全体が失敗します。

複数の LoginModule で失敗した場合、最初に失敗した LoginModule で発生した例外を伝達します。

このメソッドが abort フェーズに入った (login フェーズや commit フェーズに失敗した) 場合は、指定したアプリケーション用に構成されたすべての LoginModule を、それぞれの Configuration フラグパラメータに関係なく、呼び出します。原則として、abort フェーズ中は、Requisite と Sufficient の持つ意味は無視されます。これにより、適切なクリーンアップと状態の復元を行うことが保証されます。

例外:

LoginException - 認証に失敗した場合

logout

public void logout()
            throws LoginException

Subject をログアウトします。

このメソッドは、この LoginContext 用に構成された各 LoginModule の logout メソッドを呼び出します。各 LoginModule は、それぞれのログアウト処理を行います。ログアウト処理には、Subject からの Principal や Credential の削除/破棄や、状態のクリーンアップなどが含まれます。

このメソッドでは、指定したアプリケーション用に構成されたすべての LoginModule を、それぞれの Configuration フラグパラメータに関係なく呼び出します。原則として、このメソッドでは、Requisite と Sufficient の持つ意味は無視されます。これにより、適切なクリーンアップと状態の復元を行うことが保証されます。

例外:

LoginException - ログアウトに失敗した場合

getSubject

public Subject getSubject()

認証された Subject を返します。

戻り値:

認証された Subject。認証に失敗し、Subject がこの LoginContext のコンストラクタに渡されない場合、このメソッドは null を返す。そうでない場合は、渡された Subject を返す