Java Authentication and Authorization Service (JAAS): LoginModule開発者ガイド

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の動作に影響を与えるように指定された構成オプションを特定します。将来の使用に備えて、変数内にオプションの値を保存することもできます。

注意: JAAS LoginModuleは、PAM (use_first_pass、try_first_pass、use_mapped_passおよびtry_mapped_pass)に定義されたオプションを使用してシングル・サインオンします。詳細については、「Making Login Services Independent of Authentication Technologies」を参照してください。

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

• try_first_pass - trueの場合、スタック内の最初のログイン・モジュールが入力されたパスワードを保存し、それ以降のログイン・モジュールはこれを使用しようとする。認証に失敗した場合、ログイン・モジュールは新しいパスワードを要求し、認証を再試行する。
• use_first_pass - trueの場合、スタック内の最初のログイン・モジュールが入力されたパスワードを保存し、それ以降のログイン・モジュールはこれを使用しようとする。ログイン・モジュールは、認証に失敗しても新しいパスワードを要求しない。
• try_mapped_pass - trueの場合、スタック内の最初のログイン・モジュールが入力されたパスワードを保存し、それ以降のログイン・モジュールはこれをサービス固有のパスワードにマッピングしようとする。認証に失敗した場合、ログイン・モジュールは新しいパスワードを要求し、認証を再試行する。
• use_mapped_pass - trueの場合、スタック内の最初のログイン・モジュールが入力されたパスワードを保存し、それ以降のログイン・モジュールはこれをサービス固有のパスワードにマッピングしようとする。ログイン・モジュールは、認証に失敗しても新しいパスワードを要求しない。
• moduleBanner - trueの場合、ログイン・モジュールは、CallBackHandlerの呼出し時に最初のCallbackとしてTextOutputCallbackを提供する。このCallbackには、認証を実行しているログイン・モジュールに関する情報が記述されている。
• debug - trueの場合、ログイン・モジュールに対してデバッグ情報の出力を指示する。

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

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

LoginModule.loginメソッド

boolean login() throws LoginException;

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

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

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

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

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 - 名前を保存/取得するための共有状態マップ・キーとして使用。
• javax.security.auth.login.password - パスワードを保存/取得するための共有状態マップ・キーとして使用。

認証に失敗した場合、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呼出しが成功したことを想定しています。たとえば、上部左側のボックスは、以前のloginメソッド呼出しとcommitメソッド呼出しに成功し、さらにabortメソッド自体の呼出しにも成功した場合に返されるabortメソッドの結果を示しています。

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ファイルに配置

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

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

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

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

ステップ6b: JARファイルの格納場所を決定

本来、アプリケーションはユーザーの好みの場所に格納できます。

LoginModuleも、ユーザーまたはその他のクライアントの好みの場所に格納できます。完全に信頼できるLoginModuleは、JREのlib/ext (標準拡張)ディレクトリに格納できます。

lib/extディレクトリ内にあるLoginModuleとその他のディレクトリにあるLoginModuleを両方ともテストする必要があります。これは、LoginModuleにセキュリティ関連操作の実行に必要なJava Development Kit (JDK)でのアクセス権を明示的に付与する必要がある場合と、そうでない場合があるためです。

JREのlib/extディレクトリ内のLoginModuleは、インストール済拡張機能と見なされるので、これにアクセス権を付与する必要はありません。インストール済拡張機能には、デフォルトのシステム・ポリシー・ファイル構文により、すべてのアクセス権が付与されます。

一方、それ以外のディレクトリ内のLoginModuleには、ポリシー・ファイル内のgrant文を使うなどしてアクセス権を付与する必要があります。

LoginModule JARファイルがインストール済み拡張機能と見なされない場合は、このファイルの格納場所を指定してテストします。次のステップでは、指定された場所にあるJARファイルにアクセス権を付与します。

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

LoginModuleやアプリケーションが、セキュリティ・チェックをトリガーするセキュリティ関連タスク(ネットワーク接続の確立、ローカル・ディスク上のファイルの読取り、書込みなど)を実行するとします。これらがインストール済拡張機能(ステップ6b: JARファイルの格納場所を決定を参照)ではなく、セキュリティ・マネージャがインストールされている環境で実行される場合は、Java Development Kit (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";
};

ステップ6d: ログイン・モジュールを参照する構成を作成

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をインストール済み拡張機能にする、クラス・パス内に配置する、など)および実行環境(セキュリティ・マネージャを実行する、または実行しない)を使用するテストも実行してください。インストール・オプションの詳細は、ステップ6b: JARファイルの格納場所を決定を参照してください。特に、セキュリティ・マネージャがインストールされていてLoginModuleとアプリケーションがインストール済拡張機能でない場合は、LoginModuleを確実に動作させるため、ステップ6c: LoginModuleおよびアプリケーションのJARファイルのアクセス権の設定で説明されているように、必要なアクセス権を付与した後、インストールおよび実行環境をテストする必要があります。