public abstract class AMLoginModule extends Object
Because it is an abstract class, Login Module writers must subclass and implement init(), process(), getPrincipal() methods.
The Callback[] for the Login Module is dynamically generated based on the xml module configuration. The module configuration file name must be the same as the name of the class (no package name) and have the extension .xml.
Here is a sample module configuration file:
<ModuleProperties moduleClass="LDAP" version="1.0" > <Callbacks length="2" order="1" timeout="60" header="LDAP Authentication" > <NameCallback> <Prompt> Enter UserId </Prompt> </NameCallback> <PasswordCallback echoPassword="false" > <Prompt> Enter Password </Prompt> </PasswordCallback> </Callbacks> <Callbacks length="3" order="2" timeout="120" header="Password Expiring Please Change" > <PasswordCallback echoPassword="false" > <Prompt> Enter Current Password </Prompt> </PasswordCallback> <PasswordCallback echoPassword="false" > <Prompt> Enter New Password </Prompt> </PasswordCallback> <PasswordCallback echoPassword="false" > <Prompt> Confirm New Password </Prompt> </PasswordCallback> </Callbacks> </ModuleProperties>Each Callbacks Element corresponds to one login state. When an authentication process is invoked, there will be Callback[] generated from user's Login Module for each state. All login state starts with 1, then module controls the login process, and decides what's the next state to go in the process() method.
In the sample module configuration shown above, state one has three Callbacks, Callback[0] is for module information, Callback[1] is for user ID, Callback[2] is for user password. When the user fills in the Callbacks, those Callback[] will be sent to the process() method, where the module writer gets the submitted Callbacks, validates them and returns. If user's password is expiring, the module writer will set the next state to 2. State two has four Callbacks to request user to change password. The process() routine is again called after user submits the Callback[]. If the module writer throws an LoginException, an 'authentication failed' page will be sent to the user. If no exception is thrown, the user will be redirected to their default page.
The optional 'timeout' attribute in each state is used to ensure that the user responds in a timely manner. If the time between sending the Callbacks and getting response is greater than the timeout, a timeout page will be sent.
There are also optional 'html' and 'image' attribute in each state. The 'html' attribute allows the module writer to use a custom HTML page for the Login UI. The 'image' attribute allows the writer to display a custom background image on each page.
When multiple states are available to the user, the Callback array from a
previous state may be retrieved by using the getCallbak(int)
methods. The underlying login module keeps the Callback[] from the previous
states until the login process is completed.
If a module writer need to substitute dynamic text in next state, the writer
could use the getCallback()
method to get the Callback[] for the
next state, modify the output text or prompt, then call
replaceCallback()
to update the Callback array. This allows a
module writer to dynamically generate challenges, passwords or user IDs.
Each authentication session will create a new instance of your Login Module Java class. The reference to the class will be released once the authentication session has either succeeded or failed. It is important to note that any static data or reference to any static data in your Login module must be thread-safe.
AMLoginModule will call
Here is a sample module schema for authentication level:
For a complete sample, please refer to
<install_root>/SUNWam/samples/authentication/providerssetAuthLevel()
method when authentication
has succeeded for each Login Module. The authentication level can be defined in
Login Module's service schema and the attribute name must conform to
forgerock-am-auth-
.
<AttributeSchema name="forgerock-am-auth-adaptive-auth-level"
cosQualifier="default"
type="single"
syntax="number"
i18nKey="a500"
order="100"
resourceName="authenticationLevel">
<DefaultValues>
<Value>0</Value>
</DefaultValues>
</AttributeSchema>
The final authentication level for a user's session is calculated to be the highest
authentication level of any authentication module that passed.
Modifier and Type | Method and Description |
---|---|
void |
clearInfoText(int state)
Clears the info text for a given callback state
|
void |
destroyModuleState()
This method should be overridden by each login module
to destroy dispensable state fields.
|
String |
getAttribute(int state,
int index)
Returns the attribute name for the specified callback in the
specified login state.
|
int |
getAuthLevel()
Returns authentication level that has been set for the module
|
Callback[] |
getCallback(int index)
Returns a Callback array for a specific state.
|
Callback[] |
getCallback(int index,
boolean fetchOrig)
Return a Callback array for a specific state.
|
int |
getCurrentState()
Returns the current state in the authentication process.
|
int |
getFailCount(AMIdentity amIdUser)
Get the number of failed login attempts for a user when account locking
is enabled.
|
javax.servlet.http.HttpServletRequest |
getHttpServletRequest()
Returns the
HttpServletRequest object that
initiated the call to this module. |
javax.servlet.http.HttpServletResponse |
getHttpServletResponse()
Returns the
HttpServletResponse object for the servlet
request that initiated the call to this module. |
String |
getInfoText(int state,
int index)
Returns the info text associated with a specific callback
|
String |
getLocale()
Returns the locale for this authentication session.
|
int |
getMaximumFailCount()
Get the maximum number failed login attempts permitted for a user
before when their account is locked out.
|
Set |
getNewUserIDs(Map attributes,
int num)
Returns a set of user IDs generated from the class defined
in the Core Authentication Service.
|
int |
getNumberOfStates()
Returns the number of authentication states for this
login module.
|
Map |
getOrgProfile(String orgDN)
Returns the organization attributes for specified organization.
|
Map |
getOrgServiceTemplate(String orgDN,
String serviceName)
Returns service template attributes defined for the specified
organization.
|
abstract Principal |
getPrincipal()
Abstract method must be implemeted by each login module to
get the user Principal
|
String |
getRequestOrg()
Returns the organization DN for this authentication session.
|
Map |
getServiceConfig(String name)
Returns service configuration attributes.
|
String |
getSessionId()
Returns a unique key for this authentication session.
|
SSOToken |
getSSOSession()
Returns an administration SSOToken for use the OpenAM APIs.
|
AMUser |
getUserProfile(String userDN)
Deprecated.
This method has been deprecated. Please use the
IdRepo API's to get the AMIdentity object for the user. More
information on how to use the Identity Repository APIs is
available in the "Customizing Identity Data Storage" chapter
of the OpenAM Developer's Guide.
|
String |
getUserSessionProperty(String name)
Returns the property from the user session.
|
Set<SSOToken> |
getUserSessions(String userName)
Returns the set of SSOTokens for a specified user
|
void |
incrementFailCount(String userName)
Increments the fail count for the given user.
|
abstract void |
init(Subject subject,
Map sharedState,
Map options)
Initialize this LoginModule.
|
boolean |
isAccountLocked(String userName)
Returns true if the named account is locked out, false otherwise.
|
boolean |
isRequired(int state,
int index)
Checks if a Callback is required to have input.
|
boolean |
isSessionQuotaReached(String userName)
Returns true if the user identified by the supplied username has reached
their session quota.
NBThe existing session count is exclusive of any session created as part of the running authentication process |
abstract int |
process(Callback[] callbacks,
int state)
Abstract method must be implemented by each login module to
control the flow of the login process.
|
void |
replaceCallback(int state,
int index,
Callback callback)
Replace Callback object for a specific state.
|
void |
resetCallback(int state,
int index)
Reset a Callback instance to the original Callback for the specified
state and the specified index.
|
boolean |
setAuthLevel(int auth_level)
Sets the
AuthLevel for this session. |
void |
setFailureID(String userID)
Sets the
userID of user who failed authentication. |
void |
setLoginFailureURL(String url)
Sets the the login failure URL for the user.
|
void |
setLoginSuccessURL(String url)
Sets the the login successful URL for the user.
|
void |
setUserAttributes(Map attributeValuePairs)
Sets a Map of attribute value pairs to be used when the authentication
service is configured to dynamically create a user.
|
void |
setUserSessionProperty(String name,
String value)
Sets a property in the user session.
|
void |
substituteHeader(int state,
String header)
Use this method to replace the header text from the XML file with new
text.
|
void |
substituteInfoText(int state,
int callback,
String infoText)
Allows you to set the info text for a specific callback.
|
void |
validatePassword(String userPassword)
Validate password for the distinguished user, this will use validation
plugin if exists to validate password
|
void |
validateUserName(String userName,
String regEx)
Validates the given user name by using validation plugin if exists
else it checks invalid characters in the source string.
|
public SSOToken getSSOSession() throws AuthLoginException
setUserSessionProperty
and getUserSessionProperty
method respectively.SSOToken
.AuthLoginException
- if the authentication SSO session
is null.public Callback[] getCallback(int index) throws AuthLoginException
This method can be used to retrieve Callback[] for any state. All previous submitted Callback[] information are kept until the login process is completed.
index
- order of stateAuthLoginException
- if unable to read the callbackspublic Callback[] getCallback(int index, boolean fetchOrig) throws AuthLoginException
This method can be used to retrieve Callback[] for any state. All previous submitted Callback[] information are kept until the login process is completed.
index
- order of statefetchOrig
- boolean indicating even if the callbacks for this
state have been previously retrieved, get the original callbacks
from AMModuleProperties, if set to "true".AuthLoginException
- if unable to read the callbackspublic void replaceCallback(int state, int index, Callback callback) throws AuthLoginException
state
- Order of login stateindex
- Index of Callback in the Callback array to be replaced
for the specified state. Here index starts with 0, i.e. 0 means the
first Callback in the Callback[], 1 means the second callback.callback
- Callback instance to be replacedAuthLoginException
- if state or index is out of
bound, or callback instance is null.public void substituteInfoText(int state, int callback, String infoText) throws AuthLoginException
state
- state in which the Callback[] to be resetcallback
- the callback to associate the info textinfoText
- the infotext for the callbackAuthLoginException
- if state/callback is out of boundspublic void clearInfoText(int state) throws AuthLoginException
state
- The state to clear all infotextsAuthLoginException
- Invalid statepublic void substituteHeader(int state, String header) throws AuthLoginException
state
- state state in which the Callback[] to be resetheader
- The text of the header to be replacedAuthLoginException
- if state is out of boundspublic void resetCallback(int state, int index) throws AuthLoginException
replaceCallback()
method.state
- state in which the Callback[] to be resetindex
- index order of the Callback in the Callback[], index starts
with 0, i.e. 0 means first callback instance, 1 means
the second callback instance.AuthLoginException
- if state or index is out of bound.public abstract void init(Subject subject, Map sharedState, Map options)
This is an abstract method, must be implemented by user's Login Module to initialize this LoginModule with the relevant information. If this LoginModule does not understand any of the data stored in sharedState or options parameters, they can be ignored.
subject
- - the Subject to be authenticated.sharedState
- - state shared with other configured LoginModules.options
- - options specified in the login Configuration for this
particular LoginModule. It contains all the global and organization
attribute configuration for this module. The key of the map is the
attribute name (e.g. iplanet-am-auth-ldap-server
) as
String, the value is the value of the corresponding attribute as Set.public abstract int process(Callback[] callbacks, int state)
This method takes an array of sbumitted Callback, process them and decide the order of next state to go. Return -1 if the login is successful, return 0 if the LoginModule should be ignored.
callbacks
- Callback[] for this Login statestate
- Order of state. State order starts with 1.LoginException
- if login fails.public abstract Principal getPrincipal()
public void destroyModuleState()
public int getAuthLevel()
public boolean setAuthLevel(int auth_level)
AuthLevel
for this session.
The authentication level being set cannot be downgraded
below that set by the module configuration.auth_level
- authentication level string to be settrue
if setting is successful,false
otherwisepublic int getCurrentState()
public javax.servlet.http.HttpServletRequest getHttpServletRequest()
HttpServletRequest
object that
initiated the call to this module.HttpServletRequest
for this request, returns null
if the HttpServletRequest
object could not be
obtained.public javax.servlet.http.HttpServletResponse getHttpServletResponse()
HttpServletResponse
object for the servlet
request that initiated the call to this module. The servlet response
object will be the response to the HttpServletRequest
received by the authentication module.HttpServletResponse
for this request, returns null
if the HttpServletResponse
object could not be obtained.public String getLocale() throws AuthLoginException
java.util.Locale
locale for this authentication
session.AuthLoginException
- if problem in accessing the
locale.public int getNumberOfStates()
public String getRequestOrg()
public String getSessionId()
public Map getOrgProfile(String orgDN) throws AuthLoginException
orgDN
- Requested organization DN.AuthLoginException
- if cannot get organization profile.public Map getOrgServiceTemplate(String orgDN, String serviceName) throws AuthLoginException
orgDN
- Organization DN.serviceName
- Requested service name.AuthLoginException
- if cannot get organization service
template.public Map getServiceConfig(String name) throws AuthLoginException
name
- Requested service name.AuthLoginException
- if error in accessing the service schema.public AMUser getUserProfile(String userDN) throws AuthLoginException
userDN
- distinguished name os user.AMUser
object for the user's distinguished name.AuthLoginException
- if it fails to get the user profile for
userDN
.public String getUserSessionProperty(String name) throws AuthLoginException
name
- The property name.AuthLoginException
- if the user session is invalid.public void setUserSessionProperty(String name, String value) throws AuthLoginException
name
- The property name.value
- The property value.AuthLoginException
- if the user session is invalid.public Set getNewUserIDs(Map attributes, int num) throws AuthLoginException
iplanet-am-auth-username-generator-enabled
is
set to false.attributes
- the keys in the Map
contains the
attribute names and their corresponding values in
the Map
is a Set
that
contains the values for the attributenum
- the maximum number of returned user IDs; 0 means there
is no limitAuthLoginException
- if the class instantiation failedpublic void setLoginFailureURL(String url) throws AuthLoginException
url
- URL to go when authentication failed.AuthLoginException
- if unable to set the URL.public void setLoginSuccessURL(String url) throws AuthLoginException
url
- URL
to go when authentication is successful.AuthLoginException
- if unable to set the URL.public boolean isRequired(int state, int index)
state
- Order of state.index
- Order of the Callback in the Callback[], the index.
starts with 0.true
if the callback corresponding to the number
in the specified state is required to have value,
false
otherwisepublic String getInfoText(int state, int index)
state
- The state to fetch the info textindex
- The callback to fetch the info textpublic String getAttribute(int state, int index)
state
- Order of stateindex
- Order of the Callback in the Callback[], the index
starts with 0.public void setFailureID(String userID)
userID
of user who failed authentication.
This userID
will be used to log failed authentication in
the OpenSSO error logs.userID
- user name of user who failed authentication.public void setUserAttributes(Map attributeValuePairs)
attributeValuePairs
- A map containing the attributes
and its values. The key is the attribute name and the value
is a Set of values.public void validateUserName(String userName, String regEx) throws UserNamePasswordValidationException
userName
- source string which should be validated.regEx
- the pattern for which to search.UserNamePasswordValidationException
- if user name is invalid.public void validatePassword(String userPassword) throws UserNamePasswordValidationException
userPassword
- source string which should be validated.UserNamePasswordValidationException
- if user password is invalid.public int getFailCount(AMIdentity amIdUser) throws AuthenticationException
AuthenticationException
- if the user name passed in is not valid
or null, or for any other error condition.public int getMaximumFailCount() throws AuthenticationException
AuthenticationException
public void incrementFailCount(String userName) throws AuthenticationException
AuthenticationException
- if the user name passed in is not valid
or null, or for any other error condition.public boolean isAccountLocked(String userName) throws AuthenticationException
AuthenticationException
- if the user name passed in is not valid
or null, or for any other error condition.public boolean isSessionQuotaReached(String userName)
userName
- the username of the user who's session quota will be checkedpublic Set<SSOToken> getUserSessions(String userName)
userName
- The username to be used to query the sessionsCopyright © 2010-2016, ForgeRock All Rights Reserved.