Package com.sun.identity.authentication.spi

Class AMLoginModule

java.lang.Object

com.sun.identity.authentication.spi.AMLoginModule

All Implemented Interfaces:

LoginModule

@Supported
public abstract class AMLoginModule
extends Object
implements LoginModule

An abstract class which implements JAAS LoginModule, it provides methods to access OpenAM services and the module xml configuration.

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 setAuthLevel() 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-<Login Module Name>--auth-level.

Here is a sample module schema for authentication level:

 <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.

For a complete sample, please refer to <install_root>/SUNWam/samples/authentication/providers

Method Summary

Modifier and Type	Method	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.
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	isAccountActive(String userName)	Returns true if the named account is active, false otherwise.
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	isReturningPrincipalAsDn()	Defines whether the principal being returned is a DN.
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)	Deprecated.
void	validateUserName(String userName, String invalidChars)	Validates the given user name by using validation plugin if exists else it checks invalid characters in the source string.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getSSOSession

@Supported
public SSOToken getSSOSession()
                       throws AuthLoginException

Returns an administration SSOToken for use the OpenAM APIs. NB:This is not the SSOToken that represents the user, if you wish to set/get user session properties use the setUserSessionProperty and getUserSessionProperty method respectively.

Returns:

An administrative SSOToken.

Throws:

AuthLoginException - if the authentication SSO session is null.

getCallback

@Supported
public Callback[] getCallback(int index)
                       throws AuthLoginException

Returns a Callback array for a specific state.

This method can be used to retrieve Callback[] for any state. All previous submitted Callback[] information are kept until the login process is completed.

Parameters:

index - order of state

Returns:

Callback array for this state, return 0-length Callback array if there is no Callback defined for this state

Throws:

AuthLoginException - if unable to read the callbacks

getCallback

@Supported
public Callback[] getCallback(int index,
                              boolean fetchOrig)
                       throws AuthLoginException

Return a Callback array for a specific state.

This method can be used to retrieve Callback[] for any state. All previous submitted Callback[] information are kept until the login process is completed.

Parameters:

index - order of state

fetchOrig - boolean indicating even if the callbacks for this state have been previously retrieved, get the original callbacks from AMModuleProperties, if set to "true".

Returns:

Callback array for this state, return 0-length Callback array if there is no Callback defined for this state

Throws:

AuthLoginException - if unable to read the callbacks

replaceCallback

@Supported
public void replaceCallback(int state,
                            int index,
                            Callback callback)
                     throws AuthLoginException

Replace Callback object for a specific state.

Parameters:

state - Order of login state

index - 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 replaced

Throws:

AuthLoginException - if state or index is out of bound, or callback instance is null.

substituteInfoText

@Supported
public void substituteInfoText(int state,
                               int callback,
                               String infoText)
                        throws AuthLoginException

Allows you to set the info text for a specific callback. Info Text is shown under the element in the Login page. It is used in the membership module to implement in-line feedback.

Parameters:

state - state in which the Callback[] to be reset

callback - the callback to associate the info text

infoText - the infotext for the callback

Throws:

AuthLoginException - if state/callback is out of bounds

clearInfoText

@Supported
public void clearInfoText(int state)
                   throws AuthLoginException

Clears the info text for a given callback state

Parameters:

state - The state to clear all infotexts

Throws:

AuthLoginException - Invalid state

substituteHeader

@Supported
public void substituteHeader(int state,
                             String header)
                      throws AuthLoginException

Use this method to replace the header text from the XML file with new text. This method can be used multiple times on the same state replacing text with new text each time. Useful for modules that control their own error handling.

Parameters:

state - state state in which the Callback[] to be reset

header - The text of the header to be replaced

Throws:

AuthLoginException - if state is out of bounds

resetCallback

@Supported
public void resetCallback(int state,
                          int index)
                   throws AuthLoginException

Reset a Callback instance to the original Callback for the specified state and the specified index. This will override change to the Callback instance by the replaceCallback() method.

Parameters:

state - state in which the Callback[] to be reset

index - 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.

Throws:

AuthLoginException - if state or index is out of bound.

init

@Supported
public abstract void init(Subject subject,
                          Map sharedState,
                          Map options)

Initialize this LoginModule.

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.

Parameters:

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.

process

@Supported
public abstract int process(Callback[] callbacks,
                            int state)
                     throws LoginException

Abstract method must be implemented by each login module to control the flow of the login process.

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.

Parameters:

callbacks - Callback[] for this Login state

state - Order of state. State order starts with 1.

Returns:

order of next state. return -1 if authentication is successful, return 0 if the LoginModule should be ignored.

Throws:

LoginException - if login fails.

getPrincipal

@Supported
public abstract Principal getPrincipal()

Abstract method must be implemeted by each login module to get the user Principal

Returns:

Principal

destroyModuleState

@Supported
public void destroyModuleState()

This method should be overridden by each login module to destroy dispensable state fields.

getAuthLevel

@Supported
public int getAuthLevel()

Returns authentication level that has been set for the module

Returns:

authentication level of this authentication session

setAuthLevel

@Supported
public boolean setAuthLevel(int auth_level)

Sets the AuthLevel for this session. The authentication level being set cannot be downgraded below that set by the module configuration.

Parameters:

auth_level - authentication level string to be set

Returns:

true if setting is successful,false otherwise

getCurrentState

@Supported
public int getCurrentState()

Returns the current state in the authentication process.

Returns:

the current state in the authentication process.

getHttpServletRequest

@Supported
public javax.servlet.http.HttpServletRequest getHttpServletRequest()

Returns the HttpServletRequest object that initiated the call to this module.

Returns:

HttpServletRequest for this request, returns null if the HttpServletRequest object could not be obtained.

getHttpServletResponse

@Supported
public javax.servlet.http.HttpServletResponse getHttpServletResponse()

Returns the 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.

Returns:

HttpServletResponse for this request, returns null if the HttpServletResponse object could not be obtained.

getLocale

@Supported
public String getLocale()
                 throws AuthLoginException

Returns the locale for this authentication session.

Returns:

java.util.Locale locale for this authentication session.

Throws:

AuthLoginException - if problem in accessing the locale.

getNumberOfStates

@Supported
public int getNumberOfStates()

Returns the number of authentication states for this login module.

Returns:

the number of authentication states for this login module.

getRequestOrg

@Supported
public String getRequestOrg()

Returns the organization DN for this authentication session.

Returns:

organization DN.

getSessionId

@Supported
public String getSessionId()

Returns a unique key for this authentication session. This key will be unique throughout an entire Web browser session.

Returns:

null is unable to get the key,

getOrgProfile

@Supported
public Map getOrgProfile(String orgDN)
                  throws AuthLoginException

Returns the organization attributes for specified organization.

Parameters:

orgDN - Requested organization DN.

Returns:

Map that contains all attribute key/value pairs defined in the organization.

Throws:

AuthLoginException - if cannot get organization profile.

getOrgServiceTemplate

@Supported
public Map getOrgServiceTemplate(String orgDN,
                                 String serviceName)
                          throws AuthLoginException

Returns service template attributes defined for the specified organization.

Parameters:

orgDN - Organization DN.

serviceName - Requested service name.

Returns:

Map that contains all attribute key/value pairs defined in the organization service template.

Throws:

AuthLoginException - if cannot get organization service template.

getServiceConfig

@Supported
public Map getServiceConfig(String name)
                     throws AuthLoginException

Returns service configuration attributes.

Parameters:

name - Requested service name.

Returns:

Map that contains all attribute key/value pairs defined in the service configuration.

Throws:

AuthLoginException - if error in accessing the service schema.

getUserSessionProperty

@Supported
public String getUserSessionProperty(String name)
                              throws AuthLoginException

Returns the property from the user session. If the session is being force upgraded then set on the old session otherwise set on the current session.

Parameters:

name - The property name.

Returns:

The property value.

Throws:

AuthLoginException - if the user session is invalid.

setUserSessionProperty

@Supported
public void setUserSessionProperty(String name,
                                   String value)
                            throws AuthLoginException

Sets a property in the user session. If the session is being force upgraded (or is part of a transaction) then set on the old session otherwise set on the current session.

Parameters:

name - The property name.

value - The property value.

Throws:

AuthLoginException - if the user session is invalid.

getNewUserIDs

@Supported
public Set getNewUserIDs(Map attributes,
                         int num)
                  throws AuthLoginException

Returns a set of user IDs generated from the class defined in the Core Authentication Service. Returns null if the attribute iplanet-am-auth-username-generator-enabled is set to false.

Parameters:

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 attribute

num - the maximum number of returned user IDs; 0 means there is no limit

Returns:

a set of auto-generated user IDs

Throws:

AuthLoginException - if the class instantiation failed

setLoginFailureURL

@Supported
public void setLoginFailureURL(String url)
                        throws AuthLoginException

Sets the the login failure URL for the user. This method does not change the URL in the user's profile. When the user authenticates failed, this URL will be used by the authentication for the redirect.

Parameters:

url - URL to go when authentication failed.

Throws:

AuthLoginException - if unable to set the URL.

setLoginSuccessURL

@Supported
public void setLoginSuccessURL(String url)
                        throws AuthLoginException

Sets the the login successful URL for the user. This method does not change the URL in the user's profile. When the user authenticates successfully, this URL will be used by the authentication for the redirect.

Parameters:

url - URL to go when authentication is successful.

Throws:

AuthLoginException - if unable to set the URL.

isRequired

@Supported
public boolean isRequired(int state,
                          int index)

Checks if a Callback is required to have input.

Parameters:

state - Order of state.

index - Order of the Callback in the Callback[], the index. starts with 0.

Returns:

true if the callback corresponding to the number in the specified state is required to have value, false otherwise

getInfoText

@Supported
public String getInfoText(int state,
                          int index)

Returns the info text associated with a specific callback

Parameters:

state - The state to fetch the info text

index - The callback to fetch the info text

Returns:

The info text

getAttribute

@Supported
public String getAttribute(int state,
                           int index)

Returns the attribute name for the specified callback in the specified login state.

Parameters:

state - Order of state

index - Order of the Callback in the Callback[], the index starts with 0.

Returns:

Name of the attribute, empty string will be returned if the attribute is not defined.

isReturningPrincipalAsDn

@Supported
public boolean isReturningPrincipalAsDn()

Defines whether the principal being returned is a DN. The check is based on the property org.forgerock.am.modules.returningprincipalasdn by default, but may be overridden.

The property should contain a space separated list of module type class names and/or module DNs of the format name=my-module-name,orgdn where my-module-name is the name of a module instance in AM and orgdn is the DN of the organisation containing the module instance.

This property should only be used when it is impractical to update the Java code of the module itself to override this method with the correct implementation and may have performance implications.

Returns:

true if the module is returning the principal as a DN, otherwise false.

setFailureID

@Supported
public void setFailureID(String userID)

Sets the userID of user who failed authentication. This userID will be used to log failed authentication in the OpenSSO error logs.

Parameters:

userID - user name of user who failed authentication.

setUserAttributes

@Supported
public 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.

Parameters:

attributeValuePairs - A map containing the attributes and its values. The key is the attribute name and the value is a Set of values.

validateUserName

@Supported
public void validateUserName(String userName,
                             String invalidChars)
                      throws UserNamePasswordValidationException

Validates the given user name by using validation plugin if exists else it checks invalid characters in the source string.

Parameters:

userName - source string which should be validated.

invalidChars - the pattern for which to search.

Throws:

UserNamePasswordValidationException - if user name is invalid.

validatePassword

@Supported
@Deprecated
public void validatePassword(String userPassword)
                      throws UserNamePasswordValidationException

Deprecated.

Validate password for the distinguished user, this will use validation plugin if exists to validate password

Parameters:

userPassword - source string which should be validated.

Throws:

UserNamePasswordValidationException - if user password is invalid.

getFailCount

@Supported
public int getFailCount(AMIdentity amIdUser)
                 throws AuthenticationException

Get the number of failed login attempts for a user when account locking is enabled.

Returns:

number of failed attempts, -1 means account locking is not enabled.

Throws:

AuthenticationException - if the user name passed in is not valid or null, or for any other error condition.

getMaximumFailCount

@Supported
public int getMaximumFailCount()
                        throws AuthenticationException

Get the maximum number failed login attempts permitted for a user before when their account is locked out.

Returns:

the maximum number of failed attempts

Throws:

AuthenticationException

incrementFailCount

@Supported
public void incrementFailCount(String userName)
                        throws AuthenticationException

Increments the fail count for the given user.

Throws:

AuthenticationException - if the user name passed in is not valid or null, or for any other error condition.

isAccountLocked

@Supported
public boolean isAccountLocked(String userName)
                        throws AuthenticationException

Returns true if the named account is locked out, false otherwise.

Throws:

AuthenticationException - if the user name passed in is not valid or null, or for any other error condition.

isAccountActive

@Supported
public boolean isAccountActive(String userName)
                        throws AuthenticationException

Returns true if the named account is active, false otherwise. Does not take into account memory locking, isAccountLocked(java.lang.String)

Throws:

AuthenticationException - if the user name passed in is not valid or null, or for any other error condition.

isSessionQuotaReached

@Supported
public 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

Parameters:

userName - the username of the user who's session quota will be checked

Returns:

true if the user session quota is reached, false otherwise

getUserSessions

@Supported
public Set<SSOToken> getUserSessions(String userName)

Returns the set of SSOTokens for a specified user

Parameters:

userName - The username to be used to query the sessions

Returns:

The set of SSOTokens for the user's current sessions, returns null on error