25 Developing Configurable Actions

Oracle Adaptive Access Manager provides Configurable Actions, a feature which allows users to create new supplementary actions that are triggered based on the result action and/or based on the risk scoring after a checkpoint execution. This section describes how to integrate a Configurable Action with the Oracle Adaptive Access Manager software.

This chapter contains the following sections:

25.1 Adding a New Configurable Action

To add a new Configurable Action, perform the following tasks:

  1. Develop the Configurable Action by implementing the com.bharosa.vcrypt.tracker.dynamicactions.intf.DynamicAction java interface.

    Note:

    In this step, implementing means writing java code based on the contract specified by the Java interface com.bharosa.vcrypt.tracker.dynamicactions.intf.DynamicAction.

    While implementing the com.bharosa.vcrypt.tracker.dynamicactions.intf.DynamicAction java interface, the following two methods have to be coded:

    • getParameters() - In this method, the code has to be written that returns the parameters used by the Configurable Action. Ensure that the size of the parameters array returned is the same as the number of parameters.

    • execute() - In this method, code has to be written that performs the logic required by the Configurable Action. Configurable Action parameter values are passed in actionParamValueMap where the parameter name is the key and the RuntimActionParamValue object is the value. Use the appropriate getXXXValue() method to get the parameter value.

  2. Compile your custom java classes that extend or implement Oracle Adaptive Access Manager classes by adding the JAR files from $ORACLE_IDM_HOME\oaam\cli\lib folder to the build classpath.

  3. Test the implementation of the Configurable Action thoroughly.

    Since Configurable Actions are standalone java classes, they can be tested with Unit Testing Methodology using JUnit framework.

    For sample JUnit code for testing configurable actions, see Section 25.4, "Sample JUnit Code."

  4. Compile the java class and create a JAR file of the compiled class files.

  5. Extend/customize Oracle Adaptive Access Manager to add the custom JAR file. For instructions for adding the custom JAR file to Oracle Adaptive Access Manager, see Section 7, "Using the OAAM Extensions Shared Library to Customize OAAM."

  6. Restart OAAM Server and the OAAM Admin Server.

  7. Log in to OAAM Admin and create an action definition entry for the newly deployed Configurable Action.

  8. Make sure all the parameters required for the Configurable Action are displayed in the user interface.

  9. Use the newly available Configurable Action by adding it to the required checkpoints. For information on configuring Configurable Actions, see Oracle Fusion Middleware Administrator's Guide for Oracle Adaptive Access Manager.

25.2 Executing Configurable Actions in a Particular Order and Data Sharing

You can use configurable actions to implement chaining in such a way that

  • they execute in a particular order

  • data can be shared across these actions

Note:

Sharing data across Configurable Actions involves writing java code and requires more effort than just a configuration task.

To be able to execute Configurable Actions in a particular order and share data:

  1. Configure Configurable Actions as synchronous actions with the required order of execution in ascending order.

    Note:

    A Configurable Action is executed only if the trigger criteria is met; therefore, make sure the trigger criteria is correct.
  2. To share data, insert the data into the actionContextMap parameter of the Configurable Action's execute() method. Since the actionContextMap is a Map, it requires a key and value pair that represents the data to be shared.

    Note:

    it is the implementor's responsibility to ensure that
    • the duplicate keys are not used while inserting data

    • the same key is used when trying to access this shared data from another Configurable Action.

  3. Ensure that the code can handle the case where the key is not present in the actionContextMap. This step must be performed to avoid errors or NullPointerException when the other action do not insert the value into the actionContextMap.

25.3 How to Test Configurable Actions Triggering

To test if configurable actions triggering:

  1. Make sure there is a way to identify if the code in the Configurable Action is executed. This could be as simple as an entry in log file or an entry in database.

  2. Enable debug level logging for oracle.oaam logger in OAAM Server.

  3. Create an action template for the given Configurable Action.

  4. Add the action to a Pre-Authentication checkpoint with trigger criteria as score between 0 and 1000.

  5. Try logging in to OAAM Server as a user.

  6. Check OAAM Server logs for the entry Enter: executeAction(): Executing Action Instance.

  7. If there is no error then you will see a related log statement like Exit: executeAction(): Action Instance.

  8. If there is an error, you will see a log statement like Error: executeAction().

  9. In addition, check for a log entry or a database entry created by the Configurable Action.

25.4 Sample JUnit Code

The following is a sample JUnit code for testing dynamic action:

public class TestDynamicActionsExecution extends TestCase {
        static Logger logger = Logger.getLogger(TestDynamicActionsExecution.class);
        private DynamicAction caseCreationAction = null;
 
 
        public void setUp()throws Exception {
                caseCreationAction = new CaseCreationAction();
    }
 
        public void testDynamicAction() {
 
                //RequestId
                String requestId = "testRequest";
 
                //Request Time
                Date requestTime = new Date();
 
                //Map that contains values passed to the rule/model execution
                Map ruleContextMap = new HashMap();
 
                //Result from rule execution
                VCryptRulesResultImpl rulesResult = new VCryptRulesResultImpl();
                rulesResult.setResult("Allow");
                rulesResult.setRuntimeType(new Integer(1));
 
                //Configurable action's parameter values
                Map actionParamValueMap = new HashMap();
                RuntimeActionParamValue caseTypeParamValue = new
 RuntimeActionParamValue();
                caseTypeParamValue.setIntValue(CaseConstants.CASE_AGENT_TYPE);
 
                RuntimeActionParamValue caseSeverityParamValue = new
 RuntimeActionParamValue();
                caseSeverityParamValue.setIntValue(1);
 
                RuntimeActionParamValue caseDescriptionParamValue = new
 RuntimeActionParamValue();
                caseDescriptionParamValue.setStringValue("Testing CaseCreation
 Action");
 
                //ActionContext Map for passing data to/from the dynamic action
 execution
                Map actionContextMap = new HashMap();
 
                //Execute the action
                try {
                        caseCreationAction.execute(requestId, requestTime,
 ruleContextMap, rulesResult, actionParamValueMap, actionContextMap);
                }catch(Exception e) {
                        Assert.fail("Exception occurred while executing dynamic
 action");
                        logger.error("Exception occcurred while executing dynamic
 action", e);
                }
 
                //Write appropriate asserts to check if the configurable action
 has executed properly
        }
 
    public void tearDown() throws Exception {
 
    }
}

25.5 Sample Java Code for Configuration Action

Sample code is provided in this section for a configurable action:

public class HelloWorldAction implements DynamicAction {
 
     private UserDefEnum valueTypeEnum = UserDefEnum.getEnum("value.type.enum");
 
     public boolean execute(String sessionId, Date requestTime,
 
               Map ruleContextMap, VCryptRulesResult ruleResult,
 
               Map actionParamValueMap, Map actionContextMap) throws Exception {
 
           // TODO Auto-generated method stub
 
            System.out.println("Hello World!!");
 
            return false;
 
      }
 
 
 
     public DynamicActionParamInfo[] getParameters() {
 
         DynamicActionParamInfo params[] = new DynamicActionParamInfo[3];
 
 
 
         String paramName = "Sample Integer Parameter";
 
         String description = "Integer Parameter Description";
 
         String notes = "Integer Parameter Notes";
 
         String promptLabel = "Integer Parameter";
 
         int valueType = valueTypeEnum.getElementValue("int");
 
         String defaultValue = "1";
 
 
 
         params[0] = new DynamicActionParamInfo();    
              
 
         params[0].setParamName(paramName);
 
         params[0].setPromptLabel(promptLabel);
 
         params[0].setNotes(notes);
 
         params[0].setDescription(description);
 
         params[0].setValueType(valueType);
 
         params[0].setDefaultValue(defaultValue);
 
                              
 
         paramName = "Sample String Parameter";
 
         description = "String Parameter Description";
 
         notes = "String Parameter Notes";
 
         promptLabel = "String Parameter";
 
         valueType = valueTypeEnum.getElementValue("string");
 
         defaultValue = "Sample String value";
 
                              
 
         params[1] = new DynamicActionParamInfo();    
              
 
         params[1].setParamName(paramName);
 
         params[1].setPromptLabel(promptLabel);
 
        params[1].setNotes(notes);
 
        params[1].setDescription(description);
 
        params[1].setValueType(valueType);
 
        params[1].setDefaultValue(defaultValue);
 
 
 
 
 
        paramName = "Sample Boolean Parameter";
 
        description = "Boolean Parameter Description";
 
        notes = "Boolean Parameter Notes";
 
        promptLabel = "Boolean Parameter";
 
        valueType = valueTypeEnum.getElementValue("boolean");
 
        defaultValue = "true";
 
        params[2] = new DynamicActionParamInfo();    
              
 
        params[2].setParamName(paramName);
 
        params[2].setPromptLabel(promptLabel);
 
        params[2].setNotes(notes);
 
        params[2].setDescription(description);
 
        params[2].setValueType(valueType);
 
        params[2].setDefaultValue(defaultValue);
                                return params;
 
     }
 
}