3 Integrating Native .NET Applications

3.1 Overview

ASP.NET applications, written in any ASP.NET language, use the OAAM .NET API to access Oracle Adaptive Access Manager. This API communicates with the server using SOAP, as illustrated in Figure 3-1.

Figure 3-1 .NET Application

3.2 Installing Oracle Adaptive Access Manager .NET SDK

The Oracle Adaptive Access Manager .NET development kit (SDK) is packaged in the ZIP file, Bharosa_SDK_DotNet2.0.zip. The contents of this ZIP file should be extracted to the virtual directory of the Web application to be integrated with Oracle Adaptive Access Manager, and the Web application project files must be updated with references to the unzipped development kit DLLs.

3.3 Application Configuration

To configure the application, define the BharosaSOAPURL key in the <appSettings> section of the configuration file for the Web application, web.config.

The value of this key should be set to the URL that the application will use to access the Oracle Adaptive Access Manager Server SOAP services. The following section of a web.config file illustrates this setting:

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

3.4 Properties

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

The Oracle Adaptive Access Manager .NET API uses these properties to read configurable values at runtime, such as the location of images for virtual authentication devices. 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.

3.5 User-Defined Enumerations

A user-defined enumeration is 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.6 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.15, "ASP.NET Sample Applications."

3.7 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.8 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 "Creating Policies" in 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
}

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

VCrypResponse[] createTransactions(TransactionCreateRequestData[] transactionCreateRequestData);

VCrypResponse[] updateTransactions(TransactionUpdateRequestData[] transactionUpdateRequestData);

3.9 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.15, "ASP.NET Sample Applications."

3.10 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.11 Virtual Authentication Devices

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

• Creating a Virtual Authentication Device

• Embedding a Virtual Authentication Device in a Web Page

• Validating User Input with a Virtual Authentication Device

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;
}

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

3.12 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.13 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.14 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.15 ASP.NET Sample Applications

The SDK includes ASP.NET applications that illustrate the integration of several Oracle Adaptive Access Manager features with a simple ASP.NET Web application.

The names and brief description of these applications is shown in Table 3-2.

The source code for each of these applications is packaged in a separate directory, and the Visual Studio Solution files for each of them are located in the root directory. The solutions file SampleWebApps can be loaded to view all applications together in a development environment.

When setting up an environment to run the sample applications, make sure that:

• The URL of the service that communicates via SOAP with Oracle Adaptive Access Manager is correctly set in the application's web.config file.

  A sample setting is shown:

  <appSettings>
      <add key="BharosaSOAPURL" 
           value="http://localhost:9090/mySOAPservices/services"/>
    </appSettings>
  

• Oracle Adaptive Access Manager used with these applications is loaded with the policies contained in the file models.zip.

• Both the Oracle Adaptive Access Manager SOAP Server and the Web applications are configured to look for virtual authentication device images in the same directory paths. To this purpose, set the following properties:

  bharosa.authentipad.full.background.dirlist
      bharosa.authentipad.alphanumeric.background.dirlist
      bharosa.authentipad.numeric.background.dirlist
      bharosa.authentipad.textpad.background.dirlist
      bharosa.authentipad.textpadreset.background.dirlist
      bharosa.authentipad.questionpad.background.dirlist