OpenJDK 27 · javax.security.auth.login.LoginContext · APIdia, the JavaDoc alternative

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:

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

Modifier and Type	Class and Description
private static class	LoginContext.ModuleInfo LoginModule information - encapsulates Configuration info and actual module instances

Modifier and Type	Field and Description
private static final String	ABORT_METHOD
private CallbackHandler	callbackHandler
private static final String	COMMIT_METHOD
private Configuration	config
private ClassLoader	contextClassLoader
private static final Debug	debug
private static final String	DEFAULT_HANDLER
private LoginException	firstError
private LoginException	firstRequiredError
private static final String	LOGIN_METHOD
private boolean	loginSucceeded
private static final String	LOGOUT_METHOD
private int	moduleIndex
private LoginContext.ModuleInfo[]	moduleStack
private static final String	OTHER
private static final WeakHashMap<ClassLoader, Set<ServiceLoader.Provider<LoginModule>>>	providersCache
private final Map<String, ?>	state
private Subject	subject
private boolean	subjectProvided
private boolean	success

Constructor Summary

Access	Constructor and Description
public	LoginContext(String the name used as the index into the `Configuration`. name) Instantiate a new `LoginContext` object with a name.
public	LoginContext(String the name used as the index into the `Configuration`. name, Subject the `Subject` to authenticate. subject) Instantiate a new `LoginContext` object with a name and a `Subject` object.
public	LoginContext(String the name used as the index into the `Configuration`. name, CallbackHandler the `CallbackHandler` object used by LoginModules to communicate with the user. callbackHandler) Instantiate a new `LoginContext` object with a name and a `CallbackHandler` object.
public	LoginContext(String the name used as the index into the `Configuration`. name, Subject the `Subject` to authenticate. subject, CallbackHandler the `CallbackHandler` object used by LoginModules to communicate with the user. callbackHandler) Instantiate a new `LoginContext` object with a name, a `Subject` to be authenticated, and a `CallbackHandler` object.
public	LoginContext(String the name used as the index into the caller-specified `Configuration`. name, Subject the `Subject` to authenticate, or `null`. subject, CallbackHandler the `CallbackHandler` object used by LoginModules to communicate with the user, or `null`. callbackHandler, Configuration the `Configuration` that lists the login modules to be called to perform the authentication, or `null`. 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 and Description
private void	clearState()
public 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. getSubject() Return the authenticated Subject.
private void	init(String name)
private void	invoke(String methodName) Invokes the login, commit, and logout methods from a LoginModule.
private void	loadDefaultCallbackHandler()
public void	login() Perform the authentication.
public void	logout() Logout the `Subject`.
private void	throwException(LoginException originalError, LoginException le)

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

ABORT_METHOD	back to summary
private static final String ABORT_METHOD

callbackHandler	back to summary
private CallbackHandler callbackHandler

COMMIT_METHOD	back to summary
private static final String COMMIT_METHOD

config	back to summary
private Configuration config

contextClassLoader	back to summary
private ClassLoader contextClassLoader

debug	back to summary
private static final Debug debug

DEFAULT_HANDLER	back to summary
private static final String DEFAULT_HANDLER

firstError	back to summary
private LoginException firstError

firstRequiredError	back to summary
private LoginException firstRequiredError

LOGIN_METHOD	back to summary
private static final String LOGIN_METHOD

loginSucceeded	back to summary
private boolean loginSucceeded

LOGOUT_METHOD	back to summary
private static final String LOGOUT_METHOD

moduleIndex	back to summary
private int moduleIndex

moduleStack	back to summary
private LoginContext.ModuleInfo[] moduleStack

OTHER	back to summary
private static final String OTHER

providersCache	back to summary
private static final WeakHashMap<ClassLoader, Set<ServiceLoader.Provider<LoginModule>>> providersCache

state	back to summary
private final Map<String, ?> state

subject	back to summary
private Subject subject

subjectProvided	back to summary
private boolean subjectProvided

success	back to summary
private boolean success

Constructor Detail

LoginContext back to summary

LoginContext	back to summary
public LoginContext(String name) throws LoginException Instantiate a new `LoginContext` object with a name. Parameters name:String the name used as the index into the `Configuration`. Exceptions 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.

public LoginContext(String name) throws LoginException

Instantiate a new LoginContext object with a name.

Parameters

name:String: the name used as the index into the Configuration.

Exceptions

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 back to summary

LoginContext	back to summary
public LoginContext(String name, Subject subject) throws LoginException Instantiate a new `LoginContext` object with a name and a `Subject` object. Parameters name:String the name used as the index into the `Configuration`. subject:Subject the `Subject` to authenticate. Exceptions 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.

public LoginContext(String name, Subject subject) throws LoginException

Instantiate a new LoginContext object with a name and a Subject object.

Parameters

name:String: the name used as the index into the Configuration.
subject:Subject: the Subject to authenticate.

Exceptions

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 back to summary

LoginContext	back to summary
public LoginContext(String name, CallbackHandler callbackHandler) throws LoginException Instantiate a new `LoginContext` object with a name and a `CallbackHandler` object. Parameters name:String the name used as the index into the `Configuration`. callbackHandler:CallbackHandler the `CallbackHandler` object used by LoginModules to communicate with the user. Exceptions 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`.

public LoginContext(String name, CallbackHandler callbackHandler) throws LoginException

Instantiate a new LoginContext object with a name and a CallbackHandler object.

Parameters

name:String: the name used as the index into the Configuration.
callbackHandler:CallbackHandler: the CallbackHandler object used by LoginModules to communicate with the user.

Exceptions

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 back to summary

LoginContext	back to summary
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:String the name used as the index into the `Configuration`. subject:Subject the `Subject` to authenticate. callbackHandler:CallbackHandler the `CallbackHandler` object used by LoginModules to communicate with the user. Exceptions 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`.

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:String: the name used as the index into the Configuration.
subject:Subject: the Subject to authenticate.
callbackHandler:CallbackHandler: the CallbackHandler object used by LoginModules to communicate with the user.

Exceptions

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 back to summary

LoginContext	back to summary
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:String the name used as the index into the caller-specified `Configuration`. subject:Subject the `Subject` to authenticate, or `null`. callbackHandler:CallbackHandler the `CallbackHandler` object used by LoginModules to communicate with the user, or `null`. config:Configuration the `Configuration` that lists the login modules to be called to perform the authentication, or `null`. Exceptions LoginException: if the caller-specified `name` does not appear in the `Configuration` and there is no `Configuration` entry for "other". Since 1.5

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:String: the name used as the index into the caller-specified Configuration.
subject:Subject: the Subject to authenticate, or null.
callbackHandler:CallbackHandler: the CallbackHandler object used by LoginModules to communicate with the user, or null.
config:Configuration: the Configuration that lists the login modules to be called to perform the authentication, or null.

Exceptions

LoginException:: if the caller-specified name does not appear in the Configuration and there is no Configuration entry for "other".

Since

1.5

Method Detail

clearState	back to summary
private void clearState()

getSubject	back to summary
public Subject getSubject() Return the authenticated Subject. Returns:Subject 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.

getSubject

back to summary

public Subject getSubject()

Return the authenticated Subject.

Returns:Subject: 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.

init	back to summary
private void init(String name) throws LoginException

invoke	back to summary
private void invoke(String methodName) throws LoginException Invokes the login, commit, and logout methods from a LoginModule.

loadDefaultCallbackHandler	back to summary
private void loadDefaultCallbackHandler() throws LoginException Annotations @SuppressWarnings:deprecation

login	back to summary
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. Exceptions LoginException: if the authentication fails.

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.

Exceptions

LoginException:: if the authentication fails.

logout back to summary

logout	back to summary
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. Exceptions LoginException: if the logout fails.

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.

Exceptions

LoginException:: if the logout fails.

public Class LoginContext

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class LoginContext.ModuleInfo

Modifier and Type	Field and Description
pack-priv AppConfigurationEntry	entry
pack-priv LoginModule	module