14 Extending Device Identification

This chapter describes how to extend device identification in a typical deployment. It includes the following topics:

14.1 When to Use Extend Device Identification

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

14.2 Prerequisites

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.

14.3 Developing a Custom Device Identification Plug-in

The custom device identification plug-in is software that extends the out-of-the-box device identification provided by Oracle Adaptive Access Manager.

14.3.1 Implement the Client Side Plug-in

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


    Name of the client plug-in. A constant value that indicates the plug-in type.


    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.

14.3.2 Add Properties related to Custom Device Identification Plug-in to OAAM Extensions Shared Library

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


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



Note: This is very important for OAAM to use the custom device identification

14.3.3 Extend/Implement the DeviceIdentification Plug-in class

Extend the DeviceIdentification plug-in class: com.bharosa.uio.processor.device.DeviceIdentificationProcessorBase and implement the following methods: getPlugInHTML

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" 

Note: This method is called by the oaamLoginPage.jsp when the user navigates to login page.

14.3.4 getFingerPrint

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.

14.3.5 getDigitalCookie

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.

14.3.6 getClientDataMap

public Map getClientDataMap(HttpServletRequest request);

Implementation should read the data from request and store it into a map that can be used for logging or auditing purposes.

14.4 Overview of Interactions

Following is the overview of how the device identification plug-in works and interacts with OAAM Server:

  1. The user navigates to the OAAM user login page on the OAAM Server.

  2. 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.

  3. Once the login page is rendered, the client based plug-in is activated and collects information about the device.

  4. The client plug-in then submits the collected data to the device identification URL on the OAAM Server.

  5. The OAAM Server then calls the device identification plug-in to obtain the fingerprint based on collected data from the client plug-in.

  6. 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.

  7. 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.

  8. The digital cookie is returned to the client plug-in so that it is stored on the client machine.

  9. Once the User ID is entered, using the digital cookie or browser cookie or both, the user request is associated to the device.

  10. After the authentication (success/failure), the user request is updated with the authentication result.

  11. If the same device is used for future logins, the digital cookie can be used to look up the device without having to fingerprint.

14.5 Compile, Assemble and Deploy

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.

14.6 Important Note About Implementing the Plug-In

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".