This chapter describes how to extend device identification in a typical deployment. It includes the following sections:
A device is a computer, PDA, cell phone, kiosk, and so on, a user uses to login from a location. A Device ID is an internal Oracle Adaptive Access Manager identifier for the device used for the login session. This section provides information on the process of identifying the device and assigning a Device ID to it.
The process involves three stages:
Data Gathering
Data Processing
Data Storage
Device identification is a mechanism to recognize the devices a customer uses. The fingerprint details can help in identifying a device, check whether it is secure, and determine the risk level for the authentication or transaction. During the login process, data is collected such as browser type, browser headers, operating system type, locale, and so on from the device fingerprint.
There are two categories of data: secure and digital. Each of these categories have within them a fingerprint and a cookie. Oracle Adaptive Access Manager uses two types of cookies to perform device identification. One is the secure cookie (also known as browser cookie) and the other is the digital cookie (also known as the flash cookie).
Secure data is gathered from the user's browser. This data includes the user-agent string, and an HTTP cookie value. The User-Agent is used as the secure fingerprint. The HTTP cookie value is a unique one-time use cookie that is set every time a user logs in. This cookie value is retrieved from the user's browser upon login.
Digital data is gathered from the user's Adobe Flash installation. This data includes an array of Flash system capability data, and a Flash Locally Stored Object (LSO). The Flash capability data is used as the digital fingerprint representing the Flash system capabilities. The LSO contains a unique one-time use value that is set every time a user logs in. This value is retrieved using a flash object that runs upon login.
An example of data gathering flow is:
User enters user name.
Login jump page is displayed. This second login page is a transient page to capture the flash and secure cookies and for fingerprinting the user device.
Pre-authentication checkpoint. Pre-authentication rules are run before the user is authenticated. Common values returned by the pre-authentication checkpoint include: Allow and Block.
AuthentiPad checkpoint. This stage determines the virtual authentication device to use.
Password page is displayed.
Once this data is gathered, the OAAM Server must process the device fingerprint data and determine if this device has ever been seen before. Oracle Adaptive Access Manager does not solely rely on one element to develop the "device fingerprint". If persistent cookies are disabled, Oracle Adaptive Access Manager still has other information to use in identifying the device. For example, in the case where datapoints are unavailable, the system can still provide robust security utilizing other objects (secure cookie, flash cookie, HTTP header, Real Media, QuickTime, and so on). Based on the presence of the datapoints it determines if this is a new, or existing device.
Device fingerprinting generates a fingerprint for each user session which is unique to the individual's device and which is replaced upon each subsequent visit with another unique fingerprint.
The Device ID is generated when a device matching the data available in the fingerprint cannot be found in the OAAM database. The process of looking for existing devices based on device fingerprint data includes searching for devices with matching rotating cookie values and fingerprints. OAAM weights fingerprint data differently, and the weighting is roughly as follows: Flash Cookie, Flash Fingerprint, Secure Cookie, Secure Fingerprint. If a device is found that matches the criteria, no new device id will be generated.
This process can be augmented, or modified by creating policies in the Device Identification checkpoint. This checkpoint is run during device fingerprinting to allow for additional rules to be processed to influence device identification also assess risk. The risk score that is calculated during the device identification checkpoint evaluation is used as the Device Risk Gradient in the pre-conditions of rules configured in other checkpoint's policies.
The device risk gradient specifies the certainty of the device being identified. It is standard in most rules as a pre-condition. For example, a device risk gradient of 0 is an exact match whereas a device gradient of 500 is a "similar" device, and a score of 1000 a "different" device.
Once a device has been given an ID, new rotating cookie values are generated and set. The secure cookie is set as an HTTP cookie, and the digital cookie is set as a Flash LSO by the flash object. These two values are the only values stored on a user's computer during the device identification process.
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".