# 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. 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`
   - If the constructor has a Subject input parameter, the LoginContext uses the caller-specified Subject object.
   - If the caller specifies a `null` Subject and a `null` value is permitted, the LoginContext instantiates a new Subject.
   - If the constructor does not have a Subject input parameter, the LoginContext instantiates a new Subject.
2. `Configuration`
   - If the constructor has a Configuration input parameter and the caller specifies a non-null Configuration, the LoginContext uses the caller-specified Configuration.

     If the constructor does not have a Configuration input parameter, or if the caller specifies a `null` Configuration object, the constructor uses the following call to get the installed Configuration:

               config = Configuration.getConfiguration();

     For both cases, the name argument given to the constructor is passed to the `Configuration.getAppConfigurationEntry` method. If the Configuration has no entries for the specified name, then the `LoginContext` calls `getAppConfigurationEntry` with the name, "other" (the default entry name). If there is no entry for "other", then a `LoginException` is thrown.
3. `CallbackHandler`
   - If the constructor has a CallbackHandler input parameter, the LoginContext uses the caller-specified CallbackHandler object.
   - If the constructor does not have a CallbackHandler input parameter, or if the caller specifies a `null` CallbackHandler object (and a `null` value is permitted), the LoginContext queries the `auth.login.defaultCallbackHandler` security property for the fully qualified class name of a default handler implementation. If the security property is not set, then the underlying modules will not have a CallbackHandler for use in communicating with users. The caller thus assumes that the configured modules have alternative means for authenticating the user.

Since:
  1.4
See Also:
  - `Security`
  - `Subject`
  - `CallbackHandler`
  - `Configuration`
  - `LoginModule`
  - security properties

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `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

  Modifier and Type
  Method
  Description
  `Subject`
  `getSubject()`
  Return the authenticated Subject.
  `void`
  `login()`
  Perform the authentication.
  `void`
  `logout()`
  Logout the `Subject`.

  ### Methods declared in class java.lang.Object

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

- ## Constructor Details

  - ### 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.

  - ### 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.

  - ### 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`.

  - ### 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`.

  - ### 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".
    Since:
      1.5

- ## Method Details

  - ### 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.