- 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. AConfiguration
specifies the authentication technology, orLoginModule
, 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. TheCallbackHandler
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 aSubject
. Thelogin
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 thegetSubject
method. Principals and Credentials associated with the Subject may be retrieved by invoking the Subject's respectivegetPrincipals
,getPublicCredentials
, andgetPrivateCredentials
methods.To logout the Subject, the caller calls the
logout
method. As with thelogin
method, thislogout
method invokes thelogout
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 anull
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.
- If the constructor has a Subject
input parameter, the LoginContext uses the caller-specified
Subject object.
-
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 theConfiguration.getAppConfigurationEntry
method. If the Configuration has no entries for the specified name, then theLoginContext
callsgetAppConfigurationEntry
with the name, "other" (the default entry name). If there is no entry for "other", then aLoginException
is thrown. - When LoginContext uses the installed Configuration, the caller
requires the createLoginContext.name and possibly
createLoginContext.other AuthPermissions. Furthermore, the
LoginContext will invoke configured modules from within an
AccessController.doPrivileged
call so that modules that perform security-sensitive tasks (such as connecting to remote hosts, and updating the Subject) will require the respective permissions, but the callers of the LoginContext will not require those permissions. - When LoginContext uses a caller-specified Configuration, the caller
does not require any createLoginContext AuthPermission. The LoginContext
saves the
AccessControlContext
for the caller, and invokes the configured modules from within an AccessController.doPrivileged call constrained by that context. This means the caller context (stored when the LoginContext was created) must have sufficient permissions to perform any security-sensitive tasks that the modules may perform.
- 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
null
CallbackHandler object (and anull
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. - When the LoginContext uses the installed Configuration (instead of
a caller-specified Configuration, see above),
then this LoginContext must wrap any
caller-specified or default CallbackHandler implementation
in a new CallbackHandler implementation
whose
handle
method implementation invokes the specified CallbackHandler'shandle
method in ajava.security.AccessController.doPrivileged
call constrained by the caller's currentAccessControlContext
.
- If the constructor has a CallbackHandler
input parameter, the LoginContext uses the caller-specified
CallbackHandler object.
Note that Security Properties (such as
auth.login.defaultCallbackHandler
) can be set programmatically via thejava.security.Security
class, or statically in the Java security properties file located in the file named <JAVA_HOME>/lib/security/java.security. <JAVA_HOME> refers to the value of the java.home system property, and specifies the directory where the JRE is installed.- See Also:
Security
,AuthPermission
,Subject
,CallbackHandler
,Configuration
,LoginModule
-
-
-
Constructor Summary
Constructors Constructor and Description LoginContext(String name)
Instantiate a newLoginContext
object with a name.LoginContext(String name, CallbackHandler callbackHandler)
Instantiate a newLoginContext
object with a name and aCallbackHandler
object.LoginContext(String name, Subject subject)
Instantiate a newLoginContext
object with a name and aSubject
object.LoginContext(String name, Subject subject, CallbackHandler callbackHandler)
Instantiate a newLoginContext
object with a name, aSubject
to be authenticated, and aCallbackHandler
object.LoginContext(String name, Subject subject, CallbackHandler callbackHandler, Configuration config)
Instantiate a newLoginContext
object with a name, aSubject
to be authenticated, aCallbackHandler
object, and a loginConfiguration
.
-
Method Summary
Methods Modifier and Type Method and Description Subject
getSubject()
Return the authenticated Subject.void
login()
Perform the authentication.void
logout()
Logout theSubject
.
-
-
-
Constructor Detail
-
LoginContext
public LoginContext(String name) throws LoginException
Instantiate a newLoginContext
object with a name.- Parameters:
name
- the name used as the index into theConfiguration
.- Throws:
LoginException
- if the caller-specifiedname
does not appear in theConfiguration
and there is noConfiguration
entry for "other", or if the auth.login.defaultCallbackHandler security property was set, but the implementation class could not be loaded.SecurityException
- if a SecurityManager is set and the caller does not have AuthPermission("createLoginContext.name"), or if a configuration entry for name does not exist and the caller does not additionally have AuthPermission("createLoginContext.other")
-
LoginContext
public LoginContext(String name, Subject subject) throws LoginException
Instantiate a newLoginContext
object with a name and aSubject
object.- Parameters:
name
- the name used as the index into theConfiguration
.subject
- theSubject
to authenticate.- Throws:
LoginException
- if the caller-specifiedname
does not appear in theConfiguration
and there is noConfiguration
entry for "other", if the caller-specifiedsubject
isnull
, or if the auth.login.defaultCallbackHandler security property was set, but the implementation class could not be loaded.SecurityException
- if a SecurityManager is set and the caller does not have AuthPermission("createLoginContext.name"), or if a configuration entry for name does not exist and the caller does not additionally have AuthPermission("createLoginContext.other")
-
LoginContext
public LoginContext(String name, CallbackHandler callbackHandler) throws LoginException
Instantiate a newLoginContext
object with a name and aCallbackHandler
object.- Parameters:
name
- the name used as the index into theConfiguration
.callbackHandler
- theCallbackHandler
object used by LoginModules to communicate with the user.- Throws:
LoginException
- if the caller-specifiedname
does not appear in theConfiguration
and there is noConfiguration
entry for "other", or if the caller-specifiedcallbackHandler
isnull
.SecurityException
- if a SecurityManager is set and the caller does not have AuthPermission("createLoginContext.name"), or if a configuration entry for name does not exist and the caller does not additionally have AuthPermission("createLoginContext.other")
-
LoginContext
public LoginContext(String name, Subject subject, CallbackHandler callbackHandler) throws LoginException
Instantiate a newLoginContext
object with a name, aSubject
to be authenticated, and aCallbackHandler
object.- Parameters:
name
- the name used as the index into theConfiguration
.subject
- theSubject
to authenticate.callbackHandler
- theCallbackHandler
object used by LoginModules to communicate with the user.- Throws:
LoginException
- if the caller-specifiedname
does not appear in theConfiguration
and there is noConfiguration
entry for "other", or if the caller-specifiedsubject
isnull
, or if the caller-specifiedcallbackHandler
isnull
.SecurityException
- if a SecurityManager is set and the caller does not have AuthPermission("createLoginContext.name"), or if a configuration entry for name does not exist and the caller does not additionally have AuthPermission("createLoginContext.other")
-
LoginContext
public LoginContext(String name, Subject subject, CallbackHandler callbackHandler, Configuration config) throws LoginException
Instantiate a newLoginContext
object with a name, aSubject
to be authenticated, aCallbackHandler
object, and a loginConfiguration
.- Parameters:
name
- the name used as the index into the caller-specifiedConfiguration
.subject
- theSubject
to authenticate, ornull
.callbackHandler
- theCallbackHandler
object used by LoginModules to communicate with the user, ornull
.config
- theConfiguration
that lists the login modules to be called to perform the authentication, ornull
.- Throws:
LoginException
- if the caller-specifiedname
does not appear in theConfiguration
and there is noConfiguration
entry for "other".SecurityException
- if a SecurityManager is set, config isnull
, and either the caller does not have AuthPermission("createLoginContext.name"), or if a configuration entry for name does not exist and the caller does not additionally have AuthPermission("createLoginContext.other")- Since:
- 1.5
-
-
Method Detail
-
login
public void login() throws LoginException
Perform the authentication.This method invokes the
login
method for each LoginModule configured for the name specified to theLoginContext
constructor, as determined by the loginConfiguration
. EachLoginModule
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'sabort
method if the overall authentication failed. If authentication succeeded, each successful LoginModule'scommit
method associates the relevant Principals and Credentials with theSubject
. If authentication failed, each LoginModule'sabort
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 theabort
method for each configuredLoginModule
.If the
abort
phase fails for any reason, then this method propagates the original exception thrown either during thelogin
phase or thecommit
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 thelogin
orcommit
phase failed), this method invokes all LoginModules configured for the application regardless of their respectiveConfiguration
flag parameters. Essentially this means thatRequisite
andSufficient
semantics are ignored during theabort
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 theSubject
.This method invokes the
logout
method for eachLoginModule
configured for thisLoginContext
. EachLoginModule
performs its respective logout procedure which may include removing/destroyingPrincipal
andCredential
information from theSubject
and state cleanup.Note that this method invokes all LoginModules configured for the application regardless of their respective
Configuration
flag parameters. Essentially this means thatRequisite
andSufficient
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 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.
-
-
Document created the 11/06/2005, last modified the 04/03/2020
Source of the printed document:https://www.gaudry.be/en/java-api-rf-javax/security/auth/login/logincontext.html
The infobrol is a personal site whose content is my sole responsibility. The text is available under CreativeCommons license (BY-NC-SA). More info on the terms of use and the author.
References
These references and links indicate documents consulted during the writing of this page, or which may provide additional information, but the authors of these sources can not be held responsible for the content of this page.
The author This site is solely responsible for the way in which the various concepts, and the freedoms that are taken with the reference works, are presented here. Remember that you must cross multiple source information to reduce the risk of errors.