Login Context

The javax.security.auth.login.LoginContext class provides the basic methods used to authenticate subjects, and provides a way to develop an application independent of the underlying authentication technology. The LoginContext consults a Configuration to determine the authentication services, or LoginModules, configured for a particular application. Therefore, different LoginModules can be plugged in under an application without requiring any modifications to the application itself.

LoginContext offers four constructors from which to choose:

    public LoginContext(String name) throws LoginException;

    public LoginContext(String name, Subject subject) throws LoginException;

    public LoginContext(String name, CallbackHandler callbackHandler)
           throws LoginException

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

All of the constructors share a common parameter: name. This argument is used by the LoginContext as an index into the login Configuration to determine which LoginModules are configured for the application instantiating the LoginContext. Constructors that do not take a Subject as an input parameter instantiate a new Subject. Null inputs are disallowed for all constructors. Callers require an AuthPermission with target "createLoginContext.<name>" to instantiate a LoginContext. Here, <name> refers to the name of the login configuration entry that the application references in the name parameter for the LoginContext instantiation.

See the Callback Handler section for information on what a CallbackHandler is and when you may need one.

Actual authentication occurs with a call to the following method:

    public void login() throws LoginException;

When login is invoked, all of the configured LoginModules are invoked to perform the authentication. If the authentication succeeded, the Subject (which may now hold Principals, public credentials, and private credentials) can be retrieved by using the following method:

     public Subject getSubject();

To logout a Subject and remove its authenticated Principals and credentials, the following method is provided:

    public void logout() throws LoginException;

The following snippet of code in an application will authenticate a Subject called "bob" after accessing a configuration file with a configuration entry named "moduleFoo":

    Subject bob = new Subject();
    LoginContext lc = new LoginContext("moduleFoo", bob);
    try {
        lc.login();
        System.out.println("authentication successful");
    } catch (LoginException le) {
        System.out.println("authentication unsuccessful"+le.printStackTrace());
    }

This snippet of code in an application will authenticate a "nameless" Subject and then use the getSubject method to retrieve it:

    LoginContext lc = new LoginContext("moduleFoo");
    try {
        lc.login();
        System.out.println("authentication successful");
    } catch (LoginException le) {
        System.out.println("authentication unsuccessful"+le.printStackTrace());
    }
    Subject subject = lc.getSubject();

If the authentication failed, then getSubject returns null. Also, there isn't an AuthPermission("getSubject") required to do this as is the case for Subject.getSubject