• initialize

• login

• commit

• abort

• logout

LoginModule実装は、これらのメソッドに加え、引数をとらないpublicのコンストラクタを提供する必要があります。このことにより、LoginContextによるインスタンス化が適切に行われるようになります。LoginModule実装でこの種のコンストラクタが提供されない場合、引数を取らないデフォルト・コンストラクタが自動的にObjectクラスから継承されます。

LoginModule.initializeメソッド

    public void initialize(
        Subject subject,
        CallbackHandler handler,
        Map<java.lang.String, ?> sharedState,
        Map<java.lang.String, ?> options);

initializeメソッドが呼び出され、関連する認証および状態情報でLoginModuleの初期化が行われます。

このメソッドは、LoginModuleをインスタンス化したあと(かつほかのpublicメソッドを呼び出す前)、すぐにLoginContextにより呼び出されます。このメソッド実装は、将来の使用に備えて指定された引数を格納します。

initializeメソッドはさらに、指定されたsharedStateを調べて、他のLoginModuleから提供された追加の認証状態を特定し、指定されたoptionsも詳しく調べて、LoginModuleの動作に影響を与えるように指定された構成オプションを特定します。将来の使用に備えて、変数内にオプションの値を保存することもできます。

次に示すのは、LoginModuleがサポートする一般的なオプションの一覧です。ただし、これはガイドラインにすぎません。モジュールは、次のオプションのサブセットを随意サポートします。

• tryFirstPass - trueの場合、スタック内の最初のLoginModuleが入力されたパスワードを保存し、それ以降のLoginModulesもこれを使用することを試みます。認証に失敗した場合、LoginModuleは新しいパスワードを要求し、認証を再試行します。
• useFirstPass - trueの場合、スタック内の最初のLoginModuleが入力されたパスワードを保存し、それ以降のLoginModulesもこれを使用することを試みます。LoginModuleは、認証に失敗しても新しいパスワードを要求しません。
• tryMappedPass - trueの場合、スタック内の最初のLoginModuleが入力されたパスワードを保存し、それ以降のLoginModulesはこれをサービス固有のパスワードにマッピングすることを試みます。認証に失敗した場合、LoginModuleは新しいパスワードを要求し、認証を再試行します。
• useMappedPass - trueの場合、スタック内の最初のLoginModuleが入力されたパスワードを保存し、それ以降のLoginModulesはこれをサービス固有のパスワードにマッピングすることを試みます。LoginModuleは、認証に失敗しても新しいパスワードを要求しません。
• moduleBanner - trueの場合、LoginModuleは、CallbackHandlerの呼出し時に最初のCallbackとしてTextOutputCallbackを提供します。このCallbackには、認証を実行しているLoginModuleに関する情報が記述されます。
• debug - trueの場合、LoginModuleに対してデバッグ情報の出力を指示します。

initializeメソッドは、認識できない状態やオプションを無視できます。ただし、この種のイベントが発生した場合、それを記録する方が望ましい場合もあります。

このLoginModule (およびその他の構成済LoginModule)を呼び出すLoginContextはすべて、指定されたSubjectおよびsharedStateへの同一の参照を共有します。SubjectおよびsharedStateへの変更は、すべてが認識します。

LoginModule.loginメソッド

    boolean login() throws LoginException;

loginメソッドが呼び出され、Subjectの認証が行われます。これが認証の第1フェーズです。

このメソッド実装は、実際の認証を実行します。たとえば、ユーザー名およびパスワードの入力を求めてから、パスワード・データベースに対しパスワードの検証を試みます。別のサンプル実装として、フィンガプリント・リーダーに指を挿入するようユーザーに指示し、入力されたフィンガ・プリントをフィンガプリント・データベースと照合する場合が考えられます。

LoginModuleがなんらかのユーザーとの通信の形式を必要とする(ユーザー名とパスワードの取得など)場合は、それを直接実行しないでください。それは、ユーザーとの様々な通信方法が存在するためであり、LoginModuleが様々なユーザーとの通信のタイプから独立させておくことが望ましいです。それよりも、LoginModuleのloginメソッドから、initializeメソッドに渡されたCallbackHandlerインタフェースのhandleメソッドを呼び出して、ユーザーと通信し、適切な結果(ユーザー名、パスワードなど)を設定するようにしてください。LoginModuleはCallbackHandlerに適切なCallback (ユーザー名に対してはNameCallback 、パスワードに対してはPasswordCallback )からなる配列を渡し、CallbackHandlerは要求に従ってユーザーと通信し、Callback内に適切な値を設定します。たとえば、NameCallbackを処理する場合、CallbackHandlerはユーザーから名前を取得し、NameCallbackのsetNameメソッドを呼び出してその名前を格納します。

認証プロセスに、ネットワーク経由の通信が含まれる場合もあります。たとえば、このメソッド実装がKerberosのkinitと等価な機能を実行する場合、KDCとのコンタクトが必要になります。パスワード・データベースのエントリがリモート・ネーム・サービス内に存在する場合、Java Naming and Directory Interface (JNDI)を利用するなどして、そのネーム・サービスとコンタクトを取る必要があります。実装は、基盤となるオペレーティング・システムと通信する必要もあります。たとえば、ユーザーがLinux、macOS、Windowsなどのオペレーティング・システムにすでにログインしている場合、このメソッドは基盤となるオペレーティング・システムの識別情報を単にインポートします。

loginメソッドは、次の処理を行う必要があります。

1. このLoginModuleを無視するかどうかを決定します。たとえば、ユーザーがこのLoginModuleと無関係な識別情報を使って認証を試みた場合(たとえば、ユーザーがNISを使い、rootで認証を試みた場合)は、LoginModuleを無視する必要があります。このLoginModuleを無視する必要がある場合、loginの戻り値はfalseになります。それ以外の場合、次の処理を行います。
2. ユーザーとの通信が必要な場合はCallbackHandlerのhandleメソッドを呼び出します。
3. 認証を実行します。
4. 認証結果(成功または失敗)を格納します。
5. 認証に成功した場合は、関連状態情報をすべて保存します。この情報は、commitメソッドで使用される可能性があります。
6. 認証に成功した場合はtrueを返し、認証に失敗した場合はLoginException (FailedLoginExceptionなど)をスローします。

loginメソッド実装が、新規Principalまたはクレデンシャル情報を保存済みのSubjectオブジェクトに関連付けることはできません。このメソッドは、認証のみを実行して、認証結果および対応する認証状態を格納します。あとで、commitまたはabortメソッドからこの結果および状態へのアクセスが行われます。結果および状態は、ほかのLoginModuleと共有ではないので、通常、sharedState Mapには保存できません。

たとえば、LoginModuleがパスワードを共有するように構成されている場合であれば、このメソッドにとって、sharedStateのMapに状態情報を保存することは有利です。この場合、入力されたパスワードは、共有状態として保存されます。パスワードの共有により、パスワードを1回入力するだけで後続のLoginModuleでも認証された状態を維持できます。次に、sharedStateのMapから名前とパスワードを格納および保存する際の標準的な規約を示します。

• javax.security.auth.login.name - 名前を保存/取得するための共有状態マップ・キーとして使用。値はStringである必要があります。
• javax.security.auth.login.password - パスワードを保存/取得するための共有状態マップ・キーとして使用。値はchar配列である必要があります。

認証に失敗した場合、loginメソッドは認証を再試行できません。この処理はアプリケーションが担当します。LoginModule.login()内から何度もログインを試みるよりも、アプリケーションから繰り返しLoginContextのloginメソッドを呼び出すことをお薦めします。

LoginModule.commitメソッド

    boolean commit() throws LoginException;

commitメソッドが呼び出され、認証プロセスがコミットされます。これは、第1認証フェーズが成功した場合の第2認証フェーズです。LoginContext全体の認証が成功した場合(関連するREQUIRED、REQUISITE、SUFFICIENT、およびOPTIONALのLoginModuleが成功した場合)に呼び出されます。

このメソッドは、loginメソッドにより保存された認証結果および対応する認証状態にアクセスします。

認証結果からloginメソッドの失敗が明らかになった場合、commitメソッドは最初に保存された対応する状態をすべて削除/破棄します。

保存された結果からLoginModuleのloginメソッドの成功が明らかになった場合は、対応する状態情報から関連するPrincipalおよびクレデンシャルの情報が構築されます。このPrincipalおよびクレデンシャルの情報が、initializeメソッドによって格納されたSubjectに追加されます。

Principalおよびクレデンシャルの追加後は、不要な状態フィールドを迅速に破棄する必要があります。たとえば、認証プロセスで格納されたユーザー名やパスワードは破棄されます。

commitメソッドは、コミットの成功または失敗を示す非公開の状態を保存する必要があります。

次に、LoginModuleのcommitメソッドから返される結果を図示します。各ボックスは、発生する可能性がある各種の状況を表します。たとえば、上部左側のボックスは、以前のloginメソッド呼出しとcommitメソッド自体の呼出しに成功した場合に返されるcommitメソッドの結果を示しています。

LoginModule.abortメソッド

    boolean abort() throws LoginException;

abortメソッドが呼び出され、認証プロセスが強制的に中断されます。これは、第1認証フェーズが失敗した場合の第2認証フェーズです。これは、LoginContextの全体の認証に失敗した場合に呼び出されます。

このメソッドは、最初に、loginメソッド(および場合によりcommitメソッド)によって保存されているLoginModuleの認証結果および対応する認証状態にアクセスし、情報をクリアおよび破棄します。たとえば、ユーザー名およびパスワードは破棄されます。

LoginModuleの認証に失敗した場合、非公開の状態を消去する必要は生じません。

次に、LoginModuleのabortメソッドから返される結果を図示します。最初の図は、以前のlogin呼出しが成功したことを想定しています。たとえば、abortメソッドは、以前のlogin呼出しとcommit呼出しに成功し、さらにabortメソッド自体も成功した場合は、TRUEを返します。

2番目の図は、以前のloginメソッドの呼出しに失敗した場合に返されるLoginModuleのabortメソッドの結果を示しています。たとえば、abortメソッドは、以前のlogin呼出しには失敗し、以前のcommit呼出しには成功し、さらにabortメソッド自体も成功した場合は、FALSEを返します。

LoginModule.logoutメソッド

    boolean logout() throws LoginException;

logoutメソッドが呼び出され、Subjectからログアウトします。

このメソッドは、Principalを削除し、commit操作中にSubjectに関連付けられたクレデンシャルを削除/破棄します。このメソッドは、Subject内の既存のPrincipalやクレデンシャル、またはほかのLoginModuleによって追加されたPrincipalやクレデンシャルに対しては、一切の操作を実行できません。

Subjectが読取り専用 (SubjectのisReadOnlyメソッドがtrueを返す)の場合、このメソッドはcommit操作中にSubjectに関連付けられているクレデンシャルのみを破棄します(クレデンシャルを削除することはできません)。Subjectが読取り専用であり、commit操作中にSubjectと関連付けられたクレデンシャルを破棄できない(このクレデンシャルがDestroyableインタフェースを実装していない)場合、このメソッドはLoginExceptionをスローする可能性があります。

logoutメソッドは、ログアウトに成功した場合はtrueを返し、それ以外の場合はLoginExceptionをスローします。

ステップ6a: LoginModuleとアプリケーション・コードをJARファイルに配置

ステップ6b: LoginModuleとアプリケーションのJARファイルにアクセス権を設定でポリシー内のJARファイルを参照できるように、LoginModuleおよびアプリケーション・コードを別々のJARファイルに格納します。次は、JARファイルを作成するサンプル・コマンドです。

jar cvf <JAR file name> <list of classes, separated by spaces>

このコマンドにより、指定されたクラスを含む、指定された名前のJARファイルが作成されます。

jarツールの詳細は、jarを参照してください。

ステップ6b: LoginModuleとアプリケーションのJARファイルにアクセス権を設定

LoginModuleやアプリケーションが、セキュリティ・チェックをトリガーするセキュリティ関連タスク(ネットワーク接続の確立、ローカル・ディスク上のファイルの読取り、書込みなど)を実行するとします。セキュリティ・マネージャがインストールされている環境で実行する場合は、必要なアクセス権を付与する必要があります(JDKでのアクセス権を参照)。

通常、LoginModuleはPrincipalとクレデンシャルを認証済サブジェクトに関連付けます。このため、LoginModuleは、アクセス権として、modifyPrincipals、modifyPublicCredentialsおよびmodifyPrivateCredentialsというターゲット名のAuthPermissionを必要とします。

次に示すサンプル文は、コードがMyLM.jarに記述されているLoginModuleへのアクセス権を付与するものです。この種の文は、ポリシー・ファイルに記述されます。この例では、MyLM.jarファイルは/localWorkディレクトリに格納されるものとします。

grant codeBase "file:/localWork/MyLM.jar" {
    permission javax.security.auth.AuthPermission "modifyPrincipals";
    permission javax.security.auth.AuthPermission "modifyPublicCredentials";
    permission javax.security.auth.AuthPermission "modifyPrivateCredentials";
};

ステップ6c: LoginModuleを参照する構成を作成

JAASはプラガブルな認証アーキテクチャをサポートするため、既存のアプリケーションを変更せずに新しいLoginModuleを使用できます。新しいLoginModuleの使用を示すためには、ログインConfigurationを更新するだけで済みます。

OracleのデフォルトのConfiguration実装は、ConfigFileで説明するように、構成ファイルから構成情報を読み取ります。

テスト用の構成ファイルを作成します。たとえば、以前取り上げた架空のIBMのアプリケーション用LoginModuleを構成する場合、次のような内容の構成ファイルを使用することになります。

    AppName {
        com.ibm.auth.Module REQUIRED debug=true;
    };

AppNameは、アプリケーションがログイン構成ファイル内のこのエントリを参照するために使用する任意の名前です。アプリケーションはこの名前をLoginContextコンストラクタの第1引数として指定します。

この場合、次のようにしてアプリケーションを実行し、構成ファイルを指定できます。

java -classpath MyApp.jar
 -Djava.security.auth.login.config=test.conf MyApp

コマンド全体は、1行で入力してください。ここでは、読みやすくするために複数行に分けて表示してあります。

my.policyという名前のポリシー・ファイルを指定し、インストールされているセキュリティ・マネージャを使ってアプリケーションを実行するには、次のように入力します。

java -classpath MyApp.jar -Djava.security.manager
 -Djava.security.policy=my.policy
 -Djava.security.auth.login.config=test.conf MyApp

ここでも、コマンド全体は1行で入力してください。

debugオプションを付けてLoginModuleを構成すると、適正に動作することを確認できます。

コードをデバッグし、必要に応じてテストを続行します。問題が発生する場合は、ここまでのすべてのステップが完了していることを確認してください。

ユーザーによる入力と、構成ファイルに指定したLoginModuleオプションを確実に変更してください。

異なったインストール・オプション(LoginModuleをクラス・パスやモジュール・パス内に配置するなど)および実行環境(セキュリティ・マネージャを実行する、または実行しない)を使用するテストも実行してください。特に、セキュリティ・マネージャがインストールされている場合にLoginModuleを確実に動作させるには、ステップ6b: LoginModuleとアプリケーションのJARファイルにアクセス権を設定で説明されているように、必要なアクセス権を付与した後、インストールおよび実行環境をテストする必要があります。

たとえば、次のようなドキュメントを記述できます。