RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide Contact Information Go to the RSA corporate web site for regional Customer Support telephone and fax numbers: www.rsa.com Trademarks RSA, the RSA Logo and EMC are either registered trademarks or trademarks of EMC Corporation in the United States and/or other countries. All other trademarks used herein are the property of their respective owners. For a list of RSA trademarks, go to www.rsa.com/legal/trademarks_list.pdf. License agreement This software and the associated documentation are proprietary and confidential to EMC, are furnished under license, and may be used and copied only in accordance with the terms of such license and with the inclusion of the copyright notice below. This software and the documentation, and any copies thereof, may not be provided or otherwise made available to any other person. No title to or ownership of the software or documentation or any intellectual property rights thereto is hereby transferred. Any unauthorized use or reproduction of this software and the documentation may be subject to civil and/or criminal liability. This software is subject to change without notice and should not be construed as a commitment by EMC. Note on encryption technologies This product may contain encryption technology. Many countries prohibit or restrict the use, import, or export of encryption technologies, and current use, import, and export regulations should be followed when using, importing or exporting this product. Distribution Use, copying, and distribution of any EMC software described in this publication requires an applicable software license.
EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice.
THE INFORMATION IN THIS PUBLICATION IS PROVIDED “AS IS.” EMC CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Copyright © 2012-2015 EMC Corporation. All Rights Reserved. October 2012 Revised: July 2014, May 2015, December 2015 RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
Contents
Preface...... 5 About This Guide...... 5 RSA Adaptive Authentication (Hosted) Documentation...... 5 Support and Service ...... 7 Before You Call Customer Support...... 7
Chapter 1: Data Gathering Overview...... 9 Collection Methods...... 9 JavaScript Collection ...... 9 Mobile Data Collection...... 9 Browser Cookie ...... 9 Flash Shared Objects (FSO) ...... 10 Supported Browser and Operating System Combinations...... 10 Operating Systems with Java Collection Support...... 10 Mobile Devices and Browsers with Java Collection Support...... 11 Supported Browser and Flash Component Combinations...... 12 Best Practices for Data Gathering...... 12 Files to Implement Data Gathering...... 13
Chapter 2: JavaScript Collection...... 15 Device Fingerprint ...... 15 Prerequisites...... 17 Implementing the Device Fingerprint Method ...... 17 Mobile Location Awareness ...... 19 Collecting Mobile Browser Geolocation Data using JavaScript ...... 19 Sending Collected Mobile Browser Geolocation Data to RSA Adaptive Authentication...... 23
Chapter 3: Mobile Data Collection ...... 25 Collecting Mobile Data...... 27 Collecting and Sending Information with the JavaScript ...... 28 Collecting Information with the RSA Mobile SDK - Adaptive Authentication Module . 28 Sending Collected Data with the RSA Mobile SDK to RSA Adaptive Authentication ... 28
Chapter 4: Browser Cookie ...... 29 Implementing the Browser Cookie ...... 29 Writing or Updating a Browser Cookie ...... 30 Sending Collected Data to the RSA Adaptive Authentication System...... 30
Chapter 5: Adobe Flash Shared Object ...... 31 Prerequisites...... 31 Flash File Location and Flash Shared Object Creation...... 31 Understanding Flash Variables ...... 32 Detecting the Flash Version and Running the Movie...... 32 Implementing the Flash Shared Object...... 33
Contents 3 RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
Running the Flash Shared Object Example ...... 34 Implementing the Flash Shared Object with the Anti-Theft Feature...... 35 Reading the Flash Shared Object...... 35 Writing or Updating a Flash Shared Object...... 35 Running the Anti-Theft Flash Shared Object Example ...... 36 Sending Collected Data to the RSA Adaptive Authentication System...... 37
Chapter 6: IP Address Gathering Techniques...... 39 End User is not Behind Proxy...... 39 End User is Behind Proxy...... 39
Appendix A: SOAP Analyze Request Example...... 41
4 Contents RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
Preface
About This Guide RSA Adaptive Authentication makes extensive use of data collection for risk-based authentication. This guide focuses on the data gathering techniques for Device Fingerprint, Mobile device identifiers, Flash Shared Object, and Browser Cookie collection, that are used in conjunction with the SOAP API. It also describes the implementation mechanisms that allow the application or web site to collect data from the user’s device and pass it to the Adaptive Authentication system. This guide is intended for web site designers, system administrators, and other trusted personnel responsible for implementing data gathering techniques. Do not make this guide available to the general user population.
Note: This document describes the JavaScript Collection code implementation in conjunction with Adaptive Authentication API 6.5. It is not compatible with earlier API versions.
RSA Adaptive Authentication (Hosted) Documentation For more information about RSA Adaptive Authentication, see the following documentation: RSA Adaptive Authentication (Hosted) Release Notes. Provides information about what is new and changed in this release, as well as workarounds for known issues. The latest version of the Release Notes is available on RSA SecurCare Online at https://knowledge.rsasecurity.com. RSA Adaptive Authentication (Hosted) Product Overview Guide. Provides a high-level introduction to the product and its documentation. Setup Form. Specifies and describes the basic system configuration parameters that are required for getting started and describes optional system parameters that can be set by your organization as part of the implementation process. FI Load User’s Guide. Describes how to integrate organizations with your RSA Adaptive Authentication system. Applicable for vendors. Policy Loader User’s Guide. Describes how an organization can define any set of collection or authentication rules using the Policy Loader process. Programmer’s Guide. Describes the web services offered by RSA Adaptive Authentication (Hosted) and the common use cases associated with each service. API Reference Guide. Describes overall business workflows of RSA Adaptive Authentication (Hosted), web service methods, and data elements for each of the methods.
Preface 5 RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
API Mapping Guide. Describes how to map the legacy RSA API to the Adaptive Authentication (Hosted) API Release 6.5 and how to upgrade to the new API by gradually adding new API calls on top of existing API. Case Management API Developer’s Guide. Describes the functionality and capabilities of the RSA Adaptive Authentication Case Management API. Batch File Integration Guide. Describes the batch file option (a method for sending online transactions data to the RSA Risk Engine for risk evaluation) and how to integrate it into your RSA system. Back Office SSO API Guide. Describes how to integrate your organization’s existing application sets with the RSA Adaptive Authentication (Hosted) Back Office applications. Data Gathering Techniques Guide. Describes the implementation mechanisms that allow your organization’s application or web site to collect data from the user's device and pass it to the RSA system using the SOAP API Device Fingerprint Collection JavaScript code and Flash Shared Object. Raw Data Reports User’s Guide. Describes the Raw Data Reports feature including the report requirements, the content of the report, the way it should be transferred to a client, and the configuration and customization options. Back Office User’s Guide. Describes the Back Office application suite, including: • MIS Reports. Provides a summary of the available MIS reports and their use for clear, high-level visibility of the system. • Representative Administration. Describes how to perform the administration tasks required to manage Back Office users. • Case Management. Describes how to track and follow up on various online customer activities to determine whether they are genuine or fraudulent. • Policy Manager. Describes how to define, edit, and add to a set of built-in heuristic risk-management decision rules. • Customer Service. Describes how to respond to end user inquiries and guide end users.
6 Preface RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
Support and Service
RSA SecurCare Online https://knowledge.rsasecurity.com
Customer Support Information www.emc.com/support/rsa/index.htm
RSA Ready Community https://community.emc.com/community/connect/rsa xchange/rsa-ready
RSA SecurCare Online offers a knowledgebase that contains answers to common questions and solutions to known problems. It also offers information on new releases, important technical news, and software downloads. The RSA Secured Partner Solutions Directory provides information about third-party hardware and software products that have been certified to work with RSA products. The directory includes Implementation Guides with step-by-step instructions about interoperation of RSA products with these third-party products.
Before You Call Customer Support To log a ticket with the RSA Help Desk, please have the following information available when you call: Your RSA Site ID/License ID: Company Name: Company Address: Contact Name: Phone Number: E-mail Address: RSA Product/Version: Summary of Problem:
Preface 7
RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
1 Data Gathering Overview
Collection Methods RSA Adaptive Authentication supports different data collection methods. The developer must incorporate the selected mechanisms into the pages constructed for the web site. The interfaces for gathering user device information apply to most business use cases for financial and non-financial services that use Adaptive Authentication or Transaction Monitoring. The supported data collection methods are:
JavaScript Collection A JavaScript code is implemented in the desired application page, which collects data from the user’s device and enables passing it to the Adaptive Authentication or Transaction Monitoring system in a SOAP request message. The JavaScript collects data for the following functionality: • Device Fingerprint. A method that identifies detailed hardware and software characteristics of user devices. • Mobile Location Awareness. This is an element of Adaptive Authentication’s Enhanced Mobile Protection functionality. The JavaScript collects mobile geolocation information for mobile browsers.
Mobile Data Collection Adaptive Authentication provides Mobile Protection functionality that retrieves the location of the end user mobile device and additional mobile device identifiers, including the WiFi Mac Address or OS ID, for risk-based authentication. Mobile data is collected using one of the following methods: • For mobile browsing. A JavaScript is used to collect the location information. For more information, see “Collecting Mobile Browser Geolocation Data using JavaScript” on page 19. • For mobile applications. The RSA Mobile SDK - Adaptive Authentication Module is used to collect the location information and other mobile device identifiers. For more information, see “Mobile Data Collection” on page 25.
Browser Cookie A method that installs a unique device ID on the user’s device, enabling efficient tracking of user devices. A JavaScript code is implemented to collect device data and store it in the browser cookie. This cookie is later sent to the Adaptive Authentication or Transaction Monitoring system for device identification.
1: Data Gathering Overview 9 RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
Flash Shared Objects (FSO) A method that stores a device cookie as a Flash movie file on the user's device. This technique enables storing of information on the user’s device in the same way that cookies do, and retrieving it at a later time. Flash Shared Objects are not deleted when a user clears the browser cookies. Flash Shared Objects are stored in the following locations: • In Windows: C:/Documents and Settings/
Supported Browser and Operating System Combinations Device information can be collected from a range of browsers and operating systems. This topic describes supported browsers and operating systems, and limitations for specific features.
Note: The following tables refer to the latest version of a browser unless the version is specified.
Operating Systems with Java Collection Support The following browser and operating system combinations have been tested to ensure that RSA Adaptive Authentication (Hosted) retrieves distinctive device fingerprint for each combination.
Windows Windows Windows Windows Windows Browser Linux MacX 8.1 7 Vista XP Server 2008
IE 11.0 X X
IE 10.0 X
IE 9.0 X
IE 8.0 X X X X
Opera X X X
Firefox X X X X X X X
Safari 7 X X
Chrome X X X X X X
10 1: Data Gathering Overview RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
The following browser limitations exist: • The following browsers cannot detect the System Language and User Language values: – Firefox – Mozilla – Netscape – Safari • The Opera browser cannot detect the System Language value. • The software value can only be detected in Windows operation system browsers. • For Mobile Location Awareness supported browsers for geolocation collection, see Mobile Data Collection on page 25. • Due to known limitations, the device fingerprint is not collected from Blackberry devices. • The Flash Shared Object technique is not compatible with the Safari 1.0 browser. However, you can use the Device Fingerprint JavaScript code to gather other device fingerprint data.
Mobile Devices and Browsers with Java Collection Support The following mobile devices and browsers support JavaScript data collection.
Windows Mobile Browser iOS Android Mobile
Chrome X X
Firefox Mobile X
Safari X
Opera X X
Skyfire 4.0 X X
WebKit Browser X
IE X
1: Data Gathering Overview 11 RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
Supported Browser and Flash Component Combinations The following browser and Flash component combinations are tested to ensure successful operation with Flash shared objects.
Browser Flash 11 Latest Version
IE 11.0 X
IE 10.0 X
IE 9.0 X X
IE 8.0 X X
Opera X X
Firefox X
Safari X
Chrome X
Best Practices for Data Gathering RSA recommends the following best practices for implementing data gathering: • Organizations must send device forensic information, such as IP address, browser cookie, Flash Shared Object, and device fingerprints to Adaptive Authentication for every event using the Analyze call (not only for logon events). This additional data improves the risk assessment capabilities. • The data gathered during logon activities can be stored in a session. RSA recommends that organizations do not store and reuse the information collected during logon activities. • New web pages added to the organization’s web site must implement the data gathering techniques.
Note: This guide uses the Analyze method as an example. The instructions are also applicable for the Notify method. For more information, see the API Reference Guide.
12 1: Data Gathering Overview RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
Files to Implement Data Gathering RSA provides a set of files required to implement data gathering and a set of files to demonstrate the implementation. The files are packaged as ZIP archives and can be downloaded from RSA SecurCare Online at https://knowledge.rsasecurity.com. The following table describes the archives provided.
Filename Description
datacollection.hosted-jslib-3.0.0.0.zip The set of files required to implement data gathering techniques.
datacollection.hosted-aahdemo-Data The set of sample files required to demonstrate the CollectionKit.zip implementation of data gathering techniques.
1: Data Gathering Overview 13
RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
2 JavaScript Collection A JavaScript code is implemented in the desired application page, which collects data from the user’s device and enables passing it to the Adaptive Authentication or Transaction Monitoring system in a SOAP request message. The JavaScript collects data for the following functionality: • Device Fingerprint • Mobile Location Awareness
Device Fingerprint A device fingerprint includes the detailed hardware and software characteristics of the user’s device. This information is used to identify the device attempting to access a system protected by RSA Adaptive Authentication or Transaction Monitoring. The device fingerprint consists of the following data: • Browser and user agent data (version, platform, browser language settings, and time zone settings) • Browser Events (mouse movements and keyboard strokes) • Screen resolution (width and height dimensions, and color depth) • Software and plug-in information • Latency (internal IP and external IP ping time) This information is fed into the RSA Risk Engine, where it contributes to the risk assessment and scoring, as well as to user profile building. The Device Fingerprinting code runs in each page where the organization requires a risk assessment, such as in the organization’s logon page, or in pages that contain other events such as payments or address changes. The organization then passes the gathered device fingerprint information in a SOAP message to Adaptive Authentication.
2: JavaScript Collection 15 RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
The following figure illustrates the message flow in a typical Adaptive Authentication use case. Device fingerprint collection is highlighted in the red boxes.
Organization’s User Browser RSA Web App Web Server
Access the logon page
Login form: Request “User ID” + password Logon Logon Page Process Analyze call user_id; Risk assessment and device fingerprint recommended action Submits User ID + password + information in inet decision hidden deviceFingerprint data structure Device Fingerprint, HTTP Cookie, JavaScript and FSO Collection
Device fingerprint Additional Interactions Information: -Browser info. Subsequent -Plug-ins -Language Processes -Time zone -Display
Analyze call user _id; Present payment form device fingerprint information in inet data structure Risk assessment and Payment recommended action Pay Bill Process decision Attempt to pay bill Device Fingerprint, HTTP Cookie, HTTP Cookie, Fingerprint, Device JavaScript and FSO Collection
16 2: JavaScript Collection RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
Prerequisites You must use the package provided by RSA to implement the device fingerprint gathering technique described in this chapter. The following table describes the files included in this package.
Filename Description
rsa.js JavaScript that collects the DevicePrint information and mobile browsing data.
Note: The JavaScript is obfuscated and minimized for increased security.
hashtable.js A file that provides hashtable functionality for use within JavaScript. Wherever in your code you call the rsa.js script, you must also call the hashtable.js script. The hashtable.js script reference must be added before rsa.js because rsa.js has references to hashtable.js.
Files to Demonstrate Device Fingerprint Implementation
start.jsp The first page to access the demo application.
devicePrintTestPage.jsp A sample page that shows how to collect device fingerprint data.
Implementing the Device Fingerprint Method RSA provides a JavaScript (rsa.js) to extract the devicePrint information from a web page. The add_deviceprint() function in the script is invoked to get the devicePrint information. You must modify each page that contains an event requiring risk assessment or an event notifying the Risk Engine. For example, if the organization requires a risk assessment of logon events, you must implement the code in the organization’s logon page, as well as for events such as payment and address changes. For a sample implementation, see “Running the Device Fingerprint Example.”
Note: urlEncode() function must be used to encode the results of the add_deviceprint() function in order to encode special characters.
To implement the device fingerprint JavaScript: 1. Add the device fingerprint script code to the existing pages. In the header section of the web page, type:
Note: To view geolocation data collection in IE9, enter the declaration before the tag. This notifies the browser that HTML 5 is used. For example: <% response.addHeader ("Access-Control-Allow-Origin","*"); %>
2. Add a new hidden field, for example, RSADevicePrint, to the form and populate it with the value of the add_deviceprint() method. For example:
Sending Collected Data to the RSA Adaptive Authentication System You must send the collected data to Adaptive Authentication whenever there is a need for risk assessment. The SOAP API reads this data from the following field: GenericRequest.deviceRequest.devicePrint
Running the Device Fingerprint Example The following figure demonstrates the gathering of device fingerprint data using the devicePrintTestPage.jsp file.
18 2: JavaScript Collection RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
Mobile Location Awareness The Mobile Protection functionality uses Mobile Location Awareness to retrieve the location of the end user mobile device for risk-based authentication of transactions originating from the mobile channel. A JavaScript is used to collect the location information. The collection location information is used to determine if, for example, the end user is accessing an account from an irregular location, or the ground speed between two transactions is not feasible. This section includes the following topics: • Collecting Mobile Browser Geolocation Data using JavaScript • Sending Collected Mobile Browser Geolocation Data to RSA Adaptive Authentication
Note: This feature requires an initial silent period for the system to learn to distinguish between genuine user behavior and fraudulent behavior.
Note: This feature is relevant for the following W3C Geolocation API types: HTML5 and BlackBerry proprietary API (starting from version 4.1).
Note: Certain countries require explicit end user acknowledgement and consent in order to collect the end user's information (for example location information, location awareness granularity and device information). The Adaptive Authentication API for mobile browsing and Mobile SDK – Adaptive Authentication Module are intended to enable compliance with legal conditions, however RSA is not responsible for the fulfillment of all the legal requirements.
Note: For mobile applications, the RSA Mobile SDK - Adaptive Authentication Module is used to collect the location information and other mobile device identifiers. For more information, and other methods of mobile collection, see “Mobile Data Collection” on page 25.
Collecting Mobile Browser Geolocation Data using JavaScript RSA provides the rsa.js script to collect detailed information about the location of the end user mobile device for risk-based authentication.
Note: Ensure that you integrate the JavaScript code from RSA into your web applications on each page that requires Enhanced Mobile Protection.
2: JavaScript Collection 19 RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
The rsa.js script contains the following functions: • startCollection. Initializes the collection of mobile location information when the HTML page loads. This function also determines the type of mobile device used by the end user. When you call this function, the end user receives a request to approve the collection of the mobile location information.
Note: You must call this function during the onLoad event. You can define specific parameters that help configure the mobile location information collection. For a list of these parameters, see “Defining Location Collection Parameters” on page 20.
• getGeolocationStruct. Formats the collected information into a single string. If you call the stopCollection function during the collection, the getGeolocationStruct function formats the information collected from the time the onLoad event is called until the time the stopCollection function is called.
Note: You must call this function during the onSubmit event.
• stopCollection - (Optional) Stops the collection of mobile location information.
Note: If you choose to stop the collection, you can call the stopCollection function at any time after the onLoad event.
Defining Location Collection Parameters Organizations can define specific parameters that help configure the collection of the mobile location information. If you do not specify the value for a parameter, or if the value exceeds the valid range, then the default value is used.
Note: If you choose to assign values to the parameters, you must do this before calling the startCollection function.
When you call the startCollection () function, include the assigned values in the parenthesis (), with each value separated by a comma. You must position the values according to the order of the parameters listed in the following table. For example, startCollection (Accuracy value, Timeout value, Relevancy value, Expiration value, aidMode value).
20 2: JavaScript Collection RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
The following table includes a detailed description of these parameters.
Default Parameter Description Valid Range Value
Accuracy Threshold in meters for the accuracy of a position. This parameter 100 5 - 200 defines the radius of accuracy required to stop the collection of mobile location information. If the accuracy radius is lower or equal to this value, then the location is no longer collected for that transaction.
Note: This parameter is relevant for HTML5 Geolocation API.
Timeout Threshold in seconds for receiving a valid position. If no position 180 90 - 300 is received by that time, the collection of mobile location information stops.
Relevancy Threshold in seconds for the age of a relevant position. If the age 120 60 - 240 of a position is lower or equal to this value, the collection of mobile location information stops and that position is saved.
Expiration Threshold in hours for the maximum age of a cached location. If 48 24 - 60 the location is older than this value, a location value is not returned.
aidMode The level of accuracy according to the type of collection 2 See “aidMode mechanism used. Functions” on page 21 for a Note: This parameter is relevant for BlackBerry proprietary API list of aidMode (starting from version 4.1). functions.
aidMode Functions
Note: The aidMode parameter is relevant for BlackBerry proprietary API (starting from version 4.1).
A list of aidMode functions is shown in the following table..
aidMode Numeric Description Function Value
Cellsite Uses the GPS location of the Cell Site Tower to provide first-order GPS 0 information.
Note: The Cellsite mode requires network connectivity and carrier support.
Assisted Uses the network to provide short-term satellite data to the device chip. 1
Note: The Assisted mode requires network connectivity and carrier support.
Autonomous Uses the GPS chip on the BlackBerry device without assistance from the 2 network.
2: JavaScript Collection 21 RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
Collecting Location Information The following procedure describes how to collect information about the location of the end user mobile device. It applies to the following W3C Geolocation API types: HTML5 and BlackBerry proprietary API (starting from version 4.1).
To collect Mobile information: 1. When the HTML page loads, initialize the information collection by calling the following function: startCollection() For example:
Note: You must call this function during the onLoad event.
2. (Optional) If you have assigned values for the parameters, add these values in the startCollection parenthesis ().
Note: Each value must be separated by a comma. You must position the values according to the order of the parameters listed in the table. For a list of parameters in the table, see “Defining Location Collection Parameters” on page 20.
For example: startCollection(50,100,220,55,2)
22 2: JavaScript Collection RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
3. Format the collected information into a single string by calling the following function: var geoLocationJSON= getGeolocationStruct(); For example:
Note: You must call this function during the onSubmit event. If you choose to stop the collection, you can call the stopCollection function at any time after the onLoad event. The getGeolocationStruct function formats the information collected from the time the onLoad event is called until the time the stopCollection function is called.
4. Repeat the above procedure for each page that requires information collection for Mobile. 5. Post the string to your organization’s application. Once it is returned, pass it to the Adaptive Authentication system in the geoLocation element in the DeviceRequest payload as part of the SOAP request. For more information on sending the information to the Adaptive Authentication system, see “Sending Collected Mobile Browser Geolocation Data to RSA Adaptive Authentication” on page 23.
Example of the output { "GeoLocationInfo": [ { "Status": "0", "Latitude": "32.1593746442196", "Longitude": "34.80888040361763", "Altitude": "33", "Heading": "0", "Speed": "0", "Timestamp": "1320814898265", "HorizontalAccuracy": "65" "AltitudeAccuracy": "10" } ] } Sending Collected Mobile Browser Geolocation Data to RSA Adaptive Authentication You must send the Mobile geolocation data that was collected by the RSA JavaScript to Adaptive Authentication whenever there is a need for risk assessment. The SOAP API reads this data from the following field: deviceRequest.deviceSpecific.mobile.mobileInfoJs
Note: The values should not be URL encoded.
2: JavaScript Collection 23
RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
3 Mobile Data Collection Mobile Protection functionality gives organizations strong risk-based authentication for online transactions via mobile devices. Adaptive Authentication protects multiple types of mobile channels, from mobile applications to mobile browsing, including WAP and SMS messages. The Mobile Protection functionality uses Mobile Location Awareness to retrieve the location of the end user mobile device and additional mobile device identifiers, such as the WiFi Mac Address and OS ID, for risk-based authentication. It also enables organizations to apply different policies for transactions originating from mobile browsers and those originating from mobile applications. Mobile data is collected using one of the following methods: • For mobile browsing. A JavaScript is used to collect the location information. • For mobile applications. The RSA Mobile SDK - Adaptive Authentication Module is used to collect the location information and other mobile device identifiers.
Note: Organizations using mobile applications without the RSA Mobile SDK - Adaptive Authentication Module should collect the data independently and send it to Adaptive Authentication using the API. For more information, see the RSA Adaptive Authentication API Reference Guide.
Note: If more than one method is used for mobile data collection, the data is used in the following order of priority: 1. RSA Mobile SDK - Adaptive Authentication Module 2. API 3. JavaScript
This section includes the following topics: • Collecting Mobile Data • Collecting and Sending Information with the JavaScript • Collecting Information with the RSA Mobile SDK - Adaptive Authentication Module • Sending Collected Data with the RSA Mobile SDK to RSA Adaptive Authentication
Note: This feature requires an initial silent period for the system to learn to distinguish between genuine user behavior and fraudulent behavior.
3: Mobile Data Collection 23 RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
Note: This feature is relevant for the following W3C Geolocation API types: HTML5 and BlackBerry proprietary API (starting from version 4.1).
Note: Certain countries require explicit end user acknowledgement and consent in order to collect the end user's information (for example location information, location awareness granularity and device information). The Adaptive Authentication API for mobile browsing and Mobile SDK – Adaptive Authentication Module are intended to enable compliance with legal conditions, however RSA is not responsible for the fulfillment of all the legal requirements.
Note: Geolocation collection is supported by the following browsers: – iPhone 3.0 + – Android 2.0 + – Firefox 3.5 – Safari 5.0 – Chrome 5.0 – Internet Explorer 9.0+ Geolocation information is not collected in other browsers.
24 3: Mobile Data Collection RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
Collecting Mobile Data The following figure shows an overview of the information collection for Mobile Location Awareness.
3: Mobile Data Collection 25 RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
Collecting and Sending Information with the JavaScript RSA provides the rsa.js script to collect detailed information about the location of the end user mobile device for risk-based authentication.
Note: For more information, see “Collecting Mobile Browser Geolocation Data using JavaScript” on page 19.
Collecting Information with the RSA Mobile SDK - Adaptive Authentication Module Mobile SDK – Adaptive Authentication Module provides collection methods that support risk-based authentication of end users accessing online transaction applications using a mobile device. Mobile SDK – Adaptive Authentication Module is designed to be embedded in the client application and to enable flexible and customizable collection of device identifiers and location awareness. For more information on collecting information with the RSA Mobile SDK - Adaptive Authentication module, see the RSA Mobile SDK – RSA Adaptive Authentication Module Developer’s Guide.
Sending Collected Data with the RSA Mobile SDK to RSA Adaptive Authentication You must send the collected data to Adaptive Authentication whenever there is a need for risk assessment. The SOAP API reads this data from the following field: deviceRequest.deviceSpecific.mobile.mobileInfoSdk
Note: These values should not be URL encoded.
26 3: Mobile Data Collection RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
4 Browser Cookie Browser cookies are used to identify devices attempting to access a system protected by RSA Adaptive Authentication or Transaction Monitoring. The User ID is used to identify the user and the cookie is used to identify the user’s device.
Important: Do not use the User ID as the cookie name or cookie value.
Implementing the Browser Cookie RSA recommends using values of the following elements to create a browser cookie: • IP address of the device • Server time in milliseconds • (Optional) Process or thread ID on the server A browser cookie created using these elements is unique as it is highly unlikely that two devices will have the same IP address, make a call to the server at the same time, and have the same process or thread ID.
To implement a browser cookie: Do one of the following: • If the cookie is not already set: – Gather the values of the elements and concatenate them into a single string. – (Optional) Hash the values. – Set the cookie with a long expiration date (current time + X years). • If the cookie is already set, reset the cookie (current time + X years). RSA recommends that you set the expiration date of the browser cookie to five years. If you do not set the expiration date, the cookie automatically expires when you close the browser window, impacting the risk score calculation. The following is a sample implementation: String cookie_value = null; if (there is a cookie with the "cookie name") { cookie_value = GetCookieValue(cookie name); update expiry to current time + X years ahead; } else { current_client_ip_address = get current client IP address; current_time = get current time in milliseconds; current_thread_id = current server thread id; cookie_value = current_client_ip_address + "." +
4: Browser Cookie 27 RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
current_time + "." + current_thread_id; SetCookie(name = " cookie name", value = cookie_value, expiry = current time + X years ahead); } Pass cookie_value to the deviceTokenCookie element of the API.
Writing or Updating a Browser Cookie With this feature, Adaptive Authentication returns a new encrypted cookie value on each API call. This new value must be placed as the new cookie value. The following is a sample implementation: String cookie_value = get new cookie value from API response (deviceTokenCookie); if (cookie_value != null) { SetCookie(name = "persistent cookie name", value = cookie_value, expiry = current time + X years ahead); }
Sending Collected Data to the RSA Adaptive Authentication System Customers using the cookie anti-theft feature must send the browser cookie to Adaptive Authentication with the SOAP API, parse the SOAP response, and extract the new browser cookie from the SOAP response. The collected browser cookie is sent in the following SOAP request field: GenericRequest.deviceRequest.deviceTokenCookie The new browser cookie should be parsed from the following SOAP response field: GenericResponse.deviceResult.deviceData.deviceTokenCookie
28 4: Browser Cookie RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
5 Adobe Flash Shared Object An Adobe Flash Shared Object (FSO) is an object similar to a browser cookie. These objects are used to store a device cookie as a Flash movie file on the user's device.
Note: Flash version 6.0.0 is the minimum required Flash version.
Prerequisites You must use the package provided by RSA to implement the FSO device fingerprint gathering technique described in this chapter. The following table describes the files included in this package.
Filename Description
rsa_fso.swf The Flash movie file used to set and read the device FSO.
AC_OETags.js JavaScript provided by Adobe for detecting and embedding Flash in the user’s browser.
Files to Demonstrate Flash Shared Object Implementation
start.jsp The first page to access the demo application.
fso1\login.jsp Pages demonstrating the use of the Flash movie to read the FSO in the default fso1\account.jsp mode.
fso2\login.jsp Pages demonstrating the use of the Flash movie to read the FSO in the anti-theft fso2\account.jsp mode.
Flash File Location and Flash Shared Object Creation Due to security reasons and the nature of Flash Shared Objects creation, it is important that you place the movie file (rsa_fso.swf) in a single location on your web application. If the SWF file is available in duplicate locations, the system may receive a different FSO for every user activity from the same device. Different cookies for the same user-device combination may cause the system to fail to accurately identify the user’s device. For example, if the SWF file is stored in http://
5: Adobe Flash Shared Object 29 RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
Understanding Flash Variables The Flash Variables (FlashVars) property of Adobe Flash Player provides an efficient method to import variables into a movie. Use the following syntax to pass multiple variables: "movie.swf?variable1=value1&variable2=value2" Special and non-printable characters must be URL encoded.
Note: This feature requires Flash Player version 6 or later.
The Flash movie (rsa_fso) supports the variables described in the following table.
Variable Description Example
ip_address The users’ IP address. This is retrieved by your web ip_address=212.150.210. application.
field_name ID of an HTML input form element where the movie can field_name=RSADeviceFso store the FSO data. This element must be submitted with the form. This is a mandatory variable.
rsa_flash_id The movie identification in the HTML page. Deprecated as of RSA Adaptive Authentication 8.5.
fso_in The FSO data received from the Adaptive Authentication fso_in= a string of 125 alpha system when using the Cookie Anti-Theft feature. This numeric chars. value is set in the local FSO. Available as of RSA Adaptive Authentication 8.5.
Detecting the Flash Version and Running the Movie The scripts that are provided by RSA detect whether Adobe Flash is installed on the user’s device. This prevents the security warnings generated when attempting to run Flash movies on a system that does not have Flash installed, or that does not have the minimum required player version. In addition, due to different browser technologies, you must embed the Flash movie differently depending on the browser. The script AC_OETags.js, provided in the Adobe Flash detection kit, solves both of these issues.
Note: The use of AC_OETags.js is only one of many alternatives to embed the movie. For example, you can also use swfobject project at http://code.google.com/p/swfobject/.
30 5: Adobe Flash Shared Object RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
To detect the Flash version and run the movie: 1. Add the following code to the header section of the web page: 2. Add the following code to the body of the web page:
Implementing the Flash Shared Object The Flash movie attempts to read an FSO named rsa_fso.sol from C:/Documents and Settings/
To implement the Flash Shared Object: 1. Add the following code to the header section of the web page: 2. Add the following code to the web pages to populate the RSADeviceFso field by the movie: <%String ip_address = request.getRemoteAddr(); //get user IP%>
Note: You must send the value of the hidden field (RSADeviceFso in this example) in the Analyze or Notify SOAP request.
Running the Flash Shared Object Example The package that RSA provides contains two pages that demonstrate the Flash Shared Object data collection method: • fso1\login.jsp – Shows how to invoke the movie to read the FSO and pass it to the web application, as shown in the following figure.
32 5: Adobe Flash Shared Object RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
• fso1\account.jsp - Demonstrates that the FSO was passed as a hidden field, as shown in the following figure.
Note: In order to access the FSO demo page, a Java Web server is required to run the Flash Shared Object demo application.
Implementing the Flash Shared Object with the Anti-Theft Feature To protect against cookie theft, the SWF movie changes the cookie data on each request. This scenario supports two modes: reading the FSO, and writing or updating the FSO.
Reading the Flash Shared Object This step is similar to reading the FSO in a standard flow. For more information, see “Implementing the Flash Shared Object” on page 31.
Note: In a standard flow, you can omit the ip_address variable in the FlashVars. In the cookie anti-theft flow, the generation and encryption of cookies is done in Adaptive Authentication.
Writing or Updating a Flash Shared Object In cookie anti-theft, Adaptive Authentication generates a new FSO for every Analyze call. The new FSO value is passed to the user to be stored in the local storage. The following procedure describes how to set the FSO information using the FlashVars.
To implement the Flash Shared Object with the anti-theft feature: 1. Add the following code to the header section of the web page:
5: Adobe Flash Shared Object 33 RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
2. Add the following code to the web pages to populate the RSADeviceFso field by the movie: <% // pseudo code to get the FSO from RSA system.%> String fso_from_rsa = analyzeResponse.getDeviceResult().getDeviceData().getDeviceT okenFSO(); %>
Note: FlashVars contains two fields: field_name and fso_in. You must send the value of the hidden field (RSADeviceFso in this example) in the Analyze and Notify SOAP request.
Running the Anti-Theft Flash Shared Object Example The package that RSA provides contains two pages that demonstrate the FSO data collection method in anti-theft mode: • fso2\login.jsp - Shows how to invoke the movie to read the FSO and pass it to the web application. • fso2\account.jsp - Shows how to invoke the movie to write the new FSO value that was received from the Adaptive Authentication system.
34 5: Adobe Flash Shared Object RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
Sending Collected Data to the RSA Adaptive Authentication System Customers using the FSO anti-theft feature must send the FSO to the Adaptive Authentication system in SOAP API, parse the SOAP response, and extract the new FSO from the SOAP response. The collected FSO is sent in the SOAP request field: GenericRequest.deviceRequest.deviceTokenFSO. The new FSO is parsed from the SOAP response field: GenericResponse.deviceResult.deviceData.deviceTokenFSO.
5: Adobe Flash Shared Object 35
RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
6 IP Address Gathering Techniques The technique that you use to gather IP addresses varies depending on whether the end user is behind a proxy.
End User is not Behind Proxy If the end user is not behind a proxy, you can obtain the user’s IP address using the HttpServletRequest getRemoteAddr() method. For example: String ip_address = request.getRemoteAddr();
Note: This example uses the HttpServletRequest getRemoteAddr() method. If you use the method provided in the example, you must use the .jsp file type.
End User is Behind Proxy If the end user is behind a proxy, you must use the X-Forwarded-For (XFF) special header. The XFF HTTP header is the standard for identifying the originating IP address of a client connecting to a web server through an HTTP proxy. XFF headers are supported by most proxy servers, including Squid, Cisco Cache Engine, and NetApp NetCache. The caching servers are usually those of large ISPs who either encourage or force their users to use caching proxy servers for accessing the Internet to reduce external bandwidth. In some cases, these proxy servers are transparent proxies, and users may be unaware that they are using them. Without the use of XFF or a similar technique, any connection made through a proxy reveals only the originating IP address of the proxy server, effectively turning the proxy server into an anonymizing service. This makes the detection and prevention of abusive access significantly harder to detect. The usefulness of XFF depends on the proxy server that reports the original host's IP address. The effective use of XFF requires knowledge of which proxies are trustworthy, for example, by looking them up in a whitelist of server maintainers that can be trusted.
6: IP Address Gathering Techniques 37
RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
A SOAP Analyze Request Example The following code is an example of an Analyze SOAP request with the device fingerprint data value marked in bold.
A: SOAP Analyze Request Example 39 RSA Adaptive Authentication (Hosted) Data Gathering Techniques Guide
40 A: SOAP Analyze Request Example