15 Integrating Client Applications with OAAM for Transactions

Oracle Adaptive Access Manager can evaluate the risk associated with a transaction in real-time to prevent fraud and misuse. Any user activity that requires monitoring after successfully logging in can be termed as a transaction.

This chapter covers the integration of native client applications with OAAM for the risk analysis of transactions. It includes the following sections:

• Transaction Example

• About the Transaction Flow

• High-Level Steps Required to Integrate Native Client Applications with OAAM

• OAAM Set Up and Configuration

• Client Setup

• Entity and Transaction APIs

• Run-time Data Analysis

• Targeted Purging of Transaction and Entity Data

15.1 Transaction Example

An example of a transaction is an e-commerce transaction in which the buyer purchases a book over the Internet. John Doe logs on to his laptop, accesses the "Bigbookemporium.com" Internet site and performs an electronic search. John selects the book he wants and Bigbookemporium.com displays the purchase price. When John is ready to check out, he pays for it by credit card by providing the following information:

• Amount of the transaction

• Credit card type

• Credit card number

• Credit card expiration date

• Buyer first and last name

• Buyer billing address

15.2 About the Transaction Flow

Figure 15-1 shows the transaction flow when the OAAM Server processes client transactions for risk. Numbers correspond to numbers in the figure.

Figure 15-1 Tradition Transaction Flow With OAAM Server Added

1. At your website, the customer submits a transaction.

2. You invoke the Create Transaction OAAM API along with transaction data to create a transaction in OAAM database.

   Note:

   The CreateTransaction API requires the Session ID to create a transaction. If you do not have a Session ID, you must call the CreateOAAMSession API to create a session before calling the CreateTransaction API.

3. The OAAM API returns the status of transaction creation to you.

4. Based on the business requirements, you invoke a Run Rules API to analyze the risk/fraud related to the customer transaction.

5. OAAM server returns the rules response that contains action(s) and score to you.

6. Based on the OAAM response, you decide on a corresponding action (Allow, Block, Challenge, and so on) and the website displays the result to the customer.

15.3 High-Level Steps Required to Integrate Native Client Applications with OAAM

The high-level steps required to integrate the native client applications with OAAM are as follows:

1. Identify the types of client transactions that need to be integrated with OAAM. Prepare a list of transaction specific attributes (data) that makes up the transaction. Refer to this as "Source" data or Client Data. For example, in an online transaction, the data involved may be credit cards, e-checks, debit cards, dollar amounts, name, shipping and billing addresses.

2. Design and develop the transaction and entity definitions in OAAM. The entities and transaction data elements are then mapped to the source data (client-specific data) so that the OAAM Server can process the information from the client application. For additional information on modeling a transaction in OAAM, see Oracle Fusion Middleware Administrator's Guide for Oracle Adaptive Access Manager.

3. Identify and determine the checkpoints required based on the types of transactions.

4. Define and configure the security policies and rules for risk evaluation that are specific to each of the transactions.

5. Write code in the client application to call OAAM APIs to create or update the transactions, evaluate risk, and also to receive specific responses from OAAM.

6. Test the integration and make sure it is working end-to-end.

7. For information on how the integration and risk evaluation work for different transactions and the usage of the transaction APIs, see the out-of-the-box OAAM Sample application.

   The OAAM sample application illustrates the Java API integration and can be downloaded with My Oracle Support article ID 1351899.1 titled OAAM 11g PS1 (11.1.1.5) Sample Application Download.

   You can access My Oracle Support at https://support.oracle.com.

15.4 OAAM Set Up and Configuration

This chapter includes the following topics:

• Set Up Transaction Definitions

• Set up Policies and Rules

• Sizing and Capacity Requirements

15.4.1 Set Up Transaction Definitions

In order for OAAM to perform risk analysis associated with the client transaction, you must determine how to represent the client transactions in OAAM, how to process the customer data collected by OAAM, and how to use it to prevent fraud and misuse. For example, in an eCommerce transaction, the data to process in the transaction might be credit card numbers, shipping and billing addresses, names, and dollar amounts; for a wire transfer, the important data might be Amount, Name, To account, From account, Routing Number, Bank Address, and Bank Phone. For information on entities, see Oracle Fusion Middleware Administrator's Guide for Oracle Adaptive Access Manager.

OAAM uses transaction definitions to represent client-specific transactions. Hence, the External transaction ID provided by the client should match with the transaction definition key in OAAM.

The transaction definition in OAAM consists of transaction parameters and entities. For information on creating and managing transaction definitions, see Oracle Fusion Middleware Administrator's Guide for Oracle Adaptive Access Manager

An entity structure is created by combining multiple related data points for optimization. The entity can be reused in multiple transactions by creating new instances of the entity. Entities are not associated with or dependent on any transactions.

For example, shipping address and billing address instances can be created for two different transactions from the Address entity. The address entity can include street number, street name, apartment number, city, state, postal code, and country as its data points.

In addition to creating instances, an entity can be also linked to other entities thus establishing a relationship or association between entities. The Customer entity can be linked to another entity like Address. The relationship between Customer and Address entities can be said to be one-to-one (1:1) because they have a one to one direct mapping. The Address entity is not dependent on the Customer and can reside by itself.

All data fields that cannot be combined to form entities should be added as transaction parameters. Typically these attributes are unique/specific and dependent on the current transaction.

For example:

Transaction Data

• Amount

• Item #

Entities

• Credit Card entity (which includes the data elements like Credit Card Number and Expiry Date)

• Customer (which includes the data elements like first name, last name, date of birth and so on)

15.4.2 Set up Policies and Rules

Oracle Adaptive Access Manager performs risk evaluation and fraud analysis on a client's transaction based on a set of policies and rules defined in OAAM. Follow these guidelines to set up policies and rules for transactions.

1. Determine if you can use any of the out-of-the-box OAAM checkpoints to define new policies for transactions. If an existing checkpoint can be reused, you will not need to create a checkpoint. Otherwise, create a new OAAM checkpoint. For information on creating checkpoints, see Chapter 26, "Creating Checkpoints and Final Actions."

2. Create an OAAM security policy and provide the following information.

   • Name

   • Status

   • Scoring Engine

   • Weight

   • Description

3. Add the rule to the policy. The rule must contain conditions specific to transactions. Provide the following information:

   • Rule Name

   • Status

   • Description

   • Condition

   • Results if the rule condition is satisfied.

     Link the Alert and Action groups and specify a score.

     For details on rule conditions, see Oracle Fusion Middleware Administrator's Guide for Oracle Adaptive Access Manager.

4. Activate the transaction definitions and policies for OAAM to perform risk evaluation.

   For information on configuring policies, see Oracle Fusion Middleware Administrator's Guide for Oracle Adaptive Access Manager.

15.4.3 Sizing and Capacity Requirements

For information on sizing and capacity requirements, see Oracle Fusion Middleware Performance and Tuning Guide.

This completes the setup and configuration in OAAM.

15.5 Client Setup

To integrate the client application with OAAM, proceed as follows:

1. Write custom client code using the APIs provided by OAAM to create and update transactions and run rules on the transactions. For information on OAAM APIs, see Chapter 4, "Natively Integrating OAAM with Java Applications."

2. Integrate the client application with OAAM using OAAM shared libraries, see Chapter 2, "Natively Integrating Oracle Adaptive Access Manager."

3. Update the client application so it can interpret the results from OAAM and take appropriate action in terms of redirecting the user to the relevant pages. For example, indicate that the user is not allowed to perform wire transfer, and others.

15.6 Entity and Transaction APIs

API	Task
createOAAMSession	Creates a login session.
createTransaction	Creates a transaction in OAAM
updateTransaction	Updates an existing OAAM transaction. Typically this is done based on outcome of processRules API.
processRules	Processes fraud rules
createOrUpdateEntities	Creates or updates entities without sending the full data with the transactions
searchEntityByKey	Searches entities based on its key attributes

15.6.1 Sequence of API Calls

This section shows how transactions are processed in OAAM and supplying the values for API operations from the client application.

• If a Session ID does not exist, call the CreateOAAMSession API to create a session containing the Session ID. The Session ID is required by the createTransaction API.

• Information is provided by the client application and the createTransaction API is called.

• Review to make sure the status of the createTransactionoperation is isSuccess() before obtaining the transaction ID with the method getTransactionResponse().

• Call the processRules API to trigger the fraud policies/rules associated to the Transaction checkpoint. This step results in triggering the rules engine that would execute the policies and rules associated to this checkpoint and creating alerts if the associated rules trigger. The output of this API is a set of actions and risk score as returned by the policies and rules.

• Based on the outcome of the processRules API call the client application can choose to call the updateTransaction API to set the transaction status or to update data in the existing transaction.

• In some cases, client applications can choose to execute a processRules API with a Post Transaction kind of checkpoint that has policies/rules that have to be executed after a transaction is created.

15.6.2 Out-of-the-Box Checkpoints

The Pre-Transaction and Post-Transaction checkpoints are described in this section.

15.6.2.1 Pre-Transaction Checkpoint

If a create transaction operation was successful, then you can call the processRules API to trigger the fraud policies/rules associated to the Pre-transaction checkpoint. This step results in triggering of the rules engine that would execute the policies and rules associated to this checkpoint and creating alerts if the associated rules trigger. The output is a set of actions and risk score as returned by the policies and rules.

15.6.2.2 Post - Transaction Checkpoint

If an update transaction operation was successful, then you can call the processRules API to trigger the fraud policies/rules associated to the Post-transaction checkpoint. This step results in triggering the rules engine that would execute the policies and rules associated to this checkpoint and creating alerts if the associated rules trigger. The output is a set of actions and risk score as returned by the policies and rules.

15.6.3 Entities API List

The two entities APIs are listed as follows.

15.6.3.1 create OrUpdateEntities

You can use the createOrUpdateEntities API to perform the following tasks:

• Create and update entities

• Replace and merge attribute values during an entity update

For more information, see Section 4.5.7, "createOrUpdateEntities."

15.6.3.2 SearchEntityByKey

You can use the searchEntityByKey API to find entities based on its key attributes. For more information on the API, see Section 4.5.27, "searchEntityByKey."

15.7 Run-time Data Analysis

OAAM provides tools for run-time data analysis of transactions.

15.7.1 Investigation Transaction Search, Comparison, and Utility Panel

OAAM provides several features for the fraud investigation of transactions, as described in the following table. For details on these investigation tools, see Oracle Fusion Middleware Administrator's Guide for Oracle Adaptive Access Manager.

Feature	Description
Transaction Search	Investigators can search for OAAM run-time data in a transaction-centric manner using the Sessions and Transactions search pages. For example, the investigator begins the investigation by searching for Retail Ecommerce transactions in the last 24 hours at a certain alert level.
Utility Panel	Investigators can use the Utility Panel to: Quickly locate sessions and transactions with data in common Iterate on a query to expand and contract returns Both view aggregate numbers of sessions and transactions found and drill in to expand investigation
Compare Transactions	Investigators can use the compare transactions feature to compare transactions side by side to find the matching data elements.

15.7.2 BIP Reports

OAAM provides the SearchTransactions report out-of-the-box for transactions. Table 15-0 shows the search filters for the SearchTransactions report.

Figure 15-2 BIP Report

You can also create and configure custom reports on the transaction data as needed. For information on building custom reports, see Section 24.2, "Building OAAM Transactions Reports."

15.8 Targeted Purging of Transaction and Entity Data

To specify a different retention period based on the transaction type or entity, refer to "Setting Up Targeted Purging for Entity Data" and "Setting Targeted Purging for Transaction Data Per Transaction Definition" in the Oracle Fusion Middleware Administrator's Guide for Oracle Adaptive Access Manager.