RSA® Adaptive Authentication (On-Premise) Version 7.3
Integration Guide RSA Adaptive Authentication Integration Guide 2 Contact Information RSA Link at https://community.rsa.com contains a knowledgebase that answers common questions and provides solutions to known problems, product documentation, community discussions, and case management. Trademarks Dell, RSA, the RSA Logo, EMC and other trademarks, are trademarks of Dell Inc. or its subsidiaries. Other trademarks may be trademarks of their respective owners. For a list of RSA 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 Dell Inc. or its subsidiaries 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 Dell Inc. Third-Party Licenses This product may include software developed by parties other than RSA. The text of the license agreements applicable to third-party software in this product may be viewed on the product documentation page on RSA Link. By using this product, a user of this product agrees to be fully bound by terms of the license agreements. 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 Dell software described in this publication requires an applicable software license. Dell Inc. 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." DELL INC. 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 © 1994-2020 Dell Inc. or its subsidaries. All Rights Reserved. Published: July 2020.
RSA Adaptive Authentication Integration Guide 3 Contents
About This Guide 6 Related Documentation 6 Support and Service 7 Before You Call Customer Support 7 Chapter 1: Security 8 Encryption 8 Encryption Algorithms 8 Key Creation and Storage 9 Enable Web Services Security 9 Reverse HTTP Proxy Server 11 Chapter 2: Validating User Data 13 Chapter 3: SafetyNet Validation for Adaptive Authentication Mobile SDK Modules 14 SafetyNet Validation Workflow 14 Integrate the Database 15 Running the SQL Scripts 16 Microsoft SQL Server Script Credentials 17 Oracle Database Script Credentials 17 Application Properties 17 Key Generator Application 18 Set the Key Generator Application Properties 18 Set the Loader Properties 18 Configure the Log 19 Error Codes 19 Chapter 4: Data Collection 20 Device Information 21 Device Print 22 Device Print Output Example 23 Device Tokens 23 Information Stored in a Device Token 24 Binding and Setting Device Tokens 24 Device Token Recovery 27 Device Token Theft Detection 28 Workflows for Collecting Device Information 28
RSA Adaptive Authentication Integration Guide 4 Collection of Device Print Information During Logon 29 Collection of Device Print Information During Enrollment 30 Collection of Device Print Information During Transaction Protection 31 Collection of Information Using the Mobile SDK 33 Collection Methods 34 Collect the Device Print Information 34 Scripts for Collection of Device Information 35 Functions in the rsa.js Script 36 Sample Scripts 37 Sample Script for Flash Detection 38 Sample Script for Browser Detection 38 Sample Script for Retrieving the Device Token 39 Sample Script for Setting the Device Token in a Session 40 Retrieving the Device Token 40 Retrieve a Device Token from a PMData Cookie 40 Retrieve a Device Token from a Flash Shared Object 41 Data Sent to Web Services 42 Workflows for Setting Device Information 43 Device Information Set During Enrollment 43 Device Information Set After a Successful Challenge Authentication 45 Device Information Set During Transaction Protection 46 Setting Device Token Information 47 Set the Flash Shared Object 47 Set the PMData Cookie 47 Set the Flash Shared Object Token 48 Chapter 5: Mobile Location Awareness 52 Mobile Location Awareness Workflow 53 Location Collection Parameters 54 aidMode Functions 55 Collect Information for Mobile Location Awareness 55 Send Collected Data 57 Chapter 6: RDP Trojan Protection 58 RDP Trojan Protection Overview 58 Collecting RDP Trojan Protection Information 59 RDP Trojan Collection Parameters 62
RSA Adaptive Authentication Integration Guide 5 About This Guide
This guide introduces the procedures that are required to integrate RSA Adaptive Authentication with existing applications, by enabling your application or web site to collect data from the user’s device and pass it to Adaptive Authentication. This guide is intended for web and mobile 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. Related Documentation
The Adaptive Authentication documentation set is comprised of these documents.
Guide Description Describes Adaptive Authentication Web Services API methods and parameters. This guide also describes how to build your own web services API Reference Guide clients and applications using a web services API to integrate and utilize the capabilities of Adaptive Authentication. Describes the Authentication Plug-In development process that enables Authentication Plug-In external authentication providers to integrate their products with Adaptive Developer’s Guide Authentication. Provides an overview of these Back Office applications: The Back Office User Administration Console, Policy Management, Case Management, Access Guide Management, Customer Service Administration, and Reports. Installation and Describes detailed procedures on how to install and configure Adaptive Upgrade Guide Authentication. Integration Guide Describes how to integrate and deploy Adaptive Authentication. Provides information on how to administer and operate Adaptive Operations Guide Authentication. Provides information about performance testing and performance test Performance Guide results for the current release version of Adaptive Authentication. Product Overview Provides a high-level overview of Adaptive Authentication, including Guide system architecture. Provides information about what is new and changed in this release, as well as workarounds for known issues. It also includes the supported Release Notes platforms and work environments for platform certifications. The latest version of the Release Notes is available on RSA Link®. Security Best Provides recommendations and best practices for the general security of Practices Guide Adaptive Authentication.
RSA Adaptive Authentication Integration Guide 6 Support and Service
Guide Description Describes the workflows and processes that allow end users to interact Workflows and with your system and that allow users to interact with Adaptive Processes Guide Authentication. Support and Service
Link Description
RSA Link ® RSA Link offers a knowledgebase that contains answers to common questions and solutions to known problems. It also offers information on new releases, important technical news, product documentation, and software downloads. The Downloads section of RSA Link contains the data collection library and WSDL files for released versions. For more information on the files in the data collection library, see the Integration Guide. For more information on calling Customer Support, see Before You Call Customer Support.
RSA Product and Customer RSA Product and Customer Support Services provides a full Support range of global support services to meet your organization's unique needs and requirements, including self-service and personalized support options.
RSA Ready Community 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
Before calling Customer Support, ensure that you have direct access to the computer running the software. Have this information available when you call:
l Your RSA Customer ID, License ID, or Site ID
l Adaptive Authentication software version or product number
l Make and model of the machine with the problem
l Name and version of the operating system used by the machine with the problem
l Name and version of the database
l Name and version of the application server
RSA Adaptive Authentication Integration Guide 7 Chapter 1: Security
There are several methods utilized to secure your implementation of Adaptive Authentication.
Encryption 8 Enable Web Services Security 9 Reverse HTTP Proxy Server 11 Encryption
Adaptive Authentication makes extensive use of encryption for internal operations with other systems, such as online systems. You must encrypt any sensitive data that is stored in the database or the file system. The only persistent data encrypted by Adaptive Authentication are the keys themselves. These keys are used for encrypting internal and customer messages, user phrases, and answers to challenge questions. This section describes where and how encryption is used in Adaptive Authentication.
Encryption Algorithms 8 Key Creation and Storage 9 Encryption Algorithms
Cryptography FIPS-validated RSA BSAFE® Crypto-J 6.1.3 cryptography module. module Java Cryptography Extensions (JCE) library, bundled into JDK 1.4 and later. Libraries The classes that are used are in the java.security and javax.crypto classes. RSA uses the default JCE Provider implementation.
l Advanced Encryption Standard (AES) — 128-bit keys . This is the preferred method for secret-key encryption. If your application requires a different Cryptographic encryption method, contact your Implementation Manager to discuss whether methods RSA can provide a customized encryption method.
l Triple-DES — Three 56-bit keys
RSA Adaptive Authentication Integration Guide 8 Key Creation and Storage
The key creation and storage mechanisms are different for each type of application use:
l Internal Token Keys. Keys for internal token encryption are generated within Adaptive Authentication 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 rotation, on a regular basis. You can configure the key rotation interval in the Administration Console, in the Key Life Time (days) parameter. The default value for key rotation 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.
l Persistence Keys. When Adaptive Authentication is 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.
Enable Web Services Security
All users issuing Adaptive Authentication web services API SOAP calls must be authenticated and authorized. The web services SOAP API and the AdminService API use Web Services Security (WS-Security) to authenticate the web service caller credentials. To enable WS-Security in Java:
l Set the user name and password in the soap header. This code sample shows the Java code for the SOAP header: /** * Create a security header for ws-security * @param user * @param password * @return */ private OMElement getSecurityHeaderElement(String user, String password) { /** * Set credential on HTTP header to support ws security */
RSA Adaptive Authentication Integration Guide 9 Enable Web Services Security
OMFactory omFactory = OMAbstractFactory.getOMFactory(); OMElement omSecurityElement = omFactory.createOMElement (new QName("http://docs.oasis-open.org/wss/2004/01/oasis -200401-wss-wssecurity-secext-1.0.xsd","Security", "wsse") , null); omSecurityElement.addAttribute("mustUnderstand", "1", null); OMElement omusertoken = omFactory.createOMElement (new QName("http://docs.oasis-open.org/wss/2004/01/oasis -200401-wss-wssecurity-secext-1.0.xsd", "UsernameToken", "wsse"), null); OMElement omuserName = omFactory.createOMElement (new QName("http://docs.oasis-open.org/wss/2004/ 01/oasis-200401-wss-wssecurity-secext-1.0.xsd", "Username", "wsse"), null); omuserName.setText(user); OMElement omPassword = omFactory.createOMElement ( new QName("http://docs.oasis-open.org/wss/2004/01/ oasis-200401-wss-wssecurity-secext-1.0.xsd", "Password", "wsse"), null); omPassword.addAttribute("Type", "http://docs. oasis-open.org/wss/2004/01/oasis-200401-wss- username-token-profile-1.0#PasswordText",null ); omPassword.setText(password); omusertoken.addChild(omuserName); omusertoken.addChild(omPassword) omSecurityElement. addChild(omusertoken); return omSecurityElement; }
This is the output for the security SOAP header.
As a security application server, the contents of Adaptive Authentication must be protected. RSA recommends that the Adaptive Authentication server is located behind one of the most secure segments of the firewall, in a location not open to network traffic directly from the Internet. You should 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. 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. You can use a reverse proxy to:
l Allow the RSA application server to reside in a more protected zone that is inaccessible to direct Internet traffic.
l Increase the chances that the requests reaching the application server are well formed. Reverse proxy servers inspect the contents of each request more thoroughly than most firewalls.
l Perform SSL acceleration and load distribution frequently. The SSL tunnel terminates at the reverse proxy server. The reverse proxy server listens for requests to a particular HTTP URL. When the reverse proxy receives a request, it creates a new request to the actual RSA server. Note: The RSA server must be able to determine the original source of the IP address of the end- user device, or, at least, the outside IP address of the end-user device firewall. The system uses the IP address for geolocation in forensics policies and authentication. The reverse proxy server must:
l Receive the original source IP address in one of two ways:
l The proxy maintains the same source IP address from which it received the original client request.
RSA Adaptive Authentication Integration Guide 11 Reverse HTTP Proxy Server
l The proxy places the original source IP address in the “x-forwarded-for” http header. The Apache proxy performs this action.
l Allow cookies to pass
l Allow Flash MIME types to pass
RSA Adaptive Authentication Integration Guide 12 Chapter 2: Validating User Data
Your application is responsible for performing first-level authentication on user data to ensure that it is valid before submitting the information to Adaptive Authentication. Adaptive Authentication 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 against a profanity list and checks certain special characters such as -, <, /, and \. Before sending collected information, your application must validate end-user input for these issues:
There are several methods for validating data entered by the end user, including Profanity using the same logic used to check an end user password. However, RSA currently does not offer any recommended method with which to check this information. SQL injection is a way to exploit your web application by inserting a SQL query or command into fields that are normally reserved for end-user information that is SQL submitted as input, such as the user name or password field. This query or command Injection then submits a request to your database. Adaptive Authentication provides functionality to check for SQL injection. Configure your application to check for potential SQL queries or commands.
XML injection is a way for fraudsters to manipulate the end-user SOAP API by inserting XML fragments into the end-user input fields. XML injection can cause XML undesired behavior of the system, such as disabling the RSA Risk Engine. Injection Configure your application to look for the following character strings and disallow these strings from the end-user input: .
Adaptive Authentication provides functionality to check for special characters. Configure your application to look for and disallow the following characters in end- Special user input: `, -, <, >, ", ', %, ;, (, ), &, +, \, /, #, ?, {., }., |, ^, ~, [, and ]. Characters If your system finds any of these characters within user data fields, the system displays an input error to the end user and prompts the end user to resubmit the data.
Adaptive Authentication provides functionality to check for scripting patterns. Scripting Configure your application to look for and disallow the following scripting patterns in Patterns end-user input: <, (, ', ", ` and \.
RSA Adaptive Authentication Integration Guide 13 Chapter 3: SafetyNet Validation for Adaptive Authentication Mobile SDK Modules
SafetyNet Validation Workflow 14 Integrate the Database 15 Running the SQL Scripts 16 Application Properties 17 Key Generator Application 18 Configure the Log 19 Error Codes 19 SafetyNet Validation Workflow
1. Adaptive Authentication Mobile SDK Modules sends a nonce generation request to WebService. 2. The nonce generated by the WebService is stored in the database and sent as response to the Adaptive Authentication Mobile SDK Modules.
RSA Adaptive Authentication Integration Guide 14 Integrate the Database
3. The SafetyNet Attestation API receives a call from Adaptive Authentication Mobile SDK Modules, which includes the nonce generated in step 1. The SafetyNet Attestation service evaluates the runtime environment and requests a signed attestation of the assessment results from Google servers. 4. Google servers send the signed attestation to the SafetyNet Attestation service on the device, which returns the signed attestation to the mobile application. 5. The mobile application forwards the signed attestation to the WebService. 6. The server validates the response. 7. The server returns the validation findings to the mobile application.
Integrate the Database
Google SafetyNet supports different databases, such as SQL Server and Oracle database. Deploy the SafetyNetValidation.War and edit the application.properties file to configure the database. For more information about deployment of the SafetyNetValidation.war file for all app- servers, see the Installation and Upgrade Guide. Prerequisites: To incorporate SafetyNet for Adaptive Authentication (On-Premise) 7.3, you must download these files from RSA Link:
l The latest Mobile SDK Modules package from RSA Adaptive Authentication Mobile SDK Downloads page.
l The SafetyNetValidation.war file from RSA Adaptive Authentication (On Premise) 7.3 Downloads page.
l The KeyGeneratorUtility.zip package from RSA Adaptive Authentication (On Premise) 7.3 Downloads page.
l The DB_Scripts.zip package from RSA Adaptive Authentication (On Premise) 7.3 Downloads page. To integrate the Database: 1. Open the SafetyNetValidation.war file. 2. Download the supported JDBC driver for the database and java support and add it in SafetyNetValidation.war\WEB-INF\lib. 3. In SafetyNetValidation.war\WEB-INF\classes, edit the application.properties file and select the desired database. Uncomment the lines in the section for the required database. For example, to connect the Oracle Database, uncomment the code in the Oracle Database Set Up, and comment the other database code sections: ##SQL Database setup #spring.datasource.driver-class- name=com.microsoft.sqlserver.jdbc.SQLServerDriver #spring.datasource.url=jdbc:sqlserver://
RSA Adaptive Authentication Integration Guide 15 Running the SQL Scripts
localhost:1433;databaseName=RSA_CORE_AA #spring.datasource.username=sa #spring.datasource.password=Admin123! #spring.datasource.driverClassName=com.microsoft.sqlserver.jdbc. SQLServerDriver #spring.jpa.database- platform=org.hibernate.dialect.MySQL5InnoDBDialect #spring.jpa.hibernate.dialect=org.hibernate.dialect.SQLServer201 2Dialect #spring.jpa.hibernate.ddl-auto = none #spring.jpa.generate-ddl=false #spring.datasource.initialization-mode=always #spring.datasource.schema=classpath:schema-mssql.sql ## Oracle Database SetUp spring.datasource.url=jdbc:oracle:thin:@10.125.244.39:1521:orcl spring.datasource.username=RSA_SAFETYNET_USER spring.datasource.password=RSA_SAFETYNET_USER spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.Or acle10gDialect spring.datasource.driver-class- name=oracle.jdbc.driver.OracleDriver Note: For Tomcat, download javax.transaction-api-1.2.jar and add it to the Tomcat/lib directory. 4. In SafetyNetValidation.war\WEB-INF\classes, edit the log4j.properties file and configure the required path to save the logs. 5. Save all changes in the SafetyNetValidation.war file.
Running the SQL Scripts
Create a directory to store the database file and database log file, with the directory path in the script. Credentials are provided to run the SQL scripts for the SafetyNet Database for a Microsoft SQL or Oracle database.
Microsoft SQL Server Script Credentials 17 Oracle Database Script Credentials 17
RSA Adaptive Authentication Integration Guide 16 Application Properties
Microsoft SQL Server Script Credentials
Use the credentials in this table to run the SQL scripts for the SafetyNet Database in the Microsoft SQL Server.
Script Credential 10_DBA_CreateEnv.sql System user 981_Grant_Privileges.sql DBA user mssql.sql DBA user 20_APP_CleanDatabaseObjects.sql Note: This script is only run to drop tables. DBA user
Oracle Database Script Credentials
Use the credentials in this table to run the SQL scripts for the SafetyNet Database.
Script Credential 10_DBA_CreateEnv.sql System user 981_Grant_Privileges.sql Schema user 982_APP_Synonyms_changes.sql Application user oracle.sql Schema user 20_DropSchemaObjects.sql Note: This script is only run to drop tables. Schema user
22_App_DropSchemaObjects.sql Note: This script is only run to drop tables. Application user
Application Properties
The properties file is located in the \SafetyNetValidation\WEB-INF\classes directory.
Parameter Oracle Value SQL Value jdbc:sqlserver:// jdbc:oracle:thin:
RSA Adaptive Authentication Integration Guide 17 Key Generator Application
Key Generator Application
The Key Generator is a separate jar file that is used to generate the access key. The customer id and access key are passed in the header while sending the request to validate a genuine user. If the value passed in header does not match, or is not located in the database, the user cannot use the service. The user must save the jar file. To manage the access key: 1. Download the KeyGeneratorUtility.zip package from RSA Adaptive Authentication (On Premise) 7.3 Downloads page and extract the files. 2. For Windows: Run the start.bat batch file. The CMD window opens. For Linux: Enter start.sh and click Enter. 3. Enter the username and password credentials. 4. View or generate the customerId key. Enter G to generate a new key, or V to view the current key.
Set the Key Generator Application Properties
To set the application properties: 1. Edit the \KeyGeneratorUtility\application.properties file. 2. Set the database for MSSQL and Oracle. Enter the values described in Integrate the Database.
Set the Loader Properties
To set the loader properties: 1. Download the supported JDBC driver for the database and java support. 2. Edit the properties file. Add the path in the loader.properties file. For example: loader.path=lib,C:\\safetynet\\KeyGeneratorUtility\\KeyGenerator Utility
3. Run the batch file.
RSA Adaptive Authentication Integration Guide 18 Configure the Log
Configure the Log
To configure the log:
l In the KeyGeneratorUtility\log4j.properties file, change the log level by editing these fields: log4j.rootLogger=DEBUG, LOGFILE log4j.logger.org.apache=DEBUG, LOGFILE
Error Codes
These error codes can be displayed:
Error Code Description 400 A required parameter is missing. 401 There is no record in the database for the android device in the validation API. 402 The validation api failed due to an internal error. 403 The JWSResponse is in an incorrect format. 405 The CustomerId and access key are incorrect
RSA Adaptive Authentication Integration Guide 19 Chapter 4: Data Collection
Your organization can maximize Adaptive Authentication's risk-based authentication capabilities by integrating data collection mechanisms into your web pages. The various collection techniques allow you to collect information from the device that is trying to access your application, and use that information together with the Adaptive Authentication API. The data collection techniques get information such as device fingerprint information, mobile device identifiers, Trojan indicators, and token codes used to identify end users from browser cookies and Flash shared objects, from the end-user's device. Adaptive Authentication creates a unique device token code, comprised of a static code and a time stamp, and sends the token information to your system in the API response messages that require user authentication. Whenever the token is sent in the response message, your application must set the cookie, Flash shared object (FSO), or both on the end-user device. Your web site developer incorporates the device collecting mechanisms into your web pages to gather the information from the device and the cookie that you set on the device.
Device Information 21 Device Print 22 Device Tokens 23 Workflows for Collecting Device Information 28 Collection of Device Print Information During Logon 29 Collection of Device Print Information During Enrollment 30 Collection of Device Print Information During Transaction Protection 31 Collection of Information Using the Mobile SDK 33 Collection Methods 34 Collect the Device Print Information 34 Scripts for Collection of Device Information 35 Functions in the rsa.js Script 36 Sample Scripts 37 Sample Script for Flash Detection 38 Sample Script for Browser Detection 38 Sample Script for Retrieving the Device Token 39 Sample Script for Setting the Device Token in a Session 40 Retrieving the Device Token 40 Retrieve a Device Token from a PMData Cookie 40 Retrieve a Device Token from a Flash Shared Object 41 Data Sent to Web Services 42 Workflows for Setting Device Information 43
RSA Adaptive Authentication Integration Guide 20 Device Information
Device Information Set During Enrollment 43 Device Information Set After a Successful Challenge Authentication 45 Device Information Set During Transaction Protection 46 Setting Device Token Information 47 Set the Flash Shared Object 47 Device Information
Device information is a group of facts from an end-user device. These facts feed into the RSA Risk Engine and help identify fraudsters and fraudulent activities. JavaScript and HTTP request headers are used to collect these facts. The device information that is collected helps to uniquely identify an end-user device. This table describes the types of device information that are collected for each device that interacts with Adaptive Authentication.
Information Description Type HTTP header fields define the operating parameters of a transaction. Information in the HTTP headers includes:
l Accept string. HTTP l Referrer value. headers l Accept-Language string. This language may be different from the language captured by the Device Print scripts.
l User-Agent string. This request information is captured to validate the authenticity of the device token and for further forensic analysis and fuzzy matching.
Source IP addresses are used to further validate the device and to generate user geolocation 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 (IPv4 or IPv6) is fronted with a reverse proxy server, you can use a Source IP "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.
Adaptive Authentication creates a globally unique device ID for each device that accesses your online application. The device ID, together with additional methods, is used to verify the identity of the client device. The additional methods are: Device ID l Device forensics. Analysis of the detailed hardware and software characteristics, or Device Print, of each computer.
l Network forensics. Analysis of the IP address, subnet, ownership, and
RSA Adaptive Authentication Integration Guide 21 Device Information
Information Description Type
geographic location of the network connection that the computer is using. For more information, see Device Print.
For information on mobile device information, see the API Reference Guide. Mobile For information on integrating the Adaptive Authentication Mobile SDK Modules - device Adaptive Authentication Module, setting the user permissions, and installing and information using the sample application, see the RSA Mobile SDK - RSA Adaptive Authentication Module Developer's Guide.
User - defined For information on user-defined credentials, see the API Reference Guide. credentials Adaptive Authentication handles the device information used in step-up Device authentication in the form of encrypted device tokens, also referred to as device token 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). Device Print
The device print elements are fed into the RSA Risk Engine and contribute to risk analysis and fuzzy matching. RSA supplies a series of scripts to gather this information. For more information, see Scripts for Collection of Device Information. The device print consists of these data elements:
Data Description Elements Includes this information:
l Browser type. The browser being used, for example, Explorer, Firefox, or Chrome. User agent l Major version. The major version number of the browser. string l Operating system. The operating system installed on the device, for example, Windows, Linux, or iPhone/iPad.
l Language. The browser language and the system language.
Screen The width, height, and color depth of the screen. resolution Plug-in The browser plug-ins that are installed on the device. information Time zone The end-user time zone in GMT. Java-enabled A Boolean value that indicates whether the end user has Java enabled on the
RSA Adaptive Authentication Integration Guide 22 Device Information
Data Description Elements device A Boolean value that indicates whether the end user has cookies enabled on the Cookies device. Latency Internal IP and external IP ping time.
Device Print Output Example
This 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|qt4|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 This example shows URL encoding performed on the devicePrint output. 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&pm_fpco=1&pm_ fpasw=npgoogleupdate3|nppdf32|npctrl|npdeployjava1|npjp2|nperoom7| npswf32|npwatweb|npnv3dvstreaming|npnv3dv|npwachk|npoffice&pm_ fpan=Netscape&pm_fpacn=Mozilla&pm_fpol=true&pm_fposp=&pm_fpup= &pm_fpsaw=1440&pm_fpspd=24&pm_fpsbd=&pm_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
Device Tokens
Adaptive Authentication handles the device information used in step-up authentication in the form of encrypted device tokens, also referred to as device cookies or PMData cookies. A device token helps to authenticate an end user when the end user signs in to your online application and during transaction authentication. The collection of device token information is optional. When a user enrolls in Adaptive Authentication, the system generates a device token and stores the token on the client device, using two different methods:
l 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 the P3P definition.
RSA Adaptive Authentication Integration Guide 23 Device Information
l Flash shared objects. The system uses a Flash shared object (FSO) 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. The device token is also stored in the User ID record in the database after enrollment is completed.
Information Stored in a Device Token
Data encoded into device tokens includes payload data (device ID, user-agent string to identify browser and creation date) and protocol data (version number, key ID, and checksum). Adaptive Authentication calculates a checksum, and provides encryption for all data stored in a device token on the client device. The encryption ensures the integrity of the data and verifies Adaptive Authentication as the source of the data. Because the sending and receiving parties are the same, the system uses secret-key encryption to encrypt device tokens. Note: Adaptive Authentication uses the FIPS-validated RSA BSAFE® Crypto-J 6.1.3 cryptography module for encryption. Each device token is constructed using this format: [Token Version][Key Name][Encrypted Token Information] where:
Token Version The version of the device token, for example, version 3 is V3. Key Name The name of the key used to encrypt the data within the token. Includes:
l Device ID Encrypted Token Information l Creation date
l Checksum of the device ID and creation date values
Binding and Setting Device Tokens
Adaptive Authentication associates the device token with a particular end-user device by setting or binding the device token. You can configure how the device token is associated with the end-user device:
l Set a token. This method places a device token on an end-user device.
l Bind a token. This method places a device token on the end-user device and associates the device with that particular end user. Device binding (linking an end user and a device) helps identify the end user and allows the end user to log on to your system without being challenged. Typically, an end user is bound to a device after successfully enrolling in Adaptive Authentication and after successfully responding to a challenge authentication.
RSA Adaptive Authentication Integration Guide 24 Device Information
A single end user can log on to your application from more than one device by logging on from each machine and passing a challenge authentication. For example, a single end user can use a computer at home and a computer at work to log on to your application. In addition, a single device can be bound to more than one end user through single or multiple tokens on the same machine. For example, a family with multiple end users can use one computer to log on to their respective online accounts. You can configure this when your application binds an end user to a device, such as after the end user successfully enrolls, or after the end user has successfully passed a challenge authentication, and when the application sets a device token. If the device token is not present or if the end user is not bound to a device, for example, when logging on from a different computer, the end user may be presented with a challenge authentication. During certain actions, such as transaction protection, a device token can be set on an end-user device that is not bound to the end user. Setting the device token for these actions can help detect fraud, such as man-in-the-middle attacks. This example shows the SOAP request to create an end user with device binding.
RSA Adaptive Authentication Integration Guide 25 Device Information
RSA Adaptive Authentication Integration Guide 26 Device Information
Device Token Recovery
When an enrolled end user logs on to Adaptive Authentication, the system searches for device tokens on the end-user device. The end user may have deleted or suppressed cookies or disabled Flash Player, which prevents Adaptive Authentication from identifying the end user as a valid user. Consequently, the end user may be presented with a challenge authentication. Device token recovery helps prevent a legitimate end user from unnecessary challenge authentications if the end user deletes cookies or disables the Flash player. Device token recovery works only for devices that are bound to the end user. Device token recovery is only relevant for web and mobile channels. Note: In earlier versions, data elements were used to determine whether the channel was Web or Mobile. Starting from version 7.0, the Channel Determination Service is used to identify the type of channel. Device token recovery is automatically enabled. You can disable device token recovery by modifying the relevant parameters in the Administration Console. For more information, see the Back Office User Guide. Note: Due to forensic similarities between browsers across mobile devices, RSA recommends that you modify the parameters in the Administration Console to disable device token recovery specifically for mobile browsers. These steps describe the device token recovery process: 1. If an end user logs on to your system and the device token is missing, the system attempts to re-create the device token for the end user using information such as:
l Source IP address
l HTTP header information
l Device print information The information in the database is compared to the information from the current client device and passes through various models that determine how well the information matches. A device recovery score is generated based on the match. 2. The device recovery score is matched against your policies within the Policy Engine to determine if the score meets a threshold setting for device token recovery confidence, resulting in one of these scenarios:
l If the device recovery score exceeds the threshold, the device token is considered recovered, and the end user is allowed to proceed without a challenge authentication.
l If the device recovery score does not meet the threshold, the device token is not considered recovered, and the end user may be presented with a challenge authentication. If the device token is recovered, a new device token is generated from the recovered record and sent back to the application to update the end-user device.
3. The database is updated with new information indicating that a device token recovery occurred.
RSA Adaptive Authentication Integration Guide 27 Workflows for Collecting Device Information
Device Token Theft Detection
Device token theft detection identifies when a fraudster, who steals a device token from a legitimate device, attempts to use the token on another machine. These steps descrie the process of device token theft detection: 1. Because a device token is regenerated each time an end user accesses the system, an old instance of a token is detected. 2. An analyzer compares the retrieved token to the end-user history, resulting in either a low or high match confidence:
l If the match confidence is low, a high risk score is assigned to that device, which triggers Adaptive Authentication to issue a challenge authentication for the device and prevents the fraudster from accessing your system.
l If the match confidence is high, a low risk score is assigned to the device. You can choose to either issue a challenge authentication to the end user or allow the end user access based on policy facts available in the Policy Management application.
3. The database is updated with the new information including a high-risk score for that device token.
Workflows for Collecting Device Information
RSA recommends that device print information always be collected:
l During logon, to help 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 page.
l During enrollment, to capture historical information on the user. After the user is successfully authenticated by your system, you can enroll the user into Adaptive Authentication. RSA recommends that you send the information to Adaptive Authentication when the user selects, for example, an image, a phrase, and challenge questions during enrollment. The collected information and caption are posted to the server at the same time.
l 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 when the user begins a transaction. During this period, your application should write the collected information to the client browser.
Collection of Device Print Information During Logon 29 Collection of Device Print Information During Enrollment 30 Collection of Device Print Information During Transaction Protection 31 Collection of Information Using the Mobile SDK 33
RSA Adaptive Authentication Integration Guide 28 Workflows for Collecting Device Information
Collection of Device Print Information During Logon
During logon, you must ensure that your application captures the device information when the end user submits the user name. You can then post all the device information and User ID within one given page. This figure describes the collection of device print information during logon.
These steps describe the workflow: 1. The end user tries to log on to your online system. 2. Your online system prompts the end user to enter a user name and password. 3. If flash is enabled on the end-user device, the data-gathering JavaScript executes as the page loads and collects the Flash shared object (FSO) data. 4. If JavaScript is enabled on the end-user device, the data-gathering JavaScript collects device print information.
RSA Adaptive Authentication Integration Guide 29 Workflows for Collecting Device Information
5. The data-gathering JavaScript executes as the page loads and collects the device data, such as the IP address, browser information, device fingerprint, deviceTokenCookie, and deviceTokenFSO. 6. The end user enters the user credentials and clicks the submit button. The device data is sent along with the user credentials. 7. Your online system verifies the user credentials. 8. Your online system sends the end user credentials and device information to Adaptive Authentication.
Collection of Device Print Information During Enrollment
After the end user is successfully authenticated by your system, you can enroll the end user into Adaptive Authentication. RSA recommends that you send the device information to Adaptive Authentication during enrollment, for example, when the end user selects challenge questions during enrollment. The device information is posted to the server at the same time. For more information, see Device Information Set During Enrollment. This figure describes the collection of device print information during enrollment.
These steps describe the workflow: 1. The end user tries to log on to your online system. 2. Your online system prompts the end user to enter a user name and password. 3. If JavaScript is enabled on the end-user device, the data-gathering JavaScript executes as the page loads and collects the device data, such as the IP address, browser information, device fingerprint, deviceTokenCookie, and deviceTokenFSO.
RSA Adaptive Authentication Integration Guide 30 Workflows for Collecting Device Information
4. The online system displays a set of challenge questions for the end user. 5. The end user selects and submits challenge questions and answers. 6. The online system sends the challenge questions and answers to Adaptive Authentication.
Collection of Device Print Information During Transaction Protection
RSA recommends that you send the device information to Adaptive Authentication when the end- user begins an activity. During this period, your application should write the device token information to the client browser. For more information, see Device Information Set During Transaction Protection. This figure describes the collection of device print information during an activity.
Thse steps describe the workflow: 1. The end user initiates a transaction. 2. Your online system displays the transaction screen.
RSA Adaptive Authentication Integration Guide 31 Workflows for Collecting Device Information
3. If flash is enabled on the end-user device, the data-gathering JavaScript executes as the page loads and collects the Flash shared object (FSO) data. 4. The end uses submits the transaction information. 5. The online system servlet filter listens for the FSO data. 6. If JavaScript is enabled on the end-user device, the data-gathering JavaScript collects device print information. 7. The data-gathering JavaScript collects the device data, such as the IP address, browser information, device fingerprint, deviceTokenCookie, and deviceTokenFSO. 8. The online system servlet sends a request to the end-user device for data. 9. The end-user device sends transaction and device data to the online system servlet. 10. The online system sends the end user credentials and device information to Adaptive Authentication.
RSA Adaptive Authentication Integration Guide 32 Workflows for Collecting Device Information
Collection of Information Using the Mobile SDK
The RSA Adaptive Authentication Mobile SDK Modules 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 Mobile SDK Data Collection Module Developer's Guide. RSA recommends that you collect the information using the Adaptive Authentication Mobile SDK Modules during logon, enrollment and transaction protection. This figure describes the collection of device information during logon, enrollment, and transaction protection.
These steps describe the workflow: 1. The end user attempts to log on or enroll to the system, or initiates a transaction. 2. Your online system displays the transaction screen. 3. The RSA Adaptive Authentication Mobile SDK Data Collection Module collects end-user device data such as the simId, otherId, hardwareId, location data and device model. 4. The online system servlet filter listens for the FSO data. 5. The online system collects the mobile parameters from the end-user device and returns them to the servlet. 6. The online system sends the mobile parameters to Adaptive Authentication.
RSA Adaptive Authentication Integration Guide 33 Collection Methods
Collection Methods
Adaptive Authentication supports different data collection methods. The developer incorporates the selected mechanisms in the pages constructed for the website, mobile site, or mobile application. Data collection methods can be performed using one of these options:
Option Description In the JavaScript collection method, the developer implements a JavaScript code in the desired application page. The JavaScript JavaScript collects detailed hardware and software characteristics from the end user's device and enables passing it to the Adaptive Authentication system in a SOAP request message. In the Flash shared object (FSO) collection method, your system stores a device cookie as a Flash movie file on the user's device. Flash Shared Objects (FSO) This technique enables storing of information on the user’s device in the same way that cookies do, and allows you to retrieve it at a later time.
Mobile Data Collection: In mobile data collection, you can use either the JavaScript or the RSA Mobile SDK to retrieve 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.
l For mobile browsers, Mobile Location Awareness, an element of Adaptive Authentication’s Enhanced Mobile Protection functionality uses the JavaScript to collects mobile geoLocation information, the location of the end user mobile device.
l For mobile applications, the RSA Adaptive Authentication Mobile SDK Data Collection Module is used to collect the location information and other mobile device identifiers.
Collect the Device Print Information
Adaptive Authentication provides the rsa.js script, which:
l Pulls the device print information from the application.
l URL encodes the information.
l Posts the information to Adaptive Authentication. 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 Adaptive Authentication. You must invoke this specific function within rsa.js to retrieve the device print information. Note: The add_deviceprint() function only returns the value of devicePrint. The function does not populate a hidden value to be returned to Adaptive Authentication.
RSA Adaptive Authentication Integration Guide 34 Scripts for Collection of Device Information
To collect the Device Print information: 1. Add the HTML or JavaScript code below the signin page with the username field, calling the rsa.js script and invoking the add_deviceprint() function.
… … … …Scripts for Collection of Device Information
RSA provides mechanisms that your application can use to interface with the client browser and mobile application and with Adaptive Authentication Ensure that you integrate rsa.js from Adaptive Authentication into your web application. The JavaScript code in rsa.js collects device information from end users. It is mandatory that you send RSA the device information through the deviceRequest element. For web service calls, you must get the Flash shared object (FSO) and cookie information from the session and populate web services. 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. This table describes the scripts that are included for device collection.
Script Name Description The JavaScript file created by Adobe that is responsible for detecting the Flash AC_OETags.js version on the client browser. The reference file that shows how to collect device information and post the rsa.js information back to Adaptive Authentication. hashtable.js A file that provides hashtable functionality for use within javascript. Wherever in
RSA Adaptive Authentication Integration Guide 35 Functions in the rsa.js Script
Script Name Description your code you call thersa.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. The Flash movie that reads and sets the FSO. pmfso.swf Do not edit this file.
This table describes the sample scripts included for your reference.
Script Name Description The servlet that shows how to retrieve posted PMData PassMarkSimpleFSOServlet.java using the invisible Flash movie. The reference file that shows how to run the Flash pmfso.jsp movie and retrieve the device token from the Flash shared object (FSO). The reference file that shows how to run the Flash pmfso_set.jsp movie and set the device token in the FSO. The file that demonstrates how to include the reference Signin.jsp information found in pmfso.jsp and rsa.js in the logon workflow. Functions in the rsa.js Script
This table describes functions in the rsa.js script that are used to collect information to different features.
Related Function Name Description Feature Passes the device print information as a single encode_deviceprint() string to Adaptive Authentication. dom_data_ Configures the collection of DOM elements, HTML collection.initFunctions such as field names, iFrames, and function Injection ToExclude names. Protection Runs the main collection of information. HTML dom_data_collection.start You must call this function after the onLoad Injection Inspection event is called and before the onSubmit event is called. Protection dom_data_ HTML Formats the collected DOM elements into a collection.domData Injection single string. AsJSON Protection UIEventCollector.initEvent Initializes the collection of data when the Man vs.
RSA Adaptive Authentication Integration Guide 36 Sample Scripts
Related Function Name Description Feature HTML page loads. You must call this function after the onLoad Machine Collection event is called and before the onSubmit Detection event is called.
Formats the collected browser events into a single string. Man vs. UIEventCollector.serialize You must call this function after the onLoad Machine event is called and before the onSubmit Detection event is called.
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 Mobile startCollection you call this function, the end user receives a Location request to approve the collection of Awareness information for Mobile Location Awareness. You must call this function during the onLoad event.
Formats the collected information into a single string. If you call the stopCollection function during the collection, the getGeolocationStruct function formats Mobile getGeolocationStruct the information collected from the time that the Location onLoad event is called until the time that the Awareness stopCollection function is called. You must call this function during the onSubmit event.
Stops the collection of information. If you choose to stop the collection, you can Mobile stopCollection call the stopCollection function at any Location time after the onLoad event. Awareness
Sample Scripts
These scripts are examples of scripts for collecting and setting device information.
Sample Script for Flash Detection 38 Sample Script for Browser Detection 38 Sample Script for Retrieving the Device Token 39 Sample Script for Setting the Device Token in a Session 40
RSA Adaptive Authentication Integration Guide 37 Sample Scripts
Sample Script for Flash Detection
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 client browser does not have Flash Player installed, the movie is not played, and the FSO is not posted. You must use Flash version 6.0.0 or later to use the Flash token mechanism. The AC_OETags.js script, provided by the Adobe Flash detection kit, detects the Flash version installed on the client browser. This step avoids security warnings that are generated by trying to run Flash movies on a system that does not have Macromedia Flash installed. This example shows the Flash player detection in pmfso.jsp.
Sample Script for Browser Detection
The FSO token value represents the same token value that is created in the cookie placed on the browser. An end user may use different types of browsers on the same device to access the online application. In this case, different cookies are created for different browsers. Because the FSO value backs up the same cookie value, different Flash shared objects (FSOs) are created for different browser types.
RSA Adaptive Authentication Integration Guide 38 Sample Scripts
To detect the browser type for the Flash usage, Adaptive Authentication uses the hashtable.js and rsa.js files. This same file is used for gathering the device fingerprint. The hashtable.js and rsa.js scripts must be called on every page that uses the Flash file. The script contains the BrowserDetect object, which collects the information about the client browser. You must use a specific BrowserDetect.browser parameter in rsa.js to retrieve the browser type as a string. This example shows the browser detection in Signin.jsp: <%@ include file="pmfso.jsp" %> This example shows the browser detection in pmfso.jsp: ...""...
Note: You must ensure that the gotoUrlEnc and sendUrlEnc parameters are URL encoded and that the destination locations are authorized locations, to avoid security issues. Sample Script for Retrieving the Device Token
The Flash movie, contained in the pmfso.swf file, retrieves the device token. You must 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 Flash movie runs, fetches the device token from the Flash shared object (FSO), and posts the device token to the FSO servlet while the end user is entering data. The FSO servlet reads the PMData from the HttpRequest object. This example shows a script that includes the pmfso.jsp file.
RSA Adaptive Authentication Integration Guide 39 Retrieving the Device Token
<%@ include file="pmfso.jsp" %> ... Username:
Sample Script for Setting the Device Token in a Session
After retrieving the token device, the Flash movie posts the retrieved device token to a Flash Shared Object (FSO) servlet. This servlet stores the device token using session-based mechanisms. You can use the reference servlet to create your own listener to receive the posted FSO data. The Flash movie posts the device token under the PMData parameter. The following is an example of a JavaScript that sets the device token: //get device token from request fsoToken = request.getParameter("PMData"); //store it in the session session.setAttribute(ATTR_FLASH_SO, fsoToken); This is an example of a VB Script that sets the device token: If Not Request.Form("PMData") Is Nothing AndAlso Request.Form("PMData").Trim().Length > 0 Then pmfso = Request.Form("PMData") Session("pmfso") = pmfso 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. Retrieving the Device Token
You must retrieve the device token, which is stored as both a PMData cookie and a Flash shared object (FSO).
Retrieve a Device Token from a PMData Cookie 40 Retrieve a Device Token from a Flash Shared Object 41 Retrieve a Device Token from a PMData Cookie
Adaptive Authentication uses a persistent cookie, PMData, to store device tokens. To retrieve a device token from a PMData Cookie: 1. Using the Web Services API, retrieve the PMData cookie from the client device. 2. Populate the Web Services deviceTokenCookie element with the value of PMData.
RSA Adaptive Authentication Integration Guide 40 Retrieving the Device Token
Retrieve a Device Token from a Flash Shared Object
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. Prerequisites: The Flash movie, stored in the pmfso.swf file, retrieves the device token and takes these values as part of the FlashVars variable: In the pmfso.jsp file, set these values in the FlashVars parameter:
Value Description Address of the servlet to which the retrieved device token is posted. This is sendUrl passed by the JavaScript or VBScript code to the Flash movie Redirects the end user to a specific target page after the Flash movie sends the gotoUrl device token to Adaptive Authentication. If you do not want the end user to be redirected, set gotoURL= “”.
The end-user browser type, which is used to distinguish between FSO names BrowserType that were created in different browser types.
Note: When placing the device token in the FSO, you can also pass the gotoUrl variable with the value of a specific URL. The page that hosts the Flash movie redirects the end user to the specified target page after the Flash movie sets the device token in the FSO. To retrieve a device token from an FSO: 1. Detect whether Flash is installed. For more information, see Sample Script for Setting the Device Token in a Session. 2. Detect the browser type. For more information, see Sample Script for Browser Detection. 3. Retrieve the device token. For more information, see Sample Script for Retrieving the Device Token. 4. Include the pmfso.jsp file in your logon page that contains the UserID field. 5. Set the device token in the session. For more information, see Sample Script for Setting the Device Token in a Session. 6. Get the FSO token information from the session and populate Web Services. For more information, see Collect the Device Print Information.
RSA Adaptive Authentication Integration Guide 41 Data Sent to Web Services
Data Sent to Web Services
The Web Services AuthRequest has a deviceRequest parameter, which contains various fields in which to populate the device data. Several of the variables listed in this table are used for earlier versions of Web Services. The devicePrint parameter sets this value in Web Services 7.
Variable Description Value
browserDevicePrint The Device Print of the browser. string
cookies The deviceTokenCookie. array of cookies
deviceLanguage The browser language setting information. string
devicePrint The information collected by the rsa.js script for string Device Print. See Scripts for Collection of Device Information.
devicePrintChecked A Boolean value that tells Adaptive Authentication boolean whether your system checked the Device Print. This value should be set to true if your system attempted to retrieve the Device Print.
deviceTimeZone The time zone of the end-user 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 device. string
language The end-user language setting. string
screenDevicePrint The end-user screen device information. string
softwareDevicePrint The plug-ins on the end-user device. string
userAgent The User-Agent string. string
For more information about these fields within Web Services, see the API Reference Guide.
RSA Adaptive Authentication Integration Guide 42 Workflows for Setting Device Information
Workflows for Setting Device Information
Adaptive Authentication creates a 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 these times:
l During enrollment, to capture historical information on the end user.
l After a successful challenge authentication. If the end user fails the challenge authentication, you do not need to set the cookie.
l During transaction protection, to help determine the validity of the end user and prevent man- in-the-middle attacks. Note: You must place the PMDataCookie and the fsoToken on the end-user 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 =. Device Information Set During Enrollment
After your system has successfully authenticated the end user, you can enroll the end user into Adaptive Authentication. RSA recommends that you set the device information when the end user confirms the enrollment information.
RSA Adaptive Authentication Integration Guide 43 Workflows for Setting Device Information
This figure describes setting the device information during enrollment.
These steps describe the workflow: 1. The end user initiates enrollment and your online system prompts the user to select challenge questions and answers. 2. If JavaScript is enabled on the end-user device, the data-gathering JavaScript collects device print information. 3. The online system servlet filter listens for the FSO post. 4. The online system collects the device data, such as cookie, FSO and other device token information and sends it to the end user device browser. 5. The online system displays the confirmation screen and sets the cookie information. The end user clicks the OK button. 6. The online system passes the user and device data to Adaptive Authentication. 7. Adaptive Authentication sends the token information to the online system. 8. The end user continues to other transactions.
RSA Adaptive Authentication Integration Guide 44 Workflows for Setting Device Information
Device Information Set After a Successful Challenge Authentication
After an end user passes a challenge authentication, you must place the device information on the end-user device, provided the device is not a public device, for example, a computer in a library or Internet cafe. Your system should ask if the end user is using a public device. This figure describes setting the device information during a challenge authentication.
These steps describe the workflow: 1. The end user logs on and your online system prompts the user to answer the challenge question. 2. The end user submits an answer to the challenge question. 3. The online system performs data validation and sends the challenge answer to Adaptive Authentication. 4. Adaptive Authentication processes the user answer and calculates if the answer is correct. 5. If the user's answer score is greater than zero, Adaptive Authentication sends the cookie, FSO and other device token data to the online system. 6. The online system sets the device cookie data.
RSA Adaptive Authentication Integration Guide 45 Workflows for Setting Device Information
7. The online system passes the cookie, FSO and device token data to the end user browser. The JavaScript script sets the FSO data. The end user clicks the OK button to accept. 8. The end user continues to other transactions.
Device Information Set During Transaction Protection
During an activity, you must collect device token information, as well as place new information on the end-user browser. For information about how to collect the information, see Collection of Device Print Information During Transaction Protection. When you initiate transaction protection, you receive a message back from Adaptive Authentication with device token information. Set this new token information on the end-user browser. Placing this information on the end-user browser can help prevent man-in-the-middle attacks. This figure describes setting a device token during transaction protection.
These steps describe the workflow: 1. The end user initiates a transaction. 2. The online system displays the transaction screen. 3. If flash is enabled on the end-user device, the data-gathering JavaScript executes as the page loads and collects the FSO (Flash shared object) data. 4. The end user enters the transaction information and clicks the submit button. 5. The online system servlet filter listens for the FSO post. 6. If JavaScript script is enabled on the end-user device, the data-gathering JavaScript collects device print information.
RSA Adaptive Authentication Integration Guide 46 Setting Device Token Information
7. The data-gathering JavaScript collects the device data, such as the IP address, browser information, device fingerprint, deviceTokenCookie, and deviceTokenFSO. 8. The online system servlet sends a query for information to the end-user device. 9. The end-user device sends transaction and device information to the online system servlet. 10. The end user clicks the submit button. 11. The online system sends the end-user credentials and device information Adaptive Authentication. 12. Adaptive Authentication returns device token data to the online system. 13. The online system sets the device cookie data. 14. The online system passes the cookie, FSO and device token data to the end-user browser. The JavaScript script sets the FSO data. 15. The user receives transaction approval.
Setting Device Token Information
Adaptive Authentication passes two types of data to be placed on the end-user device:
Set the Flash Shared Object 47 Set the Flash Shared Object
RSA provides the pmfso_set.jsp script to set the Flash shared object (FSO) on an end-user device. Note: When placing the FSO, make sure that the FSO is URL encoded. To set the FSO: 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.
Set the PMData Cookie
You must set the PMData cookie on the end-user device to set device print information. Set the received deviceToken on the end-user machine in a cookie with these properties:
Property Value
Name PMData
MaxAge 365 days
RSA Adaptive Authentication Integration Guide 47 Setting Device Token Information
Property Value
Domain Your domain name
Path “/”. This value ensures that the cookie is accessible from any URL on this server.
Secure For a production environment, this cookie must be secure
Value deviceToken
Set the Flash Shared Object Token
These steps outline how the FSO Token is set into the FSO using pmfso_set.jsp. Prerequisites 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. To set the FSO Token: 1. Detect whether Flash is installed. 2. Detect the browser type. 3. Run the Flash movie. Results In the pmfso_set.jsp file, two values in the FlashVars parameter are passed to the Flash movie and need to be set:
l PMData: The value of the deviceToken that is extracted from the session.
l browserType: The end-user 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: FlashVars='PMData=the deviceToken value &browserType=the user's browser type' If you are using a web technology other than JSP, use this code example to see how to call the movie and pass 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)
RSA Adaptive Authentication Integration Guide 48 Setting Device Token Information
{ 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; } %> <% if (isTokenValid) { %> <% Note: You must ensure that the values are securely encoded using HTML entities.
RSA Adaptive Authentication Integration Guide 51 Chapter 5: Mobile Location Awareness
Mobile Location Awareness uses detailed information about the location of the end-user mobile device to support risk-based authentication. Mobile Location Awareness enables you to identify the location from which the end user is attempting to access an account by way of a new or previously used mobile device. The collected data is entered into the Risk Engine and helps Adaptive Authentication identify potential fraudulent transactions. The RSA Adaptive Authentication Mobile SDK Modules and rsa.js script collect this data using GPS, WiFi, or cell tower triangulation:
l Longitude
l Latitude
l Horizontal accuracy
l Altitude
l Altitude accuracy
l Heading
l Speed
l Time stamp
l Status code For detailed information about the data collected by Mobile Location Awareness, see Mobile Device Structure in the Web Services Request Data Structures and Types chapter in the API Reference Guide. The collected information is formatted as a single string, and sent to Adaptive Authentication as part of the geoLocation element within the DeviceRequest. Based on the collected information and the end-user profile, Adaptive Authentication determines:
l Whether the end user is accessing an account from a location other than the usual location
l Whether the end user is accessing an account from a high-risk area
l The ground speed between two activities If more than one method is used for mobile data collection, the data is used in this order of priority: 1. Adaptive Authentication Mobile SDK Modules 2. API 3. JavaScript Note:
l You must apply the script to each page that requires Mobile Location Awareness.
l This feature is relevant for the following W3C geolocation API types: HTML5 and BlackBerry proprietary API (version 4.1 and later).
RSA Adaptive Authentication Integration Guide 52 Mobile Location Awareness Workflow
l Certain countries require explicit end-user acknowledgment and consent to collect the end- user information, such as location information, location awareness granularity, and device information. The Adaptive Authentication API for mobile browsing and Adaptive Authentication Mobile SDK Modules are intended to enable compliance with legal conditions, however RSA is not responsible for the fulfillment of all the legal requirements.
Mobile Location Awareness Workflow 53 Location Collection Parameters 54 Collect Information for Mobile Location Awareness 55 Send Collected Data 57 Mobile Location Awareness Workflow
Note: You must apply the script to each page that requires Mobile Location Awareness. This figure shows the collection of information for Mobile Location Awareness.
These steps describe the workflow: 1. The end user logs on to your online system and performs a payment-related transaction. 2. The online system displays the transaction screen. 3. If JavaScript is enabled on the end-user device browser, the server page continuously collects geolocation information. Note: The stopCollection message can be called at any time between the onLoad event and the onSubmit event.
RSA Adaptive Authentication Integration Guide 53 Location Collection Parameters
4. The end user clicks OK to submit the transaction. The server page sends the collected data to the online system. 5. The online system writes the collected geolocation data as part of the SOAP API call to Adaptive Authentication. For more information about the flow of this event within Web Services, see the API Reference Guide. 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 this table. For example, startCollection (Accuracy value, Timeout value, Relevancy value, Expiration value, aidMode value). This table includes a detailed description of these parameters.
Parameter Description Default Valid Value Range
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 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 180 90 - 300 position is received by that time, the collection of mobile location information stops.
Relevancy Threshold in seconds for the age of a relevant position. If 120 60 - 240 the age 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 48 24 - 60 location. If the location is older than this value, a location value is not returned.
RSA Adaptive Authentication Integration Guide 54 Collect Information for Mobile Location Awareness
Parameter Description Default Valid Value Range
aidMode The level of accuracy according to the type of collection 2 See mechanism used. aidMode Note: This parameter is relevant for BlackBerry Functions proprietary API (starting from version 4.1). on page 19 for a list of aidMode functions. aidMode Functions
A list of aidMode functions is shown in this table.
aidMode Description Numeric Function Value
Cellsite Uses the GPS location of the Cell Site Tower to provide first-order 0 GPS information. Note: The Cellsite mode requires network connectivity and carrier support.
Assisted Uses the network to provide short-term satellite data to the device 1 chip. 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
Prerequisites: (Optional) Define specific parameters that help configure the information collection for Mobile Location Awareness. For a list of these parameters, see Location Collection Parameters. 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. You must call this function during the onLoad event.
RSA Adaptive Authentication Integration Guide 55 Collect Information for Mobile Location Awareness
This example shows the startCollection function.
2. (Optional) If you have assigned values for the parameters, add these values to the startCollection function. 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 Location Collection Parameters. This is an example of the startCollection function with assigned values: startCollection(50,100,220,55,2)
3. During the onSubmit event, format the collected information into a single string by calling this function: var geoLocationJSON= getGeolocationStruct(); This is an example of getGeolocationStruct function: Note: If you choose to stop the collection, you can call the stopCollection() function at any time after the onLoadevent. 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.
RSA Adaptive Authentication Integration Guide 56 Send Collected Data
The string is posted to your application and passed to Adaptive Authentication as part of the SOAP request. For more information about the flow of this event within Web Services, see the API Reference Guide. This is an 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" }, ] }
Send Collected Data
To send the collected data: 1. After the device components have been collected, construct a string containing these name- value parameters in this format : cookieToken=xxxyyy&fsoToken=zzzwwww&… Note: These values should be URL encoded. 2. Send the string to Adaptive Authentication.
RSA Adaptive Authentication Integration Guide 57 Chapter 6: RDP Trojan Protection
The Trojan Protection feature is designed to protect against fraudsters who use malware with embedded VNC/RDP functionality and social engineering to perform fraudulent activity. Note: The Trojan Protection Solution is designed for websites only and does not apply to mobile applications or WAP (mobile Internet) sites.
RDP Trojan Protection Overview 58 Collecting RDP Trojan Protection Information 59 RDP Trojan Collection Parameters 62 RDP Trojan Protection Overview
A JavaScript code is implemented in the relevant application page, which collects data from the end user's device and enables passing the data to Adaptive Authentication in a SOAP request message. Note: The Trojan Protection feature is designed for PC-based devices with Microsoft Windows operating system only, and does not apply to mobile devices. RSA provides the rsa.js (JavaScript) file for collecting the information for the RDP Trojan Protection feature. RDP Trojan detection requires that the devicePrint and userLoginName be sent to Adaptive Authentication as part of a SOAP analyze request call. Collected information related to the RDP Trojan Protection feature is also sent asynchronously to Adaptive Authentication on an active website, as soon as the JavaScript script detects that an end user has logged on. 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 these data elements:
Element Description Device identifier used to match the device ID sent in the Adaptive device_id Authentication SOAP analyze request to the attacked device in the Trojan blacklist. Unique user name or logon name provided by your organization to the user_name online website user. The time that the event information was collected according to the local timestamp device system clock. url The URL of the current page the end user is visiting. active_window A Boolean value denoting whether the current window is active.
Note: You must apply the script to each HTML page that requires RDP Trojan Protection.
RSA Adaptive Authentication Integration Guide 58 Collecting RDP Trojan Protection Information
This figure shows an overview of the information collection for the RDP Trojan Protection feature.
For more information on the flow of this event within Web Services, see the API Reference Guide. Collecting RDP Trojan Protection Information
This procedure describes how to collect information for the RDP Trojan Protection feature using the rsa.js file. This script can be run only on web browsers. It cannot be run on a mobile browser. Prerequisites
l Your online system must integrate the rsa.js code in the desired application pages for collecting device fingerprint data before you can collect information for RDP Trojan Protection. See Collect the Device Print Information.
RSA Adaptive Authentication Integration Guide 59 Collecting RDP Trojan Protection Information
To Collect RDP Trojan Protection Information: 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. In the header section of the web page, place this text:
2. To begin data collection, place the function below 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. 3. Repeat steps 1 and 2 for each HTML page that requires collection for RDP Trojan Protection. The collected data is sent to Adaptive Authentication as part of an analyzeRequest message in the devicePrint and jsEvents fields in the deviceRequest structure and in the userLoginName field in the identificationData structure. Below is a sample implementation of the onSubmit event using JQuery to send the collected data during integration. … $('form').submit(function() { var jsEventStatus = '@@0,0,0,'+TimestampCollector.getStatus(); var userLoginName = getLoginName(); var devicePrint = encode_deviceprint(); $('') .attr( {type : 'hidden', name : 'jsEvent', value : jsEventStatus} ) .appendTo('form');RSA Adaptive Authentication Integration Guide 60 Collecting RDP Trojan Protection Information
$('') .attr( {type : 'hidden', name : 'userLoginName', value : userLoginName} ) .appendTo('form'); $('') .attr( {type : 'hidden', name : 'devicePrint', value : devicePrint} ) .appendTo('form'); }
4. To permit event information to be sent from the online system to the BrowserEventsAnalyzer, 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. Your web application, such as Apache and IIS, should apply a re-write rule similar to the example below, written in the Apache rule style:
b. Open your online web firewall to allow secure communication over HTTPS with Adaptive Authentication. c. Report the source IP address to Adaptive Authentication to identify that the requests are routed from a legitimate website, via your RSA representative.
RSA Adaptive Authentication Integration Guide 61 RDP Trojan Collection Parameters
RDP Trojan Collection Parameters
These parameters are collected for RDP Trojan Protection.
Parameter Description Required
loginname Callback method that returns end-user log on name. This should be Y implemented by the online website developers. Note: The callback should return an empty string if the end user did not log on.
url Relative path of the URL indicating where the online system redirects Y the collected data to Adaptive Authentication.
interval Interval in seconds that collected data is sent to the Y BrowserEventsAnalyzer. Valid values are 1, 2, 5 and 10 seconds.
RSA Adaptive Authentication Integration Guide 62