2 Natively Integrating with Oracle Adaptive Access Manager

Native application integration deployments embed the rules engine and user interface flows into the client application so the OAAM Administration Console, which contains the customer service and secure analyst case management functionality, is the only additional managed server added to the deployment. 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.

This chapter contains guidelines to integrate Oracle Adaptive Access Manager into a client application using the APIs the server exposes.

2.1 Overview

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.

2.1.1 What is Native Integration?

Native Oracle Adaptive Access Manager integration involves customizing your application to include OAAM API calls at various stages of the login process. In native integration, your application invokes Oracle Adaptive Access Manager directly and the application itself manages the authentication and challenge flows.

To integrate with Oracle Adaptive Access Manager, the application can use the native API. The native API options are:

  • SOAP service wrapper API for Java or .NET applications.

    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.

    Refer to "Using SOAP Service Wrapper API".

  • Link libraries statically for Java applications only

    This scenario only involves local API calls and therefore no remote server risk engine calls (SOAP calls).

    Refer to "Using the In-Proc Method".

2.1.2 Using SOAP Service Wrapper API

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

This integration requires adding lightweight client libraries (JARs or DLLs) to the client library. The application communicates with Oracle Adaptive Access Manager using Web services and the server API.

2.1.3 Using the In-Proc Method

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.

2.1.4 SOAP Service Wrapper API vs. In-Proc Method

When communicating with the rules engine, you have to decide whether to statically include all the .jar files locally in the application server, or to make SOAP calls to a distributed rules engine (typically located on the same host that administers the rules themselves).

Using SOAP Server Wrapper 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.

Even though In-Proc may provide slightly better performance, it is not suitable for all Java clients. In-Proc is recommended for clients developing their own applications with Oracle Adaptive Access Manager built in their J2EE or application.

In-Proc integration 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.1.5 Non-Native Integration - SOAP Services

Using direct SOAP services is preferred if the client does not want to include any of the OAAM client JAR or DLL files within their application. However, to use the adaptive strong authentication functionality, you must use the native Java or .NET integration.

OAAM 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 Authenticator and KBA modules.

  • VCryptRulesEngine contains the APIs for running the rules.

  • VCryptCC contains the APIs for invoking customer-care-related requests.

2.1.6 Sample Application as a Reference for Integration

A sample application is available for your reference. Before you integrate the APIs into your own application, be sure to download the sample application. The sample application illustrates how to call the product APIs. It is available as a form of documentation.

The sample application is not intended to be used as production code. For example, the sample application does not have proper error handling; it only provides basic elements of API usage. Customers implementing a native integration should develop their own application using the sample application as a reference only.

Note:

Custom applications developed for these deployments are not supported directly. However, Oracle Support Services can assist customers with product issues, such as if customers encounter problems when using the provided APIs.

2.1.6.1 Setting Up the Native SOAP based OAAM Sample Application

This section contains instructions to set up the Native SOAP based OAAM sample application.

2.1.6.1.1 Pre-requisites

Before you set up the SOAP based OAAM sample application you need:

  • Oracle Adaptive Access Manager to be installed, configured, and running

  • Oracle Adaptive Access Manager SOAP service to be enabled and reachable from the host where the sample application is being deployed

  • Details about the database host, username, password used by the Oracle Adaptive Access Manager

2.1.6.1.2 Installing and Configuring the Sample Application

To set up the SOAP based OAAM sample application:

  1. Create a oaam_sample folder.

  2. Extract oaam_sample_soap.zip into oaam_sample.

  3. Edit the bharosa_server.properties file under the <customer application deployment>/WEB-INF/classes directory:

    • Set the vcrypt.tracker.soap.url property.

      vcrypt.tracker.soap.url=http://<host-name>:<port>/oaam_server/services

      This setting is the location of the web services with which the application will communicate.

    • Set the soap class vcrypt.common.util.vcryptsoap.impl.classname property.

      This setting specifies for the application which libraries to use when creating SOAP messages to exchange with the OAAM services.

      The available option is:

      com.bharosa.vcrypt.common.impl.VCryptSOAPGenericImpl

    • Set bharosa.image.dirlist to the absolute folder path where OAAM images are available.

  4. Set the following properties:

    vcrypt.tracker.impl.classname=com.bharosa.vcrypt.tracker.impl.VCryptTrackerSOAPImpl
vcrypt.user.image.dirlist.property.name=bharosa.image.dirlist
bharosa.config.impl.classname=com.bharosa.common.util.BharosaConfigPropsImpl
bharosa.config.load.impl.classname=com.bharosa.common.util.BharosaConfigLoadPropsImpl
vcrypt.tracker.soap.useSOAPServer=true
vcrypt.soap.disable=false
vcrypt.soap.auth.keystoreFile=system_soap.keystore

    If SOAP Authentication is not enabled, set the following property:

    vcrypt.soap.auth=false

    If SOAP Authentication is enabled, set the following properties:

    vcrypt.soap.auth=true 
vcrypt.soap.auth.keystorePassword=Java-keystore-password
vcrypt.soap.auth.aliasPassword=Keystore-alias-password
vcrypt.soap.auth.username=SOAP-User-name

  5. If you are installing the sample application on the same WebLogic domain where OAAM Server is running then comment out the properties named bharosa.cipher.encryption.algorithm.enum related to encryption keys.

    If you are deploying on a non-WebLogic server or a non-IAM WebLogic domain then you have to create the keystores system_db.keystore and system_config.keystore and set the value for the following properties:

    bharosa.cipher.encryption.algorithm.enum.DESede_config.keystorePassword
bharosa.cipher.encryption.algorithm.enum.DESede_config.aliasPassword

  6. Update the sample application so it picks up the changes made to the bharosa_server.properties file. Navigate to the WebLogic Administration Console > Deployments > Summary of Deployments. Click Next to sample application and click the Update button. Click Finish.

  7. Start the managed server.

  8. Make changes to OAAM Web services security to allow access to the OAAM SOAP services. By default they are protected by OWSM (Oracle Web Services Manager). The steps are as follows:

    1. Log into Enterprise Manager of IDM domain using the URL http://weblogic-admin-hostname:port/em and WebLogic Administrator username/password.

    2. Locate oaam_server_server1 in the left hand side menu by expanding WebLogic Domain and the OAAM domain under it.

    3. Right-click oaam_server_server1 and select the Web Services menu option.

    4. Click Attach Policies in the top-right area of the page.

    5. Select all the rows related to OAAM Webservices in the next page and click the Next button.

    6. To enable SOAP Authentication select the row oracle/wss_http_token_service_policy and click the Next button.

      To disable SOAP Authentication, select the row oracle/no_authentication_service_policy and oracle/no_authorization_service_policy and click the Next button.

    7. Click the Attach button in the next page.

    8. Restart the OAAM Server if required.

  9. Navigate to the WebLogic Administration Console. Click Lock and Edit and select the Deployments node. On the Summary of Deployments page, find and select the sample application. Click Start > Servicing all requests. Click Yes to confirm.

  10. Log into the OAAM Admin application and import the snapshot.

  11. Navigate to the URL http://<host-name>:<port>/oaam_sample. You will see login page of sample application.

  12. Enter the user name and then password in the next page. You are taken through registration.

    Note:

    The password must be test for the initial log in. You must change the password immediately.

2.1.6.2 Setting Up the Native In-Proc Based OAAM Sample Application

This section contains instructions to set up the Native In-Proc based OAAM sample application.

2.1.6.2.1 Pre-requisites

Before you can set up the native In-Proc based OAAM sample application you need:

  • OAAM Admin to be installed, configured, and running

  • Oracle Adaptive Access Manager SOAP service to be enabled and reachable from the host where the sample application is being deployed

  • Details about the database host, username, password used by the Oracle Adaptive Access Manager

2.1.6.2.2 Install and Configure

To set up the Native In-Proc based OAAM sample application:

  1. Create the oaam_sample folder.

  2. Unzip oaam_sample_inproc.zip into oaam_sample.

  3. Start the WebLogic Server.

  4. Navigate to WebLogic Administration Console.

    http://<oaam_host>:<port>/console

  5. Deploy the OAAM Shared Library $MW_HOME\Oracle_IDM1\oaam\oaam_libs\war\oaam_native_lib.war as a shared library.

    1. Click Deployments under IAMDomain (in the navigation panel) in Summary of Deployments under the Control tab.

    2. Click the Install button. In the path specify $MW_HOME\Oracle_IDM1\oaam\oaam_libs\war and select oaam_native_lib.war. Click Next.

    3. Select Install this deployment as a library radio button. Click Next.

    4. In the Select Deployments targets page, select the managed server from the list of servers and click Next. Notice the name of the shared library is oracle.oaam.libs.

      If the managed server is OAAM Server then there is no need to create a OAAM Data Source. Otherwise create a Data source with JNDI name as jdbc/OAAM_SERVER_DB_DS and point it to the OAAM schema.

    5. Click Finish.

  6. Deploy the sample application as an application onto the same managed server where the OAAM Shared Library is deployed.

    1. Click Deployments under IAMDomain (in the left navigation panel) in Summary of Deployments under the Control tab.

    2. Click Install button. In the path, specify the location of the sample application. Click Next.

    3. Select Install this deployment as an application radio button. Click Next.

    4. In the Select Deployments targets page, select the managed server from the list of servers and click Next.

    5. Click Finish.

  7. Click Activate Changes under the Change Center.

  8. In the deployment descriptor file, set the reference to the OAAM shared library oracle.oaam.libs.

    To use the Oracle Adaptive Access Manager Shared Library in Web applications, you must refer to the shared library by adding the following entry to your WebLogic deployment descriptor file, weblogic.xml:

    <library-ref>
       <library-name>oracle.oaam.libs</library-name>
</library-ref>

    To use the Oracle Adaptive Access Manager Shared Library in Enterprise applications, you must refer to the shared library by adding the following entry to your WebLogic deployment descriptor file, weblogic-application.xml:

    <library-ref>
       <library-name>oracle.oaam.libs</library-name>
</library-ref>

  9. Start the managed server.

  10. Navigate to the WebLogic Administration Console. Click Lock and Edit and select the Deployments node. On the Summary of Deployments page, find and select the sample application. Click Start > Servicing all requests. Click Yes to confirm.

  11. Log into OAAM Admin application and import the snapshot.

  12. Navigate to the URL http://managed_server:port/oaam_sample. You will see login page of the sample application.

  13. Enter the user name and then password in the next page. You are taken through registration.

    Note:

    The password must be test for the initial log in. You must change the password immediately.

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-1 illustrates an authentication flow example that uses these three solutions (virtual authentication devices, knowledge-based authentication, One-Time Password). Note that the flow illustrated is an example and that other authentication flows are possible.

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

Figure 2-1 Virtual Authentication Devices, Knowledge-Based Authentication, and OTP Scenario

An example native integration flow is shown.

2.2.1.1 User Name Page (c1)

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-2 shows a sample of the first page.

Figure 2-2 User Name Page

This is a screen shot of the Username page

2.2.1.2 Device Fingerprint Flow (r2)

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()

APIs that construct the fingerprint are:

  • VCryptServletUtil.getBrowserFingerPrint(userAgent, language, country, variant);

  • VCryptServletUtil.getFlashFingerPrint(client, fpStr);

For method details on updateLog(), see Section 4.5.30, "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

Cookies in Device Identification

Oracle Adaptive Access Manager uses two types of cookies to perform device identification.

One is the browser cookie (also known as secure cookie) and the other is the flash cookie (also known as digital cookie).

The browser cookie value is constructed using the browser user agent string. The flash cookie value is constructed using data from the OAAM flash movie.

The following is sample code to fingerprint the device using browser and flash cookies. Refer to code in handleFlash.jsp for details:

//Get Browse/Secure cookie
String secureCookie = getCookie(request, "bharosa");
Locale locale = request.getLocale();
String browserFp = VCryptServletUtil.getBrowserFingerPrint(request.getHeader("user-agent"),
locale.getLanguage(),
locale.getCountry(), locale.getVariant());
 
 
 
String client = request.getParameter("client");
String fpStr = request.getParameter("fp");
String flashFp = bharosaHelper.constructFlashFingerPrint( client, fpStr );
 
//Get the flash cookie
String flashCookie = request.getParameter("v");
CookieSet cookieSet = bharosaHelper.fingerPrintFlash(bharosaSession, bharosaSession.getRemoteIPAddr(), request.getRemoteHost(),
BharosaEnumAuthStatus.PENDING, secureCookie, browserFp, flashCookie, flashFp);

2.2.1.3 Run 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.5.23, "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 Run Virtual Authentication Device Rules (r3)

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.5.23, "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.4.1 Generate a Generic TextPad (p1)

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

Figure 2-3 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 Generic TextPad APIs

Module APIs Description

Server

VCryptAuth::getUserByLoginId()

You can obtain an instance of VCryptAuth by calling VCryptAuthUtil.getVCryptAuthInstance().

For method details, see Section 4.5.17, "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.4.2 Generate a Personalized TextPad or KeyPad (p2)

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

Figure 2-4 Personalized TextPad

This is a screen shot of the Personalized TextPad

Figure 2-5 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.5.17, "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.4.3 Display TextPad and KeyPad (s2 and s3)

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.5 Decode Virtual Authentication Device Input (p3)

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 serialized and stored in the database or the file system.

The virtual authentication device is stored in session because it is used to decode the input. This is needed for virtual authentication devices like PinPad and KeyPad where the user input is not clear text. For consistency it is performed for all virtual authentication devices since they are designed to be able to be used interchangeably.

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.6 Validate User and Password (c2)

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 OAAM 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.6.1 Update Authentication Status (p4)

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.5.29, "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.6.2 Password Status (c3)

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

2.2.1.7 Run Post-Authentication Rules (r4)

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.

The APIs used for post-authentication are 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.5.23, "processRules."

Oracle Adaptive Access Manager Sample

handlePassword.jsp

Calls BharosaHelper::runPostAuthRules which returns:

ALLOW

BLOCK

CHALLENGE

If ALLOW:

BharosaHelper::runRegistrationRules

returns

ALLOW

REGISTER_QUESTIONS

REGISTER_USER_INFO

REGISTER_USER

SYSTEM_ERROR

If CHALLENGE:

forward_challengePage

BharosaHelper

BharosaHelper::runPostAuthRules()

  

2.2.1.8 Check Registration for User (p5)

Rules are run to check registration; if the user is not registered, he is directed to do so.

2.2.1.9 Run Registration Required Rules (r5)

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.5.23, "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.10 Enter Registration Flow (p6)

The Registration Flow allows you to register a new image and caption, questions, and so on as described in the table below:

Table 2-12 Registration Flow

Module APIs Description

Server

VCryptRulesEngine::processRules()

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

Oracle Adaptive Access Manager Sample

registerImagePhrase.jsp

Assigns new image and caption to user

Assigns new image and caption to user

Forwards to page handleRegisterImagePhrase.jsp
 

registerQuestions.jsp

Gets question pick set for the user

Displays question selection user interface and inputs for answers

Forwards to page handleRegisterQuestions.jsp
 

registerContactInfo.jsp

Presents user with inputs for OTP registration information

Forwards to page handleRegisterContactInfo.jsp

BharosaHelper

BharosaHelper::getAuthentiPad()

BharosaHelper::createSampleAuthentiPad

BharosaHelper::assignRandomImageAndCaption

BharosaHelper::saveNewImageAndOrCaption

BharosaHelper::getQuestions

BharosaHelper::isDeviceRegistered

BharosaHelper::setContactInfo

  

2.2.1.11 Run Challenge Rules (r6)

The challenge rules are invoked to determine which type of challenge to display to the user. Values returned by the challenge rules include the following:

  • ChallengeQuestion to challenge the user with question.

  • ChallengeSMS to challenge user with OTP via SMS, to challenge user with OTP

  • ChallengeEmail to challenge user with OTP via email

  • Block to block the user.

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

Table 2-13 Run Challenge Rules APIs

Module APIs Description

Server

VCryptRulesEngine::processRules()

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

Oracle Adaptive Access Manager Sample

handleChallenge.jsp

handleChallenge.jsp calls BharosaHelper::validateAnswer

If that method returns BharosaEnumChallengeResult.SUCCESS, status is updated to "success" and the user is allowed to move forward; otherwise if BharosaEnumChallengeResult.WRONG_ANSWER is returned then challenge rules are run again to determine the next step.

BharosaHelper

BharosaHelper::validateAnswer()

  

2.2.1.12 Run Authentication Rules (r7)

BharosaHelper::getAuthentiPad is used to create an authentication device. That method in turn calls the Authentication Device Rules to determine the device to use.

If the user is to be challenged with a question, the rule returns the QuestionPad. If the user is to be challenge with an OTP, the rule returns the TextPad.

2.2.1.13 Challenge the User (p7)

If appropriate, the user is challenged with either Knowledge Based Authentication (KBA) or OTP (One Time Password).

KBA is an extension to existing User ID/password authentication and secures an application using a challenge/response process where users are challenged with questions. The user must answer the question correctly to proceed with his requested sign-on, transaction, service, and so on.

OTP is an extension to existing User ID/password authentication as well and adds an extra security layer to protect applications. OTP is generated after verifying the user ID and password and then delivered to users via e-mail or mobile phone if the application deems it to be necessary. Users then use the OTP to sign-in to the application.

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

Table 2-14 Challenge User APIs

Module APIs Description

Server

VCryptAuth::getSecretQuestion()

VCryptTracker::generateOTP()

  

Oracle Adaptive Access Manager Sample

Challenge.jsp

Determine type of challenge to use. BharosaHelper::runChallengeRules

If challenge type returned is KBA (ChallengeQuestion) then get user question with VCryptAuth:getUserQuestion

If challenge type is OTP (ChallengeSMS, ChallengeEmail, ...) then generate, store, and send OTP code.

  • BharosaHelper::generateOTP

  • BharosaHelper::sendCode

Use authentication pad rules to determine authentipad to display to the user. See Section 2.2.1.4, "Run Virtual Authentication Device Rules (r3).".

Submits the answer to handleChallenge.jps

handleChallenge.jsp collects user input and calls BharosaHelper::validateAnswer - used to validate user answer for challenge (same as question challenge)

BharosaHelper

BharosaHelper:: createPersonalizedAuthentiPad ()

BharosaHelper::createAuthentiPad()

BharosaHelper::generateOTP

BharosaHelper::sendCode

BharosaHelper::getUserQuestion

  

Client

AuthentiPad::getHTML()

  

2.2.1.14 Check Answers to Challenge (c4)

This stage involves validating the user's input to the challenge:

  • For KBA, calling Oracle Adaptive Access Manager Server to determine whether the answer the user has supplied matches the registered reply.

  • For OTP, validating the entered value to the OTP generated and sent to the user.

Table 2-15 lists the APIs used to validate a challenge.

Table 2-15 Validate Answer to a Challenge

Module APIs Description

Server

VCryptAuth::authenticateQuestion()

VCryptRulesEngine::processRules()

VCryptTracker::updateAuthStatus()

For method details, see Section 4.5.23, "processRules," and Section 4.5.29, "updateAuthStatus."

Oracle Adaptive Access Manager Sample

handleChallenge.jsp

Calls BharosaHelper::validateAnswer

If that method returns BharosaEnumChallengeResult.SUCCESS, status is updated to "success" and the user is allowed to move forward; otherwise if BharosaEnumChallengeResult.WRONG_ANSWER is returned then challenge rules are run again to determine the next step.

BharosaHelper

BharosaHelper:: validateAnswer()

If the type of challenge being validated is KBA (ChallengeQuestion), then VCryptAuth::authenticateQuestion is called to validate the users input against the registered answer for the question presented.

If the type of challenge being validated is OTP (ChallengeSMS, ChallengeEmail, and so on), then the users input is compared to the value stored when OTP code was generated. If the answer is correct, the OTP challenge counter is reset by calling BharosaHelper::resetOTPCounter. Otherwise if the answer is incorrect, the OTP challenge counter is incremented (BharosaHelper::incrementOTPCounter).

Method returns a BharosaEnumAuthStatus of either BharosaEnumAuthStatus.SUCCESS or BharosaEnumAuthStatus.WRONG_ANSWER

2.2.1.15 Lock Out Page (c6)

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

2.2.1.16 Landing or Splash Page (c5)

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.

2.2.2.1 User/Password (S1)

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.

2.2.2.2 Stages

For information on the other stages, see the following sections: