-
- All Known Implementing Classes:
JndiLoginModule,KeyStoreLoginModule,Krb5LoginModule,LdapLoginModule,NTLoginModule,UnixLoginModule
public interface LoginModuleService-provider interface for authentication technology providers. LoginModules are plugged in under applications to provide a particular type of authentication.
While applications write to the
LoginContextAPI, authentication technology providers implement theLoginModuleinterface. AConfigurationspecifies the LoginModule(s) to be used with a particular login application. Therefore different LoginModules can be plugged in under the application without requiring any modifications to the application itself.The
LoginContextis responsible for reading theConfigurationand instantiating the appropriate LoginModules. EachLoginModuleis initialized with aSubject, aCallbackHandler, sharedLoginModulestate, and LoginModule-specific options.The
Subjectrepresents theSubjectcurrently being authenticated and is updated with relevant Credentials if authentication succeeds. LoginModules use theCallbackHandlerto communicate with users. TheCallbackHandlermay be used to prompt for usernames and passwords, for example. Note that theCallbackHandlermay benull. LoginModules which absolutely require aCallbackHandlerto authenticate theSubjectmay throw aLoginException. LoginModules optionally use the shared state to share information or data among themselves.The LoginModule-specific options represent the options configured for this
LoginModuleby an administrator or user in the loginConfiguration. The options are defined by theLoginModuleitself and control the behavior within it. For example, aLoginModulemay define options to support debugging/testing capabilities. Options are defined using a key-value syntax, such as debug=true. TheLoginModulestores the options as aMapso that the values may be retrieved using the key. Note that there is no limit to the number of options aLoginModulechooses to define.The calling application sees the authentication process as a single operation. However, the authentication process within the
LoginModuleproceeds in two distinct phases. In the first phase, the LoginModule'sloginmethod gets invoked by the LoginContext'sloginmethod. Theloginmethod for theLoginModulethen performs the actual authentication (prompt for and verify a password for example) and saves its authentication status as private state information. Once finished, the LoginModule'sloginmethod either returnstrue(if it succeeded) orfalse(if it should be ignored), or throws aLoginExceptionto specify a failure. In the failure case, theLoginModulemust not retry the authentication or introduce delays. The responsibility of such tasks belongs to the application. If the application attempts to retry the authentication, the LoginModule'sloginmethod will be called again.In the second phase, if the LoginContext's overall authentication succeeded (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules succeeded), then the
commitmethod for theLoginModulegets invoked. Thecommitmethod for aLoginModulechecks its privately saved state to see if its own authentication succeeded. If the overallLoginContextauthentication succeeded and the LoginModule's own authentication succeeded, then thecommitmethod associates the relevant Principals (authenticated identities) and Credentials (authentication data such as cryptographic keys) with theSubjectlocated within theLoginModule.If the LoginContext's overall authentication failed (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules did not succeed), then the
abortmethod for eachLoginModulegets invoked. In this case, theLoginModuleremoves/destroys any authentication state originally saved.Logging out a
Subjectinvolves only one phase. TheLoginContextinvokes the LoginModule'slogoutmethod. Thelogoutmethod for theLoginModulethen performs the logout procedures, such as removing Principals or Credentials from theSubjector logging session information.A
LoginModuleimplementation must have a constructor with no arguments. This allows classes which load theLoginModuleto instantiate it.- Since:
- 1.4
- See Also:
LoginContext,Configuration
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description booleanabort()Method to abort the authentication process (phase 2).booleancommit()Method to commit the authentication process (phase 2).voidinitialize(Subject subject, CallbackHandler callbackHandler, Map<String,?> sharedState, Map<String,?> options)Initialize thisLoginModule.booleanlogin()Method to authenticate aSubject(phase 1).booleanlogout()Method which logs out aSubject.
-
-
-
Method Detail
-
initialize
void initialize(Subject subject, CallbackHandler callbackHandler, Map<String,?> sharedState, Map<String,?> options)
Initialize thisLoginModule.This method is called by the
LoginContextafter thisLoginModulehas been instantiated. The purpose of this method is to initialize thisLoginModulewith the relevant information. If thisLoginModuledoes not understand any of the data stored insharedStateoroptionsparameters, they can be ignored.- Parameters:
subject- theSubjectto be authenticated.callbackHandler- aCallbackHandlerfor communicating with the end user (prompting for usernames and passwords, for example).sharedState- state shared with other configured LoginModules.options- options specified in the loginConfigurationfor this particularLoginModule.
-
login
boolean login() throws LoginExceptionMethod to authenticate aSubject(phase 1).The implementation of this method authenticates a
Subject. For example, it may prompt forSubjectinformation such as a username and password and then attempt to verify the password. This method saves the result of the authentication attempt as private state within theLoginModule.- Returns:
trueif the authentication succeeded, orfalseif thisLoginModuleshould be ignored.- Throws:
LoginException- if the authentication fails
-
commit
boolean commit() throws LoginExceptionMethod to commit the authentication process (phase 2).This method is called if the LoginContext's overall authentication succeeded (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules succeeded).
If this LoginModule's own authentication attempt succeeded (checked by retrieving the private state saved by the
loginmethod), then this method associates relevant Principals and Credentials with theSubjectlocated in theLoginModule. If this LoginModule's own authentication attempted failed, then this method removes/destroys any state that was originally saved.- Returns:
trueif this method succeeded, orfalseif thisLoginModuleshould be ignored.- Throws:
LoginException- if the commit fails
-
abort
boolean abort() throws LoginExceptionMethod to abort the authentication process (phase 2).This method is called if the LoginContext's overall authentication failed. (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules did not succeed).
If this LoginModule's own authentication attempt succeeded (checked by retrieving the private state saved by the
loginmethod), then this method cleans up any state that was originally saved.- Returns:
trueif this method succeeded, orfalseif thisLoginModuleshould be ignored.- Throws:
LoginException- if the abort fails
-
logout
boolean logout() throws LoginExceptionMethod which logs out aSubject.An implementation of this method might remove/destroy a Subject's Principals and Credentials.
- Implementation Note:
- Implementations should check if a variable is
nullbefore removing it from the Principals or Credentials set of aSubject, otherwise aNullPointerExceptionwill be thrown as these sets prohibit null elements. This is especially important if this method is called after a login failure. - Returns:
trueif this method succeeded, orfalseif thisLoginModuleshould be ignored.- Throws:
LoginException- if the logout fails
-
-