リソースへのアクセスを承認する場合、最初に、アプリケーションが要求元を認証する必要があります。JAASフレームワークでは、要求元をサブジェクトという用語で表します。サブジェクトは、個人やサービスなどの任意のエンティティです。サブジェクトが認証されると、javax.security.auth.Subjectには関連する識別情報またはプリンシパルが割り当てられます。Subjectには、多数のPrincipalを含めることができます。たとえば、ある個人は、名前Principal (「John Doe」)およびSSN Principal (「123-45-6789」)などを持ち、これらにより、他のサブジェクトと区別されます。

Subjectは、クレデンシャルと呼ばれるセキュリティ関連の属性も保持できます(クレデンシャルの項を参照)。非公開暗号化キーなどの特別な保護が必要な機密の資格は、非公開資格Set内に格納されます。公開キー証明書などの共有されるクレデンシャルは、公開クレデンシャルSet内に格納されます。資格証明Setが異なると、それにアクセスおよび変更するためのアクセス権も異なります。

サブジェクトは、次のコンストラクタを使用して作成されます。

public Subject();
public Subject(boolean readOnly, Set principals,
               Set pubCredentials, Set privCredentials);

最初のコンストラクタは、Principalおよびクレデンシャルの空(nullではない)のSetでSubjectを作成します。2番目のコンストラクタは、指定されたPrincipalおよびクレデンシャルのSetでSubjectを作成します。Subjectを読取り専用にするために使用できるboolean型の引数も持っています。読取り専用のSubject内では、PrincipalおよびクレデンシャルSetは不変です。

アプリケーション作成者がSubjectをインスタンス化する必要はありません。アプリケーションがLoginContextをインスタンス化し、SubjectをLoginContextコンストラクタに渡さない場合、LoginContextは新しい空のSubjectをインスタンス化します。LoginContextの項を参照してください。

Subjectが読取り専用の状態でインスタンス化されなかった場合、次のメソッドを呼び出して読取り専用に設定できます。

public void setReadOnly();

ターゲット名「setReadOnly」を持つjavax.security.auth.AuthPermissionは、このメソッドを呼び出すために要求されます。読取り専用の状態に設定したあとで、Principalやクレデンシャルを追加または削除しようとすると、IllegalStateExceptionがスローされます。次のメソッドを使用して、Subjectの読取り専用状態をテストできます。

public boolean isReadOnly();

Subjectに関連したPrincipalを取得する場合、次の2つのメソッドを利用できます。

public Set getPrincipals();
public Set getPrincipals(Class c);

最初のメソッドは、Subjectに含まれるすべてのPrincipalを返します。一方、2番目のメソッドは、指定されたクラスcのインスタンスまたはクラスcのサブクラスのインスタンスになっているPrincipalしか返しません。Subjectに関連付けられているPrincipalがない場合は、空のセットが返されます。

Subjectに関連した公開クレデンシャルを取得する場合は、次のメソッドを利用できます。

public Set getPublicCredentials();
public Set getPublicCredentials(Class c);

これらのメソッドの動作はgetPrincipalsメソッドの動作と似ています。ただし、getPrincipalsメソッドでは、公開クレデンシャルを取得することはできません。

Subjectに関連した非公開クレデンシャルにアクセスする場合は、次のメソッドを利用できます。

public Set getPrivateCredentials();
public Set getPrivateCredentials(Class c);

これらのメソッドの動作は、getPrincipalsメソッドやgetPublicCredentialsメソッドとよく似ています。

SubjectのPrincipal Set、公開クレデンシャルSet、または非公開クレデンシャルSetを変更または操作する場合、呼出し側はjava.util.Setクラスで定義されたメソッドを使用します。その方法を示すサンプル・コードを次に示します。

Subject subject;
Principal principal;
Object credential;
// ...

// add a Principal and credential to the Subject
subject.getPrincipals().add(principal);
subject.getPublicCredentials().add(credential);

非公開資格証明のSetで繰返し処理を実行するには、各資格証明にアクセスするため、javax.security.auth.PrivateCredentialPermissionが必要です。詳細は、PrivateCredentialPermission APIドキュメントを参照してください。

次のメソッドは、指定したSubjectとしてアクションを実行できます:

public static <T> T callAs(Subject subject, Callable<T> action)
public static <T> T doAs(Subject subject, PrivilegedAction<T> action)
public static <T> T doAsPrivileged(Subject subject,
                                   PrivilegedAction<T> action,
                                   AccessControlContext acc)

セキュリティ・マネージャが許可されている場合、callAs、doAsまたはdoAsPrivilegedを起動すると、SubjectをAccessControlContextに関連付けることができます。次のメソッドは、指定されたAccessControlContextと関連付けられたSubjectを返すか、指定されたAccessControlContextと関連付けられたSubjectが存在しない場合には、nullを返します。

public static Subject getSubject(final AccessControlContext acc);

ターゲット名「getSubject」を持つAuthPermissionは、getSubjectを呼び出すために要求されます。

詳細は、「特定のSubjectとしてアクションを実行するためのdoAsメソッド」を参照してください。

セキュリティ・マネージャが許可されていない場合、doAsまたはcallAsメソッドを使用してアクションを実行すると、Subjectは実行期間にバインドされます。次のメソッドは、現在のスレッドの実行期間に関連付けられたSubjectを返し、Subjectが設定されていない場合はnullを返します:

public static Subject current();

セキュリティ・マネージャが許可されていない場合、getSubjectを使用してSubjectを取得しようとすると、UnsupportedOperationExceptionが表示されます。

詳細は、特定のSubjectとしてアクションを実行するためのcallAsおよび現在のメソッドを参照してください。

Subjectクラスには、java.lang.Objectから継承した次のメソッドも含まれます。

public boolean equals(Object o);
public String toString();
public int hashCode();

public static <T> T callAs(Subject subject, Callable<T> action)
    throws CompletionException

Subject.callAs(mySubject, anotherAction);

Callable<Void> anotherAction = () -> {
    
    Subject s = Subject.current();
    System.out.println("\nCurrent subject: " + s);
    
    // Add a new Principal
    Random r = new Random();
    String pn = Integer.toString(r.nextInt());
    Principal p = new sample.principal.SamplePrincipal(pn);
    
    System.out.println("\nAdding principal " + pn);
    s.getPrincipals().add(p);         
    
    // List Principals
    System.out.println("\nAuthenticated user has the following Principals:");
    Iterator pi = s.getPrincipals().iterator();

    while (pi.hasNext()) {
        Principal nextp = (Principal)pi.next();
        System.out.println("\t" + nextp.toString());            
    }
    
    System.out.println("\nYour java.home property: "
        + System.getProperty("java.home"));

    System.out.println("\nYour user.home property: "
        + System.getProperty("user.home"));

    File f = new File("foo.txt");
    System.out.print("\nfoo.txt does ");
    if (!f.exists())
        System.out.print("not ");
    System.out.println("exist in the current working directory.");
    
    return null;            
};

Callable<Void> addRandomPrincipal = () -> {
    
    Subject s = Subject.current();
    
    // Add a new Principal
    Random r = new Random();
    String pn = Integer.toString(r.nextInt());
    Principal p = new sample.principal.SamplePrincipal(pn);
    
    System.out.println("\nAdding principal " + pn);
    s.getPrincipals().add(p);         
    return null;
};

Callable<Void> structuredAction = () -> {
    try (var scope = new StructuredTaskScope<>()) {
        scope.fork(addRandomPrincipal);
        scope.fork(addRandomPrincipal);
        scope.fork(addRandomPrincipal);

        scope.join();
                
        Subject s = Subject.current();
        System.out.println("\nCurrent subject: " + s);
    
    } catch (InterruptedException e) {
        e.printStackTrace();
    }
    return null;
};        
        
Subject.callAs(mySubject, structuredAction);

public static Object
    doAs(final Subject subject,
         final java.security.PrivilegedAction action);

public static Object
    doAs(final Subject subject,
         final java.security.PrivilegedExceptionAction action)
         throws java.security.PrivilegedActionException;

PrivilegedAction<Object> privAct = () -> {
    AccessControlContext acc = AccessController.getContext();
    // Subject::getSubject throws an UnsupportedOperationExample
    // if a security manager isn't allowed
    Subject s = Subject.getSubject(acc);
    System.out.println("Current subject: " + s);
    return null;
};
Subject.doAs(mySubject, privAct);

PrivilegedAction<Object> privAct = () -> {
    Subject s = Subject.current();
    System.out.println("Current subject: " + s);
    return null;
};
Subject.doAs(mySubject, privAct);

    // grant "BOB" permission to read the file "foo.txt"
    grant Principal com.ibm.security.Principal "BOB" {
        permission java.io.FilePermission "foo.txt", "read";
    };

    class ExampleAction implements java.security.PrivilegedAction {
        public Object run() {
            java.io.File f = new java.io.File("foo.txt");

            // the following call invokes a security check
            if (f.exists()) {
                System.out.println("File foo.txt exists");
            }
            return null;
        }
    }

    public class Example1 {
        public static void main(String[] args) {

            // Authenticate the subject, "BOB".
            // This process is described in the
            // LoginContext class.

            Subject bob;
            // Set bob to the Subject created during the
            // authentication process

            // perform "ExampleAction" as "BOB"
            Subject.doAs(bob, new ExampleAction());
        }
    }

public static Object doAsPrivileged(
    final Subject subject,
    final java.security.PrivilegedAction action,
    final java.security.AccessControlContext acc);

public static Object doAsPrivileged(
    final Subject subject,
    final java.security.PrivilegedExceptionAction action,
    final java.security.AccessControlContext acc)
    throws java.security.PrivilegedActionException;

前述したように、サブジェクトが認証されると、関連する識別情報またはプリンシパルがサブジェクトに割り当てられます。サブジェクトには、多数のプリンシパルを含めることができます。たとえば、ユーザーは、他のサブジェクトと明確に区別される名前プリンシパル(「John Doe」)およびSSNプリンシパル(「123-45-6789」)を保持できます。プリンシパルはjava.security.Principalおよびjava.io.Serializableインタフェースを実装する必要があります。サブジェクトに関連付けられたプリンシパルの更新方法の詳細は、サブジェクトを参照してください。

サブジェクトは、関連付けられたプリンシパルに加え、クレデンシャルと呼ばれる独自のセキュリティ関連属性を保持できます。クレデンシャルには、新規サービスに対してサブジェクトを認証する際に使用可能な情報が含まれます。この種のクレデンシャルには、パスワード、Kerberosチケット、および公開キー証明書が含まれます。クレデンシャルには、サブジェクトによる特定操作の実行を可能にするだけのデータが含まれる場合もあります。たとえば、暗号化キーは、サブジェクトによるデータへの署名または暗号化を可能にするクレデンシャルを表します。公開および非公開クレデンシャル・クラスは、コアJAASクラス・ライブラリの一部ではありません。したがって、あらゆるクラスがクレデンシャルを表すことができます。

公開および非公開クレデンシャル・クラスは、コアJAASクラス・ライブラリの一部ではありません。ただし、開発者は、クレデンシャルに関連する2つのインタフェース、RefreshableおよびDestroyableを実装するクレデンシャル・クラスを持つことを決定できます。

    boolean isCurrent();

    void refresh() throws RefreshFailedException;

    boolean isDestroyed();

    void destroy() throws DestroyFailedException;

javax.security.auth.login.LoginContextクラスは、サブジェクトの認証に使用する基本的なメソッドを提供し、基盤となる認証テクノロジから独立したアプリケーションを開発する方法を提供します。LoginContextは、Configurationを調べて、特定のアプリケーション用に構成された認証サービスまたはLoginModuleを判別します。このため、アプリケーション自体に変更を加えることなく、アプリケーションに様々なLoginModuleをプラグインできます。

LoginContextは、選択可能な次の4つのコンストラクタを提供します。

    public LoginContext(String name) throws LoginException;

    public LoginContext(String name, Subject subject) throws LoginException;

    public LoginContext(String name, CallbackHandler callbackHandler)
           throws LoginException

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

すべてのコンストラクタは、共通のパラメータnameを共有します。LoginContextは、この引数をログインConfigurationのインデックスとして使用し、LoginContextのインスタンス化を行うアプリケーション用として構成されるLoginModuleを特定します。Subjectを入力パラメータとして取らないコンストラクタは、新規Subjectをインスタンス化します。どのコンストラクタでも、nullの入力は許可されません。呼出し元は、createLoginContext.<name>をターゲットとするAuthPermissionに対して、LoginContextのインスタンス化を要求します。ここで、<name>は、アプリケーションがLoginContextのインスタンス化の際にnameパラメータで参照するログイン構成エントリの名前です。

CallbackHandlerとこれが必要な状況の詳細は、CallbackHandlerを参照してください。

実際の認証は、次のメソッドへの呼出しを使って行われます。

    public void login() throws LoginException;

loginを呼び出すと、すべての構成済みLoginModuleが呼び出され、認証を実行します。認証に成功した場合は、次のメソッドを使用して、認証されたSubject (Principal、公開クレデンシャル、非公開クレデンシャルを保持している場合がある)を取得できます。

     public Subject getSubject();

Subjectをログアウトして、認証済みのPrincipalsおよびクレデンシャルを削除するには、次のメソッドを使用します。

    public void logout() throws LoginException;

次のサンプル・コードは、サブジェクトの認証およびログアウトに必要な呼出しを示します。

    // let the LoginContext instantiate a new Subject
    LoginContext lc = new LoginContext("entryFoo");
    try {
        // authenticate the Subject
        lc.login();
        System.out.println("authentication successful");

        // get the authenticated Subject
        Subject subject = lc.getSubject();

        ...

        // all finished -- logout
        lc.logout();
    } catch (LoginException le) {
        System.err.println("authentication unsuccessful: " +
            le.getMessage());
    }

LoginModule インタフェースを使用すると、異なる種類の認証技術を実装して、アプリケーションでプラグインとして利用できます。たとえば、ユーザー名/パスワードベースの認証を実行できるLoginModuleがあります。スマート・カードやバイオメトリック・デバイスなどのハードウェアへのインタフェースを提供するLoginModuleもあります。

ノート: アプリケーション作成者は、LoginModuleの機能を理解していなくてもかまいません。アプリケーションを作成し、構成情報(ログイン構成ファイルの情報など)を指定し、アプリケーションが構成によって指定されたログイン・モジュールを利用してユーザーを認証できるようにするだけで十分です。

一方、認証技術を実装するLoginModuleを作成する必要があるプログラマは、Java Authentication and Authorization Service (JAAS): LoginModule開発者ガイドで具体的なステップを確認してください。

LoginModuleがユーザーと通信して、認証情報を取得する必要がある場合があります。LoginModuleは、この目的でjavax.security.auth.callback.CallbackHandlerを使用します。アプリケーションはCallbackHandlerインタフェースを実装し、それをLoginContextに転送します。LoginContextは、それを基礎となるLoginModuleに直接転送します。LoginModuleはCallbackHandlerを使用して、ユーザーからの入力(パスワードやスマート・カードの暗証番号など)を収集したり、ユーザーに情報(ステータス情報など)を提供したりします。アプリケーションにCallbackHandlerの指定を許可することにより、基礎となるLoginModulesは、アプリケーションとユーザー間の通信方法から独立した状態にすることができます。たとえば、GUIアプリケーション用のCallbackHandlerの実装は、ウィンドウを表示してユーザーの入力を求めることができます。一方、非GUIツール用のCallbackHandlerの実装では、単にユーザーにコマンド行から直接入力するように求めることができます。

CallbackHandler

1つのメソッドを実装するインタフェースです。

     void handle(Callback[] callbacks)
         throws java.io.IOException, UnsupportedCallbackException;

LoginModuleはCallbackHandler handleメソッドに適切なCallback (ユーザー名に対してはNameCallback、パスワードに対してはPasswordCallback)で構成される配列を渡し、CallbackHandlerは要求に従ってユーザーと通信し、Callback内に適切な値を設定します。たとえば、NameCallbackを処理する場合、CallbackHandlerはユーザーから名前を取得し、NameCallbackのsetNameメソッドを呼び出してその名前を格納します。

CallbackHandlerのドキュメントには、このドキュメントには記載されていない大量のサンプルが記載されています。

javax.security.auth.callbackパッケージには、コールバック・インタフェースおよびいくつかの実装が含まれています。LoginModulesは、コールバックの配列を、CallbackHandlerのhandleメソッドに直接渡すことができます。

使用方法の詳細については、各種Callback APIを参照してください。

java.security.Policyクラスは、システム全体のアクセス制御ポリシーを表す抽象クラスです。Policy APIはPrincipalベースの問合せをサポートしています。

JDKは、デフォルトで、ファイルベースのサブクラス実装を提供します。この実装もアップグレードされ、ポリシー・ファイル内でPrincipalベースのgrantエントリを使用できるようになっています。

ポリシー・ファイルおよびその内部のエントリ構造については、「デフォルトのPolicyの実装とポリシー・ファイルの構文」を参照してください。

javax.security.auth.AuthPermissionクラスは、JAASに必須の基本的なアクセス権をカプセル化しています。AuthPermissionには名前(「ターゲット名」とも呼ばれる)は含まれますが、アクション・リストは含まれません。名前付きアクセス権を得るか、得ないかのどちらかになります。

AuthPermissionは、java.security.Permissionから継承されたメソッドのほかに2つのpublicコンストラクタを持っています。

    public AuthPermission(String name);
    public AuthPermission(String name, String actions);

最初のコンストラクタは、指定された名前で新しいAuthPermissionを作成します。2番目のコンストラクタも、指定された名前で新しいAuthPermissionオブジェクトを作成しますが、追加のactions引数があります。これは現在のところ未使用であるため、nullにしてください。このコンストラクタは、Policyオブジェクトで新しいPermissionオブジェクトをインスタンス化するためだけに存在します。その他のほとんどのコードでは、最初のコンストラクタが適しています。

現在のところ、AuthPermissionオブジェクトを使用して、Policy、Subject、LoginContext、およびConfigurationオブジェクトへのアクセスを保護します。サポートされる有効な名前のリストについては、AuthPermissionのJavaDoc APIドキュメントを参照してください。

javax.security.auth.PrivateCredentialPermissionクラスは、Subjectの非公開クレデンシャルへのアクセスを保護し、1つのpublicコンストラクタを提供します。

     public PrivateCredentialPermission(String name, String actions);