2 API Integration

This chapter contains the guidelines to natively integrate the client portion of Adaptive Risk Manager Online solutions. In an API integration, the client application invokes the Adaptive Risk Manager Online APIs directly and manages the authentication and challenge flows.

Note:

Adaptive Strong Authenticator is not used in this integration; all of the related screens need coding into the client application using the API.

Oracle provides the APIs to fingerprint the devices, collect authentication/transaction logs, run security and business rules, and challenge the user by using Adaptive Risk Manager Online's KBA. Adaptive Risk Manager Online also provides the utility APIs to generate authentication pads like KeyPad, TextPad, and QuestionPad.

API integration of Adaptive Risk Manager Online provides various advantages--some of which are highlighted below:

Flexibility in managing and controlling the authentication process flow.
Ability to change the default user registration flow.
Capability to share session data between existing applications and the Adaptive Risk Manager Online application. For example, the existing login session ID can be passed on to Adaptive Risk Manager Online API calls.

This chapter contains the guidelines for integrating:

Only the Adaptive Risk Manager
Adaptive Risk Manager and KBA
Adaptive Risk Manager, KBA and Authentication devices
AuthentiPad (Keypad, PinPad, and other pads)
Customer Care API

2.1 Application (API) Integration

Adaptive Risk Manager Online's components are software- and hardware-independent when deployed in a stand-alone environment using the published Web services API over SOAP. Support is also available for native (Java/.NET) environments.

Basic familiarity with SOAP, Java, or .NET is the skill set requirement for integration.

API integration is available in two flavors:

SOAP Service
Native APIs
- SOAP Service wrapper (in Java or .NET)
- Static-linked libraries (in Java)

2.1.1 SOAP Services

Adaptive Risk Manager Online SOAP services consists of five major modules:

VCryptCommon contains the common APIs.
VCryptTracker contains the APIs for fingerprinting and collecting authentication and transaction logs.
VCryptAuth contains the APIs for accessing the Adaptive Strong Authenticator and KBA modules.
VCryptRulesEngine contains the APIs for running the rules.
VCryptCC contains the APIs for invoking customer-care-related requests.

Using direct SOAP services is preferred if the client does not want to include any of the Adaptive Risk Manager Online client jars or DLL within their application. However, to use the Adaptive Strong Authenticator functionality, native Java or .NET you must use the native Java or .NET integration.

2.1.2 Native API

The native API consists of a wrapper over the SOAP API that is published by the Adaptive Risk Manager Online Server and written in the client's native application language. The native APIs construct the SOAP bodies for the Adaptive Risk Manager Online request and also invoke the SOAP requests.

API integration can be done using the SOAP as the underlying mechanism or statically linking (available only for Java integration) the Adaptive Risk Manager Online jars.

2.1.2.1 Adaptive Risk Manager Online Native Client API - Web Services/ SOAP

The construction of SOAP bodies and the SOAP calls help in abstracting the SOAP WSDL and other Web Services related issues.

Using native API, which is preferred over making direct SOAP calls, has a lot of advantages. A few advantages are listed below:

The client library constructs the SOAP body and abstracts the SOAP nuances from the client application developer.
Changes to any SOAP API signature does not require any code change from the application developer.
Higher-level utility methods are available to extract parameters required by Adaptive Risk Manager Online directly from the HTTP Request and HTTP Session objects.
APIs for encoding and decoding of some fingerprint data are available in native integration.

API libraries are available in Java, .NET and C++. In the Web Service configuration, these libraries have utility methods which make direct SOAP calls. The option requires lightweight client libraries (jars or dll) to be added to the client library part.

Figure 2-1 Web Services/SOAP Integration

This illustration shows a Web Services/SOAP integration.

2.1.2.2 Adaptive Risk Manager Online Native Client API - Static Linking

Clients using Java have the option to choose static linking. In static linking, the API doesn't make SOAP calls, instead they statically call the Adaptive Risk Manager Online engine APIs. With the static linking option, the client must include the Adaptive Risk Manager Online server jars and configure appropriate properties.

Although this option may provide slightly better performance, it may not be suitable for all clients.

Advantages of static linking are

No SOAP calls; eliminates creating and tearing down of TCP/IP connections.
No network latencies.
Load balancer not required.

Disadvantages of static linking are

The client server/application server has to accommodate the extra resource required by the Adaptive Risk Manager Online engine.
The client server/application server may not be able to load balance the requests.

Figure 2-2 Static linking

This illustration illustrates static linking

2.2 Integration Options

Clients can integrate Adaptive Risk Manager in a relatively short time frame and have their site secure from most fraud attacks. Integrating only the Adaptive Risk Manager doesn't require any change to the user experience.

Note:

In this integration, Adaptive Strong Authenticator is not used.

2.2.1 Adaptive Risk Manager Only Scenario

A diagram of the Adaptive Risk Manager only scenario is shown below.

Figure 2-3 Adaptive Risk Manager Only Scenario

This is a diagram of the Adaptive Risk Manager only scenario

2.2.1.1 User/Password Page (S1.1)

The User/Password Page is the existing page currently used by the client. It contains the text box for both the username and password. There are no changes required for this page; however, the post from this page should display a transient (intermediate) refresh page.

Figure 2-4 Username/Password Page

This is an screen shot of a User/Password Page

2.2.1.2 Device Fingerprint Flow (F2)

This is the flow for fingerprinting the device.

Table 2-1 Device fingerprint Flow (F2) Reference APIs

Module	APIs
Server	VCryptTracker::updateLog()
Sample	handleJump.jsp and handleFlash.jsp

updateLog(): For information on updateLog(), the parameters, and how to use the parameters, refer to Chapter 4, "Native Integration Java."

handleJump.jsp:

sets the client's time zone
sets a secure cookie
sets the browserfingerprint, sets status to "pending"
calls the pre-auth rules. Expects an "allow" action to proceed, else "block" or "error" due to unrecognized action or server error
stores bharosaSession
forwards to password.jsp

handleFlash.jsp sets the flashCookie if browser is flash enabled

2.2.1.3 Validate User/ Passwd (CP1)

This is the client's existing process. The client invokes the local API to validate the user. The result of the authentication is passed on to the Adaptive Risk Manager Online Server.

Table 2-2 Validate User/ Passwd (CP1) Reference API

Module	API
Sample	handlePassword.jsp

handlePassword.jsp

retrieves the password from the pad
decodes the password
validates the user

2.2.1.4 Update Authentication Status (P5)

After validating the user password, the status is updated in the Adaptive Risk Manager.

Table 2-3 Update Authentication Status (P5) Reference APIs

Module	APIs
Sample	handlePassword.jsp
BharosaHelper	BharosaHelper::updateStatus()

handlePassword.jsp:

updates the status to "success" if user is valid, else to "invalid," "error," or "bad password"

2.2.1.5 Password Status (C1)

Based on the authentication status, the user is either taken to the retry page or to post authentication rule processing.

2.2.1.6 Post Authentication Rules (R3)

The post authentication rules are run after the user password is authenticated. The post authentication runtime contains security rules.

For example, common actions returned are

Allow: Allow the authentication.
Block: Block the user.
Challenge: Challenge is returned if the user has registered questions. The option may not be available for Adaptive Risk Manager Only deployments.

Table 2-4 Post Authentication Rules (R3) Reference APIs

Module	APIs
Server	VCryptRulesEngine::processRules()
Sample	handlePassword.jsp
BharosaHelper	BharosaHelper::runPostAuthRules()

processRules(): For information on processRules(), the parameters, and how to use the parameters, refer to Chapter 4, "Native Integration Java."

handlePassword.jsp

runs post-auth rules and one of the following actions:
- REGISTER_USER_OPTIONAL
- REGISTER_QUESTIONS
- REGISTER_USER
- CHALLENGE
- BLOCK
- ALLOW
- SYSTEM_ERROR
forwards to registerImageandPhrase during registration or challenge if the user is registered

2.2.1.7 Lock Out Page (S2)

The Lock Out Page is the page that the user is generally redirected to if he is blocked from authentication or if he is carrying out a transaction.

2.2.1.8 Landing or Splash Page (S3)

The Landing or Splash Page is the page where the user lands after a successful login.

2.2.2 Adaptive Risk Manager, Adaptive Strong Authenticator and KBA Scenario

This flow is a consolidation of the Adaptive Risk Manager, AuthentiPads and KBA solutions. The flows are determined by the rules that are run at different runtimes.

Note:

The flows with models suggested in this section are example scenarios; there are other models and rules and other scenarios available.

Figure 2-5 Adaptive Risk Manager, Adaptive Strong Authenticator and KBA Scenario

2.2.2.1 Username Page (S1)

When personalization (image and/or phrase) is used, the login page must be split into two pages. The username (login ID) is accepted from the first page and stored in the HTTP session. The username page is followed by a transient page for capturing the flash and secure cookies and for fingerprinting the device.

Figure 2-6 Username Page

This is a screen shot of the Username page

2.2.2.2 Device Fingerprint Flow (F2)

This is the flow for fingerprinting the device.

Table 2-5 Device Fingerprint Flow (F2) Reference APIs

Module	APIs
Server	VCryptTracker::updateLog()
Sample	handleJump.jsp and handleFlash.jsp

updateLog(): For information on updateLog(), the parameters, and how to use the parameters, refer to Chapter 4, "Native Integration Java."

handleJump.jsp:

sets the client's time zone
sets a secure cookie
sets the browserfingerprint, sets status to "pending"

handleFlash.jsp sets the flashCookie if browser is flash enabled

2.2.2.3 Pre Authentication Rules (R1)

Pre Authentication rules are run before the user is authenticated or shown his personal device and/or phrase.

The common actions are

Allow: Allow the authentication flow to proceed.
Block: Block the user.

Table 2-6 Pre Authentication Rules Reference APIs

Module	APIs
Server	VCryptRulesEngine::processRules()
Sample	handleJump.jsp
BharosaHelper	BharosaHelper::runPreAuthRules()

processRules(): For information on processRules(), the parameters, and how to use the parameters, refer to Chapter 4, "Native Integration Java."

handleJump.jsp:

calls the pre-auth rules. Expects an "allow" action to proceed, else "block" or "error" due to unrecognized action or server error
stores bharosaSession
forwards to password.jsp

2.2.2.4 Use AuthentiPad Rules (R2)

This runtime runs the rules for determining which AuthentiPad is used. If the user has not registered, the rule returns the Generic TextPad. If the user is registered with Adaptive Risk Manager Online, either the personalized TextPad or KeyPad action will be returned.

The common actions are

Generic TextPad: Use default generic TextPad.
TextPad: Use personalized TextPad with phrase.
KeyPad: Use personalized KeyPad with phrase.

Table 2-7 Use AuthentiPad Rules (R2) Reference APIs

Module	APIs
Server	VCryptRulesEngine::processRules()
Sample	password.jsp
BharosaHelper	BharosaHelper::getAuthentiPad()

processRules(): For information on processRules(), the parameters, and how to use the parameters, refer to Chapter 4, "Native Integration Java."

password.jsp:

invokes rules to identify user's pad type, else uses the default KeyPad
creates the pad, names it, and sets all initial background frames, buttons, and so on
invokes kbimage.jsp as configured in the bharosa_client.properties
forwards to handlePassword.jsp

2.2.2.5 Generate Non-Personalized TextPad (P2)

Generic TextPad and non-personalized TextPad are used for users who have not yet registered with Adaptive Risk Manager Online. A non-personalized textpad is shown below.

Figure 2-7 Non-Personalized TextPad

This is a screen shot of the Generic TextPad

Table 2-8 Generate Non-Personalized TextPad (P2) Reference APIs

Module	APIs
Server	VCryptAuth::getUserByLoginId()
Sample	Password.jsp
BharosaHelper	BharosaHelper:: createPersonalizedAuthentiPad () BharosaHelper::createAuthentiPad()
Client	AuthentiPad::getHTML()

getUserByLoginId(): For information on getUserByLoginId(), the parameters, and how to use the parameters, refer to Chapter 4, "Native Integration Java."

password.jsp:

invokes rules to identify user's pad type, else uses the default KeyPad
creates the pad, names it, and sets all initial background frames, buttons, and so on
invokes kbimage.jsp as configured in the bharosa_client.properties
forwards to handlePassword.jsp

2.2.2.6 Generate Personalized TextPad or KeyPad (P3)

A textpad and a keypad are shown below.

Figure 2-8 Personalized TextPad

This is a screen shot of the Personalized TextPad

Figure 2-9 Personalized KeyPad

This is a screenshot of the Personalized KeyPad

Personalized KeyPad or TextPad are similar to the Generic TextPad, except they use user-selected phrases and background images.

Table 2-9 Generate Personalized TextPad or KeyPad Reference APIs

Module	APIs
Server	VCryptAuth::getUserByLoginId()
Sample	password.jsp
BharosaHelper	BharosaHelper:: createPersonalizedAuthentiPad () BharosaHelper::createAuthentiPad()
Client	AuthentiPad::getHTML()

getUserByLoginId(): For information on getUserByLoginId(), the parameters, and how to use the parameters, refer to Chapter 4, "Native Integration Java."

password.jsp:

invokes rules to identify user's pad type, else uses the default KeyPad
creates the pad, names it, and sets all initial background frames, buttons, and so on
invokes kbimage.jsp as configured in the bharosa_client.properties
forwards to handlePassword.jsp

2.2.2.7 Display TextPad or KeyPad (S4 and S5)

The HTML snippet should be embedded in the password page. The HTML renders the TextPad or KeyPad using Javascript. There is a <img> tag, which makes a HTTP request to the server to get the TextPad or KeyPad image.

Table 2-10 Display TextPad or KeyPad Reference APIs

Module	APIs
Server	VCryptAuth::getUserByLoginId()
Sample	password.jsp kbimage.jsp
BharosaHelper	BharosaHelper:: createPersonalizedAuthentiPad () BharosaHelper::createAuthentiPad() BharosaHelper::imageToStream()
Client	AuthentiPad::getHTML() KeyPadUtil::encryptImageToStream()

getUserByLoginId(): For information on getUserByLoginId(), the parameters, and how to use the parameters, refer to Chapter 4, "Native Integration Java."

password.jsp:

invokes rules to identify user's pad type, else uses the default KeyPad
creates the pad, names it, and sets all initial background frames, buttons, and so on
invokes kbimage.jsp as configured in the bharosa_client.properties
forwards to handlePassword.jsp

kbimage.jsp is the page that outputs the authenticator

2.2.2.8 Decode AuthentiPad Input (P4)

The data entered by the user is decoded by the Adaptive Risk Manager Online Utility API. The decoded value is in raw text format. The AuthentiPad, which had been used to generate the image, is used during the decoding. It is recommended that it be saved in the HTTP Session. The AuthentiPad object is serializable and can be stored in the database or file system.

Table 2-11 Decode AuthentiPad Input Reference APIs

Module	APIs	Notes
Sample	handlePassword.jsp
BharosaHelper	BharosaHelper::decodePadInput()	This method removes the AuthentiPad object from the HTTP Session
Client	KeyPadUtil::decodeKeyPadCode

handlePassword.jsp

retrieves the password from the pad
decodes the password
validates the user

2.2.2.9 Validate User/ Passwd (CP1)

This is the client's existing process. The client invokes the local API to validate the user. The result of the authentication is passed on to the Adaptive Risk Manager Online Server.

Table 2-12 Validate User/Passwd Reference APIs

Module	APIs
Sample	handlePassword.jsp

handlePassword.jsp

retrieves the password from the pad
decodes the password
updates the status to "success" if user is valid, else to "invalid," "error," or "bad password"
runs post-auth rules and one of the following actions:
- REGISTER_USER_OPTIONAL
- REGISTER_QUESTIONS
- REGISTER_USER
- CHALLENGE
- BLOCK
- ALLOW
- SYSTEM_ERROR
forwards to registerImageandPhrase during registration or challenge if the user is registered

2.2.2.10 Update Authentication Status (P5)

After validating the user password, the status is updated in the Adaptive Risk Manager.

Table 2-13 Update Authentication Status Reference APIs

Module	APIs
Server	VCryptTracker::updateAuthStatus()
Sample	handlePassword.jsp
BharosaHelper	BharosaHelper::updateStatus()

updateAuthStatus(): For information on updateAuthStatus(), the parameters, and how to use the parameters, refer to Chapter 4, "Native Integration Java."

handlePassword.jsp

retrieves the password from the pad
decodes the password
validates the user
runs post-auth rules and one of the following actions:
- REGISTER_USER_OPTIONAL
- REGISTER_QUESTIONS
- REGISTER_USER
- CHALLENGE
- BLOCK
- ALLOW
- SYSTEM_ERROR
forwards to registerImageandPhrase during registration or challenge if the user is registered

2.2.2.11 Password Status (C1)

Based on the authentication status, the user is either taken to the retry page or to post authentication rule processing.

2.2.2.12 Post Authentication Rules (R3)

The post authentication rules are run after the user password is authenticated. The post authentication runtime contains security rules.

Some common actions returned are

Allow: Allow the authentication.
Block: Block the user.
Challenge: Challenge is returned if the user has registered questions. The option may not be available for Adaptive Risk Manager Only deployments.

Table 2-14 Post Authentication Rules Reference APIs

Module	APIs
Server	VCryptRulesEngine::processRules()
Sample	handlePassword.jsp
BharosaHelper	BharosaHelper::runPostAuthRules()

processRules(): For information on processRules(), the parameters, and how to use the parameters, refer to Chapter 4, "Native Integration Java."

handlePassword.jsp

run post-auth rules which might return one of the following actions:
- REGISTER_USER_OPTIONAL
- REGISTER_QUESTIONS
- REGISTER_USER
- CHALLENGE
- BLOCK
- ALLOW
- SYSTEM_ERROR
forwards to registerImageandPhrase during registration or challenge if the user is registered

2.2.2.13 Check Question Registration for User (C2)

If the user is already verified, it is not necessary to continue to Registration Required Rules.

2.2.2.14 Registration Required Rules (R4)

This runtime runs the rules for determining whether the user is asked to register. The registration requirement is based on the business and security requirements. The business requirement dictates whether the registration is mandatory or optional.

The common actions are

Register: Force the user to register.
Registration Optional: Make the registration optional for the user.
Skip Registration: Skip registration for this session.

Table 2-15 Registration Required Rules Reference APIs

Module	APIs
Server	VCryptRulesEngine::processRules()
Sample	password.jsp
BharosaHelper	BharosaHelper::getAuthentiPad()

processRules(): For information on processRules(), the parameters, and how to use the parameters, refer to Chapter 4, "Native Integration Java."

password.jsp:

invokes rules to identify user's pad type, else uses the default KeyPad
creates the pad, names it, and sets all initial background frames, buttons, and so on
invokes kbimage.jsp as configured in the bharosa_client.properties
forwards to handlePassword.jsp

2.2.2.15 Challenge (QuestionPad) (S6)

Challenge pad is similar to TextPad, only the question is embedded in the pad.

Figure 2-10 Question Pad

Table 2-16 Challenge Reference APIs

Module	APIs
Server	VCryptAuth::getSecretQuestions()
Sample	Challenge.jsp
BharosaHelper	BharosaHelper:: createPersonalizedAuthentiPad () BharosaHelper::createAuthentiPad()
Client	AuthentiPad::getHTML()

getSecretQuestions(): For information on getSecretQuestions(), the parameters, and how to use the parameters, refer to Chapter 4, "Native Integration Java."

Challenge.jsp

gets the question
gets the QuestionPad
displays the Question on the QuestionPad
submits user answer to handleChallenge.jsp

2.2.2.16 Check Challenge Question Answer (C3)

This step calls the server to validate whether the answer provided by the user is correct.

Table 2-17 Check Challenge Question Answer Reference APIs

Module	APIs
Server	VCryptAuth::authenticateQuestion() VCryptRulesEngine::processRules() VCryptTracker::updateAuthStatus()
Sample	handleChallenge.jsp
BharosaHelper	BharosaHelper:: validateAnswer()

Module

APIs

Server

VCryptAuth::authenticateQuestion()

VCryptRulesEngine::processRules()

VCryptTracker::updateAuthStatus()

Sample

handleChallenge.jsp

BharosaHelper

BharosaHelper:: validateAnswer()

authenticateQuestion(), processRules(), and updateAuthStatus(): For information on the APIs, the parameters, and how to use the parameters, refer to Chapter 4, "Native Integration Java."

handleChallenge.jsp

validates answer
if answer is "valid," updates status to "success" and forwards to success
else if answer is "invalid," runs Challenge Rules to determine what needs to be done

2.2.2.17 Run Challenge Rules (R5)

If the user fails to answer the question correctly, this runtime is invoked to determine whether the user is given another chance to answer the question or to block the user.

Common rule actions are

Challenge: Challenge the user again.
Block: Block the user.

Table 2-18 Run Challenge Rules Reference APIs

Module	APIs
Server	VCryptRulesEngine::processRules()
Sample	handleChallenge.jsp
BharosaHelper	BharosaHelper::validateAnswer()

processRules(): For information on processRules(), the parameters, and how to use the parameters, refer to Chapter 4, "Native Integration Java."

handleChallenge.jsp

validates answer
if answer is "valid," updates status to "success" and forwards to success
else if answer is "invalid," runs Challenge Rules to determine what needs to be done

2.2.2.18 Lock Out Page (S2)

The Lock Out Page is the page the user is generally redirected to if he is blocked from authentication or if he is carrying out a transaction.

2.2.2.19 Landing or Splash Page (S3)

The Landing or Splash Page is the page the user lands on after a successful login.

2.2.3 Adaptive Risk Manager and KBA Scenario

This scenario is the same as the previous scenario, except it doesn't have a split login flow and there are no personalizations or AuthentiPads.

Figure 2-11 Adaptive Risk Manager and KBA Scenario

2.3 Troubleshooting

This section describes the steps to take if you experience any problems with Adaptive Risk Manager after the integration.

Confirm that bharosa_properties is in the classes directory.
Confirm that you have customized bharosa_client.properties.
Make sure only one copy of the bharosa_client.properties appears in the classpath. If multiple property files are needed, ensure that they are all are identical.
Make sure the directory specified in log4j.xml for logfiles is present and write-accessible.
Update log4j.xml to different levels of logging for troubleshooting application issues.
Check the log levels in log4j.xml for recommended levels in case of space issues.