Skip Headers
Oracle® Adaptive Access Manager Developer's Guide
Release 10g (10.1.4.5)
Part Number E12052-03
Go to Documentation Home
Home		 Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Index
Index		 Go to Feedback page
Contact Us
Go to previous page
Previous		 Go to next page
Next
View PDF

3 Native Integration .net

ASP.NET applications can integrate with Oracle Adaptive Access Manager using the .NET API provided by Oracle Adaptive Access Manager to add multi-factor authentication.

3.1 Architecture

The Oracle Adaptive Access Manager .NET APIs can be called by the client applications natively in the .NET language of their choice. The Oracle Adaptive Access Manager .NET APIs communicate with the Adaptive Risk Manager server using the SOAP protocol. Details on installing and configuring Oracle Adaptive Access Manager .NET APIs are covered later in this chapter.

Figure 3-1 .Net API Communication

This illustration shows the API .net architecture

3.2 Installing SDK

Oracle Adaptive Access Manager .NET API contents are packaged in a zip file, Bharosa_SDK_DotNet2.0.zip. Contents of this zip file should be extracted to the virtual directory of the web application in which Oracle Adaptive Access Manager should be integrated. The application (project files) must be updated to add references to the SDK DLLS.

3.3 Application Configuration

Web.config, located in the virtual/root directory of the web application, is the configuration file for web applications. Update Web.config to include the BharosaSOAPURL setting in the <appSettings> section. The BharosaSOAPURL setting should be set to the SOAP URL to access the Adaptive Risk Manager SOAP services, as shown below:

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

3.4 Properties

The Oracle Adaptive Access Manager .NET SDK contains properties files that contain the default values. Each deployment can update certain properties to specify deployment specific values.

The Oracle Adaptive Access Manager .NET API uses properties to read configurable values at runtime, like the location of images for authenticators, and others. Properties are read and cached from a list of files at startup and also whenever one of the loaded properties files is updated. Details of how the properties files are loaded by Oracle Adaptive Access Manager .NET API is given below:

The properties files, including lookup.properties, will be searched in the following directories, in the given order. The search will stop when the file is found in one of these directories.

Table 3-1 Directories Searched for Properties Files

Directory description 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.5 User-Defined Enumeration

User-defined enums are a collection of properties that represent a list of items. Each element in the list may contain several different attributes. The definition of a user-defined enum begins with a property ending in the keyword ".enum" and has a value describing the use of the user-defined enum. Each element definition then starts with the same property name as the enum, and adds on an element name and has a value of a unique integer as an ID. The attributes of the element follow the same pattern, beginning with the property name of the element, followed by the attribute name, with the appropriate value for that attribute.

API Usage sample

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

3.6 Users

Oracle Adaptive Access Manager stores various details of users in its database and uses this information for example, to determine the risk rules to run for a user, to find user specific authenticator attributes, to present the user with a challenge question and validate the answer, and so on.

The client application is responsible for populating Oracle Adaptive Access Manager with the user details at runtime. For example, when a user logs in, the client application should first determine whether the user record exists in Oracle Adaptive Access Manager; if the user record does not exist, appropriate APIs should be called to create the user record and set the user's status. The sample below demonstrates an application calling Oracle Adaptive Access Manager APIs to deal with the user data.

For more usage scenarios and the details, please refer to the sample applications at the end of this chapter.

API Usage sample:

string loginId = "testuser";  // loginId of the user logging in
 
IBharosaProxy proxy = BharosaClientFactory.getProxyInstance();
 
//
// find the user record in OAAM
//
VCryptAuthUser user = proxy.getUserByLoginId(loginId);
 
//
// if user does not exist in OAAM - create
//
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;

The Proxy is the interface to access Adaptive Risk Manager SOAP server services.

3.7 Adaptive Risk Manager

Adaptive Risk Manager is a component of Oracle Adaptive Access Manager. Adaptive Risk Manager provides APIs to capture user login information, user login status, and various attributes of the user session to determine device and location information. Adaptive Risk Manager also provides APIs to collect transaction details.

API Usage sample:

//
// 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 username/password has been validated by now, set the status
// below to appropriate value: success/wrong_Password/invalid_user.
// if username/password has not yet been validated, set the status to 
// pending; after validation is done call updateLog() again with
// the updated 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 component of Adaptive Risk Manager provides APIs for policy execution and enforcement. The Rules Engine can be viewed as an enforcement component of the Adaptive Risk Manager. Based on the calling context, various policies and models are evaluated and the results are provided. The policies and models are configured by the administrators.

API Usage sample:

The following sample code demonstrates the use of APIs to run rules in post-auth runtime and process the rule 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.8.1 Device ID Evaluation

Along with rule results, the Rules Engine component can return a Device Id. The Device Id that is returned by the Rules Engine API is an internal identifier within Adaptive Risk Manager. It is the same Id shown in Adaptive Risk Manager for the user session.

A sample algorithm to get the Device Id is shown below:

VCryptRulesResult rulesResult = new VCryptRulesEngineImpl().processRules(<params..>);
 
If (!rulesResult.getVCryptResponse().isSuccess()) {
 
     Logger.error("Error running rules " + rulesResult.getVCryptResponse().getErrorMessage());
 
}
 
Long deviceId = VCryptRulesResult#getDeviceId();

Troubleshooting:

  • Make sure the Adaptive Risk Manager version is 10.1.4.5 or above

  • The following property must be set to true for the Device Id to be captured.

    bharosa.tracker.send.deviceId=true

3.8.2 Create Transactions in Bulk

The Rules Engine component can create transactions in bulk.

A sample algorithm to create transactions in bulk is shown below:

/**
     * API To create a Transactions in bulk
     * Return response object for each create request
     *
     * @param transactionCreateRequestData requestId / Session Id, required
     * @return VCryptResponse Array of response objects. Each request will have corresponding response. Check isSuccess on each response object
     * @since 10.1.4.5.2
     */
    public VCryptResponse[] createTransactions(TransactionCreateRequestData[] transactionCreateRequestData);

3.8.3 Update Transactions in Bulk

The Rules Engine component can update transactions in bulk.

A sample algorithm to update transactions in bulk is shown below:

/**
     * API to update Transactions in bulk
     * If there are errors in any update, will proceed with next transaction and return response for each request
     *      
     * @param transactionUpdateRequestData array of update Request object
     * @return VCryptResponse Array of response objects. Each request will have corresponding response. Check isSuccess on each response object
     * @since 10.1.4.5.2
     */
    public VCryptResponse[] updateTransactions(TransactionUpdateRequestData[] transactionUpdateRequestData);

3.9 Challenge Questions

Oracle Adaptive Access Manager can be configured to challenge the user with pre-registered questions during high risk/suspicious scenarios. In a typical deployment, users will be asked to pick three questions from a given set of questions and register answers for them. Oracle Adaptive Access Manager expects the user to enter a correct answer for one of the registered questions at the time of the challenge.

The following sample code shows the API to be used during the registration and challenge process. Please refer to the sample application for more details on using various Oracle Adaptive Access Manager APIs to support Knowledge Based Authentication (KBA) scenarios.

API Usage sample:

//
//  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);
 
//
// Please refer to the sample application for details on displaying the
// questions in the UI and processing the user input; let us assume
// that user selected questions and answers are now in questions object
//
 
//
// Register the questions and answers with OAAM
//
VCryptResponse response = proxy.addQuestions(
                                         user.CustomerId, questions);
 
 
//
// Retrive the question to show the user during challenge
//
VCryptQuestion secretQuestion = proxy.getSecretQuestion(
                                                     user.CustomerId);
//
// Create QuestionPad authenticator to display the question text.
// Please refer to the sample application for details; let us here
// assume that the user entered answer is stroed in string answer
//
 
//
// Validate the user entered answer
//
VCryptAuthResult res = proxy.authenticateQuestion(customerId, answer);
 
bool isValid = (res != null && res.ResultCode == 0);

3.10 Reset Challenge Failure Counters

The API to reset failure counters for a given user or user and question combination is shown below. It is applicable when the KBA module is enabled. Adaptive Risk Manager stores the failure counters for the user questions. Failure counters are used to enforce lock. If a question id is sent, failure counters associated with the question are reset. If no question id is sent, failure counters for all questions are reset.

/**
 
     * Reset Challenge failure counters for the given customerid
 
     * @param requestId to track the request
 
     * @param customerId external customer id, required and used to identify customer uniquely, it is not login Id
 
     * @param questionId optional, if sent, failure counters for the given question id are reset 
 
     * @return The response from the server. check isSuccess() for success
 
     */
 
    public VCryptResponse resetChallengeFailureCounters(final String requestId, final String customerId, final Long questionId);

3.11 Authenticators

This section gives details on creating and using the authenticators in ASP.NET applications.

3.11.1 Creating an Authenticator

Use BharosaClient.getAuthentiPad() to generate the .NET authenticator object, as shown below:

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; this will be needed
    // - in GetImage.aspx.cs to generate the authenticator image 
    // - while decoding the user input
    //
    sessionData[padName] = authPad;
}

3.11.2 Embedding an Authenticator in a Web Page

The .ASPX file and the code behind file (ASPX.CS for C#) need to be updated, as shown below, to display the authenticator created in the previous section:

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

  2. Create a label in the ASPX file where the authenticator is to be displayed, as shown below:

    <asp:Label ID="authenticator" runat="server"></asp:Label>

  3. Generate the HTML in the code behind file (ASPX.CS) from the authenticator object and assign to the label, as shown below:

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

3.11.3 Decoding User Input

The user-entered input in the authenticator is posted to the application in the HTTP parameter named padName + "DataField". This input should be decoded using the authenticator as shown below:

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

3.12 Specifying Credentials to Access Adaptive Risk Manager SOAP Services

The credentials to access Adaptive Risk Manager Soap services can be specified in one of the following ways.

When the second option above is used to specify SOAP credentials, the encrypted value can be specified. For details on encrypting the property values, please refer to the section below.

3.13 Encrypting Property Values

Property value in the properties files used by Oracle Adaptive Access Manager .NET DLLs can be encrypted using command-line utility BharosaUtils.exe, which is included in the Oracle Adaptive Access Manager .NET API package. A user-selected encryption key is required to encrypt and decrypt the properties. The key used to encrypt the properties must be available to Oracle Adaptive Access Manager .NET API through the property, "bharosa.cipher.client.key," that is, this property must be set in one of the properties files used by the application. BharosaUtil.exe prompts the user to interactively enter the encryption key and the value to be encrypted. The encrypted value is output to the console. The encrypted value can be used in the properties file, instead of the plain text value.

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

3.14 Troubleshooting

The Oracle Adaptive Access Manager .NET API can be configured to print trace messages of various levels using diagnostics switches in Web.config. The tracing can be configured to print to a file by configuring appropriate listeners. The following XML demonstrates the trace switches supported by the Oracle Adaptive Access Manager .NET API and a sample listener configuration that writes 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 Applications

The following four ASP.NET applications are included in the sample package to demonstrate the integration of various Oracle Adaptive Access Manager features in ASP.NET based applications.

Table 3-2 ASP.NET applications samples

Application name Description

SampleWebApp

This is a plain ASP.NET application with no Oracle Adaptive Access Manager integration. This application is provided so that the reader can easily see incremental changes required to integrate various Oracle Adaptive Access Manager features - like Adaptive Risk Manager, authenticator, KBA.

SampleWebAppWithTracker

This application demonstrates the integration of the Oracle Adaptive Access Manager-Adaptive Risk Manager functionality with SampleWebApp, which is listed above.

SampleWebAppWithAuthTracker

This application demonstrates the integration of the Oracle Adaptive Access Manager-Adaptive Risk Manager and authenticator functionalities with SampleWebApp, which is listed above.

SampleWebAppWithKBATracker

This application demonstrates the integration of the Oracle Adaptive Access Manager-Adaptive Risk Manager and KBA functionalities with SampleWebApp, which is listed above.

The 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 solutions file, "SampleWebApps," can be used to load and view all applications together. This section highlights the content of each application.

A few tips are listed below to set up the environment to successfully run the samples.

Ensure that the SOAP URL to access the Adaptive Risk Manager server is set correctly in the web.config file of the application, as per your deployment configuration. A sample is shown below:

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

Make sure that the Adaptive Risk Manager server used with these applications is loaded with the models contained in models.zip.

Make sure that both the Adaptive Risk Manager server and the web applications are configured to look for authenticator images in the same directory paths. The following properties should be set:

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

3.16 SampleWebApp

This application contains the following pages, which demonstrates a web application before an Oracle Adaptive Access Manager integration.

3.17 SampleWebAppWithTracker

This application contains the following pages, which demonstrate the integration of Oracle Adaptive Access Manager-Adaptive Risk Manager functionality with the sample application listed above.

This application requires the integration of the Oracle Adaptive Access Manager .NET APIs found in the SDK package, Bharosa_SDK_DotNet2.0.zip. The content of the archive needs to be extracted to the root directory of the web application.

3.18 SampleWebAppAuthTracker

This application contains the following pages that demonstrate integration of Oracle Adaptive Access Manager authenticator and Adaptive Risk Manager functionalities to the sample application listed above. This application collects the password using authenticators offered by Oracle Adaptive Access Manager.

This application requires the integration of the Oracle Adaptive Access Manager .NET APIs found in the SDK package, Bharosa_SDK_DotNet2.0.zip. The content of the archive needs to be extracted to the root directory of the web application.

3.19 SampleKBATracker

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

This application requires the integration of the Oracle Adaptive Access Manager .NET APIs found in the SDK package Bharosa_SDK_DotNet2.0.zip. The content of the archive needs to be extracted to the root directory of the web application.

Go to previous page
Previous		 Go to next page
Next
Go to Documentation Home
Home		 Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Index
Index		 Go to Feedback page
Contact Us