java.lang.Object | +--javax.security.auth.login.LoginContext
TheLoginContext 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. Therefore, different LoginModules can be plugged in under an application without requiring any modifications to the application itself.
In addition to supportingpluggable authentication, this class also supports the notion ofstacked authentication. In other words, an application may be configured to use more than oneLoginModule. For example, one could configure both a KerberosLoginModule and a smart cardLoginModule under an application.
A typical caller instantiates this class and passes in aname and aCallbackHandler.LoginContext uses thename as the index into theConfiguration 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 aLoginContext, it invokes thelogin method to authenticate aSubject. Thislogin method invokes thelogin method from each of the LoginModules configured for thename specified by the caller. EachLoginModule 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, thislogin method completes a 2-phase authentication process by then calling either thecommit method or theabort method for each of the configured LoginModules. Thecommit method for eachLoginModule gets invoked if the overall authentication succeeded, whereas theabort method for eachLoginModule gets invoked if the overall authentication failed. Each successful LoginModule'scommit method associates the relevant Principals (authenticated identities) and Credentials (authentication data such as cryptographic keys) with theSubject. Each LoginModule'sabort method cleans up or removes/destroys any previously stored authentication state.
If thelogin method returns without throwing an exception, then the overall authentication succeeded. The caller can then retrieve the newly authenticatedSubject by invoking thegetSubject method. Principals and Credentials associated with theSubject may be retrieved by invoking the Subject's respectivegetPrincipals,getPublicCredentials, andgetPrivateCredentials methods.
To logout theSubject, the caller simply needs to invoke thelogout method. As with thelogin method, thislogout method invokes thelogout method for eachLoginModule configured for thisLoginContext. Each LoginModule'slogout method cleans up state and removes/destroys Principals and Credentials from theSubject as appropriate.
Each of the configured LoginModules invoked by theLoginContext is initialized with aSubject to be authenticated, aCallbackHandler used to communicate with users, sharedLoginModule state, and LoginModule-specific options. If theLoginContext was not provided aSubject then it instantiates one itself. EachLoginModule which successfully authenticates a user updates theSubject with the relevant user information (Principals and Credentials). ThisSubject can then be returned via thegetSubject method from theLoginContext class if the overall authentication succeeds. Note that LoginModules are always invoked from within anAccessController.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 securityPolicy, the callers of the LoginModules do not require those Permissions.
ALoginContext supports authentication retries by the calling application. For example, a LoginContext'slogin method may be invoked multiple times if the user incorrectly types in a password. However, aLoginContext should not be used to authenticate more than oneSubject. A separateLoginContext should be used to authenticate each differentSubject.
Multiple calls into the sameLoginContext do not affect theLoginModule state, or the LoginModule-specific options.
Subject,CallbackHandler,Configuration,LoginModuleLoginContext(java.lang.String name)Constructor for the LoginContext class. | |
LoginContext(java.lang.String name,CallbackHandler callbackHandler)Constructor for the LoginContext class. | |
LoginContext(java.lang.String name,Subject subject)Constructor for the LoginContext class. | |
LoginContext(java.lang.String name,Subject subject,CallbackHandler callbackHandler)Constructor for the LoginContext class. | |
getSubject()Return the authenticated Subject. | |
login()Perform the authentication and, if successful, associate Principals and Credentials with the authenticated Subject. | |
logout()Logout the Subject. | |
| Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
publicLoginContext(java.lang.String name) throwsLoginException
LoginContext class. Initialize the newLoginContext object with a name.LoginContext uses the specified name as the index into theConfiguration to determine which LoginModules should be used. If the provided name does not match any in theConfiguration, then theLoginContext uses the defaultConfiguration entry, "other". If there is noConfiguration entry for "other", then aLoginException is thrown.
This constructor does not allow for aCallbackHandler. Therefore the underlying LoginModules will not have aCallbackHandler for use in communicating with users. The caller thus assumes that the configured LoginModules have alternative means for authenticating the user.
Since noSubject can be specified to this constructor, it instantiates aSubject itself.
name - the name used as the index into theConfiguration.LoginException - if the specifiednamedoes not appear in theConfigurationand there is noConfiguration entryfor "other".publicLoginContext(java.lang.String name,Subject subject) throwsLoginException
LoginContext class. Initialize the newLoginContext object with a name and aSubject object.
LoginContext uses the name as the index into theConfiguration to determine which LoginModules should be used. If the provided name does not match any in theConfiguration, then theLoginContext uses the defaultConfiguration entry, "other". If there is noConfiguration entry for "other", then aLoginException is thrown.
This constructor does not allow for aCallbackHandler. Therefore the underlying LoginModules will not have aCallbackHandler for use in communicating with users. The caller thus assumes that the configured LoginModules have alternative means for authenticating the user.
LoginContext passes theSubject object to configured LoginModules so they may perform additional authentication and update theSubject with new Principals and Credentials.
name - the name used as the index into theConfiguration.subject - theSubject to authenticate.LoginException - if the specifiednamedoes not appear in theConfiguration and there is noConfiguration entry for "other", or if the specifiedsubjectisnull.publicLoginContext(java.lang.String name,CallbackHandler callbackHandler) throwsLoginException
LoginContext class. Initialize the newLoginContext object with a name and aCallbackHandler object.
LoginContext uses the name as the index into theConfiguration to determine which LoginModules should be used. If the provided name does not match any in theConfiguration, then theLoginContext uses the defaultConfiguration entry, "other". If there is noConfiguration entry for "other", then aLoginException is thrown.
LoginContext passes theCallbackHandler object to configured LoginModules so they may communicate with the user. TheCallbackHandler object therefore allows LoginModules to remain independent of the different ways applications interact with users. ThisLoginContext must wrap the application-providedCallbackHandler in a newCallbackHandler implementation, whosehandle method implementation invokes the application-provided CallbackHandler'shandle method in ajava.security.AccessController.doPrivileged call constrained by the caller's currentAccessControlContext.
Since noSubject can be specified to this constructor, it instantiates aSubject itself.
name - the name used as the index into theConfiguration.callbackHandler - theCallbackHandler object used byLoginModules to communicate with the user.LoginException - if the specifiedname does not appear in theConfiguration and there is noConfiguration entry for "other", or if the specifiedcallbackHandler isnull.publicLoginContext(java.lang.String name,Subject subject,CallbackHandler callbackHandler) throwsLoginException
LoginContext class. Initialize the newLoginContext object with a name, aSubject to be authenticated, and aCallbackHandler object.
LoginContext uses the name as the index into theConfiguration to determine which LoginModules should be used. If the provided name does not match any in theConfiguration, then theLoginContext uses the defaultConfiguration entry, "other". If there is noConfiguration entry for "other", then aLoginException is thrown.
LoginContext passes theSubject object to configured LoginModules so they may perform additional authentication and update theSubject with new Principals and Credentials.
LoginContext passes theCallbackHandler object to configured LoginModules so they may communicate with the user. TheCallbackHandler object therefore allows LoginModules to remain independent of the different ways applications interact with users. ThisLoginContext must wrap the application-providedCallbackHandler in a newCallbackHandler implementation, whosehandle method implementation invokes the application-provided CallbackHandler'shandle method in ajava.security.AccessController.doPrivileged call constrained by the caller's currentAccessControlContext.
name - the name used as the index into theConfiguration.subject - theSubject to authenticate.callbackHandler - theCallbackHandler object used byLoginModules to communicate with the user.LoginException - if the specifiedname does not appear in theConfiguration and there is noConfiguration entry for "other", or if the specifiedsubject isnull, or if the specifiedcallbackHandler isnull.public voidlogin() throwsLoginException
Subject. This method invokes thelogin method for each LoginModule configured for thename provided 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'scommit 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 thecommit phase of the authentication process fails, then the overall authentication fails and this method invokes theabort method for each configuredLoginModule.
If theabort 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 firstLoginModule which failed.
Note that if this method enters theabort phase (either thelogin orcommit phase failed), this method invokes all LoginModules configured for the specified 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.
LoginException - if the authentication fails.public voidlogout() throwsLoginException
Subject. This method invokes thelogout 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 specified application regardless of their respectiveConfiguration flag parameters. Essentially this means thatRequisite andSufficient semantics are ignored for this method. This guarantees that proper cleanup and state restoration can take place.
LoginException - if the logout fails.publicSubjectgetSubject()
null.Otherwise, this method returns the provided Subject.