javax.security.auth.login Documentation Differences

This file contains all the changes in documentation in the package javax.security.auth.login as colored differences. Deletions are shown like this, and additions are shown like this.

If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.

Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

This class represents a single LoginModule entry configured for the application specified in the getAppConfigurationEntry(String appName) method in the Configuration class. Each respective AppConfigurationEntry contains a LoginModule name a control flag (specifying whether this LoginModule is REQUIRED REQUISITE SUFFICIENT or OPTIONAL) and LoginModule-specific options. Please refer to the Configuration class for more information on the different control flags and their semantics. @version 1.30 1231 02/0321/0102 @see javax.security.auth.login.Configuration

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. @version 1.92 1293 02/0321/0102 @see javax.security.auth.Subject @see javax.security.auth.callback.CallbackHandler @see javax.security.auth.login.Configuration @see javax.security.auth.spi.LoginModule