2 Natively Integrating with Oracle Adaptive Access Manager

Oracle Adaptive Access Manager provides APIs to fingerprint devices, collect authentication and transaction logs, run security rules, challenge the user to answer pre-registered questions correctly, and generate virtual authentication devices such as KeyPad, TextPad, or QuestionPad.

In native integration, the application invokes Oracle Adaptive Access Manager directly and the application itself manages the authentication and challenge flows.

Using the Oracle Adaptive Access Manager APIs, you can:

This chapter contains guidelines to integrate a client application with Oracle Adaptive Access Manager using the APIs the server exposes. The typical process flows for the authentication and challenge scenarios are presented in this chapter. Within these flow sections, there are details about which API should be called at each stage.

The integration options are presented in the following sections:

2.1 Overview

To integrate with Oracle Adaptive Access Manager, the application uses the native API.

You can choose one of the following native API options:

2.1.1 Using Web Services and SOAP API

In this scenario, the application communicates with Oracle Adaptive Access Manager using the Oracle Adaptive Access Manager native client API (SOAP service wrapper API) or via Web services.

The SOAP service wrapper API enables you to create SOAP objects and invoke SOAP calls and abstracts the SOAP WSDL and other Web services details from the application code. Libraries for this API are available for the following languages: Java, .NET, and C++.

Using this API is recommended over making direct SOAP calls. The reasons are as follows:

  • The client library constructs the SOAP objects, and the details involved in SOAP calls is abstracted from the client application.

  • A SOAP API signature change does not require any change in the client code.

  • The API provides higher-level utility methods to extract parameters directly from the HTTP request and HTTP session objects.

  • It provides methods to encode and decode fingerprint data.

This integration requires adding lightweight client libraries (JARs or DLLs) to the client library.

Figure 2-1 illustrates how an application communicates with Oracle Adaptive Access Manager using Web services and the server API.

Figure 2-1 Client Application Using Web Services and Server API

OAAM-application communication is shown.

2.1.2 Using Static Linking

Java applications can be static-linked. This scenario only involves local API calls and therefore no remote server risk engine calls (SOAP calls). The integration imbeds the processing engine for Oracle Adaptive Access Manager with the application and enables it to leverage the underlying database directly for processing. In this scenario, the application must include the server JARs and configured properties, as appropriate.

Even though static linking may provide slightly better performance, it is not suitable for all Java clients.

Static linking is recommended for clients developing their own applications with Oracle Adaptive Access Manager built in their J2EE or application.

Static-linking an application has several advantages:

  • The application makes no SOAP calls, thus eliminating the need to create and delete TCP/IP connections.

  • It experiences no network latencies.

  • It does not require a load balancer.

2.2 Integration Options

This section describes the following integration options:

2.2.1 Integrating with Virtual Authentication Devices and Knowledge-Based Authentication

This integration consolidates virtual authentication devices and knowledge-based authentication.

Globalized virtual authentication device image files including registration flows must be developed by the deployment team.

Figure 2-2 illustrates an authentication flow example that uses these two solutions (virtual authentication devices and knowledge-based authentication). Note that the flow illustrated is an example and that other authentication flows are possible.

Figure 2-2 Virtual Authentication Devices and Knowledge-Based Authentication Scenario

ARM, ASA and KBA Scenario
The legend for diagrams is shown.

The details of the stages in the Figure 2-2 are explained in the following sections:

2.2.1.1 User Name Page (S1)

When the application uses a custom login page, the login page must be split into two pages. The user inputs the login ID (user name) in the first page, and this data is stored in the HTTP session. The second login page is a transient page to capture the flash and secure cookies and for fingerprinting the user device. Figure 2-3 shows a sample of the first page.

Figure 2-3 User Name Page

This is a screen shot of the Username page

2.2.1.2 Device Fingerprint Flow (F2)

The device fingerprint stage involves fingerprinting the user device. The APIs used for this purpose are detailed in Table 2-1.

Table 2-1 Device Fingerprinting APIs

Module APIs Description

Server

VCryptTracker::updateLog()

For method details, see Section 4.3.6, "updateLog."

Oracle Adaptive Access Manager Sample

handleJump.jsp

Sets the client's time zone

Sets a secure cookie

Sets the browser fingerprint

Sets the status to pending

Calls the pre-authentication rules; expects "allow" to allow the user to proceed or "block" or "error" to stop the user from continuing

Stores bharosaSession

Forwards the user to the password.jps page

Oracle Adaptive Access Manager Sample

handleFlash.jsp

Sets the flashCookie if the browser is flash-enabled

2.2.1.3 Running Pre-Authentication Rules (R1)

Pre-authentication rules are run before the user is authenticated. Common values returned by the pre-authentication checkpoint include:

  • Allow to allow the user to proceed forward.

  • Block to block the user from proceeding forward.

The APIs used for pre-authentication are listed in Table 2-2.

Table 2-2 Pre-Authentication Rules Reference APIs

Module APIs Description

Server

VCryptRulesEngine::processRules()

For method details, see Section 4.4.1, "processRules."

Oracle Adaptive Access Manager Sample

handleJump.jsp

Invokes the pre-authentication rules; returns "allow" to proceed forward to password.jsp or "block" or "error" to signal an error

Stores bharosaSession

BharosaHelper

BharosaHelper::runPreAuthRules()

  

2.2.1.4 Running Virtual Authentication Device Rules (R2)

This stage determines the virtual authentication device to use. If the user has not registered an image and a phrase, the rule returns the Generic TextPad; otherwise, if the user has registered, the rule returns either the personalized TextPad or KeyPad. Common values returned by virtual authentication devices include:

  • Generic TextPad, to use the default generic TextPad.

  • TextPad, to use a personalized TextPad.

  • KeyPad, to use a personalized KeyPad.

The APIs used to run virtual authentication device rules are listed inTable 2-3.

Table 2-3 Virtual Authentication Device Rules APIs

Module APIs Description

Server

VCryptRulesEngine::processRules()

For method details, see Section 4.4.1, "processRules."

Oracle Adaptive Access Manager Sample

password.jsp

Invokes rules to identify the user's virtual authentication device type

Creates the virtual authentication device, names it, and sets all initial background frames

Invokes kbimage.jsp as configured

Forwards to page handlePassword.jsp

BharosaHelper

BharosaHelper::getAuthentiPad()

  

2.2.1.5 Generating a Generic TextPad (P2)

A generic, non-personalized TextPad is used for users who have not yet registered with Oracle Adaptive Access Manager. Figure 2-4 illustrates a generic TextPad.

Figure 2-4 Generic, Non-Personalized TextPad

This is a screen shot of the Generic TextPad

Table 2-4 lists the APIs used to generate a generic TextPad.

Table 2-4 Generation of a GenericTextPad APIs

Module APIs Description

Server

VCryptAuth::getUserByLoginId()

For method details, see Section 4.3.7, "getUserByLoginId."

Oracle Adaptive Access Manager Sample

Password.jsp

Invokes rules to identify the virtual authentication device type to use; the default is KeyPad

Creates the virtual authentication device, names it, and sets all initial background frames

Invokes kbimage.jsp as configured

Forwards to page handlePassword.jsp

BharosaHelper

BharosaHelper:: createPersonalizedAuthentiPad ()

BharosaHelper::createAuthentiPad()

  

Client

AuthentiPad::getHTML()

  

2.2.1.6 Generating a Personalized TextPad or KeyPad (P3)

A personalized TextPad is used for users who have registered with Oracle Adaptive Access Manager. Figure 2-5 andFigure 2-6 illustrate personalized text and key virtual authentication devices.

Figure 2-5 Personalized TextPad

This is a screen shot of the Personalized TextPad

Figure 2-6 Personalized KeyPad

This is a screenshot of the Personalized KeyPad

Table 2-5 lists the APIs used to generate a personalized TextPad or KeyPad.

Table 2-5 Generating a Personalized TextPad or KeyPad APIs

Module APIs Description

Server

VCryptAuth::getUserByLoginId()

For method details, see Section 4.3.7, "getUserByLoginId."

Oracle Adaptive Access Manager Sample

password.jsp

Invokes rules to identify the virtual authentication device type to use; the default is KeyPad

Creates the virtual authentication device, names it, and sets all initial background frames

Forwards to page handlePassword.jsp

Invokes kbimage.jsp as configured

BharosaHelper

BharosaHelper:: createPersonalizedAuthentiPad ()

BharosaHelper::createAuthentiPad()

  

Client

AuthentiPad::getHTML()

  

2.2.1.7 Displaying TextPad and KeyPad (S4 and S5)

The HTML code example to display TextPad and KeyPad should be embedded in the password page. This HTML renders the TextPad or KeyPad using Javascript, and it includes an <img> tag, which makes a HTTP request to the server to get the TextPad or KeyPad image.

Table 2-6 lists the APIs used to display TextPad and KeyPad.

Table 2-6 Displaying TextPad and KeyPad APIs

Module APIs Description

Server

VCryptAuth::getUserByLoginId()

  

Oracle Adaptive Access Manager Sample

password.jsp

Invokes rules to identify the virtual authentication device type to use; the default is KeyPad

Creates the virtual authentication device, names it, and sets all initial background frames

Invokes kbimage.jsp as configured

Forwards to page handlePassword.jsp

Oracle Adaptive Access Manager Sample

kbimage.jsp

Outputs the virtual authentication device(s)

BharosaHelper

BharosaHelper:: createPersonalizedAuthentiPad ()

BharosaHelper::createAuthentiPad()

BharosaHelper::imageToStream()

  

Client

AuthentiPad::getHTML()

KeyPadUtil::encryptImageToStream()

  

2.2.1.8 Decoding Virtual Authentication Device Input (P4)

In this stage, the chosen virtual authentication device decodes the data the user supplies to it; the decoded value is in raw text format, and it is recommended that it be saved in the HTTP Session. The Virtual Authentication Device object is can be serialized and stored in the database or the file system.

Table 2-7 lists the APIs used to decode user input.

Table 2-7 Decoding Virtual Authentication Device Input APIs

Module APIs Description

Oracle Adaptive Access Manager Sample

handlePassword.jsp

Retrieves the password

Decodes the password

Validates the user

BharosaHelper

BharosaHelper::decodePadInput()

Removes the Virtual Authentication Device object from the HTTP Session

Client

KeyPadUtil::decodeKeyPadCode

  

2.2.1.9 Validate User and Password (CP1)

This stage represents the client's existing process in which the client invokes the local API to authenticate the user, and the authentication result is passed on to Oracle Adaptive Access Manager Server. The API used is detailed in Table 2-8.

Table 2-8 Validating User and Password API

Module API Description

Oracle Adaptive Access Manager Sample

handlePassword.jsp

Retrieves the password

Decodes the password

Updates the status to "success" (if user is valid), or to "invalid," "error," or "bad password" (if the user is invalid)

Runs post-authentication rules and returns one of the following values:

REGISTER_USER_OPTIONAL

REGISTER_QUESTIONS

REGISTER_USER

CHALLENGE

2.2.1.10 Update Authentication Status (P5)

After validating the user password, the status is updated with the APIs detailed in Table 2-9.

Table 2-9 Updating Authentication Status APIs

Module APIs Description

Server

VCryptTracker::updateAuthStatus()

For method details, see Section 4.3.8, "updateAuthStatus."

Oracle Adaptive Access Manager Sample

handlePassword.jsp

Retrieves the password

Decodes the password

Validates the user

Forwards to registerImageandPhrase, or challenges a registered user

BharosaHelper

BharosaHelper::updateStatus()

  

2.2.1.11 Password Status (C1)

Depending on the password authentication status, the user is directed to the retry page or to post-authentication.

2.2.1.12 Post-Authentication Rules (R3)

These rules are run after the user password has been authenticated. Common actions returned by post-authentication include:

  • Allow, to allow the user to proceed forward.

  • Block, to block the user from proceeding forward.

  • Challenge, to challenge the user, if he has registered questions.

The APIs used for post-authentication is listed in Table 2-10.

Table 2-10 Post-Authentication Rules Reference APIs

Module APIs Description

Server

VCryptRulesEngine::processRules()

For method details, see Section 4.4.1, "processRules."

Oracle Adaptive Access Manager Sample

handlePassword.jsp

Runs post-authentication rules and returns one of the following values:

REGISTER_USER_OPTIONAL

REGISTER_QUESTIONS

REGISTER_USER

CHALLENGE

BLOCK

ALLOW

SYSTEM_ERROR

Forwards to registerImageandPhrase, or challenges a registered user

BharosaHelper

BharosaHelper::runPostAuthRules()

  

2.2.1.13 Check Question Registration for User (C2)

This stage checks whether the user is registered; if he is not registered, the user is directed to do so.

2.2.1.14 Registration Required Rules (R4)

The registration is required depending on business and security requirements, which specify whether the registration is mandatory or optional. Values returned by registration rules include the following:

  • Register, to require user registration.

  • Registration Optional, to make user registration optional.

  • Skip Registration, to skip registration for this session.

Table 2-11 lists the APIs used to run registration rules.

Table 2-11 Registration Required Rules Reference APIs

Module APIs Description

Server

VCryptRulesEngine::processRules()

For method details, see Section 4.4.1, "processRules."

Oracle Adaptive Access Manager Sample

password.jsp

Invokes rules to identify the virtual authentication device type to use; the default is KeyPad

Creates the virtual authentication device, names it, and sets all initial background frames

Invokes kbimage.jsp as configured

Forwards to page handlePassword.jsp

BharosaHelper

BharosaHelper::getAuthentiPad()

  

2.2.1.15 Challenging the User with QuestionPad (S6)

If appropriate, the user is challenged to answer a registered question. Table 2-11 illustrates a QuestionPad where a challenge question is displayed.

Figure 2-7 Question Pad

This is a screenshot of a QuestionPad.

Table 2-12 lists the APIs to challenge the user with registered questions.

Table 2-12 Challenge User APIs

Module APIs Description

Server

VCryptAuth::getSecretQuestions()

  

Oracle Adaptive Access Manager Sample

Challenge.jsp

Gets the question

Gets the QuestionPad

Displays the question in the virtual authentication device

Submits the answer to handleChallenge.jps

BharosaHelper

BharosaHelper:: createPersonalizedAuthentiPad ()

BharosaHelper::createAuthentiPad()

  

Client

AuthentiPad::getHTML()

  

2.2.1.16 Checking Answers to Challenge Questions (C3)

This stage involves calling Oracle Adaptive Access Manager Server to determine whether the answer the user has supplied matches the registered reply.

Table 2-13 lists the APIs used to validate answers to a challenged question.

Table 2-13 Validate Answer to a Challenge Question APIs

Module APIs Description

Server

VCryptAuth::authenticateQuestion()

VCryptRulesEngine::processRules()

VCryptTracker::updateAuthStatus()

For method details, see Section 4.4.1, "processRules," and Section 4.3.8, "updateAuthStatus."

Oracle Adaptive Access Manager Sample

handleChallenge.jsp

Validates the user

If valid, updates the status to "success" and allows the user to move forward; otherwise, if invalid, runs Challenge Rules to determine what should be done

BharosaHelper

BharosaHelper:: validateAnswer()

  

2.2.1.17 Run Challenge Rules (R5)

If the user fails to answer a challenge question correctly, the challenge rules is invoked to determine whether the user should be given another chance to answer the question or to block him from proceeding forward. Values returned by the challenge rules include the following:

  • Challenge, to challenge the user one more time.

  • Block, to block the user.

Table 2-14 lists the APIs used to run the challenge rules.

Table 2-14 Run Challenge Rules APIs

Module APIs Description

Server

VCryptRulesEngine::processRules()

For method details, see Section 4.4.1, "processRules."

Oracle Adaptive Access Manager Sample

handleChallenge.jsp

Validates the user

If valid, updates the status to "success" and allows the user to move forward; otherwise, if invalid, runs Challenge Rules to determine what should be done

BharosaHelper

BharosaHelper::validateAnswer()

  

2.2.1.18 Lock Out Page (S2)

The Lock Out page is the page to which the user is redirected when the post-authorization rules return Block.

2.2.1.19 Landing or Splash Page (S3)

This page is the page to which the user is redirected after a successful login, that is, when the post-authorization rules return Allow.

2.2.2 Integrating with Knowledge-Based Authentication

This scenario is a subset of the scenario described in Section 2.2.1, "Integrating with Virtual Authentication Devices and Knowledge-Based Authentication." This scenario does not have a split login flow and does not include personalizations or virtual authentication devices.

Figure 2-8 illustrates a flow of authentication that uses this solution. For details about the stages of this flow, see the following sections:

Figure 2-8 Knowledge-Based Authentication Scenario

Adaptive Risk Manager and KBA Scenario
The legend for diagrams is shown.