-
public interface LoginModule
Service-provider interface for authentication technology providers. LoginModules are plugged in under applications to provide a particular type of authentication.
While applications write to the
LoginContext
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.The
LoginContext
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 this
LoginModule
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 as debug=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 the
LoginModule
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 the
commit
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 the
abort
method for eachLoginModule
gets invoked. In this case, theLoginModule
removes/destroys any authentication state originally saved.Logging out a
Subject
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.A
LoginModule
implementation must have a constructor with no arguments. This allows classes which load theLoginModule
to instantiate it.- Since:
- 1.4
- See Also:
LoginContext
,Configuration
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description boolean
abort()
Method to abort the authentication process (phase 2).boolean
commit()
Method to commit the authentication process (phase 2).void
initialize(Subject subject, CallbackHandler callbackHandler, Map<String,?> sharedState, Map<String,?> options)
Initialize this LoginModule.boolean
login()
Method to authenticate aSubject
(phase 1).boolean
logout()
Method which logs out aSubject
.
-
-
-
Method Detail
-
initialize
void initialize(Subject subject, CallbackHandler callbackHandler, Map<String,?> sharedState, Map<String,?> options)
Initialize this LoginModule.This method is called by the
LoginContext
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.- Parameters:
subject
- theSubject
to be authenticated.callbackHandler
- aCallbackHandler
for communicating with the end user (prompting for usernames and passwords, for example).sharedState
- state shared with other configured LoginModules.options
- options specified in the loginConfiguration
for this particularLoginModule
.
-
login
boolean login() throws LoginException
Method to authenticate aSubject
(phase 1).The implementation of this method authenticates a
Subject
. 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.- Returns:
- true if the authentication succeeded, or false if this
LoginModule
should be ignored. - Throws:
LoginException
- if the authentication fails
-
commit
boolean commit() throws LoginException
Method 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
login
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.- Returns:
- true if this method succeeded, or false if this
LoginModule
should be ignored. - Throws:
LoginException
- if the commit fails
-
abort
boolean abort() throws LoginException
Method 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
login
method), then this method cleans up any state that was originally saved.- Returns:
- true if this method succeeded, or false if this
LoginModule
should be ignored. - Throws:
LoginException
- if the abort fails
-
logout
boolean logout() throws LoginException
Method which logs out aSubject
.An implementation of this method might remove/destroy a Subject's Principals and Credentials.
- Returns:
- true if this method succeeded, or false if this
LoginModule
should be ignored. - Throws:
LoginException
- if the logout fails
-
-