com.sun.identity.authentication.spi
Class AMLoginModule

java.lang.Object
  |
  +--com.sun.identity.authentication.spi.AMLoginModule
All Implemented Interfaces:
javax.security.auth.spi.LoginModule

public abstract class AMLoginModule
extends java.lang.Object
implements javax.security.auth.spi.LoginModule

An abstract class which implements JAAS LoginModule, it provides methods to access Java System Access Manager 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.

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


Constructor Summary
AMLoginModule()
           
 
Method Summary
 void destroyModuleState()
          This method should be overridden by each login module to destroy dispensable state fields.
 java.lang.String getAttribute(int state, int index)
          Get the attribute name for the specified callback in the specified login state
 int getAuthLevel()
          Get authentication level.
 javax.security.auth.callback.Callback[] getCallback(int index)
          Return a Callback array for a specific state.
 int getCurrentState()
          Returns the current state in the authentication process.
 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.
 java.lang.String getLocale()
          Gets the locale for this authentication session.
 java.util.Set getNewUserIDs(java.util.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.
 java.util.Map getOrgProfile(java.lang.String orgDN)
          Returns the organization attributes for specified organization.
 java.util.Map getOrgServiceTemplate(java.lang.String orgDN, java.lang.String serviceName)
          Gets service template attributes defined for the specified organization.
 boolean getPersistentCookieOn()
          Checks if persistent cookie is on or off.
abstract  java.security.Principal getPrincipal()
          Abstract method must be implemeted by each login module to get the user Principal
 java.lang.String getRequestOrg()
          Returns the organization DN for this authentication session.
 java.util.Map getServiceConfig(java.lang.String name)
          Returns service configuration attributes.
 java.lang.String getSessionId()
          Returns a unique key for this authentication session.
 SSOToken getSSOSession()
          Get the authentication SSO session
 AMUser getUserProfile(java.lang.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 Access Manager Developer's Guide.
 java.lang.String getUserSessionProperty(java.lang.String name)
          Returns the property from the user session.
abstract  void init(javax.security.auth.Subject subject, java.util.Map sharedState, java.util.Map options)
          Initialize this LoginModule.
 boolean isRequired(int state, int index)
          Check if a Callback is required to have input
abstract  int process(javax.security.auth.callback.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, javax.security.auth.callback.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)
          Set the AuthLevel for this session.
 void setFailureID(java.lang.String userID)
          Sets the userID of user who failed authentication.
 void setLoginFailureURL(java.lang.String url)
          Sets the the login failure URL for the user.
 void setLoginSuccessURL(java.lang.String url)
          Sets the the login successful URL for the user.
 boolean setPersistentCookieOn()
          Attempts to set the Persistent Cookie for this session.
 void setUserAttributes(java.util.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(java.lang.String name, java.lang.String value)
          Sets a property in the user session.
 void validatePassword(java.lang.String userPassword)
          This method will use validation plugin if exists to validate password
 void validateUserName(java.lang.String userName, java.lang.String regEx)
          This method will use validation plugin if exists else it checks invalid characters in the source string
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface javax.security.auth.spi.LoginModule
abort, commit, initialize, login, logout
 

Constructor Detail

AMLoginModule

public AMLoginModule()
Method Detail

getSSOSession

public SSOToken getSSOSession()
                       throws AuthLoginException
Get the authentication SSO session
Returns:
single sign on token for the authentication service
Throws:
AuthLoginException - if the authentication SSO session is null.

getCallback

public javax.security.auth.callback.Callback[] getCallback(int index)
                                                    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
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

public void replaceCallback(int state,
                            int index,
                            javax.security.auth.callback.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.

resetCallback

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

public abstract void init(javax.security.auth.Subject subject,
                          java.util.Map sharedState,
                          java.util.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

public abstract int process(javax.security.auth.callback.Callback[] callbacks,
                            int state)
                     throws javax.security.auth.login.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.

getPrincipal

public abstract java.security.Principal getPrincipal()
Abstract method must be implemeted by each login module to get the user Principal
Returns:
Principal

destroyModuleState

public void destroyModuleState()
This method should be overridden by each login module to destroy dispensable state fields.

getAuthLevel

public int getAuthLevel()
Get authentication level.
Returns:
authentication level of this authentication session

setAuthLevel

public boolean setAuthLevel(int auth_level)
Set 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

public int getCurrentState()
Returns the current state in the authentication process.
Returns:
the current state in the authentication process.

getHttpServletRequest

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

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

public java.lang.String getLocale()
                           throws AuthLoginException
Gets the locale for this authentication session.
Returns:
java.util.Locale locale for this authentication session.
Throws:
AuthLoginException - if problem in accessing the locale.

getNumberOfStates

public int getNumberOfStates()
Returns the number of authentication states for this login module.
Returns:
the number of authentication states for this login module.

getRequestOrg

public java.lang.String getRequestOrg()
Returns the organization DN for this authentication session.
Returns:
organization DN.

getSessionId

public java.lang.String getSessionId()
Returns a unique key for this authentication session. This key will be unique throughout an entire Web browser session.
Returns:
String return null is unable to get the key

getOrgProfile

public java.util.Map getOrgProfile(java.lang.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

public java.util.Map getOrgServiceTemplate(java.lang.String orgDN,
                                           java.lang.String serviceName)
                                    throws AuthLoginException
Gets 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

getPersistentCookieOn

public boolean getPersistentCookieOn()
Checks if persistent cookie is on or off.
Returns:
true if persistent cookie is set, false otherwise

setPersistentCookieOn

public boolean setPersistentCookieOn()
Attempts to set the Persistent Cookie for this session. Can be called from any state in the authentication module. It will return whether "Core Authentication" will add the persistent cookie (name is specified in the /etc/opt/SUNWam/config/AMConfig.properties: com.iplanet.am.pcookie.name property)
Returns:
true when setting is successful, false if the persistent cookie mode attribute is not set for the organization

getServiceConfig

public java.util.Map getServiceConfig(java.lang.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.

getUserProfile

public AMUser getUserProfile(java.lang.String userDN)
                      throws AuthLoginException
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 Access Manager Developer's Guide.

Returns the user profile for the user specified. This method may only be called in the validate() method.
Parameters:
userDN - distinguished name os user.
Returns:
AMUser object for the user's distinguished name.
Throws:
AuthLoginException - if it fails to get the user profile for userDN.

getUserSessionProperty

public java.lang.String getUserSessionProperty(java.lang.String name)
                                        throws AuthLoginException
Returns the property from the user session.
Parameters:
name - The property name.
Returns:
The property value.
Throws:
AuthLoginException - if the user session is invalid.

setUserSessionProperty

public void setUserSessionProperty(java.lang.String name,
                                   java.lang.String value)
                            throws AuthLoginException
Sets a property in the user session.
Parameters:
name - The property name.
value - The property value.
Throws:
AuthLoginException - if the user session is invalid.

getNewUserIDs

public java.util.Set getNewUserIDs(java.util.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

public void setLoginFailureURL(java.lang.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

public void setLoginSuccessURL(java.lang.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

public boolean isRequired(int state,
                          int index)
Check 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

getAttribute

public java.lang.String getAttribute(int state,
                                     int index)
Get 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:
String the name of the attribute, empty string will be returned if the attribute is not defined

setFailureID

public void setFailureID(java.lang.String userID)
Sets the userID of user who failed authentication. This userID will be used to log failed authentication in the Access Manager error logs.
Parameters:
userID - user name of user who failed authentication.

setUserAttributes

public void setUserAttributes(java.util.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

public void validateUserName(java.lang.String userName,
                             java.lang.String regEx)
                      throws UserNamePasswordValidationException
This method will use validation plugin if exists else it checks invalid characters in the source string
Parameters:
userName - source string which should be validated
regEx - the pattern for which to search.
Throws:
UserNamePasswordValidationException - if user name is invalid.

validatePassword

public void validatePassword(java.lang.String userPassword)
                      throws UserNamePasswordValidationException
This method will use validation plugin if exists to validate password
Parameters:
userPassword - source string which should be validated.
Throws:
UserNamePasswordValidationException - if user password is invalid.


Copyright 2005 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.