WS API ReferenceGuide

RSA Adaptive Authentication
(On-Premise) 7.1
Web Services API Reference Guide
Contact Information
Go to the RSA corporate web site for regional Customer Support telephone and fax numbers: www.rsa.com
Trademarks
RSA, the RSA Logo and EMC are either registered trademarks or trademarks of EMC Corporation in the United States and/or
other countries. All other trademarks used herein are the property of their respective owners. For a list of RSA trademarks, go
to www.rsa.com/legal/trademarks_list.pdf.
License agreement
This software and the associated documentation are proprietary and confidential to EMC, are furnished under license, and
may be used and copied only in accordance with the terms of such license and with the inclusion of the copyright notice
below. This software and the documentation, and any copies thereof, may not be provided or otherwise made available to any
other person.
No title to or ownership of the software or documentation or any intellectual property rights thereto is hereby transferred. Any
unauthorized use or reproduction of this software and the documentation may be subject to civil and/or criminal liability.
This software is subject to change without notice and should not be construed as a commitment by EMC.
Note on encryption technologies
This product may contain encryption technology. Many countries prohibit or restrict the use, import, or export of encryption
technologies, and current use, import, and export regulations should be followed when using, importing or exporting this
product.
Distribution
Use, copying, and distribution of any EMC software described in this publication requires an applicable software license.
EMC believes the information in this publication is accurate as of its publication date. The information is subject to change
without notice.
THE INFORMATION IN THIS PUBLICATION IS PROVIDED "AS IS." EMC CORPORATION MAKES NO
REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS
PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE.
Copyright 2013 EMC Corporation. All Rights Reserved. Published in the USA.
November 2013
RSA Adaptive Authentication (On-Premise) 7.1 Web Services API Reference Guide
Contents
Preface................................................................................................................................. 13
About This Guide.............................................................................................................. 13
RSA Adaptive Authentication (On-Premise) Documentation .......................................... 13
Support and Service .......................................................................................................... 14
Before You Call Customer Support........................................................................... 14
Chapter 1: API Overview .......................................................................................... 17

Introduction to Web Services API .................................................................................... 17
Types of Authentication.................................................................................................... 18
Types of Credentials ......................................................................................................... 19
How Web Services Uses Credentials................................................................................ 20
Adaptive Authentication (On-Premise) Workflow ........................................................... 20
Identifying Invalid Users .................................................................................................. 23
Authentication Attempt Time-Out .................................................................................... 23
Using Web Services .......................................................................................................... 23
Backward Compatibility ............................................................................................ 24
SOAP Requests.......................................................................................................... 25
SOAP Responses ....................................................................................................... 27
SOAP Endpoints ........................................................................................................ 28
Additional Endpoints ................................................................................................. 29
Retrieve WSDL files.................................................................................................. 29
SOAP Authentication ................................................................................................ 31
Receiving SOAP Request and Response Elements ................................................... 31
ISO 8601 Date and Time Format............................................................................... 32
Using Web Services Security for Case Management API ................................................ 32
Chapter 2: Web Services Basic Processes .................................................. 35

Summary of the Basic Workflows .................................................................................... 35
User Enrollment ................................................................................................................ 37
Step 1: Check if the User is Enrolled......................................................................... 38
Step 2: Begin Enrollment........................................................................................... 39
Step 3: User Chooses Challenge Questions (Optional) ............................................. 39
Step 4: User Enters Out-of-Band Information (optional) .......................................... 40
Step 5: User Registers Additional Credentials (optional).......................................... 40
Step 6: Add User Information to the Database .......................................................... 40
Log On with Risk-Based Authentication .......................................................................... 41
Step 1: User Logs On to Your Application................................................................ 42
Step 2: Make a Risk Analysis .................................................................................... 42
Step 3: A Recommended Action is Returned ............................................................ 42
Log on with Positive Device Identification ...................................................................... 43
Step 1: User Logs On to Your System....................................................................... 44
Contents 3
Step 4: Collect the Users Password (Optional) ........................................................ 45

Log on with Verification Process...................................................................................... 45
Step 1: User Logs On to Your System....................................................................... 45
Step 2: Risk Score is Made ........................................................................................ 45
Step 3: Check the Verification Information............................................................... 46
Step 4: Notify the Adaptive Authentication System.................................................. 46
User Transaction Authentication ...................................................................................... 47
Step 1: User Initiates a Transaction ........................................................................... 49
Extra Credentials Workflows............................................................................................ 50
Extra Credentials (General) ....................................................................................... 50
Challenge-Response Credentials Process .................................................................. 53
Out-of-Band Credentials Process............................................................................... 56
User Maintenance ............................................................................................................. 58
The User Initiates a Maintenance Update.................................................................. 60
Retrieve & Update Information ................................................................................. 60
Chapter 3: Web Services API Methods ........................................................... 61

Simplified Overall Workflow ........................................................................................... 62
Adaptive Authentication Web Services Methods ............................................................. 63
Synchronous and Asynchronous Web Services Methods.......................................... 63
Methods and Credentials ........................................................................................... 65
Request and Response Messages for Each Method .......................................................... 66
GenericRequest Message ........................................................................................... 66
GenericResponse Message ........................................................................................ 68
analyze Method ................................................................................................................. 70
AnalyzeRequest Message .......................................................................................... 70
AnalyzeResponse Message........................................................................................ 72
authenticate Method .......................................................................................................... 73
AuthenticateRequest Message ................................................................................... 73
AuthenticateResponse Message................................................................................. 74
challenge Method .............................................................................................................. 74
ChallengeRequest Message ....................................................................................... 75
ChallengeResponse Message ..................................................................................... 76
createUser Method ............................................................................................................ 76
CreateUserRequest Message...................................................................................... 76
CreateUserResponse Message ................................................................................... 77
notify Method.................................................................................................................... 78
NotifyRequest Message ............................................................................................. 78
NotifyResponse Message........................................................................................... 79
queryAuthStatus Method .................................................................................................. 80
queryAuthStatusRequest Message............................................................................. 80
queryAuthStatusResponse Message .......................................................................... 80
query Method ................................................................................................................... 81
4 Contents
QueryRequest Message.............................................................................................. 81
queryResponse Message ............................................................................................ 82
updateUser Method ........................................................................................................... 83
UpdateUserRequest Message .................................................................................... 83
UpdateUserResponse Message .................................................................................. 84
Chapter 4: Web Services API Data Elements .............................................. 85

Priority Levels................................................................................................................... 85
Supported Event Types ..................................................................................................... 85
Common Event Data Elements ......................................................................................... 87
Event-Specific Data Elements .......................................................................................... 93
Chapter 5: Web Services Request Data Structures and Types ..... 105
Data Structures and Methods .......................................................................................... 105
Structures Used in All Methods ...................................................................................... 107
ActionTypeList ........................................................................................................ 107
GenericActionTypeList ........................................................................................... 107
configurationHeader ................................................................................................ 109
deviceRequest .......................................................................................................... 109
identificationData......................................................................................................111
messageHeader .........................................................................................................114
securityHeader ..........................................................................................................116
autoCreateUserFlag..........................................................................................................116
clientReturnData Structure...............................................................................................116
collectionRequest .............................................................................................................117
collectionInitiator......................................................................................................117
collectionReason .......................................................................................................118
orgCredentialList ......................................................................................................118
credentialAuthStatusRequest ...........................................................................................118
credentialChallengeRequest.............................................................................................119
credentialDataList ........................................................................................................... 121
credentialManagementRequestList ................................................................................. 122
deviceManagementRequest ............................................................................................ 123
DeviceActionTypeList Values................................................................................. 123
eventDataList .................................................................................................................. 124
eventData Structure.................................................................................................. 124
AuthenticationLevel Structure ................................................................................. 126
EventType Values.................................................................................................... 126
runRiskType.................................................................................................................... 126
userData Structure........................................................................................................... 127
UserAddress Structure .................................................................................................... 128
UserName Structure........................................................................................................ 128
ClientGenCookie Structure ............................................................................................. 129
MobileDevice Structure .................................................................................................. 129
PhoneData ....................................................................................................................... 135
Contents 5
Chapter 6: Web Services Common Data Structures and Types ... 137
Account Structures.......................................................................................................... 137
AccountData Structure............................................................................................. 137
Amount Structure..................................................................................................... 139
AccountOwnershipType Values .............................................................................. 140
AccountRelationType Values .................................................................................. 140
AccountType............................................................................................................ 140
Credential Structures....................................................................................................... 141
CredentialList Structure ........................................................................................... 141
Credential Structure ................................................................................................. 141
CredentialStatus ....................................................................................................... 141
CredentialType Values ............................................................................................ 142
Device Structures ............................................................................................................ 142
DeviceData Structure ............................................................................................... 142
BindingType Values ................................................................................................ 143
Fact Structures................................................................................................................. 144
Fact List .................................................................................................................. 144
Fact Structure .......................................................................................................... 144
DataType Values............................................................................................................. 144
Stock Structures .............................................................................................................. 145
StockData Structure ................................................................................................. 145
StockTradeData Structures ...................................................................................... 146
Common Values for Stock Structure Data Elements............................................... 146
Transaction Structures..................................................................................................... 148
TransactionData Structures...................................................................................... 148
Values for Transaction Structure Data Elements..................................................... 149
Chapter 7: Web Services Response Data Structures and Types . 153

Data Structures and Methods .......................................................................................... 153
Structures Used in All Methods ...................................................................................... 155
deviceResult............................................................................................................. 155
AuthenticationResult ............................................................................................... 155
identificationData..................................................................................................... 156
UserStatusType Values............................................................................................ 157
messageHeader ........................................................................................................ 158
statusHeader............................................................................................................. 159
browsableGroupNames................................................................................................... 161
collectableCredentialList ................................................................................................ 161
CollectableCredential Structure ............................................................................... 161
credentialAuthResult....................................................................................................... 162
credentialAuthStatusResponse........................................................................................ 163
credentialChallengeList .................................................................................................. 164
credentialChallenge ................................................................................................. 164
credentialManagementResponseList .............................................................................. 165
credentialManagementResponse ............................................................................. 165
6 Contents
deviceManagementResponse .......................................................................................... 165

CallStatus Structure ................................................................................................ 166
StatusCode Values .................................................................................................. 166
StatusDescription Structure ..................................................................................... 166
requiredCredentialList .................................................................................................... 166
RequiredCredential Structure .................................................................................. 167
CredentialType Values ............................................................................................ 167
riskResult ........................................................................................................................ 167
TriggeredRule Structure .......................................................................................... 168
ActionCode Values .................................................................................................. 168
ActionApplyType Values ........................................................................................ 169
serverRedirectData.......................................................................................................... 170
systemCredentials ........................................................................................................... 170
CredentialList Structure ........................................................................................... 170
userCredentials................................................................................................................ 170
Chapter 8: AdminService Basic Processes ............................................... 171

Processes and AdminService Methods ........................................................................... 171
Retrieving User Information Process .............................................................................. 172
User Scenario for Retrieving User Information....................................................... 172
Unlocking a Users Account ........................................................................................... 172
User Scenario for Unlocking User Accounts........................................................... 173
Locking a Users Account............................................................................................... 173
Unenrolling a User .......................................................................................................... 175
User Scenarios for Unenrolling Users ..................................................................... 175
Terminate Authentication Sessions................................................................................. 176
User Scenarios for Terminating Authentication Sessions ....................................... 176
Chapter 9: AdminService API Methods ........................................................ 177

Overview of AdminService API Methods ...................................................................... 177
Request and Response Messages for AdminService Methods ....................................... 179
Generic Requests for All Methods........................................................................... 181
securityHeader ......................................................................................................... 182
Generic Responses for the All Methods .................................................................. 182
deleteUser Method .......................................................................................................... 183
Request /Response for deleteUser Method .............................................................. 183
Sample SOAP .......................................................................................................... 184
getUserChangeHistory Method....................................................................................... 184
Request or Response for getUserChangeHistory Method ....................................... 184
Response Structure .................................................................................................. 185
Sample SOAP .......................................................................................................... 185
resetOpenSessions Method ............................................................................................. 187
Request or Response for resetOpenSessions Method.............................................. 187
Sample Soap ............................................................................................................ 188
Flagged Terminated Authentication Session ........................................................... 188
Contents 7
getUserStatus Method ..................................................................................................... 189

Request or Response for getUserStatus Method...................................................... 190
Sample SOAP .......................................................................................................... 190
setUserStatus Method ..................................................................................................... 191
Request or Response for setUserStatus Method ...................................................... 191
Sample SOAP .......................................................................................................... 192
unlockUser Method......................................................................................................... 192
Request / Response for unlockUser Method............................................................ 192
Request Structure ..................................................................................................... 193
lockUser Method............................................................................................................. 193
Request or Response for lockUser Method ............................................................. 194
Sample SOAP .......................................................................................................... 194
Chapter 10: AdminService API Interfaces ................................................... 197

AdminService Methods................................................................................................... 197
Getting User Change History .......................................................................................... 198
Setting User Status .......................................................................................................... 198
Setting User States ................................................................................................... 201
AdminService Parameters............................................................................................... 202
AdminRequest Elements.......................................................................................... 202
AdminResponse Elements ....................................................................................... 202
UserChangeHistory.................................................................................................. 203
Chapter 11: Case Management Processes................................................. 205

Case Management Processes .......................................................................................... 205
Retrieving Information for Multiple Activities Process ................................................. 206
User Scenario for Retrieving Activities Information ............................................. 207
Retrieving Information for Multiple Cases Process........................................................ 207
User Scenario for Retrieving Cases Information.................................................... 207
Retrieving Information for a Specific Case Process ....................................................... 208
User Scenario for Retrieving Cases Information.................................................... 208
Updating a Specific Activity Process.............................................................................. 208
User Scenarios for Updating a Specific Activity..................................................... 208
Updating a Specific Case Process ................................................................................... 209
User Scenarios for Updating a Specific Case .......................................................... 209
Locking Process Implementation.................................................................................... 210
Chapter 12: Case Management API Methods............................................ 213

Overview of the Case Management API Methods.......................................................... 213
Request and Response Messages for Case Management Methods................................. 214
getActivities Method....................................................................................................... 215
Request for the getActivities Method ...................................................................... 215
Response for the getActivities Method.................................................................... 220
getActivities Sample SOAP Request ....................................................................... 227
getActivities Sample SOAP Response .................................................................... 228
getCases Method ............................................................................................................. 230
8 Contents
Request for the getCases Method ............................................................................ 230

Response for the getCases Method .......................................................................... 232
getCases Sample SOAP Request ............................................................................. 234
getCases Sample SOAP Response........................................................................... 235
getCase Method............................................................................................................... 236
Request for the getCase Method .............................................................................. 236
Response for the getCase Method ........................................................................... 237
getCase Sample SOAP Request............................................................................... 237
getCase Sample SOAP Response ............................................................................ 238
updateActivity Method ................................................................................................... 240
Request for the updateActivity Method................................................................... 240
Response for the updateActivity Method ................................................................ 241
updateActivity Sample SOAP Request.................................................................... 241
updateActivity Sample SOAP Response ................................................................. 241
updateCase Method......................................................................................................... 242
Request for the updateCase Method ........................................................................ 242
Response for the updateCase Method...................................................................... 243
updateCase Sample SOAP Request ......................................................................... 243
updateCase Sample SOAP Response ..................................................................... 243
Error Messages................................................................................................................ 244
Chapter 13: ATM Protection Module............................................................... 247

ATM Request Payload .................................................................................................... 247
Sample Analyze SOAP Request for ATM .............................................................. 258
ATM Analyze Response ................................................................................................. 260
Sample Analyze SOAP Response for ATM ............................................................ 262
ATM Error Messages...................................................................................................... 264
Appendix A: Out-of-Band Phone Authentication Plug-In .................. 267

Overview ......................................................................................................................... 267
Client Managed Data ............................................................................................... 268
Billing Data.............................................................................................................. 268
Authentication Plug-In Architecture for Out-of-Band Phone......................................... 269
Web Services Messaging for Out-of-Band Phone .......................................................... 270
Authentication Plug-In for Out-of-Band Phone Workflow ............................................ 270
Challenge-Response Process ................................................................................... 271
Method Calls for Challenge-Response .................................................................... 271
Activating Your Out-of-Band Phone Credential in Authentication Plug-In Services .... 272
Appendix B: Out-of-Band Phone Authentication Plug-In Web

Services Messages .................................................................................................. 273
Overview ......................................................................................................................... 273
Out-of-Band Phone Message Workflow......................................................................... 275
Out-of-Band Phone Status Codes ................................................................................... 276
Channel Status Codes .............................................................................................. 276
Out-of-Band Phone Response Data Structures and Types.............................................. 278
Contents 9
AuthenticationResult ............................................................................................... 278

Out-of-Band Phone Reason Codes ................................................................................. 280
Analyze Response Message ............................................................................................ 282
Your Application Challenge Request Message .............................................................. 284
Challenge Structure.................................................................................................. 285
Adaptive Authentication Challenge Response Message................................................. 286
Query Authentication Status Request Message .............................................................. 287
Query Authentication Status Response Message............................................................ 288
Phone Token Collection Through Online Session .......................................................... 289
Appendix C: Out-of-Band Phone and Email Credential ..................... 293

Out-of-Band Phone and Email Credential Methods ....................................................... 293
OOB Credential Data Structures..................................................................................... 294
Activity Structures ................................................................................................... 295
OOB Management Structures .................................................................................. 296
User Information Structures..................................................................................... 297
Challenge Structures ................................................................................................ 298
Authentication Structures ........................................................................................ 299
Appendix D: One-Time Password Credential ........................................... 303

One Time Password Credential Methods........................................................................ 303
One-Time Password Credential Data Structures ............................................................ 304
OTP Management Structures................................................................................... 305
Query Structures ...................................................................................................... 310
Appendix E: Knowledge-based Authentication Credential .............. 313

Knowledge-based Authentication Credential Methods .................................................. 313
Knowledge-based Authentication Credential Data Structures........................................ 314
Management Structures ........................................................................................... 315
Appendix F: Out-of-Band SMS Authentication Credential ............... 323

Out-of-Band SMS Authentication Credential Methods.................................................. 323
OOB SMS Authentication Credential Data Structures ................................................... 323
Management Structures ........................................................................................... 324
Appendix G: Challenge Question Credential ............................................ 327

Challenge Question Credential Methods ........................................................................ 327
Challenge Question Credential Data Structures.............................................................. 328
Activity Structures ................................................................................................... 329
Actual Question Information Structures .................................................................. 330
Question Management Structures ............................................................................ 334
10 Contents
Appendix H: Authentication Plug-In Credential ...................................... 335

WSDL/XSD Additions ................................................................................................... 335
Authentication Plug-In Credential Payloads................................................................... 336
Authentication Plug-In Credential Requests and Responses .......................................... 336
Authentication and Analyze Request....................................................................... 336
Authentication and Analyze Response .................................................................... 338
Query, Create User, and Update User Requests ...................................................... 339
Query, Create User, and Update User Responses.................................................... 341
Challenge Request ................................................................................................... 342
Challenge Response ................................................................................................. 344
Get Authentication Status Request .......................................................................... 345
Get Authentication Status Response........................................................................ 347
Appendix I: Authentication Levels................................................................... 351

Appendix J: API Error Messages ...................................................................... 353
Error Messages................................................................................................................ 353
reasonCode & reasonDescription Values ....................................................................... 354
Contents 11
Preface
About This Guide

This guide describes the Web Services, AdminServices, Case Management API, ATM
Protection Module, and Authentication Plug-In Service for RSA Adaptive
Authentication (On-Premise). It describes the overall business workflows, the
methods, and the data elements for each of those methods. This guide is intended for
system administrators, security analysts, database administrators, implementers,
developers, and other trusted personnel. Do not make this guide available to the
general user population.
For more information about RSA Adaptive Authentication (On-Premise) 7.1 , see the
Product Overview Guide.
RSA Adaptive Authentication (On-Premise) Documentation

For more information about RSA Adaptive Authentication (On-Premise), see the
following documentation:
Authentication Plug-In Developers Guide. Describes the Authentication Plug-In
development process that enables external authentication providers to integrate
their products with RSA Adaptive Authentication (On-Premise).
Back Office Users Guide. Provides an overview of the following Back Office
applications: Policy Management, Case Management, Access Management,
Customer Service Administration, and the Report Viewer.
Bait Credentials Setup and Implementation Guide. Describes how to set up and
implement RSA bait credentials, which help provide you with accelerated fraud
detection and prevention capabilities.
Best Practices for Challenge Questions. Describes the best practices related to
challenge questions that RSA has evolved through experience at multiple
deployments.
Installation and Upgrade Guide. Describes detailed procedures on how to install,
upgrade, and configure RSA Adaptive Authentication (On-Premise).
Integration Guide. Describes how to integrate and deploy RSA Adaptive
Authentication (On-Premise).
Operations Guide. Provides information on how to administer and operate
RSA Adaptive Authentication (On-Premise) after upgrade. This guide also
describes how to configure Adaptive Authentication (On-Premise) within the
Configuration Framework.
Performance Guide. Provides information about performance testing and
performance test results for the current release version of Adaptive Authentication
(On-Premise).
Preface 13
Product Overview Guide. Provides a high-level overview of RSA Adaptive

Authentication (On-Premise), including system architecture.
Release Notes. Provides information about what is new and changed in this
release, as well as workarounds for known issues. It also includes the supported
platforms and work environments for platform certifications. The latest version of
the Release Notes is available on RSA SecurCare Online at
https://knowledge.rsasecurity.com.
Security Best Practices Guide. Provides recommendations for configuring your
network and RSA Adaptive Authentication (On-Premise) securely.
Web Services API Reference Guide. Describes RSA Adaptive Authentication
(On-Premise) Web Services API methods and parameters. This guide also
describes how to build your own Web Services clients and applications using Web
Services API to integrate and utilize the capabilities of Adaptive Authentication
(On-Premise).
Whats New. Highlights new features and enhancements in RSA Adaptive
Authentication (On-Premise) 7.1.
Workflows and Processes Guide. Describes the workflows and processes that
allow end users to interact with your system and that allow your system to interact
with RSA Adaptive Authentication (On-Premise).
Support and Service

RSA SecurCare Online https://knowledge.rsasecurity.com
Customer Support Information www.emc.com/support/rsa/index.htm
RSA Solution Gallery https://gallery.emc.com/community/marketplace/rsa?

view=overview
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 Solution Gallery provides information about third-party hardware and
software products that have been certified to work with RSA products. The gallery
includes Secured by RSA Implementation Guides with step-by-step instructions and
other information about interoperation of RSA products with these third-party
products.
Before You Call Customer Support

Make sure that you have direct access to the computer running the Adaptive
Authentication (On-Premise) software.
Please have the following information available when you call:
Your RSA Customer/License ID.
Adaptive Authentication (On-Premise) software version number.
14 Preface
The make and model of the machine on which the problem occurs.
The name and version of the operating system under which the problem occurs.
Preface 15
1 API Overview
Introduction to Web Services API
Types of Authentication
Types of Credentials
How Web Services Uses Credentials
Adaptive Authentication (On-Premise) Workflow
Identifying Invalid Users
Authentication Attempt Time-Out
Using Web Services
Using Web Services Security for Case Management API
This chapter provides an overview of the Web Services API and describes how you
can use Web Services.
Introduction to Web Services API

The Web Services API allows businesses to build applications to integrate with and
utilize the capabilities of the RSA Adaptive Authentication (On Premise) system.
The Web Services API is suitable for applications that benefit from the flexibility of
using an application programming interface (API) (as opposed to a standalone
configuration). The API allows you to build your own Web Services clients (web
pages) and applications that serve your own branded pages to your users, while
providing the Adaptive Authentication (On-Premise) system functionality.
The API provides flexibility in the type of implementation because the application can
reside on a different server and be independent from the Adaptive Authentication (On-
Premise) system.
To perform an action using Web Services, your application passes a message to the
server, in the form of a Simple Object Access Protocol (SOAP) request, specifying a
method and the arguments. The method is invoked and the required actions are
performed. You receive a correlating SOAP response when the method has completed
the actions.
Note: RSA recommends that your organization implement strict data field validation
on input fields before sending to the Web Services API in order to avoid data
manipulation.
1: API Overview 17
The following types of services are described in this chapter:

Adaptive Authentication (On-Premise). Supports your application to allow
user-based activities, such as:
Enrolling in the Adaptive Authentication (On-Premise) system
Changing user account information
Logging on to the existing systems
Performing risk analysis
AdminService. Supports your applications to allow customer support, such as:
Checking on the status of a user. For example, getsUserStatus or
getUserChangeHistory.
Locking a user account
Deleting a user from the Adaptive Authentication (On-Premise) system
Unlocking a user account
For more information, see Chapter 8, AdminService Basic Processes.
Types of Authentication
The Adaptive Authentication (On-Premise) system supports different types of
authentication that fall under the larger umbrella term of Adaptive Authentication.
Logon Authentication. When a user tries to log on to your application, the
Adaptive Authentication (On-Premise) system authenticates the user. Any time a
user who tries to log on proves risky, as determined by your policies, a risk
analysis is performed on the logon to determine how much risk is associated with
that event.
Information is gathered from the users device, such as device information (IP
address) and network information (browser information) to help authenticate
users into your application.
Risk Based Authentication (RBA) can also make use of the positive device
identification where the Adaptive Authentication (On-Premise) system
specifically looks for a device token that serves to identify the users device.
For this type of authentication, the device token is a required piece of information
that could affect the risk score and the recommended actions.
Transaction Authentication. After the user signs into your application, the
Adaptive Authentication (On-Premise) system continues to perform risk analysis.
Any time a user initiates a transaction that might prove risky, as determined by
your policies, a transaction authentication is performed to determine the risk of the
transaction. Information is again collected from the user to authenticate the user.
18 1: API Overview
Types of Credentials
Credentials are the means by which a user is authenticated to the application. In any of
the authentication methods, the Adaptive Authentication (On-Premise) system
requests additional credentials if a user is deemed potentially risky. A user is
considered risky when the risk score and recommended policies dictate that additional
authentication is required from the user. The additional credentials provide added
means of verification of the user identity.
When asked for these extra credentials, the user must provide a second level of
authentication. Secondary level authentication is given in one of the following
credential formats:
A one-time password (OTP)
An extra password
Answers to a set of challenge questions
An identification number
The Adaptive Authentication (On-Premise) system uses this secondary level of
authentication in addition to the user name and password or device information to help
authenticate the user. If the secondary authentication matches, the user is allowed to
access the application.
In version 7.1, Adaptive Authentication (On-Premise) expands the use of credentials
to include additional types. The available credential types are listed in the following
table.
Credential Type Description Credential
Asynchronous A user is presented with a challenge Out-of-band phone

challenge-response or asked to verify a credential, and an Out-of-band email
asynchronous response is received
Out-of-band SMS
from the user.
Challenge-response A credential in which the user Challenge questions

response is associated with that Knowledge-based authentication
challenge. In this case, the challenge
One-time password
is predetermined by the user.
Synchronous or Both synchronous and asynchronous Generic authentication plug-in

asynchronous challenge- challenge-response types are
response supported for the organization
authentication plug-in credential
Verification only A user presents their credentials to Device information

the server to be verified.
1: API Overview 19
How Web Services Uses Credentials

The Web Services treat credentials as a package that is integrated into the Web
Services model to support a specific type of authentication credential. Different
credential types might have an associated credential Web Services Description
Language (WSDL). Adaptive Authentication (On-Premise) provides tightly coupled
credentials that are already incorporated into the Adaptive Authentication Web
Services WSDL:
Challenge Question Credential
Positive Device Identification Credential
OOB Phone Credential
OOB Email Credential
OOB SMS Credential
One-Time Password
Generic Authentication Plug-In
Knowledge-based Authentication
Each credential has its own WSDL schema fragments and payload (actual data)
information in the Adaptive Authentication (On-Premise) system.
Adaptive Authentication (On-Premise) Workflow

This section describes the general workflow of the Adaptive Authentication (On-
Premise) system . You should understand this workflow before trying to understand
each of the separate workflows and business processes that use the Web Services
methods.
1. The user attempts to log on to your online system.
2. Your system identifies the user as a valid or genuine user. True users are marked
as persistent users to Adaptive Authentication. Non-persistent users, user names
that are not valid, are treated as phishers in the Adaptive Authentication (On-
Premise) system.
Your system performs the first layer of authentication by using your current
authentication process, that is, user name or user name and password.
3. For logon authentication only. After identifying the user as a true user, your
application collects information from the user device (device, network, or device
token information). The Adaptive Authentication (On-Premise) system analyzes
the information and makes a determination of the risk of the user by the use of a
risk score.
Based on the risk score and other factors, a recommended policy action is returned
to your application.
If the user is determined to be low risk, the user can proceed to access your
online application.
20 1: API Overview
If the user is determined to be a high risk, the user is asked to enter extra
credentials, for example, answers to challenge questions or a one-time
password sent by an out-of-band (OOB) method. For more information about
credentials, see Types of Credentials on page 19.
If the credentials match, the user can access your online system. The user
has a preset number of attempts to correctly enter their credential
information.
If a match is not made and the user has exceeded the predetermined
number of failed attempts, the user is locked out of the account.
Note: Risk scores do not appear, not even a default starting score, or work
correctly until the Risk Engine task is run regularly for 2-4 months. Until then,
there may be erratic behavior when using the score-based modes. For more
information, see the topics on system health checks in the Installation and Upgrade
Guide.
4. For Transaction Authentication only. The user attempts to execute a

transaction, for example, transferring money, paying bills, or buying stocks.
Your online system sends the transaction to the Adaptive Authentication (On-
Premise) system for review.
The Adaptive Authentication (On-Premise) system analyzes the risk of the
transaction. Based on the risk score and the policies of your organization, one
of the following occurs:
The user is allowed to continue with the transaction.
The user is blocked from doing this particular transaction.
The user is allowed to continue, but the transaction is monitored or sent
for review.
1: API Overview 21
The following figure shows a high-level overview of the decisions made within the
Adaptive Authentication (On-Premise) system.
22 1: API Overview
Identifying Invalid Users

Your system must validate the user logon as valid. If the user is not a valid user, you
can inform the system by setting the userType to NONPERSISTENT. The
NONPERSISTENT userType parameter value helps to identify an invalid user and to
prevent hackers from harvesting valid user names.
The challenge mechanism repeats the same question until the hacker is locked out
after a predefined number of attempts. The default number of attempts is three. You
can reconfigure this parameter in the Back Office Administration Console. For more
information about this parameter, see the chapter Administration Console in the
Back Office Users Guide.
Authentication Attempt Time-Out

A transaction time-out counter starts from the time that a transaction is created. The
transaction is initiated by a challenge action response. If the analyze response is a
challenge, the follow-up Authentication request must be sent, while the session and
transaction processing continue, before the time-out ends.
The authentication transaction time-out period is two minutes by default, with three
attempts, by default, allowed until lockout occurs and the session closes. You can
configure both the time out and the number of allowed attempts.
The transaction time-out counter, which is considered as an authentication attempt
time-out counter, is initialized to zero for each authentication request. Upon time-out,
an authentication time-out error is returned, along with the transaction ID and session
ID. The transaction and session ID parameters must be used in follow-up
authentication attempts until the session time-out or lock-out occurs.
During processing of the Challenge request in Adaptive Authentication (On-Premise),
the time-out is ignored. A time-out is presented only as a response to the follow-up
authentication request.
Using Web Services

Web Services are invoked using SOAP API calls, which allows objects written in any
platform or language to communicate. The information is passed using Extensible
Markup Language (XML) and transported through HTTPS.
Adaptive Authentication (On-Premise) uses a WSDL file to define the available Web
Services, methods, parameters, and the data returned.
1: API Overview 23
Web Services requires:

A client created by your organization hosted by a server that is connected to the
web
An Adaptive Authentication (On-Premise) system implementation using standard
J2EE components
A standard for transmitting data and calls from Web Services to its users
Important: Adaptive Authentication (On-Premise) expects all data to be UTF-8

encoded. Data received in any other encoding is not be interpreted correctly.
Backward Compatibility
The application programming interfaces (APIs) provided by both RSA Adaptive
Authentication (On Premise) 7.0 and 7.1 are different than the API provided by
previous versions of Adaptive Authentication (On-Premise).
If no changes are made to the Adaptive Authentication (On-Premise) API which use
features supported in either RSA Adaptive Authentication (On Premise) 7.0 or 7.1, the
API provided with RSA Adaptive Authentication (On Premise) 7.1 is backward
compatible with the API provided with RSA Adaptive Authentication (On Premise)
6.0.2.1 API including 6.0.2.1 service packs.
For backward compatibilty, the version data element in the Message headers of all
SOAP call requests must be 6.0.
If changes are made which use features supported in either RSA Adaptive
Authentication (On Premise) 7.0 or 7.1, the API provided with RSA Adaptive
Authentication (On Premise) 7.1 is not backward compatible.
If the API is not backward compatible, the version data element in the Message
headers of all SOAP call requests must be 7.0.
Note: The RSA Adaptive Authentication (On Premise) 5.7 Backward Compatibility
API, available in previous versions of Adaptive Authentication (On-Premise), is not
supported in RSA Adaptive Authentication (On Premise) 7.0 and 7.1.
24 1: API Overview
SOAP Requests
A SOAP request is a special XML-based protocol that defines the framework of the
data contained in the request and how to process the data. By default, the Web
Services SOAP request expects a SOAP response, except in the case of an
asynchronous call.
Sample SOAP request
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/

2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://
ws.csd.rsa.com">
<soap:Body>
<tns:analyze>
<tns:request>
<tns:actionTypeList>
<tns:genericActionTypes>SET_USER_STATUS<
/tns:genericActionTypes>
</tns:actionTypeList>
<tns:identificationData>
<tns:userName>user</tns:userName>
<tns:userStatus>VERIFIED</tns:userStatus>
<tns:userType>PERSISTENT</tns:userType>
</tns:identificationData>
<tns:messageHeader>
<tns:apiType>DIRECT_SOAP_API</tns:apiType>
<tns:requestType>ANALYZE</tns:requestType>
<tns:version>7.0</tns:version> -for Backward Compatibility
</tns:messageHeader>
<tns:securityHeader>
<tns:method>PASSWORD</tns:method>
</tns:securityHeader>
1: API Overview 25
<tns:channel xsi:type="tns:ATM">
<tns:timezone>2</tns:timezone>
<tns:atmOwner>FI</tns:atmOwner>
<tns:atmID>1234</tns:atmID>
<tns:locationType>STREET</tns:locationType>
<tns:cardIssueDate>423543</tns:cardIssueDate>
<tns:atmLanguage>ENG</tns:atmLanguage>
<tns:location>
<tns:country>isr</tns:country>
<tns:state>ISR</tns:state>
<tns:city>PARIS</tns:city>
<tns:address>V</tns:address>
<tns:zip>123</tns:zip>
<tns:geoCoordinates>
<tns:longitude>19.7244</tns:longitude>
<tns:latitude>156.0787</tns:latitude>
<tns:altitude>0</tns:altitude>
</tns:geoCoordinates>
</tns:location>
<tns:cardPINChangeDate>123</tns:cardPINChangeDate>
<tns:atmOS>windows</tns:atmOS>
</tns:channel>
<tns:autoCreateUserFlag>true</tns:autoCreateUserFlag>
<tns:eventDataList>
<tns:eventData>
<tns:eventType>WITHDRAW</tns:eventType>
<tns:transactionData>
<tns:amount>
<tns:amount>12</tns:amount>
<tns:amountInUSD>12</tns:amountInUSD>
<tns:currency>NIS</tns:currency>
</tns:amount>
<tns:myAccountData>
<tns:internationalAccountNumber>123<
/tns:internationalAccountNumber>
</tns:myAccountData>
</tns:transactionData>
</tns:eventData>
</tns:eventDataList>
<tns:runRiskType>ALL</tns:runRiskType>
<tns:channelIndicator>ATM</tns:channelIndicator>
</tns:request>
</tns:analyze>
</soap:Body>
</soap:Envelope>
26 1: API Overview
SOAP Responses
All responses are assumed to be in a SOAP envelope.
Sample SOAP response
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<ns1:analyzeResponse xmlns:ns1="http://ws.csd.rsa.com">
<ns1:analyzeReturn xsi:type="ns1:AnalyzeResponse"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ns1:deviceResult>
<ns1:authenticationResult>
<ns1:authStatusCode>FAIL</ns1:authStatusCode>
<ns1:risk>0</ns1:risk>
</ns1:authenticationResult>
<ns1:callStatus>
<ns1:statusCode>SUCCESS</ns1:statusCode>
<ns1:statusDescription/>
</ns1:callStatus>
<ns1:deviceData>
<ns1:bindingType>NONE</ns1:bindingType>
<ns1:deviceTokenCookie>PMV6008tZxkzhRev5ecX3cjXqxDwzMNqbzpDwnyJlaVMabOGBJXy4LuV7wF
MMgUGprPV0t</ns1:deviceTokenCookie>
<ns1:deviceTokenFSO>PMV6008tZxkzhRev5ecX3cjXqxDwzMNqbzpDwnyJlaVMabOGBJXy4LuV7wFM
MgUGprPV0t</ns1:deviceTokenFSO>
</ns1:deviceData>
</ns1:deviceResult>
<ns1:identificationData>
<ns1:delegated>false</ns1:delegated> <ns1:transactionId>9af7-:fd4bb419931:5cba5794-
_TRX</ns1:transactionId>
<ns1:userName>user</ns1:userName>
<ns1:userStatus>VERIFIED</ns1:userStatus>
<ns1:userType>PERSISTENT</ns1:userType>
</ns1:identificationData>
<ns1:messageHeader>
<ns1:apiType>DIRECT_SOAP_API</ns1:apiType>
<ns1:requestType>ANALYZE</ns1:requestType>
<ns1:timeStamp>2012-09-05T07:41:18.775Z</ns1:timeStamp>
<ns1:version>7.0</ns1:version>
</ns1:messageHeader>
1: API Overview 27
<ns1:statusHeader>
<ns1:reasonCode>0</ns1:reasonCode>
<ns1:reasonDescription>Operations were completed
successfully
</ns1:reasonDescription>
<ns1:statusCode>200</ns1:statusCode>
</ns1:statusHeader>
<ns1:riskResult>
<ns1:riskScore>14</ns1:riskScore>
<ns1:riskScoreBand>SCORE_BAND_0</ns1:riskScoreBand>
<ns1:triggeredRule>
<ns1:actionCode>ALLOW</ns1:actionCode>
<ns1:actionName>FALLBACK RULE</ns1:actionName>
<ns1:actionType>STRICT</ns1:actionType>
<ns1:clientFactList/>
<ns1:ruleId>FALLBACK RULE</ns1:ruleId>
<ns1:ruleName>FALLBACK RULE</ns1:ruleName>
</ns1:triggeredRule>
</ns1:riskResult>
</ns1:analyzeReturn>
</ns1:analyzeResponse>
</soapenv:Body>
</soapenv:Envelope>
If an error occurs in the SOAP response, errors are logged and error messages are
returned in the SOAP response. The SOAP response also contains a status parameter
that lets you know if the SOAP request was successfully processed.
Note: For asynchronous Web Services calls, even if you do not receive a SOAP
response, you still receive an HTTP202 response call.
SOAP Endpoints
Adaptive Authentication (On-Premise) provides SOAP endpoints to be used with the
Web Services operations when sending requests. The URL of the endpoint is as
follows:
Adaptive Authentication (On-Premise) endpoint
http://{host}:{port}/AdaptiveAuthentication/services/AdaptiveAuthentication
Asynchronous Adaptive Authentication endpoint
http://{host}:{port}/AdaptiveAuthentication/services/
AsyncAdaptiveAuthentication
Note: After generating the client mode, you must modify for all client-generated
proxies (that is, NET 3.0) to make the AsyncAdaptiveAuthentication WSDL work
correctly.
Change the endpoint of the Async WSDL to: http://{host}:{port}/

AdaptiveAuthentication/services/AsyncAdaptiveAuthentication
28 1: API Overview
Additional Endpoints
There are additional SOAP endpoints used for user administration and case
management. Not all organizations will choose to use these endpoints. The following
are the additional endpoints:
AdminService API endpoint
http://{host}:{port}/AdaptiveAuthenticationAdmin/services/
AdaptiveAuthenticationAdmin
Case Management API endpoint
http://{host}:{port}/casemanagement/services/casemanagement
Retrieve WSDL files

To retrieve the WSDLs for Adaptive Authentication:
1. To obtain the Adaptive Authentication WSDL depending on the value of the
Administration Console parameter, go to:
If the Administration Console parameter Access the Web Services using Logon
Form is False:
http://{host}:{port}/AdaptiveAuthentication/services/
AdaptiveAuthentication?wsdl&username=[caller Id]&password=[caller password]
Form is True:
http://{host}:{port}/AdaptiveAuthentication/services/AdaptiveAuthentication?wsdl
The default value of the parameter is True.
Note: When the parameter is true, you must log on to the Adaptive Authentication
to enter your Web Services credentials.
2. Save the WSDL to your local drive.

3. To obtain the XSD files for each authentication method depending on the value of
the Administration Console parameter, go to:
Form is False:
http://{host}:{port}/AdaptiveAuthentication/services/AdaptiveAuthentication?xsd=[xsd
name].xsd&username=[caller Id]&password=[caller password]
Form is True:
http://{host}:{port}/AdaptiveAuthentication/services/AdaptiveAuthentication?xsd=[xsd
name].xsd
(On-Premise) to enter your Web Services credentials.
1: API Overview 29
4. Save the XSD files to the same directory to which you saved the Adaptive
Authentication WSDL. You must repeat the process for each of the following
XSD files:
ACSP.xsd
ACSPImport.xsd
ACSPInternalImport.xsd
ATM.xsd
RSA_main.xsd
KBA.xsd
OOBGen.xsd
OOBSMS.xsd
OTP.xsd
To retrieve the WSDLs for Adaptive Authentication AdminService API:

1. To obtain the Adaptive Authentication AdminService WSDL depending on the
value of the Administration Console parameter, go to:
Form is False:
AdaptiveAuthenticationAdmin?wsdl&username=[caller Id]& password=[caller
password]
Form is True:
AdaptiveAuthenticationAdmin?wsdl
Admin to enter your Web Services credentials.
2. Save the WSDL to your local drive.
The Location of the WSDLs for Adaptive Authentication Case

Management API:
To generate the client code for Case Management API, use the Case Management API
WSDL and the related XSD files. You can find the files in the following location.
casemanagement.war/WEB-INF/services/rsa-cm-ws-base-1.0.0-SNAPSHOT.jar/META-
INF
Note: When generating the Web Services client, if you are using Axis version 2, RSA
recommends that you use the XML Beans binding method.
30 1: API Overview
SOAP Authentication
Starting with release 6.0, Adaptive Authentication (On-Premise) provides a measure
of security for Web Services by providing a user name and password security scheme
(see securityHeader on page 116), whereby the Adaptive Authentication (On-
Premise) system authenticates the SOAP request as coming from a valid server within
your application.
Your organization is responsible for securing the channel end points and implementing
access protection to your servers.
Receiving SOAP Request and Response Elements

The following is an overview of how request and response elements are sent and
received.
1. Your Web Services client sends a message containing a request element for a
particular method.
The method is invoked.
2. The response element is returned to the Adaptive Authentication (On-Premise)
database or integration server and to your application with the results of the
method invoked.
3. If any errors occur during any step in this process, the error handling systems are
invoked, and error status messages are logged. The following types of errors are
logged:
Invalid or malformed requeststhe information passed to the Adaptive
Authentication (On-Premise) system is not usable. These errors are caught by
Axis version 2 and a SOAP fault is returned.
Errors caught by Adaptive Authentication (On-Premise)These errors are
caught by the SOAP stack and returned with a status code and description in a
well-formed response.
For a list of error messages, see Appendix J, API Error Messages.
Note: Both Adaptive Authentication (On-Premise) and Web Services use Axis version
2.
1: API Overview 31
ISO 8601 Date and Time Format

In many cases, you must enter a value in the ISO 8601 date and time format. This
format is a complete date, plus hours, minutes, and seconds:
Example
YYYY-MM-DDThh:mm:ssTZD (for example, 1997-07-16T19:20:30+01:00)
or
YYYYMMDDThhmmssTZD (for example, 19970716T192030+01:00)
where
YYYY = four-digit year
MM = two digits for the month (e.g. 01=January)
DD = two digits for the day of the month (01 through 31)
hh = two digits for the hour (00 through 23)
Note: am and pm are NOT allowed.
mm = two digits for the minute (00 through 59)
ss = two digits for the second (00 through 59)
TZD = time zone designator (Z or +hh:mm or -hh:mm)
The profile defines two ways of handling time zone offsets:
Times are expressed in UTC (Coordinated Universal Time) with the UTC
designator, Z.
Times are expressed in local time, together with a time zone offset in
hours and minutes.
A time zone offset of +hh:mm indicates that the date and time use a local
time zone that is hh hours and mm minutes ahead of UTC. A time zone
offset of -hh:mm indicates that the date and time use a local time zone that
is hh hours and mm minutes behind UTC.
Example
1994-11-05T08:15:30-05:00 corresponds to November 5, 1994, 8:15:30 am, US Eastern
Standard Time.
1994-11-05T13:15:30Z corresponds to the same instant.
Using Web Services Security for Case Management API

Authentication and authorization is required for all users issuing Case Management
API SOAP calls. Case Management API provides the ability to use Web Services
Security (WS-Security) for authentication purposes. WS-Security allows the
communication of various security token formats such as user identification and
password credentials.
32 1: API Overview
Authorization is accomplished by assigning the users to at least one of two specific

roles defined to grant access to the Case Management API service:
CMAPIExtract, for selecting and viewing activities (events)
CMAPIUpdate, for selecting and viewing activities, and updating actions
These roles must be defined in Access Management or in the external identity store
that you are using to manage your users. For more information about managing these
roles, see the section on role management in the chapter Managing Access to the
Back Office Applications in the Back Office Users Guide.
Implementing the Web Services Security SOAP Header

The Case Management API service requires you to add a security header to each
SOAP call for WS-Security purposes. WS-Security requires a specific format for the
SOAP header. The required parameters are:
wsse:userName
wsse:Password
These parameters and their values are the users credentials passed to the Case
Management API service for authentication and authorization purposes. If you do not
follow this format, the authentication process rejects the SOAP call.
After the credentials are verified, the rest of the SOAP call is processed accordingly. If
the authentication or the authorization fails, the SOAP call receives a SOAP fault. As
a result, the user is denied access to the Case Management API service.
For more information on case management, see the chapter Managing Cases in RSA
Adaptive Authentication (On Premise) in the Back Office Users Guide.
Example
The following example shows the required format for the security SOAP header:
1: API Overview 33
<soapenv:Header>
<wsse:Security soapenv:mustUnderstand="1"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/
oasis-200401-wss-wssecurity-secext-1.0.xsd">
<wsse:UsernameToken wsu:Id="UsernameToken-13"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/
oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsse:Username>Alice</wsse:Username>
<wsse:Password
Type="http://docs.oasis-open.org/wss/2004/01/
oasis-200401-wss-username-token-profile-1.0#PasswordText"
>pswAlice<
/wsse:Password>
<wsse:Nonce EncodingType="http://docs.oasis-open.org/wss/2004/01/
oasis-200401-wss-soap-message-security-1.0#Base64Binary"
>bbl2YNeDtZa+ntclg3P3TA==<
/wsse:Nonce>
<wsu:Created>2012-01-31T10:42:01.391Z</wsu:Created>
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>
34 1: API Overview
2 Web Services Basic Processes

Summary of the Basic Workflows
User Enrollment
Log On with Risk-Based Authentication
Log on with Positive Device Identification
Log on with Verification Process
User Transaction Authentication
Extra Credentials Workflows
User Maintenance
This chapter provides an overview of some of the basic application business processes
using the Web Services methods and functionality.
Adaptive Authentication Web Services do not change or modify your application.
There are multiple methods for performing many of the tasks and processes listed
here. However, there are some preferred business processes that optimize the use of
the Adaptive Authentication system.
Note: The business processes in this chapter are provided as examples. Consult with
your RSA Implementation Manager to fine-tune the processes for your specific
implementation.
Summary of the Basic Workflows

Each of these workflows corresponds to several Web Services methods. This chapter
elaborates on how these basic workflows interact between the user, your online
system, and the RSA Adaptive Authentication (On Premise) system.
2: Web Services Basic Processes 35

The following table provides a description and lists the Web Services methods used
for each workflow.
Workflow Description Methods Used
User Enrollment This process enrolls a validated user into the query or analyze
Adaptive Authentication system. createUser
updateUser
Logon with Risk-Based This process authenticates a user using network and analyze
Authentication device information, optionally, also positive device notify
information. Extra Credentials process
If extra credentials are required to authenticate a
user, the Extra Credentials sub-process is invoked.
Logon with Positive This process authenticates a user using network and analyze
Device Identification device information, as well as positive device notify
Only information. Extra Credentials process
If extra credentials are required to authenticate a
user, the Extra Credentials sub-process is invoked.
Transaction This process performs a risk analysis on the analyze

Authentication transaction of an already authenticated user. The notify
user might have to provide extra credentials in Logon process
order for the transaction to be approved.
Extra Credentials process
This process uses the Extra Credentials subprocess
to authenticate extra credentials.
Extra Credentials This process is a subprocess for Logon and risk analyze
analysis processes. challenge
For this subprocess, the user is asked for extra authenticate
credentials to allow the user access to your online notify
system.
queryAuthStatus
Extra credentials include:
Answering challenge questions
Voice out-of-band authentication
Email out-of-band authentication
SMS out-of-band authentication
Generic Authentication Plug-In
Knowledge-based authentication
User Maintenance This process allows a user to change their existing query
information or add more information to their user updateUser
profile.
36 2: Web Services Basic Processes

User Enrollment
The User Enrollment process registers a new user in the Adaptive Authentication
system. You can allow the new user to choose several different enrollment options
(such as challenge questions, OOB information, or other credentials).
The application must identify the user as a valid user before invoking the createUser
method. The following are the steps and methods used in this business process:
Step 1: Check if the User is Enrolled
Step 2: Begin Enrollment
Step 3: User Chooses Challenge Questions (Optional)
Step 4: User Enters Out-of-Band Information (optional)
Step 5: User Registers Additional Credentials (optional)
Step 6: Add User Information to the Database
The following figure shows the seven steps for the user enrollment process. Each step
requires the issuing of a request and response for a SOAP method. The numbering of
the request and response messages are noted in the explanation of each step by the
number of the request and response in the figure.
For example, in step 1c, request 1 in the figure is denoted as request message (1).
Likewise, in step 1d, response 1 in the figure is denoted as response message (1).

Step 1: Check if the User is Enrolled

To determine if a user is enrolled in the Adaptive Authentication system, the following
options exist:
Your application keeps track of user enrollment.
The Adaptive Authentication system keeps track of user enrollment.
The method you use determines which method begins the workflow. During the check
for enrollment, the following occurs:
a. The user logs on to your application.
b. Your system identifies the user and collects any device information from the
user device.
c. Your system sends an analyze request message (1) to the Adaptive
Authentication system.
d. The Adaptive Authentication system sends a response message (1) indicating
whether the user is enrolled.

If the user is not enrolled, the method returns userStatus =

NOTENROLLED or DELETED.
If the user is enrolled, this method returns a risk analysis on the analyze
response message and the userStatus = UNVERIFIED, VERIFIED, or
UNLOCKED.
Step 2: Begin Enrollment

When user enrollment begins, the following occurs:
a. Your system determines whether or not to run a risk analysis on the users
enrollment.
b. Your system sends a request message (2) to the createUser method, to create a
new record in the database.
You can request the Adaptive Authentication system to perform a risk analysis
on the enrollment by setting the risk analysis flag (runRiskType = ALL).
c. The createUser method returns a response message (2) indicating the
following:
The database record has been created for the user if the risk analysis
allows for enrollment.
The risk analysis on user enrollment, if requested. If the policy action
resulting by the risk analysis for enrollment is DENY, the record is not
created and control is passed back to your application. At this point, your
own policies should dictate the next steps for the type of user.
d. Your application displays enrollment pages to the user, in addition to whatever
options you allow the user to choose, challenge questions or out-of-band
information.
Note: You may send the Adaptive Authentication system additional information about
the user, such as address, account information, or any other information that you feel
is necessary.
Step 3: User Chooses Challenge Questions (Optional)

You can allow the user to browse through different challenge questions and provide
answers. This procedure uses the query method to retrieve the information from the
Adaptive Authentication database.
a. Your system sends a request (3) to the query method to retrieve the challenge
questions from which the user can choose.
b. The Adaptive Authentication system returns a response (3) with the array of
challenge questions.
c. Your system collects the users answers.
d. Your system performs data validation on the users answers to the challenge
questions to ensure that no invalid data is being passed.

e. (Optional) After the user has chosen their challenge questions and answers,
you can immediately commit this information to the database by sending a
request (A) to the updateUser method. The updateUser method also activates
the users credential.
Note: RSA recommends that you update the user information immediately.
Step 4: User Enters Out-of-Band Information (optional)

In this step of the process:
a. Your system presents additional pages to the user in order to obtain contact
information, such as a phone number, for out-of-band (OOB) authentication.
b. Your system should perform data validation on the user information to ensure
that no invalid data is passed.
c. (Optional) After the user has submitted their OOB contact information, you
can immediately commit this information to the database by sending a request
message (A) to the updateUser method.
Step 5: User Registers Additional Credentials (optional)

a. Your system can present additional pages to the user in order to register
additional credentials.
b. Your system should perform data validation on the user credential information
to ensure that no invalid data is passed.
c. (Optional) After the user has submitted their additional credential
information, you can immediately commit this information to the database by
sending a request message (A) to the updateUser method.
Step 6: Add User Information to the Database

a. If you have not already committed the user enrollment information to the
database, the collected session information is committed by submitting a
request message (6) to the updateUser method.
b. Set the userStatus to VERIFIED, if the user has supplied enough information
during the enrollment process. Setting the user status to VERIFIED confirms
user enrollment.
If you are using Positive Device Identification, which uses tokens or Flash Shared
Objects, you must bind the user device at this step. You can allow the user to
determine the label for the user device, for example, work, home, or other. For more
information about binding the user device, see the Integration Guide.

Log On with Risk-Based Authentication

This section describes a scenario in which a user who is enrolled in the Adaptive
Authentication system attempts to log on to your online application.
The steps in this process are:
Step 1: User Logs On to Your Application
Step 2: Make a Risk Analysis
Step 3: A Recommended Action is Returned
The following figure shows the three steps for the logon process with risk-based
authentication. Each step requires the issuing of a request and response for a SOAP
method. The numbering of the request and response messages are noted in the
explanation of each step by the number of the request and response in the figure.
For example, in step 2a, request 1 in the figure is denoted as request message (1).
Likewise, in step 2b, response 1 in the figure is denoted as response message (1).

Step 1: User Logs On to Your Application

a. The user attempts to log on to your online application.
b. Your system identifies the user as valid either through the user name or the
user name and password. (Optional) The users password can be collected
after RBA.)
c. Your system collects:
device and network information from the users device
(Optional) the users device token

a. Your system sends a request message (1) to the analyze method with a
runRiskType set to ALL or RISK_ONLY.
b. The analyze method determines if the user is enrolled, and, if so, the risk score
for the Logon Process.
It returns a response message (1) with the recommended action policy.

There are several polices that might be recommended by the Adaptive Authentication
system based on the Risk Score. This information is returned in the response message
(1/2). The figure in Log on with Positive Device Identification on page 43 shows
only a small subset of the actions that are returned; the complete list is as follows:
ALLOWIf the risk score is sufficiently low, the analyze method might indicate
that the user should be allowed to continue their transactions (response message
1).
CHALLENGEIf the user is deemed a potential risk or if you need to collect
information (response message 1b). For more information, see Extra Credentials
Workflows on page 50.
DENYIf the risk score is sufficiently high, the analyze method might
recommend that the user be denied any access to the account (response message
1c). The user is not locked out of the account, but should be denied access for that
specific request.
NONENo recommendation.
REVIEWThe Adaptive Authentication system recommends the transaction,
but flags for a later review (response message 1d).

Log on with Positive Device Identification

The following section describes a scenario where the user is already enrolled in the
Adaptive Authentication system and the user is authenticated into your application
through positive device identification (the use of information from the users device).
In this process, the collection of device information is transparent to the user.
If the user is determined to be risky, the Extra Credentials process is initiated by the
Adaptive Authentication system. For more information, see Extra Credentials
Workflows on page 50.
The steps and methods used in this process are:
Step 1: User Logs On to Your System
Step 4: Collect the Users Password (Optional)
The following figure shows the four steps for the logon process with positive device
identification. Each step requires the issuing of a request and response for a SOAP
method. The numbering of the request and response messages are noted in the
explanation of each step by the number of the request and response in the figure.
Likewise, in step 2b, responses 1a,1b,1c, and 1d in the figure are denoted as response
message (1a/1b/1c/1d).


a. The user attempts to log on to your online system.
b. Your system identifies the user as valid through the user name.
c. Your system collects the device and network information from the users
device and the users device token.

a. Your system sends a request message (1) to the analyze method with the
information you collected.
b. The analyze method determines if the user is enrolled, and, if so, the risk score
for the logon process. It returns a response message (1a/1b/1c/1d) with the
recommended action policy.


system based on the risk score. This information is returned in the response message.
The figure in the Log on with Verification Process section on page 45 shows only a
small subset of the actions that are returned; the complete list is as follows:
ALLOWIf the risk score is sufficiently low, the analyze method might return a
response message (1a) to your application indicating that the user should be
allowed to continue their transactions.
CHALLENGEIf the user is deemed a potential risk or you need to collect
information. For more information, see Extra Credentials Workflows on page 50.
DENYIf the risk score is sufficiently high, the analyze method might simply
1b). The user is not locked out of the account, but should be denied access from
that specific user device.
REVIEWThe system allows the transaction, but flags for a later review
(response message 1c).
Step 4: Collect the Users Password (Optional)

You can opt to collect the users password information after the users personalized
image is displayed. The Adaptive Authentication system does not collect the users
password information. Your application should be responsible for collecting and
authenticating the users password.
Log on with Verification Process

This section describes the process where the user uses a verification identification
(such as challenge questions) as a secondary form of authentication.
Step 2: Risk Score is Made
Step 3: Check the Verification Information

As Step 1 of this process:
a. The user attempts to log on to your online system.
b. Your system validates the user either through the user name or the user name
and password.
c. Your system collects the device and network information from the users
device and the users device token (cookie and/or FSO).
Step 2: Risk Score is Made

As Step 2 of this process:

a. Your system sends a request message to the analyze method.

The analyze method determines if the user is enrolled, and, if so, the risk score
for the logon process.
b. The analyze method returns a response message informing your system that
the information needs to be collected.
c. The user enters their verification information.
(Optional) If the user did not enter their verification information, your policies
can dictate whether to allow the use of fallback credentials.
If your policies allow for fallback credentials, you can opt to use the Extra
Credentials process. See Extra Credentials Workflows on page 50.
If your policies do not allow for fallback credentials, then the user is
denied access to your organization if they do not have their verification
information.
d. Your system should perform a data validation on the information entered by
the user.
e. Your system sends a request message to the authenticate method to verify the
token information.
f. Based on the risk score, a recommended action is taken based on the policies
created by your organization, and a response message is returned to your
application.
Step 3: Check the Verification Information

system based on the risk score. This information is returned in the response message .
The figure in the Log on with Verification Process section on page 45 shows only a
small subset of the actions that are returned; the complete list is as follows:
ALLOWIf the risk score is sufficiently low, the authenticate method might
return a response message to your system indicating that the user should be
allowed to continue their transactions.
CHALLENGE/COLLECTIONIf the user is deemed a potential risk or if you
simply need to collect information. See Extra Credentials Workflows on page 50.
recommend that the user be denied any access to the account response message.
The user is not locked out of the account, but is denied access from that specific
user device.
REVIEWAllow the transaction, but flag for a later review.
After you have implemented the suggested action, you should send a notify request
about the final actions you took with the user.
Step 4: Notify the Adaptive Authentication System

After you have implemented the suggested action, you should send a notify request
about the final actions you took with the user.

If you determine the validity of the users password, you need to send a request
message to the notify method. By notifying the Adaptive Authentication system,
this information can be stored and used for further authentication at a later date.
If you allow or deny the user access to your online system, you should inform the
Adaptive Authentication system of your final action by sending a request message
to the notify method.
Note: No response message is returned with the notify method.
User Transaction Authentication

Transaction Authentication is the process whereby a user (who has successfully
passed the logon process) initiates a certain transaction (i.e. transferring money to an
outside account or setting up an unknown bill payee) that triggers an additional risk
analysis step.
As an alternative to this process, Transaction Monitoring can be used instead. This
process is similar to Transaction Authentication except that no recommended action is
sent to your application; instead it is logged in the Adaptive Authentication database
and high risk transactions can be sent to the Adaptive Authentication Case
Management application for further review by your security. This method is not
shown in this document.
The steps of this process are:
Step 1: User Initiates a Transaction
The following figure shows this process. This process uses the Extra Credentials
process, if necessary. See Extra Credentials Workflows on page 50.
The following figure shows the three steps for the transaction authentication process.
Each step requires the issuing of a request and response for a SOAP method. The
numbering of the request and response messages are noted in the explanation of each
step by the number of the request and response in the figure.

For example, in step 2, request 1 in the figure is denoted as request message (1).
Likewise, in step 3, response 1a in the figure is denoted as response message (1a).

Step 1: User Initiates a Transaction

It is assumed that a user has already successfully signed into your application prior to
initiating a transaction. At this step of the process:
a. The user initiates a transaction that requires an analysis:
Add Payee
Deposit / Payment
Change users account information (phone, address, challenge questions,
password)
A specific type of transaction as defined by your organization
b. Your system submits a request message (1) to the analyze method to
determine what credentials, if any, are required from the user. It should also
send the device information from the users device.

a. Your system sends a request message (1) to the analyze method with the
information you collected.
b. The analyze method determines if the transaction is potentially risky and if the
risk score is sufficiently low.

system based on the risk score. This information is returned in the response message
(1a). The figure in Log on with Verification Process on page 45 shows only a small
subset of the actions that are returned; the complete list is as follows:
ALLOWIf the risk score is sufficiently low, the analyze method might return a
response message to your application indicating that the user should be allowed to
continue their transactions.
CHALLENGEIf the user is determined to be a potential risk or if you simply
need to collect information. See Extra Credentials Workflows on page 50.
1b). The user is not locked out of the account, but should be denied access from
that specific user device.
REVIEWAllow the transaction, but flag for a later review.

Extra Credentials Workflows

The Extra Credentials Workflows are a subset of the specific extra credentials
workflows that can be initiated by your application. This process can be used in
conjunction with the following:
All logon processes
Transaction authentication process
There are different credential types, which have their own specific business processes.
For more information about credentials, see Types of Credentialson page 19. The
specific credential processes include:
Credential Process Description
Using Challenge Questions The user is asked to correctly respond to their pre-chosen challenge
questions.
See Challenge-Response Credentials Process on page 53.
Using Out-of-band Phone Credentials The user receives a one-time password (OTP) via their phone. The user
enters the OTP into field in the web page.
See Out-of-Band Credentials Process on page 56.
Using Out-of-band Email Credentials The user is receives a one-time password via email message. The user
enters the OTP into field in the web page.
Using Out-of-band SMS Credentials The user is receives a one-time password via an SMS. The user enters the
OTP into field in the web page.
Using Generic Authentication Plug-In See Appendix H, Authentication Plug-In Credential

credentials
Using Knowledge-based Authentication See Appendix E, Knowledge-based Authentication Credential

credentials
Extra Credentials (General)

This section provides an overview of the generic Extra Credentials process.
Subsequent sections detail the specific processes for each of the credential types.
Step 1: The User Initiates a Transaction
Step 2: The System Determines the Need for Extra Credentials
Step 3: Collect the Users Credential Information/Answer
Step 4: Validate the Users Information/Answer

The following figure shows the four steps for the Extra Credentials process. The
figure shows all of the different credential processes.

The user initiates a transaction that requires an analysis (either a logon or a
transaction).
a. Your system submits a request message (1) to the Adaptive Authentication
system for a risk analysis to the analyze method.
b. The analyze method returns a response message (1) with the suggested action.

Step 2: The System Determines the Need for Extra Credentials

The analyze method determines the risk score and the corresponding recommend
action. For this process, the analyze method returns a response message (1) indicating
that extra credentials are required. As part of the response message (1), the analyze
method returns the type of credentials that you need to retrieve from the user. Each
credential type has a slightly different process.
The Adaptive Authentication system might ask for any of the following credential
information from the user:
challenge questionsyour application needs to submit a request message (2) to
the challenge method in order to retrieve the challenge questions to be presented
to the user.
additional informationyour application retrieves additional information from
the user, such as:
Device Information
Network Information
one-time passwordyour application needs to submit a request message (2) to
the challenge method in order to send an out-of-band message be sent to the user
via phone.
Note: (For Logon) The user must successfully pass the challenge in order to re-bind
their device. Otherwise, they will be challenged again the next time they attempt to log
on to your application.
Step 3: Collect the Users Credential Information/Answer

After it has been determined that the user needs to be challenged:
a. The Adaptive Authentication system informs you what credential needs to be
collected.
b. Collect the extra credentials information from the user.
c. Perform a data validation on the information entered by the user.
d. Send a request message (3) to the authenticate method to see if the user-
provided answer matches the information in the Adaptive Authentication
system.
Step 4: Validate the Users Information/Answer

After you have collected the users information and answers, you need to validate the
users information and answers. The Adaptive Authentication system checks to see if
the answers match.
If the credential is OOB phone, your application sends a request message to the
method, queryAuthStatus, in order to check the status of the OOB phone call (i.e.
if the phone number is busy or the user does not answer).
For more information, see Out-of-Band Credentials Process on page 56.
If you are submitting any other credentials, then your application checks with the

Adaptive Authentication system to see if the answer matches (through the

authenticate method).
If the users answer does not match, the Adaptive Authentication system informs you.
A user has a pre-set number of attempts to answer correctly before they are locked out
of the Adaptive Authentication system.
Note: A failed credential can result in a transaction being marked for review and sends
it to the Case Management application, regardless of whether a user is allowed to
continue or is denied the transaction. Your policies dictate which transactions are
marked for review.
Challenge-Response Credentials Process

In this process, the user is asked to answer the challenge questions that they chose
during enrollment. For this workflow, it is assumed that the Adaptive Authentication
system maintains the users challenge questions and answers in the Core database.
This workflow changes slightly if your application maintains its own challenge
mechanism (not shown in this document).
Step 2: The System Determines the Need for Challenge Questions
Step 3: Retrieve and Check the Challenge Answers
Step 4: Follow the Recommended Action
The following figure shows the four steps for the Challenge-Response Credentials
process. The figure shows all of the different credential processes.


The user initiates a transaction that requires an analysis (either a logon or a risk
analysis).
a. Your system submits a request message (1) to the Adaptive Authentication
b. The analyze method returns a response message (1) with the suggested action.
Step 2: The System Determines the Need for Challenge Questions

The analyze method determines the risk score and the corresponding. For this process,
the analyze method returns a response message (1) indicating that the user needs to
answer challenge questions.
Step 3: Retrieve and Check the Challenge Answers

After it has been determined that the user needs to be challenged with questions:
a. Your system sends a request message (2) to the challenge method to retrieve
the users challenge questions and display them to the user.

b. Collect the answers that the user enters in regards to their challenge questions,
and perform a data validation on the entered answers.
c. Send a request message (3) to the authenticate method to see if the answer
matches.

When the Adaptive Authentication system checks the answer, it checks the following:
does the answer match?
if not, has the user exceeded the preset number of attempts to answer correctly?
The Adaptive Authentication system then makes a recommendation based on that
information.
ALLOWThe users answer matches and they can be allowed to continue
(response message 3b)
CHALLENGEThe answer does not match, but the user has not exceeded the
number of attempts for that credential (response message 3C)
DENYThe user has exceeded the number of attempts, and your organization
wants to deny them their transaction. The user is not locked out of the account, but
should be denied access from that specific user device. (response message 3C)
REVIEWAllow the transaction, but flag for a later review. response message
3C)
Note: At any given point, the Adaptive Authentication system can mark a transaction
for review and send it to the Case Management application, regardless of whether a
user is allowed to continue or is denied the transaction.
Your policies dictate which transactions are marked for review.

Out-of-Band Credentials Process

This process describes the out-of-band (OOB) phone and email channel. The steps in
this process are:
Step 2: Send the Out-of-Band Authentication to the User
Step 3: Check the Challenge Answers
The following figure shows the four steps for the Out-of-Band Credentials process.
The figure shows all of the different credential processes.
For example, in step 1b, request 1 in the figure is denoted as request message (1).
Likewise, in step 1c, response 1 in the figure is denoted as response message (1).


The user initiates a transaction that requires an analysis (either a logon or a risk
analysis).
a. The user initiates a transaction that requires an analysis (either a logon or a
risk analysis).
b. Your system submits a request message (1) to the Adaptive Authentication
c. The analyze method returns a response message (1) with the suggested action.
In this case, an asynchronous challengeResponse is required.
Step 2: Send the Out-of-Band Authentication to the User

In this step, an OOB message is sent to the user. However, your application should
inform the Adaptive Authentication system that you want to do an Asynchronous
challengeResponse.
a. Your system should send a request message (2) to the challenge method.
b. The challenge method sends the OOB message to the user. For this process,
the Adaptive Authentication system provides your application with a one-time
password (OTP) that is to be presented to the user through your web pages.
After the OTP is sent, the user has to respond before an additional challenge
request is sent. A maximum of three challenge requests are sent before the
session times out. The default response time out limits can be redefined using
the Administration Console. For more information, see the Operations Guide.
c. The OOB phone service calls the user on the phone number they used during
enrollment. The user needs to answer the phone and enter their OTP correctly
within the time out window.
If the time out window expires, the user is denied access and they need to try
again.
Step 3: Check the Challenge Answers

After the user has entered their OTP, the Adaptive Authentication system checks to
see if they have correctly entered their information. Your application does not need to
send any user information to the Adaptive Authentication system.
However, your application does needs to send a request message (3) to
queryAuthStatus in order to determine if the user answered correctly in the OOB
media. This request message must be sent within the time out window of the start of
the challenge request (from Step 2).
The Adaptive Authentication system returns the result in the queryAuthStatus
response message.
Note: Your system should allow for the user to request another OOB message be sent
if the user does not receive the call.

When the Adaptive Authentication system checks the answer, it checks the following:

did the session time out?

does the answer match?
if not, has the user exceeded the preset number of attempts to answer correctly?
The Adaptive Authentication system then makes a recommendation based on that
information.
ALLOWThe users answer matches and they can be allowed to continue
(response message 3a)
CHALLENGEThe answer does not match, but the user has not exceeded the
number of attempts for that credential (response message 3b)
DENYThe user has exceeded the number of attempts or if the session timed
out, and your organization wants to deny them their transaction. The user is not
locked out of the account, but should be denied access from that specific user
device. (response message 3a)
REVIEWAllow the transaction, but flag for a later review. (response message
3a)
Note: At any given point, the Adaptive Authentication system can mark a transaction
for review and send it to the Case Management application, regardless of whether a
user is allowed to continue or is denied the transaction.
Your policies dictate which transactions are marked for review.
User Maintenance
This process allows a user, who has been successfully authenticated, to update their
user information, including their challenge questions and any other credential
information as necessary. Once the user has completed all maintenance of their
information, they are passed to normal user processes, and the information is written
to the Adaptive Authentication database.
The following figure describes the User Maintenance process, which can also be used
as a partial re-enrollment process.
The steps in the figure require the issuing of a request and response messages for a
SOAP method. The numbering of the request and response messages are noted in the
explanation of process by the number of the request and response in the figure.

For example, the review and update processes describe request 1 in the figure as
request message (1). Likewise, response 1 in the figure is described as response
message (1).

The User Initiates a Maintenance Update

In this process:
a. The user is successfully authenticated into the Adaptive Authentication
system.
b. The user chooses (or is required) to update their information, so your
application should show the various maintenance pages to the user.
c. The user chooses what information to update. This information can include:
changing their challenge questions and/or answers to those questions.
adding or changing their OOB authentication information (such as
telephone numbers).
Retrieve & Update Information

Your system should make the appropriate request Messages and show the appropriate
pages to the user. Your system should update any changes to the user record by
making an request message to the updateUser method.
For displaying the challenge questions, your application should make a request
message (1) to the query method to retrieve the challenge questions from the
Adaptive Authentication system. The query method returns a response message
(1).
For adding or changing out-of-band information, your application should show
the appropriate pages to the user, collect the information, and perform any data
validation (as needed).
Note: You can opt to make:

- one query request message for different types of requests instead of making multiple
query requests for different items.
- one updateUser request message to update multiple changes to the users record.
However, it is highly recommended that an updateUser request follow each query.

3 Web Services API Methods

Simplified Overall Workflow
Adaptive Authentication Web Services Methods
Request and Response Messages for Each Method
analyze Method
authenticate Method
challenge Method
createUser Method
notify Method
queryAuthStatus Method
query Method
updateUser Method
The RSA Adaptive Authentication (On Premise) system provides authentication-
related service to your web applications. This chapter briefly summarizes the various
methods of the Web Services API, as well as the specific data elements for those
methods.
For more information about how each method fits into the business workflow, see
Chapter 2, Web Services Basic Processes.
3: Web Services API Methods 61

Simplified Overall Workflow

The following figure shows how each of the individual methods fit into the overall
workflow. This flow has been simplified and does not include maintenance.
62 3: Web Services API Methods

Adaptive Authentication Web Services Methods

Adaptive Authentication provides different methods for use within the Adaptive
Authentication Web Services. The Adaptive Authentication methods are listed in the
following table.
Method Description
analyze This method performs one of two tasks:

a risk analysis for an event
(optionally) authenticates one or more credentials
The analyze method sends the risk analysis and authentication to the Risk Engine and
returns a recommended action.
authenticate This method performs verification for one or more credentials.
challenge This method returns the challenge material that will be presented to the user.
createUser This method is an explicit call that creates a user.

(Optional) In this method, you can run risk analysis on whether to create the user record for
enrollment. If the response is DENY, the user record is not created.
notify This method allows the organizations application to notify the Adaptive Authentication
system of any application events that can be added to the Adaptive Authentication systems
profiles.
This method does not return any actionable response values.
queryAuthStatus For asynchronous credentials, this method returns the authentication status of that
credential.
query This method queries a users profile and any system level browsable data.
updateUser This method updates a users profile.
Synchronous and Asynchronous Web Services Methods

The following are the types of Web Services methods:
Synchronous
Asynchronous

Synchronous Web Services Methods

Synchronous Web Services methods are those where calls are made by your
application (a request message), which then awaits an immediate response from the
Adaptive Authentication system.
Synchronous methods in the Adaptive Authentication Web Services are listed below:
analyze
authenticate
challenge
createUser
notify
queryAuthStatus
query
updateUser
Asynchronous Web Services Methods

An asynchronous method is a SOAP call request issued from within your application
that does not require an immediate response from the Adaptive Authentication system.
In this instance, a response message is not sent at all.

Asynchronous methods are:

analyzeinvoked asynchronously during Silent Mode or Transactional
Monitoring when receiving a response is not expected.
notifyinvoked when you notify the Adaptive Authentication system of a
specific event which does not require a response.
Note: The asynchronous methods do not create new devices or rotate the users device
token.
For asynchronous Web Services calls, even if you do not receive a SOAP response,
you still receive an HTTP202 response call.
Methods and Credentials

Each credential type supports almost all of the Adaptive Authentication methods.
Each credential type might support slightly different data structures. The following
table describes the credential structures that must be provided by each credential,
based on the credential type. Each credential structure corresponds to specific
methods.
For specific information about each of the credential types data structures, see:
Appendix G, Challenge Question Credential.
Appendix C, Out-of-Band Phone and Email Credential.
Each credential consists of a CredentialType and an Object as its payload.
Request/
Method Data Structure Description
Response
analyze Request CredentialDataList For any credential type, this structure

represents a users request.
Response CredentialAuthResultList For any credential type, this structure

represents the result of authenticating a
users response.
authenticate Request CredentialDataList For any credential type, this structure

represents a users request.
Response CredentialAuthResultList For any credential type, this structure

represents the result of authenticating a
users response.
challenge Request CredentialChallengeRequestList For a challenge-request credential, this

structure represents clients request for
challenge material
Response CredentialChallengeList For a challenge-response credential, this

structure represents the challenge materials
to be presented to the user.

Request/
Method Data Structure Description
Response
createUser Request CredentialManagementRequestLi A request to activate, deactivate, view or

st update credential material, which includes
browsable data and user-specific data.
Response CredentialManagementResponse Response to activate, deactivate or view

List the credential management material.
notify Request Not Supported By Credentials
Response Not Supported By Credentials
query Request CredentialManagementRequestLi A request to view credential material,

st which includes browsable data and user-
specific data.
Response CredentialManagementResponse Response to view a credential material

List request.
queryAuthSt Request CredentialAuthStatusRequest For asynchronous credential type, this

atus structure represents a request for the
results of authenticating a users response.
Used primarily by Asynchronous
Credentials
Response CredentialAuthStatusResponse For asynchronous credential type, this

structure represents the results of
authenticating a users response. Used
primarily by Asynchronous Credentials.
updateUser Request CredentialManagementRequestLi A request to activate, deactivate, or update

st credential material, which includes
Response CredentialManagementResponse A response to activate, deactivate, or

List update a credential material request.
Request and Response Messages for Each Method

Each Authentication Service Method contains the following groups of data elements:
Generic request or Response messages
Specific method request or response messages. Each method contains extra
elements that extend either the generic request or generic response messages.
GenericRequest Message
The following figure shows how each specific request message extends the
GenericRequest message.

Generic Requests for All Methods

The following data elements are used in all generic requests to the Adaptive
Authentication system. Each method might have additional data elements that are
added to the message.
For the definition of the individual parameters of each data element, see Structures
Used in All Methods on page 107.

Data Element Description Required Data Type
actionTypeList Identifies which specific action is to be taken. N GenericActionType

List
configurationHead (Not supported as of version 7.0) N ConfigurationHead

er This parameter is used in ASP model to load er
caller-specific configurations.
deviceRequest Information about the device and the request. N DeviceRequest
identificationData Information that identifies the user, transaction N IdentificationData

and session.
messageHeader General information about request, such as the: Y MessageHeader

request ID
request type
timestamp
Web Services version
securityHeader The credential used to authenticate the caller to Y SecurityHeader

the server.
GenericResponse Message
The following figure shows how each specific response message extends the
GenericResponse message.


Generic Response Message for the All Methods

The following data elements are used in all generic responses to the Adaptive
Authentication system. Each method might have additional data elements that are
added to the message. For the definition of these data elements, see Structures Used
in All Methods on page 107.
Data Element Description Data Type
deviceResult Authentication information about the device. DeviceResult Structure
identificationData Information that identifies user, transaction and session. IdentificationData Structure
messageHeader General information about the Response message. MessageHeader Structure
statusHeader The status of the call. StatusHeader Structure
analyze Method
The analyze method performs a risk analysis for one event or a list of events. It can
also authenticate one or more credentials that are sent to it. The analyze method sends
its results to the Risk Engine and returns a recommended policy.
Note: Do not use the analyze method for authentication.
AnalyzeRequest Message
This request message extends the GenericRequest message, as defined in
GenericRequest Message on page 66.
The following table describes the specific data elements in the analyze request
message. For a listing of the parameters for these data elements, see Chapter 5, Web
Services Request Data Structures and Types.
autoCreateUserFlag A flag to determine whether to allow an automatic, yet N Boolean

unplanned, create user process for a non-existing user.
If this is set to TRUE, you need to pass the
SET_USERSTATUS flag.
Important: Since createUser for ATM is not supported,

set the autoCreateUserFlag to true for any analyze
method request with channelIndicator set to ATM.

channelIndicator A list of available channel types: N ChannelIndicat

WEB (default) orType
IVR
CALL_CENTER
BRANCH
ATM
MOBILE
OTHER
clientDefinedChann Indication of the device type used by the customer to N ClientDefinedC

elIndicator transfer additional information on the channel in use. hannelIndicator
For example, a list of possible values for this data
element:
SMS-based
Browser-based
Application-based
clientReturnData (Not supported as of version 7.0) N ClientReturnDa

This parameter determines where to return the user, if ta
there needs to be a redirection to a new URL.
collectionRequest (Not supported as of version 7.0) N CollectionRequ

This parameter describes why a collection is being est
initiated.
credentialDataList A list of any credentials that a user has presented as part N CredentialData
of this transaction. These credentials are authenticated List
by the Adaptive Authenticationsystem.
deviceManagement A request to: N DeviceManage

Request update (bind/unbind (if BindingType is NONE)) a mentRequestPa
single device yload
unbind all devices
browse bound devices
eventDataList A list of events associated with this transaction. Only Y EventDataList

one event can be passed for any given request.
runRiskType A flag that determines whether the risk engine should Y RunRiskType
be run
by updating the users profile
without updating the users profile
by just relying on the policy rules
userData (Not supported as of version 7.0) N UserData

Additional information known about the user.

AnalyzeResponse Message
This response message extends the GenericResponse message, as defined in
GenericResponse Message on page 68.
The following table lists the specific data elements in the analyze Response. For a
listing of the parameters for these data elements, see Chapter 7, Web Services
Response Data Structures and Types.
collectableCredentialLi (Not supported as of version 7.0) CollectableCredentialLi

st A list of the credentials that is safe for your application to st
collect from the user.
credentialAuthResultLi A list of the authorization results for each credential. CredentialAuthResult

st
deviceManagementRes The result of device credential authentication. DeviceManagementRes

ponse ponsePayload
requiredCredentialList The required list of credentials that you need to collect RequiredCredentialList
from the user in order for authentication to occur.
riskResult The risk score and resulting recommended policy action for RiskResult
the overall transaction.
Note: The riskResult differs from the overall

credentialAuthResultList. A credential might be
authenticated correctly. However, the overall transaction
might be deemed risky.
serverRedirectData (Not supported as of version 7.0) ServerRedirectData

The URL to which the user has been redirected.
Note: If the analyzeResponse message returns a recommended action of

CHALLENGE, it returns a transactionID parameter that lives across multiple
requests (ChallengeRequest and AuthenticateRequest) until the user passes the
credential successfully.
Do not use the transactionID parameter as part of a different AnalyzeRequest
message. Otherwise, an error occurs.

authenticate Method
The authenticate method verifies a user using one or more credentials.
AuthenticateRequest Message
The following table lists the specific data elements in the authenticate Request. For a
Request Data Structures and Types.
channelIndicator A list of available channel types: N ChannelIndicatorT

WEB (default) ype
IVR
CALL_CENTER
BRANCH
ATM
MOBILE
OTHER
clientDefinedChann Indication of the device type used by the customer to N ClientDefinedChan

elIndicator transfer additional information on the channel in use. nelIndicator
element:
SMS-based
Browser-based
Application-based
credentialDataList A list of any credentials that the user has presented as N CredentialDataList
part of this transaction.
deviceManagement A request to: N DeviceManagemen

Request update (bind/unbind (if BindingType is NONE)) a tRequestPayload
single device
unbind all devices
eventDataList The list of events associated with this transaction. N EventDataList

AuthenticateResponse Message
This response message extends the GenericResponse Message, as defined in
The following table lists the specific data elements in the authenticate Response. For a
If a response is not received within the amount of time defined in the Transaction
Time To Live parameter, the response is considered rejected and the failure count is
incremented.
If you exceed the number of challenge or authenticate responses allowed, as defined in
the Maximum User Failure Count field in the Administration Console, the user is
locked.
credentialAuthResultList The results of the users authentication. CredentialAuthResultList
deviceManagementResp The result of device credential authentication. DeviceManagementResp

onse onsePayload
requiredCredentialList A list of the required credentials needed by the Adaptive RequiredCredentialList

Authentication system to authenticate the user.
challenge Method
The challenge method can:
Initiate a challenge-response credential type, such as challenge questions. If you
request a challenge question credential, the challenge Response returns the users
challenge questions. If you exceed the number of challenge or authenticate
responses allowed, as defined in the Maximum User Failure Count field in the
Administration Console, the user is locked.
Initiate an asynchronous challenge-response credential, such as OOB phone. The
Adaptive Authentication system makes the out-of-band call.
Initiate an asynchronous verification credential type, such as OOB phone.
For more information about the different workflows that use this method, see
Chapter 2, Web Services Basic Processes.

ChallengeRequest Message
The following table lists the specific data elements in the challengeRequest. For a
channelIndicator A list of available channel types: N ChannelIndicatorTy

WEB (default) pe
IVR
CALL_CENTER
BRANCH
ATM
MOBILE
OTHER
clientDefinedChan Indication of the device type used by the customer to N ClientDefinedChan

nelIndicator transfer additional information on the channel in use. nelIndicator
element:
SMS-based
Browser-based
Application-based
credentialChalleng The users challenge material from the Adaptive N CredentialChalleng

eRequestList Authentication system. eRequestList
deviceManagement A request to: N DeviceManagement

Request update (bind/unbind (if BindingType is NONE)) a RequestPayload
single device
unbind all devices
eventDataList A list of the events associated with this transaction. N EventDataList

ChallengeResponse Message
The following table lists the specific data elements in the challenge Response. For a
credentialChallengeList The challenge material to be presented to the user. CredentialChallengeList
deviceManagementResponse The result of the device credential authentication. DeviceManagementResp

onsePayload
createUser Method
The createUser method is an explicit call to create a new user, which can also query
the Adaptive Authentication system for the necessary data to enroll the user. If
requested, the createUser method can also run a risk analysis on the users enrollment.
CreateUserRequest Message
The following table lists the specific data elements in the createUserRequest. For a
channelIndicator A list of available channel types: N ChannelIndicatorType

WEB (default)
IVR
CALL_CENTER
BRANCH
ATM
MOBILE
OTHER

clientDefinedChan Indication of the device type used by the N ClientDefinedChannelIn

nelIndicator customer to transfer additional information dicator
on the channel in use. For example, a list of
possible values for this data element:
SMS-based
Browser-based
Application-based
credentialManage A request to activate, deactivate, view or N1 CredentialManagementR

mentRequestList update credential material, which includes equestList
deviceManagement A request to: N DeviceManagementReq

Request update (bind or unbind (if BindingType is uestPayload
NONE)) a single device
unbind all devices
runRiskType A flag whether to run the risk analysis on the Y RunRiskType

users enrollment.
userData (Not supported as of version 7.0) N UserData Structure

Information regarding the user.
1
Not required, but highly recommended.
CreateUserResponse Message
The following table lists the specific data elements in the createUserRequest. For a
credentialManagementResp The request you made in the Credential Structures

onseList credentialManagementRequestList is sent back to
your application.
deviceManagementRespon The result of the device credential authentication. DeviceManagementRespons

se ePayload

riskResult The risk score and resulting recommended policy RiskResult

action for the overall transaction.

authenticated correctly, but the overall transaction
might be deemed risky.
systemCredentials A list of credentials that your application Credential Structures

supports.
notify Method
The notify method allows your application to notify the Adaptive Authentication
system of any interesting application events that the Adaptive Authentication system
can add to its profiles. This method does not return any interesting or actionable
response values.
Important: You cannot trigger rules for notify requests. You can send them as
asynchronous analyze methods and get the same behavior at the API level (not the
response level), with the ability to define review rules.
NotifyRequest Message
The following table lists the specific data elements in this request. For a listing of the
parameters for these data elements, see Chapter 5, Web Services Request Data
Structures and Types.
autoCreateUserFlag A flag to determine whether to allow an automatic, N Boolean

yet unplanned, create user process for a non-
existing user.
If this is set to TRUE, you need to pass the
SET_USERSTATUS flag.

ChannelIndicator A list of available channel types: N ChannelIndicat

WEB (default) orType
IVR
CALL_CENTER
BRANCH
ATM
MOBILE
OTHER
clientDefinedChannelIn Indication of the device type used by the customer N ClientDefinedC

dicator to transfer additional information on the channel in hannelIndicator
use. For example, a list of possible values for this
data element:
SMS-based
Browser-based
Application-based
deviceManagementRequ A request to: N DeviceManage

est update (bind or unbind (if BindingType is mentRequestPa
NONE)) a single device yload
unbind all devices
eventDataList A list of the events associated with this transaction. Y EventDataList

Information about the user.
NotifyResponse Message
This response message does not contain any significant information. It merely extends
the GenericResponse message, as defined in GenericResponse Messageon page 68.
The response message does not require your application to take any actions. For a
deviceManagementResp The result of the device credential authentication. deviceManagementResponse

onse

queryAuthStatus Method
The queryAuthStatus method returns the authentication status of an asynchronous
credential.
queryAuthStatusRequest Message
channelIndicator A list of available channel types: N ChannelIndicatorTyp

WEB (default) e
IVR
CALL_CENTER
BRANCH
ATM
MOBILE
OTHER
clientDefinedChannel Indication of the device type used by the N ClientDefinedChanne

Indicator customer to transfer additional information on lIndicator
the channel in use. For example, a list of possible
values for this data element:
SMS-based
Browser-based
Application-based
credentialAuthStatus A request to view the status of the asynchronous N CredentialAuthStatus

Request credential. Request
queryAuthStatusResponse Message
The following table lists the specific data elements in the response message. For a
credentialAuthStatusResponse The result of the users asynchronous credential. Credential Structure

query Method
The query method looks at the user profile, and returns any browsable data, including
any credential information. For more information about the different workflows that
use this method, see Chapter 2, Web Services Basic Processes.
QueryRequest Message

WEB (default) ype
IVR
CALL_CENTER
BRANCH
ATM
MOBILE
OTHER
clientDefinedChannelIn Indication of the device type used by the N ClientDefinedChan

dicator customer to transfer additional information on nelIndicator
the channel in use. For example, a list of
possible values for this data element:
SMS-based
Browser-based
Application-based
credentialManagementR A request to: N CredentialManage

equestList view a users credential material mentRequestList
activate or deactivate a users material
update a users material
This request includes browsable data and user-
specific data.
deviceManagementRequ A request to: N DeviceManagemen

est update (bind or unbind (if BindingType is t Request
unbind all devices

queryResponse Message
The following table lists the specific data elements in this response. For a listing of the
parameters for these data elements, see Chapter 7, Web Services Response Data
browsableGroupNames A list of groups to which the user can belong. String[ ]
credentialManagementResponseL The request you made in the CredentialManagement

ist credentialManagementRequestList is sent back ResponseList
to your application.
deviceManagementResponse The result of device credential authentication. DeviceManagementRe

sponsePayload
systemCredentials The list of credentials that your application Credential Structures

supports.
userCredentials The users credential status and type. Credential Structures

updateUser Method
The updateUser method updates the users profile, including credential information.
UpdateUserRequest Message

WEB (default) ype
IVR
CALL_CENTER
BRANCH
ATM
MOBILE
OTHER
clientDefinedChann Indication of the device type used by the N ClientDefinedChan

elIndicator customer to transfer additional information on nelIndicator
the channel in use. For example, a list of possible
values for this data element:
SMS-based
Browser-based
Application-based
credentialManagem A request to: N CredentialManage

entRequestList view a users credential material mentRequestList
activate or deactivate a users material
update a users material
This request includes browsable data and user-
specific data.
deviceManagement A request to: N DeviceManagemen

Request update (bind or unbind (if BindingType is tRequestPayload
unbind all devices
eventDataList (Not supported as of version 7.0) N EventDataList

A list of the events associated with this
transaction.

runRiskType This flag determines whether risk engine should N RunRiskType

be run with or without updating the users profile
or just rely on the policy.

Any extra information known abut the user.
UpdateUserResponse Message
The following table lists the specific data elements in the response message. For a
credentialManagementRespo The request you made in the CredentialManage

nseList credentialManagementRequestList is sent back to your mentResponseList
application.
deviceManagementResponse The result of device credential authentication. DeviceManageme

ntResponsePayloa
d
riskResult The risk score and resulting recommended policy action RiskResult
for the overall transaction.

authenticated correctly, but the overall transaction might
be deemed risky.

4 Web Services API Data Elements

Priority Levels
Supported Event Types
Common Event Data Elements
Event-Specific Data Elements
This chapter describes the Adaptive Authentication data elements that must be set in
the Web Services API.
Priority Levels
The following settings indicate the levels of priority for sending a particular data
element:
required
highly recommended
recommended
optional
Note: By sending more than the required data elements, the impact and effectiveness
of the Adaptive Authentication Risk Engine in detecting fraud increases, and the
additional data elements help to keep the user challenge and false positive rates low. It
is advisable to also send the highly recommended and the recommended data
elements, in addition to the required data elements, to take advantage of the Risk
Engine and its abilities.
Supported Event Types

The RSA Adaptive Authentication (On Premise) system supports the following event
types.
Event Type Description
ACTIVATE_CARD The user attempts to activate a card (for example, debit, credit)
ADD_PAYEE The user attempts to add a new payee to their list of payees
CARD_PIN_CHANGE The user attempts to change the PIN of a credit or debit card.
CHANGE_ADDRESS The user attempts to change their standard mailing address
4: Web Services API Data Elements 85

CHANGE_ALERT_SETTINGS The user attempts to change their settings for receiving alerts (for
example, an alert when a change is made to their account)
CHANGE_AUTH_DATA The user attempts to change their authentication data (for example,
phone number, challenge questions)
CHANGE_EMAIL The user attempts to change their contact email address
CHANGE_LIFE_QUESTIONS The user attempts to change the questions/answers they want to see if
they are challenged by this form of additional authentication
CHANGE_LOGIN_ID The user attempts to change their login ID
CHANGE_PASSWORD The user attempts to change the password they use to access the
organizations online system
CHANGE_PHONE The user attempts to change their contact phone number
CHANGE_STATEMENT_SETTING The user attempts to change their settings for statement display or
S receipt
CLIENT_DEFINED The organization attempts to define their own event type to use
instead of or in addition to the Adaptive Authentication default event
types. The Adaptive Authentication risk model is run on the event
type combination.
CREATE_USER The organization attempts to add an online user
DEPOSIT The user attempts to initiate a deposit
EDIT_PAYEE The user attempts to edit a payee in their list of payees
ENROLL The user attempts to enroll into the organizations online system
EXTRA_AUTH The organization notifies the Adaptive Authentication system of the

result of external authentication. The system is informed if the
authentication is successful and if the user's profile is updated to
determine whether the transaction is genuine or fraudulent.
If EXTRA_AUTH is used, the AuthenticationLevel structure should

also be passed, to send additional information regarding the user. See
Appendix I, Authentication Levels.
FAILED_CHANGE_PASSWORD_ The user's attempt to change the password fails.

ATTEMPT
FAILED_LOGIN_ATTEMPT The user's attempt to be authenticated when logging into the

organizations online system is unsuccessful.
86 4: Web Services API Data Elements

FAILED_OLB_ENROLLED_ATTE The user's attempt to enroll online is unsuccessful.

MPT
NULL NA
OLB_ENROLL The user attempts to enroll online.
OLB_PASSWORD_CHANGE The user attempts to change the on-line banking password.
OPEN_NEW_ACCOUNT The user attempts to open a new account.
OPTIONS_TRADE The user attempts to initiate a stock options trade.
PAYMENT The user attempts to initiate a payment to a payee.
READ_SECURE_MESSAGE The user attempts to read secure messages.
REQUEST_CHECK_COPY The user requests a copy of their checks.
REQUEST_CHECKS The user requests to order checks.
REQUEST_CREDIT The user requests credit.
REQUEST_NEW_CARD The user requests a new card (for example, debit, credit).
REQUEST_NEW_PIN The user requests a new PIN.
REQUEST_STATEMENT_COPY The user request for a copy of the statement.
SEND_SECURE_MESSAGE The user attempts to send a secure message.
SESSION_SIGNIN The user attempts to log on to an online session.
STOCK_TRADE The user attempts to initiate a stock trade.
UPDATE_USER The user attempts to update user information.
USER_DETAILS The user attempts to view user details.
VIEW_CHECK The user attempts to view a check.
VIEW_STATEMENT The user attempts to view account statement.
WITHDRAW The user attempts to initiate a withdrawal from the users account.
Common Event Data Elements

The following data elements are common to all events, and are require or
recommended to be sent with all Event Types. Possible event data element values that
can be sent to the Adaptive Authentication system are listed in the Values column.

Element Field Priority Values Description
messageHeader elements
messageHeader apiType Required DIRECT_SOAP_API This defines the type of available

APIs that are used to
communicate with the Adaptive
requestId Recommended A unique value per This unique value should be

request generated by the caller and
preserved by the responder. It
may be hashed. Used for
debugging only.
requestType Required ANALYZE The type of method you want to

AUTHENTICATE invoke.
CHALLENGE
CREATEUSER
NOTIFY
QUERY
QUERYAUTHSTATUS
UPDATEUSER
timeStamp Optional Format: YYYY-MM- The caller should generate the

DD HH:mm:SS timestamp and the responder
preserve it. It is intended for
playback of old requests.
Version Required 7.0 The version of Web Services

being used.
securityHeader
securityHeader callerCrede Required Created by Web Services This maps to the password of the
ntial Authentication line caller initiating the request
application or GUI message. This does not map to the
users password.
callerId Required Created by Web Services This identifier is used for

Authentication line authenticating the caller initiating
application or GUI the request message. This does
not map to the users ID.
method Required PASSWORD The authorization method used

for encryption.

IdentificationData
IdentificationD userName Required An internal consistent ID The users user name.

ata for the user. Not the
login ID if that ID can be
changed.
userLoginN Recommended The User ID that was The users login name.
ame entered in the login form
(can be a hashed / table
translated form of it).
orgName Highly The ID for an The organization to which the

Recommended organization created in user belongs. The default value is
the Orgs and Groups the Default organization, assigned
application. only by the application.
If the field is blank, the For more information about the
application assigns the Orgs and Groups application, see
user to the Default the Operations Guide.
organization.
Note: Do not enter the

value default in the
orgName for the Default
organization.
userType Optional PERSISTENT PERSISTENT a permanent

NONPERSISTENT user whose date is remembered in
the database.
NONPERSISTENT a user
whose information is not
remembered after the call is
made, a pass through.
deviceRequest elements

deviceRequest httpAccept Highly HTTP request header - The HTTP accept header value is
Recommended accept retrieved from the HTTP request
header. This is used for device
profiling, and is a potential fraud
predictor.
httpAccept Highly HTTP request header - The HTTP accept header

Chars Recommended Accept-Charset character set is retrieved from the
HTTP request header. This is used
for device profiling, and is a
potential fraud predictor.
httpAcceptE Highly HTTP request header - The HTTP accept encoding is

ncoding Recommended Accept-Encoding retrieved from the HTTP request
predictor
deviceRequest httpAcceptL Highly HTTP request header - The HTTP accept language is
anguage Recommended Accept-Language retrieved from the HTTP request
predictor
httpReferrer Highly HTTP request header - The HTTP referrer header value
Recommended Referrer is retrieved from the HTTP
request header.
ipAddress Highly HTTP request - The IP address from the users

Recommended ip-address device is retrieved from the HTTP
request header.
This is used for device and geoIP
profiling providing real time link
analysis.
userAgent Highly HTTP request header - The user agent string is retrieved
Recommended user-agent from the HTTP request header
and is used in device profiling.
deviceIdenti Highly NA An array of device identification

fier Recommended data elements consisting of
MobileDevice, PhoneData
structures, and ClientGenCookie

pageId Highly NA Identifier of the page currently

Recommended accessed by the end-user from
which all the page elements have
been collected..
Note: pageId must be unique per

Important: The bank. This is relevant for resellers.
maximum length of this
field is 50 characters. If either HTML Infection
Field length validation is Protection or Man Vs. Machine
performed on this field. Detection features are
implemented, this field becomes
mandatory.
domElemen Highly The collected A formatted string consisting of

ts Recommended information from the the page elements collected from
script, rsa.js. the page identified by the field
pageId.
jsEvents Highly The collected A string consisting of the user

Recommended information from the actions collected from the page
script, rsa.js. identified by the field pageId.
geoLocation Highly The collected A formatted string consisting of

Recommended information from the the geographical location
script, rsa.js. elements.
devicePrint Highly The collected The detailed hardware and

Recommended information from the software characteristics of each
script, rsa.js. computer.
For detailed information about
device print, see the sections
about device print in chapter
Device Information Collection
in the Integration Guide.
deviceToke Highly System generated and The cookie retrieved from the
nCookie Recommended locally stored. users device.
The system generates the first
cookie, which is stored locally for
future user requests. This spares
the needs for identification and
authentication checks for each
subsequent logon.

deviceToke Highly System generated and The flash shared object retrieved
nFSO Recommended locally stored. from the users device. The
system generates the first FSO,
which is stored locally for future
user requests.
eventData elements
eventDataList Required (at This may have multiple The event data object element
least one elements if the user describes the event type field in
eventData eventData initiated multiple the event data object.
element) transfers or bill
payments in a single
form.
eventType Required This is defined per event. The type of event that took place
See Event-Specific in your system for the users
Data Elements on transaction.
page 93.

Event-Specific Data Elements

The following elements need to be sent, in addition to the general data elements, for
specific event types. The Values column includes the possible values to send to the
Adaptive Authentication system.
Element Field Priority Value To Use Description
Add Payee (ADD_PAYEE), Edit Payee (EDIT_PAYEE)
eventDataList eventType Required ADD_PAYEE The type of event that took place
eventData EDIT_PAYEE in your system for the users
transaction.The user sets up a new
payee or edits a current payee to
which they will direct funds.

eventDataList otherAccountT Highly BILLER This defines the payees account

eventData ype Recommende PERSONAL_ type.
transactionData d ACCOUNT
otherAccountB Highly OTHER_BAN This is the location of the payees

ankType Recommende K account.
d SAME_BANK
transferMedium Highly INTERNAL These are the methods for

Type Recommende BILLPAY_MA transferring funds between the
d IL user and the payee.
BILLPAY_EL
EC
BALANCE_T
RANSFER
ACH
WIRE
INTL_WIRE
CHECK
otherAccountO Highly ME_TO_YOU This defines the direction in

wnershipType Recommende MR_TO_ME which funds are transferred - from
d the user to the payee.
schedule Highly IMMEDIATE This defines how soon or how

Recommende SCHEDULED often the payee will receive
d RECURRING payment:
IMMEDIATE - for immediate
execution
SCHEDULED - scheduled for
a future date
RECURRING - a recurring
transfer
dueDate Highly scheduled date The scheduled date for a

Recommende transaction.
d

eventDataList recurringFreque Recommende frequency in This establishes how frequently

eventData ncy d days (the the transaction needs to occur. For
transactionData approximate example, the value for a monthly
number) transfer is 30.
between
transfers.
ExecutionSpee Highly SEVERAL_D This sets how soon the transaction

d Recommende AYS needs to take place.
d OVER_NIGH
T
FEW_HOURS
REAL_TIME
eventDataList amount Highly The transaction This is the amount of the

eventData Recommende amount in the transaction in the lowest
transactionData d original monetary denomination for the
amount currency original currency.
currency Highly The original This is the code that represents

Recommende currency code the original currency according to
d ISO standard 4217.
amountInUSD Highly The transaction This is the original currency

Recommende amount in USD amount converted into USD.
d

eventDataList routingCode Required External The routing code is functionally

eventData account routing required with the account number
transactionData code (can be in order to create a profile for the
otherAccountData hashed) payee.
accountNumber Required External The account number is

account number functionally required with the
(can be hashed) routing code in order to create a
profile for the payee.
Note: New customers must enter

the account number in IBAN
format. Existing customers must
continue to enter the account
number in the standard format to
maintain the payee profile.
internationalAc Highly External The payees account number in

countNumber Recommende account number IBAN format.
d (can be hashed)
in IBAN format
Note: Require
d for EFN and
ATM related
transactions
accountNickNa Recommende Free text entry This nickname is used to identify

me d the payees account.
eventDataList accountCountry Recommende Free text entry The country location of the
eventData d payees account.
transactionData
referenceCode Recommende Free text entry The information used by the user
otherAccountData
d to identify the reason for the
(continued) transaction.
Payment, Deposit
eventDataList eventType Required PAYMENT The type of event that took place
eventData DEPOSIT in your system for the users
transaction. The user sets up a
payment or deposit.

eventDataList transferMedium Highly INTERNAL The methods of transferring funds

eventData Type Recommende BILLPAY_MA between the user and the payee.
transactionData d IL
BILLPAY_EL
EC
BALANCE_T
RANSFER
ACH
WIRE
INTL_WIRE
CHECK
schedule Highly IMMEDIATE This defines how soon or how

Recommende SCHEDULED often the payee will receive
d RECURRING payment:
IMMEDIATEfor immediate
execution
SCHEDULEDscheduled for
a future date
RECURRINGa recurring
transfer
dueDate Highly scheduled date The scheduled date for a

Recommende transaction.
d
recurringFreque Recommende frequency in This establishes how frequently

ncy d (approximate the transaction needs to occur. For
number of) example, the value for a monthly
days between transfer is 30.
transfers.
ExecutionSpee Highly SEVERAL_D This element defines how soon a

d Recommende AYS fund transfer will take place.
d OVER_NIGH
T
FEW_HOURS
REAL_TIME

eventDataList amount Highly Transaction The amount of the payment or

eventData Recommende amount in deposit in the lowest monetary
transactionData d original denomination for the original
amount currency currency.
currency Highly Original This is the code that represents

Recommende currency code the original currency according to
d ISO standard 4217.
amountInUSD Highly Transaction This is the resulting amount in

Recommende amount in USD USD following monetary
d conversion. Conversion to USD is
the responsibility of the
organization.
eventDataList otherAccountT Highly BILLER The type of account that the payee
eventData ype Recommende PERSONAL_ has to which the user directs
transactionData d ACCOUNT funds.
otherAccountB Highly OTHER_BAN The type of bank where the payee

ankType Recommende K has an account to which the user
d SAME_BANK directs funds.
otherAccountO Highly ME_TO_YOU The owner of other account to

wnershipType Recommende ME_TO_ME which the user is sending funds.
d

eventDataList routingCode Required External The routing code is functionally

eventData account routing required with the account number
transactionData code (can be in order to create a profile for the
otherAccountData hashed) payee.
accountNumber Required External The account number is

account number functionally required with the
(can be hashed) routing code in order to create a
profile for the payee.
Note: New customers must enter

the account number in IBAN
format. Existing customers must
continue to enter the account
number in the standard format to
internationalAc Highly External The payees account number in

countNumber Recommende account number IBAN format.
d (can be hashed)
in IBAN format
Note: Require
d for EFN and
ATM related
transactions
accountNickNa Recommende Free text entry A nickname used to identify the

me d payees account.
accountCountry Recommende Free text entry The country location of the

d payees account.
referenceCode Recommende Free text entry The information used by the user
d to identify the reason for the
transaction.
Credit Request
eventDataList eventType Required REQUEST_CR The type of event that took place
eventData EDIT in your system for the users
transaction. The user initiates a
request for credit.
eventDataList successful Recommende TRUE A successful attempt by the user

eventData d to request credit coverage.
authenticationLevel

eventDataList amount Required transaction The amount of the transaction in

eventData amount cents.
transactionData totalAvailableB Highly Amount in The users total available balance
alance Recommende USD for an account.
d
totalCreditLimi Highly Amount in The users total credit limit for an

t Recommende USD account that they are requesting
d credit.
totalCreditsUse Highly Amount in The users used credit limit for an

d Recommende USD account that they are requesting
d credit.
Change Address
eventDataList eventType Required CHANGE_AD The type of event that took place
eventData DRESS in your system for the users
change of address.

eventData d to change their address.
authenticationLevel
Change Email
eventDataList eventType Required CHANGE_EM The type of event that took place
eventData AIL in your system for the users
change to their email.

eventData d to change their email.
authenticationLevel
Change Login ID
eventDataList eventType Required CHANGE_LO The type of event that took place
eventData GIN_ID in your system for the users
change to their login ID.

eventData d to change their login ID.
authenticationLevel
Change Questions

eventDataList eventType Required CHANGE_LIF The type of event that took place
eventData E_QUESTION in your system for the users
S transaction. The user initiates a
change to their challenge
questions.

eventData d to change their challenge
questions.
authenticationLevel
Change Password
eventDataList eventType Required CHANGE_PAS The type of event that took place
eventData SWORD in your system for the users
change to their password.

eventData d to change their password.
authenticationLevel
Change Phone
eventDataList eventType Required CHANGE_PH The type of event that took place
eventData ONE in your system for the users
change to their contact phone
number.

eventData d to change their contact phone
number.
authenticationLevel
Client Defined
eventDataList eventType Required Any Adaptive The type of event that took place
eventData Authentication in your system for the users
defined event transaction.
type
client_defined_ Required organization The transaction event type as

event_ type defined defined and used by the
organization, in addition to the
default Adaptive Authentication
eventType.
eventDataList event_descripti Optional organization A description of event type

eventData on defined defined by the organization.

Failed Login
eventDataList eventType Required FAILED_LOGI The type of event that took place
eventData N_ATTEMPT in your system for the users
transaction. The user fails at their
attempt to log in.
IdentificationData userName Required An internal The users user name.

consistent ID
for the user. Not
the login ID if
that ID can be
changed.
userLoginName Recommende The User ID The users login name.

d that was entered
in the login
form (can be a
hashed / table
translated form
of it).
orgName Highly The ID for an The organization to which the

Recommende organization user belongs. The default value is
d created in the the Default organization, assigned
Orgs and only by the application.
Groups For more information about the
application. Orgs and Groups application, see
If the field is the Operations Guide.
blank, the
application
assigns the user
to the Default
organization.
Note: Do not
enter the value
default in the
orgName for
the Default
organization.
userType Recommende PERSISTENT PERSISTENT - a permanent

d NONPERSIST user whose date is remembered
ENT in the database.
NONPERSISTENT - a user
whose information is not
remembered after the call is
made, a pass through.

eventDataList successful Recommende FALSE An unsuccessful attempt by the

eventData d user to log in.
authenticationLevel
Failed Password Change
eventDataList eventType Required FAILED_CHA The type of event that took place
eventData NGE_PASSW in your system for the users
ORD_ transaction. The user fails at their
ATTEMPT attempt to change their password.
eventDataList successful Recommende FALSE An unsuccessful attempt by the

eventData d user to log in.
authenticationLevel
Order Checks
eventDataList eventType Required REQUEST_CH The type of event that took place
eventData ECKS in your system for the users
request to order checks.

eventData d to order checks.
authenticationLevel
View Checks
eventDataList eventType Required VIEW_CHEC The type of event that took place
eventData KS in your system for the users
request to view a check image.

eventData d to view a check image.
authenticationLevel
Stock Trade
eventDataList eventType Required STOCK_TRA The type of event that took place
eventData DE in your system for the users
request to buy or sell stock.

stockData successful Recommende TRUE A successful attempt by the user

d to complete a stock trade.
symbol Required (The stock This symbol identifies the stock.

symbol)
numberOfShare Required (The number of The the number of shares being

s shares) purchased or sold.
currentMarketP Required Amount The current market value for the

rice shares.
tradeType Required BUY This value is used to identify the

SELL type of stock trade activity.
SELL_SHORT
BUY_TO_CO
VER

5 Web Services Request Data Structures and

Types
Data Structures and Methods
Structures Used in All Methods
autoCreateUserFlag
collectionRequest
credentialAuthStatusRequest
credentialChallengeRequest
credentialDataList
credentialManagementRequestList
deviceManagementRequest
eventDataList
runRiskType
userData Structure
userData Structure
This chapter describes all the data structures and substructures used in request
messages for each method type.
Note: The Required column indicates which fields are mandatory. RSA also
recommends providing as much information in optional fields as possible to increase
the accuracy of the risk analysis.

The following table lists the data structures and the methods that use the data
structure. For a list of the common data structures and elements, see Chapter 6,Web
Services Common Data Structures and Types..
Data Structures Used in the Method
ActionTypeList All Requests*
configurationHeader All Requests*
deviceRequest All Requests*
identificationData All Requests*
5: Web Services Request Data Structures and Types 105

messageHeader All Requests*
securityHeader All Requests*
autoCreateUserFlag Analyze Request

Notify Request
collectionRequest Analyze Request
credentialAuthStatusRequest queryAuthStatus Request
credentialChallengeRequest Challenge Request
credentialDataList Analyze Request

Authenticate Request
credentialManagementRequestList createUser Request

Query Request
updateUser Request
deviceManagementRequest Analyze Request

Challenge Request
createUser Request
Notify Request
Query Request
updateUser Request
eventDataList Analyze Request

Challenge Request
Notify Request
updateUser Request
runRiskType Analyze Request

createUser Request
updateUser Request
ChannelIndicator Analyze Request

Challenge Request
createUser Request
Notify Request
queryAuthStatus Request
Query Request
updateUser Request
106 5: Web Services Request Data Structures and Types

clientDefinedChannelIndicator Analyze Request

Challenge Request
createUser Request
Notify Request
queryAuthStatus Request
Query Request
updateUser Request

The following section lists the generic structures that are used in all methods.
ActionTypeList
Parameter Description Data Type
actionTypeList The action to be taken. GenericActionType[ ]
GenericActionTypeList
genericActionTypes[ ] The action to be taken. To pass more than one item, adjust the GenericActionType
array size.
GenericActionType Values
The ActionType values defines all the actions your application can initiate through the
various methods. If an ActionType is not supported in a particular method, a warning
or error message may occur.
Values Description Used in Methods
GET_FAVORITES Gets the user personal images favorites list query
GET_PHRASE Gets the users caption analyze

query
GET_USER_STATUS Gets the users status All Methods
GET_USER_GROUP Get the group(s) to which the user belongs All Methods

GET_SYSTEM_CREDENTIAL Gets the credentials that your application can createUser

support (supported only for backward query
compatibility)
GET_USER_CREDENTIAL Gets the list of users credentials (supported only query

for backward compatibility)
GET_SYSTEM_CREDENTIAL Gets the credentials that your application can createUser

_EXTENDED support. When an external plug-in is used, the query
information is provided for the specific plug-in.
GET_USER_CREDENTIAL_E Gets the list of users credentials. When an external query

XTENDED plug-in is used, the information is provided for the
specific plug-in.
BROWSE_USER_GROUP Gets the list of groups to which the user can belong. query
BROWSE_CATEGORIES Retrieves the list of image categories from which createUser

the user can choose their image query
SET_PHRASE Sets the users caption updateUser
SET_USER_STATUS Sets the users status analyze

createUser
notify
query
updateUser
SET_USER_PREFERENCE Sets the users milter preference updateUser
SET_USER_GROUP Sets the users group analyze

createUser
UpdateUser
UPDATE_USER_NAME Updates the users user name in the database updateUser
OPEN_SESSION Opens a new session All Methods
CLEAR_FAVORITES Clears the users personal image favorites list updateUser
CLOSE_SESSION Terminates the session All Methods
COMMIT Commits any changes made and that are stored in All Methods
the cache
CANCEL Cancels any information that was saved to the All Methods
cache. Information is not written to the database.
DEL_FAVORITE Deletes a personal image from the users favorites updateUser

list

ADD_FAVORITE Adds a personal image to the users favorites list updateUser
configurationHeader
The Configuration Header structure contains information about configuration and
routing information that is used by the RSA Adaptive Authentication (On Premise)
system.
Note: This structure is primarily used by the ASP version of the Adaptive Authentication (On-
Premise) system. This structure is not supported as of release 6.0.2.1 of the RSA
Adaptive Authentication (On Premise) system.
Max
Parameter Description Required Data Type
Length
application Information about the application for which the API is 50 N String
used.
instanceID Only for the ASP version of the Adaptive 50 Y1 String

Authentication (On-Premise) system.
ruleSet The policy rule set to be used when evaluating the risk 200 N String
of the event. If multiple sets are to be used, each
should be separated by a semicolon (;)
1
Required only for the ASP version of the Adaptive Authentication (On-Premise) system.
deviceRequest
The deviceRequest structure contains any information that the your application finds
about a users device. The following table describes the data structure for the
DeviceRequest Structure.
Max
Length
beaconId (No longer in use) NA N String

The value of the Adaptive Authentication (On-
Premise) beacon.

Max
Length
devicePrint The detailed hardware and software 4000 N String

characteristics of each computer collected by the
java script, rsa.js.
Note: For detailed information about device print,

see the sections about device print in chapter
Device Information Collection in the
Integration Guide.
Important: The values retrieved from the script

should not be modified.
deviceTokenCookie The value of the cookie. 256 N String
deviceTokenFSO The value of the Flash Shared Object. 256 N String
httpAccept The HTTP accept header value. This parameter is 3000 N String
retrieved from the HTTP request header.
httpAcceptChars The HTTP accept header character set. This 256 N String
parameter is retrieved from the HTTP request
header.
httpAcceptEncoding The HTTP accept encoding. This parameter is 256 N String

httpAcceptLanguage The HTTP accept language. This parameter is 256 N String

httpReferrer The HTTP referrer header value. This parameter 256 N String
is retrieved from the HTTP request header.
ipAddress The IP address from the users device. This 15 N String

parameter is retrieved from the HTTP request
header. The Adaptive Authentication (On-
Premise) application validates whether the
information is a valid IP address.
userAgent The user agent String. This parameter is retrieved 1024 N String
from the HTTP request header.

Max
Length
pageId The identifier of the page currently accessed by 50 N String

the end-user from which the page elements have
been collected.
Note: This parameter must be unique for a bank.

It is important for resellers.
Important: This parameter is validated for

maximum field length of 50 characters.
domElements A formatted string consisting of the page 1024 N String

elements collected by the java script rsa.js from
the page identified by the field pageId.
jsEvents A string consisting of the user actions collected 1024 N String

by the java script rsa.js from the page identified
by the field pageId.
deviceIdentifier An array of device identification data elements NA N DeviceIden

consisting of MobileDevice, PhoneData tifier
structures, and ClientGenCookie.
geoLocation A formatted string consisting of the geographical 1024 N String

location elements collected by the java script
rsa.js.
identificationData
The identificationData structure contains specific information that uniquely identifies
a given request or response message.
Max Data
Parameter Description Required
Length Type
clientSessionId The clients session ID value. 40 N String
clientTransactionId The clients transaction ID value 100 N String
delegated (Not supported as of release 6.0.2.1) NA N Boolean

Is this request originating from a customer service
representative.
groupName The group to which the user belongs. 50 N String
newUserName Allows the organization to change a user name. 50 N String
orgName The organization to which the user belongs. 50 N String

Max Data
Length Type
sessionId The ID of a given session provided by the 200 N* String

Adaptive Authentication (On-Premise) system.
If this parameter is passed in a response message,
you must re-send it in any subsequent request
message to maintain session persistence.
Important: *- sessionId is required in

Authenticate Request calls; and in Notify Request
calls when eventType = EXTRA_AUTH.
transactionId The ID of a specific event for a given transaction. 200 N String

Each session might contain different transactions.
Only one transaction can occur at any given time.
This parameter is returned on all response
messages. You need only return this parameter
under two circumstances:
1. when a sessionID is also returned in the same
response
2. when you pass eventType = EXTRA_AUTH
in a notify request message.
in this situation, this parameter should be
entered in the eventReferenceID parameter.
Note: If this parameter is passed in any other

request message other than what is listed above, an
error message occurs.
userCountry The country portion of the users locale. 2 N String
userLanguage The language portion of the users locale. 2 N String
userLoginName The name entered by the user when they log into 50 N String
your application. This parameter can change. This
differs from the userName parameter.
userName The internal representation of the userLoginName. 50 Y String

This parameter should not change for the user.
Note: Note the difference between

userLoginName and userName.
userStatus The status of the user. See UserStatusType NA N UserStatu

Values on page 113. s Type
userType The type of user. See UserType Values on NA N UserType

page 114.

UserStatusType Values
Use these value to set the users status (SET_USERSTATUS).
Values Description
DELETED The user is marked as deleted in the Adaptive Authentication (On-

Premise) system. The user is not removed.
LOCKOUT The user is locked out of their user account.
NOTENROLLED The user is not enrolled.
UNLOCKED The user is unlocked.
UNVERIFIED The user is enrolled, but not yet verified by your application.
VERIFIED The user is enrolled and verified.
The following figure shows how a user can move from each of the states to another.

UserType Values
The UserType defines the type of user that is being sent. Values are:
Values Description
BAIT The user has been flagged as a user that was purposefully given wrong
information about an account.
NONPERSISTENT The user is a fraudulent user.
PERSISTENT The user is a true user of the system
messageHeader
The messageHeader structure contains general message information, such as the
message type, the version of the Adaptive Authentication (On-Premise) system, and
the timestamp of the message.
Max
Length
apiType Defines the type of available APIs that are used NA Y ApiType
to communicate with the Adaptive
Authentication (On-Premise) system. See
APIType Values on page 115.
requestId This value is unique per request, and is generated 50 N String

by the request process.
requestType Type of method that you want to invoke. NA Y RequestType
timestamp The timestamp of the header. Limited by N String

The date should follow the ISO 8601 format or: ISO date
format
YYYY-MM-DD HH:mm:SS.mmm (GMT time)
version The version of the Web Services API provided by 7.0 Y messageVersi
this version of Adaptive Authentication (On- on
Premise).
Note: For backward compatibility, the value of

this data element should be 6.0. For more
information about backward compatibility, see
Backward Compatibility on page 24.

RequestType Values
The RequestType values correspond to the different methods. The requestType value
should match the request message you are sending to Web Services.
See Chapter 3, Web Services API Methods for more information:
Values Description
ANALYZE This method performs one of two tasks:

a risk analysis for one ore more list of events
AUTHENTICATE This method performs verification for one or more credentials.
CHALLENGE This method returns the challenge material that is to be presented to the user.
CREATEUSER This method is an explicit call that creates a user. This method returns the
information you should gather from the user during enrollment.
(Optional) This method can also determine how risky a user is to enroll.
NOTIFY This method allows the organizations application to notify the Adaptive
Authentication System of any application events that can be added to the Systems
profiles.
QUERY This method queries a users profile and any system level browsesable data.
QUERYAUTHSTATUS For asynchronous credentials, this method returns the authentication status of that
credential.
UPDATEUSER This method updates a users profile
APIType Values
Values Description
ANALYZE_ONLY (Not supported as of release 6.0.2.1)

Logon and Transaction monitoring
DIRECT_SOAP_API The UI is handled by the client, and the Adaptive Authentication (On-
Premise) system supplies the service for risk and authentication.
WEB_REDIRECT (Not supported as of release 6.0.2.1)

SOAP API and HTML Redirection (not supported as of release 6.0. Used
only for ASP-hosted clients).

securityHeader
The securityHeader structure defines the specific ID and password for the application
making the request. The User ID or password is not sent, but rather the master User ID
and password assigned to your organizations system.
Max
Length
callerCredential Maps to the password of the caller initiating 50 Y String

the request message. This does not map to the
users password.
callerId The identifier to be used for authentication of 50 Y String

the caller initiating the request message.
This does not map to the users ID.
method The authorization method used for encryption. NA Y Authorization

Method
AuthorizationMethod Values
Value Description
PASSWORD Your system should always pass this variable
SECRET_HMAC_SHA1 (Not supported as of release 6.0.2.1)
autoCreateUserFlag
This Boolean value determines whether or not to automatically create a user if the user
is not already enrolled.
If this value is set to TRUE, you must also pass the SET_USERSTATUS action.
clientReturnData Structure
(This structure is not supported as of release 6.0.2.1.)
The clientReturnData structure is sent during an analyze request message to inform
the Adaptive Authentication (On-Premise) system of where to redirect the user after
they have been authenticated. The Redirect structures define any information that
redirects the user to certain key URLS for a stronger authentication flow

Max
Length
returnUrl The URL where the user is returned after 200 N String
authentication.
validationMethod Defines the authorization methods used in NA N AuthorizationMet

the security header. See hod
AuthorizationMethod Values on
page 116.
collectionRequest
This structure is not supported as of release 6.0.2.1.
The collectionRequest structure details why a collection is being initiated and the
reasons for the collection. The following table describes the data structure for the
CollectionRequest Structure.
collectionInitiator The initiator for the collection. N CollectionInitiator
collectionReason The reason why the credential is being collected. N CollectionReason
forceCollection Informs the Adaptive Authentication (On-Premise) N Boolean

system that your application wants to force a
collection of the users credentials.
orgCredentialList Enables caller to inform the system which N CredentialList

credentials are maintained by the caller and hence
should not appear in collectable or required
credentials.
collectionInitiator
The collectionInitiator value determines what party is initiating a collection request
for a credential type. This parameter is used within CollectionRequest.
Values Description
USER_INITIATED The user has initiated a collection for a credential.
CSR_INIITIATED The customer service representative has initiated a collection request
AUTO_INITIATED The Adaptive Authentication (On-Premise) system has initiated a collection

request.

collectionReason
The collectionReason value determines why credentials are being collected. This
parameter is used within CollectionRequest.
Credential Type Description
CSR_REQUESTED The customer service representative requested the collection request.
USER_SETTINGS The user has specifically requested that additional credentials be collected.
FIRST_COLLECTION This is the first time a user has been seen by the System, and credential
information needs to be collected.
REFRESH_AFTER_FAILURE A failure occurred. Consequently, another attempt to collect is being made.
ADDITIONAL_COLLECTION Additional information needed to be collected.
REFRESH_COLLECTION A set amount of time has passed, and a refresh of the credentials is needed.
orgCredentialList
The orgCredentialList uses the CredentialList structure. See Credential Structure
on page 141 for more information.
credentialAuthStatusRequest
The credentialAuthStatusRequest structure is used to view the state of a given
credential, and the result of authenticating the users response. See each of these
credential types for specific information regarding each data structure:
Appendix C, Out-of-Band Phone and Email Credential
Appendix D, One-Time Password Credential
Appendix E, Knowledge-based Authentication Credential
Appendix F, Out-of-Band SMS Authentication Credential,
Appendix G, Challenge Question Credential
Appendix H, Authentication Plug-In Credential
Data Structure Description Required Data Type
challengeQuestionAuthS The payload for the challenge question N ChallengeQuestionAuthSt

tatusRequest credential atusRequest
oobEmailAuthStatusReq The payload for the OOB email credential N OobEmailAuthStatusReq

uest uest
oobPhoneAuthStatusReq The payload for the OOB phone N OobPhoneAuthStatusReq

uest credential. uest

acspAuthStatusRequest This structure contains the challenge N acspAuthStatusRequestD

Data request data for the generic authentication ata
plug-in, which is used for authentication
methods such as out-of-band (OOB) SMS
authentication, knowledge-based
authentication (KBA), and one-time
password (OTP).
Note: These data structures are defined as to the number of occurrences allowed per
credentialAuthStatusRequest structure.
The range of the number of occurrences is 0-1. This means the data structures listed
above are optional (0) and a maximum of one occur en ce per structure is allowed (1).
credentialChallengeRequest
The credentialChallengeRequest structure is used to request the results of the
challenge for a specific credential. See each of the following credential types for
specific information regarding each data structure:
challengeQuestionChalle The results of the challenge method for the N ChallengeQuestionChall

nge challenge question credential. enge
oobEmailChallenge The results of the challenge method for the N OobEmailChallenge

OOB email credential.
oobPhoneChallenge The results of the challenge method for the N OobPhoneChallenge

OOB phone credential.
acspChallengeRequestD This structure contains the challenge N acspChallengeRequestD

ata request data for the generic authentication ata
password (OTP).

credentialChallengeRequest structure.

credentialDataList
The credentialDataList structure is used to pass the users information as it pertains to
a specific credential. See each of the following credential types for specific
information regarding each data structure:
challengeQuestionData The payload for the challenge question N ChallengeQuestionData

credential
oobEmailData The payload for the OOB email credential N OobEmailData
oobPhoneData The payload for the OOB phone N OobPhoneData

credential.
acspAuthenticationRequ This structure contains the authentication N acspAuthenticationRequ

estData request data for the generic authentication estData
password (OTP).
credentialDataList structure.

credentialManagementRequestList
The credentialManagementList structure is used to pass a request for managing the
users credential information as it pertains to a specific credential. See each of the
credential types for specific information regarding each data structure:
challengeQuestionMana The payload for the challenge question N ChallengeQuestionManagem

gementRequest credential entRequest
oobEmailManagementR The payload for the OOB email N OobEmailManagementRequ

equest credential est
oobPhoneManagementR The payload for the OOB phone N OobPhoneManagemetnRequ

equest credential. est
acspManagementReques contains management request data for N acspManagementRequestDat

tData generic authentication plug-in, which is a
used for authentication methods such
as out-of-band (OOB) SMS
password (OTP).
credentialManagementRequestList structure.

deviceManagementRequest
The deviceManagementRequest structure contains a request to:
bind a device
unbind a device
name a device
create a device binding
modify a device binding
The following table describes the data structure for the
DeviceManagementRequestPayload.
Max
Length
actionTypeLis The action to be performed on the users device. NA Y DeviceActio

t See DeviceActionTypeList Values on page 123. nType
deviceData The users device information. NA N DeviceData

See DeviceData Structure on page 142.
Note: If the value of actionType is

UPDATE_DEVICES, this parameter is required.
DeviceActionTypeList Values
The following are the values for DeviceActionType.
Values Description
BROWSE_DEVICES View all devices bound to a user.
UNBIND_ALL_DEVICES Unbind all the users device bindings
UPDATE_DEVICES Update the users device binding(s) or add a new device binding.

eventDataList
The following structures are used to document events that occurred within your
Adaptive Authentication (On-Premise) application. The information gathered can be
useful for providing stronger authentication for your users.
Max
Length
eventData A list of the facts that occurred NA Y EventData[ ]
eventData Structure
The eventData structure captures information about a specific event that occurred
during the transaction of the user.
Max
Length
authenticationLevel Information regarding the level of NA N Authenticati

authentication used. See onLevel
AuthenticationLevel Structure on Type
page 126 for the parameters and
Appendix I, Authentication Levels for
a list of levels to use.
clientDefinedAttributeLis The attributes of client defined event, or NA N FactList

t for known events, extra attributes that
are not already defined. See Fact List
on page 144 for more information.
clientDefinedEventType This field allows an organization to 50 N String

specify their own event type, in addition
to the Adaptive Authentication (On-
Premise) default eventType, for the same
event. The Adaptive Authentication (On-
Premise) risk model is run on the event
type combination.
eventDescription A description of the event that took 50 N String

place. This information is to be presented
to the user or within a specific
application (for example: Case
Management).

Max
Length
eventID (Not supported as of release 6.0.2.1) 200 N String

The identification number assigned to
the event.This number should be the
same as transactionID. This field
should not be populated, otherwise, a
warning error (1653) is returned.
eventReferenceID The transactionID number returned by 200 N String

the Adaptive Authentication System
during an analyze response message.
This parameter should only be populated
during a notify call when the eventType
= EXTRA_AUTH.
eventType The type of event that took place in your NA Y EventType

application for that users transaction.
See Supported Event Types on page 85
for the values.
newUserData The information about a new user being NA N UserData

enrolled into your application.
stockTradeData Information specific to a given stock NA N StockTrade

trade Data
See StockData Structure on page 145
for more information.
timeOfOccurrence The date and time of the event. The date Limited to N String
should follow the ISO 8601 format. ISO date supported
The date format is yyyy-MM-dd format by Java
HH:mm:ss.SSS. For example, if the Simple Date
date and time the event occurred is format
September 21,2012 at 3:45 PM, the date
is represented as: 2012-09-21 15:45:00.
Important: If this data element is empty,

then timeStamp in the messageHeader
is used for the event date and time. If
timeStamp is empty, the application will
use the System date and time.
transactionData Information specific to a given NA N Transaction

transaction. Data
See TransactionData Structures on
page 148 for more information.

AuthenticationLevel Structure
For organizations using their own authentication or extra authentication, this structure
allows you to pass the information to the Adaptive Authentication (On-Premise)
system. See Appendix I, Authentication Levels for more information.
Max Data
Length Type
attemptsTryCount The number of times an authentication level (the None N Integer

same or different) were tried until this resulting
level was reached.
level The level of authentication requested, between 1- 4 N Integer

1000.
1= lowest authentication
1000 = highest authentication
See Appendix I, Authentication Levels.
successful Determines if the user passed the requested level NA N Boolean

of authentication.
EventType Values
For a complete list of EventType values, see Supported Event Types on page 85.
runRiskType
The runRiskType element controls execution of the Risk Engine on Adaptive
Authentication transactions. The values of runRiskType are listed in the following
table.
Note: You must set the value in the runRiskType element to either ALL or
RISK_ONLY in order to apply risk analysis on transactions. If you want to disable
risk assessment completely, you must use NONE as the value when you send SOAP
calls. You can check the values in the riskResult element of the AnalyzeResponse
message to verify that the Risk Engine was applied. For more information, see
riskResult on page 167.
RunRiskType Values Description
RISK_ONLY Run a risk analysis without updating the users profile. This value also
creates an event in the audit log for reporting purposes.

RunRiskType Values Description
DEVICE_ONLY Run a device-only risk analysis without calling the risk engine. The analysis
runs against the Policy Engine. This value also creates an event in the audit
log for reporting purposes.
Note: If you have rules that are using a risk score with a less than condition,
you must add an additional condition that says greater than minus one.
ALL Run a risk analysis and update the users profile. This value also creates an
event in the audit log for reporting purposes.
NONE Do not perform any risk analysis or update a users profile
userData Structure
This structure is not supported as of release 6.0.2.1.
The userData Structure contains information specific to a user.
Max
Length
business Determines if the account is a business NA N Boolean

account.
VIP Determines if the account is a VIP account. NA N Boolean
lastAccountOpenDate The date that the account was opened. Limited to N String
The date should follow the ISO 8601 format ISO date
or: format
YYYY-MM-DD HH:mm:SS.mmm (GMT
time)
lastOnlineServicePassw The date that the users password was Limited to N String
ordChangeDate changed. The date should follow the ISO ISO date
8601 format or: format
time)
onlineServiceEnrollDate The date that the user enrolled in the service. Limited to N String
or: format
time)
totalAvailableBalance The users total available balance. NA N Amount

Max
Length
totalCreditLimit The users total credit limit. NA N Amount
totalCreditsUsed The users used credit. NA N Amount
userAddress The users address. NA N UserAddre

See UserAddress Structure on page 128 ss
for more information
userNameData The users name. NA N UserName

See UserName Structure on page 128 for
more information
UserAddress Structure
The UserAddress structure contains specific information regarding the users address.
Max Data
Length Type
addressLastUpdate The date the users address was last updated. Limited to N String
format
addressSetDate The date the users address was originally set. Limited to N String
format
country The users country. The format should follow the 2 N String
ISO 3166 format (two letter country code in
upper case)
postalCode The users postal or zip code. 20 N String
region The users region. 20 N String
UserName Structure
The UserNameData structure contains specific information regarding the users name.
Max
Length
firstName The users first name. 50 N String

Max
Length
lastName The users last name. 50 N String
middleName The users middle name. 50 N String
nameLine NA - Text field that is stored but not used by 100 N String
the system.
prefix The users prefix like Mr., Ms, Mrs. 10 N String
suffix The users suffix, like junior, jr, III, M.D. etc. 10 N String
title The users title. 50 N String
ClientGenCookie Structure
This is an extension to DeviceIdentifier and it allows the sending of a persistent
cookie, generated by your application. One generated cookie can be sent per
transaction.
Parameter Description Max Length Required Data Type
ClientGenCookie Persistent cookie generated by the 512 N String

online application.
MobileDevice Structure
This structure is an extension to DeviceIdentifier and contains elements which support
organizations that use a mobile channel.
Note: Only one MobileDevice should be sent per transaction
Important: Although on their own, the parameters simId, otherId, and hardwareId
are optional, the mobileDevice structure requires that at least one of these parameters
must be populated.

Max
Length
simId The International Mobile Subscriber 50 N String

Identity (IMSI) or Mobile Station
International Subscriber Directory
Number (MSISDN).
Note: This element is currently not

supported by iOS.
otherId A unique identifier that is created by the 50 N String

mobile application itself. For example,
the installation ID.
hardwareId The International Mobile Equipment 50 N String

Identity (IMEI) for GSM. The Mobile
Equipment Identifier (MEID) or the
Electronic Serial Number (ESN) for
CDMA phones.
Note: For iOS devices, RSA

recommends using the WIFI MAC
address.
geoLocation This composite data type consists of NA N GeoLocation

parameters that collect geographical
location information from mobile
devices. For a list of geoLocation
parameters, see GeoLocation on
page 133
deviceModel The model of the mobile device. 50 N String
deviceMultiTaskingSupp Indicates whether or not the mobile 6 N String

orted device supports multi-tasking.
deviceName The mobile device name defined by the 50 N String

end user.
Note: For Android devices, this is the

name defined in your bluetooth settings.
deviceSystemName The operating system of the mobile 20 N String

device.
deviceSystemVersion The operating system version of the 5 N String

mobile device.
languages The languages supported by the mobile 20 N String

device.

Max
Length
wiFiMacAddress The WiFi card MAC address. 20 N String

supported by BlackBerry.
wiFiNetworksData: The basic service set identification 250 N String

BBSID (BBSID) for each basic service set.

supported by iOS.
wiFiNetworksData The WiFi station name. 250 N String

StationName
supported by iOS and BlackBerry.
wiFiNetworksData: The wireless signal strength in the NA N Integer

Signal Strength database management system. The
parameter value is an integer that can be
greater than or less than zero.

supported by iOS.
wiFiNetworksData: The WiFi band is divided into multiple 250 N String

Channel channels, each with different
frequencies. This element defines which
channel is currently being used by the
WiFi connection.

supported by iOS and Android.
wiFiNetworksData: The Service Set Identifier (SSID). 250 N String

SSID
supported by iOS.

Max
Length
cellTowerID A GSM Cell ID (CID) is a unique 20 N String

number used to identify each Base
Transceiver Station (BTS), or sector of a
BTS, within a Location Area Code
(LAC) or GSM network.

supported by iOS.
locationAreaCode The local area code. 20 N String

supported by iOS.
screenSize The screen size of the mobile device. 20 N String
numberOfAddressBook The total number of entries in the mobile 10 N Integer

Entries devices address book.
rsaApplicationkey A unique identifier. 50 N String
wapClientID The unique ID number of the WAP 50 N String

profile client.
Note: This parameter applies to WAP

(mobile internet) sites only.
vendorClientID A unique ID that represents the mobile 50 N String

user, created by an Application vendor.
mcc The mobile country code. 10 N String
mnc The mobile carrier code. 10 N String
osId The ID of the operating system. Options 50 N String

include: Android ID, iPhone UDID, and
Blackberry PIN number.
mobileSDKData A JSON-formatted string consisting of 1024 N String

the values of the mobile device data
elements, collected by the SDK Java
script. See the section about the JSON
schema format in the chapter
Integration Processes in the RSA
Mobile SDK RSA Adaptive
Authentication Module Developers
Guide.

GeoLocation
GeoLocation, a parameter in the MobileDevice data structure, is a composite data type
that consists of parameters that collect geographical location information from mobile
devices. The parameters for GeoLocation are listed in the following table.
Max
Length
longitude The longitudinal line of the mobile devices 20 N Decimal

current location. Degrees
(DD)
latitude The latitudinal line of the mobile devices 20 N Decimal

current location. Degrees
(DD)
horizontalAccuracy Indicates the radius of uncertainty for the 10 N Integer

geo-location of the mobile device. This
element is measured in meters. A negative
value indicates that the geo-location
longitude or latitude of the mobile device is
invalid.
altitude The height of the mobile device above the 10 N Integer

ground. This element is measured in meters.
Note: If the altitude is not available, the

value of this attribute should be null.
altitudeAccuracy The accuracy of the mobile devices 10 N Integer

altitude. This element is measured in
meters.
Note: If the altitude accuracy is not

available, the value of this attribute should
be null. If a value is available, a number
greater than zero must be provided.
heading The direction of travel of the mobile device. 5 N Integer

This element is returned in degrees.
Note: If the heading is not available, the

value of this attribute should be null. If the
hosting device is stationary (the value of the
speed attribute = 0), the value of the heading
attribute must be NaN.

Max
Length
speed The current ground speed of the mobile 10 N Integer

device. This element is returned in meters
per second.
Note: If the speed is not available, the value

of this attribute should be null. If a value is
available, a number greater than zero must
be provided.
timestamp The time at which the geo-location was 22 N Timestamp

created. For example, if the geo-location is in GMT
collected from the cache, then the
timestamp indicates the age of the geo-
location data. This element is returned in
milliseconds.
statusCode The status code. There are four possible NA N statusCode

status codes. For a list of the status codes,
see statusCode on page 134.
statusCode
statusCode refers to the status code of a specific request. The following table lists the
acceptable values for the statusCode options:
Status Code Numeric Value Description
SUCCESS 0 The geo-location is successfully received.
PERMISSION DENIED 1 The location collection process failed because the application
origin does not have permissions to use the geo-location API.
API ERROR 2 The position of the device could not be determined. For
example, one or more of the location providers used in the
location collection process reported an internal error that
caused the process to fail entirely.
API TIMEOUT 3 The geo-location API returns a time out error and there is no
available position to return.

PhoneData
This structure is an extension to DeviceIdentifier and contains elements that support
organizations using a mobile channel.
Note: Only one PhoneData should be sent per transaction.
Max Data
Element Description Required
Length Type
phoneNo The mobile channel phone number 10 N String
countryCode The country from where the mobile 3 N String

channel originates.
areaCode The area code of the mobile channel 5 N String

phone number.
extension The mobile channel phone extension 5 N String

number
Important: If one of the elements in the PhoneData structure is populated, all the
elements in the data structure must be specified except for the parameter extension.

6 Web Services Common Data Structures and

Types
Account Structures
Credential Structures
Device Structures
Fact Structures
Stock Structures
Transaction Structures
This chapter describes the common data structures used in the main request and
response structures.
Note: The Required column indicates which fields are mandatory. RSA also
recommends providing as much information in optional fields as possible to increase
the accuracy of the risk analysis.
Account Structures
AccountData Structure
The structure describes a users bank account.
For international banking purposes, it is necessary to also list the users bank account
number in IBAN format. IBAN is an international standard for identifying bank
accounts across national borders. This international account number format facilitates
the tracking and detection of hijacked fund transfers to mule or unintended payee
accounts.
The following table describes the structure.
Max
Parameter Description Required Type
Length
accountBalance The users account balance. NA N Amount

For more information on this structure, see
Amount Structure on page 139.
accountCategory The category of the account. 20 N String
accountCountry The country that the account is located. 3 N String
6: Web Services Common Data Structures and Types 137

Max
Length
accountCreditLimit The users credit limit for the account. NA N Amount

accountCreditsTurnov Number of times the credit turns over during a NA N Amount

er year.
accountCreditsUsed The amount of credit used on this account. NA N Amount

accountDailyLimit The amount of the daily limit on the account. NA N Amount
accountLastCreditGran The date the user was last granted credit. Limited to N String
tDate The date should follow the ISO 8601 format ISO date
or: format
time)
accountName The account name. 200 N String
accountNickName The account nickname (i.e. personal, joint, 200 N String

etc.)
accountNumber The users account number. 50 N String
Note: New customers must enter the account

number in IBAN format. Existing customers
must continue to enter the account number in
the standard format to maintain the user
profile.
internationalAccountN The users account number in IBAN format. 100 N String

umber
accountOpenedDate The date the users account was opened. Limited to N String
or: format
time)
accountOwnershipTyp The ownership type of the account. NA N Account

e Ownershi
pType
138 6: Web Services Common Data Structures and Types

Max
Length
accountRelationType The authorization level of the user accessing NA N Account

the account. Relation
Type
accountType The account type. For a list of values, see NA N Account

AccountType on page 140. Type
clientDefinedAccount The type of account as defined by your 256 N String

Type organization.
externalRiskScore The risk score calculated by your organization. NA N Integer
liquid A Boolean value that determines if the users NA N Boolean

account is liquid.
nextLiquidDate The next date that the users account is liquid. Limited to N String
or: format
time)
referenceCode Organization reference code. 50 N String
routingCode Bank routing code. 50 N String
swiftCode An international code for wire transfers. Not 256 N String

applicable in the U.S.
Amount Structure
The following table describes the data elements for the Amount structure. Enter both
the amount and the currency if an amount value exists.
Max
Length
amount The amount for the given transaction in the NA N Long

original currency. Enter the value in the lowest
monetary denomination for that currency.
For example, $100 USD = 10000 cents.
amountInUSD The value of the parameter, amount, converted to NA N Long

USD, by a static currency conversion table. See
note below.
currency The original currency of the parameter amount, 3 N String

according to the ISO standard 4217 (alphabetic
code).

Note: RSA recommends to convert the amount in original currency to USD and enter
the converted amount to the parameter, amountInUSD. This is because the monetary
conversion rates in the static conversion table are not kept current.
AccountOwnershipType Values
The following table lists the Account ownership type values.
Values Description
BUSINESS Business account.
CUSTODIAL Custodial account.
INDIVIDUAL Individual account.
JOINT Joint account.
TRUST Trust account.
AccountRelationType Values
The following table lists the Account relation type values..
Values Description
AUTHORIZED_USER The user is an authorized user of the account.
CO_OWNER The user is a co-owner of the account.
PRIMARY_OWNER The user is the primary owner of the account.
AccountType
The following table lists the Account type values.
Values Description
BROKERAGE The account is a brokerage account.
CD The account is a CD.
CHECKING The account is a checking account.
CHECKING_WITH_OVERDRAFT The account is a checking account with overdraft protection.
CREDIT_CARD The account is for a credit card.
DEBIT_CARD The account is for a debit card.
LINE_OF_CREDIT The account is for a line of credit.

Values Description
MORTGAGE The account is for a mortgage.
RETIREMENT The account is a retirement account.
SAVINGS The account is a savings account.
USER_DEFINED The account has been specifically defined by your company.
Credential Structures
CredentialList Structure
The following is a structure of the credential list.
credential The list of credentials. N Credential[ ]
Credential Structure
This structure defines the information for a credential. The following table describes
the data structure parameters.
Max
Length
credentialStatus Allows you to change the status of NA N CredentialStatus

the credential type you want to
use. See CredentialStatus on
page 141.
credentialType The type of credential. See NA N CredentialType

CredentialType Values on
page 142 for a list of the values
you should pass.
CredentialStatus
Each credential can have a specific status associated with it.
Credential Status Description
ACTIVE The specific credential is active for use by your application.
DISABLED The specific credential is not currently active for use by your application.

Credential Status Description
LOCKED (Not Supported as of Release 6.0.2.1)

The specific credential is locked from use.
UNLOCKED (Not Supported as of Release 6.0.2.1)

The specific credential has been unlocked.
CredentialType Values
If you are using the RSA Adaptive Authentication (On Premise) credential types, use
one of the following values.
QUESTION The Challenge Question Credential type.
OOBPHONE The OOB Phone Credential type.
OOBEMAIL The OOB Email Credential type.
USER_DEFINED The Authentication Plug-In credential type defined

by the organization, which is used for authentication
methods such as OOB SMS, knowledge-based
authentication (KBA), and one-time password (OTP).
Device Structures
DeviceData Structure
The following table defines the parameters that comprise the DeviceData structure.
Max
Length
bindingType The type of binding to be performed. You can NA N BindingType

update the binding type to NONE or
HARD_BIND.
Note: If the value of

deviceManagementRequest/actionType is
UPDATE_DEVICES, this parameter is
required.

Max
Length
deviceTokenCookie (Not for deviceManagement structure. 256 N String

This structure is used for deviceResult)
The cookie information.
If this is in the deviceResult structure, this
cookie is an encryption of the deviceID and a
timestamp. This cookie should be placed on
the users device.
If you do not want a new cookie with each
response, you need to change your device
configurations. For more information, see the
Operations Guide.
deviceTokenFSO (Not for deviceManagement structure. 256 N String

This structure is used for deviceResult)
The value of the Flash Shared Object.
If this is in the deviceResult structure, this
cookie is an encryption of the deviceID and a
timestamp. This cookie should be placed on
the users device.
If you do not want a new cookie with each
response, you need to change your device
configurations. For more information, see the
Operations Guide.
lookupLabel This is the label used to lookup a users device, 64 N String
newLabel A new label or nickname for the users 64 N String

device information. For example work or
home.
BindingType Values
The following are the values for the BindingType.
Values Description
HARD_BIND The device token is bound to the users device.
NONE No device has been bound.

Fact Structures
A Fact structure gives information (or facts) about a user and their activity.
Fact List
Parameter Description Max Length Required Type
fact A list of the facts that occurred. NA N Fact[ ]
Fact Structure
Parameter Description Max Length Required Type
name The name of the fact. NA Y String
value The value of the fact being sent. NA Y String
dataType The data type of the fact being sent. NA Y DataType
DataType Values
The purpose of the dataType parameter is to describe the type of data entered for the
value parameter of the Fact Structure. The values for the Data Type parameter are
listed in the following table.
Value Description
STRING A contiguous sequence of alphanumeric symbols or values.
INTEGER A whole number (not a fraction) that can be positive, negative, or zero.
BOOLEAN A logical data type having two values denoted True and False.
FLOATING POINT A real number that can be positive, negative, or zero and includes a floating
decimal point.
DOUBLE A double-precision floating-point number that can be positive, negative, or

zero.
DATE A string that stores year, month, and day values in a given format such as MM/
DD/YYYY. (Not supported as of Release 7.0)
IP A string of digits separated by periods that comprise an IP address

Stock Structures
The following is a listing of all the AuthRequest Elements and for which methods they
are required. Parameters are listed in alphabetical order.
StockData Structure
This structure contains information about a single piece of stock. The following table
describes the data structure for the stockData Structure.
Max
Length
currentMarketPrice The current market price for that stock. NA N Amount

See Amount Structure on page 139 for more
information on this structure.
ETF Indicates whether the stock is of an Exchange NA N Boolean

Traded Fund.
OTC Indicates whether the stock is an Over The NA N Boolean

Counter stock.
SP500 Indicates whether the stock is part of the Standard NA N Boolean

and Poors 500.
last30DaysAverageP The average price of the stock within the last 30 NA N Amount
rice days. See Amount Structure on page 139.
last30DaysAverage The average volume within the last 30 days. NA N Integer

Volume
last30DaysHighPric The high price of the stock within the last 30 NA N Amount
e days. See Amount Structure on page 139.
last30DaysLowPrice The lowest price of the stock within the last 30 NA N Amount
days.
See Amount Structure on page 139.
percentSharesHeldB The percentage of the shares that are held by the NA N Integer
yInstitution organization.
sharesFloating The number of floating shares in the marketplace NA N Integer

available to trade.
sharesOut The total number of shares issued (or NA N Integer

outstanding) by the company being traded.
symbol The stock symbol. 256 N String

Max
Length
todayHighPrice The high price of the stock as of the current day. NA N Amount
todayLowPrice The lowest price of the stock as of the current NA N Amount

day. See Amount Structure on page 139.
todayOpenPrice The opening price of the stock. See Amount NA N Amount

Structure on page 139
todayVolume Todays volume pricing. NA N Integer
StockTradeData Structures
This structure contains information about a single stock trade.
Max
Length
AllOrNone A flag that determines to sell ALL stock or NA N Boolean

NONE.
lowerChangeLimit Low point of stock price for trade consideration NA N Integer
lowerPrice For more information on this structure, see NA N Amount

numberOfShares The number of shares to be purchased. NA N Integer
priceType This value is for stock pricing data. NA N PriceType
stockData For more information on this structure, see NA N StockData

StockData Structure on page 145.
termType This value is related to stock order types. NA N TermType
tradeType This value is used for commodities and stock NA N TradeType

trade activities.
upperChangeLimit High point of stock price for trade consideration NA N Integer
upperPrice For more information on this structure, see NA N Amount

Common Values for Stock Structure Data Elements

The following are some of the common values for the Stock structures.

PriceType Values
PriceType values are listed in the following table.
Value Description
BRACKETED_FIXED Fixed range in relation to a price change limit
BRACKETED_PERCENTAGES Change from the original price, in percentage
BRACKETED_POINTS Change from the original price, in points,

determined by technical analysis
MARKET Market value based
Brackets are related to the values of lowerChangeLimit and upperChangeLimit, and

can be expressed as amount from the original, points (as determined by technical
analysis), or percentage of the stock price.
TermType Values
TermType values are listed in the following table.
Value Description
FILL_OR_KILL An order that needs to be completely filled or completely cancelled
GOOD_FOR_DAY A day buy or sell order remains in effect for that trading day otherwise, it is
cancelled.
GOOD_UNTIL_CANCELLED An order to buy or sell that remains valid until executed or cancelled.
IMMEDIATE_OR_CANCEL An order requiring that all or part of the order be executed immediately
after it has been brought to the market. Portions not immediately executed
are automatically cancelled.
TradeType Values
TradeType values are listed in the following table.
Value Description
BUY Buy the order.
BUY_TO_COVER An order placed to close out a short position in a particular stock.
SELL Sell the order.
SELL_SHORT Selling a security that is not actually owned in the hope of buying it back at a lower
price.

Transaction Structures
The following is a listing of all the AuthRequest Elements and for which methods they
are required. Parameters are listed in alphabetical order.
TransactionData Structures
The TransactionData structure comprises the details of the specific transaction. It
includes:
the receivers account information, in the case where monies are transferred from
the users account (bill pay or transfer)
the source of the funds, in the case where money is deposited into the users
account. Data elements are otherAccount*
Max
Length
amount The amount of the transaction. NA N Amount

dueDate For scheduled transactions, the due date Limited to N String

of the transaction. ISO date
For recurring transactions, the due date format
of the first payment.
The date should follow the ISO 8601
format or:
time)
estimatedDeliveryDate For non real-time transactions, this date is Limited to N String

the estimated time the funds will be ISO date
transferred to the payee. format
The date should follow the ISO 8601
format or:
time)
executionSpeed This value determines how fast a NA N ExecutionS

transaction will take place. peed
See OtherAccountBankType Values on
page 150.
myAccountData Information about the source account from NA N AccountDat

which the transaction takes place. a
For more information, see AccountData
Structure on page 137.

Max
Length
otherAccountBankType The type of bank account. NA OtherAccou

See OtherAccountBankType Values on ntBankType
page 150.
otherAccountData Information about the receivers account. NA N AccountDat

For more information on this structure, see a
otherAccountType This value indicates whether the account is NA N OhterAccou

a Biller or a Private Account. ntType
otherAccountOwnershi This value indicates whether the money NA N OtherAccou

pType transfer is between accounts of the same ntOwnershi
person or different people. pType
This field is only relevant when the
accountType =
PERSONAL_ACCOUNT.
See OtherAccountOwnershipType
Values on page 150.
previousAmount The previous standing order amount (prior NA N Amount

to payment).
recurringFrequency The approximate number of days between NA N Integer

a recurring transaction.
NOTE: This value is used for risk
assessment purposes and not for the actual
payment. An exact number is not required.
It can be set to 30 for a monthly recurring
payment, 15 days for twice a month
payment, 90 days for quarterly, etc.
schedule This value determines all the available NA N Schedule

transaction schedules.
See Schedule Values on page 150.
transferMediumType This value determines the different NA N TransferMe

methods of carrying out a transaction. diumType
Values for Transaction Structure Data Elements

This section details the specific String values for various data elements within
Transaction structures.

ExecutionSpeed Values
ExecutionSpeed values are follows:
Values Description
FEW_HOURS Execution of the action takes place within a few hours.
OVER_NIGHT Execution of the action takes place within over night.
REAL_TIME Execution of the action takes place in real time.
SEVERAL_DAYS Execution of the action takes place within a few days.
OtherAccountBankType Values
OtherAccountBankType values are as follows.
Values Description
OTHER_BANK The recipients account is with another bank.
SAME_BANK The recipients account is within the same bank.
OtherAccountOwnershipType Values
OtherAccountOwnershipType values are as follows.
Values Description
ME_TO_ME Money transfers between accounts of the same person.
ME_TO_YOU Money transfers between accounts of different people.
OtherAccountType
OtherAccountType values are as follows.
Values Description
BILLER Used for bill payment.
PERSONAL_ACCOUNT Used for transfer to a different personal account
Schedule Values
Schedule values are as follows.
Values Description
IMMEDIATE The action is immediate.

Values Description
RECURRING The action is recurring within a set time frame.
SCHEDULED The action is scheduled.
TransactionMediumType Values
TransactioMediumType values are as follows.
Values Description
ACH The transaction is an ACH payment.
BALANCE_TRANSFER The transaction is a balance transfer.
BILLPAY_ELEC The transaction is an electronic bill pay.
BILLPAY_MAIL The transaction is a bill pay via mail.
CHECK The transaction is via a check.
INTERNAL The transaction is internal.
INTL_WIRE The transaction is via international wire.
WIRE The transaction is via a domestic wire.

7 Web Services Response Data Structures

and Types
browsableGroupNames
collectableCredentialList
credentialAuthResult
credentialAuthStatusResponse
credentialChallengeList
credentialManagementResponseList
deviceManagementResponse
requiredCredentialList
riskResult
systemCredentials
userCredentials
This chapter describes all the data structures and substructures used in response
messages for each method type.
Note: Some of the data structures defined in this chapter are also used in request
messages. For request messages, data elements can be required or optional. For
response messages, all data elements are optional.

The following table lists the data structures and the methods that use the data
structure.
deviceResult All Responses
identificationData All Responses
messageHeader All Responses
statusHeader All Responses
7: Web Services Response Data Structures and Types 153

browsableGroupNames Query Response
collectableCredentialList Analyze Response
credentialAuthResult Analyze Response

Authenticate Response
Challenge Response
credentialAuthStatusResponse QueryAuthStatus Response
credentialChallengeList Challenge Response
credentialManagementResponseList CreateUser Response

Query Response
UpdateUser Response
deviceManagementResponse Analyze Response

Challenge Response
CreateUser Response
Query Response
UpdateUser Response
requiredCredentialList Analyze Response

riskResult Analyze Response

CreateUser Response
UpdateUser Response
systemCredentials CreateUser Response

Query Response
userCredentials Query Response
154 7: Web Services Response Data Structures and Types


The following section lists the generic structures used in all methods.
deviceResult
The deviceResult structure contains information about the authentication of that
device. The following table describes the data structure for the DeviceAuthResult
Structure.
Parameter Description Type
authenticationResult The result of the authentication. AuthenticationResult
callStatus The status of the Web Services call. See CallStatus CallStatus
Structure on page 166.
deviceData The list of devices and the resulting authentication for each DeviceData Structure
of the devices sent in DeviceResponse.
AuthenticationResult
The following table describes the authentication result returned from all credentials.
risk The credential risk score. This parameter is different from the value Integer
returned in riskResult.
authStatusCode The result of the credential verification (i.e. did the user pass the String
credential?).
See AuthStatusCode Values.
AuthStatusCode Values
authStatusCode Values Description
FAIL The user failed to pass the credential.
SUCCESS The user successfully passed the credential challenge.
PENDING The authentication of the credential is still pending.

identificationData
clientSessionId The clients session ID value. String
clientTransactionId The clients transaction ID value String
delegated Is the request coming from a customer service representative? Boolean
groupName The group to which the user belongs. String
Note: This parameter is not returned in the response when the user does
not belong to a group.
newUserName If the user has changed their user name, use this field to pass the new user
name (using updateUser method).
orgName The organization to which the user belongs. String
sessionId The ID of a given session provided by the Adaptive Authentication String

system.
If this parameter is passed in a response message, you need to resend it in
any subsequent request message in order to maintain session persistence.
transactionId The ID of a specific event for a given transaction. Each session might String
contain different transactions. Only one transaction can occur at any given
time.
This parameter is returned on when the runRiskType = ALL.
However, you only need to return this parameter under two
circumstances:
when a sessionID is also returned in the same response, which usually
occurs when actionCode = CHALLENGE
when you pass eventType = EXTRA_AUTH in a notify request
message, this parameter should be entered in the eventReferenceID
parameter.
If this parameter is passed in any other request message other than what is
described above, an error message occurs.
Note: Do not pass this parameter if it is a separate AnalyzeRequest

message. Otherwise, an error occurs.
userCountry The country portion of the users locale. String
userLanguage The language portion of the users locale. String
userLoginName The name entered by the user when they log into your application. This String
parameter can change. This differs from the userName parameter.

userName The internal representation of the userLoginName. This parameter should String
not change for the user.
Note the difference between userLoginName and userName.
userStatus The status of the user. See AuthStatusCode Values on page 155. UserStatus
Type
userType The type of user. See UserType Values on page 157. UserType
UserStatusType Values
Values Description
DELETE The user has been marked as deleted in the Adaptive Authentication
system. The user is not actually removed, but is merely marked as
deleted.
LOCKOUT The user is locked out of their user account.
NOTENROLLED The user is not enrolled.
UNLOCKED The user has been unlocked.
UNVERIFIED The user has enrolled, but is not yet verified by your application.
VERIFIED The user is enrolled and is verified.
UserType Values
The userType defines the type of user that is being sent.
Values Description
BAIT The user has been flagged as a user that was purposefully given wrong
information about an account.
NONPERSISTENT The user is a fraudulent user.
PERSISTENT The user is a true user of the system

messageHeader
The messageHeader structure contains general message information, such as message
type, version of the RSA Adaptive Authentication (On Premise) system, and the
timestamp of the message.
requestId This value is unique per request and should be generated by the String
requested.
requestType This is the type of method that you want to invoke. See Request
RequestType Values on page 158. Type
timestamp The timestamp of the header. The date should follow the ISO 8601 String
format or: YYYY-MM-DD HH:mm:SS.mmm (GMT time)
version The version of the Web Services being used. The value is 7.0. String
RequestType Values
The RequestType values correspond to the different methods. Choose the method that
you want to invoke the request message. For more information, see Chapter 3, Web
Services API Methods.
Values Description
ANALYZE This method performs one of two tasks:

a risk analysis for one ore more list of events
AUTHENTICATE This method performs verification for one or more credentials.
CHALLENGE This method returns the challenge material to be presented to the user.
CREATEUSER This method is an explicit call that creates a user. This method returns the
information that you should gather from the user during enrollment.
(Optional) This method can also determine how risky a user is to enroll.
NOTIFY This method allows the organizations application to notify the Adaptive
Authentication system of any application events that can be added to the systems
profiles.
Note: This notification does not trigger a policy nor does it create case in the Case
Management application.
QUERY For asynchronous credentials, this method returns the authentication status of that
credential.
QUERYAUTHSTATUS This method queries a users profile and any system level browse-able data.

Values Description
UPDATEUSER This method updates a users profile.
statusHeader
The statusHeader structure is returned by the Generic Response, and contains
information about the message status. It only exists in the response message for any
method call.
reasonCode A more detailed explanation of the statusCode being returned. For a Integer
detailed list of the reasonDescriptions, see Appendix J, API Error
Messages.
reasonDescription An explanation of the Web Services call status. For a detailed list of the String
reasonDescriptions, see Appendix J, API Error Messages.
statusCode The status code of the Web Services operation. Integer

statusCode Values
The statusCode indicates the overall status of the Web Services operation.
statusCode Description Additional Information
200 The Web Services operation was completed This value refers to the completion of an
successfully. actual Web Services call and means that all
Web Services features are functioning
correctly.
300 A warning acknowledging the failure of one or For example, a createUser request is issued.
more actions taken by an API call. This method request not only creates a new
A single API call executes one or more actions. user but also defines the authentication
If one action fails, the others may succeed. This method for the user. For some reason, such
warning notifies the user to check for the one or as a field validation violation, the
more failed actions. registration to the authentication method
fails.
A 300 error code is returned in the
createUser response and the credentials
payload is returned with an error. As a result,
the user exists without an authentication
method.
In this situation,
An updateUser request must be issued to
define the authentication method for the
user.
The error that occured in the createUser
request must be corrected to avoid another
failure.
500 A system error occurred. The operation failed. This is possibly an error in the Adaptive
Authentication application. Contact the RSA
Advanced Technical Support.
510 A process error occurred. The operation failed. Either the data in the element is incorrect, or
the wrong element is being sent.
Alternatively, the data that is required to
properly complete the request is not
available (e.g. the database is not
responding).

browsableGroupNames
This value contains the list of groups to which a group can belong. It is of a String
array type.
browsableGroupNames The list of group names to which the user can belong. These String
group names are defined by your organization in your
Configuration Tree. This structure is only used by the query
method.
collectableCredentialList
This structure is Not Supported as of Release 6.0.2.1.
The following table lists the credentials that are required.
collectableCredenti This parameter defines the collectable credential type. CollectableCred

al ential
CollectableCredential Structure
The following table lists the collectable Credential structure parameters.
collectionReason The reason why a credential is being collected. See collectionReason CollectionReason
Values on page 161.
collectionType The type of collection. See CollectionType Values on page 162 for CollectionType
more information.
credentialType The type of credentials to be collected. If you are using the Adaptive CredentialType[ ]
Authentication credentials, see CredentialType Values on page 162
for a list of values.
collectionReason Values
The collectionReason value determines why credentials are being collected. This
parameter is used within CollectionRequest.
Value Description
CSR_REQUESTED The customer service representative requested the collection request.

Value Description
USER_SETTINGS The user specifically requested that additional credentials be collected.
FIRST_COLLECTION This is the first time a user has been seen by the system and credential
information needs to be collected.
REFRESH_AFTER_FAILURE A failure occurred. Consequently, another attempt to collect is being made.
ADDITIONAL_COLLECTION Additional information needed to be collected.
REFRESH_COLLECTION A set amount of time has passed, and a refresh of the credentials is needed.
CollectionType Values
Value Description
OPTIONAL_COLLECTION Collecting the credential is optional.
REQUIRED_COLLECTION Collecting the credential is required for authentication.
Use the following values if you are using the Adaptive Authentication credentials.
Value Description
OOB_PHONE The OOB Phone Credential type.
OOB_EMAIL The OOB Email Credential type.
USER_DEFINED The Authentication Plug-In credential type defined by the

organization. This credential type is used for authentication
methods such as OOB SMS, knowledge-based
authentication (KBA), and one-time password (OTP).
credentialAuthResult
This structure is used as the response message for the methods, analyze and
authenticate, and each credential structure is specific to each type of credential. For
more information about the individual data structures listed here, refer to the specific
credential payloads.
challengeQuestionAuthResult The result for the challenge question ChallengeQuestionAuthResult

credential authentication.

oobEmailAuthResult The result for the OOB email credential OobEmailAuthResult

authentication.
oobPhoneAuthResult The result for the OOB phone OobPhoneAuthResult

credential authentication.
acspAuthenticationResponseData contains authentication response data AcspAuthenticationResponseD

for generic authentication plug-in, ata
which is used for authentication
methods such as out-of-band (OOB)
SMS authentication, knowledge-based
password (OTP).
credentialAuthStatusResponse
This structure is similar to the request message for the method, queryAuthStatus, and
each credential structure is specific to each type of credential. For more information
about the individual data structures listed here, refer to the specific credential payloads
challengeQuestionAuthStatusR The payload for the challenge question ChallengeQuestionAuthStatus

esponse credential Request
oobEmailAuthStatusResponse The payload for the OOB email credential OobEmailAuthStatusRequest
oobPhoneAuthStatusResponse The payload for the OOB phone OobPhoneAuthStatusRequest

credential.
acspAuthStatusResponseData Challenge response data for the generic AcspAuthStatusResponseData

authentication plug-in, which is used for
authentication methods such as out-of-
band (OOB) SMS authentication,
knowledge-based authentication (KBA),
and one-time password (OTP).

credentialChallengeList
This structure is used as the request message for the method, challenge. For more
information about the individual data structures listed here, refer to the specific
credentialChallengeList A list of all the credentials requested. CredentialChallenge[ ]
credentialChallenge
This structure is used as the response message for the method, challenge. For more
challengeQuestionChallenge The payload for the challenge question ChallengeQuestionChallenge

credential.
oobEmailChallenge The payload for the OOB email credential. OobEmailChallenge
oobPhoneChallenge The payload for the OOB phone OobPhoneChallenge

credential.
acspChallengeResponseData This contains challenge response data for AcspChallengeResponseData

generic authentication plug-in, which is
used for authentication methods such as
out-of-band (OOB) SMS authentication,

credentialManagementResponseList
credentialManagementResponseL A list of all the credentials requested. CredentialManagementResponse[

ist ]
credentialManagementResponse
This structure is used as the response message for the method, createUser, query, and
updateUser. Each structure is specific to the credential type being used. For more
challengeQuestionManagementRe The response payload for challenge ChallengeQuestionManageme

sponse question credential. ntResponse
oobEmailManagementResponse The response payload for OOB email OobEmailManagementRespon

credential. se
oobPhoneManagementResponse The response payload for OOB phone OobPhoneManagemetnRespo

credential. nse
acspManagementResponeData This contains management response data AcspManagementResponeDat

for generic authentication plug-in, which a
is used for authentication methods such as
out-of-band (OOB) SMS authentication,
deviceManagementResponse
This response structure is used to bind, unbind, name a device, create or modify a
device binding bindings. The following table describes the data structure for the
DeviceManagementResponse Structure.
acspAccountID Each Authentication Plug-In (or credential) returns a specific String

Authentication Plug-In account ID based on the users ID and the
Authentication Plug-In that they are using.
callStatus The status of the Web Services call. CallStatus

deviceData See DeviceData Structure on page 142. DeviceData

Structure
CallStatus Structure
statusCode The status code of the call. String
statusDescription Explanatory text about the status code. See StatusCode Values StatusDescription
below.
StatusCode Values
statusCode Values Description
OK The call successfully was passed.
SYSTEM_ERROR There was a system error.
INVALID_USER_REQUEST Your application passed an invalid request.
StatusDescription Structure
description Explanatory text about the status String
requiredCredentialList
A list of the credentials that are required.
requiredCredential The type of credentials to be collected RequiredCredential[ ]

RequiredCredential Structure
The RequiredCredential structure is a contained with the analyze response message,
and is used to indicate what credentials are required to be collected from the user by
your application. The following table describes the data structure for the
RequiredCredential Structure.
credentialType The type of credentials to be collected. If you are using the CredentialType
Adaptive Authentication credentials, see CredentialType
Values on page 142 for a list of values.
groupName The users group name. String
preference The users milter preference. Integer
required A Boolean value that determines if the credential is required. Boolean
Use the following values if you are using the Adaptive Authentication credentials.
OOB_EMAIL The OOB email credential type.
OOB_PHONE The OOB phone credential type
USER_DEFINED The Authentication Plug-In credential type defined by the organization. This
credential type is used for authentication methods such as OOB SMS, knowledge-
based authentication (KBA), and one-time password (OTP).
riskResult
The riskResult element contains information about the risk analysis performed on
transactions.
Note: The parameters in the riskResult element reflect the values set in the
runRiskType element of the AnalyzeRequest. For more information, see
runRiskType on page 126
riskScore The risk score assigned to the event during the logon or a risk analysis. Integer

riskScoreBand The risk score band assigned to the event during the logon or a risk String
analysis
triggeredRule The rule triggered during the risk analysis. See TriggeredRule Triggered
Structure on page 168. Rule
triggeredTestRule If any rules are being tested, this value lists out the test rules that are Triggered
triggered during a risk analysis. See TriggeredRule Structure on Rule
page 168.
TriggeredRule Structure
This structure contains information about the specific rule that is triggered during the
risk analysis.
actionCode Indicates the action recommended by the triggered rule. See ActionCode
ActionCode Values on page 168.
actionName The name of the action taken when the rule was triggered. String
actionType Indicates the type of action to be taken, based on the actionCode. See ActionApplyType
ActionApplyType Values on page 169.
clientFactList The general facts about the triggered rule. Fact

See Fact Structure on page 144.
ruleId The rule ID number. String
ruleName The rule name. String
ActionCode Values
The ActionCode indicates the action recommended by a triggered rule. These are the
list of actions that can be executed if triggered by an Adaptive Authentication
predefined rule set.
ActionCode Values Description
ALLOW Allow the transaction.
CHALLENGE Challenge the user using challenge-response credential.
DENY Deny the transaction.
NONE No recommendation.
REVIEW Allow the transaction, but flag for later review.

ActionApplyType Values
The ActionApplyType defines the actionType to be taken in regards to the
recommended policy; in other words, what your organization will decide to do with
the policy recommended by the Adaptive Authentication system. This structure is sent
to the Adaptive Authentication system in the request message of the methods:
createUser, query, and updateUser.
The values for ActionApplyType are:
actionType Values Description
STRICT Take action only if the actual action code is stricter than the recommended
policy.
LIGHT Take action only if the actual action code is lighter than the recommended
policy.
OVERRIDE Always use the actual action code, regardless of the recommended policy.
LOG Do not take action, but log the event as a Adaptive Authentication event.
NONE Do not take action and do not log the event.

serverRedirectData
This structure is Not Supported as of Release 6.0.2.1.
The ServerRedirectData structure is returned by the analyze response message. It
informs your application of where to redirect the user if they need to be authenticated.
This structure is in response to the clientReturnData structure sent in the request
message.
redirectUrl The URL where the user needs to be redirected. String
secretKey The key for redirection. String
systemCredentials
This structure is of type CredentialList.
CredentialList Structure
A list of the credentials.
credential The list of credentials. See Credential Structure on page 141 for Credential[ ]
more information.
userCredentials
Max
Length
userCredentials The users credential. CredentialList

See CredentialList Structure on
page 141.

8 AdminService Basic Processes

Processes and AdminService Methods
Retrieving User Information Process
Unlocking a Users Account
Locking a Users Account
Unenrolling a User
Terminate Authentication Sessions
This chapter provides examples of processes that use the AdminService methods and
describes their functionality.
Processes and AdminService Methods

The following table describes the processes and the AdminService methods used by
these processes.
Process Description Methods Used
Retrieving User Information Get a users information about their account. getUserStatus
The customer service representative can getUserChangeHistory
retrieve the users current status or the users
change history.
Unlocking a Users Account Allows the customer service representative to getUserStatus

unlock a users account when they have been getUserChangeHistory
locked out. setUserStatus
unlockUser
Locking a Users Account Allows the customer service representative to getUserStatus

lock a users account. getUserChangeHistory
setUserStatus
Unenrolling a User from the Remove a user from the system. getUserStatus
System deleteUser
Terminate Authentication Terminate abandoned open user resetOpenSessions

Sessions authentication sessions. getUserChangeHistory
8: AdminService Basic Processes 171

Retrieving User Information Process

This process allows a Customer Service application to retrieve the status of a users
account in the system. The customer service representative can retrieve:
users account status informationthe users account status details.
users change history informationthe last actions taken on the users account.
User Scenario for Retrieving User Information

The following is an example scenario in which the user can update their information.
A user calls the Customer Service line in order to get an update about their
account or enrollment into the system. The customer service representative using
their adminID can access a user account status by submitting the user ID
information.
Unlocking a Users Account

One example of this process allows the customer service representative to unlock an
existing user account after a user has been locked out of their account due to too
many incorrect login attempts.
Your organization might have an alternative process for unlocking a user account
based on your existing policies.
172 8: AdminService Basic Processes

User Scenario for Unlocking User Accounts

The following is an example of a user scenario in which a user may be locked out of
their Adaptive Authentication (On-Premise) account.
A user repeatedly failed to correctly answer the challenge question(s) causing
RSA Adaptive Authentication (On Premise) to lock out their account.
Locking a Users Account

An example of this process allows the customer service representative to lock an
existing users account for any number of reasons, such as the user contacting your
organization about a hijacked account. Your organization might have other rules and
policies to determine why a users account should be locked.
This process uses the following methods:
getUserStatus
lockUser


Unenrolling a User
This process allows the customer service representative to mark a user name as
removed from the system. The users Adaptive Authentication (On-Premise)
information is not deleted, but is marked as unused.
Note: Once a user is unenrolled from the system, the account status is marked as
UNVERIFIED. The user information is not deleted from the Adaptive Authentication
(On-Premise) database.
User Scenarios for Unenrolling Users

The following are some examples of user scenarios in which a user might be deleted.
A user does not complete their enrollment and has forgotten the enrolment
information. The user needs to start the enrollment process over.
A user has closed their account and you would like to remove them from the
system.

Terminate Authentication Sessions

This process allows the customer service representative to terminate abandoned open
authentication sessions for a specified user. The terminated sessions can be monitored
using the user change history value Reset Session (S).
If the Administration Console parameter Open Case for Events on Session
Termination is set to True, a case is automatically opened for each terminated
session.
User Scenarios for Terminating Authentication Sessions

The following are some examples of user scenarios in which an authentication session
might be terminated.
The user attempts to log on to Adaptive Authentication (On-Premise). However,
the number of open sessions for the user has reached the maxmum allowed for
that user. The customer representative decides to terminate the open sessions for
the user to allow the user to log on to the application.
The customer representative terminates the open sessions for a user. A case is
automatically opened for each terminated session because the Administration
Console parameter Open Case for Events on Session Termination is set to True.
The customer representative terminates the open sessions for a user. The user
monitors the terminated sessions for a user by reporting all the sessions flagged
Reset Session (S) in the user change history information.

9 AdminService API Methods

Overview of AdminService API Methods
Request and Response Messages for AdminService Methods
deleteUser Method
getUserChangeHistory Method
resetOpenSessions Method
getUserStatus Method
setUserStatus Method
unlockUser Method
lockUser Method
This chapter briefly summarizes the various methods of AdminService. It does not
describe the workflows using these methods. For more information about the
Adaptive Authentication Web Services workflows, see Chapter 8, AdminService
Basic Processes.
Overview of AdminService API Methods

AdminService provides administrative applications through the use of Web Services.
All methods accept an AdminRequest element and returns an AdminResponse
element.
The following figure shows a high level overview of how the individual methods fit
into the overall online system workflow.
9: AdminService API Methods 177

178 9: AdminService API Methods

The various methods for AdminService are listed in the following table.
Method Description
deleteUser Unenrolls a user, if the user status is enrolled.
getUserChangeHistory Returns the history of a user for a set time period.
resetOpenSessions Terminates the abandoned open authentication sessions for a user
getUserStatus Returns the status of a user (for example: not enrolled, locked, etc.)
setUserStatus Changes the status of a user.
unlockUser Unlocks a user if their status is locked.
lockUser Locks a users account.
Sample SOAP messages are provided for the methods listed.

User credentials can be passed either using the URL or in the SOAP message payload,
depending on the value of the Administration Console parameter, Admin Caller
Credentials Passed in Payload. This parameter determines the URL for the Adaptive
Authentication Admin service methods.
Use the following endpoint URL according to the value of the parameter:
If the Administration Console parameter Admin Caller Credentials Passed in
Payload is True, use this URL:
AdaptiveAuthenticationAdmin
If the Administration Console parameter Admin Caller Credentials Passed in
Payload is False, use this URL:
AdaptiveAuthenticationAdmin?username=[caller Id]& password=[caller password]
Request and Response Messages for AdminService Methods

Each AdminService Method contains the following groups of data elements:
A generic request or generic response message
A specific method request or response messages. Each method contains extra
elements that extend either the generic request or generic response messages.

The following figure shows how each specific request and response message extends
the GenericRequest and GenericResponse messages respectively.

Generic Requests for All Methods

The following data elements are used in all generic requests to the RSA Adaptive
Authentication (On Premise) System. Each method may have additional data elements
that are added to the message. For more information about those additional data
elements, refer to that specific method.
Note: The Required column indicates which fields are mandatory.
action The action to be taken. N ActionType
adminID The identification number used to identify the customer N String

service representative who is accessing the users account.
orgName The organization to which the user belongs. N String

If the field is blank, the application assigns the user to the
Default organization.
Note: Do not enter the value default in the orgName for

the Default organization.
userName The user name being requested. This data element is Y* String
required.
Note: In the WSDL, this data element is optional.
securityHeader The credential used to authenticate the caller of the Adaptive N* SecurityHeader
Authentication Admin service method.
Note: If the Administration Console parameter Admin

Caller Credentials Passed in Payload is True, this data
element is required.

securityHeader
The securityHeader structure defines the specific ID and password for the Adaptive
Authentication Admin service method making the request.
Max
Length
callerCredential Maps to the password of the caller initiating 50 N String

the request message. This does not map to the
users password.
callerId The identifier to be used for authentication of 50 N String

the caller initiating the request message.
This does not map to the users ID.
Note: If the Administration Console flag Admin Caller Credentials Passed in Payload
is True, the securityHeader parameters are required.
Generic Responses for the All Methods

The following data elements are used in all generic responses to the Adaptive
Authentication system. Each method may have additional data elements added to the
message. For more information about additional data elements, refer to the specific
method.
status The transaction status. String

deleteUser Method
The deleteUser method removes a users enrollment in the system. The actual user
information is not deleted from the Adaptive Authentication database, but it is
inaccessible by the user and the customer service representative. A user who has been
unenrolled must re-enroll before they can access the system.
Request /Response for deleteUser Method

The following are the additional request and response elements for this method.
Request Structure
userStatus The users status. This data element is optional. N String
Response Structure
userChangeHistoryList The history for the users account for a specific time UserChangeHistoryList
period.
userStatus The current status of the users String

Sample SOAP
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:adm="http://admin.ws.csd.rsa.com">
<soapenv:Header/>
<soapenv:Body>
<adm:deleteUser>
<adm:in0>
<adm:adminID>admin</adm:adminID>
<adm:userName>user</adm:userName>
<adm:securityHeader>
<adm:callerCredential>password</ adm:callerCredential>
<adm:callerId>callerId</adm:callerId>
</adm:securityHeader>
<adm:userStatus>VERIFIED</adm:userStatus>
</adm:in0>
</adm:deleteUser>
</soapenv:Body>
</soapenv:Envelope>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/ soap/envelope/">

<soapenv:Body>
<ns1:deleteUserResponse xmlns:ns1="http:// admin.ws.csd.rsa.com">
<ns1:deleteUserReturn xsi:type="ns1:AdminResponse"
<ns1:status>OK</ns1:status>
<ns1:userStatus>DELETED</ns1:userStatus>
</ns1:deleteUserReturn>
</ns1:deleteUserResponse>
</soapenv:Body>
</soapenv:Envelope>
getUserChangeHistory Method
This method returns a users account history. This method is synchronous. The
customer service representative is blocked from other methods until a response is
received from the Adaptive Authentication database.
Request or Response for getUserChangeHistory Method


Request Structure
userStatus The users status. N String
Response Structure
userChangeHistory The history for the users account for a specific time UserChangeHistoryList
period.
userStatus The current status of the user. String
Sample SOAP
This is a sample request for the getUserChangeHistory method.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:adm="http://

admin.ws.csd.rsa.com">
<soapenv:Header/>
<soapenv:Body>
<adm:getUserChangeHistory>
<adm:in0>
<adm:userName>user</adm:userName>
<adm:callerCredential>password</adm:callerCredential>
<adm:userStatus xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/ XMLSchema-instance"/>
</adm:in0>
</adm:getUserChangeHistory>
</soapenv:Body>
</soapenv:Envelope>

This is a sample response for the getUserChangeHistory method.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<ns1:getUserChangeHistoryResponse xmlns:ns1="http://admin.ws.csd.rsa.com">
<ns1:getUserChangeHistoryReturn xsi:type="ns1:AdminResponse" xmlns:xsi="http://www.w3.org/2001/
XMLSchema-instance">
<ns1:userChangeHistory>
<ns1:date>2012-09-10 07:29:52.165</ns1:date>
<ns1:description>CV</ns1:description>
</ns1:userChangeHistory>
<ns1:date>2012-09-11 07:31:51.290</ns1:date>
<ns1:description>L</ns1:description>
<ns1:type>admin -</ns1:type>
<ns1:date>2012-09-11 07:43:05.572</ns1:date>
<ns1:description>R</ns1:description>
<ns1:date>2012-09-11 07:45:19.993</ns1:date>
<ns1:description>V</ns1:description>
</ns1:getUserChangeHistoryReturn>
</ns1:getUserChangeHistoryResponse>
</soapenv:Body>
</soapenv:Envelope>

resetOpenSessions Method
The resetOpenSessions method is provided in the Web Services Adaptive
Authentication Administration API to allow you to terminate the abandoned open
authentication sessions in your application for a specific user.
Important: Regenerate your Adaptive Authentication Administration SOAP API Client

code to use the ResetOpenSessions method.
Request or Response for resetOpenSessions Method

Request Structure
orgName The organization to which the user belongs. N String

If the field is blank, the application assigns the user to the
Default organization.
Note: Do not enter the value default in the orgName for

the Default organization.
userName The user name being requested. This data element is Y String
required.
securityHeader The credential used to authenticate the caller of the Adaptive N SecurityHeader
Authentication Administration service method.
Response Structure
status The transaction status. STATUS_OK

Sample Soap
This is a sample request for the resetOpenSessions method.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:adm="http:/

/admin.ws.csd.rsa.com">
<soapenv:Header/>
<soapenv:Body>
<adm:resetOpenSessions>
<adm:in0>
<adm:userName>AA14245usr**</adm:userName>
<adm:callerCredential>*******</adm:callerCredential>
</adm:in0>
</adm:resetOpenSessions>
</soapenv:Body>
</soapenv:Envelope>
This is a sample response for the resetOpenSessions method.
<soapenv:Body>
<ns1:resetOpenSessionsResponse
xmlns:ns1="http://admin.ws.csd.rsa.com">
<ns1:resetOpenSessionsReturn xsi:type="ns1:AdminResponse"
</ns1:resetOpenSessionsReturn>
</ns1:resetOpenSessionsResponse>
</soapenv:Body>
</soapenv:Envelope>
Flagged Terminated Authentication Session

The list of the user change history values, returned by the getUserChangeHistory
method, includes the value for Reset Session (S) for terminated abandoned open user
authentication sessions. The value for Reset Session (S) can be used to monitor
terminated sessions for a user.
For the complete list of the user change history values, see Getting User Change
History on page 198.
The following Soap example is the result of flagging a terminated session by the
resetOpenSessions method. The example is of a getUserChangeHistory request and
response that indicate a terminated session.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:adm="http:/

<soapenv:Header/>
<soapenv:Body>
<adm:getUserChangeHistory>
<adm:in0><adm:userName>AA14245usr***</adm:userName>
<adm:callerCredential>******</adm:callerCredential>
</adm:in0>
</adm:getUserChangeHistory>
</soapenv:Body>
</soapenv:Envelope>
<soapenv:Body>
<ns1:getUserChangeHistoryResponse
xmlns:ns1="http://admin.ws.csd.rsa.com">
<ns1:getUserChangeHistoryReturn xsi:type="ns1:AdminResponse"
<ns1:date>2013-02-17 16:26:11.908</ns1:date>
<ns1:description>CV</ns1:description>
<ns1:date>2013-02-17 16:26:12.661</ns1:date>
<ns1:description>S</ns1:description>
- this is the code for a terminated session
<ns1:type>ADMIN -</ns1:type>
</ns1:getUserChangeHistoryReturn>
</ns1:getUserChangeHistoryResponse>
</soapenv:Body>
</soapenv:Envelope>
getUserStatus Method
The getUserStatus method returns the status of a given user. This method is triggered
when the customer service representative submits a request. A getUserStatus
AdminRequest is sent to the Adaptive Authentication Server and returns with a
AdminResponse.

This method is synchronous. The customer service representative is blocked from

other methods until a response is received from the Adaptive Authentication database.
Request or Response for getUserStatus Method

Request Structure
Response Structure
period.
Sample SOAP
<soapenv:Header/>
<soapenv:Body>
<adm:getUserStatus>
<adm:in0>
<adm:userName>user1</adm:userName>
</adm:in0>
</adm:getUserStatus>
</soapenv:Body>
</soapenv:Envelope>

<soapenv:Body>
<ns1:getUserStatusResponse xmlns:ns1="http://
admin.ws.csd.rsa.com">
<ns1:getUserStatusReturn xsi:type="ns1:AdminResponse"
</ns1:getUserStatusReturn>
</ns1:getUserStatusResponse>
</soapenv:Body>
</soapenv:Envelope>
setUserStatus Method
The setUserStatus method sets a users status to one of the following values:
UNVERIFIED
VERIFIED
LOCKOUT
UNLOCKED
DELETED
Request or Response for setUserStatus Method

Request Structure
userStatus The users status. Y String
Response Structure
userChangeHistory The history for the users account for a specific UserChangeHistoryList
time period.

Sample SOAP
<soapenv:Header/>
<soapenv:Body>
<adm:setUserStatus>
<adm:in0>
<adm:userStatus>LOCKOUT</adm:userStatus>
</adm:in0>
</adm:setUserStatus>
</soapenv:Body>
</soapenv:Envelope>
<soapenv:Body>
<ns1:setUserStatusResponse xmlns:ns1="http://admin.ws.csd.rsa.com">
<ns1:setUserStatusReturn xsi:type="ns1:AdminResponse" xmlns:xsi="http://
www.w3.org/2001/XMLSchema-instance">
<ns1:userStatus>LOCKOUT</ns1:userStatus>
</ns1:setUserStatusReturn>
</ns1:setUserStatusResponse>
</soapenv:Body>
</soapenv:Envelope>
unlockUser Method
The unlockUser method unlocks a user that has been locked out of the system due to
failure on the challenge method.
Request / Response for unlockUser Method


Request Structure
userStatus The users status. N String
Response Structure
period.
<soapenv:Header/>
<soapenv:Body>
<adm:unlockUser>
<adm:in0>
<adm:callerCredential>password</
adm:callerCredential>
<adm:userStatus>LOCKOUT</adm:userStatus>
</adm:in0>
</adm:unlockUser>
</soapenv:Body>
</soapenv:Envelope>
<soapenv:Body>
<ns1:unlockUserResponse xmlns:ns1="http:/
<ns1:unlockUserReturn xsi:type="ns1:AdminResponse"
<ns1:userStatus>UNLOCKED</ns1:userStatus>
</ns1:unlockUserReturn>
</ns1:unlockUserResponse>
</soapenv:Body>
</soapenv:Envelope>
lockUser Method
The lockUser method locks a user account in the system. You can lock a users
account for the following reasons:

the user has requested the account to be locked due to a security compromise
your system needs to lock the account for administrative purposes
Request or Response for lockUser Method

Request Structure
Response Structure
period.
Sample SOAP
<soapenv:Header/>
<soapenv:Body>
<adm:lockUser>
<adm:in0>
<adm:callerCredential>password</
adm:callerCredential>
<adm:userStatus>VERIFIED</adm:userStatus>
</adm:in0>
</adm:lockUser>
</soapenv:Body>
</soapenv:Envelope>
<soapenv:Body>
<ns1:lockUserResponse xmlns:ns1="http:/
<ns1:lockUserReturn xsi:type="ns1:AdminResponse"
<ns1:userStatus>LOCKOUT</ns1:userStatus>
</ns1:lockUserReturn>
</ns1:lockUserResponse>
</soapenv:Body>
</soapenv:Envelope>

10 AdminService API Interfaces

AdminService Methods
Getting User Change History
Setting User Status
AdminService Parameters
This chapter describes the various methods and parameters for AdminServices
AdminRequest and AdminResponse messages.
AdminService Methods
The AdminService methods are described in the following table.
Method Description
getUserChangeHistory Retrieves the users change history.
getUserStatus Returns the status of a user:

ENROLLED
UNLOCKED
LOCKED
VERIFIED
NULL
deleteUser Marks the users account as unavailable.
setUserStatus Sets the users status:

LOCKED
UNLOCKED
unlockUser Unlocks a user if their status is locked.
10: AdminService API Interfaces 197

Getting User Change History

You can request a user change history from AdminService. Several different values
can be returned using this method. These values indicate the users history for a given
amount of time.
Created (C)The user record has been created.
Deleted (D)The user has been deleted, but the record still exists.
Lockout (L)The user has been locked out of his account.
Verified (V)The user has been verified and confirmed their enrollment.
Reset or Unlocked (R)The user has been unlocked or reset.
Unverified (N)The user has not yet completed enrollment.
Modified (M)The user has changed one or more of his settings (phrase,
questions, or answers).
Modified Phrase (P)The user has changed their phrase.
Modified Question (Q)The user has changed one or more challenge questions.
Modified Answer (A)The user has changed one or more challenge answers.
Modified User Locale (B)The user has changed their locale.
Modified User Name (U)The user has changed their user name.
Modified Group (G)The group membership for the user has changed.
Modified Contacts (T)The contact information for the user has changed.
Modified Preference (F)The preference information for the user has changed.
Reset Session (S)The abandoned open user authentication session is terminated.
Setting User Status

The customer service representative can change the users given status to several
states, based on the current state of the user.
There are several user states. This section explains the user states, how a user achieves
those states, and what states the user can move to from that given state.
NOTENROLLEDAll users begin in this state. After users leaves this state,
they cannot be reset to this state.
UNVERIFIEDUsers who have not completed enrollment are unverified.
Users can be in this state if:
they have not completed enrollment.
they were in a locked state, and the customer service representative changes
their status to UNVERIFIED. In this case, the user must re-enroll in the
system.
198 10: AdminService API Interfaces

the user account was deleted, and the user name is being re-used for another
or the same user.
From this state, users can only go to one of the following states: UNVERIFIED
or VERIFIED.
VERIFIEDUsers who are enrolled in the system.
From this state, users can only go to one of the following states: LOCKED or
DELETED.
LOCKEDUsers who have:
failed to enter their password correctly a set number of times
failed in challenge attempts
disabled accounts
From this state, users can only go to:
UNLOCKEDThe customer service representative must unlock the user or
the user performs a self-unlock. In this scenario, the user can immediately log
in and start using his account
UNVERIFIEDThe customer service representative must reset a users
status to UNVERIFIED. In this scenario, the user must re-enroll in the
system in order to access their account.
DELETEDThe customer service representative must set the users status
to DELETED.
UNLOCKEDUsers who have had their accounts unlocked by the customer
service representative
From this state, users can only go to the following state, VERIFIED, by having
the customer service representative change their userStatus.
DELETEDAccounts that have been marked as deleted in the RSA Adaptive
Authentication (On Premise) database. Once a user has been marked deleted, it
can only go to an UNVERIFIED state, and the user (either a new user or same
user) needs to (re)enroll in the system.

The following figure illustrates the users given states.

Setting User States

You can change the users status by submitting an AdminRequest with the necessary
values. userStatus value is mandatory in this request.
AdminRequest Elements
Methods
Parameter Description Data Type Required
Used
userStatus The users current status. You can change the String. Y All
users status to one of several values. Values are:
DELETED
LOCKOUT
UNLOCKED
UNVERIFIED
VERIFIED
AdminResponse Elements
Methods
Used
userStatus The current status of the user. String with values: ALL
NOTENROLLED
UNVERIFIED
VERIFIED
LOCKOUT
UNLOCKED
DELETED

The following section lists all of the parameters for AdminRequest and
AdminResponse messages.
AdminRequest Elements
Methods
Parameter Description Data Type Required
Used
adminID The customer service representative login String N All

user name.
orgName User organization. If no value is set, the String N All

string, defaultOrgName is used.
(optional)
userName The identifier or string for the end user for String Y All
which the request applies. This is the key
value that is used to locate the user's data in
the system, as passed in the Web Services
calls.
userStatus The users current status. String Y only for setUserStatus

setUserStatus
AdminResponse Elements
Methods
Used
status The transaction status. STATUS_OK ALL
userChangeHistoryList The history for the users account for the UserChangeHistory getUserChange
specified range of dates. History
userStatus The current status of the user. String with values: ALL
NOTENROLLED
UNVERIFIED
VERIFIED
LOCKOUT
UNLOCKED
DELETED

UserChangeHistory
UserChangeHistory A list of all of the user change history. UserChange
UserChange
date The date that the particular change history occurred. String
description A description of the type of change that occurred within date. String

type The type of user history that occurred. The values are: String
C CREATED. The user record is created.
D DELETED. The user is deleted (record is not deleted).
L LOCKED. The user is locked out.
V VERIFIED. The user is confirmed to be enrolled.
M MODIFIED. The user has modified one or more settings: phrase,

question, or answers. The specific modification is listed in the
description.
R RESET or UNLOCKED.
The user has been reset or unlocked.
P MODIFIED PHRASE. The user has changed their Adaptive

Authentication phrase.
Q MODIFIED QUESTION. The user has changed one or more of their

challenge questions.
A MODIFIED ANSWER. The user has changed one or more of their

challenge answers.
B MODIFIED USER LOCALE. The users locale is changed.
U MODIFIED USER NAME. The user has changed their user name.
G MODIFIED GROUP.
The users group membership is changed.
T MODIFIED CONTACTS
The users contact information is changed.
F MODIFIED PREFERENCE
The users preferences are changed.

11 Case Management Processes

Case Management Processes
Retrieving Information for Multiple Activities Process
Retrieving Information for Multiple Cases Process
Retrieving Information for a Specific Case Process
Updating a Specific Activity Process
Updating a Specific Case Process
Locking Process Implementation
This chapter describes the functionality of the processes that apply the Case
Management API methods, providing examples of each of these processes.
To learn all about case management, see the chapter Managing Cases in RSA
Adaptive Authentication (On Premise) in the Back Office Users Guide.
Case Management Processes

The Case Management API promotes improved integration between RSA Adaptive
Authentication (On Premise) Case Management and your external case management
application.The following table lists the processes, and the methods used by these
processes, which enable you to implement this integration.
Retrieving Information for Use this method to get information about existing getActivities
Multiple Activities activities for a particular organization. You can
define the activities to retrieve by using the filter
provided.
Important: Encode the information retrieved by the

this process before the information is exposed to
your end users.
Encoding data is used to prevent potential cross site
scripting (XSS) in the web application.
Retrieving Information for Use this method to get information about existing getCases
Multiple Cases cases for a particular organization. You can define
the cases to retrieve by using the filter provided.
11: Case Management Processes 205

Retrieving Information for a Use this method to get information about a specific getCase
Specific Case case by providing the caseID. The caseId is
retrieved using the getCases method. This process
allows you to lock data retrieved earmarked for
update.
Important: Encode the information retrieved by the

this process before the information is exposed to
your end users.
Encoding data is used to prevent potential cross site
Updating a Specific Activity Use this method to update resolution information updateActivity
for a specific activity. The activity (event) is
identified by its eventId. This process automatically
locks the data earmarked for update. After update is
completed, the data is unlocked automatically.
Updating a Specific Case Use this method to update information for a specific updateCase
case. The case is identified by its caseId. The case
must be retrieved and locked by the getCase
method prior to update. After update is completed,
the data is unlocked, if specified.
Retrieving Information for Multiple Activities Process

The retrieval process enables you to get information about one or more activities
(events) for a specific organization. The Default organization identification is assumed
if another organization identification is not specified.
The getActivities method, used by this process, provides you with a filter to limit the
number of events retrieved. This gives you the utmost flexibility in creating the exact
data query you require.
The filter consists of the organization identification and other selection parameters, for
the getActivities method, such as:
event type
event resolution
event time consisting of both from and to dates
risk score
policy action
For each activity selected, you can retrieve all the data, including the eventId, for one
or more events. For example, the data includes:
Financial transaction informationthe events transaction details.
206 11: Case Management Processes

IP informationthe events IP address and location details.

Risk informationthe events factors as the basis for the risk calculation.
Client informationthe events client details.
The eventId is used for the updateActivity method.
User Scenario for Retrieving Activities Information

The following is an example scenario in which the user retrieves information for
multiple activites.
1. A user of an external case management application relays a request for
information from the Adaptive Autentication Case Management application.
2. The user requires all the activities, which occurred in a particular time period,
issued by a specific user, for a specific organization.
3. The getActivities method is used to retrieve the activities and their information
according to the criteria defined by the request parameters.
Retrieving Information for Multiple Cases Process

The retrieval process enables you to get information about one or more cases for a
specific organization. The Default organization identification is assumed if another
organization identification is not specified.
The getCases method, used by this process, provides you with a filter to limit the
number of cases retrieved.
The filter for this method consists of the organization identification and other selection
parameters similar to the parameters for the filter for the getActivities method.
For each case selected, only the case metadata, including the caseId, is retrieved. The
caseId is needed for both the getCase and the updateCase methods.
User Scenario for Retrieving Cases Information

The following is an example of a user scenario in which a user requires retrieval of the
metadata for one or more cases.
1. A user of an external case management application requires the metadata,
especially the identification numbers, of specific cases.
2. A request for information is sent from the external case management application
to the Adaptive Authentication Case Management module.
3. The request requires retrieval of all the challenged cases for a specific
organization, which occurred during a particular time period, issued by a specific
user.
4. The getCases method is used to retrieve the metadata for the cases selected
according to the criteria of request parameters.

Retrieving Information for a Specific Case Process

The retrieval process enables you to get information about one specific case. The
getCase method, used by this process, requires you to provide only the caseId for that
specific case. If you intend to update the case information, this method enables you to
lock the case prior to update. You are now ready to update the case information using
the updateCase method.
User Scenario for Retrieving Cases Information

The following is an example of a user scenario in which a user requires selection of a
specific case.
1. A user of an external case management application requires the data for a specific
case. The user intends to update that cases information.
2. A request for information is sent from the external case management application
to the Adaptive Authentication Case Management module.
3. The request relays the caseId of the specific case, requesting that the case be
locked pending update.
4. The getCase method is used to retrieve the case and its information and to lock it
prior to update.
Updating a Specific Activity Process

The process uses the updateActivity method which enables you to update the event
resolution data for a specific event retrieved by the eventId. The eventId for the
activity is retrieved using the getActivities method. The Case Management API
automatically locks the event prior to the update. Following the update, the data is
automatically unlocked. For more information about locking an event, see Locking
Process Implementation, on page 210.
User Scenarios for Updating a Specific Activity

The following is an example of a user scenario in which a user requires the update of a
single event.
1. A user issues a request to update the resolution of a specific activity issued by a
specific user from a specific organization.
2. Previously, the activitys eventId was retrieved, using the getActivities method,
with request criteria consisting of the organization identification and the relevant
user.
3. The resolution to this activity is to deny access.
4. The updateActivity method is used to update the resolution of the activity. This
method automatically performs the data locking and unlocking necessary for this
update.

Updating a Specific Case Process

The process uses the updateCase method enabling you to update the data for a specific
case, identified in the request by the caseId. The specified case is retrieved and locked
by the caseId using the getCase method. Following the update, the case and its events
can be unlocked. For more information about locking a case, see Locking Process
Implementation, on page 210.
User Scenarios for Updating a Specific Case

The following is an example of a user scenario in which a user requires the update of a
specific case.
A user sends a request to update the data of a specific case. The user relays the specific
information to locate the case in question such as the organization, user identification,
time period, and IP address.
1. The case and the case metadata, including the caseId, are retrieved, using the
getCases method, according to the selection criteria provided by the user:
the specific organization,
the user identification
the time period
the IP address
2. Prior to the update, the getCase method is used to lock the specific case, identified
by the caseId. Consequently, the events associated with the case are also locked.
3. Identified by the caseId, the case is updated, as required, by using the updateCase
method.
4. After update completion, the case and its events are unlocked, using the
updateCase method, if specified.

Locking Process Implementation

The Case Management API methods perform locking before update. The following
describes the locking procedures implemented in the Case Management API
processing.
Lock an Activity Prior to an Update

Locking an activity (event) requires locking the case associated with that activity. If
there is no case associated with an event, the system creates a new case for that event.
When a case is locked, all the events associated with that case are also locked.
The procedure for locking an event is performed automatically by the Case
Management API, as part of the functionality of the updateActivity method. The
following describes the locking procedure once the case associated with the event is
determined:
a. The application checks if the case is locked.
b. If the case is locked by the same user requesting the lock, the lock is valid for
the update and processing continues.
c. If the case is locked by a different user, an error message is issued:
Cannot update activity: case already locked by a different operator.
In this situation, processing stops.
d. If the case is not locked, the application locks the case, preventing other users
from updating the case and its events.
e. When the lock is valid for the update, the resolution information of the
relevant event is updated, according to the method request parameters.
f. As part of the response processing, the case and its events are unlocked
automatically.
Note: A case is assigned to the operator name of the user who locks the case. A case
cannot be reassigned to a different operator name.
Lock a Case
You are responsible for locking and unlocking cases when using the Case
Management API. This involves setting the lock and unlock parameters of the getCase
and updateCase methods, respectively and in that order.
The locking process itself is similar to locking a case for the updateActivity method.
The procedure is as follows:
1. For the getCase method, set the caseId parameter to the caseId for the case to be
updated. The caseId for the case to be updated is retrieved using the getCases
method.
2. Set the getCase method parameter lock to true.
3. Issue the getCase method SOAP API call.

4. If the lock parameter is true, the application processes the locking request as
follows:
b. If the case is not found, an error message is issued:
No case with such an ID exists
In this situation, there is nothing to retrieve or lock.
c. If the case is locked by the same user requesting the lock, the lock is valid
for the update.
d. If the case is locked by a different user, an error message is issued:
Case is already locked by a different operator
In this situation, the lock is not valid for the update.
e. If the case is not locked, the application locks the case, preventing other
users from updating the case and its events.
5. For the updateCase method, set the caseId parameter to the caseId for the case to
be updated.
6. Optionally, set the parameter releaseLock to true, along with the other parameters
needed for the update. This allows the case and its events to be unlocked
following update.
7. Issue the updateCase method SOAP API call.
8. The application verifies the case is locked as follows:
b. If the case is not found, an error message is issued:
Unable to update case: no such case exists
In this situation, there is nothing to update.
c. If the case exists and is locked by the same user requesting the lock, the
lock is valid for the update.
d. If the case exists and is locked by a different user, an error message is
issued:
Case is already locked by a different operator
In this situation, the lock is not valid for the update.
e. If the case exists and is not locked, an error message is issued:
Update case failed: case is not locked for update.
In this situation, there is no lock.
9. If the case exists and is locked and valid for the update, the update of the case data
proceeds according to the request parameters. Otherwise, processing stops.
10. If the releaseLock parameter is set to True, as part of the response processing, the
case and its events are unlocked.
Note: A case is assigned to the operator name of the user who locks the case. A case
cannot be reassigned to a different operator name.

Unlock a Case
Use the updateCase transaction to unlock a locked case and its events that was locked
inadvertently.
The procedure is as follows:
1. Set the caseId parameter to the caseId for the case to be unlocked.
2. Set the caseStatus parameter to the current status of the case to be unlocked.
3. Set the assignedToUserName parameter to the operator name of the user who
locked the case.
4. Set the releaseLock parameter to False.
5. Issue the updateCase method SOAP API call.

12 Case Management API Methods

Overview of the Case Management API Methods
Request and Response Messages for Case Management Methods
getActivities Method
getCases Method
getCase Method
updateActivity Method
updateCase Method
Error Messages
This chapter describes the various methods of the Case Management API. For
information about applying these methods to the Case Management API processes,
see Chapter 11, Case Management Processes.
Overview of the Case Management API Methods

The Case Management API provides case management functionality through the use
of Web Services. All methods accept request data elements and return Response data
elements.
Important: Encode the information retrieved by the Case Management API methods
before the information is exposed to your end users. Encoding data is used to prevent
potential cross site scripting (XSS) in the web application.
The various methods for Case Management are listed in the following table.
Method Description
getActivities Use to retrieve data for one or more activities (events) using a filter.
getCases Use to retrieve metadata for one or more cases using a filter.
getCase Use to retrieve data for one specific case using the caseId.
updateActivity Use to update resolution information for one event using the eventId.
updateCase Use to update information for a specific case using the caseId.
12: Case Management API Methods 213

Request and Response Messages for Case Management Methods

The Case Management API methods differ from the adminServices methods in that
they do not use generic requests or generic responses. Each method structure is unique
unto itself. The following is a detailed description of each method, their request and
response structures, and the data elements that comprise those structures.
For more information about case management, see the Case Management Menu
section in the Chapter Managing Cases in RSA Adaptive Authentication (On
Premise) in the Back Office Users Guide.
Paging
The Case Management API includes the paging functionality available for all
methods. Paging provides you with the option to select the maximum number of data
items you want to retrieve. See the paging structure definition inpaging on
page 219.
Note: The Required column indicates which fields are mandatory.
214 12: Case Management API Methods

getActivities Method
The getActivities method retrieves all the data for the activities (events) selected for
retrieval. This method uses a filter to define the selection criteria for the data retrieval.
Events are selected according to this selection criteria.
Request for the getActivities Method

The following table is a list of the data elements (activitiesFilter) which, combined,
define the selection criteria for the request structure for this method.
clientDefinedEventTyp An activity type not provided by Adaptive N String

e Authentication that is defined by the customer end-
user in the Policy Management application. For
more information, see chapter Managing Policies
in the Back Office Users Guide.
eventResolution The resolution determination for a specific event. N Resolutions

For the list of resolution values, see resolutions
Values on page 218.
caseResolution The resolution determination for a specific case. For N Resolutions

the list of resolution values, see resolutions
Values on page 218.
eventType The activity type. See Supported Event Types on N eventType

page 85, for a list of all acceptable event types.
triggeringRuleType The flag type assigned by the Adaptive N triggeringRuleT

Authentication system. See triggeringRuleType ype
on page 216 for a list of pre-defined values.
eventTimeFilter The beginning and end of the retrieval period (range N eventTimeFilter
of the events date and time). For more information,
see eventTimeFilter on page 217.
Note: Without limits on the retrieval time period,

data retrieval can take a long time. Enter the
eventTimeFilter fields to allow for an efficient
selection process.
riskScoreFilter This parameter includes the To and From fields, N riskScoreFilter

indicating the range of event risk scores for
retrieval. The maximum range is 0-1000
ipFilter This parameter consists of both the IP address and N ipFilter

the country where it is located. For more
information, see ipFilter on page 218.

orgId The identification of an organization to which an N String

event belongs.
Note: If not specified, the application uses the

Default organization identification.
policyAction The action assigned to the event. N String
caseAvailabilityAnd The scope of the query in regard to the case N caseRefType

Status associated with a given activity. See caseRefType
on page 218 for a list of query values.
ruleId The rule triggered by an event. N String
userId The identification of the user. N String
userInternationalAcct The number of the users account in IBAN format. N String (100)
Number
Note: If the channel indicator for this event is set to
ATM, this is an ATM-related data element. For more
information on ATM transactions, see ATM
Protection Module on page 247.
triggeringRuleType
The triggeringRuleType refers to the characteristic of an event which explains the
status of the events association with a case. This status refers to whether an event is
flagged.
A flagged event is an event that appears to be fraudulent and is associated with a case.
This status also refers to the contributing factors that opened the case associated with
an event.
The table below lists the acceptable pre-defined values for this data type.
Values Description
PRODUCTION The event is associated with a case opened due to production rules, whether
or not test rules were also a contributing factor.
BOTH The event is associated with a case opened due to both test and production
rules.
TEST The event is associated with a case opened due to test rules, whether or not
production rules were also a contributing factor.
TEST_ONLY The event is associated with a case opened only due to test rules.
NOT_FLAGGED The event is not flagged. It is not associated with any case.

Values Description
ANY Any event
eventTimeFilter
The eventTimeFilter consists of a date range, indicating the beginning and end of the
retrieval period. An event is retrieved if the eventDate is within the range of the
eventTime filter.
From This is the beginning of the event retrieval period. An String supported by Java
events eventTime must be equal to or greater than this Simple Date format
date.
To This is the end of the event retrieval period. An events String supported by Java
eventTime must be equal to or less than this date. Simple Date format
Note: The To date value must be equal to or less than the From date value.
Important: For both the From and To date fields, the date format is yyyy-MM-dd
HH:mm:ss.SSS.
For example, if the From date is September 21,2012 at 3:45 PM, the date is
represented as: 2012-09-21 15:45:00.
riskScoreFilter
The riskScoreFilter defines the range of acceptable risk scores for events to be
retrieved. An event is retrieved if its risk score is within the range defined by the
riskScoreFilter.
From This is the beginning of the risk score range. An Integer

events risk score must be equal to or greater than
this value.
To This is the end of the risk score range. An events Integer

risk score must be equal to or less than this value.

ipFilter
The ipFilter defines the geographic location from where the events are issued. .
ipAddress This is the IP address that issued the events to be ipType

retrieved. The IP address must be in either IpV4 or
IpV6 format.
ipCountry This is the country where the IP address is located from String
which the events were issued.
caseRefType
The caseAvalabilityAndStatus parameter specifies the type of case that is associated
with a given activity. The table below lists the acceptable pre-defined values for the
data type..
Values Description
WITH_CASE The event is associated with a case.
WITHOUT_CASE The event is not associated with a case.
OPEN_CASE The status of the case to retrieve is either New or Could not contact user
CLOSED_CASE The status of the case to retrieve is Closed.
ANY All cases are retrieved.
resolutions Values
The resolutions values correspond to the different resolution outcomes assigned by
the Risk Engine to the individual events or cases. The table below lists the acceptable
values for this data type.
For more information, see the Case Resolution section in the chapter Managing
Cases in RSA Adaptive Authentication (On Premise) in the Back Office Users
Guide..
Values Description
CONFIRMED_FRAUD The event or case is deemed fraudulent.
SUSPECTED_FRAUD The event or case appears to be fraudulent. It requires additional investigation

and analysis.
CONFIRMED_GENUINE The event or case is deemed genuine.
ASSUMED_GENUINE The event or case appears to be genuine. It requires additional investigation

and analysis.

Values Description
UNKNOWN The resolution for this event or case is undetermined. It requires additional
investigation and analysis.
ANY All events or cases regardless of their resolution outcome.
paging
The paging structure is common to all method requests. If you choose to set the
paging for a specific method, you must define both the pageSize and the offset by
inputting both values. For example, if you require 500 results from the halfway point
out of 10000 results, the pageSize is 500 and the offset is 5001.
A few points about paging are:
The default page size is the first 2000 results.
A page contains a maximum of 2000 results.
If you specify a pagesize greater than the maximum number of results, the
default pagesize is retrieved.
The following table describes the paging data elements:.
pageSize The maximum number of results you want to retrieve. Integer
offset The number of the result from which to start Integer

information retrieval.
Note: If you do not define the page size, the default pagesize will be retrieved. If you
do not define the offset, the default is zero.

Response for the getActivities Method

The response for the getActivities method (getActivitiesResponse) returns either zero
or one or more events. The getActivitiesResponse structure consists of the response
sub-structure and the call status information.
Important: Encode the information retrieved by this method before the information is
exposed to your end users. Encoding data is used to prevent potential cross site
For the callStatus definitions, see callStatus on page 220.

The following is a description of the sub-structures in the getActivitiesResponse
structure:
The response sub-structure is made up of the caseEvents sub_structure and the
eventCount.
The eventCount is the number of events retrieved by the SOAP call. It is reported
at the end of the response sub-structure.
The caseEvents sub-structure represents a single event. It is made up the
following sub-structures:
eventDetails
customFactsList
ipDetails
riskContributorsList
The eventId, for each event retrieved, is listed in the eventDetails sub-structure of the
caseEvents sub-structure.
callStatus
The callStatus sub-structure includes all the information about the status of a specific
SOAP call. The table below describes each parameter in the structure and lists their
acceptable values where applicable:
Parameter Description Values
status The status of the call. SUCCESS

FAILURE
statusCode The numeric code that represents the call 0 = SUCCESS

status. If not 0, the code defines what type 1 = APPLICATION ERROR
of error has occurred. 2 = AUTHENTICATION ERROR
statusDescription A free-text explanation of the call failure. NA
Note: This field only appears if the status of

the call is FAILURE.

eventDetails
The eventDetails sub-structure consists of most of an events general information.
The following table is the list of the data elements included in this structure.
eventDescription A description of the event described by the customer. String
eventId The identification number assigned to the event. String
eventResolution The resolution determination for the event For a list Resolutions
of resolution values, see resolutions Values on
page 218.
eventTime The specific date and time that an event took place. String supported
The date format is yyyy-MM-dd HH:mm:ss.SSS. by Java Simple
For example, if the eventTime date is September Date format
21,2012 at 3:45 PM, the date is represented as: 2012-
09-21 15:45:00.
eventType The activity type. See Supported Event Types on eventType

page 85, for a list of all acceptable event types.
Note: If the value of this data element is

WITHDRAW, the channel indicator must be set to
ATM . This transaction type requires additional
information for ATM monitoring in the eventDetails
section. See ATM-related Information on page 224.
extAcctNumber The number of the payee or other account. String (50)
Note: New customers must enter the account number

in IBAN format. Existing customers must continue to
enter the account number in the standard format to
extInternationalAcctNumber The payee or other account number in IBAN format. String (100)
Note: If the channel indicator for this event is set to

ATM, this is an ATM-related data element. For more
extAcctOwnerName The name of the owner of the payee or other account. String
extAcctRoutingCode The routing code of the payee or other account. String
extAcctType The account type of the payee or other account. String
acctOpenDate The date that the account was last opened. Date

addrChangeDate The date that the users address record was last Date
changed or created.
amountCurrency The currency of the transaction amount according to String

the ISO standard 4217 (alphabetic code).
amountInUSD The value of the transaction amount in US dollars. Double
original Amount The value of the original transaction amount String

specified in the original currency.
passwordChangeDate The date the users password record was last changed Date
or created.
phoneChangeDate The date the users phone number was last changed. Date
policyAction The action that the event was assigned. String
policyRuleName The name of the policy rule triggered. String
challengeSuccess the outcome of a challenge authentication process: String

If the policy action is Challenge, the value is
"N" if the challenge was not successful
"Y" if the challenge was successful
If the policy action is not Challenge, this field is
not applicable.
channelIndicator Indication of the device type. See String

channelIndicatorType values on page 224 for a list
of channelIndicator values.
Note: If the value of this parameter is ATM,

additional information is included in the eventDetails
section. See ATM-related Information on page 224.
clientDefChannelInd Indication of the device type used by the customer to String

transfer additional information on the channel in use
(for example: SMS/Browser/Application based).
clientTrxId The clients transaction ID value. String
triggeringRuleType The flag type assigned by the Adaptive triggeringRuleTy

Authentication system. See triggeringRuleType on pe
page 216.
loginId The users login identification code for on-line String

banking.

olbEnrollDate On-line banking enrollment date in the following Datetime

format:
orgId The identification of the organziation to which an String

event belongs.
riskScore The risk score that this event received from the Risk Integer
Engine.
testRuleNames The list of names of the test rules that were triggered String
by the event. The names in the list are separated by a
comma.
trxDueDate For scheduled transactions, the due date String supported

of the transaction. by Java Simple
Date format
For recurring transactions, the due date
of the first payment.
The date format is yyyy-MM-dd HH:mm:ss.SSS.
For example, if the eventTime date is September
09-21 15:45:00.
trxSchedule This value that defines all the available transaction String
schedules. See Schedule Values on page 150.
trxSpeed This value determines how fast a transaction will take String
place. SeeOtherAccountBankType Values on
page 150
userAcctNumber The number of the users account. String
Note: New customers must enter the account number

in IBAN format. Existing customers must continue to
enter the account number in the standard format to
maintain the user profile.
userInternationalAcctNumber The number of the users account in IBAN format. String(100)
Note: If the channel indicator for this event is ATM,

this is an ATM-related data element. For more
clientDefinedEventType An event type added by the client. String
userId The identification of the user who issued the event. String

channelIndicatorType values
A list of available channel types:
WEB (default)
IVR
CALL_CENTER
BRANCH
ATM
MOBILE
OTHER
ATM-related Information
If the channel indicator is set to ATM, the getActivities response includes specific
information relating to an ATM transaction. For more information on ATM
transactions, see ATM Protection Module on page 247.
The following table lists the data elements issued for an ATM-related event in Case
Management API methods payloads:
Data Elements Description Data Type
atmID The global unique identification of the ATM device. String(20)
atmOwner This specifies if the owner of the ATM device is an RSA String(20)
customer who is implementing the RSA Adaptive
Authentication (On Premise) ATM Protection Module.
The two values accepted for this field are:
FI - the financial institution that owns the ATM device and
is implementing the Adaptive Authentication ATM
Protection Module.
Other - the financial institution that owns the ATM device
and is not implementing the Adaptive Authentication
ATM Protection Module.
locationType The type of location where the ATM device resides. In the LocationType
chapter ATM Protection Module, see the list of pre-defined
types of locations in Location Type Values on page 253.
location The geographic location of the ATM devices consisting of Location

the physical address and the geographic coordinates. In the
chapter ATM Protection Module, see the details about the
Location data structure in Location on page 254.
atmAmount The amount of cash withdrawn for an ATM transaction of the Amount
WITHDRAW event type. In the chapter ATM Protection
Module, see Amount on page 257.

cardPinChangeDate The date the users credit or debit card PIN number was last String
changed, in GMT format. supported by
The date format is yyyy-MM-dd HH:mm:ss.SSS. For Java Simple
example, if the card PIN change date is September 21,2012 at Date format
3:45 PM, the date is represented as: 2012-09-21 15:45:00.
atmCardAge The number of days from the date the users credit or debit Integer
card was issued. For information about the card issue date,
see Channel on page 250, in the chapter ATM Protection
Module.
customFactsList
A list of custom facts, such that each fact consists of a string with a name and a value.
For more information, see the Custom Facts Management section in the Managing
Policies chapter of the Back Office Users Guide.:
name The name the user has assigned to a String

specific piece of information.
value The value of the named custom fact with String

which it is associated.
ipDetails
The details of the internet protocol (IP) from which the event was issued. The
following table lists the data elements that define the IP that issued the event:
ipAddress The IP address from which this event was sent. String
ipCity The city from which this event was sent. String
ipCountry The country connected to the IP address from which this String
event was sent.
ipIsp The Internet Service Provider taken from the GEO IP. String
ipOwner The name of the owner of the IP address. String
ipRegion The IP region from which this event was sent. String

This a list of factors that contribute to the risk score. This list consists of up to ten risk
contributors. The following table lists the data elements for each risk contributor:
contribution The value of the risk score assigned to the event due to the Integer
risk score contributor.
name The factor that contributed to the risk score. String

getActivities Sample SOAP Request

This is a sample of a SOAP request for the getActivities method:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:typ="http://ws.rsa.com/cm/types">

<soapenv:Header/>
<soapenv:Body>
<typ:getActivities>
<typ:activityFilter>
<typ:clientDefinedEventType xsi:nil="true"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
<typ:eventResolution xsi:nil="true"
<typ:caseResolution xsi:nil="true"
<typ:eventType>WITHDRAW</typ:eventType>
<typ:triggeringRuleType xsi:nil="true"
<typ:eventTimeFilter>
<typ:from xsi:nil="true"
<typ:to xsi:nil="true"
</typ:eventTimeFilter>
<typ:riskScoreFilter>
<typ:from xsi:nil="true"
<typ:to xsi:nil="true"
</typ:riskScoreFilter>
<typ:ipFilter>
<typ:ipAddress xsi:nil="true"
<typ:ipCountry xsi:nil="true"
</typ:ipFilter>
<typ:orgId xsi:nil="true"
<typ:policyAction xsi:nil="true"
<typ:caseAvailabilityAndStatus xsi:nil="true"
<typ:ruleId xsi:nil="true"
<typ:userId>user</typ:userId>
<typ:userInternationalAcctNumber xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/
>
</typ:activityFilter>
<typ:paging>
<typ:pageSize>50</typ:pageSize>
<typ:offset>0</typ:offset>
</typ:paging>
</typ:getActivities>
</soapenv:Body>
</soapenv:Envelope>

getActivities Sample SOAP Response

This is a sample of a SOAP response with a single caseEvent for the getActivities
method:
<soapenv:Body>
<ns1:getActivitiesResponse xmlns:ns1="http://ws.rsa.com/cm/types">
<ns1:response>
<ns1:caseEvents>
<ns1:eventDetails>
<ns1:eventId>7ef7-:fd4bb419931:5cba5794-_TRX</ns1:eventId>
<ns1:eventTime>2012-09-05T10:30:17.367+03:00</ns1:eventTime>
<ns1:eventType>WITHDRAW</ns1:eventType>
<ns1:extAcctRoutingCode>NA</ns1:extAcctRoutingCode>
<ns1:amountCurrency>USD</ns1:amountCurrency>
<ns1:amountInUSD>45.0</ns1:amountInUSD>
<ns1:originalAmount>12.0</ns1:originalAmount>
<ns1:policyAction>DENY</ns1:policyAction>
<ns1:policyRuleName>Rule15- Withdraw and Channel Indicator=ATM</ns1:policyRuleName>
<ns1:challengeSuccess>N/A</ns1:challengeSuccess>
<ns1:channelIndicator>ATM</ns1:channelIndicator>
<ns1:triggeringRuleType>Y</ns1:triggeringRuleType>
<ns1:orgId>dummy</ns1:orgId>
<ns1:clientDefinedEventType>NA</ns1:clientDefinedEventType>
<ns1:userId>user</ns1:userId>
<ns1:atmId>1234</ns1:atmId>
<ns1:atmOwner>FI</ns1:atmOwner>
<ns1:location>
<ns1:country>isr</ns1:country>
<ns1:state>ISR</ns1:state>
<ns1:city>PARIS</ns1:city>
<ns1:zip>123</ns1:zip>
</ns1:location>
<ns1:locationType>STREET</ns1:locationType>

<ns1:userInternationalAcctNumber>123456</ns1:userInternationalAcctNumber>
<ns1:atmCardAge>-1</ns1:atmCardAge>
<ns1:atmAmount>
<ns1:amount>12</ns1:amount>
<ns1:amountInUSD>45</ns1:amountInUSD>
<ns1:currency>USD</ns1:currency>
</ns1:atmAmount>
</ns1:eventDetails>
<ns1:customFactsList/>
<ns1:ipDetails/>
<ns1:riskContributorsList/>
</ns1:caseEvents>
<ns1:eventCount>1</ns1:eventCount>
</ns1:response>
<ns1:callStatus>
<ns1:status>SUCCESS</ns1:status>
</ns1:callStatus>
</ns1:getActivitiesResponse>
</soapenv:Body>
</soapenv:Envelope>

getCases Method
The getCases method retrieves only the metadata for the cases selected for retrieval.
This method uses a filter to set the selection criteria for the data retrieval. Cases are
selected according to this selection criteria.
Request for the getCases Method

The following table is a list of the data elements (caseFilter ) which, combined, define
the selection criteria for the request structure for this method.
caseStatus The status of a case. If not selected, only open cases N String
are retrieved. The case statuses are:
Open Case
New
Couldnt contact user
In progress
Closed
For more information about a case status, see the
Case Status section in Chapter Managing Cases
in RSA Adaptive Authentication (On Premise) in
the Back Office Users Guide.
caseResolution The resolution determination for a specific case. For N Resolutions

the list of resolution values, see resolutions
Values on page 218.
userId The identification of the user. N String
caseMaxScoreEventTy The event type of the representative flagged event N String

pe with the highest risk score.
maxScorePolicy Rule The policy rule name triggered by representative N String

Name flagged event with the highest risk score.
caseMaxScorePolicy The policy action recommended for the N String

Action representative flagged event with the highest risk
score.
caseTimeFilter The beginning and end of the retrieval period (range N caseTimeFilter
of the cases dateUpdated). For more information,
see caseTimeFilter on page 232.
Note: Without limits on the retrieval time period,

data retrieval can take a very long time. Enter the
caseTimeFilter fields to allow for an efficient
selection process.

caseMaxRiskScoreFilte This parameter includes the To and From fields, N Integer

r indicating the range of maximum case risk scores
for retrieval. The maximum range is 0-1000
ipFilter This parameter consists of both the IP address and N ipFilter

the country from which it is located. For more
information, see ipFilter on page 218.
caseId The identification code for a specific case. N Integer
orgId The identification of an organization to which a case N String

belongs.
Note: If not specified, the application uses the

Default organization identification.
operatorUserName The user name of the operator assigned to the case. N String
The default value is fraudanalyst.
Note: If this data element is not specifically chosen

as selection criteria, the default value is
automatically included in the filter.
caseMode The contributing factor by which an event was N String

flagged and became associated with a case. The
options are:
ANY - the events associated with a case were
flagged by either production or test
PRODUCTION - at least one event associated
with a case was flagged by production
TEST- all events associated with a case were
flagged by a test rule to create the case
userInternationalAcct The number of the users account in IBAN format. N String (100)
Number
Note: Use this parameter to retrieve ATM activities
for a specific users account. ATM monitoring only
recognizes the users account in IBAN format.

caseTimeFilter
The caseTimeFilter consists of a date range, indicating the beginning and end of the
retrieval period. An case is retrieved if the dateUpdated is within the range of the
caseTime filter.
From This is the beginning of the case retrieval period. A String supported by Java
cases dateUpdated must be equal to or greater than Simple Date format
this date.
To This is the end of the case retrieval period. A cases String supported by Java
dateUpdated must be equal to or less than this date. Simple Date format
Note: The To date value must be equal to or less than the From date value.
Important: For both the From and To date fields, the date format is yyyy-MM-dd
HH:mm:ss.SSS.
For example, if the From date is September 21,2012 at 3:45 PM, the date is
represented as: 2012-09-21 15:45:00.
Response for the getCases Method

The response structure (getCasesResponse) is made up of either zero or one or more
cases. The number of cases retrieved (caseCount) is reported at the end of the
response. Specific data items for each case, especially the caseId, are returned in the
response.
The response for the getCases method (getCasesResponse) returns either zero or one
or more events. The getCasesResponse structure consists of the response sub-
structure and the call status information. For the callStatus definitions, see
callStatus on page 220.
The following is a description of the sub-structures in the getCasesResponse
structure:
The response sub-structure is made up of the case sub_structure and the
caseCount.
The caseCount is the number of cases retrieved by the SOAP call. It is reported at
the end of the response sub-structure.
The case sub-structure lists the metadata of a single case.

The following table is the list of the data elements which comprise the metadata of a
single case within the response structure for this method:
caseId The ID for a specific case. Integer
dateCreated The date the case was created. Datetime
dateUpdated The date the case was last updated. Datetime
userId The identification code of the user who issued the case Integer
orgId The identification of the organization with which the String

case is associated.
caseStatus The status of a case. String
resolution The resolution of the case. String
maxScoreActivity The maximum risk score of the event associated with String
the case that has the highest risk score.
maxRiskScore The risk score of the event associated with the case that Integer
has the highest risk score.
maxScoreIpAddress The IP address of the event associated with the case that String
has the highest risk score.
maxScoreIpCountry The IP country of the event associated with the case String
that has the highest risk score.
maxScorePolicyAction The policy action recommended for the event String

associated with the case that has the highest risk score.
assignedToUserName The user name of the user to which the case is assigned. String
lockedAt The date and time the case was last locked. Datetime
lockedBy The identification of the last user who locked the case. String
snoozedAt The date and time the case was last snoozed. For more Datetime
information about cases in snooze mode, see the
Snooze Mode section in the chapter Managing
Cases in RSA Adaptive Authentication (On Premise)
in the Back Office Users Guide.
userInternationalAcct The number of the users account in IBAN format. String (100)
Number
Note: This data element is used only for ATM activities

getCases Sample SOAP Request

This is a sample of a SOAP request for the getCases method:
<soapenv:Body>
<typ:getCases xmlns:typ="http://ws.rsa.com/cm/types">
<typ:caseFilter>
<typ:caseStatus xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
<typ:caseResolution xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
<typ:userId>user</typ:userId>
<typ:caseTimeFilter xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
<typ:ipFilter xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
<typ:orgId>default</typ:orgId>
</typ:caseFilter>
<typ:paging>
<typ:pageSize>5</typ:pageSize>
<typ:offset>0</typ:offset>
</typ:paging>
</typ:getCases>
</soapenv:Body>
</soapenv:Envelope>

getCases Sample SOAP Response

This is a sample of a SOAP response with one activeCase returned for the getCases
method:
<soapenv:Body>
<ns1:getCasesResponse xmlns:ns1="http://ws.rsa.com/cm/types">
<ns1:response>
<ns1:case>
<ns1:caseId>162</ns1:caseId>
<ns1:caseStatus>NEW</ns1:caseStatus>
<ns1:maxRiskScore>4</ns1:maxRiskScore>
<ns1:maxScorePolicyAction>DENY</ns1:maxScorePolicyAction>
<ns1:assignedToUserName>fraudanalyst</ns1:assignedToUserName>
<ns1:lockedBy>0</ns1:lockedBy> <ns1:userInternationalAcctNumber>123</
ns1:userInternationalAcctNumber>
</ns1:case>
<ns1:caseCount>1</ns1:caseCount>
</ns1:response>
<ns1:callStatus>
</ns1:callStatus>
</ns1:getCasesResponse>
</soapenv:Body>
</soapenv:Envelope>

getCase Method
The purpose of the getCase method is to retrieve the data for one specific case. The
selection criteria for this method is only the case identification (caseId) of the specific
case required.
If the case selected is to be updated, this method enables you to lock the case, prior to
the update. For more information on locking a case, see Locking Process
Implementation on page 210.
Request for the getCase Method

The following table lists the data elements of the request structure for this method.
caseId The identification number of the case to be retrieved. Y Integer
operatorUserName The user name of the operator requesting the case N String
retrieval. The default value is fraudanalyst.
Note: If this data element is not specifically chosen as

selection criteria, the default value is automatically
included in the filter.
lock Determines whether or not the case should be locked Y Boolean

for the update.

Response for the getCase Method

The response for the getCase method (getCaseResponse) returns all the data for a
single case. A case is made up of the cases metadata and all the data for all the events
associated with that case. The getCaseResponse structure is a combination of the sub-
structures for both the getCases and getActivities methods.
Important: Encode the information retrieved by this method before the information is
exposed to your end users. Encoding data is used to prevent potential cross site
The following is the description of the organization of the sub-structures in the

getCaseResponse structure:
There is one case sub-structure. It is the same as the case sub-structure of the
getCases response. See Response for the getCases Method on page 232.
For each event associated with the case retrieved, there is an event sub-structure.It
is the same as the caseEvent sub-structure of the getActivities response. It is made
up the following sub-structures:
eventDetails
The eventId is listed in this sub-structure.
customFactsList
ipDetails
The call status information is at the end of the getCaseResponse structure. For the
callStatus definitions, see callStatus on page 220.
getCase Sample SOAP Request

This is a sample of a SOAP request for the getCase method:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:typ="http://

ws.rsa.com/cm/types">
<soapenv:Header/>
<soapenv:Body>
<typ:getCase>
<typ:caseId>162</typ:caseId>
<typ:operatorUserName>fraudanalyst</typ:operatorUserName>
<typ:lock>true</typ:lock>
</typ:getCase>
</soapenv:Body>
</soapenv:Envelope>

getCase Sample SOAP Response

This is a sample of a SOAP response for the getCase method:
<soapenv:Body>
<ns1:getCaseResponse xmlns:ns1="http://ws.rsa.com/cm/types">
<ns1:event>
<ns1:eventDetails>
<ns1:eventId>fcf7-:fd4bb419931:5cba5794-_TRX</ns1:eventId>
<ns1:eventType>WITHDRAW</ns1:eventType>
<ns1:amountCurrency>NIS</ns1:amountCurrency>
<ns1:policyAction>DENY</ns1:policyAction>
<ns1:policyRuleName>Rule15-Withdraw and Channel
Indicator=ATM</ns1:policyRuleName>
<ns1:channelIndicator>ATM</ns1:channelIndicator>
<ns1:triggeringRuleType>Y</ns1:triggeringRuleType>
<ns1:atmId>987654321</ns1:atmId>
<ns1:atmOwner>FI</ns1:atmOwner>
<ns1:location>
<ns1:country>rus</ns1:country>
<ns1:state>ISR</ns1:state>
<ns1:city>PARIS</ns1:city>
<ns1:zip>1234</ns1:zip>
</ns1:location>
<ns1:locationType>OTHER</ns1:locationType> <ns1:userInternationalAcctNumber>123</
ns1:userInternationalAcctNumber>
<ns1:atmAmount>
<ns1:currency>NIS</ns1:currency>
</ns1:atmAmount>
</ns1:eventDetails>
<ns1:ipDetails/>
</ns1:event>

<ns1:event>
<ns1:eventDetails>
<ns1:eventId>1df7-:fd4bb419931:5cba5794-_TRX</ns1:eventId>
<ns1:eventType>ENROLL</ns1:eventType>
<ns1:policyAction>ALLOW</ns1:policyAction>
<ns1:policyRuleName>FALLBACK RULE</ns1:policyRuleName>
<ns1:channelIndicator>WEB</ns1:channelIndicator>
<ns1:triggeringRuleType>N</ns1:triggeringRuleType>
<ns1:location>
<ns1:country>NA</ns1:country>
<ns1:state>NA</ns1:state>
<ns1:city>NA</ns1:city>
<ns1:zip>NA</ns1:zip>
</ns1:location>
<ns1:atmAmount>
</ns1:atmAmount>
</ns1:eventDetails>
<ns1:ipDetails/>
</ns1:event>
<ns1:callStatus>
</ns1:callStatus>
</ns1:getCaseResponse>
</soapenv:Body>
</soapenv:Envelope>

updateActivity Method
The purpose of the updateActivity method is to update the resolution data for an event.
The selection criteria for this method is the identification (eventId) of the specific
event to be updated.
An event must be locked prior to update. An event is locked when the case associated
with the event is locked. The case is automatically locked if it is not locked prior to
update. For more information on locking a case and its events, see Locking Process
Implementation on page 210.
Request for the updateActivity Method

The following table lists the data elements (activity) of the request structure for this
method.
eventId The identification of the event to be updated. Y Integer
resolution The resolution determination for the event updated, Y Resolutions

selected by the operator. For a list of resolution values,
see resolutions Values on page 218.
operatorUserName The operator name of the user requesting the case to be N String
updated. If not populated, the parameter is
automatically assigned the default value fraudanalyst.
Note: A case is assigned to the operator name of the

user who locks the case. A case cannot be reassigned to
a different operator name.

Response for the updateActivity Method

The response structure (updateResponse) is the same for both the updateActivity and
updateCase methods. The structure consists only of the callStatus sub-structure. For
the callStatus definitions, see callStatus on page 220.
updateActivity Sample SOAP Request

This is a sample of a SOAP request for the updateActivity method:

<soapenv:Header/>
<soapenv:Body>
<typ:updateActivity>
<typ:activity>
<typ:eventId>7e66-:ac6f55da931:c01f24d5-_TRX</typ:eventId>
<typ:resolution>CONFIRMED_GENUINE</typ:resolution>
<typ:operatorUserName>fraudanalyst</typ:operatorUserName>
</typ:activity>
</typ:updateActivity>
</soapenv:Body>
</soapenv:Envelope>
updateActivity Sample SOAP Response

This is a sample of a SOAP response for the updateActivity method:
<soapenv:Body>
<ns1:updateResponse xmlns:ns1="http://ws.rsa.com/cm/types">
<ns1:callStatus>
</ns1:callStatus>
</ns1:updateResponse>
</soapenv:Body>
</soapenv:Envelope>

updateCase Method
The purpose of the updateCase method is to update specific data for a case. The
selection criteria for this method is the identification (caseId) of the specific case to be
updated.
Request for the updateCase Method

The following table lists the data elements (case) of the request structure for this
method. It also includes the parameter to unlock the case following the update.
For more information on locking a case, see Locking Process Implementation on
page 210.
assignedToUserName The operator name of the user requesting the case to be N String
updated. If not populated, the parameter is
automatically assigned the default value fraudanalyst.
Note: A case is assigned to the operator name of the

user who locks the case. A case cannot be reassigned to
a different operator name.
caseId The identification of the case to be updated. Y Integer
caseStatus The status of a case. The case statuses are: Y String

Open Case
New
Couldnt contact user
In progress
Closed
For more information about a case status, see the Case
Status section in Chapter Managing Cases in RSA
Adaptive Authentication (On Premise) in the Back
Office Users Guide.
releaseLock Determines whether or not the case should be unlocked Y Boolean

after the update.

Response for the updateCase Method

The response structure (updateResponse) is the same for both the updateActivity and
updateCase methods. The structure consists only of the callStatus sub-structure. For
the callStatus definitions, see callStatus on page 220.
updateCase Sample SOAP Request

This is a sample of a SOAP request for the updateCase method:

<soapenv:Header/>
<soapenv:Body>
<typ:updateCase>
<typ:updateCaseType>
<typ:assignedToUserName>fraudanalyst</typ:assignedToUserName>
<typ:caseId>1001</typ:caseId>
<typ:caseStatus>CLOSED</typ:caseStatus>
</typ:updateCaseType>
<typ:releaseLock>true</typ:releaseLock>
</typ:updateCase>
</soapenv:Body>
</soapenv:Envelope>
updateCase Sample SOAP Response

The SOAP response for the updateCase method is identical to the response for the
updateActivity method. See updateActivity Sample SOAP Response on page 241.

Error Messages
When issuing the Case Management API SOAP calls, there is the possibility of errors
occurring due to incorrect application of the Case Management API methods.
The following table lists the error messages displayed for each Case Management API
method and the situation that caused the error:
Case Management
Error Message Cause for Error
API method
getActivities and (exception) org.apache.axis2.AxisFault: In one of the dates in the

getCases DAY_OF_MONTH eventTimeFilter, the day is invalid.
(exception) org.apache.axis2.AxisFault: In one of the dates in the

MONTH eventTimeFilter, the month is invalid.
(exception) org.apache.axis2.AxisFault: In one of the dates in the

YEAR eventTimeFilter, the year is invalid.
(exception) org.apache.axis2.AxisFault: There is an invalid string in the

Invalid string to parse eventTimeFilter data.
(exception) org.apache.axis2.AxisFault . One o f the values in the riskScoreFilter

java.lang.RuntimeException. at is out of range.
com.rsa.cm.ws.axis.generated.types.Risk
ScoreType.setRiskScoreType
(exception) org.apache.axis2.AxisFault One of the IPaddresses in the ipFilter is

java.lang.RuntimeException at invalid.
com.rsa.cm.ws.axis.generated.types.IpTy
pe.setIpType
getCase Case is already locked by different The lock parameter is true and the case is
operator locked by a different user.
No case with such an ID exists There is no case with this identification

number in the application system.
updateActivity Cannot update activity: Illegal resolution The resolution value is set to ANY.
value
User name <user name> is not a The operatorUserName value is a user

registered operator in the system who is not registered in the system.
Cannot update activity: case already The activity to be updated is associated

locked by different operator with a case that is locked by a different
user.

Case Management
Error Message Cause for Error
API method
updateCase Unable to update case: no such case The identification number of the case to
exists be updated does not exist in the
application system.
User name <user name> is not a The assignedToUserName value is the

registered operator in the system user who is not registered in the system.
Case is already locked by different The case to be updated is locked by a

operator different user.

13 ATM Protection Module

The ATM protection module focuses on the monitoring of ATM activities. Its purpose
is to transfer specific ATM-related information to the RSA Adaptive Authentication
(On Premise) Risk Engine. The Risk Engine analyzes this information, resulting in a
risk score and recommended action, which triggers ATM policy rules.
The ATM-related information amassed for monitoring purposes includes:
the users personal information
the users card information
the information about the ATM device
the information about ATM activity
This chapter lists the data elements that comprise the ATM payload. These data
elements are classified as either ATM-specific or as those that are already part of the
analyze method data structure. The latter are mentioned in this chapter as necessary to
the Risk Engine for analyzing ATM activity.
In this chapter, each data element is described not only by its general characteristics
but also by its position in the analyze method data structure.
To learn all about the analyze method, see the topicanalyze Method,on page 70 in
the chapter Web Services API Methods.
ATM Request Payload

Within the Adaptive Authentication SOAP API, the ATM SOAP call format is similar
to the deviceIdentifier structure within the analyze method for a channel or a device.
As a result, the ATM request payload inherits the deviceIdentifier characteristics. The
ATM payload is only valid when the channel indicator is set to ATM. Otherwise, it is
ignored.
Important: Since createUser for ATM is not supported, set the

autoCreateUserFlag to true. For more information about this flag, see the topic
AnalyzeRequest Message on page 70 in the chapter Web Services API
Methods.
The data elements required by the ATM monitoring function are located in the
following sections of the analyze method:
request - This section identifies the SOAP call as an ATM request.
identificationData - This section includes the users personal information.
messageHeader - This section provides general information about the analyze
request.
securityHeader - This section is used to authenticate the caller to the server.
13: ATM Protection Module 247

channel - This section is dedicated to ATM-specific data.

eventDataList - This section consists of transaction information.
The data elements in the ATM payload data structure are defined as either Mandatory,
Required or Optional such that:
Mandatory fields must be populated.
Required fields supply information that is essential for effective analysis
performed by the Risk Engine.
Optional fields store informative data. It is recommended to populate these
fields if the information is available.
The following tables define the ATM payload data structure.
Request
The request section consists of the entire analyze data structure including the sections
required for the ATM payload.
The following table lists the data elements related to the ATM payload,
Data Element Description Type Required
channelIndicator The channel device type. For a list of the channel ChannelIndica Mandatory
indicator types, see channelIndicatorType values torType
on page 224.
Note: Enter ATM for the ATM payload.
Important: If the value is ATM, this data element

triggers the transfer of the ATM activity data to the
Risk Engine.
actionTypeList The list of actions your application can initiate for GenericAction Optional
the analyze method when the channel is ATM. Type
For the list of action type values, see
GenericActionType Values on page 107.
248 13: ATM Protection Module

Identification Data
The identificationData section provides user information including data required for
the ATM payload.
userName For the ATM payload, the value of this data element String (50) Mandatory
is a representation of the card number.
Important: For security purposes, RSA recommends

that you tokenize the card number.
orgName The organization to which the user belongs. An String (50) Required
identification number for the organization is created
in the Orgs and Groups application.
Note: Refer to the Operations Guide for more

information about the Orgs and Groups application.
Message Header
The messageHeader structure includes a number of data elements that provide
general information about the analyze request. The table below lists the data elements
related to ATM.
requestId This value is unique per request and is generated by Integer Required
the request process.
timeStamp The date and time of the event is created in GMT String Optional
format. This value is used when the supported by
timeOfOccurrence is empty. Java Simple
The date format is yyyy-MM-dd HH:mm:ss.SSS. Date format
For example, if the date and time the event occurred
is September 21, 2012 at 3:45 PM, the date is
represented as: 2012-09-21 15:45:00.
version The Adaptive Authentication Web Services version. Float Required

Default value is 7.0

securityHeader
The securityHeader structure includes the data elements used to authenticate the
caller to the server. The table below lists the required data elements required..
callerCredential This is the password of the caller initiating the String Required
request message. This is not the users password.
callerId This is used to authenticate the caller initiating the String Required
request message. This is not the users ID.
method This is the authorization method used for credential String Required
encryption. The default value is PASSWORD.
Channel
This is the main section of the ATM payload. The section contains all the ATM-
specific data.
timeZone The local time zone of the ATM location. The range of Float Required
values is -12 - + 12.
atmOwner This specifies if the owner of the ATM device is an String (20) Mandatory
RSA customer who is implementing the Adaptive
Authentication ATM Protection Module.
The two values accepted for this field are:
FI - the financial institution that owns the ATM
device and is implementing the Adaptive
Other - the financial institution that owns the ATM
device and is not implementing the Adaptive
atmID The global unique identification of the ATM device. String (20) Mandatory
locationType The type of location where the ATM device resides. LocationType Required
For the list of pre-defined values, see Location Type
Values on page 253.
cardIssueDate The date the users credit or debit card was issued, in String Required
GMT format. supported by
example, if the card issue date is September 21,2012 at Date format
3:45 PM, the date is represented as: 2012-09-21
15:45:00.

atmLanguage The language chosen by the user for the ATM user String (25) Required
interface.
location The geographic location of the ATM devices consisting Location Required
of the physical address and the geographic coordinates.
For details about the Location data structure, see
Location on page 254.
atmIP The internal or external IP address assigned to the ATM IpType Optional
device. The IP address must be in either IpV4 or IpV6
format.
userGender The users gender. Gender Required

The two values acceptable for this field are:
Male
Female.
atmExternalScore The ATMs risk score associated with the bank or other Integer Optional
financial institution.
The acceptable range is zero to 1000.
loginFailureReason The reason behind a failed logon . There is a pre- FailureReaso Optional
defined list of values from which to choose. n
For the list of pre-defined values, see Login Failure
Reason Values on page 255.
numberOfFailed The number of failed attempts made prior to the Integer Optional
Logins successful logon.
userYearOfBirth The users year of birth. This field is used to calculateInteger Required
the users age. (Format:
Acceptable values for a users age are in the range from YYYY)
15 to 120.
cardPinChangeDate The date the users credit or debit card PIN number was String Required
last changed, in GMT format. supported by
example, if the card PIN change date is September Date format
09-21 15:45:00.
atmModel The model type of the ATM device. String (50) Optional
atmOS The operating system running on the ATM device. String (50) Optional

atmOwnerOther The name of the ATM owner. String (50) Optional

If the ATM owner is a financial institution, enter the
bank identification code. Otherwise, if the owner is not
a financial institution, enter the owner name.
cardIssuerId The identification of the business organization that String (50) Optional
issued the users card.
cardType The type of credit card. For example, two possible String (50) Optional
values for this field are:
Credit
Debit.
atmDailyLimit The maximum daily cash amount allowed for atmDailyLimi Required
withdrawal from an ATM device. t
cardDailyLimit The maximum daily cash amount allowed for cardDailyLim Required
withdrawal using a users card. it
atmDailyLimit
The atmDailyLimit structure includes the daily limit information for cash amounts
withdrawn from the ATM device.
amount The maximum cash withdrawal amount per day Long Required
allowed for an ATM device. The value is in the
lowest monetary denomination for the original
currency.
amountInUSD The resulting amount in USD for maximum daily Long Required
cash withdrawal amount from an ATM device,
following monetary conversion, by a static currency
conversion table. See note below.
currency The code that represents the original currency String(3) Required
according to ISO standard 4217.

cardDailyLimit
The cardDailyLimit structure includes the daily limit information for cash amounts
withdrawn using a users credit or debit card.
amount The maximum cash withdrawal amount per day Long Required
allowed for a users credit or debit card. The value is
in the lowest monetary denomination for the
original currency.
amountInUSD The resulting amount in USD for maximum daily Long Required
cash withdrawal amount for a users debit or credit
card , following monetary conversion, by a static
currency conversion table. See note below.
Note: .RSA recommends to convert the amount in original currency to USD and enter
Location Type Values

The following table lists the pre-defined location types including their descriptions.
Location Type Description
BANK BRANCH An ATM located within a branch of a bank.
PETROL STATION An ATM located on the premises of a gas station.
PUBLIC TRANSPORT An ATM located on the premises of a public transport station such as a
bus station or an underground (subway) station.
STREET An ATM located on the street not adjacent to any financial institution or
other facility.
CONVENIENCE STORE An ATM located on the premises of a convenience store like a kiosk, a 24-
hour fast-food chain, or an all night market.
SUPERMARKET An ATM located on the premises of a supermarket.
LEISURE FACILITY An ATM located on the premises of a country club, sports club(gym),
resort, or other leisure facility.
DRIVE THRU An ATM located adjacent to a branch of a bank with a drive-thru window
for banking transactions.

Location Type Description
ENTERTAINMENT VENUE An ATM located on the premises of a bar, bistro, restaurant, sports
stadium, amusement or theme park, movie theatre complex, or other
entertainment venue.
TRANSPORT TERMINAL An ATM located on the premises of a transport terminal such as an airport
or a train station.
POST OFFICE An ATM located on the premises of a post office.
RETAIL OUTLET An ATM located on the premises of a store, a shopping mall, or other
retail outlet.
CASINO An ATM located on the premises of a casino.
GOVERNMENT OFFICE An ATM located on the premises of a government office building.
OTHER An ATM located on the premises of a facility not mentioned in the pre-
defined list.
Location
The Location section includes the ATMs geographic location including its
coordinates.
The following table lists the data elements that define the ATMs actual location
including their descriptions.
country The country in which the ATM is located. String Required
state The state in which the ATM is located. String Required
city The city in which the ATM is located. String Required
address The street address of the building in which the String Required
ATM is located.
zip The 10-digit code for the neighborhood in which String Required
the ATM is located.
geoCoordinates The coordinates of the physical location of the GeoLocation Required

ATM device. The coordinate parameters required
for ATM monitoring are:
latitude
longitude
altitude (elevation).
For more specific information about these
coordinates, see GeoLocation on page 133.

Login Failure Reason Values

The following table lists the pre-defined Login Failure Reasons including their
descriptions.
Login Failure Reason Description
Card on Blacklist The card is on the account Blacklist.
Card Expired The card is expired.
Card Lost The card is lost.
Card Nonexistent The card does not exist.
Incorrect PIN The card PIN number entered is incorrect.
Incorrect CVV The card verification value entered is incorrect.
Event Data List

The eventDataList section contains all event information. The following tables
describe the event data related to the ATM activities.
Event Data
The eventData section identifies the type of event. It also includes the transaction
information. The following are the event types that are protected by the ATM
Protection Module:
Card PIN Change
Change Password
Deposit
Failed Login Attempts
Login
Money Transfer
View Statement
Withdrawal

The following table lists the eventData data elements that are required for the ATM
payload:
eventType The type of event of the users transaction. EventType Mandatory
Note: The event types relevant for the ATM

Protection Module are listed in Event Data on
page 255.
userExternalScore An external risk score (from another system) Integer Optional

associated with the users identification or the users
card.
The acceptable range is zero to 1000.
timeOfOccurrence The date and time of the event. The date should String Required
follow the ISO 8601 format. supported by
The date format is yyyy-MM-dd HH:mm:ss.SSS. Java Simple
For example, if the date and time the event occurred Date format
is September 21,2012 at 3:45 PM, the date is
represented as: 2012-09-21 15:45:00.
Important: If this data element is empty, then

timeStamp in the messageHeader is used for the
event date and time. If timeStamp is empty, the
application will use the System date and time.
runRiskType A flag that determines whether the risk engine RunRiskType Mandatory
should be run.
Note: For ATM, the only acceptable value is ALL.
Transaction Data
The transactionData section includes the following sections relevant to the ATM
payload.
amount The amount of the monetary transaction issued Amount Required

using the ATM device.
myAccountData The users personal banking information MyAccountData Required
otherAccountData The payees account numbers in standard and OtherAccountData Required

international formats.

Amount
The amount structure includes information about the following transactions
withdrawal
payment
deposit
other money transfer activities
amount The transaction amount in the lowest monetary Long Required

denomination for the original currency.
amountInUSD The resulting transaction amount in USD following Long Required

monetary conversion, by a static currency
conversion table. See note below.
the converted amount to the data element, amountInUSD. This is because the
monetary conversion rates in the static conversion table are not kept current.
MyAccountData
The myAccountData section lists the users personal banking information. The
following table lists the users account information for ATM purposes.
accountName The name of the users card account. String Optional
accountNumber The users account number in standard format. String (50) Required
internationalAccou The users account number in IBAN format. String (100) Mandatory
ntNumber
OtherAccountData
The otherAccountData section includes the payee account information used for ATM
purposes.
accountNumber The payees account number in standard format. String (50) Required
internationalAccou The payees account number in IBAN format. String (100) Required
ntNumber

Sample Analyze SOAP Request for ATM

This is a sample of a SOAP request for the analyze method for the channel indicator
set to ATM:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/

2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://
ws.csd.rsa.com">
<soap:Body>
<tns:analyze>
<tns:request>
<tns:actionTypeList> <tns:genericActionTypes>SET_USER_STATUS</tns:genericActionTypes>
</tns:actionTypeList>
<tns:identificationData>
<tns:userName>user</tns:userName>
<tns:userStatus>VERIFIED</tns:userStatus>
<tns:userType>PERSISTENT</tns:userType>
</tns:identificationData>
<tns:messageHeader>
<tns:apiType>DIRECT_SOAP_API</tns:apiType>
<tns:requestType>ANALYZE</tns:requestType>
<tns:version>7.0</tns:version>
</tns:messageHeader>
<tns:securityHeader>
<tns:callerCredential>password</tns:callerCredential>
<tns:callerId>callerId</tns:callerId>
<tns:method>PASSWORD</tns:method>
</tns:securityHeader>
<tns:channel xsi:type="tns:ATM">
<tns:timezone>2</tns:timezone>
<tns:atmOwner>FI</tns:atmOwner>
<tns:atmID>1234</tns:atmID>
<tns:locationType>STREET</tns:locationType>
<tns:cardIssueDate>2012-12-31</tns:cardIssueDate>
<tns:atmLanguage>ENG</tns:atmLanguage>

<tns:location>
<tns:country>isr</tns:country>
<tns:state>ISR</tns:state>
<tns:city>PARIS</tns:city>
<tns:address>V</tns:address>
<tns:zip>123</tns:zip>
<tns:geoCoordinates>
<tns:longitude>19.7244</tns:longitude>
<tns:latitude>156.0787</tns:latitude>
<tns:altitude>0</tns:altitude>
</tns:geoCoordinates>
</tns:location>
<tns:cardPINChangeDate>2012-12-31</tns:cardPINChangeDate>
<tns:atmOS>windows</tns:atmOS>
</tns:channel>
<tns:autoCreateUserFlag>true</tns:autoCreateUserFlag>
<tns:eventDataList>
<tns:eventData>
<tns:eventType>WITHDRAW</tns:eventType>
<tns:transactionData>
<tns:myAccountData> <tns:internationalAccountNumber>123</
tns:internationalAccountNumber>
</tns:myAccountData>
</tns:transactionData>
</tns:eventData>
</tns:eventDataList>
<tns:runRiskType>ALL</tns:runRiskType>
<tns:channelIndicator>ATM</tns:channelIndicator>
</tns:request>
</tns:analyze>
</soap:Body>

ATM Analyze Response

The ATMAnalyzeResponse is based on the standard response for the Analyze
method. The Analyze response includes the generic API response structure and the
specific structures required for the Analyze method response.
For more information concerning the Analyze method response, see the section
AnalyzeResponse Message on page 72 in chapter Web Services API Methods.
ATM Response Payload

The ATM response payload is similar to the Analyze response payload. The payload
is made up of:
identificationData
messageHeader
statusHeader
riskResult
Identification Data
The identificationData section for the ATM response payload not only provides user
information but also transaction identification information
.
delegated Is the request coming from a customer service Boolean Optional

representative?
transactionId The identification number of a specific event for a String Required

given transaction. In this case, it identifies an ATM
transaction.
For specific information about this data element, see
identificationData on page 156 in chapter Web
Services Response Data Structures and Types.
userName The users user name. It should be the credit or debit String (50) Mandatory
card user name.
Important: The value entered should not be the user

name for the internet on-line banking site.
orgName The organization to which the user belongs. An String (50) Mandatory
identification code for the organization is created in
the Orgs and Groups application.
Note: Refer to the Operations Guide for more

information about the Orgs and Groups application.

Message Header
The messageHeader section for the ATM response payload is the standard data
structure of the generic response for all methods.
For the list of data elements for this data structure, see messageHeader on page 158
in chapter Web Services Response Data Structures and Types.
Status Header
The statusHeader section for the ATM response payload is the standard data structure
of the generic response for all methods. If the status is not completed successfully, an
error is reported.
For the list of data elements for this data structure, see statusHeader on page 159 in
chapter Web Services Response Data Structures and Types.
For a list of ATM-related errors, see ATM Error Messages on page 264.
Risk Result
The riskResult section for the ATM response payload is the standard data structure of
the Analyze response, an extension of the generic response for all methods. Its
purpose is to return the risk score and triggered rules due to the risk score.
For the list of data elements for this data structure, see riskResult on page 167 in
chapter Web Services Response Data Structures and Types.
Within this section is the triggeredRule. All its data elements are required. For the
specific data elements of this structure, see TriggeredRule Structure on page 168 in
the same chapter.

Sample Analyze SOAP Response for ATM

This is a sample of a SOAP response for the Analyze method for the channel indicator
set to ATM:
soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<ns1:analyzeReturn xsi:type="ns1:AnalyzeResponse" xmlns:xsi="http://www.w3.org/2001/
XMLSchema-instance">
<ns1:delegated>false</ns1:delegated> <ns1:transactionId>8fe7-:7cff54a8831:05956a86-_TRX</
ns1:transactionId>
<ns1:userName>TestUser</ns1:userName>
<ns1:userStatus>UNVERIFIED</ns1:userStatus>
<ns1:messageHeader>
<ns1:statusHeader>
<ns1:reasonDescription>Operations were completed successfully</ns1:reasonDescription>
</ns1:statusHeader>

<ns1:riskResult>
<ns1:riskScoreBand>SCORE_BAND_0</ns1:riskScoreBand>
<ns1:triggeredRule>
<ns1:actionCode>ALLOW</ns1:actionCode>
<ns1:actionName>FALLBACK RULE</ns1:actionName>
<ns1:clientFactList/>
<ns1:ruleId>FALLBACK RULE</ns1:ruleId>
<ns1:ruleName>FALLBACK RULE</ns1:ruleName>
</ns1:riskResult>
</soapenv:Body>
</soapenv:Envelope>

ATM Error Messages

When issuing the Analyze ATM SOAP calls, there is the possibility of errors
occurring due to incorrect application of the ATM data elements.
All data elements are validated for general, standard data integrity checks such as
nulls and illegal characters.
The following table lists the error messages for the ATM-related data elements, along
with their causes. They are issued by the Analyze method processing only when the
channel indicator is set to ATM.
Error
Data Element Error Message Message Explanation
Displayed
amount Yes Missing amount for money The transaction amount data
withdraw or transfer structure is blank or missing for
the event type is either Withdraw
or Transfer.
atmID Yes Missing mandatory field ATM ID No data entered for the ATM
identification number
atmLanguage No - validated Missing mandatory field No language entered for the

by Axis Language language chosen by the user for
the ATM user interface.
atmOwner No - validated Missing mandatory field Owner No data entered for the ATM
by Axis owner type.
cardIssueDate No - validated Missing mandatory field Card No data entered for the card issue
by Axis Issue Date date.
channel No - validated Channel field is not ATM type The channel is not for an ATM
by Axis device.
Yes Missing mandatory field Channel No channel section is not in

SOAP request.
clientReturnData Yes ClientReturnData is not allowed If the channel is ATM, the client
for ATM request return data is not accepted.
collectionRequest Yes CollectionRequest is not allowed If the channel is ATM, the

for ATM request collection request section is not
accepted.
configurationHea Yes ConfigurationHeader is not If the channel is ATM, the

der allowed for ATM request configuration header section is
not accepted.

Error
Data Element Error Message Message Explanation
Displayed
country Yes Country must be valid country An invalid value is entered for
code of 3 characters country.
deviceManageme Yes DeviceManagementRequest is If the channel is ATM, the device

ntRequest not allowed for ATM request management request section is
not accepted.
deviceRequest Yes DeviceRequest is not allowed for If the channel is ATM, the device
ATM request request section is not accepted.
eventDataList No - validated Missing mandatory field No eventDataList section is in the

by Axis EventDataList SOAP request.
eventType Yes Incorrect event for ATM The event type issued for the
ATM-related transaction is not
included in the pre-defined set of
event types valid for channel
ATM.
identificationData No - validated Missing mandatory field No identificationData section is in

by Axis IdentificationData the SOAP request.
locationType No - validated Missing mandatory field Location No data entered for the type of
by Axis Type location where the ATM device is
situated.
messageHeader No - validated Missing mandatory field No messageHeader section is in

by Axis MessageHeader the SOAP request.
runRiskType No - validated Missing mandatory field No data entered for the run risk
by Axis RunRiskType type.
timeOfOccurrenc No - validated Missing mandatory field No data entered for the date and
e by Axis Datetime time of the event.
timeZone No - validated Missing mandatory field No data entered for the time zone
by Axis Timezone where the ATM is situated.
userData No - validated UserData is not allowed for ATM If the channel is ATM, the
by Axis request userData section is not accepted.

A Out-of-Band Phone Authentication Plug-In

Overview
Authentication Plug-In Architecture for Out-of-Band Phone
Web Services Messaging for Out-of-Band Phone
Authentication Plug-In for Out-of-Band Phone Workflow
Activating Your Out-of-Band Phone Credential in Authentication Plug-In
Services
This chapter provides an overview of the Authentication Plug-In adapter for Out-of-
Band (OOB) Phone that works with Adaptive Authentication. For additional details,
see the Authentication Plug-in Developer Guide and the Authentication Plug-in
Installation Guide.
Overview
The Authentication Plug-In for OOB phone is part of the RSA Adaptive
Authentication (On Premise) product that uses OOB phone authentication.
Authentication Plug-In Service Provider facilitates the call to the customer for user
account verification via a One-Time-Password. This credential type integrates into
Adaptive Authentication Multi-Credential Framework (MCF), version 6.0.2 and
above.
The primary use-case is for the organization to send its online customer an automated
phone call through an Authentication Plug-In for additional OOB credentials. The
customer would receive a call that requests them to key in a confirmation code over
the phone. The confirmation code is generated by Adaptive Authentication and sent to
both the Authentication Plug-In Service Provider and served to the organization web
page for the user to retrieve and enter when prompted by the phone call. Also, the
organization will be able to deactivate the Authentication Plug-In feature as needed.
The overall OOB Authentication Plug-In workflow is as follows:
1. The organization performs data collection of users phone numbers for OOB
Authentication Plug-In use.
2. If additional authentication is required, it happens before the transaction is
complete. The user is prompted to select which telephone number (work, home,
cell) to be used in the OOB challenge.
3. The are the following enrollment scenarios:
a. User enrolls with phone information. There is no additional configuration
requirement for this scenario.
b. User enrolls without providing phone information. You need to configure the
c-config-mcf.xml file. Set phone_metadata clientManaged=true.
A: Out-of-Band Phone Authentication Plug-In 267

4. Authentication Plug-In sends an automated call to the users specified phone

number. If the Analyze Response message contains the following values:
requiredCredentialList is OOBPHONE, and actionCode is CHALLENGE, you
need to populate phoneInfo with values in the subsequent challenge request
message.
5. Your applications web page displays a confirmation code.
6. The user keys in the one-time password (confirmation code) into the phone
keypad.
7. The one-time password is validated by the Authentication Plug-In server.
8. If the user enters the correct code, the transaction continues.
Authentication with Authentication Plug-In is accomplished via the Multi-Credential
Framework (MCF).
Note: For more information about Email and OOB phone data structures in the Web
Servicesrequests, Appendix C, Out-of-Band Phone and Email Credential.
The following important terms that are used in this chapter are defined:
Token IDUsers one-time password that is provided by Authentication Plug-In
for the OOB phone challenge response.
One-time password (OTP) Same as the Token ID. The OTP that
Authentication Plug-In sends to the user for the OOB phone challenge response.
Your application Organizations client application
Client Managed Data

The organization can store and manage phone number data, called Client Managed
data, or Adaptive Authentication can store the data. To set up client managed data,
you need to set the value to True for clientManaged in the c-config-mcf.xml
file. The default setting is False.
clientManaged
<value>true</value>
//default value is false
Billing Data
Each user challenge activity is logged at the infrastructural level (by the Multi-
Credential Framework) into the table BILLING_TRANSACTIONS. This table
includes the Authentication Plug-In to which the transaction was sent, and the status
returned by Authentication Plug-In.
268 A: Out-of-Band Phone Authentication Plug-In

A sample of billing transaction data is shown below.

.
Authentication Plug-In Architecture for Out-of-Band Phone

The Adaptive Authentication OOB adapters fit into the overall architecture of the
Adaptive Authentication system. The Authentication Plug-In OOB adapter is part of
the system.
The Adaptive Authentication system with Authentication Plug-In connects to the
Authentication Plug-In Service Provider using XML and HTTPS (as shown in the
following figure). The individual components and services must interact to provide
the requisite functionality.
The Authentication Plug-In adapter is designed specifically to communicate with the
Authentication Plug-In Service Provider. The communication between the
Authentication Plug-In and the Authentication Plug-In provider is done using XML/
HTTPS. For a detailed description of the Web Services request and response
messages, refer to Appendix B, Out-of-Band Phone Authentication Plug-In Web
Services Messages.

Web Services Messaging for Out-of-Band Phone

The Web Services messaging is accomplished via server-to-server communication
using XML messaging over HTTPS.
The process of authenticating a user with an OOB challenge with an Authentication
Plug-In involves the following actions:
1. Your application sends the first analyze request to Adaptive Authentication. Next,
Adaptive Authentication sends a challenge action to your application, telling it to
challenge the user. Your application sends a challenge request message to
Adaptive Authentication that contains the users phone number to use for the
OOB challenge. If deployment is configured to have OOBPHONE with
Authentication Plug-In as a required credential.
2. Adaptive Authentication sends a challenge response message to your application
with the session ID, transaction ID and the token ID. At the same time, Adaptive
Authentication sends the phone number and Token to the Authentication Plug-In
Service Provider.
3. Authentication Plug-In calls the users phone number and prompts the user to
enter the token in the phone keypad.
4. Your application sends a queryAuthStatus request to Adaptive Authentication to
poll for authentication status, then Adaptive Authentication will poll
Authentication Plug-In Service Provider for status. Token broadcast for the token
collection flow is not supported.
5. Adaptive Authentication translates the general status codes received from the
Service Provider into Channel Status Codes, and sends the status codes to the
organization in the queryAuthStatus response.
6. Adaptive Authentication sends a poll request for status to the Authentication Plug-
In Service Provider, and receives a general status code from Authentication Plug-
In. Adaptive Authentication maps the general status code to a channel status code
and sends it to your application in a queryAuthStatus response message. When the
result is Success, Error, or Failure, the organization can stop querying for status.
7. Once the user is authenticated, the user can continue the transaction.
Authentication Plug-In for Out-of-Band Phone Workflow

This section describes the workflow between the Authentication Plug-In service
provider, and Adaptive Authentication system with the Authentication Plug-In adapter
installed.
Authentication Plug-In follows theAdaptive Authentication Synchronous-Challenge
Response workflow. Method calls at various stages in the workflow are outlined in the
workflow diagrams.

Challenge-Response Process
This section describes the OOB Phone credential collection process: Authentication
Plug-In Challenge-Response. The method calls are included in the diagram below.
.
Method Calls for Challenge-Response

Your application will call the following methods during the Synchronous Challenge-
Response process:
challenge(request) Starts the OOB notification process and returns a
payload indicating that the request was received. The challenge response contains
the session ID, transaction ID, and the token ID (OTP).

queryAuthStatus(request) Query the Adaptive Authentication system for

phone authentication status. The organization needs to continue querying
Adaptive Authentication until it receives a Success or Fail
queryAuthStatusResponse message.
Activating Your Out-of-Band Phone Credential in Authentication

Plug-In Services
To enroll a user with OOB Phone and Authentication Plug-In as the service provider,
see Chapter 2, Web Services Basic Processes.
Specifically, the OOB phone enrollment section pertains to the credential setup when
the user is first enrolled in Adaptive Authentication.
To activate your credential in Adaptive Authentication system for Authentication
Plug-In, you need to set the following parameters:
Credential.credentialProvisioningStatus to ACTIVESee Chapter 7, Web
OOBActionTypeList.ActionTypeList to ADD_OOBSee Chapter 7, Web
PhoneManagementRequestPayload.contactList -- This parameter should be
left empty.
You can set up these parameters during the createUser and updateUser requests, and to
set up credential activation parameters, see Appendix G, Challenge Question
Credential.

B Out-of-Band Phone Authentication Plug-In

Web Services Messages
Overview
Out-of-Band Phone Message Workflow
Out-of-Band Phone Status Codes
Out-of-Band Phone Response Data Structures and Types
Out-of-Band Phone Reason Codes
Analyze Response Message
Your Application Challenge Request Message
Adaptive Authentication Challenge Response Message
Query Authentication Status Request Message
Query Authentication Status Response Message
Phone Token Collection Through Online Session
This chapter explains how the RSA Adaptive Authentication (On Premise) system
(with Authentication Plug-In adapter installed) and the Authentication Plug-In Service
Provider accomplish the out-of-band (OOB) phone challenges via Web Services
request and response messages.
Note: For more information on how to prepare SOAP request and response messages,
see Chapter 9, AdminService API Methods.
Overview
Web Services messaging is accomplished by sending SOAP request and response
messages from your client application to the Adaptive Authentication system. The
Web Services call consists of two messages: a request, and a response.
Authentication Plug-In uses synchronous Web Services messaging. For each Web
Services request that your application issues, the system awaits an immediate response
from the Adaptive Authentication system. For details about how to create a SOAP
request, see Chapter 9, AdminService API Methods.
Your organization client sends challenge requests to initiate the out-of-band (OOB)
phone challenge with the Adaptive Authentication system. Your application also sends
queryAuthStatus requests to Adaptive Authentication to get the status of the
authentication.
B: Out-of-Band Phone Authentication Plug-In Web Services Messages 273

Your application receives the response message with the current status of the
authentication as follows:
If the phone authentication is complete, the response message indicates
SUCCESS or FAIL.
If the authentication is in-progress, the response message indicates PENDING for
the authentication status.
If there are system errors during the authentication process, the response message
indicates NULL status.
Response messages will contain the following status codes:
Call Status
Reason
Auth Status
Channel Status
For more details, see Channel Status Codes on page 276.
Message Message Contents
challengeRequest Your applications challenge request message contains the users phone
number.
challengeResponse The Adaptive Authentication challenge response message returns an OTP

(token ID), transaction ID, and session ID to your application.
queryAuthStatusRequest Your applications queryAuthStatus request message contains the

following challenge responses: session ID, transaction ID, and the OTP
(token ID).
queryAuthStatusResponse Adaptive Authentication returns a queryAuthStatus response message that

contains all the status codes. See Query Authentication Status Response
Message on page 288.
274 B: Out-of-Band Phone Authentication Plug-In Web Services Messages

Out-of-Band Phone Message Workflow

The messages between your application, Adaptive Authentication with Authentication
Plug-In for OOB Phone and the Authentication Plug-In Service Provider follow the
workflow shown in the following figure.

Out-of-Band Phone Status Codes

The challenge and queryAuthStatus response messages contain various status codes
to indicate specific aspects of the authentication process. The response message
includes the generic data elements such as session ID and transaction ID, and the
following elements:
Data Elements Description
authenticationResult Contains authStatusCode and the risk elements.
risk Risk score for the authentication.
authStatusCode Status of the authentication process. Possible values are:

PENDING
SUCCESS
FAIL
NULL
callStatus Contains statusCode and statusDescription elements.
statusCode Status of the web services call (session) from Adaptive Authentication to
Authentication Plug-In. Possible values are SUCCESS or FAIL.
statusDescription Description of the status code.
channelStatus Status of the OOB channel (phone call to the user).
reason A more detailed explanation of the status returned.
Channel Status Codes

The channel status codes found in the response for challenge and queryAuthStatus
requests have the values shown in the following table.
Values Description
CHALLENGE_FAILED The user has incorrectly replied to the OOB notification.
CHALLENGE_SUCCESS The user has correctly replied to the OOB notification.
CREATED The OOB channel has been created, and notification is in progres.s
EXPIRED The OOB notification has exceeded its time limit for a user's response
(default=10 minutes).
SYSTEM_ERROR A system failure has occurred during the notification progress.
UNREACHABLE The user is unreachable. Check the reasonCode for a more detailed description
of the user status.

If the Channel Status code is CREATED, your application searches for a status by
sending a queryAuthStatus request message to Adaptive Authentication.
If the Channel Status code is SYSTEM_ERROR, there is no query for status.
After sending the initial queryAuthStatus request message, if the Channel Status
code returned in the response is CREATED, subsequent queryAuthStatus requests
must be sent.
The challenge response messages contain several status codes:
authStatusCodeResult of the Authentication process; available values are
PENDING, or NULL.
channelStatus Status of the OOB channel; for a list of available values, see
Channel Status Codes on page 276.
ReasonDescription for channel status codes.
statusCode Status of the Web Services session; available values are
SUCCESS, FAIL, or ERROR.
Your application sends the users phone number in a challenge request to Adaptive
Authentication. When the Authentication Plug-In calls the users phone number, the
user answers and hangs up.
Your application receives the status codes in the queryAuthStatus response message
as follows:
Data Elements Example Value
authStatusCode FAIL
channelStatus Status.CHALLENGE_FAILED
Reason Reason.HANGUP
statusCode SUCCESS
Status Code Examples:


<ns1:callStatus>
</ns1:callStatus>




<ns1:channelStatus>Status.CHALLENGE_FAILED</ns1:channelStatus>


<ns1:reason>Reason.HANGUP</ns1:reason>

Out-of-Band Phone Response Data Structures and Types

AuthenticationResult
risk The risk score. Integer
authStatusCode The status code of the call. See AuthStatusCode Values for more String
information.
AuthStatusCode Values
authStatusCode Values Description
FAIL The user failed to pass the credential.
SUCCESS The user successfully passed the credential challenge.
PENDING The authentication of the credential is still pending. This value is commonly
passed during out-of-band credentials.
NULL There is a system error due to an infrastructure failure. The user has not
passed or failed authentication.
statusHeader
The statusHeader structure is returned only by the generic response, and contains
information about the message status.
reasonCode A more detailed explanation of the status being returned. For a detailed Integer
list of the reasonDescriptions, see Out-of-Band Phone Reason Codes
on page 280.
reasonDescription An explanation of the Web Services call status. For a detailed list of the String
reasonDescriptions, see Out-of-Band Phone Reason Codes on
page 280.
statusCode The status code of the Web Services operation. Integer

statusCode Values
The statusCode indicates the overall status of the Web Services operation.
statusCode Description Additional Information
200 The Web Services operation was This value refers to the completion of an actual
completed successfully. Web Services call. It means that all Web
Services features are functioning correctly.
300 A warning acknowledging the failure of at A single API call executes one or more
least one of the actions taken by an API actions. Each of the actions are independent of
call. one another. Therefore, even if one action
fails, the others can succeed. This warning
basically notifies the user to check for the one
or more failed actions.
500 A system error occurred. The operation This error is most likely an Adaptive
failed. Authentication error.
510 A process error occurred. The operation This error is usually data driven, and should be
failed. corrected by your application. It normally
points to correcting the Web Services Request
data.
CallStatus Structure
statusCode The status code of the call. String
statusDescription Explanatory text about the status code. String
StatusCode Values
Values Description
OK The call successfully was passed.
SYSTEM_ERROR There was a system error.
INVALID_USER_REQUEST Your application passed an invalid request.
StatusDescription Structure
description Explanatory text about the status. String

Out-of-Band Phone Reason Codes

The parameters, reasonCode and reasonDescription provide details on the status of
the Web Services call, in the following formats:
generic errors and warnings
configuration errors and warnings
user errors and warnings
The Adaptive Authentication Authentication Plug-In Service Provider sends reason
codes to the organization, as shown in the following table.
Reason Code Description
None A confirmation success.
Reason.BLOCKED_NUMBER The number was determined to be blocked by the

Authentication Plug-In system and will not be called.
Reason.CONFIG_ERROR Configuration error.
Reason.CONFIRMATION_NUM_FAILURE User failed to enter the correct confirmation number after

repeated attempts.
Reason.DATA_PROVIDER_ERROR Data returned by the data provider was invalid or not

properly formatted.
Reason.FAX_ANSWERED The call was placed, but a fax answered.
Reason.HANGUP Phone Disconnected by the user or due to a technical

glitch.
Reason.INVALID_AREA_CODE The area code included in the request message did not
match the area code within Authentication Plug-In's
database.
Reason.INVALID_AREA_EXCH_CODE The area code/exchange included in the request message

did not match the area code within Authentication Plug-
In's database.
Reason.INVALID_AUTH_PARAMS A parameter in the authentication request was missing or

invalid
Reason.INVALID_CLNT_CERT Client authentication failed due to an invalid certificate
Reason.INVALID_COUNTRY_CODE The country code included within the request message

did not match the country code within Authentication
Plug-In's database.
Reason.INVALID_NUMBER The telephone number provided was not valid, according

to the data provider's records.

Reason.INVALID_PASSWORD Invalid password in the configuration files.
Reason.INVALID_PHONE_NUMBER The telephone number falls outside the acceptable

number of digits for the country associated with the
dialed number.
Reason.INVALID_TEID XML Poll message contained a TEID, which did not

correspond to the assigned session TEID.
Reason.INVALID_TSOID Invalid TSOID.
Reason.INVALID_XML Problem with configuration values.
Reason.NETWORK_CONGESTION Reorder tone - "fast busy."
Reason.NETWORK_CONN_FAILURE Connection failure due to phone network problems.
Reason.NO_AFFIRMATION The call was picked up, a voice was detected but no
pound key was entered.
Reason.NO_DATA_PROV There is no data provider for the area code entered.
Reason.NO_SOUND_DETECTED The call was picked up, but no sound was detected even
after repeated prompts.
Reason.NO_VOICE_HEARD A voice recording was prompted repeatedly, but no voice

was heard.
The phone provider application provided for Adaptive
Authentication does not need recording. Support of this
variable requires provider application to add back voice
recording.
Reason.NOT_SPEAKING_CLEARLY User did not speak clear enough to be understood.
Reason.NUMBER_NOT_FOUND The telephone number was not found within data

provider's records.
Reason.OPERATOR_REQUEST User asked for an operator.
Reason.PHONE_BUSY Repeated attempts were made to call the number, but the
line was busy.
Reason.PHONE_MALFUNCTION The call was picked up, but a phone malfunction, usually
a faulty keypad or a stuck key, caused the session to time
out and be disconnected.
Reason.PHONE_NO_ANSWER The call was placed, but there was no answer.
Reason.PROV_SYSTEM_ERROR Authentication Plug-In System error.
Reason.PROV_SYSTEM_OVERLOAD Authentication Plug-In System overload.

Reason.REACHED_MAX_RETRIES The entry was either not understood, or did not match the
expected entry.
Reason.RECORDING_TOO_SHORT A voice recording was prompted repeatedly, but the

recording was shorter than the minimum specified length.
(Future support by phone provider.)
Reason.SPECIAL_INFO_TONE Three tones with message indicating error such as

network congestion or a disconnected number.
Reason.TOO_MANY_HELPS User pressed the help key (*) too many times for the same
prompt.
Reason.UNABLE_TO_DECRYPT Authentication Plug-In was unable to decrypt.
Reason.UNABLE_TO_REACH_DATA_PROV Authentication Plug-In was unable to connect to the data

provider.
Reason.UNASSIGNED_NUMBER The call was placed, but the PSTN returned an "invalid
number" error.
Reason.Unknown Unknown error.
Reason.VOICEPRINT_NOT_VERIFIED Visitor's voiceprint failed to match with the associated

VID. (Voice Biometrics). Future implementation.
Analyze Response Message

The Risk Engine recommends an action when a user performs an activity, such as a
logon or other transaction, that your organization assumes to be potentially risky. If
the Adaptive Authentication system considers the user activity potentially risky, it
may determine that extra credentials are required to help further authenticate the user.
The user is asked to provide either:
Answers to Challenge QuestionsUser-selected during enrollment
Out-of-Band authenticationThe user is called at a previously registered phone
number.
The extra credentials required are shown as requiredCredentialList in the Analyze
response as shown in Query Authentication Status Response Message on page 287.
For an example message, see Query Authentication Status Response Message on
page 288.
Analyze Response Message Sample (PART1)

<?xml version="1.0" encoding="utf-8"?>
<soapenv:Body>

<ns1:analyzeReturn xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="ns1:AnalyzeResponse">
<ns1:delegated>false</ns1:delegated>
<ns1:groupName>
</ns1:groupName>
<ns1:orgName>CompleteFlowOrg</ns1:orgName>
<ns1:sessionId>56ff18:114b954dc7d:-7fbc</ns1:sessionId>
<ns1:transactionId>TRX_56ff18:114b954dc7d:-7fbb</ns1:transactionId>
<ns1:userName>OOBPhoneUser0831010153640</ns1:userName>
<ns1:messageHeader>
<ns1:statusHeader>
<ns1:reasonDescription>Operations were completed successfully
Analyze Response Message Sample (PART2)

</ns1:statusHeader>
<ns1:requiredCredentialList>
<ns1:requiredCredential>
<ns1:credentialType>OOBPHONE</ns1:credentialType>
<ns1:groupName>DEFAULT</ns1:groupName>
<ns1:preference>0</ns1:preference>

<ns1:required>true</ns1:required>
</ns1:requiredCredential>
</ns1:requiredCredentialList>
<ns1:riskResult>
<ns1:triggeredRule>
<ns1:actionCode>CHALLENGE</ns1:actionCode>
<ns1:actionName>AuthDevNotBound</ns1:actionName>
<ns1:clientFactList />
<ns1:ruleId>AuthDevNotBound</ns1:ruleId>
<ns1:ruleName>AuthDevNotBound</ns1:ruleName>
</ns1:riskResult>
</soapenv:Body>
</soapenv:Envelope>
Your Application Challenge Request Message

If your application receives an action code value CHALLENGE from the
riskResult element in the Analyze response, it indicates that the user has performed
some risky event that requires authentication. Your application sends a challenge
request message to Adaptive Authentication that contains the phoneInfo element.
This data element is made up of values for the users phone number, including area
code, country code, label (work or cell), and other transaction details. For request data
structures, see Chapter 5, Web Services Request Data Structures and Types.
For an message example, see OOBPhoneChallengeRequest payload on page 285.
Note: The tokenCollectionFlow element should be always set to True. The phone
broadcast flow is not currently supported.
The following options are available for specifying the phone number:
1. Enter the entire phone number in the phoneNumber field, including the country
code, area code, and phone number.
2. Enter the phone number segments separately using the countryCode, areaCode,
and phoneNumber fields.

Challenge Structure
The following structure contain the specific information for when an OOB challenge
is sent to a user.
OOBPhoneChallengeRequest payload
This structure contains information regarding the users phone contact information.
This request payload uses OOBInfoResponse payload as its response.
noOp Determines if a phone call should be made. Y Boolean
phoneInfo The users phone contact information. Information N PhoneInfo

passed should only contain digits. No other characters
should be passed.
TokenCollectionFlow Determines if you are sending an OTP to the user. N Boolean

Default: False
Note: For more information on OOB Credential Data Structures, see Appendix C,
Out-of-Band Phone and Email Credential.
Challenge Request Message Sample

xmlns:ws="http://ws.csd.rsa.com">
<soapenv:Header/>
<soapenv:Body>
<ws:challenge>
<ws:request>
<ws:identificationData>
<ws:userName>TxnTestUserXX01a3ef</ws:userName>
<ws:userStatus>VERIFIED</ws:userStatus>
<ws:userType>PERSISTENT</ws:userType>
</ws:identificationData>
<ws:messageHeader>
<ws:apiType>DIRECT_SOAP_API</ws:apiType>
<ws:requestType>CHALLENGE</ws:requestType>
<ws:version>7.0</ws:version>
</ws:messageHeader>
<ws:securityHeader>
<ws:callerCredential>password</ws:callerCredential>
<ws:callerId>callerId</ws:callerId>
<ws:method>PASSWORD</ws:method>
</ws:securityHeader>
<ws:credentialChallengeRequestList>
<ws:oobPhoneChallengeRequest>
<ws:payload>
<ws:noOp>false</ws:noOp>
<ws:phoneInfo>
<ws:label>work</ws:label>

<ws:areaCode>650</ws:areaCode>
<ws:countryCode>1</ws:countryCode>
<ws:phoneNumber>1234567</ws:phoneNumber>
</ws:phoneInfo>
<ws:tokenCollectionFlow>true</ws:tokenCollectionFlow>
</ws:payload>
</ws:oobPhoneChallengeRequest>
</ws:credentialChallengeRequestList>
</ws:request>
</ws:challenge>
</soapenv:Body>
</soapenv:Envelope>
Adaptive Authentication Challenge Response Message

Adaptive Authentication sends a challengeResponse message to your application that
contains the session ID, transaction ID, and the token ID (OTP). Example messages
are shown in this section.
The authStatusCode element value is PENDING to indicate that the status of the
authentication is in-progress. The possible authStatus values are PENDING or NULL.
NULL signifies system error, indicating that the user has neither passed nor failed, but
the infrastructure has failed.
For authStatusCode PENDING in the challenge response, your application needs to
initiate a queryAuthStatus request message.
An authStatusCode NULL in the challenge response indicates that there was a system
error.
Challenge Response Message Sample (Part 1)

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/ envelope/">
<soapenv:Body>
<ns1:challengeResponse xmlns:ns1="http://ws.csd.rsa.com">
<ns1:challengeReturn xsi:type="ns1:ChallengeResponse" xmlns:xsi="http://
www.w3.org/2001/XMLSchema-instance">
<ns1:groupName/>
<ns1:sessionId>1ab4292:1148edfd5a9:-8000</ns1:sessionId>
<ns1:transactionId>TRX_1ab4292:1148edfd5a9:-7fff</
ns1:transactionId>
<ns1:userName>TxnTestUserXX01a3ef</ns1:userName>
<ns1:messageHeader>
<ns1:requestType>CHALLENGE</ns1:requestType>
<ns1:statusHeader>

<ns1:reasonDescription>Operations were completed successfully</

ns1:reasonDescription>
</ns1:statusHeader>
Challenge Response Message Sample (Part 2)

<ns1:credentialChallengeList>
<ns1:oobPhoneChallenge>
<ns1:payload>
<ns1:authenticationResult> <ns1:authStatusCode>PENDING</
ns1:authStatusCode>
<ns1:callStatus>
</ns1:callStatus> <ns1:channelStatus>Status.CREATED</
ns1:channelStatus>
<ns1:reason>NONE</ns1:reason>
<ns1:token>740608</ns1:token>
</ns1:payload>
</ns1:oobPhoneChallenge>
</ns1:credentialChallengeList>
</ns1:challengeReturn>
</ns1:challengeResponse>
</soapenv:Body>
</soapenv:Envelope>
Query Authentication Status Request Message

Your application sends a queryAuthStatus request message to Adaptive
Authentication to get the OOB authentication status. The message contains the session
ID, transaction ID, and optionally the token ID (OTP). An example message is
displayed below.
Query Authentication Status Request Sample

xmlns:ws="http://ws.csd.rsa.com">
<soapenv:Header/>
<soapenv:Body>
<ws:queryAuthStatus>
<ws:request>
<ws:identificationData>
<ws:sessionId>a7b7ff:114ab24a736:-8000</ws:sessionId>
<ws:transactionId>TRX_a7b7ff:114ab24a736:-7fff</ws:transactionId>
<ws:userName>TxnTestUserXX01a3ef</ws:userName>
<ws:userStatus>VERIFIED</ws:userStatus>
<ws:userType>PERSISTENT</ws:userType>
</ws:identificationData>
<ws:messageHeader>
<ws:apiType>DIRECT_SOAP_API</ws:apiType>
<ws:requestType>QUERYAUTHSTATUS</ws:requestType>
<ws:version>7.0</ws:version>

</ws:messageHeader>
<ws:securityHeader>
<ws:callerCredential>password</ws:callerCredential>
<ws:callerId>callerId</ws:callerId>
<ws:method>PASSWORD</ws:method>
</ws:securityHeader>
<ws:credentialAuthStatusRequest>
<ws:oobPhoneAuthStatusRequest>
<ws:payload>
<ws:token>740608</ws:token>
</ws:payload>
</ws:oobPhoneAuthStatusRequest>
</ws:credentialAuthStatusRequest>
</ws:request>
</ws:queryAuthStatus>
</soapenv:Body>
</soapenv:Envelope>
Query Authentication Status Response Message

Adaptive Authentication sends a queryAuthStatus response message to your
application that returns the users authentication status.
The queryAuthStatus response message contains an authStatus code (SUCCESS,
FAIL, PENDING or NULL). Your application decides whether or not to continue
sending queryAuthStatus request messages based on the authstatus code. A
PENDING will require continuing queryAuthStatus requests. A NULL code signifies
System or Provider Error since infrastructure failed.
The channel status codes shown in the response will be as follows:
CHALLENGE_SUCCESS
CHALLENGE_FAILED
UNREACHABLE
SYSTEM_ERROR
CREATEDNotification is in progress, and request has been sent to the phone
Provider.
EXPIREDThis channel status code, EXPIRED, will occur when notification
cannot be retrieved possibly due to customer error or notification expired (10
minutes time out). The following is an example of messages
Query Authentication Status Response Sample (Part 1)

<soapenv:Envelope xmlns:soapenv=
"http://schemas.xmlsoap.org/ soapenvelope/">
<soapenv:Body>
<ns1:queryAuthStatusResponse xmlns:ns1="http://ws.csd.rsa.com">
<ns1:queryAuthStatusReturn xsi:type="ns1:
QueryAuthStatusResponse":xsi=
"http://www.w3.org/2001/XMLSchema-instance">

<ns1:groupName/>
<ns1:sessionId>a7b7ff:114ab24a736:-8000</ns1:sessionId>
<ns1:transactionId>TRX_a7b7ff:114ab24a736:-7fff</ns1:transactionId>
<ns1:userName>TxnTestUserXX01a3ef</ns1:userName>
<ns1:messageHeader>
<ns1:requestType>QUERYAUTHSTATUS</ns1:requestType>
<ns1:statusHeader>
<ns1:reasonDescription>Operations were completed successfully
</ns1:statusHeader>
Query Authentication Status Response Sample (Part 2)
<ns1:credentialAuthStatusResponse>
<ns1:oobPhoneAuthStatusResponse>
<ns1:payload>
<ns1:authenticationResult>
<ns1:callStatus>
</ns1:callStatus>
<ns1:channelStatus>Status.CHALLENGE_FAILED
</ns1:channelStatus>
<ns1:reason>Reason.HANGUP</ns1:reason>
</ns1:payload>
</ns1:oobPhoneAuthStatusResponse>
</ns1:credentialAuthStatusResponse>
</ns1:queryAuthStatusReturn>
</ns1:queryAuthStatusResponse>
</soapenv:Body>
</soapenv:Envelope>
Phone Token Collection Through Online Session

In this scenario, the token is sent to the users browser running the organization
application. The token is then collected via the users phone.
Here is an example scenario of the phone token collection:

1. The user performs an event that requires authentication, such as sending an online
payment.
2. Adaptive Authentication sends a challenge action to your application requesting
that they challenge the user.
3. Your application prompts the user to choose the phone number that they want to
use for the OOB challenge phone call in this session from a list of phone numbers
displayed in the browser.
4. Your application collects the users phone number from the online session, and
sends a challenge request message with the phone number to Adaptive
Authentication. For the complete message example, see
OOBPhoneChallengeRequest payload on page 285.
<ws:oobPhoneChallengeRequest>
<ws:payload>
<ws:noOp>false</ws:noOp>
<ws:phoneInfo>
<ws:label>work</ws:label>
<ws:areaCode>650</ws:areaCode>
<ws:countryCode>1</ws:countryCode>
<ws:phoneNumber>1234567</ws:phoneNumber>
</ws:phoneInfo>
<ws:tokenCollectionFlow>true</ws:tokenCollectionFlow>
</ws:payload>
</ws:oobPhoneChallengeRequest>
5. Adaptive Authentication sends a challenge response message to your application
containing the Session ID, Transaction ID, and Token ID. For the complete
message example, see Adaptive Authentication Challenge Response Message
on page 286.

<ns1:sessionId>1ab4292:1148edfd5a9:-8000</ns1:sessionId>
<ns1:transactionId>TRX_1ab4292:1148edfd5a9:-7fff</
ns1:transactionId>
---------------------------------------------------------------
<ns1:callStatus>
</ns1:callStatus>
<ns1:channelStatus>Status.CREATED</ns1:channelStatus>
<ns1:reason>NONE</ns1:reason>
6. Adaptive Authentication passes the users phone number and token (OTP) to the
Authentication Plug-In.
7. The Authentication Plug-In server calls the user and requests the user to enter the
token into the telephone keypad.
8. Your application sends queryAuthStatus request message containing the Session
ID, Transaction ID, and optionally, Token ID, to Adaptive Authentication to poll
the status of the authentication.
9. Adaptive Authentication sends a response message to your application. If the
authentication status is PENDING, then your organization continues to send
queryAuthStatus requests.

10. Based on the status codes returned by the Authentication Plug-In, Adaptive
Authentication shows SUCCESS, FAIL, PENDING, or NULL.
The status code NULL means a system error or provider error has occurred. It
does not specify whether the user passed or failed, since the infrastructure failed.

C Out-of-Band Phone and Email Credential

Out-of-Band Phone and Email Credential Methods
OOB Credential Data Structures
This chapter describes the Out-Of-Band phone and email credential. For this
credential, a One-Time-Password (OTP) is sent to the user through their web page,
and the user enters the OTP into the subsequent phone call that is sent.
Out-of-Band Phone and Email Credential Methods

The following section describes the methods and data structures defined for out-of-
band phone and email authentication.
Adaptive
Request/
Authentication Data Structure Extends the Structure
Response
Method
authenticate Request OOBInfoRequestPayload CredentialData
Response OOBInfoResponsePayload CredentialResult
analyze Request OOBInfoRequestPayload CredentialData
Response OOBInfoResponsePayload CredentialResult
challenge Request OOBEmailChallengeRequest CredentialChallengeRequest

OOBPhoneChallengeRequest
Response OOBInfoResponse CredentialChallenge
createUser Request EmailManagementRequest CredentialManagementRequest

PhoneManagementRequest
Response EmailManagementResponse CredentialManagementResponse

PhoneManagementResponse
notify Request Not supported in this credential

method
Response Not supported in this credential

method
queryAuthStatus Request OOBInfoRequestPayload CredentialAuthStatusRequest
Response OOBInfoResponsePayload CredentialAuthStatusResponse
C: Out-of-Band Phone and Email Credential 293

Adaptive
Request/
Response
Method
query Request EmailManagementRequest CredentialManagementRequest


updateUser Request EmailManagementRequest CredentialManagementRequest


OOB Credential Data Structures

The following section lists the various data structures for this credential type. This
section is divided according to the usage of these structures.
Type of Structure Usage
Activity Structures Informs the Adaptive Authentication Web Services what actions to take
with the request message that you send to it. It includes:
ActionType Structure
OOBActionType Values
For more information, see Activity Structures on page 295.
User Information Structures Provide the users actual OOB contact information, such as a list of email
addresses or phone numbers. It includes:
OOBContactInfoObject structure
PhoneInfo Structure
For more information, see User Information Structures on page 297.
Challenge Structures Provides the specific information for when a user is challenge. For
example, the specific phone number to call the user for a challenge. It
includes:
For more information, see Challenge Structures on page 298.
294 C: Out-of-Band Phone and Email Credential

Authentication Structures Provides the results of the actual OOB authentication. Did the user
successfully pass the OOB challenge? What is the state of the OOB Web
Services call?
It includes:
OOBInfoRequest payload structure
OOBInfoResponse payload structure
For more information, see Authentication Structures on page 299.
OOB Management Structures Allows you to manage a users OOB information, such as updating,
deleting, or adding contact information.
It includes:
OOBManagementRequest payload
OOBManagementResponse payload
For more information, see OOB Management Structures on page 296.
Activity Structures
These activity structures inform the RSA Adaptive Authentication (On Premise) Web
Services the necessary actions to take with the information being sent.
ActionType Structure
This structure extends the ActionTypeList, as described in ActionTypeList on
page 107.
oobActionType The specific OOB action that the system should OOBActionType[ ]
take.
OOBActionType Values
The following values determine what action should be taken with the OOB Credential
Type.
Action Description
ADD_OOB Add new OOB contact information.
GET_OOB Get the users OOB contact information.
DELETE_OOB Delete the listed OOB contact information.
UPDATE_OOB Update the listed OOB contact information.

OOB Management Structures

The OOBManagement structures allow you to query, update, and add user contact
information to the users phone contact information.
OOBManagementRequest payload
This structure extends the structure PhoneManagementRequest payload.
Data Element Description Data Type Required
oobActionTypeList The specific OOB action that the system OOBActionTypeList Y

should take.
PhoneManagementRequest payload
contactList The list of the users contact information. If the PhoneInfo[ ] N

action type is ADD_OOB or UPDATE_OOB,
this data element is mandatory.
OOBManagementResponse payload
This structure provides the parent class to the structure PhoneManagementResponse
payload.
PhoneManagementResponse payload
contactList The list of the users contact information. PhoneInfo[ ]

User Information Structures

The following structures detail the specific user OOB information.
OOBContactInfoObject structure
This object provides the parent class of the structure PhoneInfo.
Max Data
Data Element Description Required
Length Type
defaultFlag This flag indicates if the contact information is the NA Boolean N

default.
The first OOB contact information that is entered
is automatically marked as default.
To mark a new contact as the default, this flag must
be set. Otherwise, the first contact remains the
default.
label The predefined label for the contact information, 50 String Y

such as Home or Work. This parameter must be
unique for each contact.
lastModified The date that the users contact information was NA String N
last modified.
reference (Currently not supported in 6.0) NA String N

The reference number for the contact information.
This data element is returned by the Adaptive

PhoneInfo Structure
This structure extends OOBContactInfo object.
Max
Length
areaCode The users area code. 5 String N

Information passed should only contain
digits. Do not pass other character types.
countryCode The country code of the users phone 3 String N

number.
extension The users extension behind a PBX. 5 String N

phoneNumber The phone number to be called. 20 String Y

If the country code and area code are
provided with the phone number, the
phone number can be entered as a
concatenation of these three fields.
By entering the fields separately, you can
provide the application with additional
information for potential risk analysis.
Challenge Structures
The following structures contain the specific information for when an OOB challenge
is sent to a user.
This structure contains information regarding the users phone contact information.
This request payload uses OOBInfoResponse payload as its response.
noOp Determines if a phone call should be made. Boolean Y
phoneInfo The users phone contact information. Information PhoneInfo N

passed should only contain digits. Do not pass
other character types.
TokenCollectionFlow Determines if you are sending an OTP to the user. Boolean N

Default: False

Authentication Structures
The following structures request information regarding the actual authentication of a
users OOB challenge.
OOBInfoRequest payload structure

This structure was designed to act as the request structure for out-of-band
authentication for the following methods: authenticate and analyze. If this data
element is submitted for queryAuthStatus, it ignores it.
Max Data
Length Type
token The One-Time Password sent to the customer. NA String Y
OOBInfoResponse payload structure

This structure is used to respond to the following methods: challenge, authenticate,
and query.
This structure was designed to act as the response structure for
OOBPhoneChallengeRequest payload.
authenticationResult The status of the authentication. Authentication N

Result
callStatus The status of the Web Services call. CallStatus Y
channelStatus The status of the OOB channel. See String Y

channelStatus valueson page 299.
reason The reason for any channel status errors. See String Y
reason values on page 300.
token Used for asynchronous verification credentials String N

only. Currently Not Supported as of Release
6.0.
channelStatus values
Values Description
CREATED The OOB channel has been created, and notification is in progress.

Values Description
PINGED The OOB mechanism has acknowledged that it is active.
VERIFIED The OOB mechanism has verified that the transaction is correct.
TRANSMITTED The OOB mechanism has verified that the transaction has been transmitted to the
user.
CHALLENGE_SUCCESS The user has correctly replied to the OOB notification.
CHALLENGE_FAILED The user has incorrectly replied to the OOB notification.
DENIED The OOB mechanism has rejected the transaction.
UNREACHABLE The user was unreachable. Read the reasonCode (reason values on page 300.)
for a more detailed description of why the user was unreachable.
NOT_SUPPORTED The method is not supported for this transaction.
SYSTEM_ERROR A system failure has occurred during the notification progress.
UNSENT The OOB notification has not yet been sent.
CANCELLED The OOB notification has been removed from the queue.
EXPIRED The OOB notification has exceeded its time limit for a users response (default =
10 minutes).
reason values
The following values provide more information as to why the customer was
unreachable.
Values Description
UNKNOWN An unknown error occurred.
OPERATOR_REQUEST The customer demanded to speak to an operator.
HANGUP The customer hung up.
NOT_SPEAKING_CLEARLY The customer did not speak clearly enough for the telephony service
provider to understand.
CONFIG_ERROR A configuration error occurred.
TIMEOUT The specified timeout period elapsed.
PROVIDER_ERROR An error occurred in the telephony providers service.
PHONE_BUSY The customers phone number was busy.

Values Description
PHONE_NO_ANSWER The customer did not answer their phone.
NO_AVAILABLE_PORTS No ports were available to make the call.
CONFIGURATION_PROBLE (Email only) A configuration problem occurred.

M

D One-Time Password Credential

One Time Password Credential Methods
One-Time Password Credential Data Structures
This chapter describes the one-time password (OTP) authentication credential.
One Time Password Credential Methods

The following section describes the methods and data structures defined for one-time
password authentication.
Adaptive
Request/
Response
Method
authenticate Request OTPAuthenticationRequest AcspAuthenticationRequest
Response OTPAuthenticationResponse AcspAuthenticationResponse
analyze Request OTPAuthenticationRequest AcspAuthenticationRequest
Response OTPAuthenticationResponse AcspAuthenticationResponse
challenge Request OTPChallengeRequest AcspChallengeRequest
Response OTPChallengeResponse AcspChallengeResponse
createUser Request OTPManagementRequest AcspManagementRequest
Response OTPManagementResponse AcspManagementResponse
queryAuthStatus Request OTPAuthStatusRequest AcspAuthStatusRequest
Response OTPAuthStatusResponse AcspAuthStatusResponse
query Request OTPManagementRequest AcspManagementRequest
updateUser Request OTPManagementRequest AcspManagementRequest
D: One-Time Password Credential 303

One-Time Password Credential Data Structures

The following section lists the various data structures for this credential type. For ease
of reading, this section is divided according to the usage of these structures.
OTP Management Structures Allows you to manage a users OTP information, such as updating,
deleting, or adding contact information.
It includes:
OTPManagementRequestPayload
OTPManagementResponsePayload
For more information, see OTP Management Structures on page 305.
Challenge Structures Provides the specific information for when a user is challenged. It includes:
OTPChallengeRequestPayload
OTPChallengeResponsePayload
Authentication Structures Provides the results of the actual OTP authentication. Did the user
successfully pass the OTP challenge? What is the state of the OTP
Adaptive Authentication call?
It includes:
OTPAuthenticationRequestPayload
OTPAuthenticationResponsePayload
Query Structures Allows you to retrieve information according to specific selection criteria.
It includes:
OTPAuthStatusRequestPayload
OTPAuthStatusResponsePayload
For more information, see Query Structures on page 310.
304 D: One-Time Password Credential

OTP Management Structures

The OTP management structures allow you to query, update, and add user contact
Management Request
Data Structure Description
CredentialManagementRequestList Contains the following elements:

challengeQuestionManagementRequest
oobPhoneManagementRequest
oobEmailManagementRequest
acspManagementRequestData
For more information, see
credentialManagementRequestList on
page 122.
AcspManagementRequestData Contains the following elements:

acspManagementRequest: An abstract
payload from which the actual pluggable
management request payload is derived
credentialProvisioningStatus. For more
information, see Appendix H,
Authentication Plug-In Credential.

OTPManagementRequestPayload
The otpManagementRequest is derived from acspManagementRequest. It is an actual

management payload for OTP and contains the following field.
opcode Defines a specific action for a payload to N String

determine from which specific flow it is
derived.
Management Response
CredentialManagementResponseList Contains the following elements:

challengeQuestionManagementResponse
oobPhoneManagementResponse
oobEmailManagementResponse
acspManagementResponseData
credentialManagementResponseList on
page 165.
AcspManagementResponseData Contains the following elements:

acspManagementResponse:An abstract
management response payload is derived
callStatus
acspAccountId
For more information, see Appendix H,
OTPManagementResponsePayload
The otpManagementResponse is derived from acspManagementResponse. It is an
actual management payload for OTP and does not contain any data elements.

Challenge Request
The following structures contain the specific information for when an OTP challenge
is sent to a user.
CredentialChallengeRequestList Contains the following elements:

challengeQuestionChallengeRequest
oobPhoneChallengeRequest
oobEmailChallengeRequest
acspChallengeRequestData
credentialChallengeRequest on page 119.
AcspChallengeRequestData Contains the following elements:

acspChallengeRequest: An abstract payload
from which the actual pluggable challenge
request payload is derived.
OTPChallengeRequestPayload
otpChallengeRequest derives from acspChallengeRequest. It is an actual challenge
payload for OTP. It does not contain any elements. It exists to allow the system to
recognize whether there is an OTP challenge flow.
Challenge Response.
CredentialChallengeResponseList Contains the following elements:

challengeQuestionChallengeResponse
oobPhoneChallengeResponse
oobEmailChallengeResponse
acspChallengeResponseData
credentialChallengeList on page 164.
AcspChallengeResponseData Contains the following elements:

acspChallengeResponse:An abstract
challenge response payload is derived.
callStatus
acspAccountId

OTPChallengeResponsePayload
otpChallengeResponse derives from acspChallengeResponse. It is an actual challenge
payload for OTP and contains the following field.
otp Contains a one time password (token) String

generated by the system
Authentication Request
users OTP challenge.
CredentialDataList Contains the following elements:

challengeQuestionData
oobPhoneData
oobEmailData
AcspAuthenticationRequestData
credentialDataList on page 121.
AcspAuthenticationRequestData Contains the following elements:

AcspAuthenticationRequest: An abstract
authentication request payload is derived.
OTPAuthenticationRequestPayload
The otpAuthenticationRequest is derived from acspAuthenticationRequest. It is an
actual authentication payload for OTP and contains the following field.
Data
Type
otp Contains a one time password (token) Y String

provided by the user for authentication
purposes

Authentication Response.
CredentialAuthResultList Contains the following elements:

challengeQuestionAuthResult
oobPhoneChallengeAuthResult
oobEmailChallengeAuthResult
acspAuthenticationResponseData
credentialAuthResult on page 162.
acspAuthenticationResponseData Contains the following elements:

acspAuthenticationResponse:An abstract
authentication response payload is derived.
callStatus
acspAccountId
OTPAuthenticationResponsePayload
The otpAuthenticationResponse is derived from acspAuthenticationResponse. It is an
actual authentication payload for OTP and does not contain any elements.

Query Structures
QueryAuthStatus Request
CredentialAuthStatusRequest Contains the following elements:

ChallengeQuestionAuthStatusRequest
oobPhoneAuthStatusRequest
oobEmailAuthStatusRequest
acspAuthStatusRequestData
credentialAuthStatusRequest on page 118.
AcspAuthStatusRequestData Contains the following elements:

AcspAuthStatusRequest: An abstract
payload from which the actual
queryAuthStatus request payload is derived
OTPAuthStatusRequestPayload
The otpAuthStatusRequest is derived from acspAuthStatusRequest. It is an actual
queryAuthStatus payload for OTP. It does not contain any fields. It exists to allow the
system to recognize whether there is an OTP queryAuthStatus flow.
QueryAuthStatus Response.
CredentialAuthStatusResponse Contains the following elements:

challengeQuestionAuthStatusResponse
oobPhoneAuthStatusResponse
oobEmailAuthStatusResponse
acspAuthStatusResponseData
credentialAuthStatusResponse on
page 163.
AcspAuthStatusResponseData Contains the following elements:

acspAuthenticationResponse:An abstract
queryAuthStatus response payload is
derived.
callStatus
acspAccountId

OTPAuthStatusResponsePayload
otpAuthStatusResponse derives from acspAuthStatusResponse. It is an actual
queryAuthStatus payload for OTP and does not contain any elements.

E Knowledge-based Authentication Credential

Knowledge-based Authentication Credential Methods
Knowledge-based Authentication Credential Data Structures
This chapter describes the knowledge-based authentication (KBA) authentication
credential.
Knowledge-based Authentication Credential Methods

The following section describes the methods and data structures defined for
knowledge-based authentication.
Adaptive
Request/
Response
Method
authenticate Request KBAAuthenticationRequest AcspAuthenticationRequest
Response KBAAuthenticationResponse AcspAuthenticationResponse
challenge Request KBAChallengeRequest AcspChallengeRequest
Response KBAChallengeResponse AcspChallengeResponse
createUser Request KBAManagementRequest AcspManagementRequest
Response KBAManagementResponse AcspManagementResponse
query Request KBAManagementRequest AcspManagementRequest
updateUser Request KBAManagementRequest AcspManagementRequest
E: Knowledge-based Authentication Credential 313

Knowledge-based Authentication Credential Data Structures

The following section lists the various data structures for the knowledge-based
authentication (KBA) credential type. This section is divided according to the usage of
these structures.
Management Structures Allows you to manage a users KBA enrollment data, including adding,
updating, or deleting the data.
It includes:
KBAManagementRequest Payload
KBAManagementResponse Payload
For more information, see Management Structures on page 315.
Challenge Structures Provides the specific information for when a user is challenged.
It includes:
KBAChallengeRequest Payload
KBAChallengeResponse Payload
Authentication Structures Provides the results of the actual KBA authentication. Did the user
successfully pass the challenge? What is the state of the Web Services call?
It includes:
KBAAuthenticationRequest Payload
KBAAuthenticationResponse Payload
314 E: Knowledge-based Authentication Credential

Management Structures
The KBA management structures allow you to query, update, and add user contact
Management Request
KBAManagementRequest Contains the following elements:

action
personInfo
AcspManagementRequestData Contains the following elements:

acspManagementRequest: An abstract
management request payload is derived.
credentialProvisioningStatus. For more
information, see Appendix H,
KBAManagementRequest Payload
KBAManagementRequest derives from acspManagementRequest. It is an actual

management payload for KBA and contains the following field.
action Defines the action to perform.See action Y String

Values. on page 315.
personInfo The users personal information. See N String

personInfo Values on page 316.
action Values
The following table lists the kind of actions you can perform in the
KBAManagementRequest.
Action Description
ADD Add a users enrollment information.
UPDATE Update a users enrollment information.
DELETE Delete a users enrollment information.

Note: This does not unenroll the user from the system.
GET Request the users enrollment information.

personInfo Values
The following table lists the contact information for the user.
Data Element Description
region From where is the user. Possible values are:

GB
US
ssnInfo Defines the Social Security information for the user. See
ssnInfo Values on page 316.
nameInfo The users name. See NameInfo Values on page 316.
addressInfo The users address. See addressInfo Values on page 317.
birthdayInfo The users date of birth. See birthdayInfo Values on page

317.
ssnInfo Values
The following table lists the fields available when entering the users Social Security
information, and their descriptions.
ssn The users Social Security number.
ssnType Defines the format of the Social Security information

required. Valid values are:
SSN4 - The last 4 digits in the users Social Security
number.
SSN9 - The entire 9 digits from the users Social Security
number.
SSN5 - The last 5 digits in the users Social Security
number.
OTHER - A different set of required digits.
NOSSN - No Social Security number is required.
NameInfo Values
The following table lists the fields available when entering the users name, and their
descriptions.
firstName The users first name.
lastName The users last name.

addressInfo Values
The following table lists the fields available when entering the users address, and
their descriptions.
street The street on which the user lives.
town The town in which the user lives.
state The State in which the user lives.
postCode The 5-digit code for the neighborhood in which the user lives.
birthdayInfo Values
The following table lists the fields available when entering the users date of birth, and
their descriptions.
day The day on which the user was born.
month The month in which the user was born.
year The year in which the user was born.

Management Response
KBAManagementResponse Contains the following elements:

personInfo. See personInfo Values on
page 316.
AcspManagementResponse Contains the following elements:

acspManagementResponse:An abstract
management response payload is derived.
callStatus
acspAccountId
KBAManagementResponse Payload
KBAManagementResponse derives from acspManagementResponse. It is an actual
management payload for KBA and does not contain any data elements.
Data Element Description DataType
personInfo The users personal information. String
Challenge Request
The following structures contain the specific information for when a KBA challenge is
sent to a user.
KBAChallengeRequest Contains the following element:

personInfo

KBAChallengeRequest Payload
The KBAChallengeRequest is derived from acspChallengeRequest. It is an actual
challenge payload for KBA. It contains the following element.
personInfo The users personal information. N String
Note: The field is required if the data is not

provided when enrolling to KBA. This
information is not stored in the database
when you provide it as part of a challenge
request.
Challenge Response.
KBAChallengeResponse Contains the following element:

questions
KBAChallengeResponse Payload
KBAChallengeResponse derives from acspChallengeResponse. It is an actual
challenge payload for KBA and contains the following field.
questions The questions that the user must answer to String

authenticate.
question Values
The following table lists the information required for the question element.
questionID The question sets identification number.
text The text of the question.
choices The possible answers from which the user can choose.

choice Values
The following table lists the fields for the choice element.
choiceIDs The numbers identifying the selections.
text The text for the selected choice.
Authentication Request
users KBA challenge.
KBAAuthenticationRequest Contains the following elements:

answers
KBAAuthenticationRequest Payload
KBAAuthenticationRequest derives from acspAuthenticationRequest. It is an actual
authentication payload for KBA and contains the following field.
answers Contains the answers the user must provide Y String

to authenticate.
answer Values
The following table lists the information required for the question element.
questionID The question sets identification number.
choiceIDs The identification for the answers selected by the user.
Authentication Response.
KBAAuthenticationResponse Contains the following elements:

resultStatus
questions

KBAAuthenticationResponse Payload
kbaAuthenticationResponse derives from acspAuthenticationResponse. It is an actual
authentication payload for KBA and contains the following elements:
resultStatus Indicates if the authentication failed, Y String

succeeded, or is pending.
Note: When the resultStatus is pending, you

should send another set of questions for
authentication.
questions Additional questions in the event that N String

further verification for authentication is
required.

F Out-of-Band SMS Authentication Credential

Out-of-Band SMS Authentication Credential Methods
OOB SMS Authentication Credential Data Structures
This chapter describes the Out-of-Band (OOB) SMS authentication credential.
Out-of-Band SMS Authentication Credential Methods

The following section describes the methods and data structures defined for
OOB SMS authentication.
Adaptive
Request/
Response
Method
authenticate Request OOBGenAuthenticationRequest AcspAuthenticationRequest
Response OOBGenAuthenticationResponse AcspAuthenticationResponse
challenge Request OOBSMSChallengeRequest AcspChallengeRequest
Response OOBSMSChallengeResponse AcspChallengeResponse
OOB SMS Authentication Credential Data Structures

The following section lists the various data structures for this credential type. For ease
of reading, this section is divided according to the usage of these structures.
Management Structures Allows you to manage a users contact data for use in OOB SMS
authentication. You can add, delete, update, and get the contact data..
It includes:
OOBManagementRequestPayload
For more information, see Management Structures on page 324.
F: Out-of-Band SMS Authentication Credential 323

Management Structures
The OOB SMS management structures allow you to query, update, and add user
contact information to the users phone information.
Management Request
OOBManagementRequest Contains the following element:

action
OOBManagementRequestPayload
OOBManagementRequest derives from acspManagementRequest. It is an actual

management payload for OOB and contains the following field.
action Defines the action to perform.See action Y String

contactList Contains the information for each item N contactList

from OOBPhoneInfo. See OOBPhoneInfo
action Values
The following table lists the kind of actions you can perform in the
OOBManagementRequest.
Action Description
ADD Add a number to a contact list.
UPDATE Update a number in a contact list..
DELETE Remove a number from the contact list.
GET Request the numbers in a contact list.
324 F: Out-of-Band SMS Authentication Credential

OOBPhoneInfo Values
The following table lists the information available in for each phone number in a
contact list.
Action Description
isDefault Is this number the default number
phoneNumber The number to add.
countryCode The prefix to dial when accessing the number internationally.
areaCode The area code to dial when calling.
extension The extension to dial when prompted.
label The name for the phone entry.
F: Out-of-Band SMS Authentication Credential 325

G Challenge Question Credential

This chapter outlines the various methods, data structures, and data elements for the
Challenge-Response Credential, Challenge Questions.
Challenge Question Credential Methods

The following section describes the methods and structures used by this credential.
Adaptive
Request/ Implements the
Authentication Data Structure
Response Structure
Method
analyze Request Not supported in this credential
authenticate Request ChallengeQuestionDataPayload
Response ChallengeQuestionAuthResultPayload
challenge Request ChallengeQuestionChallengeRequestPayload CredentialChallengeReq

uestPayload
Response ChallengeQuestionChallengePayload CredentialChallengePayl

oad
createUser Request ChallengeQuestionManagementRequestPayload CredentialManagementR

equestPayload
Response ChallengeQuestionManagementResponsePayload CredentialManagementR

esponsePayload
queryAuthStatus Request Not Supported by this credential
Response Not Supported by this credential
query Request ChallengeQuestionManagementRequestPayload CredentialManagementR

equestPayload

esponsePayload
G: Challenge Question Credential 327

Adaptive
Request/ Implements the
Authentication Data Structure
Response Structure
Method
updateUser Request ChallengeQuestionManagementRequestPayload CredentialManagementR

equestPayload

esponsePayload
Challenge Question Credential Data Structures

The following section lists out the various data structures for this credential type. For
ease of reading, this section is divided according to usage of these structures.
Activity Structures Informs the AdaptiveAuth Web Services what actions to take with the
request message that you send to it. It includes:
ChallengeQuestionActionTypeList structure
ChallengeQuestionActionType structure
For more information, see Activity Structures on page 329.
Actual Question Information Provide the users question information.

Structures It includes:
ChallengeQuestionList structure
ChallengeQuestionIdList structure
ChallengeQuestionConfig structure
ChallengeQuestion Structure
ChallengeQuestionGroupList structure
ChallengeQuestionGroup structures
For more information, see Actual Question Information Structures on
page 330.
Authentication Structures Provides the results of the comparison of the users answer and the answer
from the database.
It includes:
ChallengeQuestionMatchResult payload
ChallengeQuestionAuthResults payload
328 G: Challenge Question Credential

Challenge Structures Allows you to retrieve challenge questions to present to the user.
ChallengeQuestionChallengeRequest payload
ChallengeQuestionChallenge payload
Question Management Allows you to manage a users challenge information, such as updating,
Structures deleting, or adding questions/answers.
It includes:
ChallengeQuestionData payload
ChallengeQuestionManagementRequest payload
ChallengeQuestionManagementResponse payload
For more information, see Question Management Structures on
page 334.
Activity Structures
ChallengeQuestionActionTypeList structure
This structure defines the specific action to be taken with the challenge questions
The structure may contain no more than one value. Multiple actions are not supported
within the same payload.
actionTypeList Parent class of structure The generic action being taken by the ActionTypeList[ ]
system. See ActionTypeList on page .107
challengeQuestionAc The specific action to be taken for the users challenge questions. ChallengeQuesti
tionType See ChallengeQuestionActionTypeList structure below for a list onActionType
of those values.

ChallengeQuestionActionType structure
The following values are types of management actions. The purpose of these actions is
to maintain each Challenge Question credential:
Action Description
ADD_USER_QUESTION Adds a new question, selected by the user, to the users profile.
BROWSE_QUESTION Allows the user to browse through all the existing questions.
GET_USER_QUESTION Retrieves the users chosen questions.
SET_USER_QUESTION Replaces the existing users questions and answers with newly revised
questions and answers selected by the user.
Actual Question Information Structures

The following structures provide information about the actual challenge questions,
such as the ID numbers, configurations, and the text for the challenge questions.
ChallengeQuestionList structure
challengeQuestions A list of the challenge questions. ChallengeQuestion[ ]
ChallengeQuestionIdList structure
questionId The identification numbers for a list of challenge questions. Each String[ ]
question has a specific identification number associated with it.
If your institution stores the users answers and provides a value in
actualAnswerOnFile, you need to set this value to Q0.0.
ChallengeQuestionConfig structure
This structure defines the configuration data for the challenge questions.
excludeQuestionList Exclude a specific question group from the pool of ChallengeQuestionIdList[ ]

questions to be returned.

excludeUserQuestions Exclude from returning a question that a user has Boolean

already answered.
groupCount The number of question groups. Each question Integer

belongs to a specific group of questions.
includeRetired Determines whether or not to include retired Boolean

questions returned.
questionCount The number of questions within each group. Integer
ChallengeQuestion Structure
This structure defines the specific details about the users chosen challenge questions
and the answers they have provided.
actualAnswerOnFile The users answer that is stored by your organization. String

This value should be passed only if your application is using the
Adaptive Authentication to authenticate a users answer, but does
not store the users answer within the Core Database.
actualAnswer The users answer to their chosen challenge questions, which is String
stored in the Core Database.
questionID The identification number of the question that the user has chosen. String
If your organization stores the users answers and provides a value
in actualAnswerOnFile, you need to set this value to Q0.0.
questionText The specific text of the question. String
userAnswer The users answer to the challenge question. String
ChallengeQuestionGroupList structure
questionGroup A specific group of challenge questions. Each challenge ChallengeQuestionGroup

question belongs to a given group.

ChallengeQuestionGroup structures
Each challenge question belongs to a group. This structure details the group
information for a challenge question.
challengeQuestion The challenge question. ChallengeQuestion
groupName The name of the group to which the question belongs. String
retired Determines if the question group is retired. Boolean
The following structures deal with the authentication results of the challenge
questions.
ChallengeQuestionMatchResult payload
This structure returns the results of the challenge question authentication.
failCount The number of times that the user tried and failed authentication. Integer
matchCount The number of challenge questions that the user successfully Integer
answered.
ChallengeQuestionAuthResults payload
This structure returns the results of the challenge question authentication.

authenticationResult The result of the authentication. AuthenticationResult
challengeQuestionMatchResult The results of the challenge question authentication. ChallengeQuestionMat

chResult
The following structures are used by the challenge method.
ChallengeQuestionChallengeRequest payload
This payload returns the result of the challenge questions.
excludeQuestions Determines which of the system questions to N ChallengeQuestoinId

exclude in the response message. List[ ]
numberOfQuestion The number of questions to return to the user. Y Integer
ChallengeQuestionChallenge payload
This response message payload structure returns the results of the challenge question
authentication.
callStatus The status of the challenge question credential call. CallStatus
challengeQuestions A list of the users specific challenge questions, minus ChallengeQuestionList[ ]

any excluded questions as denoted in the request
message.

Question Management Structures

These structures deal with managing the users challenge questions, such as updating
the users answer or changing a users challenge question.
ChallengeQuestionData payload
If your application requests the users chosen challenge question, this payload returns
it.
challengeQuestion The users chosen challenge question(s). ChallengeQuestion[]
ChallengeQuestionManagementRequest payload
This payload is used to perform management actions on the users challenge
questions.
actionTypeList The action to be taken in regards to the Y ChallengeQuestionActio

users challenge questions. nType List[ ]
challengeQuestionList The challenge question chosen by the user. Y ChallengeQuestionList[

]
challengeQuestionConfig The specific configurations for the N ChallengeQuestionConfi

challenge question. g
ChallengeQuestionManagementResponse payload
This payload is used to return the results of the request made in
ChallengeQuestionManagementRequest.
acspAccountID The session number. String
browsableChallengeQuestGr The challenge questions from which a user ChallengeQuestionGroupList[ ]

oupList can choose.
callStatus The status of the call. CallStatus
challengeQuestDataList The list of the users challenge question. ChallengeQuestionList[ ]
challengeQuestionGroupList The group number of the users challenge ChallangeQuestionGroupList[ ]

questions.

H Authentication Plug-In Credential

WSDL/XSD Additions
Authentication Plug-In Credential Payloads
Authentication Plug-In Credential Requests and Responses
This appendix describes the synchronous or asynchronous challenge-response
credential, generic authentication plug-in.
The authentication level for the plug-in should be configured by the organization.
The WSDL is enhanced to support a generic structure (place holder), which extends
the core implementation. The generic structures support both the request and the
response.
WSDL/XSD Additions
The main AdaptiveAuthentication.wsdl includes a reference to ACSP.xsd
containing all the generic payload definitions for each business request. You need to
define your own specific xsd containing the actual implementation definitions. All the
specific xsds should be listed in ACSPImports.xsd.
AdaptiveAuthentication.wsdl:

<xsd:include schemaLocation="ACSP.xsd"/>
<xsd:include schemaLocation="ACSPImports.xsd"/>

Sample.xsd:

<xsd:import
namespace="http://ws.csd.rsa.com"
schemaLocation="ACSP.xsd"/>

ACSPImports.xsd:

<xsd:import
namespace="http://ws.sample.org"
schemaLocation="SampleAcsp.xsd"/>
H: Authentication Plug-In Credential 335

Authentication Plug-In Credential Payloads

CredentialRequestList:
<complexType abstract="true" name="CredentialRequestList">
<xsd:annotation>
<xsd:documentation>This defines the contents of an abstract Credential
Request List</xsd:documentation>
</xsd:annotation>
</complexType>
CredentialResponseList:
<complexType abstract="true" name="CredentialResponseList">
<xsd:annotation>
<xsd:documentation>This defines the contents of an abstract Credential
Response List</xsd:documentation>
</xsd:annotation>
</complexType>
Authentication Plug-In Credential Requests and Responses

Authentication and Analyze Request
Credential data list contains an object acspAuthenticationRequestData, which is a
wrapper for the customized Authentication Plug-In payload.
<complexType name="CredentialDataList">
<complexContent>
<extension base="rsa_csd:CredentialRequestList">
<xsd:annotation>
<xsd:documentation>This is a list of any credentials that the user
has presented as a part of this transaction</xsd:documentation>
</xsd:annotation>
<sequence>
<element name="challengeQuestionData" minOccurs="0"
type="rsa_csd:ChallengeQuestionData" />
<element name="oobEmailData" minOccurs="0"
type="rsa_csd:OobEmailData" />
<element name="oobPhoneData" minOccurs="0"
type="rsa_csd:OobPhoneData" />
<element name="acspAuthenticationRequestData" minOccurs="0"
type="rsa_csd:AcspAuthenticationRequestData" />
</sequence>
</extension>
</complexContent>
</complexType>
This wrapper contains a generic payload. You should derive from this payload to
implement a specific one.
<xsd:complexType name="AcspAuthenticationRequestData">
<xsd:annotation>
<xsd:documentation>This type defines the Credential Data Payload</
336 H: Authentication Plug-In Credential

xsd:documentation>
</xsd:annotation>
<xsd:sequence>
<xsd:element name="payload" minOccurs="0"
type="rsa_csd:AcspAuthenticationRequest" />
</xsd:sequence>
</xsd:complexType>
Generic Section (ACSP.xsd):
<xsd:complexType name="AcspAuthenticationRequest" abstract="true">
<xsd:annotation>
<xsd:documentation>This type defines Interface for Authentication Request</
xsd:documentation>
</xsd:annotation>
</xsd:complexType>
Customized section (Sample.xsd):
<xsd:complexType name="SampleAcspAuthenticationRequest">
<xsd:complexContent>
<xsd:extension base="rsa_csd:AcspAuthenticationRequest">
<xsd:annotation>
<xsd:documentation>This type defines the Specific Authentiaction
Request</xsd:documentation>
</xsd:annotation>
<xsd:sequence>
<xsd:element name="sampleOtp" minOccurs="0" type="xsd:string" />
<xsd:element name="field1" minOccurs="0" type="xsd:string" />
<xsd:element name="field5" minOccurs="0" type="xsd:double" />
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>

Authentication and Analyze Response

Credential data list contains an object acspAuthenticationResponseData, which is a
<complexType name="CredentialAuthResultList">
<complexContent>
<extension base="rsa_csd:CredentialResponseList">
<xsd:annotation>
<xsd:documentation>This is a list of the authorization results for
each credential</xsd:documentation>
</xsd:annotation>
<sequence>
<element name="challengeQuestionAuthResult" minOccurs="0"
type="rsa_csd:ChallengeQuestionAuthResult" />
<element name="oobEmailAuthResult" minOccurs="0"
type="rsa_csd:OobEmailAuthResult" />
<element name="oobPhoneAuthResult" minOccurs="0"
type="rsa_csd:OobPhoneAuthResult" />
<element name="acspAuthenticationResponseData" minOccurs="0"
type="rsa_csd:AcspAuthenticationResponseData" />
</sequence>
</extension>
</complexContent>
</complexType>
<xsd:complexType name="SampleAcspAuthenticationResponse">
<xsd:extension base="rsa_csd:AcspAuthenticationResponse">
<xsd:annotation>
<xsd:documentation>This type defines the Specific Authentiaction
Response</xsd:documentation>
</xsd:annotation>
<xsd:sequence>
</xsd:sequence>
</xsd:extension>
</xsd:complexType>

<xsd:complexType name="AcspAuthenticationResponse" abstract="true">
<xsd:annotation>
<xsd:documentation>This type defines Interface for Authentication Response</
xsd:documentation>
</xsd:annotation>

</xsd:complexType>
Customized Section (Sample.xsd):
<xsd:complexType name="SampleAcspAuthenticationResponse">
<xsd:extension
base="rsa_csd:AcspAuthenticationResponse">
<xsd:annotation>
<xsd:documentation>This type defines the Specific
Authentiaction Response</xsd:documentation>
</xsd:annotation>
<xsd:sequence>
<xsd:element name="field1" minOccurs="0"
type="xsd:string" />
</xsd:sequence>
</xsd:extension>
</xsd:complexType>
Query, Create User, and Update User Requests

Credential data list contains an object acspManagementRequestData, which is a
<complexType name="CredentialManagementRequestList">
<complexContent>
<xsd:annotation>
<xsd:documentation>This defines the Credential Management Request
List</xsd:documentation>
</xsd:annotation>
<sequence>
<element name="challengeQuestionManagementRequest" minOccurs="0"
type="rsa_csd:ChallengeQuestionManagementRequest" />
<element name="oobEmailManagementRequest"
minOccurs="0" type="rsa_csd:OobEmailManagementRequest" />
<element name="oobPhoneManagementRequest" minOccurs="0"
type="rsa_csd:OobPhoneManagementRequest" />
<element name="acspManagementRequestData" minOccurs="0"
type="rsa_csd:AcspManagementRequestData" />
</sequence>
</extension>
</complexContent>
</complexType>
<xsd:complexType name="AcspManagementRequestData">

<xsd:annotation>
<xsd:documentation>This type defines the Credential Management Request
Payload</xsd:documentation>
</xsd:annotation>
<xsd:sequence>
<xsd:element name="credentialProvisioningStatus" minOccurs="0"
type="rsa_csd:CredentialProvisioningStatus" />
type="rsa_csd:AcspManagementRequest" />
</xsd:sequence>
</xsd:complexType>
Generic section (ACSP.xsd):
<xsd:complexType name="AcspManagementRequest" abstract="true">
<xsd:annotation>
<xsd:documentation>This type defines Interface for Management Request</
xsd:documentation>
</xsd:annotation>
<xsd:sequence>
<xsd:element name="opcode" minOccurs="0" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
Customized section (Sample.xsd):
<xsd:complexType name="SampleAcspManagementRequest">
<xsd:extension base="rsa_csd:AcspManagementRequest">
<xsd:annotation>
<xsd:documentation>This type defines the Specific Management
</xsd:annotation>
<xsd:sequence>
<xsd:element name="sampleIntEnum" minOccurs="0"
type="sample:SampleIntEnum" />
<xsd:element name="sampleStringEnum" minOccurs="0"
type="sample:SampleStringEnum" />
</xsd:sequence>
</xsd:extension>
</xsd:complexType>

Query, Create User, and Update User Responses

Credential data list contains an object acspManagementResponseData, which is a
<complexType name="CredentialManagementResponseList">
<complexContent>
<xsd:annotation>
<xsd:documentation>This defines the Credential Management Response
List</xsd:documentation>
</xsd:annotation>
<sequence>
<element name="challengeQuestionManagementResponse" minOccurs="0"
type="rsa_csd:ChallengeQuestionManagementResponse" />
<element name="oobEmailManagementResponse" minOccurs="0"
type="rsa_csd:OobEmailManagementResponse" />
<element name="oobPhoneManagementResponse"
minOccurs="0" type="rsa_csd:OobPhoneManagementResponse" />
<element name="acspManagementResponseData" minOccurs="0"
type="rsa_csd:AcspManagementResponseData" />
</sequence>
</extension>
</complexContent>
</complexType>
<xsd:complexType name="AcspManagementResponseData">
<xsd:annotation>
<xsd:documentation>This type defines the Credential Management Response
</xsd:annotation>
<xsd:sequence>
<xsd:element name="acspAccountId" minOccurs="0" type="xsd:string"/>
<xsd:element name="callStatus" minOccurs="0" type="rsa_csd:CallStatus"/>
type="rsa_csd:AcspManagementResponse" />
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="AcspManagementResponse" abstract="true">
<xsd:annotation>
<xsd:documentation>This type defines Interface for Management Response</
xsd:documentation>
</xsd:annotation>
</xsd:complexType>

<xsd:complexType name="SampleAcspManagementResponse">
<xsd:extension base="rsa_csd:AcspManagementResponse">
<xsd:annotation>
<xsd:documentation>This type defines the Specific Management
</xsd:annotation>
<xsd:sequence>
<xsd:element name="sampleIntEnum" minOccurs="0"
type="sample:SampleIntEnum" />
<xsd:element name="sampleStringEnum" minOccurs="0"
type="sample:SampleStringEnum" />
</xsd:sequence>
</xsd:extension>
</xsd:complexType>
Challenge Request
Credential data list contains an object acspChallengeRequestData, which is a wrapper
for the customized Authentication Plug-In payload.
<complexType name="CredentialChallengeRequestList">
<complexContent>
<xsd:annotation>
<xsd:documentation>This list returns a user's challenge material
from the RSA System</xsd:documentation>
</xsd:annotation>
<sequence>
<element name="challengeQuestionChallengeRequest" minOccurs="0"
type="rsa_csd:ChallengeQuestionChallengeRequest" />
<element name="oobEmailChallengeRequest" minOccurs="0"
type="rsa_csd:OobEmailChallengeRequest" />
<element name="oobPhoneChallengeRequest" minOccurs="0"
type="rsa_csd:OobPhoneChallengeRequest" />
<element name="acspChallengeRequestData" minOccurs="0"
type="rsa_csd:AcspChallengeRequestData" />
</sequence>
</extension>
</complexContent>
</complexType>

<xsd:complexType name="AcspChallengeRequestData">
<xsd:annotation>
<xsd:documentation>This type defines the Credential Challenge Request
</xsd:annotation>
<xsd:sequence>
type="rsa_csd:AcspChallengeRequest" />
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="AcspChallengeRequest" abstract="true">
<xsd:annotation>
<xsd:documentation>This type defines Interface for Challenge Request</
xsd:documentation>
</xsd:annotation>
</xsd:complexType>
<xsd:complexType name="SampleAcspChallengeRequest">
<xsd:extension base="rsa_csd:AcspChallengeRequest">
<xsd:annotation>
<xsd:documentation>This type defines the Specific Challenge
</xsd:annotation>
<xsd:sequence>
</xsd:sequence>
</xsd:extension>
</xsd:complexType>

Challenge Response
Credential data list contains an object acspChallengeResponseData, which is a
<complexType name="CredentialChallengeList">
<complexContent>
<xsd:annotation>
<xsd:documentation>This returns the challenge material to be
presented to the user</xsd:documentation>
</xsd:annotation>
<sequence>
<element name="challengeQuestionChallenge" minOccurs="0"
type="rsa_csd:ChallengeQuestionChallenge" />
<element name="oobEmailChallenge" minOccurs="0"
type="rsa_csd:OobEmailChallenge" />
<element name="oobPhoneChallenge" minOccurs="0"
type="rsa_csd:OobPhoneChallenge" />
<element name="acspChallengeResponseData" minOccurs="0"
type="rsa_csd:AcspChallengeResponseData" />
</sequence>
</extension>
</complexContent>
</complexType>
<xsd:complexType name="AcspChallengeResponseData">
<xsd:annotation>
<xsd:documentation>This type defines the Credential Challenge Payload</
xsd:documentation>
</xsd:annotation>
<xsd:sequence>
type="rsa_csd:AcspChallengeResponse" />
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="AcspChallengeResponse" abstract="true">
<xsd:annotation>
<xsd:documentation>This type defines Interface for Challenge Response</
xsd:documentation>
</xsd:annotation>
</xsd:complexType>

<xsd:complexType name="SampleAcspChallengeResponse">
<xsd:extension base="rsa_csd:AcspChallengeResponse">
<xsd:annotation>
<xsd:documentation>This type defines the Specific Challenge
</xsd:annotation>
<xsd:sequence>
<xsd:element name="sampleOtp" minOccurs="0" type="xsd:string" />
</xsd:sequence>
</xsd:extension>
</xsd:complexType>
Get Authentication Status Request

Credential data list contains an object acspAuthStatusRequestData, which is a wrapper
for the customized Authentication Plug-In payload.
<complexType name="CredentialAuthStatusRequest">
<complexContent>
<xsd:annotation>
<xsd:documentation>A request to view the status of an asynchronous
credential</xsd:documentation>
</xsd:annotation>
<sequence>
<element name="challengeQuestionAuthStatusRequest" minOccurs="0"
type="rsa_csd:ChallengeQuestionAuthStatusRequest" />
<element name="oobEmailAuthStatusRequest" minOccurs="0"
type="rsa_csd:OobEmailAuthStatusRequest" />
<element name="oobPhoneAuthStatusRequest" minOccurs="0"
type="rsa_csd:OobPhoneAuthStatusRequest" />
<element name="acspAuthStatusRequestData" minOccurs="0"
type="rsa_csd:AcspAuthStatusRequestData" />
</sequence>
</extension>
</complexContent>
</complexType>

<xsd:complexType name="SampleAcspAuthStatusRequest">
<xsd:extension base="rsa_csd:AcspAuthStatusRequest">
<xsd:annotation>
AuthStatus Request</xsd:documentation>
</xsd:annotation>
<xsd:sequence>
<xsd:element name="sampleOtp" minOccurs="0"
</xsd:sequence>
</xsd:extension>
</xsd:complexContent
</xsd:complexType>
<xsd:complexType name="AcspAuthStatusRequest" abstract="true">
<xsd:annotation>
<xsd:documentation>This type defines Interface for AuthStatus Request</
xsd:documentation>
</xsd:annotation>
</xsd:complexType>

<xsd:complexType name="SampleAcspAuthStatusRequest">
<xsd:extension base="rsa_csd:AcspAuthStatusRequest">
<xsd:annotation>
AuthStatus Request</xsd:documentation>
</xsd:annotation>
<xsd:sequence>
<xsd:element name="sampleOtp" minOccurs="0"
</xsd:sequence>
</xsd:extension>
</xsd:complexContent
</xsd:complexType>
Get Authentication Status Response

Credential data list contains an object acspAuthStatusResponseData, which is a
<complexType name="CredentialAuthStatusResponse">
<complexContent>
<xsd:annotation>
<xsd:documentation>The result of a user's asynchronous credential<
/xsd:documentation>
</xsd:annotation>
<sequence>
<element name="challengeQuestionAuthStatusResponse" minOccurs="0"
type="rsa_csd:ChallengeQuestionAuthStatusResponse" />
<element name="oobEmailAuthStatusResponse" minOccurs="0"
type="rsa_csd:OobEmailAuthStatusResponse" />
<element name="oobPhoneAuthStatusResponse" minOccurs="0"
type="rsa_csd:OobPhoneAuthStatusResponse" />
<element name="acspAuthStatusResponseData" minOccurs="0"
type="rsa_csd:AcspAuthStatusResponseData" />
</sequence>
</extension>
</complexContent>
</complexType>
<xsd:complexType name="AcspAuthStatusResponseData">

<xsd:annotation>
<xsd:documentation>This type defines the Credential AuthStatus Response
</xsd:annotation>
<xsd:sequence>
type="rsa_csd:AcspAuthStatusResponse" />
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="AcspAuthStatusResponse" abstract="true">
<xsd:annotation>
<xsd:documentation>This type defines Interface for AuthStatus Response</
xsd:documentation>
</xsd:annotation>
</xsd:complexType>

<xsd:complexType name="SampleAcspAuthStatusResponse">
<xsd:extension base="rsa_csd:AcspAuthStatusResponse">
<xsd:annotation>
<xsd:documentation>This type defines the Specific AuthStatus
</xsd:annotation>
<xsd:sequence>
</xsd:sequence>
</xsd:extension>
</xsd:complexType>

I Authentication Levels
The following table contains the various authentication levels scaled from 1-1000,
where the strength of authentication increases; 1000 is considered the strongest form
of authentication.
If you are using your own authentication methods outside of the RSA Adaptive
Authentication (On Premise) system, you should map your existing authentication to
these levels and pass them to the Adaptive Authentication system when needed. For
example, use a user name and password to authenticate a user before passing the user
to the Adaptive Authentication system for logon authentication.
Authentication
Authentication Type Used Relation to Password
Level
Challenge Questions In addition to password 750
Dynamic account data In addition to password 550
Email OOB In addition to password 800
SMS OOB In addition to password 850
Knowledge Based Authentication In addition to password 650
Password NA 500
Password (federated site) Instead of internal password 450
Password + Token - Count Based OTP - Low In addition to password 795

Confidence
Phone OOB In addition to password 850
Stock portfolio questions In addition to password 700
Token - Challenge Response Instead of password 975
Token - Connected Instead of password 950
Token - Connected In addition to password 960
Token - Count Based OTP In addition to password 810
Token - Count Based OTP Instead of password 800
Token - Count Based OTP - Low Confidence Instead of password 790
Token - Signing Instead of password 1000
Token - Time Based OTP Instead of password 900
I: Authentication Levels 351

Authentication
Authentication Type Used Relation to Password
Level
Token - Time Based OTP In addition to password 910
Token - Time Based OTP - Low Confidence Instead of password 890
Token - Time Based OTP - Low Confidence In addition to password 895
352 I: Authentication Levels

J API Error Messages

Error Messages
reasonCode & reasonDescription Values
This appendix describes the error messages returned by the RSA Adaptive
Authentication (On Premise) Web Services API processes and the reasonCode and
reasonDescription values.
Error Messages
The following table lists the actual error codes, the status description provided in the
response message, as well as an explanation of the error codes and status descriptions.
Error Code Status Description Explanation
CHECKING_NONEXISTENT_CH A challenge must be sent before An alert to check the notification

ALLENGE checking its status. object before sending a challenge.
INVALID_CHALLENGE_CONTAC Invalid contact for notification An alert that invalid contact

T challenge. information was sent for
notification.
INVALID_REQUEST Invalid Request. The request is missing a required

elementS or is null.
INVALID_REQUEST_MISSING_D Action Update_Device requires The Device Credential failed to

EVICE_DATA device data element. update a device because the data
element, deviceData, was missing
from the payload.
MISUSE_COLLECTION_FLOW INVALID_COLLECTION_FL An alert that the collection flow is

OW_USAGE being misused.
NO_ACTION_SPECIFIED No Action Specified. No action was specified.
SEE_CHANNEL_STATUS NOTE_CHANNEL_STATUS An alert to look at the channel

parameters.
SYSTEM_ERROR SYSTEM_ERROR An unknown system error occurred.
UNSUPPORTED_METHOD This method is not supported An alert that a method call is not
for this credential. supported for a given credential.
J: API Error Messages 353

reasonCode & reasonDescription Values

The parameters, reasonCode and reasonDescription, provide details on the status of
the Web Services calls, in terms of:
Generic errors and warnings
Configuration errors and warnings
User error and warning
reasonCode reasonDescription Additional Information
0 Operations completed successfully Operations completed successfully.
1001 to 1050 GENERIC ERRORS

These errors usually require further investigations by Adaptive Authentication
1001 Unknown Error
1002 General Error
1003 Platform Error Errors originated from Adaptive Authentication

platform.
1004 Missing Argument Error Errors due to missing arguments/parameters.
1051 to 1100 Generic Warnings/Info
1051 General Warning
1052 Multiple Warnings In the event where multiple warnings occur, this
warning code is displayed.
1101 to 1150 CONFIGURATION ERRORS
1101 Configuration Error
1151 to 1200 Configuration Level Warnings
1151 Configuration Warning
1201 to 1250 SESSION LEVEL ERRORS Errors in session handling
1201 Session Error Generic Session Error.
1202 Invalid Session Error The session being requested or handled is invalid.
1203 Invalid /Expired Session Id Error The error code is issued when either the session Id is
invalid or the session is expired. As a result, the
processing error prevents successful completion of
the SOAP request .
1251 to 1300 Session Level Warnings
354 J: API Error Messages

1251 Session Warnings
1252 Multiple locales in a single session Multiple locales are detected in a single session.
1301 to 1350 TRANSACTION LEVEL ERRORS

Errors in transaction handling
1301 Transaction Error Generic Transaction Error.
1302 Invalid Transaction Error The transaction being requested/handled is invalid.
1303 Invalid Transaction Id Error The transaction id input to Adaptive Authentication

is invalid.
1351 to 1400 Transaction Level Warnings
1351 Transaction Warning
1401 to 1450 MCF LEVEL ERRORS

Errors thrown by the Multi-Credential-Framework
1401 Authentication Plug-In or Payload Errors in the Authentication Plug-In payload or in

Error the underlying credential (Authentication Plug-In)
implementation.
1402 User Credential Manager Error Errors thrown by User Credential Manager.
1403 System Credential Manager Errors thrown by System Credential Manager.
1451 to 1500 MCF LEVEL WARNINGS
1451 MCF Warning
1452 User Credential Missing Warning User does not have any of the required credentials.
1453 Authentication Plug-In or Payload Warnings in the Authentication Plug-In payload or

Warning in the underlying credential (Authentication Plug-
In) implementation.
1454 Device Management Payload An error occurred during device management

Warning handling.
1501 to 1550 USER LEVEL ERRORS
1501 User Level Error Generic User level error. For now this is the only
user level error defined.
1502 User not enrolled The user is not enrolled in the Adaptive
1551 to 1550 USER LEVEL WARNINGS
J: API Error Messages 355

1551 User Level Warning
1601 to 1650 INPUT DATA ERRORS

Errors in the input data
1601 Missing Input Data Error Required data elements are missing in the request.
1602 Input Data Error The data element in the request results in processing
error.
1603 Invalid Action Type Error The ActionType element in the WS request is not
legal.
1604 Authentication Error The data failed basic authentication.
1605 Data Validation Error Data fields that failed Adaptive Authentications
data validation.
1606 Business Validation Error Failed while performing Business Validation on

incoming request.
1651 to 1700 INPUT DATA WARNINGS
1651 Input Data Warning
1652 Input Data Replaced Warning The Adaptive Authentication system replaced some
data in the request message with other data.
1653 Input Data Omitted The Adaptive Authentication system omitted some
data from the request message.
356 J: API Error Messages

WS API ReferenceGuide

Загружено:

Сведения о документе

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

WS API ReferenceGuide

Загружено:

Авторское право:

Доступные форматы

RSA Adaptive Authentication

Chapter 1: API Overview .......................................................................................... 17

Chapter 2: Web Services Basic Processes .................................................. 35

Step 4: Collect the Users Password (Optional) ........................................................ 45

Chapter 3: Web Services API Methods ........................................................... 61

Chapter 4: Web Services API Data Elements .............................................. 85

Chapter 7: Web Services Response Data Structures and Types . 153

deviceManagementResponse .......................................................................................... 165

Chapter 8: AdminService Basic Processes ............................................... 171

Chapter 9: AdminService API Methods ........................................................ 177

getUserStatus Method ..................................................................................................... 189

Chapter 10: AdminService API Interfaces ................................................... 197

Chapter 11: Case Management Processes................................................. 205

Chapter 12: Case Management API Methods............................................ 213

Request for the getCases Method ............................................................................ 230

Chapter 13: ATM Protection Module............................................................... 247

Appendix A: Out-of-Band Phone Authentication Plug-In .................. 267

Appendix B: Out-of-Band Phone Authentication Plug-In Web

AuthenticationResult ............................................................................................... 278

Appendix C: Out-of-Band Phone and Email Credential ..................... 293

Appendix D: One-Time Password Credential ........................................... 303

Appendix E: Knowledge-based Authentication Credential .............. 313

Appendix F: Out-of-Band SMS Authentication Credential ............... 323

Appendix G: Challenge Question Credential ............................................ 327

Appendix H: Authentication Plug-In Credential ...................................... 335

Appendix I: Authentication Levels................................................................... 351

About This Guide

RSA Adaptive Authentication (On-Premise) Documentation

Product Overview Guide. Provides a high-level overview of RSA Adaptive

Support and Service

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

RSA Solution Gallery https://gallery.emc.com/community/marketplace/rsa?

RSA SecurCare Online offers a knowledgebase that contains answers to common

Before You Call Customer Support

Introduction to Web Services API

The following types of services are described in this chapter:

Credential Type Description Credential

Asynchronous A user is presented with a challenge Out-of-band phone

Challenge-response A credential in which the user Challenge questions

Synchronous or Both synchronous and asynchronous Generic authentication plug-in

Verification only A user presents their credentials to Device information

How Web Services Uses Credentials

Adaptive Authentication (On-Premise) Workflow

4. For Transaction Authentication only. The user attempts to execute a

Identifying Invalid Users

Authentication Attempt Time-Out

Using Web Services

Web Services requires:

Important: Adaptive Authentication (On-Premise) expects all data to be UTF-8

Sample SOAP request

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/

Sample SOAP response

Change the endpoint of the Async WSDL to: http://{host}:{port}/

Retrieve WSDL files

2. Save the WSDL to your local drive.

To retrieve the WSDLs for Adaptive Authentication AdminService API:

2. Save the WSDL to your local drive.

The Location of the WSDLs for Adaptive Authentication Case

Receiving SOAP Request and Response Elements

ISO 8601 Date and Time Format

Using Web Services Security for Case Management API

Authorization is accomplished by assigning the users to at least one of two specific

Implementing the Web Services Security SOAP Header

2 Web Services Basic Processes