The Subject class is the key abstraction of the JAAS API. It represents a person or other entity, and consists of:

• a java.util.Set of Principal objects that specify the identity (or identities) of the Subject.

• a Set of objects that specify the public credentials, such as the public key certificates of the Subject.

• a Set of objects that specify the private credentials, such as the private keys and Kerberos tickets of the Subject.

Subject defines methods that allow you to retreive each of these three sets, or to retreive a subset of each set that contains only objects of a specified Class. Unless the Subject is read-only, you can use the methods of java.util.Set to modify each of the three sets. Once setReadOnly( ) has been called, however, the sets become immutable and their contents may not be modified.

Application code does not typically create Subject objects itself. Instead, it obtains a Subject that represents the authenticated user of the application by calling the login( ) and getSubject( ) methods of a javax.security.auth.login.LoginContext object.

Once an authenticated Subject has been obtained from a LoginContext, an application can call the doAs( ) method to run code using the permissions granted to that Subject combined with the permissions granted to the code itself. doAs( ) runs the code defined in the run( ) method of a PrivilegedAction or PrivilegedExceptionAction object. doAsPrivileged( ) is a similar method but executes the specified run( ) method using the Subject's permissions only, unconstrained by unprivileged code in the call stack.

Note that many of the methods of this class throw a SecurityException if the caller has not been granted the requisite AuthPermission.

Figure 19-4. javax.security.auth.Subject

public final class Subject implements Serializable {
// Public Constructors
     public Subject( );  
     public Subject(boolean readOnly, java.util.Set<? extends java.security.Principal>
        principals, java.util.Set<?> pubCredentials, 
        java.util.Set<?> privCredentials);  
// Public Class Methods
     public static Object doAs(Subject subject, java.security.PrivilegedExceptionAction
        action) throws java.security.PrivilegedActionException;  
     public static Object doAs(Subject subject, java.security.PrivilegedAction action);  
     public static Object doAsPrivileged(Subject subject, java.security.
        PrivilegedExceptionAction action, java.security.AccessControlContext acc) 
        throws java.security.PrivilegedActionException;  
     public static Object doAsPrivileged(Subject subject, java.security.PrivilegedAction
        action, java.security.AccessControlContext acc);  
     public static Subject getSubject(java.security.AccessControlContext acc);  
// Public Instance Methods
     public java.util.Set<java.security.Principal> getPrincipals( );  
     public <T extends java.security.Principal> java.util.Set<T> getPrincipals(Class<T> c);  
     public java.util.Set<Object> getPrivateCredentials( );  
     public <T> java.util.Set<T> getPrivateCredentials(Class<T> c);  
     public java.util.Set<Object> getPublicCredentials( );  
     public <T> java.util.Set<T> getPublicCredentials(Class<T> c);  
     public boolean isReadOnly( );                                        default:false
     public void setReadOnly( );  
// Public Methods Overriding Object
     public boolean equals(Object o);  
     public int hashCode( );  
     public String toString( );  
}

Passed To

java.security.AuthProvider.login( ), javax.security.auth.Policy.getPermissions( ), SubjectDomainCombiner.SubjectDomainCombiner( ), javax.security.auth.login.LoginContext.LoginContext( ), javax.security.auth.spi.LoginModule.initialize( )

Returned By

SubjectDomainCombiner.getSubject( ), javax.security.auth.login.LoginContext.getSubject( )