Class LoginContext
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
nullSubject and anullvalue 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
nullConfiguration 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 theConfiguration.getAppConfigurationEntrymethod. If the Configuration has no entries for the specified name, then theLoginContextcallsgetAppConfigurationEntrywith the name, "other" (the default entry name). If there is no entry for "other", then aLoginExceptionis thrown.
- If the constructor has a Configuration
input parameter and the caller specifies a non-null Configuration,
the LoginContext uses the caller-specified Configuration.
-
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
nullCallbackHandler object (and anullvalue is permitted), the LoginContext queries theauth.login.defaultCallbackHandlersecurity 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:
-
Constructor Summary
ConstructorsConstructorDescriptionLoginContext(String name) Instantiate a newLoginContextobject with a name.LoginContext(String name, CallbackHandler callbackHandler) Instantiate a newLoginContextobject with a name and aCallbackHandlerobject.LoginContext(String name, Subject subject) Instantiate a newLoginContextobject with a name and aSubjectobject.LoginContext(String name, Subject subject, CallbackHandler callbackHandler) Instantiate a newLoginContextobject with a name, aSubjectto be authenticated, and aCallbackHandlerobject.LoginContext(String name, Subject subject, CallbackHandler callbackHandler, Configuration config) Instantiate a newLoginContextobject with a name, aSubjectto be authenticated, aCallbackHandlerobject, and a loginConfiguration. -
Method Summary
-
Constructor Details
-
LoginContext
Instantiate a newLoginContextobject with a name.- Parameters:
name- the name used as the index into theConfiguration.- Throws:
LoginException- if the caller-specifiednamedoes not appear in theConfigurationand there is noConfigurationentry for "other", or if theauth.login.defaultCallbackHandlersecurity property was set, but the implementation class could not be loaded.
-
LoginContext
Instantiate a newLoginContextobject with a name and aSubjectobject.- Parameters:
name- the name used as the index into theConfiguration.subject- theSubjectto authenticate.- Throws:
LoginException- if the caller-specifiednamedoes not appear in theConfigurationand there is noConfigurationentry for "other", if the caller-specifiedsubjectisnull, or if the auth.login.defaultCallbackHandler security property was set, but the implementation class could not be loaded.
-
LoginContext
Instantiate a newLoginContextobject with a name and aCallbackHandlerobject.- Parameters:
name- the name used as the index into theConfiguration.callbackHandler- theCallbackHandlerobject used by LoginModules to communicate with the user.- Throws:
LoginException- if the caller-specifiednamedoes not appear in theConfigurationand there is noConfigurationentry for "other", or if the caller-specifiedcallbackHandlerisnull.
-
LoginContext
public LoginContext(String name, Subject subject, CallbackHandler callbackHandler) throws LoginException Instantiate a newLoginContextobject with a name, aSubjectto be authenticated, and aCallbackHandlerobject.- Parameters:
name- the name used as the index into theConfiguration.subject- theSubjectto authenticate.callbackHandler- theCallbackHandlerobject used by LoginModules to communicate with the user.- Throws:
LoginException- if the caller-specifiednamedoes not appear in theConfigurationand there is noConfigurationentry for "other", or if the caller-specifiedsubjectisnull, or if the caller-specifiedcallbackHandlerisnull.
-
LoginContext
public LoginContext(String name, Subject subject, CallbackHandler callbackHandler, Configuration config) throws LoginException Instantiate a newLoginContextobject with a name, aSubjectto be authenticated, aCallbackHandlerobject, and a loginConfiguration.- Parameters:
name- the name used as the index into the caller-specifiedConfiguration.subject- theSubjectto authenticate, ornull.callbackHandler- theCallbackHandlerobject used by LoginModules to communicate with the user, ornull.config- theConfigurationthat lists the login modules to be called to perform the authentication, ornull.- Throws:
LoginException- if the caller-specifiednamedoes not appear in theConfigurationand there is noConfigurationentry for "other".- Since:
- 1.5
-
-
Method Details
-
login
Perform the authentication.This method invokes the
loginmethod for each LoginModule configured for the name specified to theLoginContextconstructor, as determined by the loginConfiguration. EachLoginModulethen 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
commitmethod if the overall authentication succeeded (the relevant REQUIRED, REQUISITE, SUFFICIENT, and OPTIONAL LoginModules succeeded), or by calling each configured LoginModule'sabortmethod if the overall authentication failed. If authentication succeeded, each successful LoginModule'scommitmethod associates the relevant Principals and Credentials with theSubject. If authentication failed, each LoginModule'sabortmethod removes/destroys any previously stored state.If the
commitphase of the authentication process fails, then the overall authentication fails and this method invokes theabortmethod for each configuredLoginModule.If the
abortphase fails for any reason, then this method propagates the original exception thrown either during theloginphase or thecommitphase. In either case, the overall authentication fails.In the case where multiple LoginModules fail, this method propagates the exception raised by the first
LoginModulewhich failed.Note that if this method enters the
abortphase (either theloginorcommitphase failed), this method invokes all LoginModules configured for the application regardless of their respectiveConfigurationflag parameters. Essentially this means thatRequisiteandSufficientsemantics are ignored during theabortphase. This guarantees that proper cleanup and state restoration can take place.- Throws:
LoginException- if the authentication fails.
-
logout
Logout theSubject.This method invokes the
logoutmethod for eachLoginModuleconfigured for thisLoginContext. EachLoginModuleperforms its respective logout procedure which may include removing/destroyingPrincipalandCredentialinformation from theSubjectand state cleanup.Note that this method invokes all LoginModules configured for the application regardless of their respective
Configurationflag parameters. Essentially this means thatRequisiteandSufficientsemantics are ignored for this method. This guarantees that proper cleanup and state restoration can take place.- Throws:
LoginException- if the logout fails.
-
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.
-