javax.security.auth.spi
インタフェース LoginModule

public interface LoginModule

LoginModule は、認証技術のプロバイダにより実装されるインタフェースを記述します。ログインモジュールは特定タイプの認証を提供するアプリケーションへプラグインされます。

アプリケーションが LoginContext API を呼び出す一方で、認証テクノロジプロバイダは LoginModule インタフェースを実装します。Configuration では、特定のログインアプリケーションで使用される LoginModule を指定します。このため、アプリケーション自体を変更せずに、複数の異なるログインモジュールをプラグインとしてアプリケーションで使用できます。

LoginContext は、Configuration の読み取りおよび適切なログインモジュールのインスタンス化を実行します。各 LoginModule は、Subject、CallbackHandler、共有 LoginModule 状態、および LoginModule 固有のオプションを使用して、初期化されます。 Subject は、現在認証中の Subject を表し、認証に成功すると、関連する Credential で更新されます。LoginModule では CallbackHandler を使用してユーザーと通信します。たとえばユーザー名とパスワードの入力を求めるときに、CallbackHandler を使用します。CallbackHandler は null の場合もあることに留意してください。Subject を認証するために必ず CallbackHandler が必要な LoginModule では、LoginException をスローすることがあります。また、共有状態を使用して、複数のログインモジュール間で情報を共有することもできます (オプション)。

LoginModule 固有のオプションは、管理者やユーザーがログイン Configuration 内で設定する、この LoginModule 用に構成したオプションを表します。これらのオプションは、ログインモジュール自体により定義されます。またその動作制御は、ログインモジュールの内部で行われます。たとえば、ログインモジュールでデバッグ/テスト機能をサポートするオプションを定義する場合を考えましょう。オプションの定義では、鍵と値で構成される構文 (debug=true など) が使用されます。ログインモジュールは、キーを使って値を取得できるよう、オプションを Map として格納します。ログインモジュールが定義可能なオプションの数に制限はありません。

呼び出し側のアプリケーションは、認証プロセスを単一の操作と見なします。ただし、LoginModule 内部の認証プロセスは、明確な 2 つのフェーズに分かれています。最初のフェーズでは、ログインモジュールの login メソッドが、ログインコンテキストの login メソッドにより呼び出されます。次に、 LoginModule の login メソッドは、実際の認証を実行してから (たとえば、パスワードの入力を促し、入力されたパスワードを検証する)、認証ステータスを専用状態情報として保存します。終わると、LoginModule の login メソッドでは true (成功した場合) または false (無視できない場合) を返すか、LoginException をスローして失敗を指定します。障害が発生した場合、ログインモジュールは認証を再試行できません。また、遅延の発生も認められません。これらのタスクの実行は、アプリケーションが担当します。アプリケーションが認証の再実行を試みると、ログインモジュールの login が再度呼び出されます。

2 番目のフェーズでは、LoginContext の認証全体が成功した場合 (関連する REQUIRED、REQUISITE、SUFFICIENT、OPTIONAL の LoginModule が成功)、LoginModule の commit メソッドが呼び出されます。ログインモジュールの commit メソッドは、非公開での保存状態をチェックして、認証が成功したかどうかを確認します。LoginContext 全体の認証に成功し、LoginModule 自体の認証に成功した場合は、commit メソッドによって関連する Principal (認証された識別情報) と Credential (暗号化鍵などの認証データ) が、LoginModule 内にある Subject と関連付けられます。

ログインコンテキストの認証全体が失敗した (関連する REQUIRED、REQUISITE、SUFFICIENT、および OPTIONAL ログインモジュールが成功しなかった) 場合、各 LoginModule の abort メソッドが呼び出されます。この場合、LoginModule は、当初保存されていた認証状態をすべて削除/破棄します。

Subject のログアウトには、1 つのフェーズだけが関係しています。LoginContext は、ログインモジュールの logout メソッドを呼び出します。LoginModule の logout メソッドは、ログアウト処理を実行し、Principal や Credential を Subject から削除したり、セッション情報を記録したりします。

LoginModule の実装は、引数なしのコンストラクタを提供する必要があります。これにより、LoginModule をロードするクラスは、LoginModule をインスタンス化できます。

関連項目:

LoginContext, Configuration

メソッドの概要

boolean	abort() 認証プロセスを中止するメソッドです (フェーズ 2)。
boolean	commit() 認証プロセスをコミットするメソッドです (フェーズ 2)。
void	initialize(Subject subject, CallbackHandler callbackHandler, Map<String,?> sharedState, Map<String,?> options) この LoginModule を初期化します。
boolean	login() Subject を認証するメソッドです (フェーズ 1)。
boolean	logout() Subject をログアウトさせるメソッドです。

メソッドの詳細

initialize

void initialize(Subject subject,
                CallbackHandler callbackHandler,
                Map<String,?> sharedState,
                Map<String,?> options)

この LoginModule を初期化します。

この LoginModule がインスタンス化されてから、LoginContext によって呼び出されます。このメソッドの目的は、この LoginModule を関連情報で初期化することです。この LoginModule が sharedState パラメータや options パラメータに格納された情報を認識できない場合、それらの情報は無視されます。

パラメータ:

subject - 認証を受ける Subject

callbackHandler - エンドユーザーとの通信 (ユーザー名とパスワードの入力など) に使用される CallbackHandler

sharedState - 構成されたほかの LoginModule と共有する状態

options - この LoginModule 用にログイン Configuration で指定されたオプション

login

boolean login()
              throws LoginException

Subject を認証するメソッドです (フェーズ 1)。

このメソッドの実装では、Subject を認証します。たとえば、ユーザー名やパスワードといった Subject の情報の入力を求めてから、パスワードを検証します。このメソッドでは認証の試行結果を、LoginModule 内に非公開状態として保存します。

戻り値:

認証に成功した場合は true。 この LoginModule が無視される場合は false

例外:

LoginException - 認証に失敗した場合

commit

boolean commit()
               throws LoginException

認証プロセスをコミットするメソッドです (フェーズ 2)。

LoginContext の認証全体が成功した場合 (関連する REQUIRED、REQUISITE、SUFFICIENT、および OPTIONAL の各 LoginModule が成功した場合) に呼び出されます。

この LoginModule 自体の認証に成功した場合は (login メソッドで保存された非公開状態を取得して調べる)、このメソッドによって関連する Principal と Credential が、LoginModule 内にある Subject に関連付けられます。この LoginModule 自体の認証に失敗した場合は、いったん保存されていた状態を削除または破棄します。

戻り値:

このメソッドが成功した場合は true。 この LoginModule が無視される場合は false

例外:

LoginException - コミットに失敗した場合

abort

boolean abort()
              throws LoginException

認証プロセスを中止するメソッドです (フェーズ 2)。

LoginContext の認証全体が失敗した場合 (関連する REQUIRED、REQUISITE、SUFFICIENT、および OPTIONAL の各 LoginModule が失敗した場合) に呼び出されます。

この LoginModule 自体の認証に成功した場合は (login メソッドで保存された非公開状態を取得して調べる)、一旦保存されていた状態がこのメソッドによってクリーンアップされます。

戻り値:

このメソッドが成功した場合は true。 この LoginModule が無視される場合は false

例外:

LoginException - 中止に失敗した場合

logout

boolean logout()
               throws LoginException

Subject をログアウトさせるメソッドです。

このメソッドの実装では、Subject の Principal と Credential を削除または破棄します。

戻り値:

このメソッドが成功した場合は true。 この LoginModule が無視される場合は false

例外:

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