This chapter describes how to extend device identification in a typical deployment. It includes the following sections:
For most typical deployments, the out-of-the-box device identification satisfies client requirements, but you may be looking to have the ability to extend that process and include additional information in the fingerprint. 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. For example, iPhone, iPad, and so on.
There is a need to extract stronger device identification data from the client using a non-flash extension that can run inside the browser
Starting from the 11.1.1.5 release of OAAM a framework exists that you can use to extend device identification and implement in both native integrations, and non-native integrations. The framework is separated into the client side extension, and the OAAM server device identification extension.
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 extension 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. For information on using the OAAM Extensions Shared Library, see Chapter 7, "Using the OAAM Extensions Shared Library to Customize OAAM."
The custom device identification extension is software that extends the out-of-the-box device identification provided by Oracle Adaptive Access Manager.
Implementing the client side extension that can run in the client browser involves coding the extension using the appropriate technology.
The client side extension can be implemented in any technology if it can 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.
The technology chosen to implement the client side extension must run in the context of the user's browser. Technologies such as Flash, JavaScript, Java Applets are typical choices.
It can communicate with OAAM Server and post data using the HTTP protocol.
The fingerprint data and rotating cookie must be sent to the OAAM server if the standard integration is using the HTTP POST method.
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 data sent to the server must be sent in the context of the user's session in order for the fingerprinting data to be associated with the user's login. The presence of a valid JSESSIONID is required for this to work.
The list of data/values that are collected by the extension uniquely identifies a client device.
In general the fingerprints collected by OAAM should be as unique as possible given the data constraints imposed by the user's device. When extending device identification, this is the best opportunity to gather additional data to uniquely identify a user's device.
The extension can retrieve and store a cookie equivalent on the client computer.
The concept of a rotating one time use cookie is core to the device fingerprinting process. The device identification must support the capability to store and retrieve the value provided to the extension by the OAAM server.
The extension can submit the following parameters to flashFingerprint.do URL on OAAM Server using HTTP Post:
Note: This requirement is only relevant when using the standard OAAM implementation.
Table 13-1 Parameters to flashFingerprint.do URL
| Name of the parameter | Description |
|---|---|
|
client |
Name of the client extension. A constant value that indicates the extension 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 extension 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 extension. |
The static values are related to the properties that need to be defined within the OAAM Server to make it aware of the new extension.
To create custom fingerprint types, proceed as follows:
Open the oaam_custom.properties file of the OAAM Extensions Shared Library war.
Add the following properties as enum element to vcrypt.fingerprint.type.enum.
Note: Replace extension-name with a string that represents your extension. Do not use the strings 'flash', 'browser' as they are already used by the OAAM product.
Table 13-2 vcrypt.fingerprint.type.enum elements
| Property Name | Value Description |
|---|---|
|
|
Integer value above 100 |
|
|
Name that represents the extension |
|
|
Description of the extension |
|
|
Fully qualified java class name of the processor class that implements device identification logic on the server side. See the next section for details on how to implement this class. |
|
|
Comma separated list of data that is collected by the client side extension. |
|
|
Comma separated list of data and readable name of those data. |
|
|
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 |
Set the fingerprint scheme to the fingerprint type enum element ID/key.
For example:
bharosa.uio.default.device.identification.scheme=flash
The following flash fingerprint type is shown as an example.
vcrypt.fingerprint.type.enum.flash=2
vcrypt.fingerprint.type.enum.flash.name=Flash
vcrypt.fingerprint.type.enum.flash.description=Flash
vcrypt.fingerprint.type.enum.flash.processor=
com.bharosa.uio.processor.device.FlashDeviceIdentificationProcessor
vcrypt.fingerprint.type.enum.flash.header_list=
avd,acc,a,ae,ev,ime,mp3,pr,sb,sp,sa,sv,tls,ve,deb,l,lfd,m,os,ar,pt,col,dp,r,v
vcrypt.fingerprint.type.enum.flash.search_list=deb,l,os,v
vcrypt.fingerprint.type.enum.flash.result_list=deb,l,os,v
vcrypt.fingerprint.type.enum.flash.header_name_nv=
avd,Audio/Video disabled by user,acc,Has accessibility,
a,Has audio,ae,Had audio encoder,ev,Embedded video,
ime, Has input method editor (IME) installed,
mp3, Has MP3, pr, Supports printer,
sb, Supports screen broadcast applications,
sp, Supports playback on screen broadcast applications,
sa, Supports streaming audio,
sv, Supports streaming video, tls, Supports native SSL,
ve, Contains video encoder, deb, Debug version, l, Language, lfd,
Is local file read disabled, m, Manufacturer, os, Operating System,
ar, Aspect ratio of screen, pt, Player type, col, Is screen color,
dp, Dots-per-inch (DPI), r, Screen resolution, v, Flash version
#vcrypt.fingerprint.type.enum.flash.header_value_nv=t,true,f,false
vcrypt.fingerprint.type.enum.flash.header_value_nv=
t,true,f,false,en,English,es,Spanish,de,German,it,Italian,ja,Japanese,
fr,French,ko,Korean,zh,Chinese,ar,Arabic,cs,Czech,
da,Danish,nl,Dutch,fi,Finnish,el,Greek,iw,Hebrew,hu,Hungarian,
no,Norwegian,pl,Polish,pt,Portuguese,ro,Romanian,ru,Russian,
sk,Slovak,sv,Swedish,th,Thai,tr,Turkish,BR,Brazil
Extend the DeviceIdentification extension class: com.bharosa.uio.processor.device.DeviceIdentificationProcessorBase and implement the methods documented in this section. The server-side extension extends all of the required methods.
public String getPlugInHTML();
Implementation should return a valid extension 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 of extension HTML is shown as follows:
<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 extension.
This method is called when the client side extension 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 extension.
As mentioned in the previous section, client extension 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 extension. 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 extension.
Following is the overview of how the device identification extension 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 extension class. It then asks the extension class for the HTML that must be embedded in the user login page. The OAAM Server returns the user login page with the device identification extension HTML.
Once the login page is rendered, the client based extension is activated and collects information about the device.
The client extension then submits the collected data to the device identification URL on the OAAM Server.
The OAAM Server then calls the device identification extension to obtain the fingerprint based on collected data from the client extension.
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 extension 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 extension so that it is stored on the client system.
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, you can use the digital cookie to look up the device without having to fingerprint.
Compile the custom device identification extension class and assemble the OAAM Extensions Shared library. For instructions on deploying the OAAM extensions shared library, see Chapter 7, "Using the OAAM Extensions Shared Library to Customize OAAM."
When implementing the extension, keep the following points in mind:
Make sure the custom device identification class outputs a valid HTML required to activate the client side extension.
Make sure the client side extension posts the data to OAAM Server using the "existing HTTP Session".