LoginModule describes the interface implemented by authentication technology providers. LoginModules are plugged in under applications to provide a particular type of authentication.
While applications write to theLoginContext API, authentication technology providers implement theLoginModule interface. AConfiguration specifies 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.
TheLoginContext is responsible for reading theConfiguration and instantiating the appropriate LoginModules. EachLoginModule is initialized with aSubject, aCallbackHandler, sharedLoginModule state, and LoginModule-specific options. TheSubject represents theSubject currently being authenticated and is updated with relevant Credentials if authentication succeeds. LoginModules use theCallbackHandler to communicate with users. TheCallbackHandler may be used to prompt for usernames and passwords, for example. Note that theCallbackHandler may be null. LoginModules which absolutely require aCallbackHandler to authenticate theSubject may throw aLoginException. LoginModules optionally use the shared state to share information or data among themselves.
The LoginModule-specific options represent the options configured for thisLoginModule by an administrator or user in the loginConfiguration. The options are defined by theLoginModule itself and control the behavior within it. For example, aLoginModule may define options to support debugging/testing capabilities. Options are defined using a key-value syntax, such asdebug=true. TheLoginModule stores the options as aMap so that the values may be retrieved using the key. Note that there is no limit to the number of options aLoginModule chooses to define.
The calling application sees the authentication process as a single operation. However, the authentication process within theLoginModule proceeds in two distinct phases. In the first phase, the LoginModule'slogin method gets invoked by the LoginContext'slogin method. Thelogin method for theLoginModule then 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'slogin method either returnstrue (if it succeeded) orfalse (if it should be ignored), or throws aLoginException to specify a failure. In the failure case, theLoginModule must 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'slogin method 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 thecommit method for theLoginModule gets invoked. Thecommit method for aLoginModule checks its privately saved state to see if its own authentication succeeded. If the overallLoginContext authentication succeeded and the LoginModule's own authentication succeeded, then thecommit method associates the relevant Principals (authenticated identities) and Credentials (authentication data such as cryptographic keys) with theSubject located within theLoginModule.
If the LoginContext's overall authentication failed (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules did not succeed), then theabort method for eachLoginModule gets invoked. In this case, theLoginModule removes/destroys any authentication state originally saved.
Logging out aSubject involves only one phase. TheLoginContext invokes the LoginModule'slogout method. Thelogout method for theLoginModule then performs the logout procedures, such as removing Principals or Credentials from theSubject or logging session information.
ALoginModule implementation must have a constructor with no arguments. This allows classes which load theLoginModule to instantiate it.
LoginContext,Configurationabort()Method to abort the authentication process (phase 2). | |
commit()Method to commit the authentication process (phase 2). | |
initialize(Subject subject,CallbackHandler callbackHandler, java.util.Map sharedState, java.util.Map options)Initialize this LoginModule. | |
login()Method to authenticate a Subject (phase 1). | |
logout()Method which logs out a Subject. | |
public voidinitialize(Subject subject,CallbackHandler callbackHandler, java.util.Map sharedState, java.util.Map options)
This method is called by theLoginContext after thisLoginModule has been instantiated. The purpose of this method is to initialize thisLoginModule with the relevant information. If thisLoginModule does not understand any of the data stored insharedState oroptions parameters, they can be ignored.
subject - theSubject to be authenticated.callbackHandler - aCallbackHandler for communicatingwith the end user (prompting for usernames andpasswords, for example).sharedState - state shared with other configured LoginModules.options - options specified in the loginConfiguration for this particularLoginModule.public booleanlogin() throwsLoginException
Subject (phase 1). The implementation of this method authenticates aSubject. For example, it may prompt forSubject information 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 the LoginModule.
LoginModule should be ignored.LoginException - if the authentication failspublic booleancommit() throwsLoginException
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 thelogin method), then this method associates relevant Principals and Credentials with theSubject located in theLoginModule. If this LoginModule's own authentication attempted failed, then this method removes/destroys any state that was originally saved.
LoginModule should be ignored.LoginException - if the commit failspublic booleanabort() throwsLoginException
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 thelogin method), then this method cleans up any state that was originally saved.
LoginModule should be ignored.LoginException - if the abort failspublic booleanlogout() throwsLoginException
Subject.An implementation of this method might remove/destroy a Subject's Principals and Credentials.
LoginModule should be ignored.LoginException - if the logout fails