ASP.NET applications can integrate with Oracle Adaptive Access Manager using the .NET API provided by Oracle Adaptive Access Manager to add various OAAM feature, such as, virtual authentication devices, and KBA, and the OAAM Risk Engine.
This chapter provides details on how to use the OAAM .NET API for integrating ASP .NET applications. Descriptions are also provided on the OAAM sample applications, which illustrate the integration of different OAAM features with a basic Web application.
Note:
Although you can still use the DLLs in Oracle Adaptive Access Manager .NET integration, they are deprecated starting with 11.1.2.2 and will be desupported and no longer shipped in 12c. The recommendation is to use SOAP or Java API integration. For information about SOAP and Java API integration, see Chapter 2, "Natively Integrating Oracle Adaptive Access Manager" and Chapter 4, "Natively Integrating Java Applications."This chapter contains the following sections:
ASP.NET is a Web application framework that allows programmers to build dynamic websites, Web applications, and Web services. OAAM provides an OAAM .NET development kit (SDK). The OAAM .NET SDK is used 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 OAAM uses to collect the 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.
The .NET-based OAAM Sample application that illustrates .NET API integration can be downloaded from My Oracle Support.
OAAM .NET SDK is packaged in oaam_native_dot_net.zip in $ORACLE_HOME/oaam/oaam_libs/dotNet/.
The sample .NET applications that enable OAAM features require the integration of the OAAM .NET APIs found in the SDK package. The developer must extract the content of the archive to the root directory of the web application.
The OAAM .NET libraries are located in the /bin directory in the extracted SDK package.
The Oracle Adaptive Access Manager .NET SDK includes property files that specify values for the configuration used by the OAAM .NET API. A developer can modify these properties to specify application-specific values or add new ones.
The OAAM .NET API uses properties to read configurable values at run time, 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 the OAAM .NET API as follows:
The lookup.properties file, if present, is loaded first.
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).
The bharosa_lookup.properties file, if present, is loaded.
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)
All files in the queue are loaded.
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.
| 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/ |
A property value specified in a properties file can be encrypted using the command-line utility BharosaUtils.exe included in the OAAM .NET SDK. BharosaUtils.exe can be found at the /bin directory after extracting OAAM .NET SDK package.
An encryption key (arbitrarily selected by the user) is required to encrypt and decrypt values. This key is available to the OAAM .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 outputted 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-encrypt Enter text to be encrypted again: string-to-encrypt vCCKC19d14a39hQSKSirXSiWfgbaVG5SKIg==
Visual Studio 2005 enables you to use enumerations defined in the .NET Framework. 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
An example of a user-defined enumeration is presented below.
#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
An example of the use of the previous user-defined enumeration in application code is shown as follows:
UserDefEnumFactory factory = UserDefEnumFactory.getInstance();
UserDefEnum statusEnum = factory.getEnum("auth.status.enum");
int statusSuccess = statusEnum.getElementValue("success");
int statusWrongPassword = statusEnum.getElementValue("wrong_password");
This section contains details on how you can use OAAM APIs to support common OAAM scenarios. You can also refer to the OAAM sample applications for 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 run time.
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);
//createUser API calls OAAM Server to create a user in database. New user will be
//returned.
// 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 more details, see the OAAM sample applications listed in Section 3.5.2, "About the ASP.NET Applications."
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.
Some APIs are:
handletrackerRequest(): creates the signatures required to fingerprint the device
updateLog(): Updates the user node log and if required, creates the CookieSet also.
createTransaction(): creates a data entry for the transaction at OAAM Server
updateTransaction(): updates a given transaction
updateTransactionStatus(): updates the status of a transaction in OAAM Server
markDeviceSafe(): marks the device to be safe when needed
isDeviceMarkedSafe(): checks whether the device has been marked safe
The following code sample illustrates the use of this updateLog() 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);
}
By calling the updateLog() API, user information, with browser/flash fingerprint information, will be sent to the OAAM Server through a SOAP call. OAAM Server will return a new fingerprint cookie if fingerprint information being sent matches the values stored at the OAAM Server. If the user information has not been obtained, OAAM uses the handleTrackerRequest() API to collect device information as used in the OAAM Sample .NET Application.
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 Administering 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
}
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
You can use the IBharosaProxy.createTransactions() method to create bulk transactions, as illustrated in the following call:
VCrypResponse[] createTransactions(TransactionCreateRequestData[] transactionCreateRequestData);
You can use the IBharosaProxy.updateTransactions() method to update bulk transactions, as illustrated in the following call:
VCrypResponse[] updateTransactions(TransactionUpdateRequestData[] transactionUpdateRequestData);
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 code example 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 OAAM sample application in Integration Example Using the Sample
// Applications
// for details on displaying the questions in the UI and processing the user input
// 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 Integration Example Using the Sample Applications;
// 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 OAAM sample applications listed in Section 3.5.2, "About the ASP.NET Applications."
Oracle Adaptive Access Manager records the number of wrong answers to the questions posed to the user in the failure counters. Oracle Adaptive Access Manager uses failure counters 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 (for example, 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);
This section describes the creation and use of virtual authentication devices in ASP.NET applications in the following subsections:
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;
}
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:
Include the JavaScript bharosa_web/js/bharosa_pad.js in the ASPX file.
Create a label in the ASPX file where the virtual authentication device is to be displayed:
<asp:Label ID="authenticator" runat="server"></asp:Label>
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);
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
}
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)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>
The .Net API supports X.509 SSL certificate configuration when using SOAP to call the OAAM server. If you have an OAAM server deployed in an environment that requires an X.509 certificate in the SSL authentication process(or 2-way SSL), use the following APIs to add/remove the certificate to the OAAM .NET SOAP client.
For .NET 2.0, the APIs in the Bharosa.VCrypt.ClientIBharosaProxy interface are:
void AddClientCertificate()
void AddClientCertificate(X509Certificate clientCert)
void AddClientCertificate(string certFilePath, string password)
void RemoveClientCertificate(X509Certificate clientCert)
The properties to enable adding and removing of the X.509 SSL certificates when making SOAP calls to the OAAM Server when two-way SSL is required are documented below. You must set the SOAP user/password and group according to the configuration.
<add key="BharosaSOAPURL"
value="https:{OAAM SOAP SERVICE URL}"/>
<add key="BharosaSOAPUser" value="ruleAdmin1"/>
<add key="BharosaSOAPPassword" value="welcome1"/>
<add key="BharosaSOAPDomain" value="OAAM_Webservices_Group"/>
<add key="BharosaSOAPTrustAllServerCert" value="true"/>
<add key="BharosaSOAPClientCertFilePath"
value="path/to/the/client/certificate/file"/>
<add key="BharosaSOAPClientCertFilePassword"
value="{password to open client certificate file}"/>
Use "<add key="BharosaSOAPTrustAllServerCert" value="true"/>' only for debug/development purpose to let the .NET SOAP client accept all server-side SSL certificate during the SSL authentication process. Do not use the property in a production environment.
The .NET-based Sample application for OAAM is provided as a reference to illustrate how to integrate an application. This section provides details on the contents and flow each OAAM application demonstrates.
The .NET-based OAAM Sample application that illustrates .NET API integration can be downloaded from My Oracle Support.
The OAAM Sample applications are for demonstration purposes to familiarize you with OAAM APIs. They are not intended to be used as production code since they only provide basic elements of API usage. If you are implementing a .NET integration, you can develop your application using the OAAM Sample applications as 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.
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 |
|---|---|
|
|
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, virtual authentication devices, and KBA. |
|
|
This application demonstrates integration of Oracle Adaptive Access Manager Risk Engine to SampleWebApp. |
|
|
This application demonstrates integration of Oracle Adaptive Access Manager Risk Engine and virtual authentication device to SampleWebApp. |
|
|
This application demonstrates integration of the Oracle Adaptive Access Manager Risk Engine and KBA to SampleWebApp. |
Details about the four applications are provided in this section.
This application contains the following pages that demonstrate a web application before OAAM integration.
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
Success.aspx
Displays Successfully logged in message with a link for logout
LogoutPage.aspx
Logs out the user session and redirects to login page
This application contains the following pages that demonstrate integration of the Oracle Adaptive Access Manager Risk Engine to the OAAM sample application listed prior. The Oracle Adaptive Access Manager Risk Engine helps the OAAM server collect multiple kinds of user information including the User ID entered, device fingerprint collected by the OAAM embedded flash movie, IP information, and so on. The integrated web application could call appropriate SOAP APIs at the required checkpoint. OAAM Server will run pre-defined authentication rules on collected information according to authentication rules defined through the OAAM Admin console. The authentication result will be returned so that the protected web application could take corresponding actions accordingly.
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 must be extracted to the root directory of the web application.
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 fingerprint of the user device
LoginJumpPage.aspx
Loads the user from OAAM by calling AppUtil.InitUser() (AppUtil is included in the SDK package). If the user is not found, a new user record will be created. By calling BharosaClientFactory.getProxyInstance(), OAAM gets a reference to the IBharosaProxy interface. This interface exposes the multiple OAAM .NET SOAP APIs for integrating .NET applications. APIs call in AppUtil.InitUser(): getUserByLoginId(), getUser(), createUser(), setUserStatus(), getUserStatus(), and setPin().
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 fingerprint details. CookieManager.aspx records the fingerprint in OAAM 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 OAAM), redirects the browser to LoginHandlerPage.aspx
LoginHandlerPage.aspx
Records the user login attempt with OAAM by calling AppUtil.InitTracker()
Validates the login and password information
Updates OAAM with the password validation status (success/wrong user/wrong password/disabled user, and so on) 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 OAAM 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
Success Page
Displays Successfully logged in message with a link for logout
Logout Page
Logs out the user session and redirects to login page
This application contains the following pages that demonstrate integration of Oracle Adaptive Access Manager Risk Engine and a virtual authentication device to the OAAM sample application listed prior. This application collects the password using authenticators offered by OAAM.
Authenticator functionality refers to the use of the OAAM Virtual Authentication Device used to collect credentials. By calling the OAAM .NET API to run the pre-authentication rule, a user might be blocked before he can see the OAAM virtual authentication device. By running the Authentipad rule, the OAAM Virtual Authentication Device will be selected/created for the user and rendered on the password page.
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 must be extracted to the root directory of the web application.
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 fingerprint of the user device
LoginJumpPage.aspx
Loads the user from OAAM 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 fingerprint details. CookieManager.aspx records the fingerprint in OAAM 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 OAAM), redirects the browser to LoginHandlerPage.aspx
LoginHandlerPage.aspx
Records the user login attempt with OAAM by calling AppUtil.InitTracker()
Redirects the user to PasswordPage.aspx to collect the password using OAAM authenticator.
PasswordPage.aspx
On Load:
Sets the session authentication status to Pending in OAAM
Runs pre-authentication rules by calling the AppUtil.RunPreAuthRules()
If the pre-authentication rules return block, blocks the user login after updating OAAM with this information
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()
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)
Stores the authenticator object in the session for later use during image generation and password decode
On PostBack:
Decodes the password using the authenticator object stored in the session
Validates the login and password information
Updates OAAM with the password validation status (success/wrong user/wrong password/disabled user, and others) 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 OAAM 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
Success Page
Displays Successfully logged in message with a link for logout
Logout Page
Logs out the user session and redirects to login page
This application contains the following pages that demonstrate integration of OAAM authenticator, risk engine, and KBA and KBA (Knowledge Based Authentication) to the OAAM sample application listed prior. This application shows authentication mechanisms using password and KBA authenticators offered by OAAM. OAAM KBA enables the ability to let the user register challenge questions and challenge the user at some point. For example, based upon the result of post-authentication rules, the integrated web application could decide to challenge a user using registered question/answer pairs.
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 must be extracted to the root directory of the web application.
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 fingerprint of the user device
LoginJumpPage.aspx
Loads the user from OAAM 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 fingerprint details. CookieManager.aspx records the fingerprint in OAAM 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 OAAM), redirects the browser to LoginHandlerPage.aspx
LoginHandlerPage.aspx
Records the user login attempt with OAAM by calling AppUtil.InitTracker()
Redirects the user to PasswordPage.aspx to collect the password using OAAM authenticator
PasswordPage.aspx
On Load:
Sets the session authentication status to Pending in OAAM
Runs pre-authentication rules by calling the AppUtil.RunPreAuthRules()
If the pre-authentication rules return block, blocks the user login after updating OAAM with this information
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()
Creates the 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)
Stores the authenticator object in the session for later use during image generation and password decode
On PostBack:
Decodes the password using the authenticator object stored in the session
Validates the login and password information
Updates OAAM with the password validation status (success/wrong user/wrong password/disabled user, and others) by calling AppUtil.UpdateAuthStatus()
If the password validation fails, the user will be redirected to LoginPage.aspx with appropriate error message
If password validation succeeds, runs post-authentication rules by calling AppUtil.RunPostAuthRules()
The user will be taken through different flows depending on 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 |
PersonalizationPage.aspx
Introduces the user to device personalization explaining the steps that would follow to create a 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
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()
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()
ChallengeUser.aspx
Challenges the user by displaying a QuestionPad with one of the questions already registered by the user
The answer is validated by calling proxy.authenticateQuestion() and the result is updated in OAAM 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 reenter the answer or be redirected to the block page after updating the block status in OAAM
The number of attempts that a user gets to answer a question correctly is set by the rule administrator for OAAM
On successfully answering the question correctly, the user is forwarded to the Success.aspx page
Success Page
Displays Successfully logged in message with a link for logout
Logout Page
Logs out the user session and redirects to login page
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 Internet Information Server (IIS) 6.0 on Windows Server 2003. You can use SampleWebApps to load and view all applications together using Visual Studio.
Instructions to set up the environment to successfully run the OAAM sample applications are provided in this section. After all the following have been applied, you should be able to run these OAAM sample applications and see how they integrate with OAAM 11g in different scenarios.
Ensure that SOAP URL to access OAAM server is set correctly in the web.config file of the application, according to your deployment configuration. An example is shown as follows:
<appSettings>
<add key="BharosaSOAPURL"
value="http://localhost:14300/oaam_server/services"/>
</appSettings>
<appSettings>
For OAAM sample applications integration with OAAM 11g, set bharosa.image.dirlist in bharosa_app.properties to the path where oaam_images directory could be found. The default value is: ${oracle.oaam.home}/oaam_images. The oaam_images directory includes images that OAAM will use to generate a virtual authentication device.
The directory 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 directory named oaam_images and this directory is under the root directory of the web application, the path should be: ${Application_HOME}/oaam_images/
Make sure lookup.properties is created/contained in the /bharosa_properties/ directory, which should list all the properties files that need to be read. It can be obtained from:
${ORACLE_HOME}/oaam/apps/oaam_native/overrides/conf/bharosa_properties
Find and comment out the bharosa.authentipad.image.url property.
For developers who have access to Microsoft Visual Studio 2005 to test the web applications, build the solution after making all the prior changes and debug it.
For deployment of these applications, follow these guidelines:
The system should be Windows Server 2003
The application server should be installed using Control Panel > Add or Remove Programs > Add/Remove Windows Components. Microsoft Internet Information Server (IIS) and ASP.NET should be enabled
Create a new website using Internet Information Services (IIS) Manager by running inetmgr in the command window
Ensure that the ASP.NET version is set to version 2.0 through the ASP.NET tab in the website's properties;
Ensure that ASP.NET version 2.0 is set to allowed in Internet Information Services (IIS) Manager. If there is no ASP.NET version 2.0 extension, add a new web service extension manually. Go to C:\WINDOWS\Microsoft.NET\Framework, there should be a directory named v2.0.50727 or similar if ASP.NET version 2.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, select Local System on the right of the Predefined option if there is a problem accessing C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\Temporary ASP.NET Files when opening web application pages.
The following pages demonstrate how to enable transaction logging and rule processing in OAAM Admin using the ASP.NET sample applications.
Transaction definitions in Sample_Transaction_Defs.zip need to be available in Oracle Admin. Import the transaction definitions using OAAM Admin.
Transaction policies defined in models.zip should be available in OAAM Admin
Following properties must exist in bharosa_app.properties at the OAAM Admin and the .NET client side:
Enumeration for Transaction Status
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
Enumeration for Checkpoints
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
Admin Options for the 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.
For more information on the APIs listed in this section, see Java API Reference for Oracle Adaptive Access Manager.
Note:
isElementInList(), getListElements() and updateList() APIs do not support update and other actions in the alert group lists.Table 3-3 describes the .NET APIs available in OAAM.
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 Java API Reference for Oracle Adaptive Access Manager.| API | Description |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Reads " Supports X.509 SSL certificate configuration when using SOAP to call the OAAM server. |
|
|
Adds the given X.509 certificate to the SOAP client. Supports X.509 SSL certificate configuration when using SOAP to call the OAAM server. |
|
|
Gets the certificate in the given file path using the given password and then adds the certificate to the SOAP client. Supports x.509 SSL certificate configuration when using SOAP to call the OAAM server. |
|
|
Removes the given certificate from the SOAP client if it is under the .NET framework Supports x.509 SSL certificate configuration when using SOAP to call the OAAM server. |