javax.security.auth.login
Class LoginContext

java.lang.Object
  |
  +--javax.security.auth.login.LoginContext

public class LoginContext

extends Object

The LoginContext class describes the basic methods used to authenticate Subjects and provides a way to develop an application independent of the underlying authentication technology. A Configuration specifies the authentication technology, or LoginModule, to be used with a particular application. Therefore, different LoginModules can be plugged in under an application without requiring any modifications to the application itself.

In addition to supporting pluggable authentication, this class also supports the notion of stacked authentication. In other words, an application may be configured to use more than one LoginModule. For example, one could configure both a Kerberos LoginModule and a smart card LoginModule under an application.

A typical caller instantiates this class and passes in a name and a CallbackHandler. LoginContext uses the name as the index into the Configuration to determine which LoginModules should be used, and which ones must succeed in order for the overall authentication to succeed. The CallbackHandler is passed to the underlying LoginModules so they may communicate and interact with users (prompting for a username and password via a graphical user interface, for example).

Once the caller has instantiated a LoginContext, it invokes the login method to authenticate a Subject. This login method invokes the login method from each of the LoginModules configured for the name specified by the caller. Each LoginModule then performs its respective type of authentication (username/password, smart card pin verification, etc.). Note that the LoginModules will not attempt authentication retries or introduce delays if the authentication fails. Such tasks belong to the caller.

Regardless of whether or not the overall authentication succeeded, this login method completes a 2-phase authentication process by then calling either the commit method or the abort method for each of the configured LoginModules. The commit method for each LoginModule gets invoked if the overall authentication succeeded, whereas the abort method for each LoginModule gets invoked if the overall authentication failed. Each successful LoginModule's commit method associates the relevant Principals (authenticated identities) and Credentials (authentication data such as cryptographic keys) with the Subject. Each LoginModule's abort method cleans up or removes/destroys any previously stored authentication state.

If the login method returns without throwing an exception, then the overall authentication succeeded. The caller can then retrieve the newly authenticated Subject by invoking the getSubject method. Principals and Credentials associated with the Subject may be retrieved by invoking the Subject's respective getPrincipals, getPublicCredentials, and getPrivateCredentials methods.

To logout the Subject, the caller simply needs to invoke the logout method. As with the login method, this logout method invokes the logout method for each LoginModule configured for this LoginContext. Each LoginModule's logout method cleans up state and removes/destroys Principals and Credentials from the Subject as appropriate.

Each of the configured LoginModules invoked by the LoginContext is initialized with a Subject to be authenticated, a CallbackHandler used to communicate with users, shared LoginModule state, and LoginModule-specific options. If the LoginContext was not provided a Subject then it instantiates one itself.

Each LoginModule which successfully authenticates a user updates the Subject with the relevant user information (Principals and Credentials). This Subject can then be returned via the getSubject method from the LoginContext class if the overall authentication succeeds. Note that LoginModules are always invoked from within an AccessController.doPrivileged call. Therefore, although LoginModules that perform security-sensitive tasks (such as connecting to remote hosts) need to be granted the relevant Permissions in the security Policy, the callers of the LoginModules do not require those Permissions.

A LoginContext supports authentication retries by the calling application. For example, a LoginContext's login method may be invoked multiple times if the user incorrectly types in a password. However, a LoginContext should not be used to authenticate more than one Subject. A separate LoginContext should be used to authenticate each different Subject.

Multiple calls into the same LoginContext do not affect the LoginModule state, or the LoginModule-specific options.

See Also:

Subject, CallbackHandler, Configuration, LoginModule

Constructor Summary

LoginContext(String name)
Constructor for the LoginContext class.

LoginContext(String name, CallbackHandler callbackHandler)
Constructor for the LoginContext class.

LoginContext(String name, Subject subject)
Constructor for the LoginContext class.

LoginContext(String name, Subject subject, CallbackHandler callbackHandler)
Constructor for the LoginContext class.

Method Summary

Subject	getSubject() Return the authenticated Subject.
void	login() Perform the authentication and, if successful, associate Principals and Credentials with the authenticated Subject.
void	logout() Logout the Subject.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LoginContext

public LoginContext(String name)
             throws LoginException

Constructor for the LoginContext class.

Initialize the new LoginContext object with a name. LoginContext uses the specified name as the index into the Configuration to determine which LoginModules should be used. If the provided name does not match any in the Configuration, then the LoginContext uses the default Configuration entry, "other". If there is no Configuration entry for "other", then a LoginException is thrown.

This constructor does not allow for a CallbackHandler. If the auth.login.defaultCallbackHandler security property is set to the fully qualified name of a default CallbackHandler implementation class, then that CallbackHandler will be loaded and passed to the underlying LoginModules. If the security property is not set, then the underlying LoginModules will not have a CallbackHandler for use in communicating with users. The caller thus assumes that the configured LoginModules have alternative means for authenticating the user.

The auth.login.defaultCallbackHandler security property can be set in the Java security properties file located in the file named <JAVA_HOME>/lib/security/java.security, where <JAVA_HOME> refers to the directory where the SDK was installed.

Since no Subject can be specified to this constructor, it instantiates a Subject itself.

Parameters:

name - the name used as the index into the Configuration.

Throws:

LoginException - if the specified name does not appear in the Configuration and there is no Configuration entry for "other", or if the auth.login.defaultCallbackHandler security property was set, but the implementation class could not be loaded.

LoginContext

public LoginContext(String name,
                    Subject subject)
             throws LoginException

Constructor for the LoginContext class.

Initialize the new LoginContext object with a name and a Subject object.

LoginContext uses the name as the index into the Configuration to determine which LoginModules should be used. If the provided name does not match any in the Configuration, then the LoginContext uses the default Configuration entry, "other". If there is no Configuration entry for "other", then a LoginException is thrown.

This constructor does not allow for a CallbackHandler. If the auth.login.defaultCallbackHandler security property is set to the fully qualified name of a default CallbackHandler implementation class, then that CallbackHandler will be loaded and passed to the underlying LoginModules. If the security property is not set, then the underlying LoginModules will not have a CallbackHandler for use in communicating with users. The caller thus assumes that the configured LoginModules have alternative means for authenticating the user.

The auth.login.defaultCallbackHandler security property can be set in the Java security properties file located in the file named %lt;JAVA_HOME%gt;/lib/security/java.security, where %lt;JAVA_HOME%gt; refers to the directory where the SDK was installed.

LoginContext passes the Subject object to configured LoginModules so they may perform additional authentication and update the Subject with new Principals and Credentials.

Parameters:

name - the name used as the index into the Configuration.

subject - the Subject to authenticate.

Throws:

LoginException - if the specified name does not appear in the Configuration and there is no Configuration entry for "other", if the specified subject is null, or if the auth.login.defaultCallbackHandler security property was set, but the implementation class could not be loaded.

LoginContext

public LoginContext(String name,
                    CallbackHandler callbackHandler)
             throws LoginException

Constructor for the LoginContext class.

Initialize the new LoginContext object with a name and a CallbackHandler object.

LoginContext uses the name as the index into the Configuration to determine which LoginModules should be used. If the provided name does not match any in the Configuration, then the LoginContext uses the default Configuration entry, "other". If there is no Configuration entry for "other", then a LoginException is thrown.

LoginContext passes the CallbackHandler object to configured LoginModules so they may communicate with the user. The CallbackHandler object therefore allows LoginModules to remain independent of the different ways applications interact with users. This LoginContext must wrap the application-provided CallbackHandler in a new CallbackHandler implementation, whose handle method implementation invokes the application-provided CallbackHandler's handle method in a java.security.AccessController.doPrivileged call constrained by the caller's current AccessControlContext.

Since no Subject can be specified to this constructor, it instantiates a Subject itself.

Parameters:

name - the name used as the index into the Configuration.

callbackHandler - the CallbackHandler object used by LoginModules to communicate with the user.

Throws:

LoginException - if the specified name does not appear in the Configuration and there is no Configuration entry for "other", or if the specified callbackHandler is null.

LoginContext

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

Constructor for the LoginContext class.

Initialize the new LoginContext object with a name, a Subject to be authenticated, and a CallbackHandler object.

LoginContext uses the name as the index into the Configuration to determine which LoginModules should be used. If the provided name does not match any in the Configuration, then the LoginContext uses the default Configuration entry, "other". If there is no Configuration entry for "other", then a LoginException is thrown.

LoginContext passes the Subject object to configured LoginModules so they may perform additional authentication and update the Subject with new Principals and Credentials.

LoginContext passes the CallbackHandler object to configured LoginModules so they may communicate with the user. The CallbackHandler object therefore allows LoginModules to remain independent of the different ways applications interact with users. This LoginContext must wrap the application-provided CallbackHandler in a new CallbackHandler implementation, whose handle method implementation invokes the application-provided CallbackHandler's handle method in a java.security.AccessController.doPrivileged call constrained by the caller's current AccessControlContext.

Parameters:

name - the name used as the index into the Configuration.

subject - the Subject to authenticate.

callbackHandler - the CallbackHandler object used by LoginModules to communicate with the user.

Throws:

LoginException - if the specified name does not appear in the Configuration and there is no Configuration entry for "other", or if the specified subject is null, or if the specified callbackHandler is null.

Method Detail

login

public void login()
           throws LoginException

Perform the authentication and, if successful, associate Principals and Credentials with the authenticated Subject.

This method invokes the login method for each LoginModule configured for the name provided to the LoginContext constructor, as determined by the login Configuration. Each LoginModule then performs its respective type of authentication (username/password, smart card pin verification, etc.).

This method completes a 2-phase authentication process by calling each configured LoginModule's commit method if the overall authentication succeeded (the relevant REQUIRED, REQUISITE, SUFFICIENT, and OPTIONAL LoginModules succeeded), or by calling each configured LoginModule's abort method if the overall authentication failed. If authentication succeeded, each successful LoginModule's commit method associates the relevant Principals and Credentials with the Subject. If authentication failed, each LoginModule's abort method removes/destroys any previously stored state.

If the commit phase of the authentication process fails, then the overall authentication fails and this method invokes the abort method for each configured LoginModule.

If the abort phase fails for any reason, then this method propagates the original exception thrown either during the login phase or the commit phase. In either case, the overall authentication fails.

In the case where multiple LoginModules fail, this method propagates the exception raised by the first LoginModule which failed.

Note that if this method enters the abort phase (either the login or commit phase failed), this method invokes all LoginModules configured for the specified application regardless of their respective Configuration flag parameters. Essentially this means that Requisite and Sufficient semantics are ignored during the abort phase. This guarantees that proper cleanup and state restoration can take place.

Throws:

LoginException - if the authentication fails.

logout

public void logout()
            throws LoginException

Logout the Subject.

This method invokes the logout method for each LoginModule configured for this LoginContext. Each LoginModule performs its respective logout procedure which may include removing/destroying Principal and Credential information from the Subject and state cleanup.

Note that this method invokes all LoginModules configured for the specified application regardless of their respective Configuration flag parameters. Essentially this means that Requisite and Sufficient semantics are ignored for this method. This guarantees that proper cleanup and state restoration can take place.

Throws:

LoginException - if the logout fails.

getSubject

public Subject getSubject()

Return the authenticated Subject.

Returns:

the authenticated Subject. If authentication fails and a Subject was not provided to this LoginContext's constructor, this method returns null. Otherwise, this method returns the provided Subject.