This chapter describes how to extend device identification in a typical deployment. It includes the following topics:
For most typical deployments, the out-of-the-box device identification satisfies client requirements. Out-of-the-box device identification uses data from the browser and OAAM flash movie. The following are the typical scenarios when you could consider extending device identification:
The OAAM flash movie cannot be used to obtain client details as the client side browser does not support Flash (example: iPhone, iPad, and so on)
There is a need to extract stronger device identification data from the client using a non-flash plug-in that can run inside the browser
The prerequisites for performing tasks to extend device identification in Oracle Adaptive Access Manager are provided in the following list:
You have knowledge of Java programming language since a custom device identification plug-in has to be developed using Java.
You have determined what pieces of information about client device have to be collected and what technology will be used to collect that. Typical technologies you can consider are applets, JavaScript, and so on.
You understand the process of developing and deploying the OAAM Extensions Shared Library.
The custom device identification plug-in is software that extends the out-of-the-box device identification provided by Oracle Adaptive Access Manager.
Implement the client side plug-in that can run in the client browser. This involves coding the client side plug-in using the appropriate technology.
The client side plug-in should satisfy the following requirements:
It can run on the client side browser without altering the web page. It is invisible and does not alter user control flow.
It can communicate with OAAM Server and post data using the HTTP protocol.
Very Important: It can use the existing OAAM "HTTP Session" while posting the data. This is very important for the device identification to work properly.
The list of data/values that are collected by the plug-in uniquely identifies a client device.
The plug-in can retrieve and store a cookie equivalent on the client machine.
Plug-in can submit the following parameters to flashFingerprint.do URL on OAAM Server using HTTP Post:
Table 14-1 Parameters to flashFingerprint.do URL
| Name of the parameter | Description |
|---|---|
|
client |
Name of the client plug-in. A constant value that indicates the plug-in type. |
|
fp |
Concatenated string that has all the name-value pairs that identify the client side. Name-value pairs is concatenated using "&" and name-value is separated using "=". Example: If os_name and os_version are collected by plug-in then the fp string value looks like "os_name=windows&os_version=7 |
|
<as determined by the implementation> |
Send the cookie equivalent value stored/maintained by the client plug-in. |
Add the following properties as enum element to vcrypt.fingerprint.type.enum to bharosa_server.properties of the OAAM Extensions Shared Library war.
Note: Replace <plug-in-name> with a string that represents your plug-in. Do not use the strings 'flash', 'browser' as they are already used by the OAAM product.
Table 14-2 vcrypt.fingerprint.type.enum elements
| Property Name | Value Description |
|---|---|
|
vcrypt.fingerprint.type.enum.<plugin-name> |
Integer value above 100 |
|
vcrypt.fingerprint.type.enum. <plug-in-name>.name |
Name that represents the plug-in |
|
vcrypt.fingerprint.type.enum. <plug-in-name>.description |
Description of the plug-in |
|
vcrypt.fingerprint.type.enum. <plug-in-name>.processor |
Fully qualified java class name of the processor class that implements device identification logic on the server side. See next section for details on how to implement this class. |
|
vcrypt.fingerprint.type.enum. <plug-in-name>.header_list |
Comma separated list of data that is collected by the client side plug-in. |
|
vcrypt.fingerprint.type.enum. <plug-in-name>.header_name_nv |
Comma separated list of data and readable name of those data. |
|
vcrypt.fingerprint.type.enum. <plug-in-name>. header_value_nv |
Comma separated list of mappings of value to readable string of those values |
|
bharosa.uio.default.device.identification.scheme |
<plug-in-name> Note: This is very important for OAAM to use the custom device identification |
Extend the DeviceIdentification plug-in class: com.bharosa.uio.processor.device.DeviceIdentificationProcessorBase and implement the following methods:
public String getPlugInHTML();
Implementation should return a valid plug-in HTML that can be embedded into login pages. The HTML should take care of handling exceptions like if the supporting technology is not available or disabled on the client.
An example for plug-in HTML is shown below:
<applet alt="Browser has Java disabled" name="OAAMDeviceIdentifier" width="0" height="0"
code="com.bharosa.uio.processor.device.SampleAppletDeviceIdentifierClient"
codebase="applet"
archive="oaam_device_sample_applet.jar">
</applet>
Note: This method is called by the oaamLoginPage.jsp when the user navigates to login page.
public String getFingerPrint();
This method should implement logic that creates a unique fingerprint that identifies the client device using the data sent by the plug-in.
This method is called when the client side plug-in submits device identification data to OAAM Server.
This method should call the UIOContext.getCurrentInstance().getRequest to get handle to HttpServletRequest object to read the data sent by the client plug-in.
As mentioned in the previous section, client plug-in would send list of data points as single string as the value of "fp" request parameter.
This class should "tokenize" this string to determine the list of datapoints and their values.
public String getDigitalCookie();
Implementation should return the digital cookie sent by the client plug-in. It is the responsibility of the client and server to designate an Http parameter that indicates the digital cookie.
This method should call the UIOContext.getCurrentInstance().getRequest to get handle to HttpServletRequest object to read the data sent by the client plug-in.
Following is the overview of how the device identification plug-in works and interacts with OAAM Server:
The user navigates to the OAAM user login page on the OAAM Server.
The OAAM Server uses the device identification configuration and appropriately instantiates the device identification plug-in class. It then asks the plug-in class for the HTML that needs to be embedded in the user login page. The OAAM Server returns the user login page with the device identification plug-in HTML.
Once the login page is rendered, the client based plug-in is activated and collects information about the device.
The client plug-in then submits the collected data to the device identification URL on the OAAM Server.
The OAAM Server then calls the device identification plug-in to obtain the fingerprint based on collected data from the client plug-in.
It then checks if the fingerprint corresponds to an existing device. If not, then it creates a new device and associates the fingerprint to that device.
The OAAM Server then calls the device identification plug-in to get the digital cookie. If digital cookie does not exist then a new one is created.
The digital cookie is returned to the client plug-in so that it is stored on the client machine.
Once the User ID is entered, using the digital cookie or browser cookie or both, the user request is associated to the device.
After the authentication (success/failure), the user request is updated with the authentication result.
If the same device is used for future logins, the digital cookie can be used to look up the device without having to fingerprint.
Compile the custom device identification plug-in class and assemble the OAAM Extensions Shared library. Refer to Chapter 7, "OAAM Extensions and Shared Library to Customize OAAM" for instructions.
When implementing the plug-in, keep the following points in mind:
Make sure the custom device identification class outputs a valid HTML required to activate the client side plug-in.
Make sure the client side plug-in posts the data to OAAM Server using the "existing HTTP Session".