RSA Adaptive Authentication (Hosted) 11 Programmer's Guide

RSA Adaptive Authentication (Hosted) Programmer's Guide Contact Information Go to the RSA corporate web site for regional Customer Support telephone and fax numbers: www.rsa.com Trademarks RSA, the RSA Logo and EMC are either registered trademarks or trademarks of EMC Corporation in the United States and/or other countries. All other trademarks used herein are the property of their respective owners. For a list of RSA trademarks, go to www.rsa.com/legal/trademarks_list.pdf. License agreement This software and the associated documentation are proprietary and confidential to EMC, are furnished under license, and may be used and copied only in accordance with the terms of such license and with the inclusion of the copyright notice below. This software and the documentation, and any copies thereof, may not be provided or otherwise made available to any other person. No title to or ownership of the software or documentation or any intellectual property rights thereto is hereby transferred. Any unauthorized use or reproduction of this software and the documentation may be subject to civil and/or criminal liability. This software is subject to change without notice and should not be construed as a commitment by EMC. Note on encryption technologies This product may contain encryption technology. Many countries prohibit or restrict the use, import, or export of encryption technologies, and current use, import, and export regulations should be followed when using, importing or exporting this product. Distribution Use, copying, and distribution of any EMC software described in this publication requires an applicable software license.

EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice.

THE INFORMATION IN THIS PUBLICATION IS PROVIDED "AS IS." EMC CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Contents

Preface...... 7 About This Guide...... 7 RSA Adaptive Authentication (Hosted) Documentation...... 7 Support and Service ...... 8 Before You Call Customer Support...... 9

Chapter 1: Overview of RSA Adaptive Authentication...... 11 Risk Models ...... 12 Anti-Fraud Model ...... 12 Anti-Intrusion Model ...... 13 General Workflow...... 13 RSA Adaptive Authentication Decision Flow and Module Relationship ...... 14 SOAP Messages...... 15 Integration Points ...... 16 Protocols and Message Formats...... 17 SOAP API...... 17 Message Structure and Format ...... 17 Transport Protocols...... 19 Web Services URLs and Multiple Version Support ...... 20 Security ...... 21 Transport Security...... 21 Application Security ...... 21 Data Integrity ...... 22 Integration Options ...... 22 SOAP API...... 22 SOAP API with Authentication Data Stored at Organization’s Site ...... 22 SOAP API and HTML Redirection...... 23 FI-Defined Authentication Method ...... 23

Chapter 2: Initial Data Collection...... 25 Collection for Challenge Questions Authentication ...... 25 Stage I - Analyze Message...... 27 Stage II - Query...... 27 Stage III - Authentication Data Collection ...... 28 Collection for Out-of-band Phone and Out-of-band SMS Authentication ...... 30 Stage I - Analyze Message...... 31 Stage II - Collection...... 31 Stage III - Authentication Data Collection ...... 32

Chapter 3: SOAP API Use Cases ...... 33 RSA Adaptive Authentication API Message Flow...... 33

Contents 3 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Challenge Questions Authentication Use Case...... 36 Stage I - Logon Process ...... 37 Stage II - Analyze Message ...... 37 Stage III - Challenge ...... 38 Stage IV - Authenticate...... 38 Out-of-Band Phone Authentication Use Case ...... 39 Stage I - Logon Process ...... 40 Stage II - Analyze Message ...... 40 Stage III - Query ...... 41 Stage IV - Challenge...... 41 Stage V - QueryAuthStatus...... 42 Out-of-Band SMS Authentication Use Case ...... 43 Stage I - Logon Process ...... 44 Stage II - Analyze Message ...... 44 Stage III - Query ...... 45 Stage IV - Challenge...... 45 Stage V - Authenticate...... 46 Knowledge-Based Authentication Use Case ...... 47 Stage I - Logon Process ...... 49 Stage II - Analyze Message ...... 49 Stage III - Challenge ...... 49 Stage IV - Authenticate...... 50 One-Time Password Authentication Use Case ...... 51 Stage I - Logon Process ...... 52 Stage II - Analyze Message ...... 52 Stage III - Challenge ...... 53 Stage IV - Authenticate...... 53 Use Case: Authentication Passed or Failed ...... 54 General Considerations...... 54 Implementing the One-Time Password Checksum ...... 55 Remember Me Use Cases ...... 56 Remember Me in Collection Flow...... 56 Remember Me in Authentication Flow ...... 57 Remember Me in FI-Defined Authentication Flow...... 61 Remember Me in Out-of-Band Phone Authentication Flow ...... 63 Remember Me in Query Flow ...... 66 Remember Me in Unlink Flow ...... 66

Chapter 4: SOAP API with Data on Organization’s Side...... 67 Handling Authentication Credentials Stored by the Organization...... 67 Message Flow Description...... 68 Challenge Questions Authentication...... 72 Stage I - Analyze Message, Recommended Action...... 73 Stage II - Challenge ...... 73 Stage III - Authenticate...... 74

4 Contents RSA Adaptive Authentication (Hosted) Programmer’s Guide

Out-of-Band Phone Authentication ...... 75 Stage I - Analyze Message...... 76 Stage II - Query...... 76 Stage III - Challenge ...... 76 Stage IV - QueryAuthStatus ...... 77 Out-of-Band SMS Authentication ...... 78 Stage I - Logon Process ...... 79 Stage II - Analyze Message ...... 79 Stage III - Query ...... 80 Stage IV - Challenge...... 80 Stage V - Authenticate...... 81 Updating RSA Adaptive Authentication about User Credentials Status using the Notify Option...... 81

Chapter 5: SOAP API and HTML Redirection...... 83 Message Flow Description...... 83 API Components...... 85 Redirection Protocol ...... 85 Authentication - Required Messages ...... 85 Stage I - Analyze Message...... 85 Stage II - Redirection...... 91 Stage III - User Authentication...... 92 Stage IV - Redirection Back and Validation ...... 93

Chapter 6: FI-Defined Authentication Method...... 95 Messages Flow Description ...... 95 Authentication - Required Messages ...... 96

Chapter 7: Integration Option Summary...... 99 Chapter 8: International Account Formats ...... 101 Hashing the Account Number...... 102 International Bank Account Number (IBAN)...... 102 SWIFT-BIC...... 102 Conversion of Bank Account Formats for Various Countries to International Format.. 103 Sample International Account Formats...... 112 Visual Display of International Account Number Structure...... 114 Additional Resources ...... 115

Contents 5

RSA Adaptive Authentication (Hosted) Programmer’s Guide

Preface

About This Guide This document describes the Web Services offered by RSA Adaptive Authentication and the common use cases associated with each service. This guide is intended for Web Services developers, Web Services application administrators, and system administrators. It is a high level guide to the API workflows and procedures, and provides a general overview of API functionality and options. The descriptive explanations in this guide enable API programmers to begin working effectively in a very short time. This guide does not replace the detailed API Reference Guide, a comprehensive guide to all of the structures, fields, and other details required for API programming.

RSA Adaptive Authentication (Hosted) Documentation For more information about RSA Adaptive Authentication, see the following documentation: RSA Adaptive Authentication (Hosted) Release Notes. Provides information about what is new and changed in this release, as well as workarounds for known issues. The latest version of the Release Notes is available on RSA SecurCare Online at https://knowledge.rsasecurity.com. RSA Adaptive Authentication (Hosted) Product Overview Guide. Provides a high-level introduction to the product and its documentation. Setup Form. Specifies and describes the basic system configuration parameters that are required for getting started and describes optional system parameters that can be set by your organization as part of the implementation process. FI Load User’s Guide. Describes how to integrate organizations with your RSA Adaptive Authentication system. Applicable for vendors. Policy Loader User’s Guide. Describes how an organization can define any set of collection or authentication rules using the Policy Loader process. Programmer’s Guide. Describes the web services offered by RSA Adaptive Authentication (Hosted) and the common use cases associated with each service. API Reference Guide. Describes overall business workflows of RSA Adaptive Authentication (Hosted), web service methods, and data elements for each of the methods. API Mapping Guide. Describes how to map the legacy RSA API to the Adaptive Authentication (Hosted) API Release 6.5 and how to upgrade to the new API by gradually adding new API calls on top of existing API. Case Management API Developer’s Guide. Describes the functionality and capabilities of the RSA Adaptive Authentication Case Management API.

Preface 7 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Batch File Integration Guide. Describes the batch file option (a method for sending online transactions data to the RSA Risk Engine for risk evaluation) and how to integrate it into your RSA system. Back Office SSO API Guide. Describes how to integrate your organization’s existing application sets with the RSA Adaptive Authentication (Hosted) Back Office applications. Data Gathering Techniques Guide. Describes the implementation mechanisms that allow your organization’s application or web site to collect data from the user's device and pass it to the RSA system using the SOAP API Device Fingerprint Collection JavaScript code and Flash Shared Object. Raw Data Reports User’s Guide. Describes the Raw Data Reports feature including the report requirements, the content of the report, the way it should be transferred to a client, and the configuration and customization options. Back Office User’s Guide. Describes the Back Office application suite, including: • MIS Reports. Provides a summary of the available MIS reports and their use for clear, high-level visibility of the system. • Representative Administration. Describes how to perform the administration tasks required to manage Back Office users. • Case Management. Describes how to track and follow up on various online customer activities to determine whether they are genuine or fraudulent. • Policy Manager. Describes how to define, edit, and add to a set of built-in heuristic risk-management decision rules. • Customer Service. Describes how to respond to end user inquiries and guide end users.

Support and Service

RSA SecurCare Online https://knowledge.rsasecurity.com

Customer Support Information www.emc.com/support/rsa/index.htm

RSA Ready Partner Solution https://gallery.emc.com/community/marketplace/rsa Directory

RSA SecurCare Online offers a knowledgebase that contains answers to common questions and solutions to known problems. It also offers information on new releases, important technical news, and software downloads. The RSA Secured Partner Solutions Directory provides information about third-party hardware and software products that have been certified to work with RSA products. The directory includes Implementation Guides with step-by-step instructions about interoperation of RSA products with these third-party products.

8 Preface RSA Adaptive Authentication (Hosted) Programmer’s Guide

Before You Call Customer Support To log a ticket with the RSA Help Desk, please have the following information available when you call:  Your RSA Site ID/License ID:  Company Name:  Company Address:  Contact Name:  Phone Number:  E-mail Address:  RSA Product/Version:  Summary of Problem:

Preface 9

RSA Adaptive Authentication (Hosted) Programmer’s Guide

1 Overview of RSA Adaptive Authentication RSA Adaptive Authentication (Hosted) is a flexible and layered authentication solution designed to match security with transaction risk, customer need, preference, and usability. The Adaptive Authentication platform offers two distinct systems that take different authentication approaches to meet the needs of your user base: • Adaptive authentication • One-time password authentication Adaptive Authentication authenticates all users behind the scenes based on profile information such as: device identification, device forensics, network forensics, user behavior profiling, and session analysis. In addition to the data gathered locally, the risk-based module leverages the RSA eFraudNetwork, a cross-industry, cross-platform online fraud network that aggregates information about fraudulent or suspicious activity. With members from over 50 leading financial institutions, as well as credit and debit card issuers, thousands of regional banks and credit unions, and most major ISPs, the RSA eFraudNetwork helps organizations identify and halt fraudulent transactions. Users that do not pass the transparent authentication layer or are deemed “high-risk” must pass a secondary layer of authentication in the form of challenge questions, out-of-band phone authentication, out-of-band e-mail, or other methods. Organizations may work with a combination of approaches. When combining approaches, the organization prioritizes the order in which each approach is to be used. Only a small minority of the cases (approximately one percent) require stronger authentication, while the remainder (the majority) is successfully authenticated by the transparent authentication layer without affecting the user experience or ability to complete a given transaction. Since end users are not required to install or possess any additional hardware or software, the risk-based module provides organizations with strong security that builds customer confidence without compromising usability. By providing the organization site with the knowledge and tools to mitigate fraud, and by continuously learning new fraud patterns, Adaptive Authentication provides protection from current and continuously evolving security threats.

1: Overview of RSA Adaptive Authentication 11 RSA Adaptive Authentication (Hosted) Programmer’s Guide

The API for Adaptive Authentication offers organizations multiple degrees of freedom in the available integration methods and the various adaptive authentication flows. This enables the organization, together with RSA, to practically tailor the optimal authentication solution to suit the organization's needs. This document introduces Adaptive Authentication services, discusses integration options, and provides explanations of message flows and required data elements involved in each integration method.

Risk-based authentication, real-time, and transparent Extra Authentication 1% Secret Automated Custom High risk Questions Phone Call

Real-time Device Risk Recognition Assessment 99% Low risk RISK

Risk Models Adaptive Authentication uses the Anti-Fraud and Anti-Intrusion models to detect fraud or to secure the access to various systems.

Anti-Fraud Model A robust, self-learning Bayesian risk model designed to identify and protect organizations from a wide variety of threats. The risk model is powered by risk assessment and authentication technology that operates transparently and classifies all users by measuring a series of risk indicators using complex statistical modeling. The Anti-Fraud model is targeted at online banking and financial services fraud, but can also be implemented with online applications in other industries. The risk model produces a normalized risk score between 0 and 1000, where a higher score indicates a higher probability of fraud. The advantage of the normalized score is that it allows the organization to estimate the challenge rate or the case generation rate, as well as the number of calls to expect in the Customer Service center.

Note: The Anti-Fraud model is available with both Adaptive Authentication and Transaction Monitoring. It can work in conjunction with the Device Identification Assurance model, which enables the Remember Me feature. For organizations using Adaptive Authentication or Transaction Monitoring to secure online banking web site access, RSA recommends the Anti-Fraud model.

12 1: Overview of RSA Adaptive Authentication RSA Adaptive Authentication (Hosted) Programmer’s Guide

Anti-Intrusion Model A risk model mainly used by enterprise organizations to securely provide remote access to employees, customers, partners, suppliers, or vendors, to protect against intrusions, and to facilitate a very low intrusion pass-through rate. This is a predictable model that consists of two sub models: device identification and behavioral pattern analysis. Device identification identifies whether the device was used by this end user in the past. Behavioral pattern analysis detects suspicious patterns or anomalies in the end user’s behavior. A combination of both layers is also provided to facilitate even stronger protection against intrusion.

Note: The Anti-Intrusion model is only available with Adaptive Authentication. Working with the Anti-Intrusion model enables the Remember Me feature.

General Workflow The following sections describe what happens behind the scenes during typical online user interactions that involve Adaptive Authentication. The following is an overview of a typical workflow: 1. The user attempts to log on to the organization's online application or execute a transaction (for example: transfer money, reset a password, or change an address). 2. The organization performs the first layer of authentication using the current authentication process, for example, verification of a User ID and password during the logon attempt. 3. The online application sends the transaction request to Adaptive Authentication for review. 4. Adaptive Authentication performs the second level of authentication by matching the user’s device and profile. 5. The results are transferred to the RSA Risk Engine, which measures and analyzes the risk of the transaction. 6. Based on the risk score calculated by the Risk Engine, Adaptive Authentication retrieves the recommended actions, for example, accept the transaction, block the account, manually review the account, or perform additional authentication or collection. If collection or additional authentication is required, the application redirects the user’s browser to Adaptive Authentication. If the organization chooses to implement one of the API integration methods, the organization is responsible for the collection and additional authentication procedures. 7. The authentication response is fed back into Adaptive Authentication and its response is sent back to the application. 8. If the user passes authentication or if the response recommends accepting the transaction without additional authentication, the user is allowed to complete the transaction.

1: Overview of RSA Adaptive Authentication 13 RSA Adaptive Authentication (Hosted) Programmer’s Guide

The following figure shows the Adaptive Authentication flows and emphasizes the modules that are responsible for each step. Though it is not explicitly depicted in the figure, Adaptive Authentication offers fallback authentication, which can be used if the primary authentication approach is not successful.

RSA Adaptive Authentication Decision Flow and Module Relationship All decision steps are made by the framework. Each color indicates a module that is called upon to supply the data, as defined in the modules legend.

User submits logon/transaction form to organization's site

Registered to No Adaptive Yes Authentication

Safe to High Risk? Collect?

Yes Yes

User Previous Data Yes Suspended? Exists? No

Suspension No No Screen

Authentication No: Increase Attempted Yes: Fill Suspension Counter Authentication Tentative Data Collection

Passed Authentication

Configured interaction with the Yes organization’s site

Modules Legend

Framework

Risk

Authentication

14 1: Overview of RSA Adaptive Authentication RSA Adaptive Authentication (Hosted) Programmer’s Guide

SOAP Messages The Adaptive Authentication Web Services API includes several types of SOAP messages. The following partial list of SOAP message types focuses on a subset of the SOAP messages used in the authentication process. These messages are generic and can be used for the multi-credential framework: Analyze messages. Used when the organization assesses the risk of a specific online operation requested by a user. Based on the data in the Analyze request, the Risk Engine outputs a risk score and Adaptive Authentication sends a response back to the organization with the score, status, and recommended action. Depending on the level of risk associated with the user’s request, the organization decides whether to allow the operation or redirect the request for further authentication. Analyze messages work in request-response pairs and can be either synchronous or asynchronous. Synchronous Analyze messages. Used when the organization waits in real time for a response from the Risk Engine and based on the Adaptive Authentication response, decides on the subsequent action. Asynchronous Analyze messages. Used when the organization wants to send a message to the Adaptive Authentication application but does not need to wait for a response from the Risk Engine. The organization’s subsequent actions are not dependent upon the risk score. AnalyzeIdentity messages. Used when the organization wishes to assess the risk of an online new account opening or enrollment requested by a user. Based on the data in the analyzeIdentity request and the predefined organization’s policies, the Risk Engine outputs a risk score and Adaptive Authentication sends a response back to the organization with the score and recommended action. Depending on the level of risk associated with the user's request, the organization decides whether to allow the operation or redirect the request for further authentication. AnalyzeIdentity messages work in request-response pairs and are synchronous. Notify messages. Asynchronous messages used by the organization when an immediate response is not required but the operation performed can still provide the Risk Engine with information for additional profiling to further improve risk assessment. Query messages. Used when requesting information for subsequent use. During pre authentication, Query messages are used to obtain information that may be required before starting the authentication process. For example, for out-of-band phone authentication, in which the user enters a one-time password (OTP) through the phone, the organization can use the Query method to retrieve the user’s phone numbers and present the user with a page prompting the selection of a phone number to use for the out-of-band phone call. For challenge questions authentication, the Query method can be used to retrieve random questions for use in the challenge questions collection procedure. Query messages work in request-response pairs. updateUser messages. Used by the organization to send the data collected from the user during collection to store in the Adaptive Authentication application. Adaptive Authentication returns an updateUser response including a status indicating the result of the collection data storage.

1: Overview of RSA Adaptive Authentication 15 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Challenge messages. Used to challenge the user. For challenge questions authentication, Challenge messages instruct the Adaptive Authentication system to retrieve the user’s challenge questions. For out-of-band phone authentication, Challenge messages are used to initialize a phone call and display an OTP to the user. Challenge messages work in request-response pairs. Authenticate messages. Complete the authentication by verifying user data and input. For example, in the case of Challenge Questions, authenticate messages instruct Adaptive Authentication to verify and authenticate user questions. Authenticate messages work in request risk based authentication-response pairs. QueryAuthStatus messages. Pull the status of an asynchronous authentication process. The calling application typically makes the QueryAuthStatus call repeatedly, every X seconds, until the authentication status is received. This method is used by the out-of-band phone authentication method. The API can be called at multiple points within the online application, for example, at logon, during new payee or new external account setup, whenever a deposit or a payment is made, and so on.

Integration Points The Adaptive Authentication flow is inserted between two points or pages in the online application. On the first page, the user must enter sensitive account information to proceed with a certain action. The organization then sends a message containing the user or event details to Adaptive Authentication for risk assessment and to receive the recommended action. On the second page, which depends on the Adaptive Authentication risk assessment outcome, the user is granted acceptance or denial for the requested action. Without the Adaptive Authentication module, the user is transported from the first page to the next with only a limited level of authentication, which is a potential scenario if a fraudster is behind the scene. The following are examples of such pages: • An online application logon page (first page) and the online application main page (second page). • Transaction details verification page (first page) and a transaction details confirmation page (second page). When the code has been implemented according to the guidelines in this document, the first page is referred to as an initiation page and the second page is referred to as a guarded page: Initiation page. The web page from where the Adaptive Authentication transaction flow is initiated. The page contains the relevant sensitive information for the pending activity which is to be protected. This information may include logon name and password, money transfer sums, account details, and so on. Guarded page. The web page where the user is granted access or denial to the protected resource, or the page which is displayed after the actual protected activity has taken place.

16 1: Overview of RSA Adaptive Authentication RSA Adaptive Authentication (Hosted) Programmer’s Guide

Protocols and Message Formats

SOAP API Integration with Adaptive Authentication requires SOAP-compatible messages for accessing Adaptive Authentication Web Services. The SOAP messages are sent in document style, literal wire format. The reason for this format is that the document and literal combination produces much smaller and more readable SOAP messages, which do not include any data type references. As the WSDL definition is made available to the clients at the implementation stage, it is not necessary to include any type references within the messages themselves. However, this means that any schema changes must be conveyed to the clients beforehand, as clients may be required to change their implementation in order to support the changes.

Note: Any version of Adaptive Authentication simultaneously supports the API of previous recently released versions. This means that client code does not need to be automatically updated with each new Adaptive Authentication version, only when clients want to take advantage of new features in the later versions that were not available in earlier versions. To work with current API, you must implement the corresponding WSDL file.

Message Structure and Format

Note: All fields in the API are case sensitive.

Most system messages work in request-response pairs, as follows: • Request format: – Each request includes a messageHeader, securityHeader, configurationHeader, and identificationData. – Multi-organization vendors must send the identificationData.orgName field to correctly identify the organization to which the information in the SOAP message applies. • Response format: – Each response includes a messageHeader and statusHeader. – The Analyze Redirect responses may also contain one optional serverRedirectData element if redirection is required.

1: Overview of RSA Adaptive Authentication 17 RSA Adaptive Authentication (Hosted) Programmer’s Guide

All messages include identification elements in a header area, as well as information in the data element fields, as follows: • Headers: – messageHeader. General message information such as message type, interface version, and time stamp. – securityHeader. ID and credentials for authentication of the caller sending the request. This is not the end user’s ID and password, but rather the master User ID and password that are assigned to the organization’s system for calling Adaptive Authentication. All fields in the securityHeader are mandatory. – configurationHeader. Includes the instanceId field which is mandatory. This is also used when working with different Adaptive Authentication rule sets. – statusHeader. Message status, either 200 (OK) or error information. • Data Elements: – identificationData. Identify a user in the online application. This includes routing information used by Adaptive Authentication to route the message to different organizations within a shared processor region. – userData. Provide information about the online application user such as account information and address. – deviceRequest. Provide any information the server discovers about a user device such as IP address or cookie values. –eventData. Describe a single event occurring in the online application. For example, session signin (logon), adding a new payee, making a payment or a deposit, changing a password, and changing an address. A single XML message can contain multiple eventData elements. For example, when a user asks to make several payments in a single form, this request generates several eventData elements. All eventData elements are contained in a single eventDataList element. – riskResult. Encapsulates the result of an Adaptive Authentication risk assessment. – clientReturnData. Used by the Adaptive Authentication server to redirect the user’s browser back to the online application site after the Adaptive Authentication flow. This is used in the Analyze request (HTML redirection API). – serverRedirectData. Required by the organization to redirect the user’s browser to the Adaptive Authentication flow. This is used in the Analyze response (HTML Redirection API).

18 1: Overview of RSA Adaptive Authentication RSA Adaptive Authentication (Hosted) Programmer’s Guide

Transport Protocols

HTTP HTTP(S) is the default transport protocol for SOAP versions of the protocol: • SOAP API uses the standard SOAP-HTTP binding. • SOAP API requires the use of the following SOAPAction headers: – analyzeIdentity messages: SOAPAction: “rsa:analyzeIdentity:AnalyzeIdentity_6_5” – Notification messages: SOAPAction: “rsa:async:Notify_6_5” – Analyze messages: SOAPAction: “rsa:analyze:Analyze_6_5” – Asynchronous Analyze messages - SOAPAction: “rsa:async:Analyze_6_5” – Query messages: SOAPAction: “rsa:query:Query_6_5” All other message types also work with equivalent SOAPAction strings.

Persistent Connections over Raw SSL When using HTTP(S), a separate TCP connection is established per request, thereby increasing the load on HTTP servers. In interfaces such as this one, where the client is expected to make multiple requests to the same server within a short amount of time, RSA recommends using persistent connections, due to the following advantages: • Network congestion is reduced by decreasing the number of packets required by TCP opens and SSL handshakes, and by allowing TCP sufficient time to determine the congestion state of the network. • By opening and closing fewer TCP connections, CPU time is saved in routers and hosts (clients, servers, proxies, gateways, tunnels, or caches), and memory used in hosts for TCP protocol control blocks can be saved. If persistent connections are used, they are on top of raw SSL and not HTTP(S). The transport protocol in this case is defined by RSA.

1: Overview of RSA Adaptive Authentication 19 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Web Services URLs and Multiple Version Support RSA consistently supports all recently released protocol versions by using separate Web Services on different URLs for different versions of the protocol. Clients are able to upgrade to a new version at their convenience. New features such as Remember Me, Cookie Anti Theft, and additional channel protection are only available in the new Adaptive Authentication API versions. For greater flexibility and the convenience of clients working with earlier versions, Adaptive Authentication allows a mix and match of old and current API features when working in SOAP_API mode, as follows: • A combination of calls through both the old and current APIs. Features of the older API, for example, risk analysis and authentication types, can be accessed through older API calls, while features of the current API, for example, adding knowledgebase questions, can only be accessed through calls to the new API. • Risk analysis through one API and authentication through another API. • Risk analysis for some events using the old calls and for other events using the new calls. Other mix and match combinations and permutations are not supported, including mixing old and new calls for the same flow or feature. Organizations can choose between two access modes: Web Redirect and Direct SOAP. However, to enjoy the full functionality of the current API, you must work with Direct SOAP. Web Services for the API version 6.5 are published on the following URLs: • http:///AdaptiveAuthentication_6_5/AdaptiveAuthentication • http:///AdaptiveAuthentication_6_5/AsyncAdaptiveAuthentication where is the domain used to host Adaptive Authentication. In the earlier API versions, there was a separate URL for each message type. The following table lists the URL per SOAP request type.

Protocol Request Type URL

SOAP Risk https:///rsa_rba_5_ GetActualAction 8/RiskEngine

SOAP Notify https:///rsa_rba_5_ Risk (Asynchronous) 8/AsyncEngine

SOAP GetRandomQuestions https:///rsa_rba_5_ GetAllUserQuestions 8/CollectChallenge SetQuestions AddQuestions

20 1: Overview of RSA Adaptive Authentication RSA Adaptive Authentication (Hosted) Programmer’s Guide

Protocol Request Type URL

SOAP SelectAuthQuestions https:///rsa_rba_5_ MatchAuthAnswers 8/AuthenticateChallenge

SOAP SetPhoneNumbers https:///rsa_rba_5_ GetPhoneNumbers 8/CollectPhoneOOB

SOAP InitPhoneAuth https:///rsa_rba_5_ GetPhoneAuthStatus 8/AuthenticatePhoneOOB

Note: Organizations that started using RSA Adaptive Authentication (Hosted) from version 8.8 or later, and want to use the Notify request, must use the following Web Services: • For synchronous calls, use AdaptiveAuthentication. • For asynchronous calls, use AsyncAdaptiveAuthentication.

Security

Transport Security RSA supports a combination of the following security measures at the physical channel layer: • SSL 128-bit encryption (server-side certificates) • IP restrictions at the firewall level • Leased line (optional) • Firewall to firewall VPN (optional)

Application Security The messages must be secured using caller ID and password for caller identification. The requests sent from the organization to the Risk Engine use password message security.

Note: By default, RSA supports SSL 128-bit encryption with server-side certificate, IP restrictions, and security ID and password within the messages.

1: Overview of RSA Adaptive Authentication 21 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Data Integrity There are two ways to pass information between the online application and the Adaptive Authentication application: • Calling Web Services through a secure SSL channel • Passing data through the user’s browser during redirection The channel is secure because it uses IP restrictions, SSL 128-bit encryption with server-side certificates, and caller ID and passwords on the client side. The redirection data that flows through this channel signs the data using a SHA1-HMAC algorithm, as defined in RFC 2104: “HMAC: Keyed-Hashing for Message Authentication” (February 1997).

Integration Options Adaptive Authentication offers organizations multiple degrees of freedom in the available integration methods and types of Adaptive Authentication flows. This enables the organization, together with RSA, to tailor the optimal authentication solution that best suits the organization’s specific needs. Adaptive Authentication can be integrated into the organization’s online application using any of the options described in the following sections. For more information, see “Integration Option Summary,”on page99.

SOAP API • Organization sends SOAP messages for risk assessment. • Organization sends SOAP messages for storage and retrieval of authentication-related data. • Authentication-related data is stored on the Adaptive Authentication side. • Organization is responsible for the user interface (UI) and screens. The organization’s online application collects authentication data, which is stored on the Adaptive Authentication side. The organization asks Adaptive Authentication to assess the risk of logons or transactions. If the user activity is found to be risky, the organization launches the strong authentication itself. The organization’s web application requests data using SOAP calls to Adaptive Authentication and renders the web pages.

SOAP API with Authentication Data Stored at Organization’s Site • Organization sends SOAP messages for risk assessment. • Organization sends SOAP messages for storage and retrieval of authentication-related data. • Authentication-related data is stored on the organization’s database. • Organization is responsible for UI and screens.

22 1: Overview of RSA Adaptive Authentication RSA Adaptive Authentication (Hosted) Programmer’s Guide

The organization’s web application collects authentication data, which is stored in the organization’s database. The organization asks Adaptive Authentication to assess the risk of logons or transactions. If the user activity is found to be risky, the organization launches the strong authentication itself. The organization’s web application requests data using SOAP calls to Adaptive Authentication, and the organization’s web application renders the web pages.

Note: Organizations storing the data in their database must notify RSA about the collection events. This step is mandatory for organizations using the Anti-Intrusion model or Anti-Fraud model with Device Identification Assurance enabled.

SOAP API and HTML Redirection • Organization sends SOAP messages for risk assessment. • Adaptive Authentication handles redirection and web page user interface. The organization’s web application redirects the user to Adaptive Authentication to collect authentication data and authenticate the user at a later stage for high risk logons or transactions. Adaptive Authentication handles both the logic and web page user interface during collection and authentication processes.

Note: HTML redirection is supported only for challenge questions and out-of-band (OOB) phone authentication. For knowledge-based authentication (KBA), this option is not supported. Working with HTML Redirection may lead to problems if the organization chooses knowledge-based authentication as an authentication method and also uses WEB-REDIRECT in requests.

FI-Defined Authentication Method Organization sends SOAP messages for risk assessment. The organization’s application collects authentication data, which is then stored in the organization’s database. The organization asks Adaptive Authentication to assess the risk of logons or transactions. If the user activity is found to be risky, the organization launches the strong authentication itself using its own methods. The organization then informs Adaptive Authentication if authentication has succeeded.

Note: Organizations can also combine their own internal authentication methods with existing Adaptive Authentication methods.

1: Overview of RSA Adaptive Authentication 23

RSA Adaptive Authentication (Hosted) Programmer’s Guide

2 Initial Data Collection Before data can be used for authentication, data must first be collected from users. The examples provided in this chapter apply to the collection of challenge questions and answers, and phone numbers for out-of-band (OOB) phone and SMS authentication, using the direct SOAP API.

Collection for Challenge Questions Authentication The following figure shows the message flow during the collection procedure for the challenge questions and answers. Each stage involved in this procedure is described in the sections that follow. The step numbers in the figure match the step numbers used in the following sections. The collection procedure proceeds only when the transaction has been verified as non risky and when authentication data is required for this user, that is, when a Policy Manager rule has been triggered recommending a collection action.

2: Initial Data Collection 25 RSA Adaptive Authentication (Hosted) Programmer’s Guide

User Browser Adaptive Organization Authentication

Org sends Analyze request with apiType =DIRECT _SOAP _API identificationData .userName User logs on - submits Logon Process eventType Stage I: Risk User ID and password assessment and 1 authentication decision

2 Adaptive Authentication returns Analyze response with transactionId and riskResult .triggeredRule . actionCode

Initiate collection process (optional, depends on risk) 5 Org sends Query request identified by either userName or transactionId , Stage II: 3 together with groupCount Providing data for and questionCount organization’s collection process

5 Adaptive Authentication 4 Displays groups of returns Query response question lists with a questionGroup

Organization sends User selects questions, Present question updateUser request, submits answers selection identified by either userName or 7 transactionId together 6 with the Stage III: challengeQuestionList Select question for this user

26 2: Initial Data Collection RSA Adaptive Authentication (Hosted) Programmer’s Guide

Stage I - Analyze Message The first stage of the collection procedure for the challenge questions and answers involves the following steps: 1. The organization extracts the relevant data for the RSA Risk Engine from the initiation page where the transaction details are entered and submitted. The organization then composes a Web Services Analyze request that includes the common headers and data elements described in “Message Structure and Format” on page 17. The required headers and data elements for this request include: • identificationData.userName • messageHeader.apiType = DIRECT_SOAP_API • eventData.eventType • identificationData.UserLoginName 2. The information in the Analyze request is processed by the Risk Engine. Adaptive Authentication returns an Analyze response with the following important fields: • riskResult.triggeredRule.actionCode. Contains the action code for the transaction as defined by the Risk Engine and the organization’s policy rules. If the value of this field is either REDIRECT_CHALLENGE or REDIRECT_COLLECT, the organization must take action. This section describes collection; for authentication see “Challenge Questions Authentication Use Case” on page 36. • serverRedirectData.transactionId or identificationData.transactionId. The unique transaction ID. In all collection type calls to Adaptive Authentication, you must send either transactionId or userName (the transactionId is recommended for improved collection report accuracy). In authentication calls to Adaptive Authentication, transactionId is always preferable and usually required.

Note: The structure depends on the work mode; HTML Redirection API uses serverRedirectData and SOAP API uses identificationData.

Stage II - Query The second stage of the collection procedure for the challenge questions and answers involves the following steps: 3. If the actionCode field is REDIRECT_COLLECT, the organization sends a Query request to Adaptive Authentication with the following fields: • identificationData.userName or identificationData.transactionId • challengeQuestionConfig.groupCount. Number of question groups. • challengeQuestionConfig.questionCount. Number of questions in each group. • challengeQuestionActionType.BROWSE_QUESTION

2: Initial Data Collection 27 RSA Adaptive Authentication (Hosted) Programmer’s Guide

4. Adaptive Authentication returns a Query response to the organization with the questionGroup element. This is a list of one or more question groups, where a question group represents one group of questions from which the user must select one question. For example, the Query response may include three groups of questions, where each group includes ten questions. 5. The organization renders the user interface (UI) pages based on the question ID, question lists, and question texts received from Adaptive Authentication. 6. The user completes the data collection procedure by selecting the challenge questions, providing and confirming answers, and so on. The organization controls the exact details of the collection procedure and the UI.

Stage III - Authentication Data Collection The third stage of the collection procedure for the challenge questions and answers involves the following step: 7. The organization sends an updateUser request to Adaptive Authentication once the user has finished interacting with the organization’s web application for data collection and has submitted the final form to the organization. The updateUser request includes the following fields: • identificationData.userName or identificationData.transactionId • challengeQuestionList. Composed of one or more challengeQuestion structures, where each one holds the data about a single question.

28 2: Initial Data Collection RSA Adaptive Authentication (Hosted) Programmer’s Guide

For SOAP API with Data on Organization’s Side, the actual answers are stored in the organization’s database and “dummy” answers are stored in Adaptive Authentication, as illustrated in the following figure.

Adaptive User Browser Organization Authentication

Org sends Analyze request with apiType =DIRECT _SOAP_API identificationData .userName Stage 1: Risk User logs on - submits Logon Process assessment and User ID and password authentication 1 decision

Adaptive Authentication returns Analyze response with transactionId and riskResult .triggeredRule . actionCode

Initiate collection process (optional, depends on risk) 5 Organization sends Query request identified by either userName or Stage II : together 3 transactionId , Providing data for with groupCount and organization questionCount collection process

Adaptive Authentication Displays groups of 4 returns Query response question lists with a questionGroup

5 Present question User selects questions, selection User answers submits answers saved at Stage III : organization Select question for 6 this user

Organization sends updateUser 7 request, identified by either userName or transactionId

2: Initial Data Collection 29 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Collection for Out-of-band Phone and Out-of-band SMS Authentication The following figure shows the message flow during the collection procedure for out-of-band phone and out-of-band SMS authentication. Each stage involved in this procedure is described in the sections that follow. The step numbers in the figure match the step numbers used in the following sections. The collection procedure proceeds only when the transaction has been verified as non risky and when authentication data is required for this user, that is, when a Policy Manager rule has been triggered recommending a collection action.

User Browser Adaptive Organization Authentication

1. Organization sends Analyze request with apiType =DIRECT _SOAP _API identificationData .userName User logs on - submits Logon Process eventType Stage I: Risk User ID and password assessment and authentication decision

2. Adaptive Authentication returns Analyze response with transactionId and riskResult .triggeredRule .actionCode 3. Organization requests telephone numbers from end user Initiate collection process (optional, 4. End user provides depends on risk) telephone numbers 5

5. Organization sends updateUser Stage II: request, with the updateOOB .userID Adaptive and phoneInfo structure. Authentication receives telephone 6. Adaptive Authentication returns numbers for from the updateUser response with the status code. organization for the authentication process

30 2: Initial Data Collection RSA Adaptive Authentication (Hosted) Programmer’s Guide

Stage I - Analyze Message The first stage of the collection procedure for out-of-band phone and out-of-band SMS authentication involves the following steps: 1. The organization extracts the relevant data for the RSA Risk Engine from the initiation page where the transaction details are entered and submitted. The organization then composes a Web Services Analyze request that includes the common headers and data elements described in “Message Structure and Format” on page 17. The required headers and data elements for this request include: • identificationData.userName • messageHeader.apiType = DIRECT_SOAP_API • eventData.eventType • identificationData.UserLoginName 2. The information in the Analyze request is processed by the Risk Engine. Adaptive Authentication returns an Analyze response with the following important fields: • riskResult.triggeredRule.actionCode. Contains the action code for the transaction as defined by the Risk Engine and the organization’s policy rules. If the value of this field is either REDIRECT_CHALLENGE or REDIRECT_COLLECT, the organization must take action. This section describes collection; for authentication see “Out-of-Band Phone Authentication Use Case” on page 39 and “Out-of-Band SMS Authentication Use Case”on page 43. • serverRedirectData.transactionId or identificationData.transactionId. The unique transaction ID. In all collection type calls to Adaptive Authentication, you must send either transactionId or userName (the transactionId is recommended for improved collection report accuracy). In authentication calls to Adaptive Authentication, transactionId is always preferable and usually required.

Note: The structure depends on the work mode; HTML Redirection API uses serverRedirectData and SOAP API uses identificationData.

Stage II - Collection The second stage of the collection procedure for out-of-band phone and out-of-band SMS authentication involves the following steps: 3. If the actionCode field is REDIRECT_COLLECT, the organization requests phone numbers for out-of-band phone and out-of-band SMS authentication from the end user. 4. The end user provides the telephone numbers to the organization.

2: Initial Data Collection 31 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Stage III - Authentication Data Collection The third stage of the collection procedure for out-of-band phone and out-of-band SMS authentication involves the following steps: 5. The organization sends an updateUser request to Adaptive Authentication once the user has provided the telephone numbers including the following fields: • updateOOB.userId • phoneInfo

Note: In order to mark SMS-enabled phone numbers for out-of-band SMS authentication, the availableForSMS attribute must be set to True.

6. Adaptive Authentication returns an updateUser response with the status code of the request.

32 2: Initial Data Collection RSA Adaptive Authentication (Hosted) Programmer’s Guide

3 SOAP API Use Cases This chapter discusses the SOAP API Integration option use cases. Each use case contains a general description of the work flow and detailed descriptions of the messages and data elements required. For sample SOAP messages, see the API Reference Guide.

RSA Adaptive Authentication API Message Flow The following figure is an example of a message flow in an RSA Adaptive Authentication use case. Other possible use-case flows are described in subsequent sections, where detail is provided on the actual messages and data elements involved in the SOAP calls and responses to and from Adaptive Authentication.

Note: All SOAP requests contain the Message and Security headers (for processors: identificationData.orgName). All responses contain the Status Header. The administrative elements, for example, mandatory headers, are not specified in the following sections on required data elements.

3: SOAP API Use Cases 33 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Start

User logs on or initiates a transaction on organization’s web application

Organization’s web application sends an Analyze request to Adaptive Authentication for risk assessment

Adaptive Authentication returns an Analyze response with risk score and recommended action

Is secondary authentication required?

YES

Organization sends a Challenge request to Adaptive Authentication to get the authentication data

NO Adaptive Authentication returns a Challenge response with authentication data

Organization prompts the user for secondary authentication

User submits the secondary credentials

Organization sends Authenticate request to Adaptive Authentication to verify secondary credentials

Adaptive Authentication verifies the user credentials and returns Authenticate response to the organization

Are the user Organization denies access to the Organization allows the user to NO authentication answers YES required page or service access the required page or service correct?

Stop

34 3: SOAP API Use Cases RSA Adaptive Authentication (Hosted) Programmer’s Guide

The flow includes the following steps: 1. Organization sends an Analyze request. The online service application server (organization) sends an Analyze request to Adaptive Authentication. The organization usually sends the Analyze request when the user requests access to a specific page or service. 2. Adaptive Authentication returns an Analyze response including risk score. The Adaptive Authentication Web Services authenticates the device and behavior and completes a risk assessment, sending an initial response that includes a recommendation regarding further authentication of the client (based on the initial risk assessment and organization-defined thresholds). 3. Organization sends a Challenge request (if required). If the application server continues with further authentication, the organization sends a SOAP request to get the authentication data (such as challenge questions with which to challenge the user). 4. Adaptive Authentication returns a Challenge response with authentication data. Adaptive Authentication sends the organization the requested authentication data. For example, the authentication data can be several challenge questions that the user previously selected and answered during an authentication data collection procedure. This data is stored in Adaptive Authentication. 5. Organization sends user an additional authentication page. The organization handles all interactions with the user and collects the user answers. To do this, the organization prompts the user with interface screens using the stored authentication data from Adaptive Authentication and handles any other required action. For example, the organization sends a page with challenge questions received in the Challenge response. Alternatively, the organization can choose to work with out-of-band phone authentication. 6. User authentication is performed. The user responds to the authentication questions, for example, answers the challenge questions. 7. Organization sends an Authenticate request to verify user answers. The organization sends the user answers to Adaptive Authentication for verification. 8. Adaptive Authentication returns an Authenticate response. The Adaptive Authentication checks the user authentication answers and returns an Authenticate response back to the organization. If the verification is successful, the application server allows the user to access the required page or service.

Note: The flow is different for out-of-band phone authentication. For more information, see “Out-of-Band Phone Authentication Use Case” on page 39.

3: SOAP API Use Cases 35 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Challenge Questions Authentication Use Case The following figure shows the message flow during the challenge questions authentication procedure. Each stage involved is described in the sections that follow.

Adaptive User Browser Organization Authentication

1. Request logon/initiate transaction 5. Organization sends Analyze request 2. Display logon/transaction form with apiType =DIRECT _SOAP_API Stage II: Risk and assessment and 3. Gather device data (IP address, Stage I: Logon identificationData .userName authentication browser information, fingerprint, Process decision deviceTokenCookie, deviceTokenFSO) 6. Adaptive Authentication 4. Submit form details and device data returns Analyze response with riskResult .triggeredRule .actionCode identificationData .trans actionId , identifying the credentialType Initiate as QUESTION Challenge Process (optional, 7. Organization sends Challenge depends on risk) request with identificationData . Stage III: transactionId and Providing data credentialChallengeReques for organization tList . authentication challengeQuestionChalleng 9. Displays the challenge questions form eRequest . process, including numberOfQuestions action code and question list 8. Adaptive Authentication returns Challenge response with Challenge User 10. User responds to authentication request credentialChallengeList

11. Organization sends Authenticate request for this transactionId with credentialDataList . challengeQuestionData , Based on result code, including user responses for user is forwarded to verification Stage IV: Match organization’s online Answers Welcome page Act upon result code 12. Adaptive Authentication returns Authenticate response with authentication status Welcome Page User logged on to organization’s Welcome page

36 3: SOAP API Use Cases RSA Adaptive Authentication (Hosted) Programmer’s Guide

Stage II - Analyze Message The second stage of the challenge questions authentication message flow involves the following steps: 5. The organization extracts the relevant data for the RSA Risk Engine from the initiation page where the transaction details are entered and submitted. The organization then composes a Web Services Analyze request that includes the common headers and data elements described in “Message Structure and Format” on page 17. The required headers and data elements for this request include: • identificationData.userName • messageHeader.apiType = DIRECT_SOAP_API • eventDataList.eventData.eventType 6. The information in the Analyze request is processed by the Risk Engine. Adaptive Authentication returns an Analyze response with the following fields: • riskResult.triggeredRule.actionCode. Contains the action code for the transaction as defined by the Risk Engine and the organization’s policy rules. If the value of this field is either REDIRECT_CHALLENGE or REDIRECT_COLLECT, the organization must take action. This section describes authentication. For more information on collection see Chapter 2, “Initial Data Collection.” • identificationData.transactionId. The unique transaction ID that must be used for all subsequent calls to Adaptive Authentication. • collectableCredentialList. collectableCredential.credentialType = QUESTION

3: SOAP API Use Cases 37 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Stage III - Challenge The third stage of the challenge questions authentication message flow involves the following steps: 7. If the actionCode field is REDIRECT_CHALLENGE and credentialType=QUESTION, the organization sends a Challenge request to Adaptive Authentication with the following fields: • identificationData.transactionId • credentialChallengeRequestList.challengeQuestionChallengeRequest.numberOf Question. The number of questions. 8. Adaptive Authentication returns a Challenge response to the organization with the following fields: • credentialChallengeList. For challenge questions, the challengeQuestionChallenge field under credentialChallengeList contains the payload for challenge question credentials. This is a list of one or more questions, which are defined by question data structures that each hold the data for a single question, including the questionId and corresponding questionText. These questions are used for authentication. 9. The organization renders the UI pages based on the information received from Adaptive Authentication. 10. The authentication procedure and the UI are controlled by the organization. The organization presents the selected questions to the user and the user answers the security questions. This completes the user intervention.

Stage IV - Authenticate The fourth stage of the challenge questions authentication message flow involves the following steps: 11. The organization sends Adaptive Authentication an Authenticate request with the following fields: • identificationData.transactionId • credentialDataList.challengeQuestionData. Contains a list of one or more question data structures that contain data on a single question, including question IDs and the corresponding answers that the user entered in the authentication form. 12. Adaptive Authentication validates the user’s answers by checking them against that user’s stored questions and answers in the database. Adaptive Authentication returns an Authenticate response to the organization with the status. The organization uses the status to determine whether to allow the user to continue performing operations in the organization’s site.

38 3: SOAP API Use Cases RSA Adaptive Authentication (Hosted) Programmer’s Guide

Out-of-Band Phone Authentication Use Case The following figure shows the message flow during the out-of-band phone authentication procedure. Each stage is described in the sections that follow.

Note: The figure does not include the first stage (logon stage) described in the flow.

Risk-Based User Browser Organization Authentication

Organization sends Analyze request apiType =DIRECT _SOAP _API, eventType , and userName User logs on - submits Stage I: Risk User ID and password assessment and Logon Process 1 authentication decision

Adaptive Authentication returns Analyze response with 2 riskResult .triggeredRule . Get Preliminary actionCode Authentication and transactionId , Data identifying the credentialType as (optional, OOBPHONE depends on risk)

Organization sends Query Stage II: Providing request identified by data for transactionId organization or userName authentication process 3 Adaptive Authentication returns Query response with 4 Org displays phone contactList number selection form

5 Phone Selection Org sends Challenge request with User selects phone number Stage III: Phone Authentify transactionId or Authentication and other userName Initiation 6 event and phone data

Render confirmation 7 code HTML Send complete phone Adaptive Authentication call data, including 9 returns Challenge response 8 eventData , with confirmation code instanceId , Enter identificationData , Confirmation eventType Code Page Phone call User’s Refresh Phone 10 every 5 Organization sends seconds QueryAuthStatus with transacationId 11

Responds with status = 12 Stage IV: Phone PENDING Authentication and Validation

13 Confirmation code validated User enters confirmation code 14

Authentication - success Organization sends QueryAuthStatus with transactionId status=SUCCESS 15 Present Welcome page

3: SOAP API Use Cases 39 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Stage II - Analyze Message The second stage of the out-of-band phone authentication message flow involves the following steps: 5. The organization extracts the relevant data for the Risk Engine from the initiation page where the transaction details are entered and submitted. The organization then composes a Web Services Analyze request that includes the common headers and data elements described in “Message Structure and Format” on page 17. The required headers and data elements for this request include the following fields: • identificationData.userName • messageHeader.apiType = DIRECT_SOAP_API • eventDataList.eventData.eventType 6. The information in the Analyze request is processed by the Risk Engine. Adaptive Authentication returns an Analyze response with the following fields: • riskResult.triggeredRule.actionCode. Contains the action code for the transaction as defined by the Risk Engine and the organization’s policy rules. The action code must be stored in the session so that the guarded page (the page that contains sensitive information and requires authentication to access) can act accordingly. If the value of this field is either REDIRECT_CHALLENGE or REDIRECT_COLLECT, the organization must take action. This section describes authentication. For more information on collection see Chapter 2, “Initial Data Collection.” • identificationData.transactionId. The unique transaction ID that must be used in all subsequent calls to Adaptive Authentication. • collectableCredentialList. collectableCredential.credentialType = OOBPHONE

40 3: SOAP API Use Cases RSA Adaptive Authentication (Hosted) Programmer’s Guide

Stage III - Query The third stage of the out-of-band phone authentication message flow involves the following steps: 7. If the actionCode field is REDIRECT_CHALLENGE and credentialType=OOBPHONE, the organization sends a Challenge request to Adaptive Authentication with the identificationData.userName or identificationData.transactionId fields. 8. Adaptive Authentication returns a Query response to the organization with the contactList. This is a list of telephone numbers defined by one or more telephone structures that contain the data about the phone number (including label, phoneNumber, and other data). 9. The organization uses the phone numbers from the Query response and renders the UI page that prompts the user to select a phone number for out-of-band phone authentication. 10. The user selects a phone number to use for out-of-band phone authentication and submits the form to the organization.

Stage IV - Challenge The fourth stage of the out-of-band phone authentication message flow involves the following steps: 11. The organization sends a Challenge request to Adaptive Authentication with the following fields: • identificationData.transactionId. Alternatively, you may send the eventData structure in conjunction with userName instead of the transactionId. The eventData structure includes enough event information for the Authentify service to be able to communicate the event details during phone authentication (eventType, amount, account, and so on). If the eventData structure is used, the Challenge response returns a transactionId, which must be used in subsequent QueryAuthStatus messages when polling for phone authentication status. • credentialChallengeRequest.oobPhoneChallengeRequest. Contains the stored phone number information.

Note: RSA recommends that the organization send an identifier of this phone number and not the full phone number. This is to eliminate a scenario where the request containing the number is manipulated and the selected phone number is changed to a different number for malicious purposes.

• identificationData.userName •eventData. The structure that contains the event information. 12. Authentication sends the Authentify Web Services a script ID as defined with RSA, together with the eventData and confirmation code. The script ID includes the instanceId, identificationData, and eventType. At the same time, Adaptive Authentication returns a Challenge response to the organization with a confirmation code. 13. The organization’s web application receives the confirmation code and presents the confirmation HTML page to the user.

3: SOAP API Use Cases 41 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Stage V - QueryAuthStatus The fifth stage of the challenge questions authentication message flow involves the following steps: 14. The Authentify service initiates phone authentication using the phone number that the user selected in Stage II. The Authentify service guides and prompts the user to enter the confirmation code displayed by the organization. Meanwhile, the user’s browser refreshes every five seconds to periodically check authentication status. 15. When the browser page refreshes, it signals the organization to find out the phone authentication status. The organization sends a QueryAuthStatus request to Adaptive Authentication with the transactionId, which is taken from the Analyze response or from Challenge response. 16. Adaptive Authentication returns a QueryAuthStatus response with credentialAuthStatusResponse.oobPhoneAuthStatusResponse status = PENDING. 17. Steps 2 and 3 are repeated, with the user’s browser page refreshing every five seconds with a display of the QueryAuthStatus message until the user enters the confirmation code. Once the user enters the confirmation code, the code is sent to Authentify for validation. 18. If the validation is successful, Authentify sends Adaptive Authentication a success status. 19. After the user browser refreshes and the organization sends a QueryAuthStatus request, Adaptive Authentication returns a response with a success status and the organization allows the user to continue with the logon or transaction.

Note: If the user supplies the correct password during the out-of-band phone authentication attempt but call forwarding is detected, the authentication fails and a case is opened in Case Management. In such cases, an error message is returned in the queryAuthStatus response indicating that call forwarding was detected (error code: 20697; error text: "Authentication terminated for security reasons: call-forwarding was detected.").

42 3: SOAP API Use Cases RSA Adaptive Authentication (Hosted) Programmer’s Guide

Out-of-Band SMS Authentication Use Case The following figure shows the message flow during the out-of-band SMS authentication procedure. Each stage is described in the sections that follow.

Adaptive User Browser Organization Authentication

5. Organization sends Analyze 1. Request logon/initiate transaction request with 2. Display logon/transaction form apiType =DIRECT _SOAP _API Stage II: Risk and assessment and 3. Gather device data (IP Stage I: Logon identificationData .userName authentication address, browser information, Process decision fingerprint, deviceTokenCookie, deviceTokenFSO) 6. Adaptive Authentication returns 4. Submit form details and device Analyze response with data riskResult .triggeredRule .actionCode and transactionId , Get identifying the as Preliminary credentialType OOBSMS Authentication Data (optional, 7. Organization sends Query request with depends on getPhoneNumbers and risk) availableForSMS = True Stage III: Providing data for out-of-band 9. Organization displays phone number SMS selection form authentication process 8. Adaptive Authentication Phone returns Query response with 10. User selects phone number. Selection list of telephone numbers

11. Organization sends Challenge request with oobSMSChallengeRequest , 12. Adaptive Authentication transactionID and other Stage IV: Phone sends a script ID as defined with event and phone data Authentication RSA, with the eventData and Initiation confirmation code.

13. Authentify sends out-of-band SMS to Authentify User’s the end user with the confirmation code. Phone

14. Organization displays a web page to the user with a text box for Web Page for User the confirmation code. confirmation Intervention code 15. User enters confirmation code. 16. Organization sends Authenticate request with the confirmation code

Stage V: Authentication Act Upon 17. Adaptive Authentication returns Authenticate response Process result code with authentication status

Pass

18. Based on the authentication result, the organization decides whether to allow the user to continue with the logon or Welcome transaction. Page

3: SOAP API Use Cases 43 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Stage II - Analyze Message The second stage of the out-of-band SMS authentication message flow involves the following steps: 5. The organization extracts the relevant data for the Risk Engine from the initiation page where the transaction details are entered and submitted. The organization then composes a Web Services Analyze request that includes the common headers and data elements described in “Message Structure and Format” on page 17. The required headers and data elements for this request include the following fields: • identificationData.userName • messageHeader.apiType = DIRECT_SOAP_API • eventDataList.eventData.eventType 6. The information in the Analyze request is processed by the Risk Engine. Adaptive Authentication returns an Analyze response with the following fields: • riskResult.triggeredRule.actionCode. Contains the action code for the transaction as defined by the Risk Engine and the organization’s policy rules. The action code must be stored in the session so that the guarded page (the page that contains sensitive information and requires authentication to access) can act accordingly. If the value of this field is either REDIRECT_CHALLENGE or REDIRECT_COLLECT, the organization must take action. This section describes authentication. For more information on collection see Chapter 2, “Initial Data Collection.” • identificationData.transactionId. The unique transaction ID that must be used in all subsequent calls to Adaptive Authentication. • collectableCredentialList. collectableCredential.credentialType = OOBSMS

44 3: SOAP API Use Cases RSA Adaptive Authentication (Hosted) Programmer’s Guide

Stage III - Query The third stage of the out-of-band SMS authentication message flow involves the following steps: 7. If the actionCode field is REDIRECT_CHALLENGE and credentialType=OOBSMS, the organization sends a Challenge request to Adaptive Authentication with the identificationData.userName or identificationData.transactionId fields.

Note: In order to only receive SMS-enabled phone numbers, the organization must set the availableForSMS attribute to True.

8. Adaptive Authentication returns a Query response to the organization with the contactList. This is a list of telephone numbers defined by one or more telephone structures that contain the data about the phone number (including label, phoneNumber, and other data). If the availableForSMS attribute in the Query request was set to True, then this list will only include telephone numbers that are marked to receive SMS messages. 9. The organization uses the phone numbers from the Query response and renders the UI page that prompts the user to select a phone number for out-of-band SMS authentication. 10. The user selects a phone number to use for out-of-band SMS authentication and submits the form to the organization.

Stage IV - Challenge The fourth stage of the out-of-band SMS authentication message flow involves the following steps: 11. The organization sends a Challenge request to Adaptive Authentication with the following fields: • identificationData.transactionId. Alternatively, you may send the eventData structure in conjunction with userName instead of the transactionId. The eventData structure includes enough event information for the Authentify service to be able to communicate the event details during phone authentication (eventType, amount, account, and so on). • credentialChallengeRequest.oobSMSChallengeRequest. Contains the stored phone number information.

• identificationData.userName •eventData. The structure that contains the event information.

3: SOAP API Use Cases 45 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Note: The following API error message is returned if the end user requests that the SMS be resent and the maximum number of SMS resend attempts is reached without successful authentication: 20730: Maximum SMS resend attempts without successful authentication exceeded.

12. Adaptive Authentication sends the Authentify Web Services a script ID as defined with RSA, together with the eventData and confirmation code. The script ID includes the instanceId, identificationData, and eventType. 13. Authentify send the out-of-band SMS to the end user at the selected phone number with the confirmation code. 14. The organization displays a text box to the end user on the web page. 15. The end user enters the confirmation code received in the SMS in the text box on the web page and submits.

Stage V - Authenticate The fifth stage of the out-of-band SMS authentication message flow involves the following steps: 16. The organization sends a Authenticate request to Adaptive Authentication with the following fields: • identificationData.transactionId – credentialDataList.oobSMSData.payload. Contains the token, which is the confirmation code as entered by the user. 17. Adaptive Authentication authenticates the user's confirmation code and returns the Authenticate response with the following fields: • otpAuthResult.payload.callStatus. The authentication status, including: – statusCode. The status code of the Authenticate request. – statusDescription. The status description of the Authenticate request. 18. Based on the Authenticate response, the organization decides whether to allow the user to continue with the logon or transaction.

46 3: SOAP API Use Cases RSA Adaptive Authentication (Hosted) Programmer’s Guide

Knowledge-Based Authentication Use Case Knowledge-based authentication (KBA) (also known as out-of-wallet credentials) uses private user data, for example, a Social Security Number or postal code, to authenticate users during activities such as Internet banking and to ensure that the credentials all belong to the same identity. Public records are used to reference and analyze this user data. To prevent identity theft, out-of-wallet credentials are based on facts about the user’s life that are not easily available to others and that fraudsters would not generally know. The user knows the information but would not normally carry it in his or her wallet, hence the name out-of-wallet authentication. Out-of-wallet data is generated automatically through convergence of databases and involves multiple-choice questions, for example: • What amount do you pay for your mortgage each month? • Who is your Internet Service Provider? • With what company is your car insured? This type of information is available to a database compiler, yet is not readily available to fraudsters who may be attempting identity theft.

Note: It is important to avoid human errors with KBA policy configurations as incorrect rules may incur high costs and create performance implications.

3: SOAP API Use Cases 47 RSA Adaptive Authentication (Hosted) Programmer’s Guide

The following figure shows the message flow during the knowledge-based authentication procedure. Each stage is described in this section. The preliminary pre-enrollment stages are not included in this figure.

User Adaptive Organization Browser Authentication

1. Request logon/initiate transaction

2. Display logon/transaction form 5. Organization sends Analyze request with Stage II: Risk 3. Gather device data (IP address, apiType =DIRECT _SOAP Stage I: Logon assessment and browser information, fingerprint, _API and .userName Process authentication deviceTokenCookie, identificationData decision deviceTokenFSO)

4. Submit form details and device data 6. Adaptive Authentication returns Analyze response with riskResult .triggeredRule .actionCode . identificationId .transac tionId , identifying the Initial credentialType as KBA knowledge- based application process Adaptive Authentication (optional, sends user details to depends on risk) 7. Organization KBA application sends Challenge request with Stage III: transactionId Providing data and user for org authentication KBA application identification process, including data, such as action code and userNameData , question list identification Type and 8. KBA application verifies identification User ID and returns Value questions to Adaptive 10. Displays challenge questions form Authentication Challenge 9. Adaptive Authentication User returns Challenge 11. User submits answers response with kbaQuestionResult 12. Organization sends 13. Adaptive Authentication Authenticate request for this sends user answers to KBA application for validation transactionID with Organization decides credentialChallengeList how to proceed based Pending including user responses for 8 Stage IV: Match on result code: verification KBA PASSED. Forward to Answers application organization’s online Act Upon Welcome page result Authentication PENDING. Repeat code 14. Adaptive Results authentication process Authentication returns a with a new round of response with one of the questions (maximum of 15 following: twice) Pass PASSED , PENDING , FAILED. User failed the FAILED authentication ERROR: Error condition Welcome User logged on to Page organization’s site showing Welcome page

48 3: SOAP API Use Cases RSA Adaptive Authentication (Hosted) Programmer’s Guide

Stage I - Logon Process The first stage of this use case involves the following steps: 1. The user requests to log on or initiate a transaction to the organization’s web application. 2. The organization’s web application displays the logon or transaction page. 3. The data gathering JavaScript executes as the logon page loads and collects the device data, such as the IP address, browser information and fingerprint information. 4. The user enters the logon or transaction details, and submits the information. The device and event data is submitted. Stage II - Analyze Message The second stage of the knowledge-based authentication message flow involves the following steps: 5. The organization extracts the relevant data for the Risk Engine from the initiation page where the transaction details are entered and submitted. The organization then composes a Web Services Analyze request that includes the common headers and data elements described in “Message Structure and Format” on  page 17. The required headers and data elements for this request include the following fields: • identificationData.userName • messageHeader.apiType = DIRECT_SOAP_API • eventDataList.eventData.eventType 6. The information in the Analyze request is processed by the Risk Engine. Adaptive Authentication returns an Analyze response with the following fields: • riskResult.triggeredRule.actionCode. Contains the action code for the transaction as defined by the Risk Engine and the organization’s policy rules. The action code must be stored in the session so that the guarded page (the page that contains sensitive information and requires authentication to access) can act accordingly. If the value of this field is REDIRECT_CHALLENGE, the organization must take action. • identificationData.transactionId. The unique transaction ID that must be used in all subsequent calls to Adaptive Authentication. • collectableCredentialList. collectableCredential.credentialType = KBA Stage III - Challenge The third stage of the knowledge-based authentication message flow involves the following steps: 7. The organization sends a Challenge request to Adaptive Authentication with the following fields: • identificationData.transactionId • userData.userNameData • Additional user identification information, including identificationType (such as social security number) and identificationValue, such as the value of the social security number. For more information, see the API Reference Guide.

3: SOAP API Use Cases 49 RSA Adaptive Authentication (Hosted) Programmer’s Guide

8. The Adaptive Authentication knowledge-based authentication application takes the user details and fetches the KBA-based questions for the user. If there is more than one user with the same name, preliminary questions are used to confirm the user’s identity. When the user’s identity is confirmed, the KBA application creates a list of multiple-choice questions to ask the user.

Note: When attempting to perform knowledge-based authentication for users under the age of 18 (according to the value in the KBA-related dateOfBirth field), the request fails as KBA only deals with users above the age of 18. There is also a limit of two characters for the value of the state field (includes a-z or A-Z characters only). If this limit is exceeded, an “invalid address-state in address tag field length” is received.

9. Adaptive Authentication returns a Challenge response to the organization with the credentialChallengeList.credentialChallenge.kbaQuestionResult field, which includes the questions to use for authentication. 10. The organization renders the UI pages based on the information received from Adaptive Authentication. 11. The authentication procedure and the UI are controlled by the organization. The organization presents the selected questions to the user and the user answers the knowledge-based questions. This completes the user intervention. Stage IV - Authenticate The fourth stage of the knowledge-based authentication message flow involves the following steps: 12. The organization sends Adaptive Authentication an Authenticate request with the following fields: • identificationData.transactionId • credentialChallengeList. List of one or more question data structures. Each structure contains data on a single question, including the question ID and the corresponding answers entered by the user. 13. Adaptive Authentication validates the user answers and returns one of the following statuses: PASS, PENDING, ERROR, or FAILED. For more information, see step 8 and the API Reference Guide. 14. Adaptive Authentication returns an Authenticate response with the authentication status to the organization. 15. The organization decides whether to allow the user to continue working in the organization’s site based on the status, as follows: • PASS. User is allowed to proceed with the requested operation. • PENDING. A new question list for the user is sent. Repeat the Authenticate Stage until you get a PASSED, FAILED or ERROR status (maximum of twice). • FAILED. An error has occurred. An error code and descriptive text are also returned. • ERROR. An error has occurred. An error code and descriptive text are also returned.

50 3: SOAP API Use Cases RSA Adaptive Authentication (Hosted) Programmer’s Guide

One-Time Password Authentication Use Case The following figure shows the message flow during the one-time password (OTP) authentication procedure. Each stage is described in the sections that follow.

Note: The figure does not include the first stage (logon stage) described in the flow.

Adaptive User Browser Organization Authentication

Organization sends Analyze User logs on - submits User ID request with Stage I: Risk and password apiType =DIRECT _SOAP API , assessment Login Process eventType , and userName and 1 authentication decision Adaptive Authentication returns Analyze response with 2 riskResult .triggeredRule .actionCode identificationData .transactionId , identifying the credentialType as OTP _EMAIL

3 Initiate OTP Process Organization sends Challenge request with transactionId and otpType Stage II: EMAIL Providing Organization sends one- OTP for time password to the user organization through e-mail. The user Adaptive Authentication enters it in the returns Challenge authentication organization’s online web response with process site for authentication. 5 otpChallenge including the 4 OTP

6 User User Response Intervention User enters the one-time password in the organization’s online page and submits.

7 Organization sends Authentication request with transactionId and Adaptive Authentication otpDatatoken containing Stage III: authenticates the OTP the OTP entered by the Match One- received by matching it user for verification to the one sent to the Time organization, verifying Password that 30 minutes have not elapsed since generating the OTP, the Adaptive Authentication returns end user has entered Authenticate response the OTP only once in specifying if the user passed or Act upon result the organization’s failed authentication in code online page, and that no statusCode and other OTP has been statusDescription 8 generated for this user 9 during this period

3: SOAP API Use Cases 51 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Stage II - Analyze Message The second stage of the OTP authentication message flow involves the following steps: 5. The organization extracts the relevant data for the Risk Engine from the initiation page where the transaction details are entered and submitted. 6. The organization then composes a Web Services Analyze request that includes the common headers and data elements described in “Message Structure and Format” on page 17. The required headers and data elements for this request include: • identificationData.userName • messageHeader.apiType = DIRECT_SOAP_API • eventDataList.eventData.eventType 7. The information in the Analyze request is processed by the Risk Engine. Adaptive Authentication returns an Analyze response with the following fields: • riskResult.triggeredRule.actionCode. Contains the action code for the transaction as defined by the Risk Engine and the organization's policy rules. The action code must be stored in the session so that the guarded page (the page that contains sensitive information and therefore requires authentication to access) can act accordingly. If the value of this field is REDIRECT_CHALLENGE, the organization must take action. • identificationData.transactionId. The unique transaction ID that must be used in all subsequent calls to Adaptive Authentication. • collectableCredentialList.collectableCredential.credentialType = OTP_EMAIL

52 3: SOAP API Use Cases RSA Adaptive Authentication (Hosted) Programmer’s Guide

Stage III - Challenge The third stage of the OTP authentication message flow involves the following steps: 8. The organization sends a Challenge request to Adaptive Authentication with the following fields: • identificationData.transactionId • credentialChallengeRequestList.otpChallengeRequest.payload.otpType=E MAIL 9. Adaptive Authentication returns a Challenge response to the organization with credentialChallengeList.otpChallenge.payload, including the following fields: • callStatus – statusCode. Status code of the one-time password Challenge request. – statusDescription. Status description of the one-time password Challenge request. •Token. This is the one-time password. The authentication procedure and the UI are controlled by the organization. The organization relays the OTP to the end user using e-mail, who is prompted to enter it in the organization's online web page. This completes the user intervention.

Stage IV - Authenticate The fourth stage of the OTP authentication message flow involves the following steps: 10. The organization sends a Authenticate request to Adaptive Authentication with the following fields: • identificationData.transactionId • credentialDataList.otpData.payload. Contains the following fields: –otpType. The channel from which this one-time password was collected. –Token. The one-time password as entered by the user. 11. Adaptive Authentication authenticates the user’s OTP and returns the Authenticate response with the following fields: • otpAuthResult.payload.callStatus. The one-time password's authentication status, including: – statusCode. The status code of the one-time password Authenticate request. – statusDescription. The status description of the one-time password Authenticate request. See the API Reference Guide for more information. 12. Based on the Authenticate response, the organization decides whether to allow the user to continue working in the organization’s site.

3: SOAP API Use Cases 53 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Use Case: Authentication Passed or Failed The one-time password authentication process is triggered due to high risk or Policy Rules. If, upon receiving the organization application's Authenticate request with the end user’s OTP, RSA determines that: • There is a match between the OTP that RSA sent and the one received in the Authenticate request and all additional criteria are met. RSA sends an “OK” message. The organization's application allows the user to continue to perform the activity. • There is no match between the OTP that RSA sent and the one received in the Authenticate request or none of the additional criteria is valid. RSA sends an error message describing the reason why authentication failed. The organization’s application must decide how to proceed with the end user, for example, block the application or authenticate the user by other means.

General Considerations RSA recommends that you consider the following when sending a one-time password (OTP) using e-mail: • The organization is responsible for sending the OTP using its mail server or integrating with its Short Message Service (SMS) provider to send an SMS message (e-mail addresses and phone numbers must be available to the organization prior to implementing this method). • Upon authentication failure, the organization must define whether to allow the transaction and subsequent attempts.

Security Recommendations As a security precaution, RSA recommends that end users not be allowed to copy and paste the OTP from the e-mail message to the authentication page.

Usability Recommendations RSA recommends the following usability guidelines for the OTP authentication method: Checksum. RSA generates a checksum character at the end of the OTP. You can use the checksum JavaScript code that RSA provides to reduce end user typing mistakes. For more information, see “Implementing the One-Time Password Checksum” on page 55. Authentication page. Add a message notifying end users that an OTP will be sent to them shortly, which they need to enter into the online application. You can correlate between the OTP and the activity performed by the end user. If the end user fails authentication, you can allow them to request another OTP by adding a Request New OTP link, or decide to deny or review the transaction. You must accompany this link with a message notifying end users that a new OTP will be sent shortly, and that they must enter the new OTP in the online application. Session Time Out page. When the OTP session has terminated, display a message explaining to the end users that the session has ended and how to proceed.

54 3: SOAP API Use Cases RSA Adaptive Authentication (Hosted) Programmer’s Guide

Implementing the One-Time Password Checksum The OTP checksum algorithm ensures that OTPs entered by your end users in your online page are entered correctly with no typing mistakes. This is important since OTPs can only be used once, after which they become invalid. This algorithm separates the user-entered OTP value into OTP and checksum, and then calculates the checksum from the OTP portion. After positively matching the calculated checksum with the actual one, it sends the OTP to RSA for authentication.

Note: The OTP checksum is not a security mechanism and validating the checksum does not imply that the end user who entered the OTP is indeed a legitimate user.

To implement the OTP checksum feature: 1. Convert the following code to the required browser scripting language. Const unsigned char ALPHA_A=’A’; Const int LETERS_IN_ALHABET=26; unsigned char Translate2Char(unsigned char in_char) { unsigned char tmp = in_char % 36; /*This string consists of 26 letters and 10 numbers.*/ if (tmp <10) tmp += ZERO; else tmp += ALPHA_A -10; return tmp; } unsigned char Translate2Code(unsigned char in_char) { if (in_char > ALPHA_A) return (in_char - ALPHA_A+10); else return (in_char - ZERO); } 2. Invoke the checksum function with the following parameters: • otp_challenge. The OTP Challenge string. •otp_length. The length of the challenge without the checksum, for example, when an organization configures the OTP length to be 10, the OTP is actually 10 letters + 1 checksum letter and the parameter here must be 10. unsigned char Checksum (unsigned char * otp_challenge, int otp_length) { unsigned char checksum = 0; for(int i=0;i

3: SOAP API Use Cases 55 RSA Adaptive Authentication (Hosted) Programmer’s Guide

5. Match the calculated checksum to the original checksum entered by the user. If there is a match, send the OTP to RSA for authentication.

Remember Me Use Cases This section describes the general flows and recommended best practices for the Adaptive Authentication Remember Me feature, which provides the ability to link a specific device to a specific user and is only relevant to customers using this feature. The organization can either choose to perform device linking without exposing this to the end customer or display a Remember Me checkbox giving the end user the option of remembering (linking) or not remembering (not linking) the device. Device linking can be done during collection and the authentication of users. In the authentication flow, if there is no explicit request to link or not link the device (that is, the deviceManagementRequest structure is not received), the default is to perform device linking upon successful authentication. For more information regarding the API requests and Remember Me status codes, see the API Reference Guide.

Remember Me in Collection Flow The Remember Me flow for collection is as follows: 1. Organization sends an Analyze request. The online service application server (organization) sends an Analyze request to Adaptive Authentication. The organization usually sends the Analyze request when the user requests access to a specific page or service. 2. Adaptive Authentication returns an Analyze response including a risk score. The Adaptive Authentication Web Services authenticates the device and behavior and completes a risk assessment, returning a response that includes a recommendation for collection from the user. The actionCode field in this response is REDIRECT_COLLECT. 3. Organization collects information from user. The organization handles all interactions with the user and collects the information from the user to use for later authentication, for example, questions or contact telephone numbers. To do this, the organization prompts the user with interface screens requesting the required information. 4. User provides information to Organization. The user provides the required information to the organization. At this stage, the organization can display a “Remember Me” checkbox to the user, allowing the user to decide whether to be remembered on the device being used. In this case, RSA recommends that an explanation be provided to the user regarding when to use this checkbox, for example, not to use it when working from a public computer. If the current device is already linked, and the user leaves the checkbox unselected, then this device is unlinked from the user.

Note: The default is for the “Remember Me” checkbox to be unselected. This means that the default will be for RSA not to link the device to the user in the collection flow.

56 3: SOAP API Use Cases RSA Adaptive Authentication (Hosted) Programmer’s Guide

5. Organization sends an updateUser request. The organization’s application sends an updateUser request to Adaptive Authentication with the data collected from the user to store in the Adaptive Authentication application. If the option to link or not link devices is exposed to the end user, the request must include: • The identificationData structure with the transactionId. • The deviceManagementRequest structure with the following data elements containing the information about whether device linking is or is not required: – actionTypeList. The action to be performed on the user’s device. This data element includes the deviceActionTypes field, which is UPDATE_DEVICE in this case. – deviceData. Includes the bindingType (mandatory) and lookupLabel (optional field that is a label or “nickname” for the user’s device, for example, work or home). If device linking is required, the bindingType must be HARD_BIND and if device linking is not required, it must be NONE.

Note: If the organization chooses to not expose the device linking to the end user and device linking is not required in collection, the deviceManagementRequest structure should not be sent in the updateUser request.

6. Adaptive Authentication returns an updateUser response. Adaptive Authentication returns an updateUser response including a status indicating the result of the collection data storage and the status of the device linking request (only if requested).

Remember Me in Authentication Flow This section describes the Remember Me in Authentication flow. The flow for OOB phone authentication is described in “Remember Me in Out-of-Band Phone Authentication Flow.” The Remember Me feature is also supported for the FI-defined authentication method, see “Remember Me in FI-Defined Authentication Flow” on page 61. For more information on each authentication method, see the detailed flows for each method.

3: SOAP API Use Cases 57 RSA Adaptive Authentication (Hosted) Programmer’s Guide

The following figure shows the Remember Me flow for the challenge questions, KBA, and OTP authentication methods.

Adaptive User Browser Organization Authentication

Stage I: Risk User logs on - submits User ID and Organization sends Analyze assessment password Logon Process request and device data and authentication 1 decision

Adaptive Authentication returns Analyze response and recommendation to authenticate.

3 Organization sends Challenge request. Organization sends one- time password to the user through e-mail. The user enters it in the Adaptive Authentication organization’s online 5 returns Challenge 4 banking site for response. User authentication. Intervention

User enters the relevant information for the User Response authentication method, Remember Me (Y/N) and 6 label (optional).

Stage II: 7 Customer sends Authenticate request with Authentication deviceManagementRequest and Linking structured if required Adaptive Authentication returns Authenticate response specifying if Organization decides the user passed or failed authentication and with the how to proceed Act upon result result of the linking. If the based on the result. code user passed and Remember Me is Yes, then Adaptive Authentication links 9 the device.

58 3: SOAP API Use Cases RSA Adaptive Authentication (Hosted) Programmer’s Guide

The flow includes the following steps: 1. Organization sends an Analyze request. The online service application server (organization) sends an Analyze request to Adaptive Authentication. The organization usually sends the Analyze request when the user requests access to a specific page or service. 2. Adaptive Authentication returns an Analyze response including a risk score. The Adaptive Authentication Web Services authenticates the device and behavior and completes a risk assessment, returning a response that includes a recommendation regarding further authentication of the end user. The actionCode field in this response is REDIRECT_CHALLENGE and the credentialType depends on the authentication method (challenge questions, KBA, or OTP). 3. Organization sends a Challenge request. The organization’s application sends a Challenge request to Adaptive Authentication to collect the authentication data with which to challenge the user. 4. Adaptive Authentication returns a Challenge response with the data to challenge the user with. Adaptive Authentication returns a Challenge response to the organization with the data with which to challenge the user. This data is stored in Adaptive Authentication. 5. Organization sends the user an additional authentication page. The organization handles all interactions with the user and collects the user information required for authentication. To do this, the organization sends the user interface screens using the stored authentication data from Adaptive Authentication and handles any other required action. 6. User Authentication. The user responds to the authentication questions, for example, answers the challenge questions. At this stage, the organization can do one of the following: • Display a “Remember Me” checkbox to the user allowing the user to decide whether to be remembered on the device being used. In this case, RSA recommends that an explanation be provided to the user regarding when to use this checkbox, for example, not to use it when working from a public computer. If the current device is already linked, and the user clears the checkbox, this device is unlinked from the user.

Note: The default is for the “Remember Me” checkbox to be selected. This means that the default will be for RSA to link the device to the user when authentication is successful. The reason for this is that it is preferable that the device is linked to avoid higher challenge rates upon subsequent logons.

• Automatically perform device linking upon successful authentication of the user without exposing this to the user.

3: SOAP API Use Cases 59 RSA Adaptive Authentication (Hosted) Programmer’s Guide

7. Organization sends Authenticate request to verify user answers. The organization sends the user’s answers in the Authenticate request to Adaptive Authentication for verification. This request must include the end user’s device linking preference in the deviceManagementRequest structure with the following data elements: • actionTypeList. The action to be performed on the user’s device. This data element includes the deviceActionTypes field, which is UPDATE_DEVICE in this case. • DeviceData. Includes the bindingType (mandatory) and lookupLabel (optional field that is a label or nickname for the user’s device, for example, work or home). If device linking is required, the bindingType must be HARD_BIND and if device linking is not required, it is NONE.

Note: In the authentication flow, if there is no explicit request to link or not link the device, that is, the deviceManagementRequest structure is not received, the default is to perform device linking upon successful authentication.

8. Adaptive Authentication returns an Authenticate response. Adaptive Authentication compares the user authentication answers against the information stored in the system for the user and returns an Authenticate response back to the organization. The Authenticate response also includes the deviceManagementResponse data element, which includes the information about the device linking. If the verification is successful, the application server allows the user to accesses required page or service.

60 3: SOAP API Use Cases RSA Adaptive Authentication (Hosted) Programmer’s Guide

Remember Me in FI-Defined Authentication Flow The following figure shows the Remember Me flow for the FI-defined authentication methods.

Adaptive User Browser Organization Authentication

Organization sends Analyze Stage I: Risk User logs on - submits User ID and request and device data assessment and password Logon Process 1 authentication decision

Adaptive Authentication 2 returns Analyze response and recommendation to authenticate.

Organization sends the one-time password to the user through e-mail. The user enters it in the User organization’s online web Intervention site for authentication.

User enters the relevant information for the User Response authentication method, Remember Me (Y/N) and Label (optional)

Stage II: Customer sends Authenticate Authentication request with and Linking deviceManagementRequest structured if required 3

3: SOAP API Use Cases 61 RSA Adaptive Authentication (Hosted) Programmer’s Guide

The flow includes the following steps: 1. Organization sends an Analyze request. The online service application server sends an Analyze request to Adaptive Authentication. The organization usually sends the Analyze request when the user requests access to a specific page or service. 2. Adaptive Authentication returns an Analyze response including a risk score. The Adaptive Authentication Web Services authenticates the device and behavior and completes a risk assessment, returning a response that includes a recommendation regarding further authentication of the end user. The actionCode field in this response is REDIRECT_CHALLENGE and the credentialType is CLIENT_DEFINED. 3. The organization authenticates the user and notifies RSA about the authentication status. If the organization sends an authentication successful message, RSA attempts to link the device to the user profile. If the organization sends an authentication failed message, the device is not linked to the user.

Note: A response will not be returned for this call. Binding of the device to the user will fail if the user tries to use a label that was previously used by that user. Organization can retrieve the list of devices bound to a user using the Query flow.

62 3: SOAP API Use Cases RSA Adaptive Authentication (Hosted) Programmer’s Guide

Remember Me in Out-of-Band Phone Authentication Flow The following figure shows the Remember Me flow for the OOB phone authentication method.

Risk-Based User Browser Organization Authentication

5 Phone Selection Org sends Challenge request with User selects phone number Stage III: Phone Authentify transactionId or Authentication and other userName Initiation 6 event and phone data

Responds with status = 12 Stage IV: Phone PENDING Authentication and Validation

13 Confirmation code validated User enters confirmation code 14

Authentication - success Organization sends QueryAuthStatus with transactionId status=SUCCESS 15 Present Welcome page

3: SOAP API Use Cases 63 RSA Adaptive Authentication (Hosted) Programmer’s Guide

The flow includes the following steps: 1. Organization sends an Analyze request. The online service application server (organization) sends an Analyze request to Adaptive Authentication. The organization usually sends the Analyze request when the user requests access to a specific page or service. 2. Adaptive Authentication returns an Analyze response including a risk score. The Adaptive Authentication Web Services authenticates the device and behavior and completes a risk assessment, returning a response that includes a recommendation regarding further authentication of the client. The actionCode field in this response is REDIRECT_CHALLENGE and the credentialType is OOBPHONE. 3. Organization sends a Query request. The organization sends a Query request to Adaptive Authentication to collect the user’s phone numbers. 4. Adaptive Authentication returns a Query response. Adaptive Authentication returns a Query response to the organization with the contactList (the list of contact telephone numbers for the user). 5. Organization renders UI page. The organization uses the phone numbers from the Query response and renders the UI page that prompts the user to select a phone number for out-of-band phone authentication. 6. User selects a phone number. The user selects a phone number to use for out-of-band phone authentication and submits the form to the organization. The organization application does one of the following: • Display a “Remember Me” checkbox to the user, allowing the user to decide whether to be remembered on the device being used. In this case, RSA recommends that an explanation be provided to the user regarding when to use this checkbox, for example, not to use it when working from a public computer. If the current device is already linked, and the user clears the checkbox, the current device is unlinked from the user.

Note: The default is for the “Remember Me” checkbox to be selected. This means that the default is for RSA to link the device to the user when authentication is successful. The reason for this is that it is preferable that the device is linked to avoid higher challenge rates upon subsequent logons.

• Automatically perform device linking upon successful authentication of the user without exposing this to the user.

64 3: SOAP API Use Cases RSA Adaptive Authentication (Hosted) Programmer’s Guide

7. Organization sends a Challenge request. The organization application sends a Challenge request to Adaptive Authentication with the phone number chosen by the user for the Phone authentication. This request includes the end user’s device linking preference in the deviceManagementRequest structure with the following data elements: • actionTypeList. The action to be performed on the user’s device. This data element includes the deviceActionTypes field, which is UPDATE_DEVICE in this case. • deviceData. Includes the bindingType (mandatory) and lookupLabel (optional field that is a label or nickname for the user’s device, for example, work or home). If device linking is required, the bindingType must be HARD_BIND and if device linking is not required, it is NONE.

8. Adaptive Authentication returns a Challenge response. Adaptive Authentication returns a Challenge response to the organization with a confirmation code for the OOB phone authentication. This response does not include information about the device linking request as the authentication has not yet been completed at this stage. 9. Organization sends the user the authentication page. The organization's web application receives the confirmation code and presents the confirmation HTML page to the user with the code. 10. User Authentication. The user is guided and prompted to enter the confirmation code displayed by the organization. Meanwhile, the user's browser refreshes every five seconds to periodically check authentication status. 11. Organization sends queryAuthStatus request. When the browser page refreshes, it signals the organization to find out the phone authentication status. The organization sends a queryAuthStatus request to Adaptive Authentication. 12. Adaptive Authentication returns queryAuthStatus response. Adaptive Authentication returns a queryAuthStatus response that includes the deviceManagementResponse data element with the device linking information. While the authentication status is PENDING, the device linking response will always be that device linking was not yet performed. Once the authentication process is completed, Adaptive Authentication responds with a successful or failed authentication and device linking status. If successful, the organization allows the user to continue with the logon or transaction.

3: SOAP API Use Cases 65 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Remember Me in Query Flow The Query request can be used to query device linking information for specific users. For example, an end user or Customer Service Representative (CSR) uses and links a specific device at work and then wants to unlink the device when leaving work. By querying for the list of linked devices, the end user or CSR can then use this information to unlink the specific device or all of the devices. For information on unlinking devices, see “Remember Me in Unlink Flow” on page 66. The flow includes the following steps: 1. Organization sends Query request. The online service application server (organization) sends a Query request to Adaptive Authentication for device linking information. The deviceManagementRequest must include the following data element: • actionTypeList. The action to be performed on the user’s device. This data element includes the deviceActionTypes field, which is BROWSE_DEVICES in this case. 2. Adaptive Authentication returns Query response. Adaptive Authentication returns a Query response with information on the 10 most recently used linked devices.

Remember Me in Unlink Flow The updateUser method can be used to unlink a specific device or unlink all devices for a user. For example, an end user or Customer Service Representative (CSR) uses and links a specific device at work and then wants to unlink the device when leaving work. The flow includes the following steps: 1. Organization sends updateUser request. The online service application server (organization) sends an updateUser request to Adaptive Authentication requesting to unlink a specific device or unlink all devices for a user. The deviceManagementRequest must include the following data elements: • actionTypeList. The action to be performed on the user's device. In this case, the value of the deviceActionTypes field can be either: – UNBIND_ALL_DEVICES. To unlink all devices for the user. – UPDATE_DEVICE. To unlink a specific device for the user. • deviceData. Includes the bindingType (mandatory) and lookupLabel (optional). This data element is relevant when deviceActionTypes=UPDATE_DEVICE. In this case, the value of the bindingType is NONE. Either the transactionId or lookupLabel data element must be supplied when deviceActionTypes=UPDATE_DEVICE for Adaptive Authentication to retrieve the specific device for unlinking. 2. Adaptive Authentication returns updateUser response. Adaptive Authentication returns an updateUser response, with the result of the request to unlink a specific device or unlink all devices is in the deviceManagementResponse data element.

66 3: SOAP API Use Cases RSA Adaptive Authentication (Hosted) Programmer’s Guide

4 SOAP API with Data on Organization’s Side This chapter discusses the SOAP API with data stored on the organization’s side integration option. It begins with a general description of the SOAP API with data stored on the organization side message flow, followed by detailed descriptions of the messages and data elements required for a series of specific uses cases.

Handling Authentication Credentials Stored by the Organization The organization can use SOAP API integration to store end user credentials such as challenge questions and answers, and phone numbers) in its own databases. When RSA Adaptive Authentication does not have information about the status of the user credentials, certain internal logic decisions required during the Analyze assessment are restricted. The following are examples of such internal logic decisions that require user credential information: • Challenge only when data exists for the user. • Collect authentication data only when data does not exist or if data is outdated. • Determine if it is safe to use credentials by utilizing parameters such as the age of the credentials' current value and who initiated the change. Adaptive Authentication offers organizations several options to improve system handling when authentication data is stored in their own databases. The organization may carry out all the logic internally and decide not to employ any of the added options. The organization can determine the criteria for notifying Adaptive Authentication of user credential status changes, as follows: • The organization notifies Adaptive Authentication whenever user data changes. With this option, the organization sends a Notify SOAP message informing the system that there has been a change or update in user credentials. For more information, see “Updating RSA Adaptive Authentication about User Credentials Status using the Notify Option” on page 81. • The organization notifies Adaptive Authentication only in high risk scenarios. With this option, the organization sends an Analyze request as usual for a given user transaction. Adaptive Authentication returns an Analyze response, indicating if authentication is possible and if so, the type of authentication method recommended (challenge questions or out-of-band phone authentication).

4: SOAP API with Data on Organization’s Side 67 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Note: The GetActualAction Request message is only available with API version 5.8. This message carries the current user credential status such as new or out of date. The system returns a GetActualAction Response with the actual action required based on the status of user credentials. Alternatively, the organization can send the same information in a Notify SOAP message, as previously described. For more information, see the API Reference Guide.

Message Flow Description The following figure shows the message flow in an example of an Adaptive Authentication use case when data is stored on the organization’s side (challenge questions authentication flow). The other possible use case flows are described in subsequent sections, which discuss the actual messages and data elements involved in the SOAP calls and responses to and from Adaptive Authentication.

Note: All SOAP requests contain the Message and Security headers (and for processors, the Configuration header). All responses contain the Status Header. The administrative elements, such as mandatory headers, are not be specified in the following sections on required data elements.

68 4: SOAP API with Data on Organization’s Side RSA Adaptive Authentication (Hosted) Programmer’s Guide

Adaptive User Browser Organization Authentication

Organization sends Analyze Stage I: Risk request and device data assessment based on User logs on - submits 1 User ID and password many parameters Logon and sensors, Process including Adaptive Authentication provisions of returns Analyze response 2 both risk including risk score score and action code

Organization checks 3 whether the user is collected Adaptive Authentication Initiate returns an indication of whether the user is 4 challenge collected or not process (optional, If the user is collected, the Stage II : depends organization sends a Providing data for on risk) 5 Challenge request asking organization for authentication data authentication process, including question list

Adaptive Authentication returns Challenge 6 Organization fetches response with question list actual authentication data and sends own page for extra authentication Challenge 7 user Answer on User responds to file at challenge questions 9 organization Organization fetches data 8 Stage III : Match 10 answers

Act upon result code Continued interaction with Adaptive Authentication 11 user returns Authenticate response with authentication status

4: SOAP API with Data on Organization’s Side 69 RSA Adaptive Authentication (Hosted) Programmer’s Guide

The flow includes the following steps: 1. The organization sends an Analyze request. The online service application server (organization) sends an Analyze request to Adaptive Authentication. The organization usually sends the Analyze request when the user requests access to a specific page or service. 2. Adaptive Authentication returns an Analyze response including the risk score. The Adaptive Authentication Web Services authenticates the device and behavior, completes a risk assessment, and returns an initial response that includes a recommendation regarding further authentication of the client (based on the initial risk assessment and organization-defined thresholds). 3. The organization checks whether the user is collected or not. If the Analyze response recommended additional authentication, the organization checks whether the user is collected. 4. Adaptive Authentication returns an indication of whether the user is collected or not. 5. If the user is collected, the organization sends a Challenge request (if required). If the organization application server continues with further authentication and the user is collected, the organization sends a SOAP request to get the authentication data, such as challenge questions with which to challenge the user. 6. Adaptive Authentication returns a Challenge response with a list of questions. Adaptive Authentication sends the organization the requested question IDs and question texts. For example, this can include several challenge questions that the user previously selected during an authentication data collection procedure. 7. The organization sends the user additional authentication page. The organization handles all interaction with the user and collects the user's answers. To do this, the organization prompts the user with interface screens using the returned question texts and handles any other required action. For example, the organization sends a page with challenge questions received in the Challenge response. Alternatively, the organization can choose to work with out-of-band phone authentication. 8. User authentication takes place. The user responds to the authentication questions, for example, answers challenge questions. 9. The organization retrieves the stored answers for the user. The organization retrieves the answers stored for this user in the organization’s database using question IDs.

Note: The stored answers are sent with the user’s recently entered responses (from the authentication form) for verification purposes only. No data is stored on the Adaptive Authentication side.

70 4: SOAP API with Data on Organization’s Side RSA Adaptive Authentication (Hosted) Programmer’s Guide

10. The organization sends an Authenticate request to verify the user's answers. The organization sends the user response together with the originally-collected user answers that are stored in the organization’s database to Adaptive Authentication. 11. Adaptive Authentication returns an Authenticate response with the authentication status. Adaptive Authentication checks the user authentication answers, compares them to the stored answers using a proprietary matching algorithm and logic, and then returns an Authenticate response back to the organization with the authentication status. If the verification process is successful, the application server allows the user to access the required page or service.

4: SOAP API with Data on Organization’s Side 71 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Challenge Questions Authentication The following figure shows the message flow during the challenge questions authentication procedure. Each stage is described in the sections that follow.

Adaptive Organization User Browser Authentication

Organization sends Analyze request apiType =DIRECT _SOAP _API , and identificationDatauserName

User logs on - submits 1 User ID and password Adaptive Authentication returns Logon Analyze response with Stage I: Risk Process riskResult .triggeredRule . assessment actioncode and and transactionId , identifying the authentication credentialType as QUESTION decision, including 2 action code

Organization checks 3 whether the user is Initiate collected challenge Adaptive Authentication process returns an indication of 4 (optional – whether the user is depends collected or not Stage II: on risk) Providing data If the user is collected, the 5 organization sends Challenge for request with organization transactionId .groupCou authentication nt and questionCount process, including question list

Adaptive Authentication returns 6 Challenge response with Display/challenge credentialChallengeList questions form Challenge user 7 Answer on file at organization Users submit answers 9

8 Stage III: Match Organization sends answers 10 Authenticate request for this transactionId with Act upon user response for result code verification Based on result code – Adaptive Authentication 11 forward to returns Authenticate organization’s online response with Welcome page authentication status

Welcome User logged on to Page organization’s site showing Welcome page

72 4: SOAP API with Data on Organization’s Side RSA Adaptive Authentication (Hosted) Programmer’s Guide

Stage I - Analyze Message, Recommended Action 1. The organization extracts the relevant data for the Risk Engine from the initiation page where the transaction details are entered and submitted. The organization then composes a Web Services Analyze request that includes the common headers and data elements described in “Message Structure and Format” on  page 17. The required headers and data elements for this request are: • identificationData.userName • messageType.apiType = DIRECT_SOAP_API • eventDataList.eventData.eventType 2. The information in the Analyze request is processed by the Risk Engine. Adaptive Authentication returns an Analyze response with the following fields: • riskResult.triggeredRule.actionCode. Contains the action code for the transaction as defined by the Risk Engine and the organization’s policy rules. The action code must be stored in the session so the guarded page (the page that contains sensitive information and therefore requires authentication to access) can act accordingly. If the value of this field is either REDIRECT_CHALLENGE or REDIRECT_COLLECT, the organization must take action. This section describes authentication. • identificationData.transactionId. The unique transaction ID that must be used for all subsequent calls to Adaptive Authentication. • collectableCredentialList. collectableCredential.credentialType = QUESTION

Stage II - Challenge The second stage of the challenge question authentication message flow with data stored on the organization’s side is as follows: 3. If the Analyze response in Stage I recommended additional authentication, the organization checks whether the user is collected. 4. Adaptive Authentication returns an indication of whether the user is collected or not. 5. If the user is collected, and the actionCode field is REDIRECT_CHALLENGE and credentialType=QUESTION, the organization sends a Challenge request to Adaptive Authentication with the following fields: • identificationData.transactionId • groupCount. Number of question groups. • questionCount. Number of questions per group. 6. Adaptive Authentication returns a Challenge response to the organization with the following fields: credentialChallengeList. A list of one or more questions, which are defined by question data structures that each hold the data for a single question, including the questionId and corresponding questionText. These questions are used for authentication.

4: SOAP API with Data on Organization’s Side 73 RSA Adaptive Authentication (Hosted) Programmer’s Guide

7. The organization renders the UI pages based on the information received from Adaptive Authentication. 8. The authentication procedure and the UI are controlled by the organization. The organization presents the selected questions to the user and the user answers the security questions. This completes the user intervention.

Stage III - Authenticate The third stage of the challenge question authentication message flow with data stored on the organization’s side is as follows: 9. The organization fetches the user’s answers, which are stored in the organization's database. 10. The organization sends Adaptive Authentication an Authenticate request with the following fields: • identificationData.transactionId. • credentialChallengeList. A list of one or more question data structures that contain data on a single question, including question IDs, the corresponding answers that the user entered in the authentication form (userAnswer), and the original answers stored in the database for that user (actualAnswerOnFile).

Note: The end user answers that are stored in the organization’s database and the answers submitted in the authentication form are sent to Adaptive Authentication for verification purposes only. The user data is discarded following verification.

11. Adaptive Authentication validates the user’s answers using a proprietary matching algorithm and logic. Adaptive Authentication then sends the organization an Authenticate response with the authentication status. The organization uses the status to decide whether to allow the user to continue performing operations in the organization’s site.

74 4: SOAP API with Data on Organization’s Side RSA Adaptive Authentication (Hosted) Programmer’s Guide

Out-of-Band Phone Authentication The following figure shows the message flow during the out-of-band phone authentication procedure. Each stage is described in the sections that follow.

Risk-Based User Browser Organization Authentication

Organization sends Analyze requ est apiType =DIRECT _SOAP _API, eventType , and userName User logs on - submits Stage I: Risk User ID and password assessment and Logon Process 1 authentication decision

Adaptive Authentication returns Analyze response with 2 riskResult .triggeredRule . Get Preliminary actionCode Authentication and transactionId , Data identifying the (optional, credentialType as OOBPHONE depends on risk)

Stage II: Internal retrieval of phone number

Organization displays phone number selection form 4 Org sends Challenge Phone Selection request with User selects phone number transactionId or Stage III: Phone Authentify userName Authentication 5 6 and other event and Initiation phone data

Render confirmation Send complete phone code HTML Adaptive Authentication 7 returns Challenge response call data, including with confirmation code eventData , instanceId , Enter identificationData , 8 Confirmation eventType Code Page Phone call

9 User’s Organization sends QueryAuthStatus with Phone transacationId 10 Refresh every 5 seconds

Responds with status = 11 Stage IV: Phone PENDING Authentication and Validation

Confirmation code validated. User enters confirmation code 13 12 Authentication - success Organization sends QueryAuthStatus with transactionId

status=SUCCESS 14 Present Welcome page

4: SOAP API with Data on Organization’s Side 75 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Stage I - Analyze Message The first stage of the out-of-band phone authentication message flow with data stored on the organization’s side is as follows: 1. The organization extracts the relevant data for the Risk Engine from the initiation page where the transaction details are entered and submitted. The organization then composes a Web Services Analyze request that includes the common headers and data elements described in “Message Structure and Format” on page 17. The required headers and data elements for this request are: • identificationData.userName • messageType.apiType = DIRECT_SOAP_API • eventDataList.eventData.eventType 2. The information in the Analyze request is processed by the Risk Engine. Adaptive Authentication returns an Analyze response with the following fields: • riskResult.triggeredRule.actionCode. Contains the action code for the transaction as defined by the Risk Engine and the organization policy rules. The action code must be stored in the session so that the guarded page (the page that contains sensitive information and therefore requires authentication to access) can act accordingly. If the value of this field is either REDIRECT_CHALLENGE or REDIRECT_COLLECT, the organization must take action. This section describes authentication. • identificationData.transactionId. The unique transaction ID that must be used in all subsequent calls to Adaptive Authentication. • collectableCredentialList. collectableCredential.credentialType= OOBPHONE

Stage II - Query The second stage of the out-of-band phone authentication message flow with data stored on the organization’s side is as follows: 3. If the actionCode field is REDIRECT_CHALLENGE and credentialType = OOBPHONE, the organization employs its standard methods to retrieve the internally stored user’s phone numbers. 4. In this example, the organization uses the phone numbers retrieved from its database and renders the UI page that prompts the user to select a phone number for out-of-band phone authentication. 5. The user selects a phone number to use for out-of-band phone authentication and submits the form to the organization.

Stage III - Challenge The third stage of the out-of-band phone authentication message flow with data stored on the organization’s side is as follows: 6. The organization sends a Challenge request to Adaptive Authentication with the following fields:

76 4: SOAP API with Data on Organization’s Side RSA Adaptive Authentication (Hosted) Programmer’s Guide

• identificationData.transactionId. Alternatively, you can send the eventData structure in conjunction with userName instead of transactionId. The eventData structure includes enough event information for the Authentify service to communicate the event details during phone authentication (eventType, amount, account, and so on). If the eventData structure is used, the Challenge response returns a transactionId, which must be used in subsequent QueryAuthStatus messages when polling for phone authentication status. • credentialChallengeRequestList.oobPhoneChallengeRequestPayload. Including areaCode, phoneNumber, and other phone information (in the phoneInfo structure). • identificationData.userName. •eventData. Structure containing event information 7. At this point, Adaptive Authentication sends the Authentify Web Services a script ID as defined with RSA, together with the eventData and confirmation code. The script ID includes the instanceId, identificationData, and eventType. At the same time, Adaptive Authentication returns a Challenge response with a confirmation code. 8. The organization’s web application receives the confirmation code and renders the confirmation HTML page to be presented to the user.

Stage IV - QueryAuthStatus The fourth stage of the out-of-band phone authentication message flow with data stored on the organization’s side is as follows: 9. The Authentify service initiates phone authentication using the phone number that the user selected in Stage II - Query. The Authentify service guides and prompts the user to enter the confirmation code displayed by the organization. Meanwhile, the user's browser refreshes every five seconds to periodically check authentication status. 10. When the browser page refreshes, it signals to the organization to find out the phone authentication status. The organization sends a QueryAuthStatus request to Adaptive Authentication with the following field: • transactionId. Taken from the Analyze response or from the Challenge response. 11. Adaptive Authentication returns a QueryAuthStatus response with status = PENDING. 12. Steps 2 and 3 are repeated, with the user’s browser page refreshing every five seconds with a display of the QueryAuthStatus message until the user enters the confirmation code. Once the user enters the confirmation code, the code is sent to Authentify for validation. 13. If the validation is successful, Authentify sends Adaptive Authentication a success status. 14. After the user’s browser refreshes and the organization sends a QueryAuthStatus request, Adaptive Authentication returns a response with a success status and the organization allows the user to continue with the logon or transaction.

4: SOAP API with Data on Organization’s Side 77 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Out-of-Band SMS Authentication The following figure shows the message flow during the out-of-band SMS authentication procedure. Each stage is described in the sections that follow.

User Browser Organization Risk-Based Authentication

1. Request logon/initiate transaction 5. Organization sends Analyze 2. Display logon/transaction form request with 3. Gather device data (IP address, apiType =DIRECT _SOAP_API Stage II: Risk browser information, fingerprint, Stage I: Logon and assessment and deviceTokenCookie, Process identificationData .userName authentication deviceTokenFSO) decision 4. Submit form details and device data

6. Adaptive Authentication Get Preliminary returns Authentication Analyze response with Data (optional, riskResult .triggered depends on risk) Rule .actionCode and transactionId , identifying the credentialType as OOBSMS

Stage II: Internal retrieval of phone number

7. Organization displays phone number selection form

Phone Selection 8. User selects phone number 9. Organization sends Challenge request with 10. Adaptive Authentication oobSMSChallengeRequest , sends a script ID as defined with transactionID and other Stage IV: SMS RSA, with the eventData and event and phone data Authentication confirmation code. Initiation

11. Authentify sends out-of-band SMS to Authentify User’s the end user with the confirmation code. Phone

12. Organization displays a web page to the user with a text box for Web Page for User the confirmation code. confirmation Intervention code 13. User enters confirmation code. 14. Organization sends Authenticate request with the confirmation code

Stage V: Authentication Act Upon 15. Adaptive Authentication returns Authenticate response Process result code with authentication status

Pass

16. Based on the authentication result, the organization decides whether to allow the user to continue with the logon or Welcome transaction. Page

78 4: SOAP API with Data on Organization’s Side RSA Adaptive Authentication (Hosted) Programmer’s Guide

4: SOAP API with Data on Organization’s Side 79 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Stage III - Query The second stage of the out-of-band SMS authentication message flow with data stored on the organization’s side is as follows: 7. If the actionCode field is REDIRECT_CHALLENGE and credentialType = OOBSMS, the organization employs its standard methods to retrieve the internally stored user’s phone numbers. In this example, the organization uses the phone numbers retrieved from its database and renders the UI page that prompts the user to select a phone number for out-of-band SMS authentication. 8. The user selects a phone number to use for out-of-band SMS authentication and submits the form to the organization.

Note: The organization must ensure that the selected phone number actually belongs to the user and that the user approved usage of the phone number for SMS messaging.

Stage IV - Challenge The fourth stage of the out-of-band SMS authentication message flow involves the following steps: 9. The organization sends a Challenge request to Adaptive Authentication with the following fields: • identificationData.transactionId. Alternatively, you may send the eventData structure in conjunction with userName instead of the transactionId. The eventData structure includes enough event information for the Authentify service to be able to communicate the event details during phone authentication (eventType, amount, account, and so on). • credentialChallengeRequest.oobSMSChallengeRequest. Contains the stored phone number information. • identificationData.userName •eventData. The structure that contains the event information. 10. Adaptive Authentication sends the Authentify Web Services a script ID as defined with RSA, together with the eventData and confirmation code. The script ID includes the instanceId, identificationData, and eventType. 11. Authentify send the out-of-band SMS to the end user at the selected phone number with the confirmation code. 12. The organization displays a text box to the end user on the web page. 13. The end user enters the confirmation code received in the SMS in the text box on the web page and submits.

80 4: SOAP API with Data on Organization’s Side RSA Adaptive Authentication (Hosted) Programmer’s Guide

Stage V - Authenticate The fifth stage of the out-of-band SMS authentication message flow involves the following steps: 14. The organization sends a Authenticate request to Adaptive Authentication with the following fields: • identificationData.transactionId – credentialDataList.oobSMSData.payload. Contains the token, which is the confirmation code as entered by the user. 15. Adaptive Authentication authenticates the user's confirmation code and returns the Authenticate response with the following fields: • otpAuthResult.payload.callStatus. The authentication status, including: – statusCode. The status code of the Authenticate request. – statusDescription. The status description of the Authenticate request. 16. Based on the Authenticate response, the organization decides whether to allow the user to continue with the logon or transaction.

Updating RSA Adaptive Authentication about User Credentials Status using the Notify Option For organizations that store user authentication credentials on the organization’s side, one option for handling user data status changes is to notify Adaptive Authentication whenever user data changes. With this option, the organization sends a Notify SOAP message informing the system that there has been a change or update in user credentials using the CollectionDetails structure (under CollectionDetailsList). A CollectionDetails structure can be sent for each user with one for each type of authentication method.

Note: The user authentication data is not sent, only information related to the status of the stored credentials is sent.

With this approach, Adaptive Authentication always has the user data status required to make internal logic decisions that involve user credential information. The message flows for authentication and collection are similar to those described in Chapter 3, “SOAP API Use Cases.”

4: SOAP API with Data on Organization’s Side 81

RSA Adaptive Authentication (Hosted) Programmer’s Guide

5 SOAP API and HTML Redirection This chapter discusses the SOAP API and HTML Redirection Integration option.

Message Flow Description The following figure shows how messages flow in a typical Redirection environment. The transaction flow includes four essential steps and is consistent for all flows in the system. This section describes the flow in a general manner that can be applied to all possible use case flows.

Note: All SOAP requests contain the Message and Security headers (and for processors, the Configuration header). All responses contain the Status Header. The administrative elements, such as mandatory headers, are not specified in the following sections on required data elements.

Adaptive User Browser Organization Authentication Web Server

Organization sends Analyze User requests access request to Adaptive Authentication Stage 1: Risk Logon Form assessment based on 1 many parameters and sensors

Adaptive Authentication returns Analyze response including risk score Redirect user to Adaptive Authentication for further 2 authentication 3 (optional, depends on risk)

4 Stage II: Authentication interaction directly between 5 Completing the user and Adaptive Authentication authentication process

Redirect user back 6 to organization

7 Continued interaction with organization

5: SOAP API and HTML Redirection 83 RSA Adaptive Authentication (Hosted) Programmer’s Guide

The flow includes the following steps: 1. The organization sends an Analyze request. The online service application server (organization) sends an Analyze request to Adaptive Authentication. The organization usually sends the Analyze request when the user requests access to a specific page or service. This request contains logon or transaction details and the URL of the organization application's post authentication page. 2. Adaptive Authentication returns an Analyze response including a risk score. The Adaptive Authentication Web Services authenticates the device and behavior, completes a risk assessment, and returns a risk score to the organization application within a SOAP response. If the risk score is high, a redirection URL for stronger authentication is returned. 3. Redirection occurs (if required). If the Adaptive Authentication Web Services recommended that further authentication is required, the online service application server redirects the user to Adaptive Authentication. The redirection can be done using a simple frameset or with an HTML Meta refresh directive. Examples are provided in the following sections. 4. Authentication data is requested from the user (if required). During the authentication step, Adaptive Authentication renders the user interface screens and directs the user through the additional required action (challenge questions or out-of-band phone call, knowledge-based authentication (KBA) is not supported in WEB_REDIRECT mode). Adaptive Authentication handles any other required action, such as making a phone call, synchronizing a web session with the phone session, and so on. All of the Adaptive Authentication screens are organization-branded and use an organization-branded domain name. 5. The user is authenticated. The user performs the authentication procedure, for example, answers challenge questions. The user sends the answers back to Adaptive Authentication to complete the authentication process. 6. The user is redirected back to organization online application with the authentication status. The user is redirected back to the organization application's post-authentication page using the URL that the organization’s application provided with the initial SOAP request. The user’s authentication status is assigned by Adaptive Authentication. 7. The organization verifies the authenticity of the Adaptive Authenticity response. The online service application server (organization) retrieves the relevant user session. The organization verifies the authenticity of the response received from Adaptive Authentication using a simple HMAC hash. If verified successfully, the application server allows the user to access the required page or service.

84 5: SOAP API and HTML Redirection RSA Adaptive Authentication (Hosted) Programmer’s Guide

Similarly, Adaptive Authentication collects authentication data (answers to challenge questions and phone numbers). The organization’s application notifies the Adaptive Authentication Web Services of a new logon. If data collection is needed and safe, the user is redirected to Adaptive Authentication which is responsible for the data collection.

API Components The SOAP API and HTML Redirection is based on the following components: A Web Services API built that was using SOAP messages. Enables the online application to feed the Risk Engine with new events that facilitate better user profiling and to initiate redirections to Adaptive Authentication and back. A redirection protocol. Enables the application to securely redirect the user between the online application, the Adaptive Authentication application, and back. An optional beacon or JavaScript code. Allows online application environments that lack access to the IP address of online users to work around this issue. Redirection Protocol The Adaptive Authentication redirection protocol is designed to securely redirect the user from the online application to Adaptive Authentication, and then back from Adaptive Authentication to the online application. The protocol was designed to achieve the following goals: • Simple to implement - Does not require complex coding patterns or encryption algorithms and can be implemented using facilities that are readily available on all common platforms (Java, VB.Net, C#, and so on). • Non intrusive - Can fit into existing web application architectures. • Reliable - Works reliably in at least 99.9 percent of browsers. • Secure - Preserves data and session integrity, and protects against force-full browsing, reply, and data manipulation attacks.

Authentication - Required Messages This section includes a high-level description of redirection. More detailed explanations for each stage follow.

Stage I - Analyze Message The first stage of redirection includes the following steps: 1. The organization extracts the relevant data for the Risk Engine from the initiation page where the transaction details are entered and submitted. The organization then composes a Web Services Analyze request. The request includes the data required to return to the application, should a redirection occur. The required data elements for this are as follows: • identificationData.userName

5: SOAP API and HTML Redirection 85 RSA Adaptive Authentication (Hosted) Programmer’s Guide

• apiType (in the configuration header) = WEB_REDIRECT • clientReturnData.returnURL – The URL to which the user is redirected when returning to the online application. – This URL is usually the URL of the guarded page. The URL can also be the URL of a dispatcher page that gets the redirect and dispatches it to the actual page. – The URL may include information that assists the online application in resuming the session, if such information is needed.

Note: When redirecting back to the organization, Adaptive Authentication appends to this URL additional parameters with the authentication status and HMAC values.

• clientReturnData.validationMethod. Identifies the validation method to use. The options currently available are SECRET_HMAC_SHA1 and PASSWORD. • clientReturnData.clientSessionID. An optional element that can be set to the current session ID of the application. If set, it is appended to the URL when redirecting back to the application. In the following example, the ABC organization uses the Analyze method for a logon operation. -

xmlns:tns3="http://payload.device.acsp.mcf.csd.rsa.com" xmlns:tns2="http://generic.ws.csd.rsa.com" xmlns:tns7="http://attribute.event.api.csd.rsa.com" xmlns:tns6="http://event.api.csd.rsa.com" xmlns:tns16="http://goid.credential.ws.csd.rsa.com" xmlns:impl="http://ws.csd.rsa.com"

xmlns:tns9="http://account.attribute.event.api.csd.rsa.com"

xmlns:tns8="http://user.attribute.event.api.csd.rsa.com" xmlns:tns19="http://payload.oob.acsp.mcf.csd.rsa.com" xmlns:tns21="http://redirect.ws.csd.rsa.com" xmlns:tns13="http://credential.ws.csd.rsa.com"

xmlns:tns10="http://stock.attribute.event.api.csd.rsa.com"

xmlns:tns11="http://transaction.attribute.event.api.csd.rsa. com"

xmlns:tns14="http://question.credential.ws.csd.rsa.com" xmlns:tns18="http://oob.credential.ws.csd.rsa.com" xmlns:tns17="http://payload.goid.acsp.mcf.csd.rsa.com"

86 5: SOAP API and HTML Redirection RSA Adaptive Authentication (Hosted) Programmer’s Guide

xmlns:tns15="http://payload.challengequestion.acsp.mcf.csd.r sa.com"> - -

- abccompany

- 123.456.78.123

- ayelet

- WEB_REDIRECT ANALYZE 6.5

00000000 CLIENTABC PASSWORD

http://www.abccompany.com/redirect_collect_ example SECRET_HMAC_SHA1

SESSION_SIGNIN

ALL

5: SOAP API and HTML Redirection 87 RSA Adaptive Authentication (Hosted) Programmer’s Guide

2. The Adaptive Authentication Web Services returns an Analyze response with the relevant fields to the initiation page and stores these fields in the application session data store. Subsequently, Adaptive Authentication internally forwards the fields from the initiation page to the guarded page (usually the same page to which it would have been forwarded without the intervention of Adaptive Authentication). The required fields are: • riskResult.triggeredRule.actionCode. Contains the action code for the transaction as defined by the Risk Engine and the organization policy rules. The action code must be stored in the session so the guarded page can act accordingly. If the value of this field is either REDIRECT_CHALLENGE or REDIRECT_COLLECT, a redirection is required. • transactionId. The RSA unique transaction ID. This must be stored in the session data for validation of the authentication status when getting the redirection back from Adaptive Authentication. The following additional fields are optional and appear only if a redirection is required: • serverRedirectData.redirectURL. The Adaptive Authentication URL to which the user is redirected. This must be stored in the session data so the guarded page can redirect the user to that URL. • serverRedirectData.secretKey. A secret key used for HMAC validation. The secret key is provided in BASE64 encoding format and must be BASE64 decoded before being used. This secret key must be stored in the session data for validation of the authentication status when getting the redirection back from Adaptive Authentication. In the following example, the Risk Engine returns an Analyze response indicating that the activity is low risk with a suggested action of collecting authentication credentials. version="1.0" encoding="UTF-8"?>

88 5: SOAP API and HTML Redirection RSA Adaptive Authentication (Hosted) Programmer’s Guide

xmlns:ans1="http://generic.ws.csd.rsa.com" xsi:nil="1" /> 1234567891234567

WEB_REDIRECT

>2353f8772ead193235e2e670f60c445a43f6d601 ANALYZE 1174923992783 6.5

5: SOAP API and HTML Redirection 89 RSA Adaptive Authentication (Hosted) Programmer’s Guide

200

OPTIONAL_COLLECTION

REDIRECT_COLLECT

REDIRECT_COLLECT STRICT abc.esphinx.0100105 sample rule REDIRECT_COLLECT

90 5: SOAP API and HTML Redirection RSA Adaptive Authentication (Hosted) Programmer’s Guide

>http://ww.abccompany.com/redirect_collect_example/

risk_based_authentication/eSAuthDispatch?cy_client_id=abccom pany& ;cy_trx_id=6588947120339930 4pSi5MWyEZ85iW5LSWx9WOGWbN4= enap COLLECT

Note: There are additional fields in the Analyze response that may interest the online application for logging and reporting purposes but are not required for the redirection protocol. In addition, the client may receive errors from the Adaptive Authentication Web Services ranging from time-outs to HTTP errors to applicative errors. The client must be able to handle them appropriately. Error handling is discussed further in the API Reference Guide.

Stage II - Redirection The second stage of redirection includes the following steps: 3. The request has been forwarded to the guarded page. Upon entry to the guarded page, the implemented code checks to see if the actionCode field is either REDIRECT_CHALLENGE or REDIRECT_COLLECT.

Note: Other possible actions, such as STOP_AND_REVIEW or DECLINE, may occur at this stage and must be handled. However, they are not relevant in terms of the redirection protocol.

4. Assuming that the actionCode field includes one of the above-mentioned values, the guarded page now checks to see if the HTTP request contains a parameter called cy_status. At this stage, the parameter should not yet exist. The presence of this parameter indicates that the redirection procedure has already occurred, Adaptive Authentication has already returned to the organization’s online application with a status code, and the application must validate this status code. 5. Once it is determined that a redirection is required and has not yet been completed, the organization web or application server retrieves the Adaptive Authentication redirection URL from the session and redirects the user to that URL using one of the following three methods: • HTTP 30X redirection • HTML meta refresh redirection

5: SOAP API and HTML Redirection 91 RSA Adaptive Authentication (Hosted) Programmer’s Guide

• HTML Frameset with one of the frames pointing to Adaptive Authentication URL The following code example shows a redirection using the HTML meta refresh method.

ABC Org - Authentication

If your browser does not automatically load the authentication page in a few seconds, click here to go to the page.

Stage III - User Authentication The third stage of redirection includes the following steps: 6. The user is interacting with Adaptive Authentication. At the end of the session, the user is redirected back to the original application using the HTML meta-refresh method. 7. The redirection uses the return URL that was supplied in the original Analyze request. Adaptive Authentication appends the following parameters to the return URL: • cy_status. A numeric status code indicating the status of the authentication that was performed by Adaptive Authentication. A value of 20X indicates a success. A value of 30X indicates a failure. For a list of possible values, see the API Reference Guide. •cy_hmac. An HMAC value that allows the application to validate the integrity of the Adaptive Authentication response. This is BASE64-encoded. • sessionId (if provided at the original request). If a sessionId was provided as part of the clientReturnData in the original Analyze request, the same value is appended to the return URL.

92 5: SOAP API and HTML Redirection RSA Adaptive Authentication (Hosted) Programmer’s Guide

Adaptive Authentication uses the HTML meta-refresh method to perform its redirection. The following code example shows an HTML code used for redirecting back to the organization’s web application. ABC Org If your browser does not automatically loads the page in a few seconds, click here to go to the page. Stage IV - Redirection Back and Validation The fourth stage of redirection includes the following steps: 8. The user is redirected back to the organization’s online application to the returnURL field value which is presumably the same as the guarded page. Upon entry to this page, the implementation starts with the same steps as in Stage II: • The implementation checks to see if the actionCode field is either REDIRECT_CHALLENGE or REDIRECT_COLLECT. • If the actionCode is one of the above, the implementation checks if the HTTP request contains a parameter called cy_status. This parameter must be present since it was appended to the returnURL by Adaptive Authentication. From this point forward, the flow is different from that of Stage II. 9. The organization’s online application validates the integrity of the status code from the guarded page as follows: • Extracts the transactionId and secretKey from the session data. • Calculates the HMAC value based on the cy_status from the HTTP request and the transactionId and secretKey from the session. The secretKey value must be BASE64 decoded before using it in the HMAC calculation and the result of the HMAC calculation is BASE64-encoded. • Compares the HMAC value that was just calculated to the one in the HTTP request. If both values are the same, the redirection status is both genuine (because the HMAC value assures this) and tied to the session (because the transactionId and secretKey were retrieved from the session).

5: SOAP API and HTML Redirection 93 RSA Adaptive Authentication (Hosted) Programmer’s Guide

The following code example shows a Java code that validates the HMAC value. //these are the values received from the Adaptive Authentication Server String cy_secret = [taken from the session]; String transactionId = [taken from the session]; String cy_status = [taken from the HTTP request];

//this is the sun built in base64 decoder - sun.misc.BASE64Decoder BASE64Decoder decoder = new BASE64Decoder(); byte[] key = decoder.decodeBuffer( cy_secret );

String algorithm = "HmacSHA1";

//create the key using the sha1 algorithm SecretKeySpec key_spec = new SecretKeySpec ( key, algorithm ); Mac hmac = Mac.getInstance( algorithm );

//initialize the MAC, using the secret key hmac.init( key_spec );

//this is the sun built in base64 encoder - sun.misc.BASE64Encoder BASE64Encoder encoder = new BASE64Encoder();

//concatenate the transaction id and the status byte[] final_string_to_hash = (transactionId + ";" + cy_status).getBytes("UTF8");

//base64 encode the hash result, and use the result for key comparison String final_hmac_to_compare = encoder.encode(hmac.doFinal( final_string_to_hash )); 10. After the status code integrity is validated, the online application examines the status code and, based on its value, acts accordingly, as follows: • If the status code is 20X, indicating a successful authentication, the application continues with normal processing of the guarded page, for example, the processing that would have been done without Adaptive Authentication. • If the status code is not 20X, indicating an error condition, the application responds with an appropriate error page for the user.

94 5: SOAP API and HTML Redirection RSA Adaptive Authentication (Hosted) Programmer’s Guide

6 FI-Defined Authentication Method

Messages Flow Description The following figure shows the message flow in an example of RSA Adaptive Authentication use case when the organization uses its own authentication method.

Organization/ Adaptive Web User Browser Authentication Application Web Server Server

Organization sends Analyze request to Adaptive User requests access Authentication Logon Form 1 Risk assessment based on multiple Adaptive Authentication parameters and returns Analyze response sensors User interaction with including risk score organization authentication process 2 3 Organization Authentication Process

Update risk-based 4 Organization sends Notify authentication with request to Adaptive authentication result Authentication

Status – Success. User continues interaction with organization.

6: FI-Defined Authentication Method 95 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Note: The Remember Me feature is supported for the FI-defined authentication method. When this feature is used, the organization sends the end user’s device linking preference in the same Notify request sent to update Adaptive Authentication with the result of the authentication.

Authentication - Required Messages The authentication flow is as follows: 1. The organization extracts the relevant data for the Risk Engine from the initiation page where the transaction details are entered and submitted. The organization then composes a Web Services Analyze request with the following required data elements: • Message and Security Headers • identificationData.userName • apiType (in the configuration header) = DIRECT_SOAP_API

96 6: FI-Defined Authentication Method RSA Adaptive Authentication (Hosted) Programmer’s Guide

2. The information in the Analyze request is processed by the Risk Engine. Adaptive Authentication returns an Analyze response with the following fields: • riskResult.triggeredRule.actionCode. Contains the action code for the transaction as defined by the Risk Engine and the organization’s policy rules. The action code must be stored in the session so that the guarded page (the page that contains sensitive information and therefore requires authentication to access) can act accordingly. If the value of this field is either REDIRECT_CHALLENGE or REDIRECT_COLLECT, the organization must take action. • transactionId. The unique transaction ID that must be used in all subsequent calls to Adaptive Authentication. 3. The organization is responsible for collection and authentication procedures, as well as logic and the final decision of whether to allow the user to continue to the guarded page. 4. The organization sends a Notify message to Adaptive Authentication with the following data elements: • identificationData.userName • identificationData.transactionId • eventData.eventType = EXTRA_AUTH • authenticationLevel.level. Level of authentication performed. • authenticationLevel.isSuccessful = – true for success – false for fail

6: FI-Defined Authentication Method 97

RSA Adaptive Authentication (Hosted) Programmer’s Guide

7 Integration Option Summary A variety of integration options are described in this document. Different approaches to integration may be more or less appropriate depending on the circumstances. For example, if the organization requires stronger authentication capabilities for logons and transactions, and the customization options of the RSA Adaptive Authentication default templates satisfy the organization’s branding and presentation requirements, the SOAP API and HTML redirection API option enables simpler and faster integration. Alternatively, if the organization requires control of the presentation layer (UI), RSA recommends using the SOAP API option, but using that option requires more code changes in the organization’s web application. Given the RSA Adaptive Authentication WSDL file, the code can be easily rendered. The following table summarizes the integration options and indicates what each application (organization or Adaptive Authentication) is responsible for at each stage.

Risk Authentication Authentication Authentication Authentication Completing Stage Assessment and Collection Credentials Meta Data Logic and the Loop and Decision UI Storage Storage Services

I.SOAP API Adaptive Organization Adaptive Adaptive Adaptive Adaptive Authentication Authentication Authentication Authentication Authentication (implicit)

(Data on Adaptive Organization Organization Adaptive Adaptive Adaptive organization’s Authentication Authentication Authentication Authentication Side) (implicit)

III.SOAP API Adaptive Adaptive Adaptive Adaptive Adaptive Adaptive & HTML Authentication Authentication Authentication Authentication Authentication Authentication Redirection (implicit)

IV. FI-defined Adaptive Organization Organization Organization Organization Adaptive Authenticatio Authentication Authentication n Method (explicit)

The stages are as follows: • Risk Assessment and Decision. For each of the integration options, Adaptive Authentication is responsible for assessing the risk of the user activity such as a logon or transaction. • Authentication User Interface. In the redirection API option, Adaptive Authentication is responsible for redirecting the user to either authentication data collection or to additional authentication when an online activity has been assessed to be high risk. Adaptive Authentication enables customer branding of pages associated with these procedures through the use of simple yet powerful configuration parameters for default templates, in order to blend the authentication and collection processes with the organization regular procedures. In the other integration options, the organization handles all UI-related aspects of the data collection and additional authentication procedures.

7: Integration Option Summary 99 RSA Adaptive Authentication (Hosted) Programmer’s Guide

• Authentication Credentials and Personal Info Storage. The data collected for authentication, such as challenge questions and their answers, or phone numbers for out-of-band phone authentication, may be stored in the Adaptive Authentication database when using: – Redirection API – API Authentication-related data is stored in the organization’s database when using the following integration options: – API – FI-defined Authentication Method • Authentication Metadata Storage. Information about the authentication data can be stored in the organization’s database or in the Adaptive Authentication database. The authentication metadata is only stored in the organization’s database in the FI-defined Authentication Method. • Authentication logic and services. Only in the FI-defined Authentication Method is the authentication logic and services performed by the organization’s application itself. For all other integration options, the authentication logic and services are performed by Adaptive Authentication. • Completing the Loop. This column in the preceding table refers to how Adaptive Authentication is updated with authentication results (implicitly or explicitly). The status of additional authentication is considered as “fail” unless the user successfully completes the additional authentication procedure. Adaptive Authentication is then updated with the “success” result for that user, and may not require additional authentication next time. In all cases, with the exception of when the organization uses its own authentication method, the authentication status is implicitly updated. In the last option (FI-defined Authentication Method) the organization has to explicitly update Adaptive Authentication if the authentication procedure has passed successfully.

100 7: Integration Option Summary RSA Adaptive Authentication (Hosted) Programmer’s Guide

8 International Account Formats The international account number format facilitates the tracking and detection of hijacked fund transfers to mule or unintended payee accounts. In the AccountData Structure, the parameter accountNumberIntlFormat is derived from the internationalAccountFormat structure. This structure contains the selected international format type and the international format of the account number. The following requirements apply to the use of account numbers: • You must translate account numbers into an international format for both the payer and payee accounts. – RSA recommends removing all non-alphanumeric characters within the account number because each organization may have different ways of writing this information. – New customers. RSA recommends implementing the accountNumber field by sending the account number. Note that this field is presented in Case Management as the beneficiary of the payment. For this reason, it must be unhashed. In addition, if you are using the out-of-band phone authentication method, this field is used to describe the account number to the end user.

Note: If you use out-of-band phone authentication, this field is used to describe the account number to the end user.

– Existing customers. Continue to populate the old payee on the payee account number field (eventDataList.eventData.transactionData.otherAccountData.accountNu mber) to maintain the profiles. – If a country changes its standard format, RSA must be notified and preparation must be made for this change. • Use SHA-256 function to hash the account number. For more information, see “Hashing the Account Number” on page 102.

8: International Account Formats 101 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Hashing the Account Number The Java code, sha256.java, shown in the following example, uses the SHA-256 algorithm for hashing. The international format account number must be hashed using this code, and the hashed value is then placed in the accountNumber field of internationalAccountFormat. import com.sun.org.apache.xerces.internal.impl.dv.util.Base64; public String getSHA256(String input) throws Exception { // Create the MessageDigest object MessageDigest hash = MessageDigest.getInstance("SHA-256"); byte[] inputByte = input.getBytes("UTF-8"); // Calculate the hash byte[] digest = hash.digest(inputByte); // Base64-encode it before returning return Base64.encode(digest); }

International Bank Account Number (IBAN) An IBAN is an international standard for identifying bank accounts across national borders. Its primary purpose is to facilitate cross-border inter-bank routing and to avoid routing errors. All banks in Europe, as well as in Israel, Tunisia, Mauritius, Turkey, and Saudi Arabia use account identifiers in the IBAN format. IBAN numbers are formatted with a two-character country code, followed by two checksum digits, and then followed by up to 30 alphanumeric characters that uniquely identify the bank account within that country. The format of these 30 characters, not all of which need to be used, is not standard and is determined by the specific country in which the bank resides. For example, Norway uses only 15 characters in the following format: NOkk BBBB CCCC CCK where BBBB is the bank code, CCCCC is the account number, and K is a checksum digit. Malta uses 31 characters in the following format: MTkk BBBB SSSS SCCC CCCC CCCC CCCC CCC where BBBB is the first part of the Bank Identifier Code, SSSSS is the sort code for the bank, and CCC CCCC CCCC CCCC CCC is the account number.

SWIFT-BIC Before the advent of IBAN numbers, the Society for Worldwide Interbank Financial Telecommunication (SWIFT) created ISO-9362, which is a standard format of Bank Identifier Codes (BIC). It is the unique identification code of a particular bank.

102 8: International Account Formats RSA Adaptive Authentication (Hosted) Programmer’s Guide

The SWIFT code is 8 or 11 characters and consists of the following: • 4 characters - bank code (alpha characters only) • 2 characters - ISO 3166-1 alpha-2 country code (alpha characters only) • 2 characters - location code (alpha, numeric or both) - if the second character is ‘1’, then it denotes a passive participant in the SWIFT network • 3 characters - Branch Code (Number), optional (‘XXX’ for primary office) (alpha, numeric or both) Banks in Australia and New Zealand have not adopted the IBAN format and tend to use Bank State Branch (BSB) codes for domestic transfers and SWIFT format for international use. Banks in the U.S. tend to use ABA routing number (Fedwire) for domestic transfers and SWIFT format for international use. For example, the SWIFT-BIC code - WFBIUS6SLIN is the code of Wells Fargo, Branch Name - Lincoln, Nebraska, in Lincoln, NE, USA, where: • WFBI identifies Wells Fargo. • US is the country code for United States. • LIN is the code for Lincoln. SWIFT codes are used only to identify a bank, and optionally a branch of that bank, but do not contain information about account numbers.

Conversion of Bank Account Formats for Various Countries to International Format To create the unified account format that will be hashed and shared using the eFraudNetwork, use the formats as shown in the following table, according to these guidelines: • For all European countries, use the IBAN format. • For all other countries, use the SWIFT format, followed by the fields, such as ABA, routing code, and account number. • Do not use any separators or add leading zeros to the account number.

Note: If an account number starts with a zero, do not remove it.

Note: The SWIFT code presented in the following table refers to the general bank SWIFT code constructed of 6 Characters (the first 4 characters represent the bank code and the following 2 characters represent the country code). If you have a problem retrieving the required SWIFT code, please contact your RSA representative for assistance. The kk after the two-character ISO country code represents the checksum digits calculated from the rest of the IBAN characters.

8: International Account Formats 103 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Country Type Format and Notes International Format

Albania (28 digits) IBAN format ALkk BBBB BBBB CCCC IBAN CCCC CCCC CCCC B = bank code, C = account number”

Andorra (24 digits) IBAN format ADkk BBBB SSSS CCCC IBAN CCCC CCCC B = bank code, S = sort code, C = account number

Australia BSB 6 digits - 2 for the bank, 1 for the SWIFT code state of the branch, and 3 for the BSB (the first six numbers branch, followed by the account that appear before the number (varies in length account number) depending on the bank) Account number

Austria (20) IBAN format ATkk BBBB BCCC CCCC IBAN CCCC B = bank code, C = account number

Belgium (16) IBAN format ATkk BBBB BCCC CCCC IBAN CCCC B = bank code, C = account number

Bosnia and (20) IBAN format BAkk BBBS SSCC CCCC IBAN Herzegovina CoKK B = bank code, S = sort code, C = account number, K = checksum digits

Bulgaria (22) IBAN format BGkk BBBB SSSS DDCC IBAN CCCC CC B = alphanumeric bank code (first four letters of SWIFT BIC), S = Branch (BAE) number, D = numeric account type, C = alphanumeric account number

Canada Transit/FIF Branch code (normally 5 digits) Swift code and account number (varies in Branch transit number length depending on the bank) Account number

104 8: International Account Formats RSA Adaptive Authentication (Hosted) Programmer’s Guide

Country Type Format and Notes International Format

Channel Bailiwicks of Guernsey and Use either France or UK codes, IBAN Islands Jersey dependant upon the format chosen by the bank.

Croatia (21) IBAN format BBBB BBBC CCCC CCCC C IBAN B = bank code, C = account number

Cyprus (28) IBAN format CYkk BBBS SSSS CCCC IBAN CCCC CCCC CCCC B = bank code, S = sort code, C = account number

Czech (24) IBAN format CZkk BBBB SSSS SSCC CCCC IBAN Republic CCCC B = bank code, S = sort code, C = account number

Denmark (18) IBAN format CZkk BBBB SSSS SSCC CCCC IBAN CCCC B = bank code, S = sort code, C = account number

Estonia (20) IBAN format EEkk BBSS CCCC CCCC IBAN CCCK B = bank code, S = sort code, C = account number, K = checksum digit

Europe For deals going into European banks, the IBAN number is required. SWIFT-BIC code of the bank and account number (varies in length depending on the bank).

Faroe Islands (18) IBAN format FOkk CCCC CCCC CCCC CC IBAN Same as Denmark, except for the country code.

Finland (18) IBAN format FIkk BBBB BBCC CCCC CK IBAN B = bank code, Branch Code (numeric) and account type, C = account number, K = checksum digit of the Finnish account numbering scheme

8: International Account Formats 105 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Country Type Format and Notes International Format

France (27) IBAN format CCCC CKK FRkk BBBB IBAN BGGG GGCC CCCC B = bank code, G = code guichet (branch), C = account number K = clé RIB (key)

Germany (22) IBAN format DEkk BBBB BBBB CCCC IBAN CCCC CC B = sort code (Bankleitzahl or BLZ), C = account number

Gibraltar (23) IBAN format GIkk BBBB CCCC CCCC IBAN CCCC CCC B = first part of BIC, C = account number

Greece 27) IBAN format GRkk BBB BBBB CCCC IBAN CCCC CCCC CCCC K = checksum digits of the Greek account numbering scheme, B = bank code and Branch Code (numeric), C = account number

Greenland (18) IBAN format GLkk BBBB CCCC CCCC CC IBAN Same as Denmark, except for the country code.

Hong Kong Branch code (numeric) SWIFT code (normally 6 digits) and account Branch code (numeric) number (varies in length Account number depending on the bank)

Hungary (28) IBAN format HUkk BBBB BBBC CCCC IBAN CCCC CCCC CCCC B = bank code, C = account number

Iceland (26) IBAN format ISkk BBBB SSCC CCCC IBAN XXXX XXXX XX B = bank code, S = sort code, C = account number, X = holder's national identification number

India SWIFT code, branch code, and SWIFT code account number Branch code (numeric) Account number

106 8: International Account Formats RSA Adaptive Authentication (Hosted) Programmer’s Guide

Country Type Format and Notes International Format

Ireland (22) IBAN format IEkk AAAA BBBB BBCC IBAN CCCC CC The first 4 alphanumeric characters are the beginning of the SWIFT code, followed by a 6-digit sort code (numeric) and an 8-digit account code (numeric).

Isle of Man Use United Kingdom code IBAN

Israel (23) IBAN format ILkk BBBN NNCC CCCC IBAN CCCC CCC B = bank number (3 digits), N = branch number (3 digits), C = account number (13 digits - typically 6 zeroes followed by a 7-digit number).

Note: Some Israeli banks have recently changed client account numbers from 6 to 7 digits.

Italy (27) IBAN format ITkk KAAA AABB BBBC IBAN CCCC CCCC CCC[1] K = checksum char (""CIN""[2], 1 alpha), A = ABI[3] bank code (""codice ABI"", 5 digits), B = Branch Code (numeric) (""CAB""[4], 5 digits), C = account ID (12 alphanumeric).

Japan Branch code (numeric) and SWIFT code account number 3-digit Branch code (numeric) 7-digit account number

Latvia (21) IBAN format LVkk BBBB CCCC CCCC IBAN CCCC C The first 4 digits are the same as the first 4 digits of the SWIFT code of the bank, followed by the 13-digit customer account number (can include both alpha and numeric).

8: International Account Formats 107 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Country Type Format and Notes International Format

Liechtenstein 21) IBAN format CCCC C LIkk BBBB BCCC CCCC IBAN Same as Switzerland,except for the country code.

Lithuania (20) IBAN format LTkk BBBB BCCC CCCC IBAN CCCC B = bank code, C = account number

Luxembourg (20) IBAN format LUkk  IBAN BBC CCCC CCCC CCCC B = bank code, C = account number

Macedonia (19) IBAN format MKkk BBBC CCCC CCCC IBAN CKK B = bank code, C = account number, K = checksum digits

Malta 31) IBAN format MTkk BBBB SSSS SCCC IBAN CCCC CCCC CCCC CCC B = first part of BIC, S = sort code, C = account number

Mauritius (30) IBAN format MUkk BBBB BBSS CCCC IBAN CCCC CCCC CCCC CC B = bank identifier, S = branch identifier, C = account number

Mexico CLABE This is a required field for SWIFT code payment to Mexico. The 18-digit CLABE code CLABE number is the banking standard for Mexico. The order is as follows: bank code (first 3 digits), followed by branch office (3 digits), account number (11 digits) and verification code (1 digit).

Monaco (27) IBAN format MCkk BBBB BGGG GGCC IBAN CCCC CCCC CKK Same as France, except for the country code

Montenegro (22) IBAN format MEkk BBBC CCCC CCCC IBAN CCCC KK kk = IBAN digit, B = bank code, C = account number, KK = checksumgit.

108 8: International Account Formats RSA Adaptive Authentication (Hosted) Programmer’s Guide

Country Type Format and Notes International Format

Netherlands Also may be referred to as NLkk BBBB CCCC CCCC CC IBAN Holland) (18) IBAN format kk = IBAN digit, B = bank code, C = account number

Note: This is not applicable to Aruba, Curacao, Sint Maarten and the Caribbean Netherlands.

New Zealand Bank and branch number Bank (2 digits) and branch (4 SWIFT digits), followed by the account number (7 digits) and suffix (either 2 or 3 digits).

Northern (uses either UK or Republic IBAN Ireland of Ireland code, dependant upon format chosen by bank)

Norway (15) IBAN format NOkk BBBB CCCC CCK IBAN B = bank code (1-3 institution ID, 4-7 branch), C = account number, kk = checksum digits. There are no alpha characters in the code. The single “k” after bank code is the now redundant checksum digit of the former system, preserved in IBAN. K = modulo-11 checksum digit.

Peru SWIFT Branch code (numeric) Account Number

Poland (28) IBAN format PLkk BBBB BBBk CCCC CCCC CCCC CCCC B = bank code, S = sort code, C = account number

Portugal (25) IBAN format The Portuguese BBAN (NIB - IBAN Número de Identificação Bancária) uses the same validation checksum as the IBAN (ISO 7064 mod 97-10 calculation) resulting in the IBAN checksum always being 50.

8: International Account Formats 109 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Country Type Format and Notes International Format

Romania (24) IBAN format ROkk BBBB CCCC CCCC IBAN CCCC CCCC The first 4 alphanumeric characters represent the bank. According to a rule established by the Romanian National Bank, the BBBB code must be the same as the first 4 characters of the bank’s identifier code. The last 16 characters represent the specific bank branch and the account, combined any way the bank decides (typically the first 4 among the 16 identify the branch). Some banks include the ISO 4217 currency identifier somewhere in the account name.

San Marino (27) IBAN format SMkk KAAA AABB BBBC IBAN CCCC CCCC CCC Same as Italy, except for the country code.

Saudi Arabia (24 digits) IBAN format SAkk BBCC CCCC CCCC IBAN CCCC CCCC B = bank code, C = account No2a [country code] 2n [checksum digits] 2n [bank identifier] followed by 18c [the basic account number preceded by zeros, if required]. The issuing start date of the Saudi Arabia IBAN was July 1, 2008 [1].

Serbia (22) IBAN format RSkk BBBC CCCC CCCC IBAN CCCC KK B = bank code, C = account number, K = account checksum digits

Singapore Branch Code (Number) SWIFT (normally 6 digits) and account number (varies in length depending on the bank)

Slovakia (24) IBAN format SKkk BBBB SSSS SSCC CCCC IBAN CCCC

110 8: International Account Formats RSA Adaptive Authentication (Hosted) Programmer’s Guide

Country Type Format and Notes International Format

Slovenia (19) IBAN format SIkk BBBB BCCC CCCC CKK IBAN The first 2 BB digits represent a bank; the next 3 BB digits represent the branch, and the last 2 digits (KK) are the checksum digits. IBAN checksum digits (kk) for Slovenia are 5 and 6.

South Africa Branch Code Branch code (numeric) SWIFT code (normally 6 digits) and account Branch code (numeric) number (varies in length Account number depending on the bank).

Spain (24) IBAN format ESkk BBBB GGGG KKCC IBAN CCCC CCCC B = bank code, G = branch or office number, K = checksum digits, C = account number

Sweden (24) IBAN format SEkk BBBB CCCC CCCC IBAN CCCC CCCC B = bank code C = account number

Switzerland (21) IBAN format CHkk BBBB BCCC CCCC IBAN CCCC C B = bank code C = account number

Tunisia (24) IBAN format TNkk BBBB BCCC CCCC IBAN CCCC CCCC B = bank code C = account number

Turkey (26) IBAN format TRkk BBBB BRCC CCCC IBAN CCCC CCCC CC The total number of alphanumeric characters, including the country code and the checksum digits is 26. The first 5 digits represent the bank. The next alphanumeric character, reserved for future use, is set to zero. The following 16 alphanumeric characters represent the specific bank branch and the account number.

8: International Account Formats 111 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Country Type Format and Notes International Format

United Sort Code SSSS SSCC CCCC CC Format field in API—IBAN Kingdom S = sort code (6 digits, often a Actual format in the account specific branch), C = account number field: number (varies in length • Sort Code depending on the bank) • Account Number (Applies to all of Great Britain, not applicable to any British Overseas Territories. Alternative applications in Northern Ireland, Channel Islands, Isle of Man, Gibraltar. See separate entries for these.)

USA ABA or routing number Normally, 9 digits total: federal Wire Routing Transit reserve routing symbol (5 digits) Number (Fedwire, ABA#): - and bank (4 digits) followed by 9 digits the account number (varies in length depending on the bank).

Sample International Account Formats The following table displays sample international account formats for various countries. For example, for UK - Great Britain, the format is GB-nn-bank abbreviation-sort code-account number. The sort code indicates the branch, normally written as: 12-34-56. The account number is padded with zeros to an 8 digit number. For example, 123456 would be 00123456.

Country Code Length Example

Andorra AD 24 AD1200012030200359100100

Austria AT 20 AT611904300234573201

Belgium BE 16 BE68539007547034

Czech Republic CZ 24 CZ6508000000192000145399

Denmark DK 18 DK5000400440116243

Finland FI 18 FI2112345600000785

France FR 27 FR1420041010050500013M02606

Germany DE 22 DE89370400440532013000

Greece GR 27 GR1601101250000000012300695

112 8: International Account Formats RSA Adaptive Authentication (Hosted) Programmer’s Guide

Country Code Length Example

Hungary HU 28 HU12123456789012345678901234

Iceland IS 26 IS140159260076545510730339

Ireland IE 22 IE29AIBK93115212345678

Italy IT 27 IT60X0542811101000000123456

Latvia LV 21 LV95HABA0055123456789

Liechtenstein LI 21 LI21088100002324013AA

Lithuania LT 20 LT827300010002027432

Luxembourg LU 20 LU280019400644750000

Netherlands NL 18 NL91ABNA0417164300

Norway NO 15 NO9386011117947

Poland PL 28 PL61109010140000071219812874

Portugal PT 25 PT50000201231234567890154

Slovenia SI 19 SI56191000000123438

Spain ES 24 ES9121000418450200051332

Sweden SE 24 SE3550000000054910000003

Switzerland CH 21 CH9300762011623852957

Tunis TN 24 TN5914207207100707129648

8: International Account Formats 113 RSA Adaptive Authentication (Hosted) Programmer’s Guide

Visual Display of International Account Number Structure The following table shows the international account number structure for various countries.

L International Account Number Structure e n Country g Cntry IBAN   Basic Bank Account Number t Code Prefix h

International max 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 34

Andorra 24 A D p p Bank Branch Account Number Code

Belgium 16 B E p p Bank Account Number p p Code

Bulgaria p p

Denmark 18 D K p p Bank Account Number p Code

Germany 22 D E p p Bank Code Account Number

Estonia 20 E E p p Account Number p

Finland 18 F I p p Bank Code Account Number p

France 27 F R p p Bank Code Branch Account Number p p

Gibraltar 23 G I p p Bank Account Number Code

Greece 27 G R p p Bank Branch Account Number Code

Great Britain 22 G B p p Bank Branch Account Number Code

Ireland 22 I E p p Bank Branch Account Number Code

Island 26 I S p p Bank Typ Account Number Identifikationsnr. Code

Italy 27 I T p p p Bank Code Branch Account Number

Latvia 21 L V p p Bank Account Number Code

Lithuania 20 L T p p Bank Code Account Number

Luxemburg 20 L U p p Bank Account Number Code

Malta p p

114 8: International Account Formats RSA Adaptive Authentication (Hosted) Programmer’s Guide

L International Account Number Structure e n Country g Cntry IBAN   Basic Bank Account Number t Code Prefix h

Netherlands 18 N L p p Bank Account Number Code

Norway 15 N O p p Bank Account Number p Code

Austria 20 A T p p Bank Code Account Number

Poland 28 P L p p Bank Code Account Number

Portugal 25 P T p p Bank Branch Account Number p p Code

Romania p p

Sweden 24 S E p p Bank Account Number p Code

Switzerland 21 C H p p Bank Code Account Number

Slovakia 24 S K p p Bank Account part 1 Account part 2 Code

Slovenia 19 S I p p Bank Code Account Number p p

Spain 24 E S p p Bank Branch p p Account Number Code

Czech Republic 24 C Z p p Bank Account part 1 Account part 2 Code

Hungary 28 H U p p Bank Branch p Account Number p Code

Cyprus 28 C Y p p Bank Branch Account Number Code

Additional Resources For additional information regarding international bank account formats, go to the following web sites: • http://wiki.openbravo.com/wiki/Projects/International_Bank_Account_Codes_ Formats/Specifications • http://en.wikipedia.org/wiki/International_Bank_Account_Number • http://www.europebanks.info/ibanguide.htm • http://www.swift.com/ • http://www.tranzfers.com/faq.html

8: International Account Formats 115