An OAAM sample application is available which demonstrates the use of Integration Processors and Task Processors. To see an example of Java API integration, see Chapter 2, "Natively Integrating Oracle Adaptive Access Manager."
The following sections provide reference information about the OAAM Custom Processor Framework:
OAAM makes available user flows and interfaces for your business security requirements out of the box, but if your requirement is outside of what is provided by the standard Web application, you can use the OAAM custom processor framework for custom development.
Figure 21-1, "OAAM Standard Web Application" shows the standard web application.
Figure 21-1 OAAM Standard Web Application
Figure 21-2, "OAAM Processor Framework" shows the different components of the processor framework.
An OAAM sample framework that illustrates task processor integration is available for your reference. The most recent OAAM sample can be downloaded from My Oracle Support.
The OAAM Sample code is for demonstration purposes to familiarize you with the task processor framework. It is not intended to be used as production code.
Note:
This sample does not replace the OAAM sample application for Java API integration. Use either the OAAM sample application that illustrates Java API integration or the one that illustrates task processor integration. The two OAAM sample applications may not be deployed together.To deploy the sample application, proceed as follows:
Create the oaam_framework_sample
folder.
Extract oaam_framework_sample.war
into oaam_framework_sample
.
Start the WebLogic Server.
Navigate to the Oracle WebLogic Administration Console.
http://oaam_host
:port
/console
Deploy the OAAM Shared Library $MW_HOME\Oracle_IDM1\oaam\oaam_libs\war\oaam_native_lib.war
as a shared library.
Click Deployments under IAMDomain (in the left pane).
In the Summary of Deployments page, click the Install button.
In the Path field, specify $MW_HOME\Oracle_IDM1\oaam\oaam_libs\war\oaam_native_lib.war
.
Select oaam_native_lib.war
and click Next.
Select the Install this deployment as a library option and click Next.
In the Select Deployments targets page, select the managed server from the list of servers and click Next. Notice the name of the shared library is oracle.oaam.libs
.
If the managed server is OAAM Server then there is no need to create a OAAM Data Source. Otherwise create a Data source with JNDI name as jdbc/OAAM_SERVER_DB_DS
and point it to the OAAM schema.
Click Finish.
Click Activate Changes.
Deploy the OAAM sample application as an application onto the same managed server where the OAAM Shared Library is deployed.
Click Deployments under IAMDomain (in the left pane).
In the Summary of Deployments page, click the Install button.
In the Path field, specify the location of the OAAM sample application and click Next.
Select the Install this deployment as an application option. Click Next.
In the Select Deployments targets page, select the managed server from the list of servers and click Next.
Click Finish.
Click Activate Changes under the Change Center.
In the deployment descriptor file, set the reference to the OAAM shared library oracle.oaam.libs
.
To use the Oracle Adaptive Access Manager Shared Library in Web applications, you must refer to the shared library by adding the following entry to your Oracle WebLogic deployment descriptor file, weblogic.xml
:
<library-ref> <library-name>oracle.oaam.libs</library-name> </library-ref>
To use the Oracle Adaptive Access Manager Shared Library in Enterprise applications, you must refer to the shared library by adding the following entry to your Oracle WebLogic deployment descriptor file, weblogic-application.xml
:
<library-ref> <library-name>oracle.oaam.libs</library-name> </library-ref>
Start the managed server.
Navigate to the Oracle WebLogic Administration Console. Click Lock and Edit and select the Deployments node. On the Summary of Deployments page, find and select the OAAM sample application. Click Start > Servicing all requests. Click Yes to confirm.
Log in to OAAM Admin application and import the snapshot.
Import the Transaction policies from the Sample_Txn_Models.zip
file.
Navigate to the URL http://managed_server:port/oaam_framework_sample
. You will see the login page of the OAAM sample application.
Enter the user name and then password in the next page. You will go through registration and after that you will see links to Sample Transaction.
Note:
The password must betest
for the initial log in. You must change the password immediately.UIOContext
is a context object that maintains thread local variables for the HTTP request and response objects. This allows access to the session (more specifically the UIOSesisonData
object) always in an application. The context should be populated at the beginning of each request (HttpServletRequest
and HttpServletResponse
)
UIOContext.setCurrentInstance(new UIOContext(request, response));
The UIOSessionData object is maintained in the HTTP session and contains all OAAM session and user data.
Task processors allow integrators to develop custom java code that perform key OAAM operations.
Task processors:
Performs a set of OAAM API calls for a specific task
Updates the OAAM session data
Separates the user interface from OAAM "work"
Task processors typically have a 1 to 1 relationship with end user pages:
Login.jsp
Presents username field to user
Submits username to loginAction.do
LoginAction
Accepts data from presentation
Maps data to the OAAM task processor
LoginTaskProcessor
Calls the OAAM APIs and updates the UIOSessionData
Returns the "target"
Each task processor class implements the TaskProcessorIntf
and extends AbstractTaskProcessor
.
TaskProcessorIntf
Static variables for task, target, task parameters, and task actions
Execute method
AbstractTaskProcessor
Breaks the interface execute method into three parts:
preProcess
, process
, postProcess
preProcess
and postProcess
methods of default classes are empty
Allows customizers to extend existing classes to execute code before or after API calls or based on outcomes
Introduces validateSession
method to easily validate user session is valid for each task
Utility methods for determining task action (show
/ submit
)
Task processors are registered in the system using properties. The task processor property definition is:
bharosa.uioappId.task.processor.taskName = java_class
For example:
bharosa.uio.default.task.processor.login = com.bharosa.uio.processor.task.LoginTaskProcessor
Task processors are accessed by calling the Utility
method:
UIOUtil.getTaskProcessor(UIOSessionData sessionData, String taskId)
TaskParams params = new TaskParams(); params.addParam(LoginTaskProcessor.PARAM_LOGIN_ID, loginId); params.setActionSubmit();
target = taskProc.execute(params).getResult();
Each task processor must implement the TaskProcessorIntf
interface, and it is recommended that it extend an existing task processor or extend the AbstractTaskprocessor
class. This will allow for customizations to only include preProcess
or postProcess
methods if only small additional pieces of java code need to be added for integration purposes.
For example if an external API is required to be called every time LogoutTaskProcessor
is called, a CustomLogoutTaskProcessor
could be implemented that extends LogoutTaskProcessor
and only implements the postProcess
method to make the external API call. The property for logout task processor could then be updated to point to the new CustomTaskProcessor
class.
bharosa.uio.default.task.processor.logout = com.bharosa.uio.processor.task.CustomLogoutTaskProcessor
The TaskProcessorIntf
is presented as follows:
public interface TaskProcessorIntf { public static final String TASK_LOGIN = "login"; public static final String TASK_JUMP = "jump"; public static final String TASK_PASSWORD = "password"; public static final String TASK_CHALLENGE = "challenge"; public static final String TASK_CHALLENGE_CHOICE = "challengeChoice"; public static final String TASK_CHANGE_PASSWORD = "changePassword"; public static final String TASK_CHANGE_USERNAME = "changeUsername"; public static final String TASK_FINGERPRINT = "fingerprint"; public static final String TASK_LOGOUT = "logout"; public static final String TASK_FORGOT_PASSWORD = "forgotPassword"; public static final String TASK_CHECKPOINT= "checkpoint"; public static final String TASK_UPDATE_STATUS = "updateStatus"; public static final String TASK_REGISTER_SUMMARY = "registerSummary"; public static final String TASK_REGISTER_IMAGE_PHRASE = "registerImagePhrase"; public static final String TASK_REGISTER_QUESTIONS = "registerQuestions"; public static final String TASK_REGISTER_USER_INFO = "registerUserInfo"; public static final String TASK_REGISTER_COMPLETE = "registerComplete"; public static final String TASK_REGISTER_SKIP = "registerSkip"; public static final String TASK_USERPREF_IMAGE_PHRASE = "userPrefsImagePhrase"; public static final String TASK_USERPREF_QUESTIONS = "userPrefsQuestions"; public static final String TASK_USERPREF_USER_INFO = "userPrefsUserInfo"; public static final String TASK_USERPREF_COMPLETE = "userPrefsComplete"; public static final String TASK_TRANSACTION = "transaction"; public static final String TASK_UPDATE_TRANSACTION_STATUS = "updateTransactionStatus";
public static final String TARGET_ERROR = "error"; public static final String TARGET_SESSION_EXPIRED = "session_expired"; public static final String TARGET_FAIL = "fail"; public static final String TARGET_ACCESS_DENIED = "accessDenied"; public static final String TARGET_INVALID_USER = "invalid_user"; public static final String TARGET_SUCCESS = "success"; public static final String TARGET_UPDATE_STATUS = "updateStatus"; public static final String TARGET_LOGIN = "login"; public static final String TARGET_JUMP = "jump"; public static final String TARGET_PASSWORD = "password"; public static final String TARGET_RESET_PASSWORD = "resetPassword"; public static final String TARGET_CHANGE_PASSWORD = "changePassword"; public static final String TARGET_CHALLENGE= "challenge"; public static final String TARGET_CHALLENGE_CHOICE= "challengeChoice"; public static final String TARGET_FORGOT_PASSWORD = "forgotPassword"; public static final String TARGET_USER_DISABLED = "user_disabled"; public static final String TARGET_NEXT = "next"; public static final String TARGET_ALLOW = Preferences.ACTION_ALLOW; public static final String TARGET_BLOCK = Preferences.ACTION_BLOCK; public static final String TARGET_REGISTER = Preferences.ACTION_REGISTER; public static final String TARGET_REGISTER_SUMMARY = "registerInfo"; public static final String TARGET_REGISTER_IMAGE_PHRASE = "registerAuthenticator"; public static final String TARGET_REGISTER_QUESTIONS = "registerQuestions"; public static final String TARGET_REGISTER_QUESTIONS_HTML = "registerQuestionsHTML"; public static final String TARGET_REGISTER_USER_INFO = "registerUserInfo"; public static final String TARGET_REGISTER_COMPLETE = "registerComplete"; public static final String TARGET_REGISTER_REQUIRED = Preferences.ACTION_REGISTRATION_REQUIRED;
public static final String PARAM_ACTION = "action"; public static final String PARAM_PURPOSE = "purpose"; public static final String ACTION_SUBMIT = "submitAnswer"; public static final String ACTION_WAIT = "wait"; public static final String ACTION_UPGRADE = "upgrade"; public static final String ACTION_DOWNGRADE = "revert"; public static final String ACTION_SHOW = "show"; public static final String PURPOSE_CHANGE_PASSWORD = "ChangePassword"; public static final String PURPOSE_FORGOT_PASSWORD = "ForgotPassword"; public static final String PURPOSE_RESET_PASSWORD = "ResetPassword"; public static final String PURPOSE_EXPIRED_PASSWORD = "ExpiredPassword"; public static final String PURPOSE_USER_PREFERENCES = "UserPreferences"; public static final String PURPOSE_TRANSACTION = "Transaction"; public static final String PURPOSE_JAVASCRIPT = "Javascript"; public TaskResult execute(TaskParams params); }
The AbstractTaskProcessor
is presented as follows:
public abstract class AbstractTaskProcessor implements Serializable, TaskProcessorIntf { public AbstractTaskProcessor() { } public TaskResult execute(TaskParams params) { UIOSessionData sessionData = UIOContext.getCurrentInstance().getSessionData(); if (params == null) params = new TaskParams(); String validateSession = validateSession(); if (validateSession != null) { List errorCodes = null; if (sessionData != null) errorCodes = sessionData.getErrorCodes(); return new TaskResult(validateSession, errorCodes); } String target = preProcess(params); if (!StringUtil.equalsIgnoreCase(target, TARGET_ERROR)){ target = process(params, target); } target = postProcess(params, target); TaskResult result = new TaskResult(target, sessionData.getErrorCodes()); result.setActionList(sessionData.getActionList()); result.setChallengeType(UIOUtil.getCurrentChallengeType(sessionData)); result.setChallengeQuestion(sessionData.getSecretQuestion()); result.setRequestId(sessionData.getRequestId()); result.setLoginId(sessionData.getLoginId()); result.setCurrentAuthDevice(sessionData.getPreferences().getCurrentDevice()); result.setCanSkipRegistration(sessionData.getPreferences().getCanSkipRegistration( )); // Update the sessionData object in session for replication. UIOSessionData.updateSession(); return result; } protected String preProcess(TaskParams params) { return null; } abstract protected String process(TaskParams params, String target); protected String postProcess(TaskParams params, String target) { return target; } protected String validateSession(){ String target = null; UIOSessionData sessionData = UIOContext.getCurrentInstance().getSessionData(); if (sessionData == null){ // Attempt to populate from context. sessionData = UIOContext.getCurrentInstance().getSessionData(); if (sessionData == null){ logger.info("SessionData is not found in session, so the session is expired or UIOContext not pupulated."); return TARGET_SESSION_EXPIRED; } } String customerId = sessionData.getCustomerId(); VCryptAuthUser clientUser = sessionData.getClientAuthUser(); if (clientUser == null && StringUtil.isEmpty(customerId)) { logger.info("Client User is not found in session, so the session is expired."); target = TARGET_SESSION_EXPIRED; } else if (clientUser == null && !StringUtil.isEmpty(customerId)) { logger.info("Client User is not found in session."); target = TARGET_ACCESS_DENIED; } return target; } public boolean isShow(TaskParams params){ return StringUtil.equalsIgnoreCase(params.getAction(), TaskProcessorIntf.ACTION_SHOW); } public boolean isSubmit(TaskParams params){ return StringUtil.equalsIgnoreCase(params.getAction(), TaskProcessorIntf.ACTION_SUBMIT); } public boolean isPurpose(TaskParams params, String purpose){ return params.isPurpose(purpose); } }
Parameter | Description | Existing expected/used values for Purpose: | Purpose Currently used by: |
---|---|---|---|
Purpose | Used to differentiate reason class is being used in cases where the same class is used to process multiple similar tasks, which may change behavior some (previously used struts parameter in session). | TaskProcessorIntf.PURPOSE_CHANGE_PASSWORD
TaskProcessorIntf.PURPOSE_FORGOT_PASSWORD TaskProcessorIntf.PURPOSE_RESET_PASSWORD TaskProcessorIntf.PURPOSE_EXPIRED_PASSWORD TaskProcessorIntf.PURPOSE_USER_PREFERENCES TaskProcessorIntf.PURPOSE_TRANSACTION TaskProcessorIntf.PURPOSE_JAVASCRIPT |
ChallengeUserTaskProcessor
ChangePasswordTaskProcessor FingerPrintTaskProcessor JumpTaskProcessor UpdateAuthStatusTaskProcessor |
setPurpose(String) getPurpose() isPurpose(String) - Tests if current purpose is the provided purpose. - isPurpose(TaskParams, String) is also available in AbstractTaskProcessor for convenience (same functionality)
The following properties define the default task processors:
bharosa.uio.default.task.processor.login = com.bharosa.uio.processor.task.LoginTaskProcessor bharosa.uio.default.task.processor.jump = com.bharosa.uio.processor.task.JumpTaskProcessor bharosa.uio.default.task.processor.password = com.bharosa.uio.processor.task.PasswordTaskProcessor bharosa.uio.default.task.processor.challenge = com.bharosa.uio.processor.task.ChallengeUserTaskProcessor bharosa.uio.default.task.processor.changePassword = com.bharosa.uio.processor.task.ChangePasswordTaskProcessor bharosa.uio.default.task.processor.changeUsername = com.bharosa.uio.processor.task.ChangeUsernameTaskProcessor bharosa.uio.default.task.processor.fingerprint = com.bharosa.uio.processor.task.FingerprintTaskProcessor bharosa.uio.default.task.processor.logout = com.bharosa.uio.processor.task.LogoutTaskProcessor bharosa.uio.default.task.processor.forgotPassword = com.bharosa.uio.processor.task.ForgotPasswordTaskProcessor bharosa.uio.default.task.processor.checkpoint = com.bharosa.uio.processor.task.CheckpointTaskProcessor bharosa.uio.default.task.processor.updateStatus = com.bharosa.uio.processor.task.UpdateAuthStatusTaskProcessor bharosa.uio.default.task.processor.registerSummary = com.bharosa.uio.processor.task.RegisterSummaryTaskProcessor bharosa.uio.default.task.processor.registerImagePhrase = com.bharosa.uio.processor.task.RegisterImageAndPhraseTaskProcessor bharosa.uio.default.task.processor.registerQuestions = com.bharosa.uio.processor.task.RegisterQuestionsTaskProcessor bharosa.uio.default.task.processor.registerUserInfo = com.bharosa.uio.processor.task.RegisterUserInfoTaskProcessor bharosa.uio.default.task.processor.registerComplete = com.bharosa.uio.processor.task.RegisterCompleteTaskProcessor bharosa.uio.default.task.processor.registerSkip = com.bharosa.uio.processor.task.RegisterSkipTaskProcessor bharosa.uio.default.task.processor.userPrefsImagePhrase = com.bharosa.uio.processor.task.UserPreferencesImageAndPhraseTaskProcessor bharosa.uio.default.task.processor.userPrefsQuestions = com.bharosa.uio.processor.task.UserPreferencesQuestionsTaskProcessor bharosa.uio.default.task.processor.userPrefsUserInfo = com.bharosa.uio.processor.task.UserPreferencesUserInfoTaskProcessor bharosa.uio.default.task.processor.userPrefsComplete = com.bharosa.uio.processor.task.UserPreferencesCompleteTaskProcessor bharosa.uio.default.task.processor.transaction = com.bharosa.uio.processor.task.TransactionTaskProcessor bharosa.uio.default.task.processor.updateTransactionStatus = com.bharosa.uio.processor.task.UpdateTransactionStatusTaskProcessor
*denotes optional parameter
Table 21-1 AbstractTaskProcessor
Class name | Params | Results | Notes |
---|---|---|---|
LoginTaskProcessor |
LoginTaskProcessor.PARAM_LOGIN_ID LoginTaskProcessor.PARAM_AUTH_STATUS* Elements defined by user defined enum: bharosa.uio. |
TaskProcessorIntf.TARGET_SUCCESS TaskProcessorIntf.TARGET_ERROR |
Load user from login id |
JumpTaskProcessor |
JumpTaskProcessor.PARAM_OFFSET JumpTaskProcessor.PARAM_JUMP |
TaskProcessorIntf.TARGET_JUMP TaskProcessorIntf.TARGET_UPDATE_STATUS TaskProcessorIntf.TARGET_SUCCESS TaskProcessorIntf.TARGET_LOGIN TaskProcessorIntf.TARGET_ERROR |
Create OAAM session Perform browser fingerprinting Run pre-authentication rules |
FingerprintTaskProcessor |
(FP data from UIOSesisonData) |
TaskProcessorIntf.TARGET_SUCCESS |
Process digital fingerprinting (Flash or other external fingerprinting requests). Uses device identification processor. |
PasswordTaskProcessor |
PasswordTaskProcessor.PARAM_PASSWORD |
TaskProcessorIntf.TARGET_SUCCESS TaskProcessorIntf.TARGET_RESET_PASSWORD TaskProcessorIntf.TARGET_INVALID_USER TaskProcessorIntf.TARGET_SESSION_EXPIRED TaskProcessorIntf.TARGET_ACCESS_DENIED TaskProcessorIntf.TARGET_FAIL TaskProcessorIntf.TARGET_ERROR TaskProcessorIntf.TARGET_UPDATE_STATUS |
Process password submission to authenticate the user using AuthManager class. |
ChallengeChoiceTaskProcessor |
ChallengeChoiceTaskProcessor.PARAM_CHOICE |
TaskProcessorIntf.TARGET_CHALLENGE TaskProcessorIntf.TARGET_CHALLENGE_CHOICE TaskProcessorIntf.TARGET_FAIL TaskProcessorIntf.TARGET_ACCESS_DENIED TaskProcessorIntf.TARGET_ERROR |
Process challenge choice when user is give option for multiple challenge types. |
ChallengeUserTaskProcessor |
ChallengeUserTaskProcessor.PARAM_ANSWER ChallengeUserTaskProcessor.PARAM_REGISTER_DEVICE |
TaskProcessorIntf.TARGET_CHALLENGE TaskProcessorIntf.TARGET_UPDATE_STATUS TaskProcessorIntf.TARGET_SESSION_EXPIRED TaskProcessorIntf.TARGET_ACCESS_DENIED TaskProcessorIntf.TARGET_FAIL TaskProcessorIntf.TARGET_ERROR |
Process user challenges using challenge processor classes based on challenge type performed. |
UpdateAuthStatusTaskProcessor |
UpdateAuthStatusTaskProcessor.PARAM_STATUS UpdateAuthStatusTaskProcessor.PARAM_SECONDARY_GROUP |
(Post Authentication Rule Action) TaskProcessorIntf.TARGET_SESSION_EXPIRED TaskProcessorIntf.TARGET_ACCESS_DENIED TaskProcessorIntf.TARGET_FAIL TaskProcessorIntf.TARGET_ERROR |
Updates the session status in OAAM |
RegisterSummaryTaskProcessor |
TaskProcessorIntf.TARGET_SUCCESS TaskProcessorIntf.TARGET_NEXT |
Executed when registration summary is requested. (No out of the box functionality) |
. |
RegisterImageAndPhraseTaskProcessor |
TaskProcessorIntf.TARGET_SUCCESS TaskProcessorIntf.TARGET_NEXT TaskProcessorIntf.TARGET_SESSION_EXPIRED TaskProcessorIntf.TARGET_ACCESS_DENIED TaskProcessorIntf.TARGET_ERROR |
Processes authenticator registration. Image, Phrase, VAD upgrade/downgrade. |
. |
RegisterQuestionsTaskProcessor |
RegisterQuestionsTaskProcessor.PARAM_QUESTION_COUNT RegisterQuestionsTaskProcessor.PARAM_QUESTION_ID_BASE+# RegisterQuestionsTaskProcessor.PARAM_QUESTION_TEXT_BASE+# RegisterQuestionsTaskProcessor.PARAM_QUESTION_ANSWER_BASE+# RegisterQuestionsTaskProcessor.PARAM_REGISTER_DEVICE* |
TaskProcessorIntf.TARGET_SUCCESS TaskProcessorIntf.TARGET_NEXT TaskProcessorIntf.TARGET_SESSION_EXPIRED TaskProcessorIntf.TARGET_ACCESS_DENIED TaskProcessorIntf.TARGET_FAIL TaskProcessorIntf.TARGET_ERROR |
Processes and validates challenge question registration. |
RegisterUserInfoTaskProcessor |
Elements defined by user defined enum: bharosa.uio. RegisterUserInfoTaskProcessor.PARAM_REGISTER_DEVICE* RegisterUserInfoTaskProcessor.PARAM_OPTOUT* |
TaskProcessorIntf.TARGET_SUCCESS TaskProcessorIntf.TARGET_NEXT TaskProcessorIntf.TARGET_SESSION_EXPIRED TaskProcessorIntf.TARGET_ACCESS_DENIED TaskProcessorIntf.TARGET_ERROR |
Processes and validates OTP contact information registration. |
RegisterCompleteTaskProcessor |
TaskProcessorIntf.TARGET_NEXT TaskProcessorIntf.TARGET_SESSION_EXPIRED TaskProcessorIntf.TARGET_ACCESS_DENIED TaskProcessorIntf.TARGET_ERROR |
Updates user registration status when registration flow is complete. |
. |
RegisterSkipTaskProcessor |
TaskProcessorIntf.TARGET_SUCCESS TaskProcessorIntf.TARGET_SESSION_EXPIRED TaskProcessorIntf.TARGET_ACCESS_DENIED TaskProcessorIntf.TARGET_ERROR |
Skips registration steps if user is allowed to skip registration. |
. |
UserPreferencesImageAndPhraseTaskProcessor |
TaskProcessorIntf.TARGET_SUCCESS TaskProcessorIntf.TARGET_NEXT TaskProcessorIntf.TARGET_SESSION_EXPIRED TaskProcessorIntf.TARGET_ACCESS_DENIED TaskProcessorIntf.TARGET_ERROR |
Processes authenticator registration. Image, Phrase, VAD upgrade/downgrade. |
. |
UserPreferencesQuestionsTaskProcessor |
RegisterQuestionsTaskProcessor.PARAM_QUESTION_COUNT RegisterQuestionsTaskProcessor.PARAM_QUESTION_ID_BASE+# RegisterQuestionsTaskProcessor.PARAM_QUESTION_TEXT_BASE+# RegisterQuestionsTaskProcessor.PARAM_QUESTION_ANSWER_BASE+# RegisterQuestionsTaskProcessor.PARAM_REGISTER_DEVICE* |
TaskProcessorIntf.TARGET_SUCCESS TaskProcessorIntf.TARGET_NEXT TaskProcessorIntf.TARGET_SESSION_EXPIRED TaskProcessorIntf.TARGET_ACCESS_DENIED TaskProcessorIntf.TARGET_FAIL TaskProcessorIntf.TARGET_ERROR |
Processes and validates challenge question registration. |
UserPreferencesUserInfoTaskProcessor |
Elements defined by user defined enum: bharosa.uio. RegisterUserInfoTaskProcessor.PARAM_REGISTER_DEVICE* RegisterUserInfoTaskProcessor.PARAM_OPTOUT* |
TaskProcessorIntf.TARGET_SUCCESS TaskProcessorIntf.TARGET_NEXT TaskProcessorIntf.TARGET_SESSION_EXPIRED TaskProcessorIntf.TARGET_ACCESS_DENIED TaskProcessorIntf.TARGET_ERROR |
Processes and validates OTP contact information registration. |
UserPreferencesCompleteTaskProcessor |
TaskProcessorIntf.TARGET_NEXT TaskProcessorIntf.TARGET_SESSION_EXPIRED TaskProcessorIntf.TARGET_ACCESS_DENIED TaskProcessorIntf.TARGET_ERROR |
Updates user registration status when user preferences flow is complete. |
. |
ForgotPasswordTaskProcessor |
ForgotPasswordTaskProcessor. PARAM_PAGEID |
TaskProcessorIntf.TARGET_FORGOT_PASSWORD TaskProcessorIntf.TARGET_SUCCESS TaskProcessorIntf.TARGET_NO_PROXY TaskProcessorIntf.TARGET_SESSION_EXPIRED TaskProcessorIntf.TARGET_FAIL |
. |
LogoutTaskProcessor |
TaskProcessorIntf.TARGET_SUCCESS |
Resets user session. |
. |
CheckpointTaskProcessor |
CheckpointTaskProcessor.PARAM_CHECKPOINT If not present, will use sessionData.getCheckpoint() |
Rule action result TaskProcessorIntf.TARGET_SUCCESS |
Runs the checkpoint passed as parameter or the checkpoint set in sessionData and returns the result. |
ChangePasswordTaskProcessor |
ChangePasswordTaskProcessor.PARAM_PAGEID ChangePasswordTaskProcessor.PARAM_PASSWORD_OLD ChangePasswordTaskProcessor.PARAM_PASSWORD_NEW ChangePasswordTaskProcessor.PARAM_PASSWORD_CONFIRM |
TaskProcessorIntf.SUCCESS TaskProcessorIntf.TARGET_UPDATE_STATUS TaskProcessorIntf.TARGET_CHANGE_PASSWORD TaskProcessorIntf.TARGET_ACCESS_DENIED TaskProcessorIntf.TARGET_ERROR TaskProcessorIntf.TARGET_ERROR |
Uses password manager to update users password. |
ChangeUsernameTaskProcessor |
ChangeUsernameTaskProcessor. PARAM_USERNAME_NEW |
TaskProcessorIntf.SUCCESS TaskProcessorIntf.TARGET_ACCESS_DENIED TaskProcessorIntf.TARGET_FAIL |
Updates a users login id / username. |
TransactionTaskProcessor |
TransactionTaskProcessor.PARAM_TRANSACTION_TYPE TransactionTaskProcessor.PARAM_CHECKPOINT TransactionTaskProcessor.PARAM_EXTERNAL_TRANSACTION_ID TransactionTaskProcessor.PARAM_AUTO_UPDATE (optional - prevents status update if set to "false") TransactionTaskProcessor.CHECKPOINT_NONE (optional, prevents checkpoints from running if set to "true") |
(Transaction Rule Action) TaskProcessorIntf.TARGET_SESSION_EXPIRED TaskProcessorIntf.TARGET_ACCESS_DENIED TaskProcessorIntf.TARGET_FAIL TaskProcessorIntf.TARGET_ERROR |
Runs pre transaction and create transaction checkpoints |
UpdateTransactionStatusTaskProcessor |
TransactionTaskProcessor.PARAM_TRANSACTION_TYPE TransactionTaskProcessor.PARAM_CHECKPOINT TransactionTaskProcessor.PARAM_EXTERNAL_TRANSACTION_ID TransactionTaskProcessor.PARAM_STATIUS TransactionTaskProcessor.CHECKPOINT_NONE (optional, prevents checkpoints from running if set to "true") |
(Transaction Rule Action) TaskProcessorIntf.TARGET_SESSION_EXPIRED TaskProcessorIntf.TARGET_ACCESS_DENIED TaskProcessorIntf.TARGET_FAIL TaskProcessorIntf.TARGET_ERROR |
Runs pre-update and update transaction checkpoints. |
Task Processors allow for custom java classes to handle OAAM Server user tasks, such as entering username, entering password, or being challenged.
bharosa.uio.default.task.processor.login = com.bharosa.uio.processor.task.LoginTaskProcessor bharosa.uio.default.task.processor.jump = com.bharosa.uio.processor.task.JumpTaskProcessor bharosa.uio.default.task.processor.password = com.bharosa.uio.processor.task.PasswordTaskProcessor bharosa.uio.default.task.processor.challenge = com.bharosa.uio.processor.task.ChallengeUserTaskProcessor bharosa.uio.default.task.processor.challengeChoice = com.bharosa.uio.processor.task.ChallengeChoiceTaskProcessor bharosa.uio.default.task.processor.changePassword = com.bharosa.uio.processor.task.ChangePasswordTaskProcessor bharosa.uio.default.task.processor.changeUsername = com.bharosa.uio.processor.task.ChangeUsernameTaskProcessor bharosa.uio.default.task.processor.fingerprint = com.bharosa.uio.processor.task.FingerprintTaskProcessor bharosa.uio.default.task.processor.logout = com.bharosa.uio.processor.task.LogoutTaskProcessor bharosa.uio.default.task.processor.forgotPassword = com.bharosa.uio.processor.task.ForgotPasswordTaskProcessor bharosa.uio.default.task.processor.checkpoint = com.bharosa.uio.processor.task.CheckpointTaskProcessor bharosa.uio.default.task.processor.updateStatus = com.bharosa.uio.processor.task.UpdateAuthStatusTaskProcessor bharosa.uio.default.task.processor.registerSummary = com.bharosa.uio.processor.task.RegisterSummaryTaskProcessor bharosa.uio.default.task.processor.registerImagePhrase = com.bharosa.uio.processor.task.RegisterImageAndPhraseTaskProcessor bharosa.uio.default.task.processor.registerQuestions = com.bharosa.uio.processor.task.RegisterQuestionsTaskProcessor bharosa.uio.default.task.processor.registerUserInfo = com.bharosa.uio.processor.task.RegisterUserInfoTaskProcessor bharosa.uio.default.task.processor.registerComplete = com.bharosa.uio.processor.task.RegisterCompleteTaskProcessor bharosa.uio.default.task.processor.registerSkip = com.bharosa.uio.processor.task.RegisterSkipTaskProcessor bharosa.uio.default.task.processor.userPrefsImagePhrase = com.bharosa.uio.processor.task.UserPreferencesImageAndPhraseTaskProcessor bharosa.uio.default.task.processor.userPrefsQuestions = com.bharosa.uio.processor.task.UserPreferencesQuestionsTaskProcessor bharosa.uio.default.task.processor.userPrefsUserInfo = com.bharosa.uio.processor.task.UserPreferencesUserInfoTaskProcessor bharosa.uio.default.task.processor.userPrefsComplete = com.bharosa.uio.processor.task.UserPreferencesCompleteTaskProcessor bharosa.uio.default.task.processor.transaction = com.bharosa.uio.processor.task.TransactionTaskProcessor bharosa.uio.default.task.processor.updateTransactionStatus = com.bharosa.uio.processor.task.UpdateTransactionStatusTaskProcessor
The OAAM Server provides a challenge processor framework that allows for custom implementations of challenge mechanisms.
Challenge processors are used for the generation and validation of user challenges. They have the ability to integrate with external challenge services.
Challenge processors can be created to perform the following tasks for a challenge:
Generate challenge secret (password) to send to the user.
Validate the user answer
Control delivery wait page (if needed)
Check if delivery service is available (if needed)
For example, to use SMS, you must implement a method for generating the secret PIN and checking the status of the send and the class that is called for by a challenge type.
A challenge processor is java code that implements the ChallengeProcessorIntf
interface or extends the AbstractChallengeProcessor
class.
This section contains information on the challenge processor class and methods to implement. An implementation example is also provided for your reference.
To implement a challenge processor, you will need to extend the following class:
com.bharosa.uio.processor.challenge.AbstractChallengeProcessor
Later, you will compile the code by adding oaam.jar from $ORACLE_IDM_HOME\oaam\cli\lib
folder to the build classpath.
For instructions on customizing, extending, or overriding Oracle Adaptive Access Manager properties, see Chapter 7, "Using the OAAM Extensions Shared Library to Customize OAAM."
The methods used in a challenge processor are listed in the sections following.
Table 21-2 Challenge Processor Methods
Methods | Description |
---|---|
protected boolean generateSecret(UIOSessionData sessionData, boolean isRetry) |
This method used to generate code to send to client |
protected boolean validateAnswer(UIOSessionData sessionData, String answer) |
This method used to validate the user answer. |
public String checkDeliveryStatus(UIOSessionData sessionData, boolean userWaiting, boolean isRetry) |
This method used to provide a wait until message is sent. |
public boolean isServiceAvailable(UIOSessionData sessionData) |
This method used to check if external service is available. |
An implementation of the email challenge processor is shown as follows:
package oracle.oaam.challenge.processor.challenge; import com.bharosa.common.util.*; import com.bharosa.uio.util.UIOUtil; import com.bharosa.uio.util.UIOSessionData; import com.bharosa.common.logger.Logger; import java.io.Serializable; /** * Email Challenge Processor - provides OTP Code generation, delivery and validation */ public class EmailChallengeProcessor extends com.bharosa.uio.processor.challenge.AbstractOTPChallengeProcessor implements Serializable{ static Logger logger = Logger.getLogger(EmailChallengeProcessor.class); public EmailChallengeProcessor( ) { } /** * Generates OTP Code and stores it in sessionData * * @param sessionData data object available for the session * @param isRetry boolean value if method was called as a result of a failed answer attempt * @return */ protected boolean generateSecret(UIOSessionData sessionData, boolean isRety) { String otpCode = sessionData.getOTPCode(); // If no secret code is present in session, generate one. if (StringUtil.isEmpty(otpCode)) { if (logger.isDebugEnabled()) logger.debug("ChallengeEmail generating security code for user: " + sessionData.getCustomerId()); otpCode = generateCode(sessionData); // save the code for later reference - validate / resend sessionData.setOTPCode(otpCode); } if (logger.isDebugEnabled()) logger.debug("OTP code for user " + sessionData.getCustomerId() + " : " + otpCode); if (StringUtil.isEmpty(otpCode)) { logger.error("Email Challenge pin generation returned null."); return false; } // isRetry flag is turned on if user fails to answer the question if (!isRetry) { return sendCode(sessionData); } return true; } /** * Validate user entered answer against value in sessionData * * @param sessionData validate code and return result. * @param answer answer provided by the user * @return */ protected boolean validateAnswer(UIOSessionData sessionData, String answer){ //need to authenticate OTP Code String otpCode = sessionData.getOTPCode(); if (otpCode != null && otpCode.equals(answer)) { // Expire OTP Code sessionData.setOTPCode(null); return true; } return false; } /** * Private methods to send secret code to client * * @param sessionData * @return */ private boolean sendCode(UIOSessionData sessionData){ String otpCode = sessionData.getOTPCode(); try { // UIOUtil.getOTPContactInfo fetches the information registered by the user. Refer to ChallengeEmail.requiredInfo in configuration. String toAddr = UIOUtil.getOTPContactInfo(sessionData, "email"); if (StringUtil.isEmpty(toAddr)) { logger.error("No user email in profile."); return false; } // Send secret code to customer using your email provider } catch (Exception ex) { logger.error("ChallengeEmail Error sending code.", ex); return false; } return true; } public String checkStatus(UIOSessionData sessionData, boolean userWaiting, boolean isRetry) { String target = ChallengeProcessorIntf.TARGET_WAIT; // user already has code, trying again - send to challenge page if (isRetry){ return ChallengeProcessorIntf.TARGET_CHALLENGE; } boolean sendComplete = false; if (userWaiting){ // if secret code is sent set target to target = ChallengeProcessorIntf.TARGET_CHALLENGE; // failed to send target = ChallengeProcessorIntf.TARGET_ERROR; // still processing target = ChallengeProcessorIntf.TARGET_WAIT; } return target; } }
This section contains instructions on defining a delivery channel type for the challenge processors to use for challenging the user. Examples are provided for your reference.
Challenge types are configured by the enum, challenge.type.enum
. The actual enum value is shown as follows:
bharosa.uio.application. challenge.type.enum.challenge_type
For example,
bharosa.uio.default.challenge.type.enum.ChallengeEmail
You use the challenge type enum to associate a challenge type with the Java code needed to perform any work related to that challenge type. An example of implementing an email challenge processor is shown in Section 21.5.2.3, "Example: Email Challenge Processor Implementation."
The Challenge Type ID (for example, ChallengeEmail) should match a rule action returned by the rules when that challenge type is used. The rule action for ChallengeEmail is rule.action.enum.ChallengeEmail. The rule action is to challenge the user using email using the email delivery channel. "Channel" typically refers to the delivery channel used to send to the user.
To define a challenge type, use the following property:
bharosa.uio.default.challenge.type.enum.MyChallenge
In the property, default is the UIO application name, and MyChallenge is the Challenge Type being added. An following example shows ChallengeEmail as the Challenge Type.
bharosa.uio.default.challenge.type.enum.ChallengeEmail
The rule action is to challenge the user with email using the email delivery channel.
rule.action.enum.ChallengeEmail
To enable/disable a challenge type, the available flag should be set:
bharosa.uio.default.challenge.type.enum.MyChallenge.available = false
Table 21-3 Challenge type Flags
Property | Description |
---|---|
available |
if the challenge type is available for use (service ready and configured). To enable/disable an OTP challenge type, the available flag should be set. |
processor |
java class for handling challenges of this type. |
requiredInfo |
comma separated list of inputs from the registration input enum |
Setting the available flag and setting the enabled flag are different. The enabled flag would remove it from list.
Example for Defining a Channel Type
Attributes bharosa.uio.default.challenge.type.enum with example values are shown as follows:
bharosa.uio.default.challenge.type.enum.MyChallenge = 1 // unique value to identify Challenge Email in // bharosa.uio.default.challenge.type.enum bharosa.uio.default.challenge.type.enum.MyChallenge.name = MyChallenge // unique string to identify Challenge Email in // bharosa.uio.default.challenge.type.enum, // no spaces bharosa.uio.default.challenge.type.enum.MyChallenge.description = Email Challenge // descriptive name bharosa.uio.default.challenge.type.enum.MyChallenge.processor = oracle.oaam.challenge.processor.challenge.EmailChallengeProcessor // Processor used for sending emails instance of // com.bharosa.uio.processor.challenge.ChallengeProcessorIntf bharosa.uio.default.challenge.type.enum.MyChallenge.requiredInfo = email // comma separated field names, User registration flow captures these data fields, // check Contact information Inputs section to define this enum bharosa.uio.default.challenge.type.enum.MyChallenge.available = false // to turn off this service bharosa.uio.default.challenge.type.enum.MyChallenge.otp = true // indicates this challenge is used for OTP, set it to true
bharosa.uio.default.challenge.type.enum.ChallengeEmail = 1 bharosa.uio.default.challenge.type.enum.ChallengeEmail.name = Email Challenge bharosa.uio.default.challenge.type.enum.ChallengeEmail.description = Email Challenge bharosa.uio.default.challenge.type.enum.ChallengeEmail.processor = com.bharosa.uio.processor.challenge.EmailUMSOTPChallengeProcessor bharosa.uio.default.challenge.type.enum.ChallengeEmail.requiredInfo = email bharosa.uio.default.challenge.type.enum.ChallengeEmail.displayedInfo = email bharosa.uio.default.challenge.type.enum.ChallengeEmail.available = false bharosa.uio.default.challenge.type.enum.ChallengeEmail.enabled = true bharosa.uio.default.challenge.type.enum.ChallengeEmail.otp=true bharosa.uio.default.challenge.type.enum.ChallengeEmail.otpexpirytimeMs=300000 bharosa.uio.default.challenge.type.enum.ChallengeEmail.htmlLabel=Email Code bharosa.uio.default.challenge.type.enum.ChallengeEmail.htmlInputType=text
bharosa.uio.default.challenge.type.enum.ChallengeSMS = 2 bharosa.uio.default.challenge.type.enum.ChallengeSMS.name = SMS Challenge bharosa.uio.default.challenge.type.enum.ChallengeSMS.description = SMS Challenge bharosa.uio.default.challenge.type.enum.ChallengeSMS.processor = com.bharosa.uio.processor.challenge.SMSUMSOTPChallengeProcessor bharosa.uio.default.challenge.type.enum.ChallengeSMS.requiredInfo = mobile,terms bharosa.uio.default.challenge.type.enum.ChallengeSMS.displayedInfo = mobile bharosa.uio.default.challenge.type.enum.ChallengeSMS.available = false bharosa.uio.default.challenge.type.enum.ChallengeSMS.otp=true bharosa.uio.default.challenge.type.enum.ChallengeSMS.otpexpirytimeMs=300000 bharosa.uio.default.challenge.type.enum.ChallengeSMS.htmlLabel=SMS Code bharosa.uio.default.challenge.type.enum.ChallengeSMS.htmlInputType=text
Instructions to configure user information properties are in the following sections:
For instructions on customizing, extending, or overriding Oracle Adaptive Access Manager properties, see Chapter 7, "Using the OAAM Extensions Shared Library to Customize OAAM."
Default configurations for enabling for registration and preference input are listed as follows:
Contact information registration
bharosa.uio.default.register.userinfo.enabled=false
Contact information preferences
bharosa.uio.default.userpreferences.userinfo.enabled=false
If user information registration and user preferences are true, configure input information.
Contact information inputs are defined in userinfo.inputs.enum. The enum element is:
bharosa.uio.application.userinfo.inputs.enum.inputname
Table 21-4 Properties for Contact Input
Property | Description |
---|---|
inputname |
Name used for the input field in the HTML form |
inputtype |
Set for text or password input |
maxlength |
Maximum length of user input |
required |
Set if the field is required on the registration page |
order |
The order displayed in the user interface |
regex |
Regular expression used to validate user input for this field |
errorCode |
Error code used to look up validation error message (bharosa.uio. |
managerClass |
java class that implements com.bharosa.uio.manager.user.UserDataManagerIntf (if data is to be stored in Oracle Adaptive Access Manager database this property should be set to com.bharosa.uio.manager.user.DefaultContactInfoManager) |
bharosa.uio.default.userinfo.inputs.enum.email=1 bharosa.uio.default.userinfo.inputs.enum.email.name=Email Address bharosa.uio.default.userinfo.inputs.enum.email.description=Email Address bharosa.uio.default.userinfo.inputs.enum.email.inputname=email bharosa.uio.default.userinfo.inputs.enum.email.inputtype=text bharosa.uio.default.userinfo.inputs.enum.email.maxlength=40 bharosa.uio.default.userinfo.inputs.enum.email.required=true bharosa.uio.default.userinfo.inputs.enum.email.order=2 bharosa.uio.default.userinfo.inputs.enum.email.enabled=true bharosa.uio.default.userinfo.inputs.enum.email.regex= .+@[a-zA-Z_]+?\\.[a-zA-Z]{2,3} bharosa.uio.default.userinfo.inputs.enum.email.errorCode=otp.invalid.email bharosa.uio.default.userinfo.inputs.enum.email.managerClass= com.bharosa.uio.manager.user.DefaultContactInfoManager
By default, challenge devices that will be used are configured through rules. The rules are under the AuthentiPad checkpoint where you can specify the type of device to use based on the purpose of the device.
Note: Bypassing the authentipad checkpoint and using properties to determine which virtual device to use will not allow you to use an alternate device for challenges on mobile browsers. Some virtual devices are not ideal for mobile browsing, such as PinPad and KeyPad.
To create/update policies to use the challenge type:
Add a new rule action, MyChallenge
, with the enum, rule.action.enum
.
Create policy to return newly created action, MyChallenge
, to use the challenge method.
Alternatively, to configure challenge devices using properties, you can bypass the AuthentiPad checkpoint by setting bharosa.uio.default.use.authentipad.checkpoint
to false
.
Devices to use for the challenge type can be added.
bharosa.uio.application.challengeType.authenticator.device=value
The examples shown use the challenge type key, ChallengeEmail
and ChallengeSMS
to construct the property name.
bharosa.uio.default.ChallengeSMS.authenticator.device=DevicePinPad bharosa.uio.default.ChallengeEmail.authenticator.device=DevicePinPad
Available challenge device values are DeviceKeyPadFull
, DeviceKeyPadAlpha
, DeviceTextPad
, DeviceQuestionPad
, DevicePinPad
, and DeviceHTMLControl
.
Table 21-5 Authentication Device Type
Property | Description |
---|---|
None |
No HTML page or authentication pad |
DeviceKeyPadFull |
Challenge user using KeyPad. |
DeviceKeyPadAlpha |
Challenge user with the alphanumeric KeyPad (numbers and letters only, no special characters) |
DeviceTextPad |
Challenge user using TextPad. |
DeviceQuestionPad |
Challenge user using QuestionPad. |
DevicePinPad |
Challenge user using PinPad. |
DeviceHTMLControl |
Challenge user using HTML page instead of an authentication pad. |
Checkpoint processors allow for custom java classes to be executed when a specific checkpoint is run. The properties take the following form:
bharosa.uio.appId.checkpoint.processor.checkpoint= fully_qualified_class_name
Checkpoint processors are registered with the application using the following properties:
bharosa.uio.default.checkpoint.processor.default = com.bharosa.uio.processor.checkpoint.DefaultCheckpointProcessor bharosa.uio.default.checkpoint.processor.preauth = com.bharosa.uio.processor.checkpoint.PreAuthCheckpointProcessor bharosa.uio.default.checkpoint.processor.postauth = com.bharosa.uio.processor.checkpoint.PostAuthCheckpointProcessor bharosa.uio.default.checkpoint.processor.ChallengeUser = com.bharosa.uio.processor.checkpoint.ChallengeCheckpointProcessor bharosa.uio.default.checkpoint.processor.ForgotPassword = com.bharosa.uio.processor.checkpoint.ForgotPasswordCheckpointProcessor bharosa.uio.default.checkpoint.processor.authentiPad = com.bharosa.uio.processor.checkpoint.AuthentiPadCheckpointProcessor
If no checkpoint processor is defined, then a default checkpoint processor will be used. The default checkpoint processor is defined by similar property.
bharosa.uio.appId.checkpoint.processor.default= fully_qualified_class_name
Each checkpoint processor must implement the CheckpointProcessorIntf
interface.
public interface CheckpointProcessorIntf{ public String processCheckpoint(UIOSessionData sessionData, VCryptRulesResult rulesResult); }
It is recommended that each custom checkpoint processor extend the DefaultCheckpointProcessor
class. The default checkpoint processor has some convenience methods to help process the checkpoint.
/** * Default checkpoint handling * * Instanciates and executes appropriatlely configured RulesResultProcessors */ public class DefaultCheckpointProcessor implements CheckpointProcessorIntf{ static Logger logger = Logger.getLogger(DefaultCheckpointProcessor.class); /** * @param sessionData * @param rulesResult * @return */ protected RulesResultProcessorIntf getResultProcessor(UIOSessionData sessionData, VCryptRulesResult rulesResult){ if (rulesResult == null || rulesResult.getResult() == null){ logger.info("getResultProcessor :: Rules Result null - Using default rules result processor."); return getDefaultResultProcessor(sessionData); } String resultName = rulesResult.getResult(); return UIOUtil.getRulesResultProcessor(sessionData, resultName); } /** * @param sessionData * @return */ protected RulesResultProcessorIntf getDefaultResultProcessor(UIOSessionData sessionData){ return UIOUtil.getRulesResultProcessor(sessionData, "default"); } /** * @param checkpointType * @return */ protected String getCheckpointId(int checkpointType){ String checkpointId = null; UserDefEnumElement checkpointElem = UserDefEnum.getElement(BharosaUIOConstants.ENUM_PROFILE_TYPE, checkpointType); if (checkpointElem != null) checkpointId = checkpointElem.getElementId(); return checkpointId; } /** * @param sessionData * @param rulesResult * @return */ public String processCheckpoint(UIOSessionData sessionData, VCryptRulesResult rulesResult){ if (logger.isDebugEnabled()) logger.debug("DefaultCheckpointProcessor::processCheckpoint() entered."); List actionList = rulesResult.getAllActions(); sessionData.setActionList(actionList); RulesResultProcessorIntf rulesResultProcessor = getResultProcessor(sessionData, rulesResult); if (rulesResultProcessor == null){ logger.error("processCheckpoint :: rulesResultProcessor is null."); return Preferences.ACTION_ERROR; } return rulesResultProcessor.processRulesResult(sessionData, rulesResult); } }
Rules Result Processors allow for custom java classes to be executed when a specific rule action is returned by the rules engine. The properties take the form:
bharosa.uio.appId. rules.result.processor.rule_action= fully_qualified_class_name
Rule results processors are registered with the application using these properties:
bharosa.uio.default.rules.result.processor.default = com.bharosa.uio.processor.rules.result.DefaultRulesResultProcessor bharosa.uio.default.rules.result.processor.Password = com.bharosa.uio.processor.rules.result.PasswordRulesResultProcessor bharosa.uio.default.rules.result.processor.Challenge = com.bharosa.uio.processor.rules.result.ChallengeRulesResultProcessor bharosa.uio.default.rules.result.processor.Register = com.bharosa.uio.processor.rules.result.RegisterRulesResultProcessor bharosa.uio.default.rules.result.processor.RegistrationRequired = com.bharosa.uio.processor.rules.result.RegistrationRequiredRulesResultProcessor
If no rules result processor is defined, then a default rules result processor will be used. The default rules result processor is defined by similar property.
bharosa.uio.appId. rules.result.processor.default= fully_qualified_class_name
Each rules result processor must implement the RulesResultProcessorIntf
interface.
public interface RulesResultProcessorIntf{ public String processRulesResult(UIOSessionData sessionData, VCryptRulesResult rulesResult); }
It is recommended that each custom checkpoint processor extend the DefaultRulesResultProcessor
class. The default rules result processor has some convenience methods to help process the rules result.
/** * Default handling of rule results */ public class DefaultRulesResultProcessor implements RulesResultProcessorIntf{ static Logger logger = Logger.getLogger(DefaultRulesResultProcessor.class); /** * Process rules results, updating user status as defined by VCryptRulesResul object. * * @param sessionData * @param rulesResult * @return */ public String processRulesResult(UIOSessionData sessionData, VCryptRulesResult rulesResult){ if (logger.isDebugEnabled()) logger.debug("DefaultRulesResultProcessor::processRulesResult() entered."); if (rulesResult == null) return null; if (rulesResult.getResult() == null){ if (logger.isDebugEnabled()) logger.debug("DefaultRulesResultProcessor.processRulesResult(): rules result is null."); return Preferences.ACTION_NONE; } Preferences prefs = sessionData.getPreferences(); String ruleAction = rulesResult.getResult(); int authStatus = sessionData.getAuthResult(); int newStatus = authStatus; UserDefEnumElement actionElement = UserDefEnum.getElement(IBharosaConstants.ENUM_RULE_ACTION_ID, ruleAction); String overRideStatus = actionElement.getProperty("authStatus"); if (!StringUtil.isEmpty(overRideStatus)) { if (logger.isDebugEnabled()) logger.debug("Overriding authStatus from action. action=" + ruleAction + ", authSatus=" + overRideStatus); newStatus = Integer.parseInt(overRideStatus); } String device = prefs.getCurrentDevice(); int clientType = UIOUtil.CLIENT_TYPE_LOGIN; if (!StringUtil.isEmpty(device)){ if (device.equals(Preferences.AUTH_DEVICE_TYPE_DEVICE_TEXTPAD)) { clientType = UIOUtil.CLIENT_TYPE_TEXTPAD; } else if (device.equals(Preferences.AUTH_DEVICE_TYPE_DEVICE_KEYPAD_FULL) || device.equals(Preferences.AUTH_DEVICE_TYPE_DEVICE_KEYPAD_ALPHA)) { clientType = UIOUtil.CLIENT_TYPE_KEYPAD; } else if (device.equals(Preferences.AUTH_DEVICE_TYPE_DEVICE_HTML_CONTROL)) { clientType = UIOUtil.CLIENT_TYPE_NORMAL; } else if (device.equals(Preferences.AUTH_DEVICE_TYPE_DEVICE_QUESTIONPAD)) { clientType = UIOUtil.CLIENT_TYPE_QUESTIONPAD; } else if (device.equals(Preferences.AUTH_DEVICE_TYPE_DEVICE_PINPAD)) { clientType = UIOUtil.CLIENT_TYPE_PINPAD; } } sessionData.setClientType(clientType); if (newStatus != authStatus) { //Update tracker if status has changed sessionData.setAuthResult(newStatus); UIOUtil uioUtil = UIOUtil.instance(); try { uioUtil.updateAuthStatus(sessionData, sessionData.getClientType(), newStatus); } catch (BharosaProxyException bpe){ logger.error("Failed to update auth status to " + newStatus + " while processing ruleAction = " + ruleAction, bpe); } } return ruleAction; } }
You can use the integration processor to develop custom java code at Entry
, Exit
, and Error
points in the OAAM user flow for each application in the OAAM environment. The Integration Processor also enables you to customize access to AuthManager
, PasswordManager
, and UserDataManager
implementations.
This section contains the following topics:
You can integrate your custom java code at entry
, exit
, and error
points with client-side OAAM code.
public interface IntegrationProcessorIntf extends Serializable { public String onEntry(); public String onExit(String target); public String onError(String target); public String getAppId(); public FlowIntf getFlow(); public AuthManagerIntf getAuthManager(); public PasswordManagerIntf getPasswordManager(); public UserDataManagerIntf getDataManager(String key); }
You can set up the sessionData
object to begin common user flows. You can initiate the flows by executing the Start method.
Table 21-6 list the out-of-the-box objects and parameters:
*denotes optional parameter
Table 21-6 SessionData Objects
Class | Parameters | Notes |
---|---|---|
LoginFlow |
String appId Map<String, String> rulesMap* Hashtable appContext* |
Standard login flow with username page, password page. Fingerprinting, challenge and registration will occur as needed. |
LoginNoUsernameFlow |
String appId String loginId Map<String, String> rulesMap* Hashtable appContext* |
Similar to the login flow, but will skip the username page and use a provided username instead. |
AuthenticateFlow |
String appId String loginId int authStatus Map<String, String> rulesMap* Hashtable appContext* |
Similar to the login flow, but will skip the username and password pages using provided username and authentication status. |
ForgotPasswordFlow |
String appId String loginId Map<String, String> rulesMap* Hashtable appContext* |
Begins the forgot password flow for the provided username. Fingerprinting and forgot password checkpoint rules will be executed, resulting in challenge if policies are configured to do so. |
UserPreferencesFlow |
String appId String loginId* int authStatus* Map<String, String> rulesMap* Hashtable appContext* |
Begins the user preferences flow. If the user session already exists username and authentication status will be used from sessionData. Alternatively the username and authentication status can be provided to create a user session and display user preferences. |
The following properties are used in the OAAM server framework for registering custom java classes.
The request parameter/header to check for integration ID is
oaam.server.integration.param=intg
The integration processor allows for custom java class to handle OAAM server entry, exit, and error cases.
oaam.server.integration.processor.default=com.bharosa.uio.processor.integration. DefaultIntegrationProcessor oaam.server.integration.processor.oam=com.bharosa.uio.processor.integration. OAMIntegrationProcessor oaam.server.integration.processor.mobile=com.bharosa.uio.processor.integration. MobileIntegrationProcessor oaam.server.integration.processor.juniper=com.bharosa.uio.processor.integration. JuniperSSLIntegrationProcessor
The following are Oracle Access Management Access Manager-specific integration properties for authentication levels (used by the OAMIntegraitonProcessor class):
oaam.server.integration.oamauthentication.level.enum=Enum for oam authentication levels provided in tap token oaam.server.integration.oamauthentication.level.enum.oamoaamlevelmapping=0 oaam.server.integration.oamauthentication.level.enum.oamoaamlevelmapping.name= Mapping oaam.server.integration.oamauthentication.level.enum.oamoaamlevelmapping. oamauthlevels= -1 to 0, 1 to 99 oaam.server.integration.oamauthentication.level.enum.oamoaamlevelmapping. oaamauthlevels= 0,1
Providers allow for custom java classes to handle authentication and password management.
Authentication managers allow for custom integration with an external authentication service.
Custom implementations of authentication manager should extend the com.bharosa.uio.manager.auth.AbstractAuthManager
class, which implements the com.bharosa.uio.manager.auth.AuthManagerIntf
interface. Authentication manager returns a com.bharosa.uio.manager.auth.AuthResult
object.
The provider can be registered here for any number of application IDs, or override the getAuthManager
class in an Integration Processor.
To register your custom provider, set the following property:
bharosa.uio.default.password.auth.provider.classname = com.bharosa.uio.manager.auth.DummyAuthManager
AbstractAuthManager
implements the AuthManagerIntf
interface to perform user authentication.
Table 21-7 AbstractAuthManager
Method | Description |
---|---|
public AuthResult authenticate(VCryptAuthUser authUser, String password, Hashtable appContext) throws Exception |
Performs internal logging and calls authenticateUser method |
protected abstract AuthResult authenticateUser(VCryptAuthUser authUser, String password, Hashtable appContext) throws Exception |
Abstract method signature that takes OAAM user object, password, and application context from UIOSessionData. Implementation of this method should call external authentication service to construct and return AuthResult object. |
Password Manager classes allow for custom handling of password management. Custom password management implementations should implement the com.bharosa.uio.manager.user.PasswordManagerIntf
interface.
The password manager allows for customization of change password, set password, and retrieval of password policy text that can be displayed to user to indicate password format requirements.
The provider can be registered here for any number of application IDs, or override the getPasswordManager
class in an Integration Processor. OAAM's default implementation is only a placeholder and does not perform any actual password management.
To register your custom provider through properties, set the following:
bharosa.uio.default.user.management.provider.classname = com.bharosa.uio.manager.user.DefaultPasswordManager
PasswordManagerIntf
is the interface for implementing password manager.
Table 21-8 PasswordManagerIntf
Method | Description |
---|---|
public VCryptResponse changePassword(UIOSessionData sessionData, String oldPasswd, String newPasswd, String confirmPasswd) |
Allows for calling of external service that requires existing password to set new password. Used for password change. |
public VCryptResponse setPassword(UIOSessionData sessionData, String password) |
Allows for calling of external service that does not require existing password. Used for password reset such as in a forgot password flow. |
public VCryptObjectResponse<String[]> getPasswordPolicyText(UIOSessionData sessionData) |
Allows for custom password policy text to be displayed on password change/reset pages. This could be any messaging that the user should see, but is intended for notifying the user of password format and restrictions. |
User data managers allow customization of access and management of user profile data, such as mobile phone number and email address. By default, OAAM stores and retrieves user data from the OAAM database. With a custom implementation of the user data manager, an integration could call an external service.
When using an external service for user data, it is recommended to set a flag in the OAAM database that is used to track the existence of the user data being set.
To customize use data manager, it is recommended that you extend the com.bharosa.uio.manager.user.DefaultContactInfoManager
class. This class implements the com.bharosa.uio.manager.user.UserDataManagerIntf
interface.
Each user data field can use a different user data manager. This would allow each data element to be maintained in a different external service if required. By default OAAM uses the same data manager for all user data fields.
To register your custom user data manager, set the "managerClass
" property on the "userinfo.inputs
" enum.
Example: bharosa.uio.default.userinfo.inputs.enum.mobile.managerClass=com.bharosa.uio.manager.user.DefaultContactInfoManager
UserDataManagerIntf
is the user data manager interface for storing/retrieving user data.
Table 21-9 UserDataManagerIntf
Method | Description |
---|---|
public String getUserData(UIOSessionData sessionData, String key) |
Get the user data value for the "key". |
public void setUserData(UIOSessionData sessionData, String key, String value) |
Set the user data "value" for the "key". |
DefaultContactInfoManager
- Default implementation of user data manager. This implementation splits the setting of the data value and the flag that indicates the value is set.
Table 21-10 DefaultContactInfoManager
Method | Description |
---|---|
public String getUserData(UIOSessionData sessionData, String key) |
Calls getUserDataValue if getUserDataFlag returns true. |
public void setUserData(UIOSessionData sessionData, String key, String value) |
Calls setUserDataValue and setUserDataFlag for the "key" and "value". |
protected String getUserDataValue(UIOSessionData sessionData, String key) |
Gets the "value" for the "key" from the OAAM database. |
protected void setUserDataValue(UIOSessionData sessionData, String key, String value) |
Sets the "value" for the "key" in the OAAM database. |
protected boolean getUserDataFlag(UIOSessionData sessionData, String key) |
Returns true if the flag for the give "key" is set in the OAAM database. |
protected void setUserDataFlag(UIOSessionData sessionData, String key, String value) |
Sets the flag indicating if a value is set for a user data key. If value passed is empty, the flag is cleared. |
The legacy rule result processors support 10g policies. The properties are listed as follows:
bharosa.uio.default.rules.result.processor.PasswordTextPadGeneric = com.bharosa.uio.processor.rules.result.legacy.PasswordRulesResultProcessor bharosa.uio.default.rules.result.processor.PasswordTextPad = com.bharosa.uio.processor.rules.result.legacy.PasswordRulesResultProcessor bharosa.uio.default.rules.result.processor.PasswordKeypad = com.bharosa.uio.processor.rules.result.legacy.PasswordRulesResultProcessor bharosa.uio.default.rules.result.processor.PasswordKeypadFull = com.bharosa.uio.processor.rules.result.legacy.PasswordRulesResultProcessor bharosa.uio.default.rules.result.processor.PasswordHTML = com.bharosa.uio.processor.rules.result.legacy.PasswordRulesResultProcessor bharosa.uio.default.rules.result.processor.RegisterUserOptionalQuestionPad = com.bharosa.uio.processor.rules.result.legacy.RegisterRulesResultProcessor bharosa.uio.default.rules.result.processor.RegisterUserQuestionPad = com.bharosa.uio.processor.rules.result.legacy.RegisterRulesResultProcessor bharosa.uio.default.rules.result.processor.RegisterUserOptionalTextPad = com.bharosa.uio.processor.rules.result.legacy.RegisterRulesResultProcessor bharosa.uio.default.rules.result.processor.RegisterUserTextPad = com.bharosa.uio.processor.rules.result.legacy.RegisterRulesResultProcessor bharosa.uio.default.rules.result.processor.RegisterUser = com.bharosa.uio.processor.rules.result.legacy.RegisterRulesResultProcessor bharosa.uio.default.rules.result.processor.RegisterUserOptional = com.bharosa.uio.processor.rules.result.legacy.RegisterRulesResultProcessor bharosa.uio.default.rules.result.processor.RegisterQuestionsQuestionPad = com.bharosa.uio.processor.rules.result.legacy.RegisterRulesResultProcessor bharosa.uio.default.rules.result.processor.RegisterQuestionsTextPad = com.bharosa.uio.processor.rules.result.legacy.RegisterRulesResultProcessor bharosa.uio.default.rules.result.processor.RegisterQuestions = com.bharosa.uio.processor.rules.result.legacy.RegisterRulesResultProcessor bharosa.uio.default.rules.result.processor.RegisterImageTextPad = com.bharosa.uio.processor.rules.result.legacy.RegisterRulesResultProcessor bharosa.uio.default.rules.result.processor.RegisterImageKeyPad = com.bharosa.uio.processor.rules.result.legacy.RegisterRulesResultProcessor bharosa.uio.default.rules.result.processor.ChallengeQuestionPad = com.bharosa.uio.processor.rules.result.legacy.ChallengeRulesResultProcessor bharosa.uio.default.rules.result.processor.ChallengeSMS = com.bharosa.uio.processor.rules.result.legacy.ChallengeRulesResultProcessor bharosa.uio.default.rules.result.processor.ChallengeEmail = com.bharosa.uio.processor.rules.result.legacy.ChallengeRulesResultProcessor bharosa.uio.default.rules.result.processor.ChallengeIM = com.bharosa.uio.processor.rules.result.legacy.ChallengeRulesResultProcessor bharosa.uio.default.rules.result.processor.ChallengeVoice = com.bharosa.uio.processor.rules.result.legacy.ChallengeRulesResultProcessor bharosa.uio.default.rules.result.processor.ChallengeQuestion = com.bharosa.uio.processor.rules.result.legacy.ChallengeRulesResultProcessor