2 Natively Integrating Oracle Adaptive Access Manager

Oracle Adaptive Access Manager can be natively integrated with an application to provide high performance and highly customizable security. A native in-proc integration embeds OAAM in-process inside the protected applications. The application invokes the Oracle Adaptive Access Manager APIs directly to access risk and challenge flows. A SOAP integration involves inclusion of the OAAM SOAP client library (Java/.Net wrapper to invoke SOAP APIs) to have communication with OAAM Server for device fingerprinting, risk evaluation, and KBA related activities.

This chapter contains guidelines to integrate Oracle Adaptive Access Manager into a client application using the APIs the server exposes. In addition to this Developer's Guide, API documentation generated by the Javadoc tool is available. This documentation is provided as HTML and can also be downloaded from the Identity Management Documentation library in HTML format as Oracle Fusion Middleware Java API Reference for Oracle Adaptive Access Manager.

This chapter contains the following sections:

About OAAM Native Integration
Getting Started
Integrating Virtual Authentication Devices, Knowledge-Based Authentication, and One-Time Password

2.1 About OAAM Native Integration

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, challenge the user to provide a one-time password, and generate virtual authentication devices such as KeyPad, TextPad, or QuestionPad.

2.1.1 What is Native Integration?

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

The Native API options are:

SOAP service wrapper API for Java or .NET applications
In-Proc (link libraries statically) for Java applications only

2.1.2 SOAP Service Wrapper API Integration

Figure 2-1 shows the SOAP service wrapper API integration scenario in which the application communicates with Oracle Adaptive Access Manager using the OAAM Native Client API (SOAP service wrapper API). The application can also communicate with OAAM through Web services.

Figure 2-1 SOAP Service Wrapper API integration Scenario

Description of "Figure 2-1 SOAP Service Wrapper API integration Scenario"

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 Java, .NET, and C++. This integration requires adding lightweight client libraries (JAR or DLL files) to the client library.

2.1.3 In-Proc Integration

Figure 2-2 shows the In-Proc integration scenario which only involves local API calls and therefore no remote server risk engine calls (SOAP calls).

Figure 2-2 In-Proc integration Scenario Using Local API Calls

Description of "Figure 2-2 In-Proc integration Scenario Using Local API 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 JAR files and configured properties, as appropriate.

Note:

In-Proc integration works only on the WebLogic container where OAAM resides.

2.1.4 SOAP Service Wrapper API vs. In-Proc Method

When communicating with the rules engine, you must 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 the 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 are 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.2 Getting Started

Instructions for setting up the OAAM Sample application are provided in this section. The OAAM Sample application is for demonstration purposes to familiarize you with OAAM APIs. It is not intended to be used as production code since it only provides basic elements of API usage. If you are implementing a native integration, you can develop your application using the OAAM Sample application as a reference. Custom applications developed for these deployments are not supported directly; however, Oracle Support Services can assist you with product issues, such as if you were to encounter problems when using the provided APIs.

2.2.1 Downloading the OAAM Sample Application

The 11.1.2.x OAAM Sample application that illustrates API integration can be downloaded from My Oracle Support document ID 1542025.1.

Note:

This OAAM sample application is different from the one for the task processor framework. Use either OAAM sample applications, but the two may not be deployed together.

If you are interested in task processor integration, see Chapter 21, "Developing Web Applications to Leverage OAAM Server Functionality".

2.2.2 Setting Up the Native SOAP-based OAAM Sample Application

If you have advanced requirements similar to native integration but prefer to use SOAP web services instead of Java API integration directly, you can choose this option.

The Native SOAP integration option involves inclusion of the OAAM SOAP client library (Java/.Net Wrapper to invoke SOAP APIs) to have communication with OAAM Server for device fingerprinting, risk evaluation, and KBA related activities.

This section describes how to set up the OAAM Sample application.

2.2.2.1 Notes about Native SOAP Integration

The following are a few important notes to keep in mind for SOAP based native integration:

OAAM Server (default name of managed server: oaam_server_server1 and the name of Enterprise Application oaam_server.ear) exposes web services for the SOAP based integration.
WSDL for the exposed web services is found in http://OAAM_Server_Host:Port/oaam_server/services?wsdl
As OAAM provides the OAAM client library for native integration, it is recommended that you use the same client library and avoid using web services directly (i.e. without using client library provided by OAAM).
When the OAAM Shared Library is not used, it is recommended that you replace the oaam_soap_client.jar file and bharosa_properties folder with the files available from IAM_ORACLE_HOME/oaam/oaam_libs/jar/oaam_soap_client.jar and IAM_ORACLE_HOME/oaam/oaam_libs/war/oaam_native_lib.war/WEB-INF/classes/bharosa_properties.
For configuring authorization on the OAAM Server side (exposing web services), see Section 4.3, "OAAM SOAP Integration."
Include all the changes in configurable properties in oaam_custom.properties. By default, many properties are already set in oaam_custom.properties and some properties require modification or deletion based on the integration and deployment scenario.
Based on the preference, EAR or WAR should be prepared including updated properties and library files.

2.2.2.2 Pre-requisites

Before you set up the 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 accessible from the host where the OAAM sample application is being deployed
Details about the database host, username, and password used by Oracle Adaptive Access Manager
The most recent OAAM Sample Application that illustrates Java API integration can be downloaded from My Oracle Support.
The latest webserviceclient+ssl.jar file.

A runtime JAR file called webserviceclient+ssl.jar contains the runtime implementation of SSL. If you are not deploying the sample application in a WebLogic container, obtain the file from your Oracle WebLogic Server installation and then, copy it to your client application development computer.

2.2.2.3 Installing and Configuring the OAAM Sample Application

To set up the OAAM sample application, proceed as follows:

Create an oaam_sample directory.
Extract the OAAM Sample file into the oaam_sample directory.
Edit the oaam_custom.properties file under the customer application deployment/WEB-INF/classes directory as follows:
1. The same OAAM client library can be used for SOAP or In-Proc integration. For the OAAM client library to use the SOAP based integration, set the following properties in oaam_custom.properties:
```
vcrypt.tracker.soap.useSOAPServer=true
vcrypt.soap.disable=false    vcrypt.tracker.impl.classname=com.bharosa.vcrypt.tracker.impl.VCryptTrackerSOAPImpl
vcrypt.tracker.soap.url=http://hostname:port/oaam_server/services
```
  The vcrypt.tracker.soap.url setting specifies the location of the web services with which the application will communicate.
2. Set the following property so that the OAAM SOAP client uses a WebLogic based SOAP implementation:
```
vcrypt.common.util.vcryptsoap.impl.classname=com.bharosa.vcrypt.common.impl.VCryptSOAPGenericImpl
```
  For usage of a different SOAP implementation (for example, AXIS), a customized implementation of VCryptSOAP (like VCryptSOAPGenericImpl) is required to be prepared and configured.
3. The OAAM client library can read configuration parameters from the database and properties files. In most deployment scenarios, OAAM Sample will not have access to the database. For the OAAM Client to read configurable parameters only from properties files, set the following properties in oaam_custom.properties:
```
bharosa.config.impl.classname=com.bharosa.common.util.BharosaConfigPropsImpl
bharosa.config.load.impl.classname=com.bharosa.common.util.BharosaConfigLoadPropsImpl
```
4. The default SOAP implementation (VCryptSOAPGenericImpl) is designed to use BASIC (username and password) based HTTP authentication. Set the following configurable properties in oaam_custom.properties to have authentication enabled for SOAP communication. For keystore related details, see Section 4.3.4, "Setting Up Client Side Keystore to Secure the SOAP User Password."
```
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>
vcrypt.soap.auth.keystoreFile=<Keystore File name should be available from the classpath, i.e., WEB-INF/classes>
```
  If SOAP Authentication is not enabled, set the following property:
```
vcrypt.soap.auth=false 
```
5. OAAM uses encryption/decryption for configurable properties and database tables/columns. Configurable properties control algorithm and implementation for such encryption/decryption. The properties are read first during initialization of the OAAM Client.
  
  By default, required configuration for such encryption/decryption is read from the CSF (which has been initialized during the first startup of OAAM Server/Admin). If the deployment of OAAM Sample application is on the same WebLogic Server domain where OAAM Server is running, comment out any bharosa.cipher.encryption.algorithm.enum properties* in oaam_custom.properties.
  
  If the deployment of the OAAM Sample application is on a non-WebLogic Server or a non-Identity Access Management WebLogic Server domain, set the following properties in oaam_custom.properties:
```
bharosa.cipher.encryption.algorithm.enum.DESede_config.keyRetrieval.classname=com.bharosa.common.util.cipher.KeystoreKeyRetrieval
bharosa.cipher.encryption.algorithm.enum.DESede_config.keystoreFile=<Keystore File name which should be available from classpath. i.e. WEB-INF/classes>
bharosa.cipher.encryption.algorithm.enum.DESede_config.keystorePassword=<Java-keystore-password>
bharosa.cipher.encryption.algorithm.enum.DESede_config.aliasPassword=<Keystore-alias-password>
bharosa.cipher.encryption.algorithm.enum.DESede_db.keyRetrieval.classname=com.bharosa.common.util.cipher.KeystoreKeyRetrieval
bharosa.cipher.encryption.algorithm.enum.DESede_db.keystoreFile=<Keystore File name which should be available from classpath. i.e. WEB-INF/classes>
bharosa.cipher.encryption.algorithm.enum.DESede_db.keystorePassword=<Java-keystore-password>
bharosa.cipher.encryption.algorithm.enum.DESede_db.aliasPassword=<Keystore-alias-password>
```
6. Set bharosa.image.dirlist to the absolute directory path where OAAM images are available. For example, bharosa.image.dirlist=/scratch/orafmw/r2ps2/products/access/iam/oaam/oaam_images/
7. Set vcrypt.user.image.dirlist.property.name=bharosa.image.dirlist.
Update the OAAM sample application so it picks up the changes made to the oaam_custom.properties file. Navigate to the Oracle WebLogic Administration Console and select Deployments and then Summary of Deployments. Click Next to the OAAM sample application and click the Update button. Click Finish.
Start the managed server.
Make changes to OAAM Web services security to allow access to OAAM SOAP services. By default they are protected by Oracle Web Services Manager (OWSM). The steps are as follows:
1. Log in to Oracle Enterprise Manager Fusion Middleware Control of the Identity Management domain as a WebLogic Administrator using the URL:
```
http://weblogic-admin-hostname:port/em
```
2. Locate oaam_server_server1 in the left pane 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.
5. Select all the rows related to OAAM Web services 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.
Navigate to the Oracle WebLogic Administration Console. Click Lock and Edit and select the Deployments node. On the Summary of Deployments page, find and select the OAAM sample application. Click Start > Servicing all requests. Click Yes to confirm.
Log in to the OAAM Admin application and import the OAAM snapshot oaam_base_snapshot.zip file into the system using the Oracle Adaptive Access Manager Administration Console. The snapshot contains policies, challenge questions, dependent components, and configurations that Oracle Adaptive Access Manager requires.

For instructions on importing the OAAM snapshot, refer to Oracle Fusion Middleware Administrator's Guide for Oracle Adaptive Access Manager.
Navigate to the URL:
```
http://host-name:port/oaam_sample
```
You are shown the login page of the OAAM sample application.
Enter the username and then password in the next page. You be taken through the registration process.

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

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

The native integration embeds OAAM in-process inside the protected applications. The application invokes the OAAM APIs directly to access risk and challenge flows. This integration involves the inclusion of OAAM core libraries (JAR files) and properties files into protected application. As OAAM is embedded in the application(s) for this integration, it may require OAAM database access from the protected applications.

This section describes how to set up the OAAM Sample application.

2.2.3.1 Important Notes about Native In-Proc Integration

The following are important notes to keep in mind for native OAAM integration in In-Proc mode:

The same OAAM Sample package works with SOAP or In-Proc integration. You must make changes in the OAAM configurable properties and libraries to use the specific integration (SOAP or In-Proc) with OAAM Sample.
With In-Proc integration, the OAAM client library directly invokes Java APIs (without the SOAP client); therefore it requires database access from the OAAM client (the OAAM client needs access to the OAAM core libraries and data source. It is recommended that you use the OAAM Shared Library and data source on WebLogic. If In-Proc integration is used with a non-WebLogic container, the OAAM Sample deployment must include changes in the persistence (database access) layer and OAAM core libraries.
The OAAM client library can read configuration parameters from the database and properties files. In In-Proc integration, OAAM Sample needs access to the database and properties files. Do not set the following properties in oaam_custom.properties:
```
bharosa.config.impl.classname
bharosa.config.load.impl.classname
```
You should include all changes in configurable properties in oaam_custom.properties. By default, many properties are already set in oaam_custom.properties and you must modify or delete properties based on the integration and deployment scenario.
Based on the preference, the EAR or WAR should be prepared including updated properties and library files.

2.2.3.2 Pre-requisites

Before you can set up the OAAM sample application you need:

OAAM Admin to be installed, configured, and running
Oracle Adaptive Access Manager SOAP service to be enabled and accessible from the host where the OAAM sample application is being deployed
Details about the database host, username, and password used by Oracle Adaptive Access Manager
The most recent OAAM Sample Application that illustrates Java API integration can be downloaded from My Oracle Support.

2.2.3.3 Installing and Configuring the OAAM Sample Application

To set up the OAAM Sample application:

Create the oaam_sample directory.
Extract the OAAM Sample file into the oaam_sample directory.
Edit the oaam_custom.properties file under the customer application deployment/WEB-INF/classes directory as follows:
1. The same OAAM client library can be used for SOAP or In-Proc integration. For the OAAM client library to use In-Proc integration, you must set the following properties in oaam_custom.properties:
```
vcrypt.tracker.soap.useSOAPServer=false
vcrypt.soap.disable=true
```
2. OAAM uses encryption/decryption for configurable properties and some database tables/columns. Configurable properties control algorithm and implementation for such encryption/decryption. These properties are read first during the initialization of the OAAM client.
  
  By default, the required configuration for such encryption/decryption is read from the CSF (which has been initialized during the first startup of OAAM Server/Admin). If the deployment of OAAM Sample application is on the same WebLogic Server domain where OAAM Server is running, comment out any bharosa.cipher.encryption.algorithm.enum* properties in oaam_custom.properties.
  
  If the deployment of OAAM Sample application is on a non-WebLogic Server or a non-Identity Access Management WebLogic Server domain, set the following properties in oaam_custom.properties:
```
bharosa.cipher.encryption.algorithm.enum.DESede_config.keyRetrieval.classname=com.bharosa.common.util.cipher.KeystoreKeyRetrieval
bharosa.cipher.encryption.algorithm.enum.DESede_config.keystoreFile=<Keystore File name which should be available from classpath. i.e. WEB-INF/classes>
bharosa.cipher.encryption.algorithm.enum.DESede_config.keystorePassword=<Java-keystore-password>
bharosa.cipher.encryption.algorithm.enum.DESede_config.aliasPassword=<Keystore-alias-password>
bharosa.cipher.encryption.algorithm.enum.DESede_db.keyRetrieval.classname=com.bharosa.common.util.cipher.KeystoreKeyRetrieval
bharosa.cipher.encryption.algorithm.enum.DESede_db.keystoreFile=<Keystore File name which should be available from classpath. i.e. WEB-INF/classes>
bharosa.cipher.encryption.algorithm.enum.DESede_db.keystorePassword=<Java-keystore-password>
bharosa.cipher.encryption.algorithm.enum.DESede_db.aliasPassword=<Keystore-alias-password>
```
In the deployment descriptor file, set the reference to the OAAM shared library oracle.oaam.libs.

There are two versions (EAR and WAR) of the OAAM Shared Library (oaam_native_lib) available from IAM_ORACLE_HOME/oaam/oaam_libs/ear or IAM_ORACLE_HOME/oaam/oaam_libs/war. The target for the shared library should be updated correctly to make sure that OAAM Sample Application would be able to access that.

If OAAM Sample is packaged (and to be deployed) as a WAR file, the WAR version of oaam_native_lib (IAM_ORACLE_HOME/oaam/oaam_libs/war/oaam_native_lib.war) must be deployed as a shared library in WebLogic.

To use the WAR version of the shared library from the OAAM Sample application, 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>
```
If OAAM Sample is packaged (and to be deployed) as an EAR file, EAR version of oaam_native_lib (IAM_ORACLE_HOME/oaam/oaam_libs/ear/oaam_native_lib.ear) should be deployed as a shared library in WebLogic.

To use the EAR version of the shared library from the OAAM Sample application, 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>
```
Start the WebLogic Server.
Navigate to the Oracle WebLogic Administration Console at
```
http://oaam_host:port/console
```
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 left pane) 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 the Install this deployment as a library option. Click Next.
4. In the Select Deployments targets page, select the managed server from the list of servers and click Next. The name of the shared library is oracle.oaam.libs.
  
  If the managed server is OAAM Server then you do not need to create an OAAM data source. Otherwise create a data source with the JNDI name as jdbc/OAAM_SERVER_DB_DS and provide the connection details for the OAAM database schema.
5. Click Finish.
Deploy the OAAM 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 pane) in Summary of Deployments under the Control tab.
2. Click the Install button. In the path, specify the location of the OAAM sample application. Click Next.
3. Select the Install this deployment as an application option. Click Next.
4. In the Select Deployments targets page, select the managed server from the list of servers and click Next.
5. Click Finish.
Click Activate Changes under the Change Center.
Start the managed server.
Navigate to the Oracle WebLogic Administration Console. Click Lock and Edit and select the Deployments node. On the Summary of Deployments page, find and select the OAAM sample application. Click Start > Servicing all requests. Click Yes to confirm.
Log in to the OAAM Admin application and import the OAAM snapshot oaam_base_snapshot.zip file into the system using the Oracle Adaptive Access Manager Administration Console. The snapshot contains policies, challenge questions, dependent components, and configurations that Oracle Adaptive Access Manager requires.

For instructions on importing the OAAM snapshot, refer to Oracle Fusion Middleware Administrator's Guide for Oracle Adaptive Access Manager.
Navigate to the URL:
```
http://managed_server:port/oaam_sample
```
You are shown the login page of the OAAM sample application.
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.3 Integrating Virtual Authentication Devices, Knowledge-Based Authentication, and One-Time Password

The integration flow example documented in this section consolidates virtual authentication devices, knowledge-based authentication, and one-time password.

The following are terms you will need to understand this chapter.

Authentication: An authentication flow is the process used to verify the identity of a person or other entity requesting access to a resource under security constraints. Multifactor authentication is a system wherein different factors are used in conjunction to authenticate the person or other entity.

Virtual authentication devices: Virtual authentication devices are authenticator interfaces used to protect end-users during the process of entering and transmitting authentication credentials and provide them with verification that they are authenticating on the valid application. OAAM includes a suite of highly secure virtual authentication devices as samples to deploy if you choose to. Alteration of these samples is considered custom development. If the deployment supports localization, globalized virtual authentication device image files including registration flows must be developed by the deployment team.

Knowledge-based authentication (KBA): Knowledge-based authentication (KBA) is a secondary authentication method that provides an infrastructure based on registered challenge questions. It enables end-users to select questions and provide answers which the system uses later on to challenge them when necessary. Security administration include:

Registration logic to manage the registration of challenge questions and answers
Answer Logic to intelligently detect the correct answers in the challenge response process
Validations for answers given by a user at the time of registration

For information, see "Managing Knowledge-Based Authentication" in the Oracle Fusion Middleware Administrator's Guide for Oracle Adaptive Access Manager.

One-time Password: One-time Password (OTP) is a risk-based challenge solution consisting of a server generated one time password delivered to an end-user through a configured out-of-band channel. Supported OTP delivery channels include short message service (SMS), email, and instant messaging (IM). You can use OTP to compliment KBA challenge or instead of KBA.

For information, see "Setting Up OTP Anywhere" in Oracle Fusion Middleware Administrator's Guide for Oracle Adaptive Access Manager.

Figure 2-3 illustrates an authentication flow example that uses virtual authentication devices, KBA, and OTP. The flow illustrated is an example and other authentication flows are possible.

Details about the checkpoints and rules are explained in the following sections:

User Name Page (c1)
Device Fingerprint Flow (r2)
Run Pre-Authentication Rules (r1)
Run Virtual Authentication Device Rules (r3)
Decode Virtual Authentication Device Input (p3)
Validate User and Password (c2)
Run Post-Authentication Rules (r4)
Check Registration for User (p5)
Run Registration Required Rules (r5)
Enter Registration Flow (p6)
Run Challenge Rules (r6)
Run Authentication Rules (r7)
Challenge the User (p7)
Check Answers to Challenge (c4)
Lock Out Page (c6)
Landing or Splash Page (c5)

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

Description of "Figure 2-3 Virtual Authentication Devices, Knowledge-Based Authentication, and OTP Scenario"

2.3.1 User Name Page (c1)

When the application uses a custom login page, the login page must be split into two pages. The user is presented with a page in which he is asked to submit his user name: The user enters the login ID (user name) in the first page, and this user name is stored in the HTTP session. The user name page is followed by a transient page to capture the Flash and secure cookies and for fingerprinting the user device. Figure 2-4 shows an example of the user name page.

Figure 2-4 User Name Page

Description of "Figure 2-4 User Name Page"

If OAAM is configured to use a single login page, virtual authentication devices are not used in any flow. For details on the Single Login Page, see Section 8.5, "Configuring a Single Login Page."

2.3.2 Device Fingerprint Flow (r2)

Device fingerprinting collects information about the device such as browser type, browser headers, operating system type, locale, and so on. Fingerprint data represents the data collected for a device during the login process that is required to identify the device whenever the user uses it to log in to the system. The fingerprinting process produces a fingerprint that is unique to the user. The fingerprint details help in identifying a device, check whether it is secure, and determine the risk level for the authentication or transaction. Table 2-1 lists the APIs used for device fingerprinting.

Table 2-1 Device Fingerprinting APIs

Module APIs Description

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.35, "updateLog."
Oracle Adaptive Access Manager Sample	`handleJump.jsp`	`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 the session data `bharosaSession` Forwards the user to the password page `password.jps`
Oracle Adaptive Access Manager Sample	`handleFlash.jsp`	`handleFlash.jsp` sets the Flash cookie if the browser is Flash-enabled.

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.35, "updateLog."

Oracle Adaptive Access Manager Sample

handleJump.jsp

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 the session data bharosaSession
Forwards the user to the password page password.jps

Oracle Adaptive Access Manager Sample

handleFlash.jsp

handleFlash.jsp sets the Flash cookie 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 sample code shows how to fingerprint the device using browser and Flash cookies. See the 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.3.3 Run Pre-Authentication Rules (r1)

Additionally, 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
BLOCK to block the user from proceeding

Table 2-2 lists the APIs used for pre-authentication.

Table 2-2 Pre-Authentication Rules Reference APIs

Module APIs Description

Server

VCryptRulesEngine::processRules()

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

Oracle Adaptive Access Manager Sample

handleJump.jsp

handleJump.jsp:

Invokes the pre-authentication rules
Returns ALLOW to proceed to the password page password.jsp or BLOCK or ERROR to signal an error
Stores bharosaSession

BharosaHelper

BharosaHelper::runPreAuthRules()

2.3.4 Run Virtual Authentication Device Rules (r3)

The Authentipad checkpoint determines the virtual authentication device to use. If the user has not registered image and phrase, the rule assigns the Generic TextPad; otherwise, if the user has registered, the rule assigns 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 personalized Textpad is a device for entering a password or PIN using a keyboard. This method of data entry helps to defend against phishing. TextPad can be deployed as the default for all users in a large deployment then each user individually can upgrade to another device if they want. The personalized image and phrase a user registers and sees every time they log in to the valid website serves as a shared secret between user and server.

The Keypad is a device for entering passwords, credit card number, and so on, using a keyboard for entry. The KeyPad protects against Trojan or keylogging.

Table 2-3 lists the APIs used to run virtual authentication device rules.

Table 2-3 Virtual Authentication Device Rules APIs

Module APIs Description

Server

VCryptRulesEngine::processRules()

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

Oracle Adaptive Access Manager Sample

password.jsp

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.3.5 Generate a Generic TextPad (p1)

If the user has not yet registered for image and phrase with OAAM, he is shown a generic, non-personalized TextPad, as seen in Figure 2-5.

There is no specific image or phrase on this device, but there is a timestamp to help prove the legitimacy of the login prompt.

Figure 2-5 Generic, Non-Personalized TextPad

Description of "Figure 2-5 Generic, Non-Personalized 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.20, "getUserByLoginId."
Oracle Adaptive Access Manager Sample	`Password.jsp`	`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.3.6 Generate a Personalized TextPad or KeyPad (p2)

If the user has registered a phrase and image with OAAM, a personalized TextPad is used for the user. Figure 2-6 andFigure 2-7 illustrate personalized text and key virtual authentication device to be generated.

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.20, "getUserByLoginId."
Oracle Adaptive Access Manager Sample	`password.jsp`	`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.3.7 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`	`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 devices
BharosaHelper	`BharosaHelper:: createPersonalizedAuthentiPad ()` `BharosaHelper::createAuthentiPad()` `BharosaHelper::imageToStream()`
Client	`AuthentiPad::getHTML()` `KeyPadUtil::encryptImageToStream()`

Figure 2-6 shows a personalized textpad.

Figure 2-6 Personalized TextPad

Description of "Figure 2-6 Personalized TextPad"

Figure 2-7 shows a personalized keypad.

Figure 2-7 Personalized KeyPad

Description of "Figure 2-7 Personalized KeyPad"

Note the image and phrase are embedded in the devices along with a current timestamp in the user's local time zone.

2.3.8 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 the system uses it 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

Module	APIs	Description
Oracle Adaptive Access Manager Sample	`handlePassword.jsp`	`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`

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.3.9 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

Module	API	Description
Oracle Adaptive Access Manager Sample	`handlePassword.jsp`	`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`

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.3.10 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

Module	APIs	Description
Server	`VCryptTracker::updateAuthStatus()`	For method details, see Section 4.5.34, "updateAuthStatus."
Oracle Adaptive Access Manager Sample	`handlePassword.jsp`	`handlePassword.jsp` Retrieves the password Decodes the password Validates the user Forwards to `registerImageandPhrase`, or challenges a registered user
BharosaHelper	`BharosaHelper::updateStatus()`

Server

VCryptTracker::updateAuthStatus()

For method details, see Section 4.5.34, "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.3.11 Password Status (c3)

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

2.3.12 Run Post-Authentication Rules (r4)

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

ALLOW
BLOCK
CHALLENGE

If the outcome of Post-Authentication is ALLOW, then OAAM determines if the user has to be registered and sends the user to the Registration flow. If the outcome of the Post-Authentication is BLOCK, then the user is blocked and will not be able to access the web application that the user tried to access. If the outcome of Post-Authentication is CHALLENGE and if the user is already registered for at least one of the challenge mechanisms, OAAM sends the user to the Challenge flow.

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.26, "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.3.13 Check Registration for User (p5)

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

2.3.14 Run Registration Required Rules (r5)

Business and security requirements specify whether 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.26, "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.3.15 Enter Registration Flow (p6)

Registration is the enrollment process, the opening of a new account, or other event where information is obtained from the user. The Registration flow allows the user to register for questions, image, phrase, and OTP (email, phone, and so on). Once the user is successfully registered, you can use KBA and OTP as secondary authentication factors to challenge the user.

Table 2-12 describes the modules and APIs in the Registration flow.

Table 2-12 Registration Flow

Module	APIs	Description
Server	`VCryptRulesEngine::processRules()`	For method details, see Section 4.5.26, "processRules."
Oracle Adaptive Access Manager Sample	`registerImagePhrase.jsp`	`registerImagePhrase.jsp` Assigns new image and caption to user Assigns new image and caption to user Forwards to page `handleRegisterImagePhrase.jsp`
	`registerQuestions.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`	`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.3.16 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 through SMS, to challenge user with OTP
ChallengeEmail to challenge user with OTP through 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.26, "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.3.17 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 assigns the QuestionPad. If the user is to be challenge with an OTP, the rule assigns the TextPad.

2.3.18 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 through 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.

Note:

The generateOTP() API has been deprecated in the OAAM JAVA and SOAP APIs. Please use the getOTPCode() API instead when writing your production code. For details on how to use the getOTPCode() API, see the Oracle Fusion Middleware Java API Reference for Oracle Adaptive Access Manager.

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`, and so on) 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.3.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.3.19 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

Module	APIs	Description
Server	`VCryptAuth::authenticateQuestion()` `VCryptRulesEngine::processRules()` `VCryptTracker::updateAuthStatus()`	For method details, see Section 4.5.26, "processRules," and Section 4.5.34, "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`

Server

VCryptAuth::authenticateQuestion()

VCryptRulesEngine::processRules()

VCryptTracker::updateAuthStatus()

For method details, see Section 4.5.26, "processRules," and Section 4.5.34, "updateAuthStatus."

Oracle Adaptive Access Manager Sample

handleChallenge.jsp

Calls BharosaHelper::validateAnswer

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.3.20 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.3.21 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.