Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Adaptive Access Manager
11g Release 1 (11.1.1)

Part Number E15480-08
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

3 Integrating Native .NET Applications

This chapter provides details how ASP.NET applications can integrate with Oracle Adaptive Access Manager using the .NET API provided by Oracle Adaptive Access Manager. Descriptions are also provided on the sample applications used to illustrate the integration of different OAAM features with a basic Web application.

This chapter contains the following sections:

3.1 Introduction

ASP.NET is a Web application framework that allows programmers to build dynamic Web sites, Web applications, and Web services. OAAM provides an OAAM .NET development kit (SDK). The OAAM .NET SDK to use for integrating ASP.NET applications with OAAM. It includes the OAAM .NET APIs that are exposed by the OAAM .NET library, OAAM sample .NET applications, OAAM flash movie page, which is used to collect fingerprint in device identification, and other files that are required for .NET Native Integration. ASP.NET applications, written in any ASP.NET language, can use the OAAM .NET API to call Oracle Adaptive Access Manager.

The OAAM .NET API communicates with the OAAM server using Simple Object Access Protocol (SOAP). SOAP is a protocol specification for exchanging structured information in the implementation of Web Services in computer networks.

3.2 Oracle Adaptive Access Manager .NET SDK

The Oracle Adaptive Access Manager .NET development kit (SDK) is packaged in the ZIP file, oaam_native_dot_net.zip in $ORACLE_HOME/oaam/oaam_libs/dotNet/.

Sample .NET applications that enable OAAM features require the integration of the OAAM .NET APIs found in the SDK package oaam_native_dot_net.zip. The content of the archive needs to be extracted to the root directory of the web application:

oaam_native_dot_net.zip could be obtained from ${ORACLE_HOME}/oaam/dist/oaam_dist_final/oracle.oaam.libs/dotNet.

3.3 Configuration Properties

The Oracle Adaptive Access Manager .NET SDK includes property files that specify values for configuration used by the Oracle Adaptive Access Manager API. A developer can modify these properties to specify application-specific values or add new ones.

3.3.1 How the API Uses Properties

The OAAM .NET API uses properties to read configurable values at runtime, such as the location of images for virtual authentication devices. Virtual authentication devices are controls for user input and provide a virtual keyboard and personalization. Properties are read and cached from a list of files at startup and updated whenever one of the properties files is updated.

The sequence in which the properties files are loaded by Oracle Adaptive Access Manager .NET API is as follows:

  1. The lookup.properties file, if present, is loaded first.

  2. If the properties.filelist property is defined in lookup.properties, then all the files listed in that property are added to the queue (in the listed order).

  3. The bharosa_lookup.properties file, if present, is loaded.

  4. If the properties.filelist property is defined in bharosa_lookup.properties, then all the files listed in that property are added to the queue (in the listed order)

  5. All files in the queue are loaded.

  6. When any of the loaded properties files is changed, the properties are reloaded.

The properties files, including lookup.properties, are searched in the following directories in the order stated in Table 3-1; the search for a given file stops when the file is first found or when no file is found.

Table 3-1 .NET Property Files

Directory Example

<ApplicationDirectory>/

c:/Inetpub/wwwroot/MyApp/

<CallingAssemblyDirectory>/

c:/Windows/System32/

<CurrentAssemblyDirectory>/

c:/Inetpub/wwwroot/MyApp/bin/

<CurrentAssemblyDirectory>/../

c:/Inetpub/wwwroot/MyApp/

<CurrentDirectory>/

c:/Windows/System32/

<ApplicationDirectory>/bharosa_properties/

c:/Inetpub/wwwroot/MyApp/bharosa_properties/

<CallingAssemblyDirectory>/bharosa_properties/

c:/Windows/System32/bharosa_properties/

<CurrentAssemblyDirectory>/bharosa_properties/

c:/Inetpub/wwwroot/MyApp/bin/bharosa_properties/

<CurrentAssemblyDirectory>/../bharosa_properties/

c:/Inetpub/wwwroot/MyApp/bharosa_properties/

<CurrentDirectory>/bharosa_properties/

c:/Windows/System32/bharosa_properties/


3.3.2 Encrypting Property Values

A property value specified in a properties file can be encrypted using the command-line utility BharosaUtils.exe included in the Oracle Adaptive Access Manager .NET SDK.

An encryption key (arbitrarily selected by the user) is required to encrypt and decrypt values. This key is available to Oracle Adaptive Access Manager .NET API through the property bharosa.cipher.client.key, which must be set in one of the application properties files.

BharosaUtil.exe prompts the user to enter the encryption key and a value, and the encrypted value is output to the console. The following run of the utility illustrates how to encrypt a string:

C:\> BharosaUtil.exe -enc
Enter key (min 14 characters len): <your key>
Enter key again: <your key>
Enter text to be encrypted: <string to encryp>
Enter text to be encrypted again: <string to encryp>
vCCKC19d14a39hQSKSirXSiWfgbaVG5SKIg==

3.3.3 Using User-Defined Enumerations to Define Elements

Visual Studio 2005 allows you to use enumerations defined in the .NET Framework. A user-defined enumerations are a collection of items; each item is assigned an integer and may contain several attributes. A user-defined enumeration is specified in a properties file, and its name, the names of its items, and the name of the item attributes must conform to the following rules:

  • The name of the enumeration has the suffix .enum

  • The name of an item has a prefix equals to the name of the enumeration

  • The name of an attribute of an item has a prefix equals to the name of the item

Here is an example of a user-defined enumeration:

#Example of a user-defined enumeration 
auth.status.enum=Enumeration to describe authentication status

#first item and its attributes
auth.status.enum.success=0
auth.status.enum.success.name=Success
auth.status.enum.success.description=Success
auth.status.enum.success.success=true

#second item and its attributes
auth.status.enum.invalid_user=1
auth.status.enum.invalid_user.name=Invalid user 
auth.status.enum.invalid_user.description=Invalid User

#third item and its attributes
auth.status.enum.wrong_password=2
auth.status.enum.wrong_password.name=Wrong password 
auth.status.enum.wrong_password.description=Wrong password

#fourth item and its attributes
auth.status.enum.wrong_pin=3
auth.status.enum.wrong_pin.name=Wrong pin
auth.status.enum.wrong_pin.description=Wrong Pin

#fifth item and its attributes
auth.status.enum.session_expired=4
auth.status.enum.session_expired.name=Session expired 
auth.status.enum.session_expired.description=Session expired

Here is an example of the use of the previous user-defined enumeration in application code:

UserDefEnumFactory factory = UserDefEnumFactory.getInstance();
UserDefEnum statusEnum = factory.getEnum("auth.status.enum");
int statusSuccess       = statusEnum.getElementValue("success");
int statusWrongPassword = statusEnum.getElementValue("wrong_password");

3.4 Oracle Adaptive Access Manager API Usage

This section contains details on how OAAM APIs are used to support common OAAM scenarios. You can also refer to the sample applications for details.

3.4.1 User Details

Oracle Adaptive Access Manager stores user details in its database and uses this information to perform the following tasks:

  • Determine the risk rules to run for a user

  • Find user-specific virtual authentication device attributes

  • Propose challenge questions

  • Validate answers to challenge questions

The client application is responsible for populating the Oracle Adaptive Access Manager database with user details at runtime.

For example, when a user logs in, the client application should first determine whether the user record exists. If the record is not found, then the application should call the appropriate APIs to create a user record and set the user status.

The following sample illustrates the calls to create a user record:

string loginId = "testuser";  // loginId of the user logging in

// set the proxy to access the SOAP server that communicates with the 
// OAAM SOAP Server 
IBharosaProxy proxy = BharosaClientFactory.getProxyInstance();
 
// find the user record in OAAM
VCryptAuthUser user = proxy.getUserByLoginId(loginId);
 
// if user record does not exist, create one
if(user == null || StringUtil.IsEmpty(user.LoginId))
{
    string customerId  = loginId; 
    string userGroupId = "PremiumCustomer";
    string password    = "_"; // this value is not used for now
 
    user = new VCryptAuthUser(loginId, customerId,
                              userGroupId, password);
    user = proxy.createUser(user);
 
    // set the status of the new user to Invalid; once the user is 
    // authenticated, set the status to PendingActivation; after the
    // user succssfully completes registration, set the status to Valid
    proxy.setUserStatus(user.CustomerId, (int)UserStatus.Invalid);
}
 
// save the user record in the session for later reference
AppSessionData sessionData = AppSessionData.GetInstance(Session);
 
sessionData.CurrentUser = user;

For further details, see the sample applications in Section 3.5.1, "ASP.NET Applications."

3.4.2 User Logins and Transactions

Oracle Adaptive Access Manager provides APIs to capture user login information, user login status, and other user session attributes to determine device and location information. Oracle Adaptive Access Manager also provides APIs to collect transaction details.

The following code sample illustrates the use of this API:

// record a user login attempt in OAAM
string   requestId      = sessionData.RequestId;
string   remoteIPAddr   = Request.UserHostAddress;
string   remoteHost     = Request.UserHostName;
bool     isFlashRequest = Request.Params["client"].Equals("vfc");
string   secureCookie   = (Request.Cookies["vsc"] != null)
                             ? Request.Cookies["vsc"].Value : null;
string   digitalCookie  = isFlashRequest
                             ? Request.Params["v"] : null;
object[] browserFpInfo = HttpUtil.GetBrowserFingerPrint();
object[] flashFpInfo   = HttpUtil.GetFlashFingerPrint();
 
int browserFingerPrintType =
               browserFpInfo == null ? 0 : (int) browserFpInfo [0];
string browserFingerPrint =
               browserFpInfo == null ? "" : (string) browserFpInfo [1];
int flashFingerPrintType =
               flashFpInfo == null ? 0 : (int) flashFpInfo[0];
string flashFingerPrint =
               flashFpInfo == null ? "" : (string) flashFpInfo[1];
 
// if user name and password have been validated by now, set the status
// to the appropriate value, such as success, wrong_password, or invalid_user 
int status = statusEnum.getElementValue("success");

// if user name and password have not yet been validated, set the status to 
// pending; after validation is done call updateLog to update status
int status = statusEnum.getElementValue("pending");
 
// Call updateLog to record the user login attempt
CookieSet cs = proxy.updateLog(requestId, remoteIPAddr, remoteHost,
                     secureCookie, digitalCookie, user.CustomerGroupId,
                     user.CustomerId, user.LoginId, false,
                     status, ClientTypeEnum.Normal,
                     "1.0", browserFingerPrintType, browserFingerPrint,
                     flashFingerPrintType, flashFingerPrint);
 
// Update secure cookie in the browser with the new value from OAAM
if (cs != null)
{
    HttpUtil.UpdateSecureCookie(Response, cs);
}

3.4.3 Rules Engine

The Rules Engine is the component of Oracle Adaptive Access Manager used to enforce policies. Based on a calling context, the Rules Engine evaluates policies and provides the results of those evaluations. Policies are configured by the administrator; for details on policy configuration, see the Oracle Fusion Middleware Administrator's Guide for Oracle Adaptive Access Manager.

The following code sample illustrates the use of APIs to invoke the Rules Engine after a user has been authorized and to process the rule evaluation result:

AppSessionData  sessionData = AppSessionData.GetInstance(Session);
IBharosaProxy      proxy    = BharosaClientFactory.getProxyInstance();
UserDefEnumFactory factory  = UserDefEnumFactory.getInstance();
UserDefEnum profileTypeEnum = factory.getEnum("profile.type.enum");
 
string             requestId    = sessionData.RequestId;
BharosaStringList  profileTypes = new BharosaStringList();
BharosaStringTable contextList  = new BharosaStringTable();
 
int postAuthType = profileTypeEnum.getElementValue("postauth");
 
profileTypes.Add(postAuthType.ToString());
 
// Run postauth rules
VCryptRulesResult res = proxy.processRules(requestId,
                                           profileTypes, contextList);
 
// process the rule result
if (StringUtil.EqualsIgnoreCase(res.Result, "Allow"))
{
// Allow the user login
}
else if (StringUtil.EqualsIgnoreCase(res.Result, "Block"))
{
// Block the user login
}
else if (res.Result.StartsWith("Challenge"))
{
// Take the user through challenge question flow
}
else if (res.Result.StartsWith("RegisterUser"))
{
// Take the user through registration flow
}

3.4.3.1 Device ID

In addition to delivering the rules result, the Rules Engine can return a device ID, an internal Oracle Adaptive Access Manager identifier for the device used for this login session.

The following sample code illustrates how to get the device ID:

VCryptRulesResult rulesResult = proxy.processRules ...);
 
If (!rulesResult.Response.IsSuccess) {
 BharosaTrace.Error("Error running rules " + rulesResult.Response.ErrorMessage);
}
Long deviceId = rulesResult.DeviceId;

Important:

The code shown assumes that:

  • You are using Oracle Adaptive Access Manager 10.1.4.5 or above

  • You have set the property bharosa.tracker.send.deviceId to true in Oracle Adaptive Access Manager:

    bharosa.tracker.send.deviceId=true
    

3.4.3.2 Creating and Updating Bulk Transactions

The IBharosaProxy.createTransactions() method can be used to create bulk transactions, as illustrated in the following call:

VCrypResponse[] createTransactions(TransactionCreateRequestData[] transactionCreateRequestData);

The IBharosaProxy.updateTransactions() method can be used to update bulk transactions, as illustrated in the following call:

VCrypResponse[] updateTransactions(TransactionUpdateRequestData[] transactionUpdateRequestData);

3.4.4 Validating a User with Challenge Questions

Oracle Adaptive Access Manager can challenge a user with pre-registered questions and match user answers with pre-registered answers during high-risk or suspicious scenarios.

Typically, a user is asked to choose questions from a given set and provide answers for them, all of which are then registered. When the user is challenged with one of these questions, he must supply the correct answer, that is, one that matches the answer he registered.

The following sample code illustrates the calls to register questions and answers and challenge the user:

//  Retrieve a question-pickset, containing groups of questions from
//  which the user would pick one question from each group for
//  registration
VCryptQuestionList[] groups = proxy.getSignOnQuestions(
                                                    user.CustomerId);
 
// See the sample application at the end of this chapter
// for details on displaying the questions in the UI and processing the user input
// Here, we assume that the q's and a's are in the question object
 
// Register the questions and answers with OAAM
VCryptResponse response = proxy.addQuestions(
                                         user.CustomerId, questions);
 
// Retrive the question to challenge the user
VCryptQuestion secretQuestion = proxy.getSecretQuestion(
                                                     user.CustomerId);

// Create QuestionPad authenticator to display the question text.
// See the sample application at the end of this chapter for details; 
// Here, we assume that the user entered an answer stored in the string answer
 
// Validate the user entered answer
VCryptAuthResult res = proxy.authenticateQuestion(customerId, answer);
 
bool isValid = (res != null && res.ResultCode == 0);

For further details, see the sample applications in Section 3.5.1, "ASP.NET Applications."

3.4.5 Resetting Challenge Failure Counters

Oracle Adaptive Access Manager records the number of wrong answers to the questions posed to the user in the failure counters. Failure counters are used to enforce a lock. The API includes a method, resetChallengeFailureCounters(), to reset the failure counters for a given user or user and question combination.

If a Question ID is specified (i.e. questionId != BharosaGlobals.LongNull), in the call, only the failure counters associated with that question are reset; if no Question ID is specified, the failure counters for all registered questions of the user are reset.

The following sample code illustrates a call to reset failure counters:

VCryptResponse resetChallengeFailureCounters(String requestId, 
                            String customerId, long questionId);

3.4.6 Virtual Authentication Devices

This section describes the creation and use of virtual authentication devices in ASP.NET applications in the following subsections:

3.4.6.1 Creating a Virtual Authentication Device

To create a virtual authentication device, use the method, BharosaClient.getAuthentiPad(), as illustrated in the following sample code:

IBharosaClient client = BharosaClientFactory.getClientInstance();
 
String padName = "passwordPad";
 
if (! IsPostBack)
{
    AuthentiPadType padType     = AuthentiPadType.TYPE_ALPHANUMERICPAD;
    String          bgFile      = proxy.getImage(user.CustomerId);
    String          captionText = proxy.getCaption(user.CustomerId);
    String          frameFile   = BharosaConfig.get(
"bharosa.authentipad.alphanumeric.frame.file",
"alphanumpad_bg/kp_v2_frame_nologo.png");
 
    AuthentiPad authPad = client.getAuthentiPad(padType, padName,
                                                frameFile, bgFile,
                                                captionText, false,
                                                true, true);
 
    // save the authenticator object in sessData: it will be needed
    // in GetImage.aspx.cs to generate the authenticator image, and
    // while decoding the user input
    sessionData[padName] = authPad;
}

3.4.6.2 Embedding a Virtual Authentication Device in a Web Page

To display a virtual authentication device properly, such as the one created in the previous section, both the .ASPX file and the code-behind file need to be updated.

To update these files, proceed as follows:

  1. Include the JavaScript bharosa_web/js/bharosa_pad.js in the ASPX file.

  2. Create a label in the ASPX file where the virtual authentication device is to be displayed:

    <asp:Label ID="authenticator" runat="server"></asp:Label>
    
  3. Generate the HTML in the code-behind file from the virtual authentication device object and assign it to the label:

    this.authenticator.Text = client.getAuthentiPadHTML(authPad,false, false);
    

3.4.6.3 Validating User Input with a Virtual Authentication Device

The input that a user supplies to a virtual authentication device is posted to the application in the HTTP parameter named padName + "DataField". This input should be decoded using the virtual authentication device as illustrated in the following sample code:

if (IsPostBack)
{
    AuthentiPad authPad       = sessionData[padName];
    String      encodedPasswd = Request.Params[padName + "DataField"];
    String      passwd        = authPad.decodeInput(encodedPasswd);
 
    // continue to validate the password
}

3.4.7 Specifying Credentials to the Oracle Adaptive Access Manager SOAP Server

The credentials to access the Oracle Adaptive Access Manager SOAP Server can be specified in one of the following ways:

  • By adding the following settings to application web.config file:

    <appSettings>
        <add key="BharosaSOAPUser"     value="soapUser"/>
        <add key="BharosaSOAPPassword" value="soapUserPassword"/>
        <add key="BharosaSOAPDomain"   value="soapUserDomain"/>
     </appSettings>
    
  • By adding the following properties to one of the application properties files:

    BharosaSOAPUser=soapUser
    BharosaSOAPPassword=soapUserPassword
    BharosaSOAPDomain=soapUserDomain
    

    Note:

    When specifying SOAP credentials in this way, you can use either clear text or an encrypted string for a value (typically, for the value of a password)

3.4.8 Tracing Messages

The Oracle Adaptive Access Manager .NET API allows to print trace messages of various levels using diagnostics switches in web.config. The trace messages can be saved to a file by configuring the appropriate listeners.

The following web.config file sample shows the configuration of switches and a listener that writes trace messages to a file:

<system.diagnostics>
  <switches>
    <add name="debug" value="0"/>
    <add name="info" value="0"/>
    <add name="soap" value="0"/>
    <add name="perf" value="0"/>
    <add name="warning" value="1"/>
    <add name="error" value="1"/>
    <add name="traceTimestamp" value="1"/>
    <add name="traceThreadId" value="1"/>
  </switches>
  <trace autoflush="true" indentsize="2">
    <listeners>
      <add name="BharosaTraceListener"
             type="System.Diagnostics.TextWriterTraceListener, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=B77A5C561934E089"
             initializeData="BharosaTrace.log"/>
    </listeners>
  </trace>
</system.diagnostics>

3.5 Integration Example Using Sample Applications

This section shows you how to integrate an application through using one of the sample applications provided in the SDK.

3.5.1 ASP.NET Applications

The following four ASP.NET applications are included in this sample package to demonstrate integration of various OAAM 11g features in ASP.NET based applications.

Table 3-2 ASP.NET Applications

Application Name Description

SampleWebApp

This is a basic ASP.NET application without OAAM integration. This application is provided so that the reader can easily see incremental changes required to integrate various OAAM feature, such as, tracker, authenticator, and KBA.

SampleWebAppTracker

This application demonstrates integration of OAAM tracker functionality to SampleWebApp listed above.

SampleWebAppAuthTracker

This application demonstrates integration of OAAM tracker and authenticator functionalities to SampleWebApp listed above.

SampleKBATracker

This application demonstrates integration of OAAM tracker and KBA functionalities to SampleWebApp listed above.


3.5.2 Sample Application Details

Details about the four applications are provided in this section.

3.5.2.1 SampleWebApp

This application contains the following pages that demonstrate a web application before OAAM integration.

  1. LoginPage.aspx

    • Collects the user name and password using a simple HTML form.

    • Validates the login and password information

    • Depending upon the validation result, the user will be redirected to either Success.aspx or to LoginPage.aspx with appropriate error message

  2. Success.aspx

    • Displays 'Successfully logged in' message with a link for logout

  3. LogoutPage.aspx

    • Logs out the user session and redirects to login page

3.5.2.2 SampleWebAppTracker

This application contains the following pages that demonstrate integration of OAAM tracker functionality to the sample application listed above.

This application requires the integration of the OAAM .NET APIs found in the SDK package oaam_native_dot_net.zip. The content of the archive needs to be extracted to the root directory of the web application.

  1. LoginPage.aspx

    • Collects the username and password using simple HTML form

    • Saves the login and password in the session

    • Redirects the user to LoginJumpPage.aspx to collect the flash finger print of the user device

  2. LoginJumpPage.aspx

    • Loads the user from ARM (Adaptive Risk Manager) by calling AppUtil.InitUser() (AppUtil is included in the SDK package). If the user is not found, a new user record will be created

    • Returns HTML to load flash object bharosa_web/flash/bharosa.swf in the browser. The flash object calls CookieManager.aspx (included in the SDK package) with flash finger print details. CookieManager.aspx records the finger print in ARM and in return sets a flash cookie on the user's device

    • After a brief wait (to allow time to get the flash cookie from ARM), redirects the browser to LoginHandlerPage.aspx

  3. LoginHandlerPage.aspx

    • Records the user login attempt with ARM by calling AppUtil.InitTracker()

    • Validates the login and password information

    • Updates ARM with the password validation status (success/wrong user/wrong password/disabled user, etc) by calling AppUtil.UpdateAuthStatus()

    • If password validation succeeds, runs post-authentication rules by calling AppUtil.RunPostAuthRules()

    • If the post-authentication rules return block, blocks the user login after updating ARM with this information

    • Depending upon the validation result and/or the rules result, redirects the user to either Success.aspx or to LoginPage.aspx with appropriate error message

  4. Success Page

    • Displays 'Successfully logged in' message with a link for logout

  5. Logout Page

    • Logs out the user session and redirects to login page

3.5.2.3 SampleWebAppAuthTracker

This application contains the following pages that demonstrate integration of OAAM authenticator and tracker functionalities to the sample application listed above. This application collects the password using authenticators offered by OAAM.

This application requires the integration of the OAAM .NET APIs found in the SDK package oaam_native_dot_net.zip. The content of the archive needs to be extracted to the root directory of the web application.

  1. LoginPage.aspx

    • Collects the username using simple HTML form

    • Saves the login in the session

    • Redirects the user to LoginJumpPage.aspx to collect the flash finger print of the user device

  2. LoginJumpPage.aspx

    • Loads the user from ARM (Adaptive Risk Manager) by calling AppUtil.InitUser() (AppUtil is included in the SDK package). If the user is not found, a new user record will be created

    • Returns HTML to load flash object bharosa_web/flash/bharosa.swf in the browser. The flash object calls CookieManager.aspx (included in the SDK package) with flash finger print details. CookieManager.aspx records the finger print in ARM and in return sets a flash cookie on the user's device

    • After a brief wait (to allow time to get the flash cookie from ARM), redirects the browser to LoginHandlerPage.aspx

  3. LoginHandlerPage.aspx

    • Records the user login attempt with ARM by calling AppUtil.InitTracker()

    • Redirects the user to PasswordPage.aspx to collect the password using OAAM authenticator.

  4. PasswordPage.aspx

    On Load:

    1. Sets the session authentication status to 'Pending' in ARM

    2. Runs pre-authentication rules by calling the AppUtil.RunPreAuthRules()

    3. If the pre-authentication rules return block, blocks the user login after updating ARM with this information

    4. If the pre-authentication rules return allow, runs another set of rules to determine the authenticator to use for this user, by calling AppUtil.RunAuthentiPadRules()

    5. Creates appropriate authenticator by calling AppUtil.CreateAuthentiPad()and renders the authenticator into HTML by using the AppUtil.getAuthentiPadHTML(). The authenticator HTML would fetch the authenticator image by calling GetImage.aspx (included in the SDK package)

    6. Stores the authenticator object in the session for later use during image generation and password decode

    On PostBack:

    1. Decodes the password using the authenticator object stored in the session

    2. Validates the login and password information

    3. Updates ARM with the password validation status (success/wrong user/wrong password/disabled user, etc) by calling AppUtil.UpdateAuthStatus()

    4. If password validation succeeds, runs post-authentication rules by calling AppUtil.RunPostAuthRules()

    5. If the post-authentication rules return block, blocks the user login after updating ARM with this information

    6. Depending upon the validation result and/or the rules result, redirects the user to either Success.aspx or to LoginPage.aspx with appropriate error message

  5. Success Page

    • Displays 'Successfully logged in' message with a link for logout

  6. Logout Page

    • Logs out the user session and redirects to login page

3.5.2.4 SampleKBATracker

This application contains the following pages that demonstrate integration of OAAM authenticator, tracker and KBA (Knowledge Based Authentication) functionalities to the sample application listed above. This application shows authentication mechanisms using password and KBA authenticators offered by OAAM.

This application requires the integration of the OAAM .NET APIs found in the SDK package oaam_native_dot_net.zip. The content of the archive needs to be extracted to the root directory of the web application.

  1. LoginPage.aspx

    • Collects the username using simple HTML form

    • Saves the login in the session

    • Redirects the user to LoginJumpPage.aspx to collect the flash finger print of the user device

  2. LoginJumpPage.aspx

    • Loads the user from ARM (Adaptive Risk Manager) by calling AppUtil.InitUser() (AppUtil is included in the SDK package). If the user is not found, a new user record will be created

    • Returns HTML to load flash object bharosa_web/flash/bharosa.swf in the browser. The flash object calls CookieManager.aspx (included in the SDK package) with flash finger print details. CookieManager.aspx records the finger print in ARM and in return sets a flash cookie on the user's device

    • After a brief wait (to allow time to get the flash cookie from ARM), redirects the browser to LoginHandlerPage.aspx

  3. LoginHandlerPage.aspx

    • Records the user login attempt with ARM by calling AppUtil.InitTracker()

    • Redirects the user to PasswordPage.aspx to collect the password using OAAM authenticator

  4. PasswordPage.aspx

    On Load:

    1. Sets the session authentication status to 'Pending' in ARM

    2. Runs pre-authentication rules by calling the AppUtil.RunPreAuthRules()

    3. If the pre-authentication rules return block, blocks the user login after updating ARM with this information

    4. If the pre-authentication rules return allow, runs another set of rules to determine the authenticator to use for this user, by calling AppUtil.RunAuthentiPadRules()

    5. Creates appropriate authenticator by calling AppUtil.CreateAuthentiPad()and renders the authenticator into HTML by using the AppUtil.getAuthentiPadHTML(). The authenticator HTML would fetch the authenticator image by calling GetImage.aspx (included in the SDK package)

    6. Stores the authenticator object in the session for later use during image generation and password decode

    On PostBack:

    1. Decodes the password using the authenticator object stored in the session

    2. Validates the login and password information

    3. Updates ARM with the password validation status (success/wrong user/wrong password/disabled user, etc) by calling AppUtil.UpdateAuthStatus()

    4. If the password validation fails, the user will be redirected to LoginPage.aspx with appropriate error message

    5. If password validation succeeds, runs post-authentication rules by calling AppUtil.RunPostAuthRules()

    6. The user will be taken through different flows, as shown below, depending upon the action from post-authenticator rules result:

      Post-Authentication Action Target URL

      Block

      LoginPage.aspx

      Allow

      Success.aspx

      ChallengeUser

      ChallengeUser.aspx

      RegisterQuestions

      RegisterQuestionsPage.aspx

      RegisterUser

      PersonalizationPage.aspx

      RegisterUserOptional

      PersonalizationPage.aspx


  5. PersonalizationPage.aspx

    • Introduces the user to device personalization explaining the steps that would follow to create a new Security Profile for the user

    • If the post authentication rule returns RegistrationOptional, the user is allowed to skip the registration process by clicking the 'Skip' button to proceed to the Success.aspx page directly

    • If registration is not optional, the user must register by clicking 'Continue' to proceed to the RegisterImagePhrase.aspx page

  6. RegisterImagePhrase.aspx

    • Allows the user to customize the randomly generated background image, caption and the type of security device used during authentication

    • A new background image and caption is assigned by calling AppUtil.AssignNewImageAndCaption()

    • The user selected security device is assigned by calling AppUtil.SetAuthMode()

  7. RegisterQuestionsPage.aspx

    • Displays sets of questions which the user can choose and register the correct answer for each.

    • The sets of questions are fetched by calling proxy.getSignOnQuestions()

  8. ChallengeUser.aspx

    • Challenges the user by displaying a question-pad with one of the questions already registered by the user

    • The answer is validated by calling proxy.authenticateQuestion() and the result is updated in ARM by calling AppUtil.UpdateAuthStatus()

    • If the answer is wrong, a call to AppUtil.RunChallengeUserRules() is made and based on the result of which, the user will either be allowed to re-enter the answer or be redirected to the block page after updating the block status in ARM

    • The number of attempts that a user gets to answer a question correctly is set by the rule administrator for ARM

    • On successfully answering the question correctly, the user is forwarded to the Success.aspx page

  9. Success Page

    • Displays 'Successfully logged in' message with a link for logout

  10. Logout Page

    • Logs out the user session and redirects to login page

3.5.3 Setting Up the Environment

Source code for each application is placed in a directory of its own. Visual Studio Solution files for each of these applications can be found in the root directory. The four applications could either be run using Visual Studio 2005 or be deployed on Microsoft IIS 6.0 on Windows Server 2003. Solutions file 'SampleWebApps' can be used to load and view all applications together using Visual Studio.

Instuctions to set up the environment to successfully run the sample applications are provided in this section. After all the following have been applied, you should be able to run these sample applications and see how they integrates with OAAM 11g in different scenarios.

3.5.3.1 Modifying the web.config File

Ensure that Soap URL to access OAAM server is set correctly in web.config file of the application, as per your deployment configuration. An example is shown as follows:

<appSettings>
    <add key="BharosaSOAPURL" 
         value="http://localhost:14300/oaam_server/services"/>
  </appSettings>
  <appSettings>
    

3.5.3.2 Setting Properties for Images

For sample applications integrating with OAAM 11g, set bharosa.image.dirlist in bharosa_app.properties to the path where "oaam_images" folder could be found. The "oaam_images" foloder is located at: ${ORACLE_HOME}/oaam/dist/oaam_dist_final/oracle.oaam.oaam_images.

The folder name could be changed but then the path should be modified accordingly. For example, if all the files obtained from the path above is stored in a folder named oaam_images and this folder is put under the root directory of the web application. The path should be: ${Application_HOME}/oaam_images/

Make sure lookup.properties is contained in /bharosa_properties/ folder, which lists all the properties files that need to be read. It could be obtained from:

${ORACLE_HOME}/oaam/apps/oaam_native/overrides/conf/bharosa_properties

Find and comment out the bharosa.authentipad.image.url property.

3.5.3.3 Running the Application

For developers who have access to Microsoft Visual Studio 2005 to test the web applications, simply build the solution after making all the above changes and click "Debug->Start Debugging" in Visual Studio 2005.

For deployment of these applications, here are some tips to follow:

  • System: Windows Server 2003

  • Application server should be installed using ->Control Panel->Add or Remove Programs->Add/Remove Windows Components. IIS and ASP.NET should be enabled;

  • Create "new website" using IIS manager by running "inetmgr" in command window;

  • Make sure ASP.NET version is set to v2.0 through ASP.NET tab in website's "Properties";

  • Make sure that ASP.NET v2.0 is set to "allowed" in IIS manager. If there is no ASP.NET v2.0 extension, add a new web service extension manually. Go to C:\WINDOWS\Microsoft.NET\Framework, there should be some folder named v2.0.50727 or similar if ASP.NET v2.0 is installed. Add v2.0.50727/aspnet_isapi.dll as a new web service extension;

  • In "IIS Manager->Local Computer->Application Pools", open "Properties->Identity", simply select "Local System" on the right of "Predefined" option if you come across probelm accessing "C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\Temporary ASP.NET Files" when opening web application pages.

3.5.4 Example: Enable Transaction Logging and Rule Processing

The following pages demonstrate how to enable transaction logging and rule processing in OARM using the ASP.NET sample applications.

Prerequisites:

  • Transaction definitions in Sample_Transaction_Defs.zip need to be available in OARM. Use 'Admin > Transactions > Import Transactions' to import the transaction definitions.

  • Transaction models defined in models.zip should be available in OARM

  • Following properties must exist in bharosa_app.properties at the OARM and the .NET client side:

    tracker.transaction.status.enum=Enum for transaction status
    tracker.transaction.status.enum.success=0
    tracker.transaction.status.enum.success.name=Success
    tracker.transaction.status.enum.success.description=Success
    tracker.transaction.status.enum.block=1
    tracker.transaction.status.enum.block.name=Block
    tracker.transaction.status.enum.block.description=Block
    tracker.transaction.status.enum.reject=2
    tracker.transaction.status.enum.reject.name=Reject
    tracker.transaction.status.enum.reject.description=Reject
    tracker.transaction.status.enum.pending=3
    tracker.transaction.status.enum.pending.name=Pending
    tracker.transaction.status.enum.pending.description=Pending
     
    profile.type.enum.pretransaction=70
    profile.type.enum.pretransaction.name=PreTransaction
    profile.type.enum.pretransaction.description=Pre Transaction
    profile.type.enum.pretransaction.ruleTypes=user,device,location,in_session
    profile.type.enum.pretransaction.listTypes=vtusers
    profile.type.enum.pretransaction.finalactionrule=process_results.rule
    profile.type.enum.pretransaction.isPreAuth=false
     
    profile.type.enum.posttransaction=80
    profile.type.enum.posttransaction.name=PostTransaction
    profile.type.enum.posttransaction.description=Post Transaction
    profile.type.enum.posttransaction.ruleTypes=user,device,location,in_session
    profile.type.enum.posttransaction.listTypes=vtusers
    profile.type.enum.posttransaction.finalactionrule=process_results.rule
    profile.type.enum.posttransaction.isPreAuth=false
    

Transaction Page

  • Dynamically generates the transaction type selection menu based on transaction enums defined in property file 'bharosa_common.properties'

  • On selecting transaction type, dynamically renders the transaction fields based on field definitions defined in properties files.

  • Either creates a transaction by calling AppUtil.createTransaction() or updates the transaction by calling AppUtil.updateTransaction()depending on the current form being submitted.

  • Runs pre and post transaction rules by calling AppUtil.RunPreTransactionRules() or AppUtil.RunPostTransactionRules(). Depending upon the result, the browser is redirected to the next appropriate page.