|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--com.sun.identity.authentication.spi.AMLoginModule
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 |
public AMLoginModule()
Method Detail |
public SSOToken getSSOSession() throws AuthLoginException
AuthLoginException
- if the authentication SSO session is null.public javax.security.auth.callback.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 void replaceCallback(int state, int index, javax.security.auth.callback.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 resetCallback(int state, int index) throws AuthLoginException
replaceCallback()
method.state
- state in which the Callback[] to be resetindex
- 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(javax.security.auth.Subject subject, java.util.Map sharedState, java.util.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(javax.security.auth.callback.Callback[] callbacks, int state) throws javax.security.auth.login.LoginException
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.public abstract java.security.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 setpublic 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 java.lang.String getLocale() throws AuthLoginException
java.util.Locale
locale for this authentication
session.AuthLoginException
- if problem in accessing the locale.public int getNumberOfStates()
public java.lang.String getRequestOrg()
public java.lang.String getSessionId()
public java.util.Map getOrgProfile(java.lang.String orgDN) throws AuthLoginException
orgDN
- Requested organization DNAuthLoginException
- if cannot get organization profilepublic java.util.Map getOrgServiceTemplate(java.lang.String orgDN, java.lang.String serviceName) throws AuthLoginException
orgDN
- Organization DNserviceName
- Requested service nameAuthLoginException
- if cannot get organization service
templatepublic boolean getPersistentCookieOn()
public boolean setPersistentCookieOn()
/etc/opt/SUNWam/config/AMConfig.properties
:
com.iplanet.am.pcookie.name
property)public java.util.Map getServiceConfig(java.lang.String name) throws AuthLoginException
name
- Requested service nameAuthLoginException
- if error in accessing the service schema.public AMUser getUserProfile(java.lang.String userDN) throws AuthLoginException
userDN
- distinguished name os user.AuthLoginException
- if it fails to get the user profile for
userDN
.public java.lang.String getUserSessionProperty(java.lang.String name) throws AuthLoginException
name
- The property name.AuthLoginException
- if the user session is invalid.public void setUserSessionProperty(java.lang.String name, java.lang.String value) throws AuthLoginException
name
- The property name.value
- The property value.AuthLoginException
- if the user session is invalid.public java.util.Set getNewUserIDs(java.util.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(java.lang.String url) throws AuthLoginException
url
- URL to go when authentication failedAuthLoginException
- if unable to set the URLpublic void setLoginSuccessURL(java.lang.String url) throws AuthLoginException
url
- URL to go when authentication is successfulAuthLoginException
- if unable to set the URLpublic boolean isRequired(int state, int index)
state
- Order of stateindex
- Order of the Callback in the Callback[], the index
starts with 0.public java.lang.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(java.lang.String userID)
userID
of user who failed authentication.
This userID
will be used to log failed authentication in
the Access Manager error logs.userID
- user name of user who failed authentication.public void setUserAttributes(java.util.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(java.lang.String userName, java.lang.String regEx) throws UserNamePasswordValidationException
userName
- source string which should be validatedregEx
- the pattern for which to search.UserNamePasswordValidationException
- if user name is invalid.public void validatePassword(java.lang.String userPassword) throws UserNamePasswordValidationException
userPassword
- source string which should be validated.UserNamePasswordValidationException
- if user password is invalid.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |