モジュール java.base

パッケージ 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メソッドを呼び出す。

導入されたバージョン:

1.4

関連項目:

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を返す。