|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object | +--javax.security.auth.login.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.
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.
Subject,
CallbackHandler,
Configuration,
LoginModule| Constructor Summary | |
java.lang.String)">LoginContext(java.lang.String name)
Constructor for the LoginContext class. |
|
java.lang.String, javax.security.auth.callback.CallbackHandler)">LoginContext(java.lang.String name,
CallbackHandler callbackHandler)
Constructor for the LoginContext class. |
|
java.lang.String, javax.security.auth.Subject)">LoginContext(java.lang.String name,
Subject subject)
Constructor for the LoginContext class. |
|
java.lang.String, javax.security.auth.Subject, javax.security.auth.callback.CallbackHandler)">LoginContext(java.lang.String name,
Subject subject,
CallbackHandler callbackHandler)
Constructor for the LoginContext class. |
|
| Method Summary | |
Subject |
getSubject()
Return the authenticated Subject. |
void |
login()
Perform the authentication and, if successful, associate Principals and Credentials with the authenticated Subject. |
void |
logout()
Logout the Subject. |
| Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Constructor Detail |
public LoginContext(java.lang.String name)
throws LoginException
LoginContext class.
Initialize the new LoginContext object with a name.
LoginContext uses the specified name as the index
into the Configuration to determine which LoginModules
should be used. If the provided name does not match any in the
Configuration, then the LoginContext
uses the default Configuration entry, "other".
If there is no Configuration entry for "other",
then a LoginException is thrown.
This constructor does not allow for a CallbackHandler. Therefore the underlying LoginModules will not have a CallbackHandler for use in communicating with users. The caller thus assumes that the configured LoginModules have alternative means for authenticating the user.
Since no Subject can be specified to this constructor, it instantiates a Subject itself.
name - the name used as the index into the
Configuration.LoginException - if the specified name
does not appear in the Configuration
and there is no Configuration entry
for "other".
public LoginContext(java.lang.String name,
Subject subject)
throws LoginException
LoginContext class.
Initialize the new LoginContext object with a name
and a Subject object.
LoginContext uses the name as the index
into the Configuration to determine which LoginModules
should be used. If the provided name does not match any in the
Configuration, then the LoginContext
uses the default Configuration entry, "other".
If there is no Configuration entry for "other",
then a LoginException is thrown.
This constructor does not allow for a CallbackHandler. Therefore the underlying LoginModules will not have a CallbackHandler for use in communicating with users. The caller thus assumes that the configured LoginModules have alternative means for authenticating the user.
LoginContext passes the Subject
object to configured LoginModules so they may perform additional
authentication and update the Subject with new
Principals and Credentials.
name - the name used as the index into the
Configuration. subject - the Subject to authenticate.LoginException - if the specified name
does not appear in the Configuration
and there is no Configuration entry
for "other", or if the specified subject
is null.
public LoginContext(java.lang.String name,
CallbackHandler callbackHandler)
throws LoginException
LoginContext class.
Initialize the new LoginContext object with a name
and a CallbackHandler object.
LoginContext uses the name as the index
into the Configuration to determine which LoginModules
should be used. If the provided name does not match any in the
Configuration, then the LoginContext
uses the default Configuration entry, "other".
If there is no Configuration entry for "other",
then a LoginException is thrown.
LoginContext passes the CallbackHandler
object to configured LoginModules so they may communicate with the user.
The CallbackHandler object therefore allows LoginModules to
remain independent of the different ways applications interact with
users. This LoginContext must wrap the
application-provided CallbackHandler in a new
CallbackHandler implementation, whose handle
method implementation invokes the application-provided
CallbackHandler's handle method in a
java.security.AccessController.doPrivileged call
constrained by the caller's current AccessControlContext.
Since no Subject can be specified to this constructor, it instantiates a Subject itself.
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 specified name
does not appear in the Configuration
and there is no Configuration entry
for "other", or if the specified
callbackHandler is null.
public LoginContext(java.lang.String name,
Subject subject,
CallbackHandler callbackHandler)
throws LoginException
LoginContext class.
Initialize the new LoginContext object with a name,
a Subject to be authenticated, and a
CallbackHandler object.
LoginContext uses the name as the index
into the Configuration to determine which LoginModules
should be used. If the provided name does not match any in the
Configuration, then the LoginContext
uses the default Configuration entry, "other".
If there is no Configuration entry for "other",
then a LoginException is thrown.
LoginContext passes the Subject
object to configured LoginModules so they may perform additional
authentication and update the Subject with new
Principals and Credentials.
LoginContext passes the CallbackHandler
object to configured LoginModules so they may communicate with the user.
The CallbackHandler object therefore allows LoginModules to
remain independent of the different ways applications interact with
users. This LoginContext must wrap the
application-provided CallbackHandler in a new
CallbackHandler implementation, whose handle
method implementation invokes the application-provided
CallbackHandler's handle method in a
java.security.AccessController.doPrivileged call
constrained by the caller's current AccessControlContext.
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 specified name
does not appear in the Configuration
and there is no Configuration entry
for "other", or if the specified subject
is null, or if the specified
callbackHandler is null.| Method Detail |
public void login()
throws LoginException
This method invokes the login method for each
LoginModule configured for the name provided 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 specified
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.
public void logout()
throws LoginException
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
specified 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.public Subject getSubject()
null.
Otherwise, this method returns the provided Subject.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||