Java™ Platform
Standard Ed. 6

javax.security.auth.login
Class LoginContext

java.lang.Object
  extended by 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. 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. Applications 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 a LoginContext with a name and a CallbackHandler. LoginContext uses the name as the index into a 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. The login method invokes the configured modules to perform their respective types of authentication (username/password, smart card pin verification, etc.). Note that the LoginModules will not attempt authentication retries nor introduce delays if the authentication fails. Such tasks belong to the LoginContext caller.

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 calls the logout method. As with the login method, this logout method invokes the logout method for the configured modules.

A LoginContext should not be used to authenticate more than one Subject. A separate LoginContext should be used to authenticate each different Subject.

The following documentation applies to all LoginContext constructors:

  1. Subject
  2. Configuration
  3. CallbackHandler

Note that Security Properties (such as auth.login.defaultCallbackHandler) can be set programmatically via the java.security.Security class, or statically in the Java security properties file located in the file named <JAVA_HOME>/lib/security/java.security. <JAVA_HOME> refers to the value of the java.home system property, and specifies the directory where the JRE is installed.

See Also:
Security, AuthPermission, Subject, CallbackHandler, Configuration, LoginModule

Constructor Summary
LoginContext(String name)
          Instantiate a new LoginContext object with a name.
LoginContext(String name, CallbackHandler callbackHandler)
          Instantiate a new LoginContext object with a name and a CallbackHandler object.
LoginContext(String name, Subject subject)
          Instantiate a new LoginContext object with a name and a Subject object.
LoginContext(String name, Subject subject, CallbackHandler callbackHandler)
          Instantiate a new LoginContext object with a name, a Subject to be authenticated, and a CallbackHandler object.
LoginContext(String name, Subject subject, CallbackHandler callbackHandler, Configuration config)
          Instantiate a new LoginContext object with a name, a Subject to be authenticated, a CallbackHandler object, and a login Configuration.
 
Method Summary
 Subject getSubject()
          Return the authenticated Subject.
 void login()
          Perform the authentication.
 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
Instantiate a new LoginContext object with a name.

Parameters:
name - the name used as the index into the Configuration.
Throws:
LoginException - if the caller-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.

SecurityException - if a SecurityManager is set and the caller does not have AuthPermission("createLoginContext.name"), or if a configuration entry for name does not exist and the caller does not additionally have AuthPermission("createLoginContext.other")

LoginContext

public LoginContext(String name,
                    Subject subject)
             throws LoginException
Instantiate a new LoginContext object with a name and a Subject object.

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

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

SecurityException - if a SecurityManager is set and the caller does not have AuthPermission("createLoginContext.name"), or if a configuration entry for name does not exist and the caller does not additionally have AuthPermission("createLoginContext.other")

LoginContext

public LoginContext(String name,
                    CallbackHandler callbackHandler)
             throws LoginException
Instantiate a new LoginContext object with a name and a CallbackHandler object.

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 caller-specified name does not appear in the Configuration and there is no Configuration entry for "other", or if the caller-specified callbackHandler is null.

SecurityException - if a SecurityManager is set and the caller does not have AuthPermission("createLoginContext.name"), or if a configuration entry for name does not exist and the caller does not additionally have AuthPermission("createLoginContext.other")

LoginContext

public LoginContext(String name,
                    Subject subject,
                    CallbackHandler callbackHandler)
             throws LoginException
Instantiate a new LoginContext object with a name, a Subject to be authenticated, and a CallbackHandler object.

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 caller-specified name does not appear in the Configuration and there is no Configuration entry for "other", or if the caller-specified subject is null, or if the caller-specified callbackHandler is null.

SecurityException - if a SecurityManager is set and the caller does not have AuthPermission("createLoginContext.name"), or if a configuration entry for name does not exist and the caller does not additionally have AuthPermission("createLoginContext.other")

LoginContext

public LoginContext(String name,
                    Subject subject,
                    CallbackHandler callbackHandler,
                    Configuration config)
             throws LoginException
Instantiate a new LoginContext object with a name, a Subject to be authenticated, a CallbackHandler object, and a login Configuration.

Parameters:
name - the name used as the index into the caller-specified Configuration.

subject - the Subject to authenticate, or null.

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

config - the Configuration that lists the login modules to be called to perform the authentication, or null.
Throws:
LoginException - if the caller-specified name does not appear in the Configuration and there is no Configuration entry for "other".

SecurityException - if a SecurityManager is set, config is null, and either the caller does not have AuthPermission("createLoginContext.name"), or if a configuration entry for name does not exist and the caller does not additionally have AuthPermission("createLoginContext.other")
Since:
1.5
Method Detail

login

public void login()
           throws LoginException
Perform the authentication.

This method invokes the login method for each LoginModule configured for the name specified 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 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 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 the caller specified a Subject to this LoginContext's constructor, this method returns the caller-specified Subject. If a Subject was not specified and authentication succeeds, this method returns the Subject instantiated and used for authentication by this LoginContext. If a Subject was not specified, and authentication fails or has not been attempted, this method returns null.

Java™ Platform
Standard Ed. 6

Submit a bug or feature
For further API reference and developer documentation, see Java SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright 2008 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.