javax.security.auth.login

クラス LoginContext

java.lang.Object

javax.security.auth.login.LoginContext

public class LoginContext
extends Object

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

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

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

呼び出し側は、LoginContext をインスタンス化すると、login メソッドを呼び出して Subject の認証を行います。login メソッドは構成済みモジュールを呼び出して、それぞれのタイプの認証 (ユーザー名/パスワードを使用した認証、スマートカードの PIN 認証など) を行います。認証に失敗しても、LoginModule は認証を再試行しません。また、遅延時間も発生しません。こうしたタスクは、LoginContext の呼び出し側が担当します。

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

Subject をログアウトさせる場合、呼び出し側は logout メソッドを呼び出します。login メソッドの場合と同様、この logout メソッドは構成済みモジュールの logout メソッドを呼び出します。

1 つの LoginContext で複数の Subject を認証することはできません。Subject ごとに別個の LoginContext を使用する必要があります。

次の内容は、すべての LoginContext コンストラクタに適用されます。

1. Subject
   • コンストラクタに Subject 入力パラメータが指定されている場合、LoginContext は呼び出し側で指定された Subject オブジェクトを使用する。

   • 呼び出し側が null Subject を指定した場合で、null 値が許可されているとき、LoginContext は新しい Subject をインスタンス化する。

   • コンストラクタに Subject 入力パラメータが指定されていない場合、LoginContext は新しい Subject をインスタンス化する。

2. Configuration
   • コンストラクタに Configuration 入力パラメータが指定されている場合で、呼び出し側が null 以外の Configuration を指定したとき、LoginContext は呼び出し側で指定された Configuration を使用する。

     コンストラクタに Configuration 入力パラメータが指定されていない場合、または呼び出し側が null Configuration オブジェクトを指定した場合、コンストラクタは次の呼び出しを使用してインストール済みの Configuration を取得する。

           config = Configuration.getConfiguration();
      

     どちらの場合も、コンストラクタに指定された name 引数は Configuration.getAppConfigurationEntry メソッドに渡される。Configuration が指定された name のエントリを持たない場合、LoginContext は、デフォルトのエントリ名である other で getAppConfigurationEntry を呼び出す。other のエントリが存在しない場合、LoginException がスローされる。

   • LoginContext がインストール済みの Configuration を使用する場合、呼び出し側は createLoginContext.name と、場合によっては createLoginContext.other という AuthPermission を必要とする。さらに、LoginContext は AccessController.doPrivileged から構成済みモジュールを呼び出す。これは、セキュリティー保護の必要があるタスク (リモートホストへの接続、Subject の更新など) を実行するモジュールはそれぞれアクセス権を必要とするが、LoginContext の呼び出し側はこれらのアクセス権なしで済むようにするためである。

   • LoginContext が呼び出し側で指定された Configuration を使用する場合、呼び出し側は createLoginContext AuthPermission を必要としない。LoginContext は呼び出し側に代わって AccessControlContext を保存し、そのコンテキストの制約を課された AccessController.doPrivileged 呼び出し内から構成済みモジュールを呼び出す。つまり、呼び出し側のコンテキスト (LoginContext の作成時に保存されたコンテキスト) は、モジュールが実行するセキュリティー保護を必要とするタスクの実行に必要なアクセス権を備えている必要がある。

3. CallbackHandler
   • コンストラクタに CallbackHandler 入力パラメータが指定されている場合、LoginContext は呼び出し側で指定された CallbackHandler オブジェクトを使用する。

   • コンストラクタに CallbackHandler 入力パラメータが指定されていない場合や、呼び出し側が null CallbackHandler オブジェクトを指定し、かつ null 値が許可されている場合、LoginContext は auth.login.defaultCallbackHandler セキュリティープロパティーに問い合わせてデフォルトのハンドラ実装の完全指定クラス名を取得する。このセキュリティープロパティーが設定されていない場合、ベースとなるモジュールはユーザーとの通信に使用する CallbackHandler を持たない。このため、呼び出し側は、構成済みモジュールが別の手段でユーザー認証を行うことができると想定する。

   • 上記のように呼び出し側で指定された Configuration を使用せず、インストール済み Configuration を使用する LoginContext は、呼び出し側で指定された (デフォルトの) CallbackHandler 実装を新しい CallbackHandler 実装でラップする必要がある。この新しい CallbackHandler 実装の handle メソッド実装は、呼び出し側の現在の AccessControlContext によって制約を課された java.security.AccessController.doPrivileged 呼び出し内で、指定された CallbackHandler の handle メソッドを呼び出す。

auth.login.defaultCallbackHandler などのセキュリティープロパティーは、java.security.Security クラスを使用してプログラムで設定するか、<JAVA_HOME>/lib/security/java.security ファイルとして格納されている Java セキュリティープロパティーファイルを使用して静的に設定することができます。<JAVA_HOME> は、java.home システムプロパティーの値を参照し、JRE のインストールディレクトリを指します。

関連項目:

Security、AuthPermission、Subject、CallbackHandler、Configuration、LoginModule

コンストラクタのサマリー

コンストラクタ

コンストラクタと説明
LoginContext(String name) 名前を指定して新しい LoginContext をインスタンス化します。
LoginContext(String name, CallbackHandler callbackHandler) 名前と CallbackHandler オブジェクトを指定して新しい LoginContext オブジェクトをインスタンス化します。
LoginContext(String name, Subject subject) 名前と Subject オブジェクトを指定して新しい LoginContext オブジェクトをインスタンス化します。
LoginContext(String name, Subject subject, CallbackHandler callbackHandler) 名前、認証を受ける Subject オブジェクト、および CallbackHandler オブジェクトを指定して、新しい LoginContext オブジェクトをインスタンス化します。
LoginContext(String name, Subject subject, CallbackHandler callbackHandler, Configuration config) 名前、認証を受ける Subject オブジェクト、CallbackHandler オブジェクト、およびログイン Configuration を指定して、新しい LoginContext オブジェクトをインスタンス化します。

メソッドのサマリー

メソッド

修飾子と型	メソッドと説明
Subject	getSubject() 認証された Subject を返します。
void	login() 認証を実行します。
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 をインスタンス化します。

パラメータ:

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

例外:

LoginException - 呼び出し側で指定された name が Configuration になく、other の Configuration エントリがない場合、または auth.login.defaultCallbackHandler セキュリティープロパティーは設定されているが、実装クラスをロードできなかった場合。

SecurityException - SecurityManager が設定されていて、呼び出し側が AuthPermission("createLoginContext.name") を持たない場合、または name の構成エントリが存在せず、呼び出し側が AuthPermission("createLoginContext.other") を持たない場合

LoginContext

public LoginContext(String name,
            Subject subject)
             throws LoginException

名前と Subject オブジェクトを指定して新しい LoginContext オブジェクトをインスタンス化します。

パラメータ:

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

subject - 認証対象の Subject。

例外:

LoginException - 呼び出し側で指定された name が Configuration になく、other の Configuration エントリがない場合、呼び出し側で指定された subject が null の場合、または auth.login.defaultCallbackHandler セキュリティープロパティーは設定されているが、実装クラスをロードできなかった場合。

SecurityException - SecurityManager が設定されていて、呼び出し側が AuthPermission("createLoginContext.name") を持たない場合、または name の構成エントリが存在せず、呼び出し側が AuthPermission("createLoginContext.other") を持たない場合

LoginContext

public LoginContext(String name,
            CallbackHandler callbackHandler)
             throws LoginException

名前と CallbackHandler オブジェクトを指定して新しい LoginContext オブジェクトをインスタンス化します。

パラメータ:

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

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

例外:

LoginException - 呼び出し側で指定された name が Configuration になく、other の Configuration エントリがない場合、または呼び出し側で指定された callbackHandler が null の場合。

SecurityException - SecurityManager が設定されていて、呼び出し側が AuthPermission("createLoginContext.name") を持たない場合、または name の構成エントリが存在せず、呼び出し側が AuthPermission("createLoginContext.other") を持たない場合

LoginContext

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

名前、認証を受ける Subject オブジェクト、および CallbackHandler オブジェクトを指定して、新しい LoginContext オブジェクトをインスタンス化します。

パラメータ:

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

subject - 認証対象の Subject。

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

例外:

LoginException - 呼び出し側で指定された name が Configuration になく、other の Configuration エントリがない場合、呼び出し側で指定された subject が null の場合、または呼び出し側で指定された callbackHandler が null の場合。

SecurityException - SecurityManager が設定されていて、呼び出し側が AuthPermission("createLoginContext.name") を持たない場合、または name の構成エントリが存在せず、呼び出し側が AuthPermission("createLoginContext.other") を持たない場合

LoginContext

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

名前、認証を受ける Subject オブジェクト、CallbackHandler オブジェクト、およびログイン Configuration を指定して、新しい LoginContext オブジェクトをインスタンス化します。

パラメータ:

name - 呼び出し側で指定された Configuration のインデックスとして使用される名前。

subject - 認証対象の Subject、または null。

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

config - 認証を行うために呼び出されるログインモジュールのリストである Configuration、または null。

例外:

LoginException - 呼び出し側で指定された name が Configuration に存在せず、other の Configuration エントリがない場合。

SecurityException - SecurityManager が設定されており、config が null で、呼び出し側が AuthPermission("createLoginContext.name") を持たない場合、または name の構成エントリが存在せず、呼び出し側が AuthPermission("createLoginContext.other") を追加で持たない場合。

導入されたバージョン:

1.5

メソッドの詳細

login

public void login()
           throws LoginException

認証を実行します。

このメソッドは、ログイン Configuration の定義に従い、LoginContext コンストラクタに指定された name に合わせて設定された各 LoginModule に対して login メソッドを呼び出します。各 LoginModule は次に、それぞれのタイプの認証 (ユーザー名/パスワードの認証、スマートカードの PIN 認証など) を実行します。

このメソッドでは、認証全体が成功した場合 (関連する 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。呼び出し側がこの LoginContext のコンストラクタに Subject を指定した場合、このメソッドは呼び出し側で指定された Subject を返す。Subject が指定されておらず、認証が成功した場合、このメソッドは、インスタンス化され、この LoginContext による認証に使用される Subject を返す。Subject が指定されておらず、認証が失敗した場合、または認証が行われなかった場合、このメソッドは null を返す。