22 Integrating Task Processors

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:

22.1 Introduction

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 22-1, "OAAM Standard Web Application" shows the standard web application.

Figure 22-1 OAAM Standard Web Application

The OAAM Processor Framework is shown.

Figure 22-2, "OAAM Processor Framework" shows the different components of the processor framework.

Figure 22-2 OAAM Processor Framework

The OAAM Processor Framework is shown.

22.2 OAAM Sample Framework as a Reference for Integration

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 document ID 1501759.1.

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 available through My Oracle Support document ID 1351899.1. 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:

  1. Create the oaam_framework_sample folder.

  2. Extract oaam_framework_sample.war into oaam_framework_sample.

  3. Start the WebLogic Server.

  4. Navigate to the Oracle WebLogic Administration Console.

    http://oaam_host:port/console

  5. Deploy the OAAM Shared Library $MW_HOME\Oracle_IDM1\oaam\oaam_libs\war\oaam_native_lib.war as a shared library.

    1. Click Deployments under IAMDomain (in the left pane).

    2. In the Summary of Deployments page, click the Install button.

    3. In the Path field, specify $MW_HOME\Oracle_IDM1\oaam\oaam_libs\war\oaam_native_lib.war.

    4. Select oaam_native_lib.war and click Next.

    5. Select the Install this deployment as a library option and click Next.

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

    7. Click Finish.

    8. Click Activate Changes.

  6. Deploy the OAAM sample application as an application onto the same managed server where the OAAM Shared Library is deployed.

    1. Click Deployments under IAMDomain (in the left pane).

    2. In the Summary of Deployments page, click the Install button.

    3. In the Path field, specify the location of the OAAM sample application and click Next.

    4. Select the Install this deployment as an application option. Click Next.

    5. In the Select Deployments targets page, select the managed server from the list of servers and click Next.

    6. Click Finish.

  7. Click Activate Changes under the Change Center.

  8. 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>
    
  9. Start the managed server.

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

  11. Log in to OAAM Admin application and import the snapshot.

  12. Import the Transaction policies from the Sample_Txn_Models.zip file.

  13. Navigate to the URL http://managed_server:port/oaam_framework_sample. You will see the login page of the OAAM sample application.

  14. 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 be test for the initial log in. You must change the password immediately.

22.3 Session Management

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.

22.4 Task Processors

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"

22.4.1 Interface and Abstract Class

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)

Property Registration

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

Accessing a Task Processor

Task processors are accessed by calling the Utility method:

UIOUtil.getTaskProcessor(UIOSessionData sessionData, String taskId)

Creating Parameters

TaskParams params = new TaskParams();
params.addParam(LoginTaskProcessor.PARAM_LOGIN_ID, loginId);
params.setActionSubmit();

Executing Task

target = taskProc.execute(params).getResult();

22.4.1.1 TaskProcessorIntf

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_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_RESET_PASSWORD = "resetPassword";
    public static final String TARGET_CHANGE_PASSWORD = "changePassword";
    public static final String TARGET_CHALLENGE= "challenge";
    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 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 String execute(UIOSessionData sessionData, Map<String, String> params);
    
}        

22.4.1.2 AbstractTaskProcessor

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);
    }
}

22.4.1.3 Default Classes

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 22-1 AbstractTaskProcessor

Class name Params Results Notes

LoginTaskProcessor

LoginTaskProcessor.PARAM_LOGIN_ID

LoginTaskProcessor.PARAM_AUTH_STATUS*

Elements defined by user defined enum: bharosa.uio.appId.credentials.enum*

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.

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.appId.userinfo.inputs.enum

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.appId.userinfo.inputs.enum

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


22.4.2 Task Processor Registration

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

22.5 Challenge Processors

The OAAM Server provides a challenge processor framework that allows for custom implementations of challenge mechanisms.

22.5.1 What are Challenge Processors

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.

22.5.2 How to Create Challenge Processors

This section contains information on the challenge processor class and methods to implement. An implementation example is also provided for your reference.

22.5.2.1 Class

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

22.5.2.2 Methods

The methods used in a challenge processor are listed in the sections following.

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


22.5.2.3 Example: Email Challenge Processor Implementation

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

22.5.2.4 Secret (PIN) Implementation

The AbstractOTPChallengeProcessor class has a default pin generation method, generateCode, that you can override to provide your pin generation logic.

22.5.3 Define the Delivery Channel Types for the Challenge Processors

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.

22.5.3.1 Challenge Type Enum

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

22.5.3.2 Example: Defining an OTP Channel Type

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

Email Example

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.EmailChallengeProcessor
bharosa.uio.default.challenge.type.enum.ChallengeEmail.requiredInfo = mobile
bharosa.uio.default.challenge.type.enum.ChallengeEmail.available = true
bharosa.uio.default.challenge.type.enum.ChallengeEmail.enabled = true

SMS Example

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.SmsChallengeProcessor
bharosa.uio.default.challenge.type.enum.ChallengeSMS.requiredInfo = mobile
bharosa.uio.default.challenge.type.enum.ChallengeSMS.available = true
bharosa.uio.default.challenge.type.enum.ChallengeSMS.enabled = true

22.5.4 Configure User Input Properties

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

22.5.4.1 Enable Registration and Preferences Input

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

22.5.4.2 Set Contact Information Inputs

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 22-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.application_ID.error.errorCode)

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)


Email Input Example

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

22.5.5 Configure the Challenge Pads Used for Challenge Types

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:

  1. Add a new rule action, MyChallenge, with the enum, rule.action.enum.

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


22.6 Checkpoint Processor

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);
  }
  
}

22.7 Rules Results Processor

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

22.8 Integration Processors

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:

22.8.1 IntegrationProcessorIntf Interface

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);
  
}

22.8.2 Common User Flows

You can set up the sessionData object to begin common user flows. You can initiate the flows by executing the Start method.

Table 22-6 list the out-of-the-box objects and parameters:

*denotes optional parameter

Table 22-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 auth status will be used from sessionData. Alternatively the username and authentication status can be provided to create a user session and display user preferences.


22.8.3 Integration Processor Parameters

The following properties are used in the OAAM server framework for registering custom java classes.

22.8.3.1 Check for Integration ID

The request parameter/header to check for integration ID is

oaam.server.integration.param=intg

22.8.3.2 Integration Processor Registration

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

22.8.3.3 Oracle Access Management Access Manager Specific Integration Properties for Authentication Levels

The following are Oracle Access Management Access Manager-specific integration properties for authentication levels (used by the OAMIntegrationProcessor 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

22.9 Provider Registration

Providers allow for custom java classes to handle authentication and password management.

22.9.1 Authentication Manager

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


22.9.2 Password Manager

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


22.9.3 User Data Manager

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


22.10 Legacy Rules Result Processors

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