RSA® Adaptive Authentication (On-Premise) 7.2 Integration Guide Contact Information Go to the RSA corporate website for regional Customer Support telephone and fax numbers: www.emc.com/domains/rsa/index.htm Trademarks RSA, the RSA Logo, BSAFE 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 EMC trademarks, go to www.emc.com/legal/emc-corporation-trademarks.htm#rsa. 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 © 2015 EMC Corporation. All Rights Reserved. Published in the USA. November 2015 RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
Contents
Preface...... 5 About This Guide...... 5 RSA Adaptive Authentication (On-Premise) Documentation...... 5 Support and Service ...... 6 Before You Call Customer Support...... 6
Chapter 1: Encryption System ...... 7 Database and Persistence Encryption ...... 7 Encryption Algorithms...... 7 Key Creation and Storage ...... 7
Chapter 2: Reverse HTTP Proxy in the DMZ...... 9 Reverse HTTP Proxy Server...... 9 Reasons for Using a Reverse Proxy...... 9
Chapter 3: Validating User Data ...... 11 Validating User Input...... 11 Profanity...... 11 SQL Injection...... 12 XML Injection ...... 12 Special Characters...... 12 Scripting Patterns...... 12 Additional Data Validation Guidelines...... 13
Chapter 4: Device Information Collection ...... 15 Device Information ...... 15 HTTP Headers ...... 15 Source IP Address...... 16 Device Print ...... 16 Mobile Device Information ...... 17 User-Defined Credentials ...... 17 Device Token...... 17 Device Token Theft Detection...... 20 Collection of Device Information ...... 20 Collection of Device Print Information During Logon ...... 21 Collection of Device Print Information During Enrollment...... 22 Collection of Device Print Information During Transaction Authentication ...... 23 Collection of Information Using the Mobile SDK - Adaptive Authentication Module 24 Scripts for Collection of Device Print Information ...... 25 Retrieval of the Device Token...... 26 Collection of Device Print Information ...... 30 Information Sent to Web Services ...... 32 Overview of the Setting of Device Print Information...... 33
Contents 3 RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
Device Print Information Set During Enrollment...... 34 Device Print Information Set After a Successful Challenge...... 35 Device Print Information Set During Transaction Authentication ...... 36 Setting Device Print Information ...... 37 Place the PMData Cookie ...... 37 Place the Flash Shared Object Token ...... 37
Chapter 5: Information Collection...... 41 Mobile Location Awareness ...... 41 Overview of Information Collection for Mobile Location Awareness...... 42 Script for Collection of Mobile Location Awareness Information...... 43 Mobile Location Awareness Function Names...... 43 Collect Information for Mobile Location Awareness...... 45
Chapter 6: RDP Trojan Protection...... 49 RDP Trojan Protection Module ...... 49 Collect RDP Trojan Protection Information ...... 51 RDP Trojan Collection Parameters...... 52
4 Contents RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
Preface
About This Guide
This guide introduces the procedures required to integrate RSA® Adaptive Authentication (On-Premise) 7.2 with existing applications. This guide is intended for system administrators, security analysts, and other trusted personnel. Do not make this guide available to the general user population.
RSA Adaptive Authentication (On-Premise) Documentation For more information about RSA Adaptive Authentication (On-Premise), see the following documentation: API Reference Guide. Describes RSA Adaptive Authentication (On-Premise) web services API methods and parameters. This guide also describes how to build your own web services clients and applications using web services API to integrate and utilize the capabilities of Adaptive Authentication (On-Premise). Authentication Plug-In Developer’s Guide. Describes the Authentication Plug-In development process that enables external authentication providers to integrate their products with RSA Adaptive Authentication (On-Premise). Back Office User’s Guide. Provides an overview of the following Back Office applications: Policy Management, Case Management, Access Management, Customer Service Administration, and the Report Viewer. Installation and Upgrade Guide. Describes detailed procedures on how to install, upgrade, and configure RSA Adaptive Authentication (On-Premise). Integration Guide. Describes how to integrate and deploy RSA Adaptive Authentication (On-Premise). Operations Guide. Provides information on how to administer and operate RSA Adaptive Authentication (On-Premise). This guide also describes how to configure Adaptive Authentication (On-Premise) within the Configuration Framework. Performance Guide. Provides information about performance testing and performance test results for the current release version of RSA Adaptive Authentication (On-Premise). Product Overview Guide. Provides a high-level overview of RSA Adaptive Authentication (On-Premise), including system architecture. Release Notes. Provides information about what is new and changed in this release, as well as workarounds for known issues. It also includes the supported platforms and work environments for platform certifications. Security Best Practices Guide. Provides recommendations for configuring your network and RSA Adaptive Authentication (On-Premise) securely.
Preface 5 RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
Workflows and Processes Guide. Describes the workflows and processes that allow end users to interact with your system and that allow your system to interact with RSA Adaptive Authentication (On-Premise).
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/rsax change/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 Ready Community provides information about third-party hardware and software products that have been certified to work with RSA products. The community includes RSA Ready Implementation Guides with step-by-step instructions and other information about interoperation of RSA products with these third-party products.
Before You Call Customer Support Make sure that you have direct access to the computer running the RSA Adaptive Authentication (On-Premise) software. Please have the following information available when you call: Your RSA Customer/License ID Adaptive Authentication (On-Premise) software version number The make and model of the machine on which the problem occurs The name and version of the operating system under which the problem occurs
6 Preface RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
1 Encryption System RSA Adaptive Authentication (On-Premise) makes extensive use of encryption for internal operations with other systems, such as online systems. This chapter describes where and how encryption is used in Adaptive Authentication (On-Premise).
Database and Persistence Encryption You must encrypt any sensitive data that is stored in the database or the file system. The only persistent data encrypted by RSA Adaptive Authentication (On-Premise) are the keys themselves. These keys are used for encrypting internal and customer messages, user phrases, and secret answers.
Encryption Algorithms RSA Adaptive Authentication (On-Premise) complies with FIPS 140-2 Level 1 and uses RSA BSAFE® 4.1. For details about FIPS 140-2 compliance, see the RSA BSAFE Crypto-J 4.1 Security Policy at http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/140sp/140sp1291.pdf.
Key Creation and Storage The key creation and storage mechanisms are different for each type of application use: Internal Token Keys. Keys for internal token encryption are generated within the Adaptive Authentication system and are only applicable to device tokens. Key seed data is generated using the Java SecureRandom class, seeded with time stamp and key name bits. This key seed data is stored in a named record in the MSG_CODE_KEY table. At runtime, the actual key is constructed from the key seed using a fixed transformation of hashes. Internal token keys are periodically regenerated, also known as “key rolling,” on a regular basis. You can configure the key regeneration interval using the field-configurable setting KEY_LIFETIME_IN_DAYS. The default value for key regeneration is seven days. Consequently, there may be multiple keys that are used, depending on the device token that is submitted by the user device. The correct key is selected based on the device token.
1: Encryption System 7 RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
Persistence Keys. When Adaptive Authentication wis first used, a new entry is created in the MSG_CODE_KEY table with the initial key name. There is never any externalized storage of persistent keys on the file system or in the database, except in the compiled Java code.
8 1: Encryption System RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
2 Reverse HTTP Proxy in the DMZ As a security application server, the contents of RSA Adaptive Authentication (On-Premise) must be protected. RSA recommends that you locate the Adaptive Authentication server behind one of the most secure segments of the firewall, in a location not open to network traffic directly from the Internet. To accommodate this recommended configuration, use a device or software agent in the web DMZ, defined as the “least protected” network segment behind the fire wall, as a reverse proxy.
Reverse HTTP Proxy Server A proxy is a device that breaks the connection between a sender and a receiver. It functions as a relay between the client and the server. The type of proxy server discussed in this guide is a reverse HTTP proxy server. This device is intended to reside near the web or application server. It performs its proxy functions at the HTTP application layer, unlike other simpler devices that perform proxy functions only at the IP layer.
Reasons for Using a Reverse Proxy The main reasons for using a reverse proxy are that the reverse proxy: • Allows the Adaptive Authentication application server to reside in a more protected zone, inaccessible to direct Internet traffic • Increases the chances that the requests reaching the application server are well formed because reverse proxy servers inspect the contents of each request more thoroughly than most firewalls • Often performs SSL acceleration and load distribution
2: Reverse HTTP Proxy in the DMZ 9
RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
3 Validating User Data Any time that your application accepts information from the user, the application is responsible to verify that the user’s data is of a valid type before submitting this information to RSA Adaptive Authentication (On-Premise). Adaptive Authentication (On-Premise) in the standalone model contains user data validation capability. At any point in which the user enters data, the standalone model validates the user information. This functionality compares the information that the user enters, for example, user phrase or answers, against profanity and certain special characters, such as -, <, /, and \. This type of data validation is not yet available in the RSA API models.
Validating User Input Before passing information to the methods, your application must validate user input into the API models against the following: • Profanity • SQL Injection • XML Injection • Special Characters • Scripting Patterns
Profanity There are several methods for validating user-entered data, including using the same logic that is used to check a user’s password. However, RSA currently does not offer any recommended method with which to check this information.
Edit the Profanity Filter During the installation and configuration, you can configure the profanity filter to include a list of profanity not allowed in the user’s personalized caption.
Important: Because of the double-byte nature of the configuration files, you must use a UTF-8 compatible text editor. If you use a text editor that is not UTF-8 compatible, you may encounter UTF-8 errors when you load your configuration files.
3: Validating User Data 11 RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
To edit the profanity filter: 1. In the rsa_root_directory/configs directory, locate and open the phrase_profanity.txt file. 2. Add any additional terms as necessary, or remove files. 3. Save the file.
Note: Changes to the profanity filter are applied only after a configuration reload. For more information, refer to the topic about reloading a Configuration Tree in the Operations Guide.
SQL Injection SQL injection is a way to exploit your web application by inserting a SQL query or command into fields that are normally reserved for user information that is submitted as input, such as the user name or password field. This query or command then submits a request to your database. RSA Adaptive Authentication (On-Premise) provides functionality to check for SQL injection. Configure your application to check for potential SQL queries or commands.
XML Injection XML injection is a way for fraudsters to manipulate the user’s SOAP API by inserting XML fragments into the user’s input fields. XML injection can cause undesired behavior of the system, such as disabling the running of the RSA® Risk Engine. Configure your application to look for the following character strings and disallow these strings from the user’s input:
Special Characters RSA Adaptive Authentication (On-Premise) provides functionality to check for special characters. Configure your application to look for and disallow the following characters in user input:
` <>" ' %;( ) &+\ #?{}| ^~[ ]
If your system finds any of these characters within the user’s data fields, it displays an input error to the user and asks the user to resubmit the data.
Scripting Patterns RSA Adaptive Authentication (On-Premise) provides functionality to check for scripting patterns. Configure your application to look for and disallow the following scripting patterns in user input:
'"`\
12 3: Validating User Data RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
Additional Data Validation Guidelines For more information on securing online applications, including guidelines for data validation, go to http://www.owasp.org.
3: Validating User Data 13
RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
4 Device Information Collection • Device Information • Collection of Device Information • Information Sent to Web Services • Overview of the Setting of Device Print Information • Setting Device Print Information RSA Adaptive Authentication (On-Premise) collects specific information about a user’s device, such as a personal computer or web-enabled PDA, that is used to initiate requests to your system. The collected information, such as device information and device tokens, helps to determine the level of risk associated with a user accessing your system. This chapter describes the device information that is required by Adaptive Authentication (On-Premise). It also describes how to collect the data using the tools and scripts provided by RSA.
Device Information Device information is a collection of facts from a user’s machine. These facts feed into the RSA Risk Engine and help identify fraudsters and fraudulent activities. The collection of these facts is performed through the use of JavaScript and HTTP request headers. The device information that is collected helps to uniquely identify a user’s device. For each device that interacts with RSA Adaptive Authentication (On-Premise), the following information is captured: • HTTP headers • Source IP address • Device Print • Mobile Device information • User-defined credentials • Device Token (optional)
HTTP Headers The information collected within the HTTP headers includes the following: • Accept string • Referrer value
4: Device Information Collection 15 RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
• Accept-Language string. This language may be different than what is captured by the Device Print scripts. • User-Agent string. This request information is captured by the system to validate the authenticity of the device token and for further forensic analysis and fuzzy matching.
Source IP Address Source IP addresses are used to further validate the device and to generate user geographic location forensics. It is important that this value is the IP address of the end user, not of a proxy or internal machine. If the web server is fronted with a reverse proxy server, you can use a “trusted proxies” mechanism to obtain the true source IP address. This mechanism retrieves the source IP address by interpreting a different field of the HTTP header based on the configuration of the proxy that sent the request. For example, if the proxy server that sent the request is an Apache server, the trusted proxies mechanism looks for the ‘X-Forwarded-For’ header field.
Device Print RSA Adaptive Authentication (On-Premise) creates a globally unique device ID for each computer that accesses your online transaction system. The device ID, together with additional methods, is used to verify the identification of the computer. The additional methods are: • Device forensics—Analysis of the detailed hardware and software characteristics, or Device Print, of each computer • Network forensics—Analysis of the IP address, subnet, ownership, and geographic location of the network connection the computer is using The Device Print consists of the following pieces of data: • User agent string—The version, platform, and the acceptance-language header (the user’s language preference) • Screen resolution—Width, height, and color depth of the user’s screen • Plug-in information—The browser plug-ins that a user has installed on the device • Browser language—The language of the actual browser • Time zone—The user’s current time zone in GMT • Language—The user’s browser language and the system language • Java-enabled—Whether or not the user has Java enabled on the device • Cookies—Whether or not the user has cookies enabled on the device This information is fed into the RSA Risk Engine and contributes to risk analysis and fuzzy matching. Adaptive Authentication (On-Premise) supplies a series of scripts to gather this information
16 4: Device Information Collection RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
Mobile Device Information For information on mobile device information, see the API Reference Guide. For information about integrating the RSA Mobile SDK - Adaptive Authentication Module, setting the user permissions, and installing and using the sample application, see the RSA Mobile SDK - RSA Adaptive Authentication Module Developer’s Guide.
User-Defined Credentials For information on user-defined credentials, see the API Reference Guide.
Device Token
Note: The collection of Device Token information is optional.
RSA Adaptive Authentication (On-Premise) handles the device information used in second-factor authentication in the form of encrypted device tokens, also referred to as device cookies or PMData cookies. Device tokens are generated by the system and stored on the client device in the form of cookies and Flash shared objects (FSOs).
Information Stored in a Device Token Data encoded into device tokens includes payload data (device ID, user-agent string to identify browser, creation date) and protocol data (version number, key ID, checksum). Each device token is constructed using the following format: [Token Version][Key Name][Encrypted Token Information] where: • Token Version is the version of the device token. For instance, version 3 is “V3” • Key Name is the name of the key used to encrypt the data within the token • Encrypted Token Information includes: – Device ID – Creation date – Checksum of the Device ID and Creation date values (to ensure the integrity of the data)
Storage of Device Tokens Device tokens are stored on the user’s device using two different mechanisms: Cookies.The system uses a persistent cookie, PMData, as the primary mechanism for storing device tokens. This persistent first-party cookie does not contain personally identifiable information in its P3P definition. Flash shared objects. A Flash shared object (FSO) is used as a backup copy of the device token in the event that the PMData cookie is deleted. The FSO is stored and retrieved by playing an invisible Flash movie. RSA provides the Flash movie file pmfso.swf, which you can run to retrieve and set the FSO.
4: Device Information Collection 17 RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
Using Device Tokens When a user enrolls in Adaptive Authentication (On-Premise), the following occurs: • A device token is created and placed on the user’s device. • The device token is also stored in the User ID record in the database after enrollment is completed. The device token helps to authenticate a user in the following situations. • When the user signs in to your online system • During transaction authentication
Bind and Set Device Tokens In Adaptive Authentication (On-Premise), you can either: • Set a token, which places a device token on a user’s device. • Bind a token, which places a device token on the user’s device and associates it with that particular user. The device is bound to that user. A token can be set on a user’s device, but not bound to the user. This might occur during certain actions, such as transaction authentication. Setting a token on a user’s device during transaction authentication can help detect fraud, such as man-in-the-middle attacks. You can configure your application when to specifically bind a user to a device at certain times, such as after the user successfully enrolls or after the user has successfully passed a challenge, and when to simply set a token. Typically, a user is bound to a device after successfully enrolling into Adaptive Authentication (On-Premise) and after successfully responding to a challenge. A device binding (linking a user and a device) helps identify the user and allows the user to log on to your system without being challenged. If the device token is not present, or if the user is not bound to a device, for example, when logging on from a different computer, the user is challenged.
Multiple Devices and Tokens A single user can log on to more than one machine by logging on from a different machine and successfully passing a challenge. For example, one person can use a computer at home and a computer at work to check account information. In addition, a single device can be bound to more than one user through single or multiple tokens on the same machine. For example, a family with multiple users can use one computer to log on to their respective online accounts.
Device Token Checksum and Encryption Adaptive Authentication (On-Premise) complies with FIPS 140-2 Level 1 encryption standards. Adaptive Authentication (On-Premise) calculates a checksum for and encrypts all data stored in a device token on the user’s computer. Because the sending and receiving parties are the same, the system uses secret-key encryption to encrypt device tokens. This checksum and encryption ensures the integrity of the data and verifies the source of the data as the system.
18 4: Device Information Collection RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
Domain Scoping For information about domain scoping, refer to the section about configuring domain scoping in the Operations Guide.
Device Token Recovery When an enrolled user logs on to Adaptive Authentication (On-Premise), the system searches for device tokens on the user’s device. The user may have deleted or suppressed cookies or disabled Flash player, which prevents Adaptive Authentication (On-Premise) from identifying the user as a valid user. Consequently, the user may be challenged repeatedly. Device token recovery helps prevent legitimate users from unnecessary challenges if they delete cookies or disable Flash player. Device token recovery works only for devices that are bound to users. Device token recovery is relevant only for the following channels: • Web • Mobile In earlier versions, data elements were used to determine whether the channel is Web or Mobile. Starting from RSA Adaptive Authentication (On-Premise) 7.0, the Channel Determination Service is used to identify the type of channel.
Note: Device token recovery is automatically enabled for Adaptive Authentication (On-Premise). You can disable device token recovery by modifying the relevant parameters in the Administration Console. For more information, see the Operations Guide. Due to forensic similarities between browsers across mobile devices, RSA recommends that you use these capabilities to disable device recovery specifically for mobile browsers.
The process of device token recovery is as follows: 1. When a user logs on to your system and the device token is missing, the system attempts to re-create the device token for the user using information such as: – Source IP address – HTTP header information – Device print information The information in the database is compared to the information from the user’s current device and passes through various models that determine how good a match it is to the current device. A device recovery score is generated based on the match. 2. The device recovery score passes through your institution’s policies (within the Policy Engine) to determine if the score meets a threshold setting for device token recovery confidence, with one of the following results: – If the device recovery score exceeds that threshold, the device token is considered recovered and the user is allowed to proceed without challenge.
4: Device Information Collection 19 RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
– If the device recovery score does not meet the threshold, the device token is not considered recovered and the user is challenged. 3. If the device token is recovered, a new device token is generated from the recovered record and sent back to your application to place on the user’s device. 4. The new information indicating that a device token recovery occurred.
Device Token Theft Detection Device tokens can potentially be stolen by malware and used to identify a hacker’s device as a legitimate device. Device token theft protection helps prevent imposters from using stolen device tokens. Device token theft detection prevents fraudsters who steal device tokens from a legitimate device and attempt to use it on another machine. This section describes the process of device token theft detection. 1. Because a device token is regenerated each time a user accesses the system, an old instance of a token is detected. 2. An analyzer compares the retrieved token against the user’s history in the device record, with one of the following results: – If the match confidence is low, a high risk score is assigned to that device, which triggers Adaptive Authentication (On-Premise) to issue a challenge for the device and prevents the imposter from accessing your system. – If the match confidence is high, a low risk score is assigned to the device. Your institution can choose to either challenge the user or allow the user access. 3. The database is updated with the new information including a high-risk device for that device token.
Collection of Device Information This section describes the implementation mechanisms that do the following: • Allow your application, for example, an organization website, to collect device data from the user and store it in RSA Adaptive Authentication (On-Premise) • Store data to an end user’s device This data is entered into the RSA Risk Engine, and helps Adaptive Authentication (On-Premise) to identify potential fraudulent transactions. RSA recommends that device print information collection always occurs at the following times: • During logon, to help determine the validity of the user and provide authentication information. • During enrollment, to capture historical information on the user. • During Transaction authentication, to help determine the validity of the user and provide information for analysis.
20 4: Device Information Collection RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
Collection of Device Print Information During Logon During logon, ensure that your application captures the device information when the user submits his user name. You can then post all the device information and User ID within one given page. The following figure shows an overview of the device collection during logon.
4: Device Information Collection 21 RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
Collection of Device Print Information During Enrollment After the user is successfully authenticated by your system, you can enroll the user into RSA Adaptive Authentication (On-Premise). RSA recommends that you send the device information to Adaptive Authentication (On-Premise) when the user selects challenge questions during enrollment. The device information is posted to the server at the same time. The following figure shows an overview of the collection during enrollment.
22 4: Device Information Collection RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
Collection of Device Print Information During Transaction Authentication RSA recommends that you send the device information to RSA Adaptive Authentication (On-Premise) when the user begins a transaction. During this period, your application should write the device token information to the user’s browser. For more information, see “Device Print Information Set During Transaction Authentication.” The following figure shows an overview of the device collection during a transaction.
4: Device Information Collection 23 RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
Collection of Information Using the Mobile SDK - Adaptive Authentication Module The RSA Mobile SDK - Adaptive Authentication Module provides collection methods that support risk-based authentication of end users accessing online transaction applications by way of a mobile device. For information about integrating the module, setting the user permissions, and installing and using the sample application, see the RSA Mobile SDK - RSA Adaptive Authentication Module Developer’s Guide. RSA recommends that you collect the information using the Mobile SDK - Adaptive Authentication Module at the following times: • During logon, to help to determine the validity of the user and provide authentication information. At this time, ensure that your application captures the information when the user submits a user name. You can then post the collected information and User ID within one given page. • During enrollment, to capture historical information on the user. After the user is successfully authenticated by your system, you can enroll the user into RSA Adaptive Authentication (On-Premise). RSA recommends that you send the information to Adaptive Authentication (On-Premise) when the user selects challenge questions during enrollment. The collected information is posted to the server at the same time. • During transaction protection, to help determine the validity of the user and provide information for analysis. RSA recommends that you send the collected information to Adaptive Authentication (On-Premise) when the user begins a transaction. During this period, your application should write the collected information to the user’s browser.
24 4: Device Information Collection RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
The following figure shows an overview of the information collection during logon, enrollment, and transaction authentication.
Scripts for Collection of Device Print Information RSA provides mechanisms that your application can use to interface to the end-user’s browser and mobile application, and to RSA Adaptive Authentication (On-Premise). Example code is provided later in this chapter. The logical flow of these operations is shown in the following files: PassMarkSimpleFSOServlet. The servlet that shows how to retrieve posted PMData using the invisible Flash movie. pmfso.jsp. The reference file that shows how to run the Flash movie and retrieve the device token from the Flash shared object (FSO). pmfso_set.jsp. The reference file that shows how to run the Flash movie and set the device token in the FSO.
4: Device Information Collection 25 RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
rsa.js. The reference file that shows how to collect Device Print information and post the information back to the server. For more information, see “Retrieval of the Device Token” on page 26.
Note: Ensure that you integrate the JavaScript code from RSA into your web applications. This JavaScript code collects device information from end users. It is mandatory that you send RSA the device information through the deviceRequest element.
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. pmfso.swf. The Flash movie that reads and sets the FSO.
Note: Do not edit this file.
Signin.jsp. The file that demonstrates how to include the reference information found in pmfso and pm_fp in the logon workflow. AC_OETags.js. The JavaScript file created by Adobe that is responsible for detecting the Flash version on the end-user’s browser.
Note: The set of files is located in the WebResources.zip package that is installed with the development utilities component. For more information, see the Installation and Upgrade Guide.
Retrieval of the Device Token You must retrieve the device token, which is stored as both a cookie and a Flash shared object (FSO). For more information about the device token, see “Device Token” on page 17.
Retrieve the PMData Cookie RSA Adaptive Authentication (On-Premise) uses a persistent cookie, PMData, to store device tokens.
To retrieve the cookie using the Web Services API: 1. Retrieve the cookie from the user’s device. 2. Populate the Web Service parameter, deviceTokenCookie, with the value of PMData.
Retrieve a Flash Shared Object Token The Flash shared object (FSO) is a backup copy of the device token that is used if the PMData cookie has been deleted. The FSO is retrieved by playing an invisible Flash “movie.” Your application must have a listener that is ready to receive the posted data. If the user does not have Flash Player installed, the movie is not played and the FSO is not posted.
26 4: Device Information Collection RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
Before you Begin In the pmfso.jsp file, set the following values in the FlashVars parameter: • sendUrl—Address of the servlet to which the retrieved device token is posted. This is passed by the JavaScript or VBScript code to the Flash movie. • gotoUrl—Redirects the user to a specific target page after the Flash movie sends the tokens to the RSA application. If you do not want the user redirected, set gotoURL=””. • browserType—The user's browser type, which is used to distinguish between FSO names that were created in different browser types. The Flash movie, stored in the pmfso.swf file retrieves the device token and takes these values as part of the FlashVars variable:
Note: When placing the token in the FSO, you can also pass the gotoUrl variable with the value of a specific URL. The page that hosts the Flash redirects the user to the specified target page after the Flash movie sets the token in the FSO.
To retrieve an FSO token: 1. Detect whether Flash is installed. For more information, see “Detection of Flash Player” on page 27. 2. Detect the browser type. For more information, see “Detection of the Browser Type” on page 28. 3. Retrieve the device token. For more information, see “Retrieve the Device Token” on page 29. 4. Include the pmfso.jsp file in your logon page that contains the User ID field. For more information, see “Include the pmfso.jsp File in your logon page that contains the User ID field” on page 29. 5. Set the device token in session. For more information, see “Setting the Device Token in Session” on page 29. 6. Get the FSO token information from the session and populate Web Services. For more information, see “Retrieval of the Token from the Session” on page 29. Detection of Flash Player The scripts provided by RSA detect whether Flash is installed on the user’s device. This step avoids security warnings that are generated by trying to run Flash movies on a system that does not have Macromedia Flash installed. The AC_OETags.js script, provided by the Adobe Flash detection kit, is activated to detect the Flash version installed on the user's browser. You must use Flash version 6.0.0 or later to use the Flash token mechanism. Example from pmfso.jsp: Detection of the Browser Type The FSO token value represents the same token value that is created in the cookie placed on the browser. A user may use different types of browsers on the same computer to access the online site. In this case, different cookies are created for different browsers. Because the FSO value backs up the same cookie value, different FSOs are created for different browser types. To detect the browser type for the Flash usage, RSA uses the rsa.js file. This same file is used for gathering the device fingerprint. The rsa.js script must be called on every page that uses the Flash file. The script contains the BrowserDetect object, which collects the information about the user's browser. You must use a specific BrowserDetect.browser parameter within rsa.js to retrieve the browser type as a string. Example from Signin.jsp: <%@ include file="pmfso.jsp" %> Example from pmfso.jsp: ...""...
28 4: Device Information Collection RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
Retrieve the Device Token Run the Flash movie, contained in the pmfso.swf file to retrieve the device token. Include the pmfso.jsp File in your logon page that contains the User ID field When the sign-in page with User ID loads, the movie runs and fetches the device token from the FSO and posts it to the FSO Servlet while the user is entering his data. When the Flash movie is played, it reads the FSO data, and sends the data asynchronously to sendURL. The servlet reads the PMData from the HttpRequest object.
Note: The token is passed to the FSO servlet to ensure that the information is bound to the page hosting the movie. This prevents hackers from stealing movie tokens.
Retrieval of the Token from the Session For Web Services, you must get the FSO token information from the session and populate Web Services.
4: Device Information Collection 29 RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
Collection of Device Print Information RSA provides the rsa.js script, which: • Pulls the device print information from the web page • URL encodes the information • Posts the information to the server The server URL decodes the information for use within the RSA database The rsa.js script contains the add_deviceprint() function, which passes the device print information as a single string to RSA Adaptive Authentication (On-Premise). You must invoke this specific function within rsa.js to retrieve the device print information.
Note: The function, add_deviceprint(), only returns the value of devicePrint. It does not populate a hidden value to be returned to Adaptive Authentication (On-Premise).
The following is an example of HTML or JavaScript code that you must add below the sign-in page with the username field.
… … … …Device Print Fields For Web Services, this information is passed within the deviceRequest.devicePrint parameter. If you are using an earlier version of Adaptive Authentication (On-Premise), (such as the legacy PassMark system), you can implement the new rsa.js script without making changes to your existing pages. If you are using Web Services, you can continue to populate individual devicePrint-related fields, using the backward-compatible API. The following information is collected by the rsa.js script: • User-agent string—Contains information, such as the application name, version, host operating system, and language.
30 4: Device Information Collection RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
• Screen information—The color depth, width, height, and vertical space of the user’s screen. • Software plug-ins—The software plug-ins installed in the user’s browser. • Time zone—The user’s current time zone. • Browser language—The language that the user has set in the browser. • A Boolean value that indicates whether Java is enabled in the browser. • A Boolean value that indicates whether cookies are enabled in the user’s browser. • Operating system—The operating system installed. Possible values are: Windows, Linux, Mac, iPhone/iPad, and “unknown OS.” • Major version—The major version of the browser. • Browser type—The browser being used. Possible values are: Netscape, Mozilla, Explorer, Camino, Firefox, Konqueror, iCab, Opera, Safari, OmniWeb, Chrome. The following is an example of the devicePrint output. version=1&pm_fpua=mozilla/5.0 (windows; u; windows nt 5.1; en-us; rv:1.8.0.4) gecko/20060508 firefox/1.5.0.4|5.0 (Windows; en-US)|Win32&pm_fpsc=32|1280|1024|990&pm_fpsw=def|qt6|qt5|qt 4|qt3|qt2|qt1|swf|pdf|mso|j14|j32|j11|j12|j13|wpm|drn|drm&pm _fptz=-7&pm_fpln=lang=en-US|syslang=|userlang=&pm_fpjv=1&pm_ fpco=1
URL Encoding Example The following is the URL encoding performed on the preceding devicePrint output example. version=DEV_VERSION&pm_fpua=mozilla/5.0 (windows nt 6.1; wow64; rv:8.0.1) gecko/20100101 firefox/8.0.1|5.0 (Windows)|Win32&pm_fpsc=24|1440|900|860&pm_fpsw=|pdf|swf|mso &pm_fptz=2&pm_fpln=lang=en-US|syslang=|userlang=&pm_fpjv=1&p m_fpco=1&pm_fpasw=npgoogleupdate3|nppdf32|npctrl|npdeployjav a1|npjp2|nperoom7|npswf32|npwatweb|npnv3dvstreaming|npnv3dv| npwachk|npoffice&pm_fpan=Netscape&pm_fpacn=Mozilla&pm_fpol=t rue&pm_fposp=&pm_fpup=&pm_fpsaw=1440&pm_fpspd=24&pm_fpsbd=&p m_fpsdx=&pm_fpsdy=&pm_fpslx=&pm_fpsly=&pm_fpsfse=&pm_fpsui=& pm_os=Windows&pm_brmjv=8&pm_br=Firefox&pm_fp_inpt=1049&pm_fp _expt=1050
4: Device Information Collection 31 RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
Information Sent to Web Services The Web Services AuthRequest has a deviceRequest parameter, which contains various fields in which to populate the device information. Several of the variables listed in the following table are used for earlier versions of Web Services. The devicePrint parameter sets this value in Web Services 5.7 and later. If you are using Web Services 2.2 or 2.2.1, you can continue using older deviceRequest fields, or you can substitute with devicePrint. However, RSA recommends that you use devicePrint to pass these values to RSA Adaptive Authentication (On-Premise).
Variable Description Value
browserDevicePrint The Device Print of the browser. string
cookies The user’s cookies. array of cookie
deviceLanguage (For releases 2.2 - 2.2.1) The browser language setting information. string
devicePrint The information collected by the rsa.js script, for Device Print. For string more information, see “Retrieval of the Device Token” on page 26.
devicePrintChecked A Boolean value that tells Adaptive Authentication (On-Premise) boolean whether your system checked the Device Print. This value should be set to true if your system has attempted to retrieve the Device Print.
deviceTimeZone (For releases 2.2 - 2.2.1) The time zone of the user’s device. string
flashToken The Flash shared object. string
httpAccept The Accept value in the HTTP header. string
httpAcceptLanguage The Accept language value in the HTTP header. string
httpReferer The Referrer value in the HTTP header. string
ipAddress The IP address of the user’s device. string
language The user’s language setting. string
screenDevicePrint (For releases 2.2 - 2.2.1) The user’s screen device information. string
softwareDevicePrint (For releases 2.2 - 2.2.1) The plug-ins on the user’s device string
userAgent (For releases 2.2 - 2.2.1) The user agent string string
For more information about these fields within Web Services, see the API Reference Guide.
32 4: Device Information Collection RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
Overview of the Setting of Device Print Information RSA Adaptive Authentication (On-Premise) creates the device token when necessary and returns the token as part of the appropriate API message. You can choose to set device information at any time, however it must always be set. RSA recommends that you set device information at the following times: • Enrollment—Captures historical information on the user. • Challenge—After the user has successfully passed the challenge, the device information should be set. If the user fails the challenge, you do not need to set the cookie. • Transaction authentication—Setting the device information at the time of a transaction authentication helps to determine the validity of the user and prevent man-in-the-middle attacks.
Note: You must place the PMDataCookie and the fsoToken on the user’s device if returned within the return message. In accordance with general security best practices, RSA recommends that you verify that the device token received via the PMData parameter is properly formatted. Device tokens should only consist of numbers, letters, and the following special characters: +, \, and =.
4: Device Information Collection 33 RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
Device Print Information Set During Enrollment After the user has been successfully authenticated by your system, you can enroll the user into RSA Adaptive Authentication (On-Premise). RSA recommends that you set the device information when the user confirms the enrollment information. The following figure shows an overview of setting the device information during enrollment.
34 4: Device Information Collection RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
Device Print Information Set After a Successful Challenge After a user successfully passes a challenge through RSA Adaptive Authentication (On-Premise), you must place the device information on the user’s device, provided it is not a public computer, for example, a computer in a library or Internet cafe. Your system should ask the users if they are using a public device. The following figure shows an overview of setting the device information during challenge.
4: Device Information Collection 35 RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
Device Print Information Set During Transaction Authentication During a transaction, you need to collect device token information and place new information on the user’s browser. For information about how to collect the information, see “Collection of Device Print Information During Transaction Authentication” on page 23. When you initiate a transaction authentication, you receive a message back from RSA Adaptive Authentication (On-Premise) with device token information. Set this new token information on the user’s browser. Placing this information on the user’s browser can help prevent man-in-the-middle attacks. The following figure shows an overview of setting a device token during a transaction authentication.
36 4: Device Information Collection RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
Setting Device Print Information RSA Adaptive Authentication (On-Premise) passes two types of data to be placed on the user’s device: • A cookie named PMData • A Flash shared object (FSO)
Place the PMData Cookie You can set the cookie information using HTTP protocols.
To set the cookie information: Set the received deviceToken on the user’s machine in a cookie with the following properties: • Name—PMData • Max Age—365 days • domain—your domain name • path— “/” This ensures that the cookie is accessible from any URL on this server. • secure—for production, this must always be secure. • value—deviceToken
Place the Flash Shared Object Token RSA provides pmfso_set.jsp script to set the Flash shared object token on a user’s device.
To set the Flash shared object token: 1. Set the received deviceToken in the HTTP session when parsing the response. 2. Edit pmfso_set.jsp to get the information from the session. 3. Include pmfso_set.jsp in the landing page.
Note: When placing the FSO, make sure it is URL encoded.
The following steps outline how the fsoToken is set into the FSO using pmfso_set.jsp: 1. Detect whether Flash is installed. 2. Detect the browser type. 3. Run the Flash movie.
Note: The rsa.js, hashtable.js, and AC_OETags.js files must be included in pmfso_set.jsp or in the file that contains the pmfso_set.jsp file.
4: Device Information Collection 37 RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
In the pmfso_set.jsp file, two values within the FlashVars parameter are passed to the Flash movie and need to be set: • PMData—The value of the deviceToken that is extracted from the session. • browserType—The user's browser type that is used to distinguish between FSO names that were created in different browser types. The Flash movie, stored in the pmfso.swf file, retrieves the device token and takes these values as part of the FlashVars parameter, as shown below: FlashVars='PMData=the deviceToken value &browserType=the user's browser type' If you are using a web technology other than JSP, use the following code example to see how to call the movie and pass it the deviceToken.
<%@ page import="java.net.URLEncoder,java.util.regex.Matcher,java.util.regex. Pattern" %> <% // get the deviceToken from session. JavaScript will pass this value to the flash movie String pmfso_set_devToken = (String) session.getAttribute("_FLASH_SO_"); if (pmfso_set_devToken == null) { pmfso_set_devToken = ""; } Pattern p = Pattern.compile("[^0-9a-zA-Z/+=]"); Matcher m = p.matcher(pmfso_set_devToken); Boolean isTokenValid = false; if (!m.find()) { pmfso_set_devToken = URLEncoder.encode(pmfso_set_devToken, "UTF-8"); isTokenValid = true; } else { // Throw an error pmfso_set_devToken = ""; isTokenValid = false; } %>
38 4: Device Information Collection RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
4: Device Information Collection 39 RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
<% if (isTokenValid) { %> <%
40 4: Device Information Collection RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
5 Information Collection • Mobile Location Awareness This chapter describes the implementation mechanism that collects detailed information about the location of the end-user mobile device The collected data is entered into the RSA Risk Engine and helps RSA Adaptive Authentication (On-Premise) identify potential fraudulent transactions.
Note: Ensure that you integrate the JavaScript code from RSA into your web applications.
Mobile Location Awareness Mobile Location Awareness uses detailed information about the location of the end-user mobile device to support risk-based authentication. It enables organizations to identify the region or country from which the end user is attempting to access an account by way of a new or previously used mobile device. The RSA Mobile SDK - Adaptive Authentication Module and JavaScript collect data using GPS, WiFi, or cell tower triangulation. Based on the collected information and the end-user profile, Adaptive Authentication (On-Premise) determines: • Whether the end user is accessing an account from a location other than the usual location • Whether the end user is accessing an account from a high-risk area • The ground speed between two transactions
Note: This feature is relevant for the following W3C geolocation API types: HTML5 and BlackBerry proprietary API (version 4.1 and later).
The RSA Mobile SDK - Adaptive Authentication Module and JavaScript enable you to collect the following information: • Longitude • Latitude • Horizontal accuracy • Altitude • Altitude accuracy • Heading • Speed • Time stamp • Status code
5: Information Collection 41 RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
When the information is collected, it is formatted as a single string and sent to RSA Adaptive Authentication (On-Premise) as part of the geoLocation element within the DeviceRequest payload. For a detailed description of the information collected by the Mobile Location Awareness feature, see “MobileDevice” in the chapter “Web Services Request Data Structures and Types” in the API Reference Guide. For information about how to collect information for Mobile Location Awareness, see “Collect Information for Mobile Location Awareness” on page 45.
Overview of Information Collection for Mobile Location Awareness The following figure shows an overview of the information collection for Mobile Location Awareness.
For information about how to collect data for Mobile Location Awareness, see “Collect Information for Mobile Location Awareness” on page 45.
42 5: Information Collection RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
Script for Collection of Mobile Location Awareness Information RSA provides the same script, rsa.js, for the collection of device print information and Mobile Location Awareness. This script includes functions that collect detailed information about the location of the end-user mobile device to support risk-based authentication. When you collect information for Mobile Location Awareness, the information is formatted as a single string. This string is posted to your organization’s application and sent to RSA Adaptive Authentication (On-Premise).
Note: This script applies to the following W3C geolocation API types: HTML5 and BlackBerry proprietary API (version 4.1 and later). Ensure that you integrate the JavaScript code from RSA into your web applications.
Mobile Location Awareness Function Names The following functions in the rsa.js script are used to collect information for the Mobile Location Awareness feature: • startCollection—Initializes the collection of Mobile Location Awareness 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 information for Mobile Location Awareness.
Note: You must call this function during the onLoad event. You can define specific parameters that help configure the information collection for Mobile Location Awareness. For a list of these parameters, see “Mobile Location Awareness Parameters” on page 44.
• 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 information.
Note: If you choose to stop the collection, you can call the stopCollection function at any time after the onLoad event.
The string is posted to the application of your organization and sent to RSA Adaptive Authentication (On-Premise) as part of the geoLocation element within the DeviceRequest payload. For more information about the flow of this event within Web Services, see the API Reference Guide. For information about how to collect information for Mobile Location Awareness, see “Collect Information for Mobile Location Awareness” on page 45.
5: Information Collection 43 RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
Mobile Location Awareness Parameters RSA provides organizations with the option to define specific parameters that help configure the information collection for Mobile Location Awareness. If you do not specify the value for a parameter, or if the value exceeds the valid range, 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, you must 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).
Default Parameter Description Valid Range Value
Accuracy Threshold in meters for the accuracy of a position. This 100 5 - 200 parameter defines the radius of accuracy required to stop the collection of Mobile Location Awareness 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 the HTML5 geolocation API.
Timeout Threshold in seconds for receiving a valid position. If no 180 90 - 300 position is received within this period, the collection of Mobile Location Awareness information stops.
Relevancy Threshold in seconds for the age of a relevant position. If 120 60 - 240 the age of a position is lower than or equal to this value, the collection of Mobile Location Awareness information stops and that position is saved.
Expiration Threshold in hours for the maximum age of a cached 48 24 - 60 location. If the location is older than this value, a location value is not returned.
aidMode The level of accuracy according to the type of collection NA See “aidMode mechanism used. Functions” on page 45 for a list Note: This data type is relevant for the BlackBerry of available proprietary API (version 4.1 and later). aidMode values.
44 5: Information Collection RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
aidMode Functions The following table shows a list of aidMode functions.
aidMode Numeric Description Function Value
Cellsite Uses the GPS location of the cell site tower to provide first-order GPS 0 information.
Note: The cell site 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 2 the network.
Collect Information for Mobile Location Awareness 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 (version 4.1 and later). For information about which Mobile Location Awareness elements are collected, see “Collect Information for Mobile Location Awareness” on page 45.
Note: You must apply the script to each page that requires Mobile Location Awareness. You must send RSA the collected information as part of the geoLocation element within the DeviceRequest payload.
Before You Begin (Optional) Define specific parameters that help configure the information collection for Mobile Location Awareness. For a list of these parameters, see “Mobile Location Awareness Parameters” on page 44.
To collect information for Mobile Location Awareness: 1. After the HTML page loads and before the onSubmit event, initialize the information collection by calling the startCollection() function. 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 parentheses ().
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 the parameters in the table, see “Mobile Location Awareness Parameters” on page 44.
For example: startCollection(50,100,220,55,2) 3. During the onSubmit event, format the collected information into a single string by calling the following function: var geoLocationJSON= getGeolocationStruct(); For example:
Note: 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 steps 1 through 3 for each page that requires information collection for Mobile Location Awareness. The string is posted to the application of your organization and passed to RSA Adaptive Authentication (On-Premise) as part of the SOAP request. For more information about the flow of this event within Web Services, see the API Reference Guide.
46 5: Information Collection RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
Example of the Output for Mobile Location Awareness { "GeoLocationInfo": [ { "Status": "0", "Latitude": "32.1593746442196", "Longitude": "34.80888040361763", "Altitude": "33", "Heading": "0", "Speed": "0", "Timestamp": "1320814898265", "HorizontalAccuracy": "65" "AltitudeAccuracy": "10" }, ] }
5: Information Collection 47
RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
6 RDP Trojan Protection RSA Adaptive Authentication (On-Premise) is able to detect Trojan activities executed using malware with built-in Remote Desktop Protocol (RDP)/Virtual Network Computing (VNC) clients.
Note: The RDP Trojan Protection feature is designed for PC-based devices with a Microsoft Windows operating system only, and does not apply to mobile devices.
RDP Trojan Protection Module The RDP Trojan Protection application consists of three components: Collector. A JavaScript script, rsa.js, that collects data from an end-user device that accesses your application website and periodically reports data about the current session to the Browser Event Analyzer. Browser Event Analyzer. Web application that accepts the data from the Collector and analyzes the data for signs of potential fraud. If it identifies a potential fraudulent activity, the Browser Event Analyzer updates the Trojan activity blacklist. RDP Trojan Protection Database. Database where the Trojan activity blacklist resides. RDP Trojan detection requires that the devicePrint and userLoginName be sent to RSA Adaptive Authentication (On-Premise) as part of a SOAP analyze request call. Collected information related to the RDP Trojan Protection feature is also sent asynchronously to the Browser Event Analyzer, as soon as the JavaScript script detects that an end user has logged on. RSA provides the rsa.js (JavaScript) file for collecting the information for the RDP Trojan Protection feature. The rsa.js file includes all of the functions that are called based on the data that you want to collect. To implement the RDP Trojan Protection feature, the JavaScript file collects the following data elements: deviceId. Device identifier used to match the device ID sent in the Adaptive Authentication (On-Premise) SOAP analyze request to the attacked device in the Trojan blacklist. userLoginName. Unique user name or logon name provided by your organization to the online website user. timestamp. The time that the event information was collected according to the local device system clock. url. The URL of the current page that the end user is visiting. active_window. A Boolean value denoting whether the current window is active.
6: RDP Trojan Protection 49 RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
For information about installing the RDP Trojan Protection Database and deploying and configuring the Browser Event Analyzer, see the Installation and Upgrade Guide. For information about integrating the rsa.js file into web pages, see “Collect RDP Trojan Protection Information” on page 51. You must also select the Enable RDP Trojan Protection parameter in the Application section of the Administration Console. See the Operations Guide. The following figure shows an overview of the information collection for the RDP Trojan Protection feature.
50 6: RDP Trojan Protection RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
Collect RDP Trojan Protection Information Use the rsa.js file to collect information for the RDP Trojan Protection feature.
Before You Begin You must integrate the rsa.js (JavaScript) code in the relevant application pages of your online application for collecting device fingerprint data before you can collect information for RDP Trojan Protection. See “Collection of Device Print Information” on page 30.
Procedure 1. Add the device Trojan protection and fingerprint script code to the HTML pages that require Trojan protection, for example, Login, Payment, Add payee, Edit payee, and Deposit pages. In the header section of the web page, place the following text:
2. To begin data collection, place the following function in a script tag at the bottom of the HTML page or call this function during the DOM onLoad event. … For an explanation of the parameters, see “RDP Trojan Collection Parameters” on page 52. 3. Repeat steps 1 and 2 for each HTML page that requires collection for RDP Trojan Protection. The collected data is sent to RSA Adaptive Authentication (On-Premise) as part of the Device Fingerprint information in the deviceRequest.devicePrint SOAP API element. 4. To permit event information to be sent from your online application to the Browser Events Analyzer, follow these steps: a. Configure your online web server with an url_rewrite rule, using a target provided by RSA. This configuration provides the information needed to identify the site as legitimate. b. Open your online web firewall to allow secure communication over HTTPS with Adaptive Authentication.6: RDP Trojan Protection 51 RSA Adaptive Authentication (On-Premise) 7.2 Integration Guide
c. Report to Adaptive Authentication the source IP address to identify that the requests are routed from a legitimate website.
RDP Trojan Collection Parameters The following parameters are required for RDP Trojan Protection collection.
Parameter Description Required
loginname Callback method that returns the end-user logon name. This Y should be implemented by the online website developers.
Note: Returns an empty string if the end user did not log on.
url Relative path of the URL indicating where the online system N redirects the collected data to RSA Adaptive Authentication (On-Premise).
interval Interval in seconds that collected data is sent to the Browser N Events Analyzer. Valid interval values are 1, 2, 5, and 10 seconds. All other values are treated as the default value of 5 seconds.
52 6: RDP Trojan Protection