LoginContext (Java 2 Platform SE v1.4.1_"07")

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

JavaTM 2 Platform
Std. Ed. v1.4.1_"07"

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

JavaTM 2 Platform
Std. Ed. v1.4.1_"07"

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.