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

public interface LoginModule

LoginModule では、認証テクノロジプロバイダが実装するインタフェースを記述します。LoginModule をアプリケーションにプラグインすることにより、特定の認証タイプを提供できます。

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

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

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

呼び出すアプリケーションは、認証プロセスを単一操作と見なします。しかし、LoginModule 内の認証プロセスは、2 つの別なフェーズで処理されます。最初のフェーズでは、LoginModule の login メソッドが、LoginContext の login メソッドによって呼び出されます。LoginModule の login メソッドでは実際の認証 (たとえばパスワードの入力を求め、検証する) を実行し、認証状態を非公開状態情報として保存します。終わると、LoginModule の login メソッドでは true (成功した場合) または false (無視できない場合) を返すか、LoginException をスローして失敗を指定します。失敗した場合、LoginModule で認証を再試行したり猶予したりしないでください。この種の処理はアプリケーションが行います。アプリケーションで認証を再試行する場合は、LoginModule の login メソッドがもう一度呼び出されます。

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

LoginContext の認証全体が失敗した (関連する REQUIRED、REQUISITE、SUFFICIENT、OPTIONAL の LoginModule が成功しなかった) 場合、それぞれの LoginModule に対して abort メソッドが呼び出されます。この場合、LoginModule はいったん保存されていた認証状態を削除または破棄します。

Subject のログアウトには、1 フェーズだけが含まれます。LoginContext は、LoginModule の 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 - 認証対象の Object

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 - ログアウトに失敗した場合