Configuring a Custom Activity Use Case in Oracle Adaptive Risk Management

Introduction

This tutorial shows you how to configure a custom activity use case in Oracle Adaptive Risk Management (OARM).

In addition to the out-of-the-box User Authentication activity, a customer can create their own custom activities and create rules using the information collected from it. Rules are customized according to business needs. These rules can be transactional in nature, monitoring various aspects of the user activity that the business is interested in. Some examples of custom activities are internet banking or bill paying in a banking application. You can add rules that use the information, like the amount involved in the payment, user information, and so on to identify a fraudulent money transfer.

This tutorial considers a scenario where the Administrator monitors a custom activity that involves a user making purchases online. If the first shopping transaction is worth more than $500, then the user is allowed to go ahead with the transaction. However, if the user performs a second online transaction within 5 minutes of the first purchase and it exceeds $500, then the user is blocked. The Administrator can monitor alerts, actions, rules, and other user-related information through the User Session dashboard.

Objectives

In this tutorial you will perform the following tasks:

  1. Configure a custom activity in OARM.
  2. Test the rule using OAA Risk REST API.
  3. Test the behaviour of the rule by updating the condition.
  4. Monitor the user session.

Prerequisites

Before starting this tutorial you must follow:

Configure a Custom Activity in OARM

To configure a Custom Activity for the Credit Card Activity perform the following steps:

Create Custom Activity for Credit Card Activity

  1. Log in to the OARM Administration console. You are redirected to the OAM login page as the console is protected by OAM OAuth. Specify your credentials and login.

  2. Click the Application Navigation hamburger menu in the top-left.

  3. Under Adaptive Risk Management, click Custom Activities. The Custom Activities page appears.

  4. Click Create New Activity.

    Description of the illustration customactivity.jpg

  5. On the New Custom Activity page, in the 1. Describe Activity pane, enter the following:

    • Enter a name for this Activity: Specify the name of the custom activity. For example, Credit Card Activity.
    • Description: Specify the description of the custom activity. For example, Credit Card Activity.
    • Click Next.

    Description of the illustration describeactivity.jpg

  6. In the 2. Specify the Actors to be monitored pane, click Next.

    Note: For this use case, no actors are selected. For more information on how to specify actors to be monitored, see Help Reference for Oracle Advanced Authentication Admin Console.

    Description of the illustration actor.jpg

  7. In the 3. Provide Activity Details to be monitored section, click Add Details and enter the following information:

    • Name: Specify a name for the activity detail. In this example item price is used as this custom activity use case is associated with the price of the item that a customer has purchased.
    • Description: Specify a description for the activity detail, for example purchased item price.
    • Required: Use the toggle button to specify the element is required. This ensures that for every transaction coming into OARM, the price information is provided.
    • Data Type: Specify the data type of the attribute as Numeric.
    • Encrypted: Use the toggle button to specify whether the element should be encrypted. Encryption is used for string data fields only; other data fields are not required to be encrypted. In this example we will leave it unencrypted.
    • Click Ok.

    Description of the illustration adddetails.jpg

    To the right of item price, click the Map icon to provide the source data as follows:

    • Source Data: The source data refers to the client data coming from a protected application as part of a transaction. For example, transaction.price.
    • Mapping Type: This specifies a way to connect the source data to the destination data and to the actor. As we require a one-to-one mapping of the source data element to the destination data element, select Direct.

    Description of the illustration mapping.jpg

    • Click Ok.
    • Click Done.

  8. Click Save and Proceed to confirm the creation of the Custom Activity.

    Description of the illustration confirm.jpg

Create an Alert Group

  1. Click the Application Navigation hamburger menu in the top-left, and under Adaptive Risk Management click Manage Groups. Click Create New Group.

  2. In the New Group page create a new Alert group as follows:

    • Group Name: Specify a name for the group, for example Purchased Item Exceeds Limit.
    • Group Type: Specify the Group Type as Alerts.
    • Group Description: Specify a description for the group, for example Alert if purchase price is above $500.
    • Click Create.

    Description of the illustration alertgroup.jpg

  3. In the Purchased Item Exceeds Limit pane, select Add Alerts:

    Description of the illustration addalerts.jpg

  4. In the Add Value pane, enter the following values and click Add:

    • Alert Type: Specify the alert type as Fraud.
    • Alert Level: Specify the alert level as High.
    • Alert Message: Specify the alert message as Purchase price exceeds limit.

    Description of the illustration alertvalues.jpg

  5. The Alert is now added to the Alert Group:

    Description of the illustration alertgroupfinal.jpg

  6. Click Save.

Configure a Credit Card Activity Rule

  1. Click the Application Navigation hamburger menu in the top-left, and click Adaptive Risk Management to view the list of activities on the dashboard.

    Description of the illustration monitoreduseractivity.jpg

  2. On the Credit Card Activity tile, click the 0 Rules link. The User Activity Page appears.

  3. On the User Activity page, Click Add New Rule.

    Description of the illustration addnewrule.jpg

  4. On the Add New Rule page, enter the following information:

    • Name: Specify a name for the rule, for example Check Credit Card Activity Rule.
    • Description: Specify a description for the rule, for example Check if purchase price is above $500.
    • Status: Use the toggle button to enable the rule.
    • Select Action: Select the action you want to associate with the rule. For example, Block in this use case.
    • Select Alert: Select the alert to trigger when the rule is evaluated. For example, Purchase Item Exceeds Limit.

    Description of the illustration checkcreditcardactrule.jpg

  5. In the same window, use the toggle button to Show Advanced Conditions.

  6. From the Search Condition list, select Check Transaction Count using filter conditions, and click Add Condition. The condition appears below. Enter the information as follows:

    • Select Transaction to count: Credit Card Activity
    • Specified Condition For Count: Greater Than Equals
    • Specified Check Value for count: 1
    • Transaction Status: Leave empty
    • Ignore Current Transaction in count: True
    • for the same user: True
    • Apply the filter checks on Current Transaction: True
    • Duration: 5
    • Duration Type: Rolling
    • Duration Unit: Minutes

    Description of the illustration condition.jpg

    • Click Save. The rule will be displayed:

    Description of the illustration useractivityrule.jpg

  7. Click the Application Navigation hamburger menu on top-left, and under Adaptive Risk Management click Custom Activities.

  8. Select the toggle button to enable Credit Card Activity.

    Description of the illustration activateactivity.jpg

  9. Click the Application Navigation hamburger menu on top-left, and click Adaptive Risk Management to view the list of user activities on the dashboard. You will now see a rule associated with the custom activity:

    Description of the illustration monitoreduseractivitywithrule.jpg

    During the authentication flow, when this rule is executed, the condition Check Transaction Count using filter conditions associated with the rule is evaluated. If this condition is evaluated to True, then the rule is triggered. Consequently, the user is blocked.

Testing the Credit Card Activity Rule Using OAA Risk REST API

In this section, you will test the Check credit card activity rule using the OAA Risk Rest API.

Install the OARM Postman Collection

Set the Environment Parameters in Postman

  1. Open Postman, and select File > Import.

  2. In the Import dialog box, in the File tab, select Upload Files. Choose the Oracle_Advanced_Authentication_Example_Environment.postman_environment.json , and then click Open.

  3. In the left hand menu click Environments.

  4. In the environment list displayed, to the right of Oracle Advanced Authentication Example Environment, click the elipsis and then Duplicate.

    Description of the illustration duplicate_env.jpg

  5. On Oracle Advanced Authentication Example Environment Copy, which appears above the original environment, click the elipsis and rename to Oracle Advanced Authentication Environment for REST APIs.

  6. Update the environment variables for the new environment by entering the following values for Initial Value and Current Value. Once complete click Save and then X on the tab to close it:

    • oaa-admin: Oracle Advanced Authentication hostname and admin port, for example https://oaa.example.com.
    • oaa-policy: Oracle Advanced Authentication hostname and policy port, for example https://oaa.example.com.
    • oaa-runtime: Oracle Advanced Authentication hostname and runtime port, for example https://oaa.example.com.
    • RELEASENAME: The RELEASENAME assigned to the Oracle Advanced Authentication setup, for example oaainstall. This is the value passed for common.deployment.name when installing OAA.
    • oaapolicyapikey: The oaapolicyapikey for the Oracle Advanced Authentication setup, for example a5764d4ef6b71129f38a2d8ddc88b6060653d3c8. This is the value passed for install.global.policyapikey when installing OAA.
    • oaaapikey: The oaaapikey for the Oracle Advanced Authentication setup, for example a5764d4ef6b71129f38a2d8ddc88b6060653d3c8. This is the value passed for install.global.uasapikey when installing OAA.
    • KBA: The KBA username for the Oracle Advanced Authentication setup, for example OAAINSTALL_OAA_KBA. This takes the value <RELEASENAME>_OAA_KBA and is case sensitive.
    • oaafactorapikey: The oaafactorapikey for the Oracle Advanced Authentication setup, for example a5764d4ef6b71129f38a2d8ddc88b6060653d3c8. This is the value passed for install.global.factorsapikey when installing OAA.
    • oaa-risk: Oracle Advanced Authentication hostname and risk port, for example https://oaa.example.com.
    • oaariskapikey: The oaaapikey for the Oracle Advanced Authentication setup, for example a5764d4ef6b71129f38a2d8ddc88b6060653d3c8. This is the value passed for install.global.riskapikey when installing OAA.

    Note: If you do not know the URL’s for oaa-admin, oaa-policy, oaa-runtime (spui), and oaa-risk, see Printing Deployment Details.

    The environment will look similar to the following:

    Description of the illustration environment.jpg

    Note: The URL values in the example above assume an OAA install using NodePort and hence port numbers for each of the pods are defined in the URL’s. If the OAA install uses an ingress then use the ingress URL in all cases.

  7. Click the Environment drop-down list, and then select the updated environment from the list:

    Description of the illustration environment_selection.jpg

Import the Postman Collection

  1. To import the Oracle Adaptive Risk Management REST API Postman collection, on the Postman main page, select File > Import.

  2. In the Import dialog box, in the File tab, select Upload Files. Choose the file Oracle_Adaptive_Risk_Management_Rest_API.postman_collection.json, and then click Open and then Import.

    Click on Collections in the left hand menu. The collection should display as follows:

    Description of the illustration collections.jpg

Test the Credit Card Activity Rule

To execute this custom activity at runtime, you must run the following API.

Retrieve the User Activity ID

Retrieve the User Activity ID associated with the Credit Card Activity:

  1. On the Postman Collections tab, navigate to Oracle Adaptive Risk Management REST API > user-activities.

  2. Select Gets user activities. This request makes a GET request to the /policy/risk/v1/user-activities endpoint and retrieves the user activity ID associated with the Credit Card Activity. Click Send:

    Description of the illustration getuseractivities.jpg

  3. In the response, confirm that the Status: 200 OK appears. From the response body, copy the value for the credit card activity to a text file. You will need this later during the transaction.

    Description of the illustration getuseractivitiesresponse.jpg

Create a Session for the User

Create a session for the user as follows:

  1. On the Postman Collections tab, navigate to Oracle Adaptive Risk Management REST API > session/v1 > (request id).

  2. Select Create new session for the user authentication request. This request makes a POST request to the risk-analyzer/session/v1 endpoint. In the body, edit the information in the body to match your user and environment. In the example below we are requesting to create a session for testuser in the default group. For more information on how to set the rest of the parameters in the body, click the documentation icon highlighted in the top right of the screenshot below:

    Description of the illustration createsession.jpg

  3. In the response body, confirm that the Status: 200 OK appears. Copy the value of requestID to a text file. You will need this value later to create a transaction.

    Description of the illustration createsessionresponse.jpg

Create a Transaction for the User

Create a transaction for the user as follows:

  1. On the Postman Collections tab, navigate to Oracle Adaptive Risk Management REST API > transaction/v1.

  2. Select Create new transactions. This request makes a POST request to the /risk-analyzer/transaction/v1 endpoint. In the body, replace the value of requestID with the value copied in the previous step, and click Send:

    Description of the illustration createtransaction.jpg

    Note: In the preceding body text, you will observe the “key”: “transaction.price”. This field is defined in the mapping created in Step 7 of Create Custom Activity for Credit Card Activity. Here we are setting to a value of $700 which is above the $500 limit set. You will also notice other key values, such as “key”: “CC.name”, which corresponds to credit card name, which is not needed in the present use case. This can be used in future if you intend to extend this use case.

  3. In the response, confirm that the Status: 200 OK appears. From the response body, copy the value of transactionId, which is 5 in a text file. You will need this value in the next step where you will execute the rule.

    Description of the illustration transactionresponse.jpg

Process the Rule

Process the rule for the transaction as follows:

  1. On the Postman Collections tab, navigate to Oracle Adaptive Risk Management REST API > transaction/v1.

  2. Select Process Rule. This request makes a PUT request to the /risk-analyzer/risk/v1 endpoint.

    Replace the following values in the API call, and click Send:

    • CheckpointList: Specifies the value obtained for the credit card activity in Retrieve the User Activity ID, for example: 1600.
    • transactionId: Specifies the value of the transaction created in Create a Transaction for the User ** , for example, **5.
    • requestID: Specifies the value obtained in Create a Session for the User.

    Description of the illustration processrule.jpg

  3. In the response body, result is blank, which means Allow and the user is allowed to proceed with the transaction on the first attempt.

    Description of the illustration processresponse.jpg

    Note: The user is allowed to proceed with the transaction in the first attempt even though the price value is $700. This is because as per the condition associated with the rule, Ignore Current Transaction in Count is set to True. This implies that the first time the user attempts a transaction with price greater than $500, the price value is ignored and the user is allowed to proceed with the transaction.

  4. Create another session for the same user to execute the second transaction within five minutes. Populate the following fields from the response body to the request body, and click Send:

    • cookieType:4: From the original create session response body copy the value of digitalCookie and paste it in the cookieType:4 request body.
    • cookieType:1: From the original create session response body copy the value of secureCookie and paste it in the cookieType:1 request body.

    Description of the illustration createsession2.jpg

  5. From the response body, copy the value of requestID in a text file. You will need this value to create a transaction.

  6. Do the following to create a second transaction for the user:

    • Replace the requestID with the value copied in the previous step.
    • Click Send.

    Description of the illustration createtransaction2.jpg

  7. From the response body, copy the value of transactionId, which is 6 in a text file. You will need this value in the next step where you will execute the rule.

    Description of the illustration transactionresponse2.jpg

  8. Process the rule for the second transaction by replacing the following values in the request body of the API call, and click Send:

    • transactionId: Specifies the value of second transaction ID created in the previous step, for instance, 6.
    • requestID: Specifies the value obtained while creating the second session in Step 5.

    Description of the illustration processrule2.jpg

  9. In the response body, the value of result is Block. As per the condition, if the price value is greater than $500 and the transaction count is greater than 1, then the user should be blocked. Notice, that the alert message is returned from the associated alert group:

    Description of the illustration processresponse2.jpg

Test the Working of the Rule by Updating the Condition

In this section, you will update the condition criteria, and test how the Credit Card Activity rule works when the user performs a transaction for the first time with a price value greater than $500. In this scenario, another user, testuser2, performs the transaction.

  1. Launch a browser and log in to the OARM Administration console. Specify your credentials and login.

  2. Click the Application Navigation hamburger menu in the top-left, and click Adaptive Risk Management. The Monitored User Activities page appears.

  3. On the Credit Card Activity tile, click the 1 Rules link. The User Activity Page appears.

    Description of the illustration creditcardactivityrule.jpg

  4. On the User Activity page, click the Edit icon against the rule.

    Description of the illustration useractivity.jpg

  5. In the Conditions section, update Ignore Current Transaction in Count to False, and click Save.

    Description of the illustration condition2.jpg

  6. In the Postman Collection, in Create Session, create another session for a new user, testuser2. Click Send:

    Description of the illustration createsession3.jpg

  7. From the response body, copy the value of requestID to a text file. You will need this value to create a transaction.

  8. Perform the following in Create transaction to create a transaction for the user:

    • Replace the requestID with the value copied in the previous step.
    • Click Send.

    Description of the illustration createtransaction3.jpg

  9. From the response body, copy the value of transactionId, which is 7, to a text file. You will need this value in the next step where you will execute the rule.

    Description of the illustration createtransaction3response.jpg

  10. Process the rule for this transaction by replacing the following values in the request body of the Process Rule API call. Click Send.

    • transactionId: Specifies the value of the transaction ID created in the previous step 9, for instance, 7.
    • requestID: Specifies the value obtained while creating the session in the earlier step.

    Description of the illustration processrule3.jpg

  11. In the response body, validate the value of result, which is Block. The user is not allowed to proceed with the transaction in the first attempt, because as per the condition, if the price value is greater than $500 in transaction count 1, then the user should be blocked.

    Description of the illustration processresponse3.jpg

Monitor the User Session

  1. Launch a new browser.

  2. Log in to the OARM Administration console. You are redirected to the OAM login page, as the console is protected by OAM OAuth. Specify your credentials and login.

  3. Click the Application Navigation hamburger menu in the top-left, and click Monitor User Sessions. The User Sessions dashboard appears. Click the Include Successful Sessions toggle button to display the list of successful and unsuccessful logins:

    Observe the following:

    • Information for testuser: The first transaction of the user is successful. When the user performs the second transaction, the user was blocked. Note that the Device ID, which is 85 is the same in both the transactions. This is because you copied the digitalCookie and secureCookie while performing this transaction. This enables you to monitor the device information of the user.
    • Information for testuser2 : The first transaction of the user was blocked.

  4. Click the link under Session ID for testuser2 created in Task 2, for instance 90. The User Sessions - 90 page appears. You will see the action is Block:

    Description of the illustration testusersession.jpg

Learn More

Feedback

To provide feedback on this tutorial, please contact idm_user_assistance_ww_grp@oracle.com

Acknowledgements

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.