javax.security.auth.login
Class LoginContext
- java.lang.Object
javax.security.auth.login.LoginContext
- public class LoginContext
- extends java.lang.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.
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.
- 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
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. - 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.doPrivilegedcall 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
AccessControlContextfor the caller, and invokes the configured modules from within anAccessController.doPrivilegedcall 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
nullCallbackHandler object (and anullvalue 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
handlemethod implementation invokes the specified CallbackHandler'shandlemethod in ajava.security.AccessController.doPrivilegedcall 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 the
java.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.
Constructor Summary
| Constructor and Description |
|---|
LoginContext(java.lang.String name)
Instantiate a new
LoginContext object with a name.
|
LoginContext(java.lang.String name,CallbackHandler callbackHandler)
Instantiate a new
LoginContext object with a name
and a CallbackHandler object.
|
LoginContext(java.lang.String name,Subject subject)
Instantiate a new
LoginContext object with a name
and a Subject object.
|
LoginContext(java.lang.String name,Subject subject,CallbackHandler callbackHandler)
Instantiate a new
LoginContext object with a name,
a Subject to be authenticated, and a
CallbackHandler object.
|
LoginContext(java.lang.String name,Subject subject,CallbackHandler callbackHandler,Configuration 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 |
|---|---|
getSubject()
Return the authenticated Subject.
|
|
|
login()
Perform the authentication.
|
|
logout()
Logout the
Subject.
|
| Methods inherited from class java.lang.Object |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail
LoginContext
- public LoginContext(java.lang.String name)
- throws LoginException
name - the name used as the index into the
Configuration. 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.
java.lang.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(java.lang.String name,
- Subject subject)
- throws LoginException
LoginContext object with a name
and a Subject object.
name - the name used as the index into the
Configuration.
subject - the Subject to authenticate. 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.
java.lang.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(java.lang.String name,
- CallbackHandler callbackHandler)
- throws LoginException
LoginContext object with a name
and a CallbackHandler object.
name - the name used as the index into the
Configuration.
callbackHandler - the CallbackHandler object used by
LoginModules to communicate with the user. 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.
java.lang.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(java.lang.String name,
- Subject subject,
- CallbackHandler callbackHandler)
- throws LoginException
LoginContext object with a name,
a Subject to be authenticated, and a
CallbackHandler object.
name - the name used as the index into the
Configuration.
subject - the Subject to authenticate.
callbackHandler - the CallbackHandler object used by
LoginModules to communicate with the user. 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.
java.lang.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(java.lang.String name,
- Subject subject,
- CallbackHandler callbackHandler,
- Configuration config)
- throws LoginException
LoginContext object with a name,
a Subject to be authenticated,
a CallbackHandler object, and a login
Configuration.
name - the name used as the index into the caller-specified
Configuration.
subject - the Subject to authenticate,
or null.
callbackHandler - the CallbackHandler object used by
LoginModules to communicate with the user, or null.
config - the Configuration that lists the
login modules to be called to perform the authentication,
or null. LoginException - if the caller-specified name
does not appear in the Configuration
and there is no Configuration entry
for "other".
java.lang.SecurityException - if a SecurityManager is set,
config is null,
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") Method Detail
login
- public void login()
- throws LoginException
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.
LoginException - if the authentication fails. logout
- public void logout()
- throws LoginException
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.
LoginException - if the logout fails. getSubject
- public Subject getSubject()
LoginContextobject with a name.