RSA SecurID Authentication API

Developer's Guide

 
Contact Information

RSA Link at https://community.rsa.com contains a knowledgebase that answers common questions and 
provides solutions to known problems, product documentation, community discussions, and case management.

Trademarks

Dell, RSA, the RSA Logo, EMC and other trademarks, are trademarks of Dell Inc. or its subsidiaries. Other 
trademarks may be trademarks of their respective owners. For a list of RSA trademarks, go to 
www.emc.com/legal/emc-corporation-trademarks.htm#rsa.

License Agreement

This software and the associated documentation are proprietary and confidential to Dell Inc. or its subsidiaries, 
are furnished under license, and may be used and copied only in accordance with the terms of such license and 
with the inclusion of the copyright notice below. This software and the documentation, and any copies thereof, 
may not be provided or otherwise made available to any other person. 

No title to or ownership of the software or documentation or any intellectual property rights thereto is hereby 
transferred. Any unauthorized use or reproduction of this software and the documentation may be subject to 
civil and/or criminal liability. 

This software is subject to change without notice and should not be construed as a commitment by Dell Inc.

Third-Party Licenses

This product may include software developed by parties other than RSA. The text of the license agreements 
applicable to third-party software in this product may be viewed on the product documentation page on RSA 
Link. By using this product, a user of this product agrees to be fully bound by terms of the license agreements.

Note on Encryption Technologies

This product may contain encryption technology. Many countries prohibit or restrict the use, import, or export 
of encryption technologies, and current use, import, and export regulations should be followed when using, 
importing or exporting this product.

Distribution

Use, copying, and distribution of any Dell software described in this publication requires an applicable software 
license.

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

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

 
©
Copyright   2015-2020 Dell Inc. or its subsidiaries. All Rights Reserved.

February 2020
RSA SecurID Access RSA SecurID Authentication API Developer's Guide

Contents

Preface 6

About This Guide 6

Product Documentation 6

OpenAPI References 6

Graphics Key 6

RSA SecurID Access Support and Service 6

Support for RSA Authentication Manager 7

Support for the Cloud Authentication Service and Identity Routers 7

RSA Ready Partner Program 7

Chapter 1: Getting Started with the RSA SecurID Authentication API 8

RSA SecurID Authentication API Overview 9

RSA SecurID Access Services 9

RSA SecurID Authentication API Definition File 9

Authentication Process Flow 9

Processing Results from Initialize and Verify 11

SSL Certificate Requirements 12

REST Endpoint URLs 12

Required Keys for REST Requests 13

RSA Authentication Manager Requirement 13

Cloud Authentication Service Requirement 13

MethodIDs and Attributes 13

SECURID_NEW_PIN and SECURID_SYSTEM_GENERATED_PIN Attributes for RSA Authentication 
Manager 14

SECURID_NEWPIN  Attributes for the Cloud Authentication Service 14

Method Attributes Returned for Initialize 15

Evaluating Assurance Levels and Primary Authentication Status to Return Authentication Methods 15

Assurance Level Evaluation 15

Assurance Level Evaluation Steps 16

Assurance Level Evaluation Examples 16

Scenario: Assurance level does not include the primary authentication method 17

Scenario: Assurance level includes the primary authentication method 18

Chapter 2: Using the RSA SecurID Authentication API 19

3
RSA SecurID Access RSA SecurID Authentication API Developer's Guide

Initialize and Verify Calls 20

Initialize  Request 20

Initialize Request Example 20

Initialize Request Parameters 21

Unsupported Parameters 23

Initialize with subjectCredentials 23

Requirements for subjectCredential 24

Initialize with clientDetails 24

Requirements for clientDetails 25

Verify Request 25

Verify Request Example 26

Verify Request Parameters 26

Verify Credential Properties 27

Verify Credential.collectedInputs (NameValuePair) Properties 27

Initialize and Verify Response 27

AuthNResponse Properties 27

AuthNResponse credentialValidationResults Properties 28

AuthNResponse challengeMethods and Related Properties 29

AuthNResponse Content Returned By Initialize and Verify 30

AuthNResponse challengeMethods (ChallengeMethods) Properties 30

AuthNResponse challengeMethods.challenges Properties 30

AuthNResponse challengeMethods...requiredMethods Properties 30

AuthNResponse challengeMethods...versions Properties 31

AuthNResponse challengeMethods...prompt Properties 32

Initialize and Verify Attempt Response Codes 32

Check Status Call 35

Check Status Request 35

Response to Verify 35

Explicit Call to Check Status 35

Check Status Example 35

Check Status Parameters 36

Check Status Response 36

AuthNStatusReponse Properties 36

4
RSA SecurID Access RSA SecurID Authentication API Developer's Guide

Cancel Call 38

Cancel Request 38

Cancel Request Example 38

Cancel Parameters 38

Chapter 3: Sample Clients for the RSA SecurID Authentication API 39

Sample Client Overview 40

Software Requirements 40

Files and Directories 40

Build Sample Clients for RSA Authentication Manager 40

5
RSA SecurID Access RSA SecurID Authentication API Developer's Guide

Preface
 

About This Guide

RSA SecurID Authentication API is a REST API for  d evelopers who want to  b uild clients that send authentication 

requests to RSA SecurID Access, either through the RSA Authentication Manager server, the Cloud 
Authentication Service, or both. 

RSA strongly recommends using the RSA SecurID Authentication API for developing new clients. This document 
describes how the REST interface JSON  p roperties are  used for  authentication and provides guidance for 
specific scenarios. Each section describes a REST endpoint interface, the expected way the interface is called, 
the server responses the client should be ready to accept, and security aspects the client should be validating.

Product Documentation
For a complete list of RSA SecurID Access documentation, see "RSA SecurID Access Product Documentation" on 
RSA Link at https://community.rsa.com/docs/DOC-60094.

OpenAPI References
The https://swagger.io web site contains useful information for developers using REST APIs. 

 l OpenAPI Specification: http://swagger.io/specification/
 l OpenAPI Tools: http://swagger.io/tools/
 l Swagger Editor: http://swagger.io/swagger-editor/
 l Swagger CodeGen: http://swagger.io/swagger-codegen/
 l Swagger UI (interactive documentation): http://swagger.io/swagger-ui/ 
 l On-Line Support Forums: http://swagger.io/forum/

Graphics Key
The symbols in the following table apply to  the graphics used in this guide.

Symbol Description

Compound element containing one or more elements.

Simple element of a single type (for example, string, number, and so on).

Ennumerated element and type.

Groups elements in an array.

RSA SecurID Access Support and Service

You can access community and support information  on RSA Link  at  h
  ttps://community.rsa.com. RSA Link 
contains a knowledgebase that answers common questions and provides solutions to known problems, product 

Preface 6
RSA SecurID Access RSA SecurID Authentication API Developer's Guide

documentation, community discussions, and case management. 

Support for RSA Authentication Manager

Before you call Customer Support for help with the RSA Authentication Manager appliance, have the following 
information available:

 l Access to the RSA Authentication Manager appliance.
 l Your license serial number. To find this number, do one of the following:
 l Look at the order confirmation e-mail that you received when your ordered the product. This e-
mail contains the license serial number.
 l Log on to the Security Console, and click License Status. Click View Installed License.

 l The  appliance software version. This information is located in the top, right corner of the Quick Setup, or 
you can log on to the Security Console and click Software Version Information.

Support for the Cloud Authentication Service and Identity Routers

If your company has deployed identity routers and uses the Cloud Authentication Service, RSA provides you with 
a unique identifier called the Customer Support ID. This is required when you register with RSA Customer 
Support. To see your Customer Support ID, sign in to the Cloud Administration Console  and click My Account >
Company Settings.

RSA Ready Partner Program

The RSA Ready Partner Program website at www.rsaready.com provides information about third-party hardware 
and software products that have been certified to work with RSA products. The website includes 
Implementation Guides with step-by-step instructions and other information on how RSA products work with 
third-party products.   

Preface 7
RSA SecurID Access RSA SecurID Authentication API Developer's Guide

Chapter 1: Getting Started with the RSA SecurID 
Authentication API

RSA SecurID Authentication API Overview 9

Authentication Process Flow 9

Processing Results from Initialize and Verify 11

SSL Certificate Requirements 12

REST Endpoint URLs 12

Required Keys for REST Requests 13

MethodIDs and Attributes 13

Evaluating Assurance Levels and Primary Authentication Status to Return Authentication Methods 15

Chapter 1: Getting Started with the RSA SecurID Authentication API 8

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

RSA SecurID Authentication API Overview

The RSA SecurID Authentication API is a REST-based programming interface that allows you to develop clients 
that  p rocess multifactor, multistep authentications through RSA Authentication Manager and the Cloud 
Authentication Service. The interface definition can be integrated with any programming language.

RSA SecurID Access Services

The Authentication API supports the RSA SecurID Access, described on RSA Link at 
https://community.rsa.com/community/products/securid. This product provides the following services:

 l Cloud Authentication Service. Your client must point to this server to support the RSA SecurID 
Authenticate Tokencode, SecurID Token, Approve, Device Biometrics (such as Fingerprint), SMS 
Tokencode, Voice Tokencode, Emergency Tokencode, and Password authentication methods. 

 l RSA Authentication Manager.  T he Authentication Manager server must be deployed in your environment 
to support RSA SecurID tokens. Authentication Manager supports RSA SecurID Authenticate Tokencodes 
when configured to integrate with the Cloud Authentication Service. The Authentication API supports 
Authentication Manager 8.2 Service Pack 1 or later.

RSA SecurID Authentication API Definition File

RSA provides an OpenAPI interface definition source file containing details on the REST endpoints and JSON 
objects. This file is the authoritative source for detailed information on all required and optional parameters. You 
can download the file, rsa-securid-authenticate-api.yaml, from RSA Link at this location: 
https://community.rsa.com/docs/DOC-71396.

Note:  Do not modify the rsa-securid-authenticate-api.yaml file. Modifying this file causes authentication to 
fail.

Authentication Process Flow

The following diagram shows the general flow of the interface during authentication. 

Chapter 1: Getting Started with the RSA SecurID Authentication API 9

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

The following steps describe at a high level the client-server process flow during authentication. These steps 
apply to both the RSA Authentication Manager server and the Cloud Authentication Service.

 1.  The client calls the Initialize interface. 

Calls to the Authentication Manager server use the user login ID (subjectName). 

Calls to the Cloud Authentication Service use the email, SecurID Username, or Alternate Username 
specified in the Identity Source  c onfiguration in the Cloud Administration Console. For Active Directory, 
the default is sAMAccountName. For other LDAP vendors, this is a vendor-specific value.

Note:  When the client sends Initialize with subjectCredentials, it provides the server with credentials to 
be verified in advance.  W
  hen subjectCredentials is not used, the server returns information to the client 
indicating what credentials are required. subjectCredentials is optional for the Initialize call.

 2.  The Initialize interface responds with the challenge method options and requirements for the user to 
complete authentication. 
 3.  The client collects challenge method credentials from the user and sends them to the server in a Verify 
interface call.

 4.  The Verify interface  r esponds in one of two ways:

 l If the user’s authentication is complete and successful, the user is  g ranted access to the 
requested resource.

Chapter 1: Getting Started with the RSA SecurID Authentication API 10

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

 l If authentication is not complete, the Verify interface sends the additional challenge 
requirements the user needs to complete authentication.

Note:  When a client (also called the agent) sends a multistep authentication request to the Authentication 
Manager server, all steps in the transaction must be completed on the same primary or replica instance. 

Note:  The RSA SecurID Authentication API does not support user password change or registration with the RSA 
SecurID Authenticate app as part of the authentication workflow. Users must perform registration and manage 
their passwords prior to initiating authentication with clients that use the API.

Processing Results from Initialize and Verify

The Initialize and Verify interfaces return an AuthNResponse JSON object. The challengeMethods element in the 
response is an array of one or more  d ata elements the server requires  to continue or complete an authentication 
request. In many cases, this array contains a single item, but authentication clients should be able to handle the 
return of multiple challenge methods and present those methods to the user. 

The API supports the following multifactor authentication and mobile methods:

 l RSA SecurID hardware and software tokens

 l RSA SecurID Authenticate Tokencode

 l Approve

 l Device Biometrics (for example, Fingerprint)

 l SMS Tokencode

 l Voice Tokencode

 l Emergency Tokencode

 l Password (primary authentication only)

Future server releases might include new challenge methodIds, and clients should be ready to present these 
new challenge methods in a dynamic manner.

A challenge method may or may not require the user to enter data, as described in the following table.

Data Required? Result

The user enters a value which is sent to the server. For example, a password 
Yes
or a new SecurID PIN.
The user confirms an authentication event for which no user response data is 
No needed. For example, the user confirms  an Approve notification on his phone, 
or the user acknowledges that he has memorized the system-generated PIN.

For elements that require the user to provide data, these mechanisms can help the client identify how the data 
should be handled:

 l Value Defined. The user enters a value that he will need to remember at a later time, such as a PIN or a 
password. It is expected that clients  r equire the user to enter the data twice and verify that both entries 
match.

Chapter 1: Getting Started with the RSA SecurID Authentication API 11

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

 l Sensitive Data. When the user enters a sensitive value, the data entry should be masked or hidden if 
possible.

The AuthenticationMethod and MethodPrompt elements contain the information the client can use to generate a 
prompt for the authentication data and to perform some lightweight verification of the user’s entry. It contains 
hints such as the minimum and maximum length of the expected data, the prompt that should be used for the 
data, and the default value, if applicable.

SSL Certificate Requirements

It is important that the client sends authentication requests  only  to trusted servers. RSA recommends that you 
configure the client to verify the server’s identity by validating that the SSL certificate presented by the server 
has been issued by a root CA certificate, trusted by the client, directly or indirectly through one or more 
intermediate CA certificates in the certificate chain.

RSA Authentication Manager generates a root CA certificate and  SSL server certificates for each primary and 
replica instance (server). The root CA is named RSA root CA for <primary-server-hostname>. Your 
company can replace the console certificates with certificates signed by a different CA. 

For the Cloud Authentication Service, use your browser to visit the Authentication API REST URL link, where you 
can view and retrieve the root CA certificate that issued the certificate presented for that link.

REST Endpoint URLs

The Authentication API supports the following REST endpoint interfaces. 

REST Endpoint URL Purpose

Initialize is the first call the client sends to the server to start the 
/mfa/v1_1/authn/initialize
authentication process.  
After Initialize succeeds, the server returns at least one 
/mfa/v1_1/authn/verify challenge method. Use Verify to provide authentication 
credentials, such as an RSA SecurID passcode, to the server.
/mfa/v1_1/authn/status Checks the status of the authentication attempt.
/mfa/v1_1/authn/cancel Explicitly cancels an initialized authentication attempt.   
For the RSA Authentication Manager server, this endpoint 
provides I18N language resources. Use to GET prompt text 
/mfa/v1_1/authn/resources
values for all prompts or for a specific prompt. Not supported by 
the Cloud Authentication Service.

Note:  SSL is required to access the endpoint URLs. 

RSA Authentication Manager uses the default port 5555. For example:  https://<fqhn>:5555/mfa/v1_
1/authn/initialize. The Cloud Authentication Service uses the default port 443. 

For the Cloud Authentication Service, add customerid.securid.com/ to each  URL. For example,  
customerid.securid.com/mfa/v1_1/authn/initialize, where customerid.securid.com is the Authentication 
Service Domain for your deployment. Your Super Admin can find the Authentication Service Domain in the Cloud 
Administration Console under Platform > Identity Routers on the Registration tab of the Identity Router 
wizard.

Chapter 1: Getting Started with the RSA SecurID Authentication API 12

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

Required Keys for REST Requests

Every  c all from the client requires a key to securely identify the authentication request. In the rsa-securid-
authenticate-api.yaml file this is the client-key.  By default, the client-key is  included in the HTTP header of 
authentication requests.  Y our Super Admin needs to generate this key and send it to you securely. 

RSA Authentication Manager Requirement

In RSA Authentication Manager, the client-key is called the Access Key. Your RSA Authentication Manager Super 
Admin generates  an Access Key when enabling the REST API interface using the Security Console. 

If the Super Admin enables  Hash-Based Message Authentication Code (HMAC) mode, the HTTP header value is 
an HMAC calculated from the Access Key, a hash of the request body, the Access ID, and other request-specific 
information. HMAC requires both the Access Key and Access ID. For more information see  "Configure the RSA 
Security Authentication API for Authentication Agents" in RSA Link.

Cloud Authentication Service Requirement

In the Cloud Authentication Service, the client_key is called the Authentication API key, which a Super Admin 
generates  using the Cloud Administration Console. For more information, see  "Add an RSA SecurID 
Authentication API Key" in RSA Link.

MethodIDs and Attributes

The following table lists the supported MethodIDs for the RSA SecurID Authentication API. 

Display name is optional. If you choose to display the name, note that you cannot change it. 

Note:  In this table, AM refers to RSA Authentication Manager and CAS refers to the Cloud Authentication 
Service.

MethodID/Attribute
Display Name Description AM CAS
Name
SECURID RSA SecurID SecurID passcode or Authenticate Tokencode X X
SECURID_NEXT_
Next Tokencode SecurID tokencode (PIN not required) X  
TOKENCODE
SecurID tokencode (PIN not required). The 
client sends this attribute in 
SECURID_NEXT_CODE Next Tokencode   X
Credential.collectedInputs. The value is the 
user's next passcode.
SECURID_NEWPIN RSA SecurID New PIN SecurID Personal Identification Number (PIN) X X
SECURID_SYSTEM_
  System-generated PIN. No value required.  X  
GENERATED_PIN
User's password for primary authentication 
PASSWORD Password   X
only. Not used in access policies.
Authenticate  RSA SecurID Authenticate Tokencode. 
TOKEN   X
Tokencode Requires the user to have a registered device.
APPROVE Approve Methods that require the user to have a 
  X
FINGERPRINT Device Biometrics registered device. FINGERPRINT may include 

Chapter 1: Getting Started with the RSA SecurID Authentication API 13

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

MethodID/Attribute
Display Name Description AM CAS
Name
additional biometric methods that require a 
registered device.
SMS_REQUEST_CODE
SMS Tokencode
SMS_VERIFY_CODE Requires the user to have a phone that can 
SMS Verify    X
receive text messages. 
SMS (Deprecated. Do not  Tokencode
use.)
VOICE_REQUEST_CODE
Voice Tokencode
VOICE_VERIFY_CODE Requires the user to have a phone that can 
Voice Verify    X
receive voice calls.
VOICE (Deprecated. Do not  Tokencode
use.)
Emergency  Generated by the administrator. Registered 
EMERGENCY_TOKENCODE   X
Tokencode device not required.

SECURID_NEW_PIN and SECURID_SYSTEM_GENERATED_PIN Attributes

for RSA Authentication Manager
These method attributes support clients using the RSA Authentication Manager  legacy ACM_RQPIN_MSG… 
structure from the C legacy UDP protocol header file.  T he server provides these attributes when a new PIN is 
required or a system-generated PIN is provided. 

Method Attribute Name Type Value

IS_SYSTEM_GENERATED_ “true” or “false.” If  “true,” the system generates the PIN 
BOOLEAN
TYPE and the valueRequired field is “false.”
System-generated PIN. This PIN may also be provided  in 
SYSTEM_GENERATED_PIN STRING
the promptArg array.
REQUIRE_ALPHANUM, REQUIRE_ALPHABETIC_ONLY, 
PIN_REQUIREMENT STRING (Enumerated) and REQUIRE_NUMERIC_ONLY. Defines the PIN 
alphanumeric character requirements.
PIN_ALPHABETIC_CHAR_
INT32 Number of alphabetic characters required.
COUNT
PIN_NUMERIC_CHAR_COUNT INT32 Number of numeric characters required.

SECURID_NEWPIN Attributes for the Cloud Authentication Service

Method Attribute
Type Value
Name
pinGeneration STRING USER_DEFINED or SYSTEM_GENERATED
pinFormat STRING NUMERIC or ALPHANUMERIC
maxPinLen STRING Maximum length, for example, "8"
minPinLen STRING Minimum length, for example, "4"
systemPin STRING System-generated PIN
Sends the PIN policy from server to client, for example, "newPinPrompt:
[maxPinLen:8, minPinLen:4, pinFormat:ALPHANUMERIC, 
newPinPrompt STRING
pinGeneration:USER_DEFINED]". This applies only when SECURID_
NEW_PIN is the next expected method (with a priority of "1").

Chapter 1: Getting Started with the RSA SecurID Authentication API 14

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

Method Attributes Returned for Initialize

The Cloud Authentication Service returns the following method attribute after the Initialize call. 

Attribute Data
Attribute Name Direction Description
Value Type
DEVICE_
NOT_
REGISTERED

DEVICE_ Method cannot be verified until the 
METHOD_NOT_APPLICABLE NOT_ String Output user registers a  d evice or method, 
CAPABLE for example, Approve.

METHOD_
NOT_
ENROLLED

Evaluating Assurance Levels and Primary Authentication Status to

Return Authentication Methods

After the Cloud Authentication Service receives an Initialize request from an authentication client, the server  
determines which authentication methods to return to the client by evaluating the following factors: 

 l Assurance level (specified in a policy or by itself). See Assurance Level Evaluation  b elow for a 
description of this process.

 l Verification of the primary authentication method. Users are challenged for primary authentication (for 
example, username and password) when they initially attempt to access the application. After primary 
authentication, the assurance level determines if additional authentication is required using RSA 
SecurID, RSA SecurID Authenticate Tokencode, Approve, Device Biometrics, SMS Tokencode, Voice 
Tokencode, or Emergency Tokencode.

The client might not require primary authentication. If it is required, the server might return different 
results depending on whether  p rimary verification succeeds. 

 l If the client's required assurance level or higher contains the primary authentication method in the list of 
methods required for additional authentication, and if that method is satisfied during primary 
authentication, the server does not return that method to the client.  

For examples of server behavior, see Scenario: Assurance level does not include the primary authentication 
method on page 17 and Scenario: Assurance level includes the primary authentication method on page 18.  

Assurance Level Evaluation

When the Cloud Authentication Service receives an authentication request, it evaluates the client's assurance 
level to determine which challenge (authentication) methods to return to the client.  Clients that are configured 
as relying parties in the Cloud Administration Console are assigned an access policy in the relying party 
settings. If an Initialize request specifies the assurance level or an access policy, that request overrides the 
configuration specified in the Cloud Administration Console. 

Assurance levels define the authentication methods required to access applications. RSA SecurID Access 
provides three assurance levels: High, Medium, and Low. Each level indicates the relative strength and security 

Chapter 1: Getting Started with the RSA SecurID Authentication API 15

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

of the authentication methods within that level. The Super Admin configures  authentication options for each 
assurance level. An option  c an be a standalone authentication method such as Device Biometrics, or it can 
combine two methods connected by AND operators, such as  SecurID Token and Approve. 

The first option listed  for an assurance level on the Assurance Levels page is presented as the default for each 
new user when he or she authenticates to an application or client assigned to that assurance level for the first 
time. A user can select another option at any time, as long as the assigned assurance level or a higher 
assurance level contains additional options that the user can complete. When a user successfully authenticates 
with an option, that option becomes the user's default for future authentications for that assurance level. 

For more information on assurance levels, see "Assurance Levels" on RSA Link at 
https://community.rsa.com/docs/DOC-53965.

Assurance Level Evaluation Steps

When the Cloud Authentication Service receive an authentication request, it performs the following evaluation: 

 1.  The server checks the assurance level assigned to the client.
 2.  The server creates a list containing  the challenge methods for the assurance level and the methods for 
all higher assurance levels. 
 3.  The server orders the challenge methods according to the assurance level configuration in the Cloud 
Administration Console, from lowest to highest, and moves the default method to the top if available.
 4.  If any duplicate methods exist, the server eliminates the duplicates.
 5.  If primary authentication is not required, the server returns the remaining methods to the client. If 
primary authentication is required, the server verifies the primary authentication method, then 
determines which methods to return to the client as shown in the following scenarios.

Assurance Level Evaluation Examples

The following table provides examples of  expected server behavior during authentication when the default 
option is available in the assigned assurance level or a higher level. The default option is moved to the top of the 
returned list of challenge methods.

Default Methods Returned

Methods Defined for
Assurance Level (Last Successful Authentication to the Client Plus
That Level
Method) Higher Levels
(SECURID AND 
(SECURID AND APPROVE) 
DEVICE BIOMETRICS) 
HIGH OR (SECURID AND DEVICE  (SECURID AND DEVICE BIOMETRICS)
OR (SECURID AND 
BIOMETRICS)
APPROVE)
(SMS TOKENCODE) 
OR 
(DEVICE BIOMETRICS) OR 
MEDIUM (SMS TOKENCODE) (DEVICE BIOMETRICS) 
(SMS TOKENCODE)
OR (SECURID AND 
APPROVE)
(SECURID AND 
APPROVE) OR 
(DEVICE BIOMETRICS) OR 
MEDIUM (SECURID AND APPROVE) (DEVICE BIOMETRICS) 
(SMS TOKENCODE)
OR 
(SMS TOKENCODE) 

LOW (APPROVE) OR  (AUTHENTICATE TOKENCODE) (AUTHENTICATE 

Chapter 1: Getting Started with the RSA SecurID Authentication API 16

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

Default Methods Returned

Methods Defined for
Assurance Level (Last Successful Authentication to the Client Plus
That Level
Method) Higher Levels
TOKENCODE) OR 
(APPROVE) OR 
(AUTHENTICATE 
(DEVICE BIOMETRICS) 
TOKENCODE)
OR 
(SMS TOKENCODE) 
(DEVICE BIOMETRICS)
(APPROVE) OR   OR (APPROVE) OR 
LOW (AUTHENTICATE  (DEVICE BIOMETRICS) (AUTHENTICATE 
TOKENCODE) TOKENCODE) OR 
(SMS TOKENCODE) 

The following table provides examples of  expected server behavior during authentication when the default 
option is not available. 

Methods Defined for Methods Returned to the Client Plus Higher

Assurance Level
That Level Levels
(SECURID  AND APPROVE) OR 
(SECURID AND APPROVE) OR (SECURID  AND 
HIGH (SECURID  AND 
DEVICE BIOMETRICS)
DEVICE BIOMETRICS)
(DEVICE BIOMETRICS) OR (SMS  (DEVICE BIOMETRICS) OR (SMS TOKENCODE) OR 
MEDIUM
TOKENCODE) (SECURID  AND APPROVE) 
(APPROVE) OR (DEVICE BIOMETRICS) OR 
LOW (APPROVE)
(SMS TOKENCODE) 

If the method list contains duplicates, the server removes the duplicate sets, as shown in the following example. 

Original Methods List Containing Duplicates Methods List After Duplicate Removal
(SECURID AND  T OKEN) OR 
(SECURID AND SMS TOKENCODE) OR (TOKEN)
(SECURID AND SMS TOKENCODE) OR (TOKEN)
(SECURID AND APPROVE) OR (SECURID AND 
DEVICE BIOMETRICS) OR (APPROVE) OR  (APPROVE) OR (DEVICE BIOMETRICS)
(DEVICE BIOMETRICS) 

If a method requires a device and the user has not registered a device, the method is included in the methods 
list marked with the METHOD_NOT_APPLICABLE attribute and the value DEVICE_NOT_REGISTERED. The user 
must register a  d evice before using this  method. 

Scenario: Assurance level does not include the primary authentication

method
When the client's assurance level does not include the primary authentication method in the list of methods 
used for additional authentication,  the following behavior occurs:  

 l If primary method verification is not required, or if  it is required and authentication succeeds, the server 
returns only the methods from the required assurance level or higher. It does not return the primary 
method.

Chapter 1: Getting Started with the RSA SecurID Authentication API 17

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

 l If  p rimary method verification is required and fails, the server adds the primary method to the list of 
methods in the assurance level and returns all methods to the client.

The following examples illustrate this behavior. In the following table, the assurance level specifies 
(DEVICE BIOMETRICS) OR (SECURID AND APPROVE).

Server Returns These Access Policy

Server Action Explanation
Methods to Client
(DEVICE BIOMETRICS) OR (SECURID  Returns only methods from the  r equired 
No primary authentication.
AND APPROVE) assurance level or higher.
Password is successfully  (DEVICE BIOMETRICS) OR (SECURID  Returns only methods from the  r equired 
verified as primary method. AND APPROVE) assurance level or higher.
(PASSWORD AND DEVICE BIOMETRICS)  The server adds Password to the list of 
Unsuccessful verification of 
OR (PASSWORD AND  methods from the required assurance 
Password as primary method.
SECURID AND APPROVE) level.

Scenario: Assurance level includes the primary authentication method

When the client's assurance level includes the primary authentication method in the list of methods required for 
additional authentication,  the following behavior occurs:  

 1.  The server attempts to validate the credential received from the client for primary authentication. 
 2.  If validation succeeds, the server removes the primary authentication method from the list of methods  in 
the required assurance level or higher and does not return that method to the client. If validation fails, 
the server adds the primary method to the list of methods in the assurance level. 
 3.  The server eliminates  any redundant methods and returns the remaining methods to the client, which 
are required to satisfy the assurance level.

The following example illustrates this behavior. In the following table, the assurance level specifies (SECURID 
AND APPROVE)  OR  (SMS TOKENCODE).

Server Returns These Access Policy

Server Action Explanation
Methods to Client
(SECURID AND APPROVE)  OR   Returns only methods from the 
No primary authentication.
(SMS TOKENCODE)  required assurance level or higher.
SECURID is counted as being 
completed and is removed from the 
Successful verification of 
list of methods from the required 
SECURID as primary  (APPROVE) OR  (SMS TOKENCODE)
assurance level or higher and the 
method
remaining methods are sent to the 
client.
SECURID is added to the list of 
Unsuccessful verification 
(SECURID AND APPROVE) OR  methods from the required assurance 
of SECURID as primary 
(SECURID AND SMS TOKENCODE) level or higher and that list is returned 
method
to the client.

Chapter 1: Getting Started with the RSA SecurID Authentication API 18

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

Chapter 2: Using the RSA SecurID Authentication API

Initialize and Verify Calls 20

Check Status Call 35

Cancel Call 38

Chapter 2: Using the RSA SecurID Authentication API 19

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

Initialize and Verify Calls

Initialize Request
The Initialize request is the first call to the server. This call starts the authentication process. 

Note:  Make sure you obtain the necessary keys  from your Super Admin. For details, see Required Keys for 
REST Requests on page 13.

When you use Initialize without subjectCredentials, the  s erver response tells the client which credentials are 
required. When you use Initialize with subjectCredentials, the Initialize request provides the server with 
credentials to be verified in advance. For more information, see Initialize with subjectCredentials on page 23.

The following graphic illustrates the relationships among the Initialize properties.

Initialize Request Example

The following snippet  s hows a sample initialize request in Java. The client provides values for the variables in 
italics. 

Note:  The client-key value is hard-coded in the  rsa-securid-authenticate-api.yaml file.

Chapter 2: Using the RSA SecurID Authentication API 20

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

ApiKeyAuth client-key = (ApiKeyAuth)mfaApi.getApiClient

().getAuthentication("client-key");

client-key.setApiKey(<api_key_from SuperAdmin>); // enter a valid api-key

MessageContext msgContext = new MessageContext();

msgContext.setMessageId(<random_message_id>); // new message id generated

by the client

Initialize initRequest = new Initialize();

initRequest.setContext(msgContext);

initRequest.setSubjectName(<user_name>); // user’s email or sAMAccountName

initRequest.setClientId(<client_id>); //client’s unique identifier

initRequest.setAssurancePolicyId(<client_policy_name>); // policy name

AuthNResponse serverResponse = mfaApi.initialize(initRequest);

Initialize Request Parameters

The Initialize request requires the following parameters.

Parameter Description Type Required?

Determines principal identity and access 
control. 
Required for 
Value for Authentication Manager: Agent name Authentication Manager.
clientId String
Value for Cloud Authentication Service: A string  Optional for the Cloud 
that will be displayed in the mobile notifications  Authentication Service.
in the User Event Monitor in the Cloud 
Administration Console.
Identifies the user account requesting the 
authentication. 

Value for Authentication Manager: User Login 
uid or alias.

For the Cloud Authentication Service, one of  the 
following values: 

subjectName  l Email attribute mapping String Required

 l SecurID Username  attribute mapping.  
For Active Directory, this is 
sAMAccountName. For other LDAP 
vendors, this is a uid. 

 l Alternate Username attribute mapping. 
For example, userPrincipalName.

assurancePolicyId Access policy name configured in the Cloud  String Optional for the Cloud 

Chapter 2: Using the RSA SecurID Authentication API 21

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

Parameter Description Type Required?

Authentication Service. 

Must specify either this 
or assuranceLevel or 
authMethodID in 
Administration Console. Obtain this name from 
request.
your Cloud Authentication Service Super 
Admin. Use this parameter if you 
want the Cloud 
Authentication Service to  
enforce an access policy 
when users authenticate.
Optional for the Cloud 
Authentication Service.

Must specify this or 
assurancePolicyId in 
request. 
Required minimum assurance level for 
authentication: LOW, MEDIUM, or HIGH Must specify either this 

assuranceLevel String or assurancePolicyId or 

Authentication methods available for each 
authMethodId in request.
assurance level are specified in the Cloud 
Administration Console. Use this parameter if you 
do not want to use 
access policies and want 
all users to authenticate 
using a specific 
assurance level.
Optional for the Cloud 
Authentication Service.

Must specify either this 
or assurancePolicyId or 
assuranceLevel in 
A supported authentication method specified in 
authMethodId String request.
MethodIDs and Attributes  on page 13
Use this parameter if you 
want all users to 
authenticate using a 
specific authentication 
method. 
Context Common authentication request context data.  Object Required
"False" (default) - Remove completed or 
Required  for the Cloud 
canceled authentication attempts  from the 
Authentication Service.
server.
keepAttempt Boolean Not implemented for 
"True" - Retain completed or canceled 
Authentication Manager. 
authentication attempts until they are removed 
The attemptID is always 
or expired. Set to "true"  if a subsequent 
removed from the server.
CheckStatus call will be made. 

Chapter 2: Using the RSA SecurID Authentication API 22

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

Parameter Description Type Required?

A completed authentication attempt is any 
attempt for which an Initialize or Verify call has 
returned a ResponseCode other than 
CHALLENGE or IN_PROCESS. 
Optional for 
Authentication Manager 
clientDetails Contains client details. Object
and the Cloud 
Authentication Service.

Note:  Do not use the Credential field versionId (string). It is ignored. 

Unsupported Parameters

Do not include authnAttemptId with the Initialize call for either server. If provided, the server ignores it and 
returns a new, random authnAttemptId  in the AuthNResponse context property.

The following table lists unsupported parameters for each server. These parameters might be supported in 
future versions of the RSA SecurID Authentication API. 

Authentication Manager 8.2 SP1 or Cloud Authentication

Parameter
Later Service
authnAttemptTimeout (number) Not supported Supported
lang (string) Not supported Not supported
sessionAttributes (NameValuePair 
Not supported Supported
array)
tenantId (string) Not supported Not supported
display (string) Not supported Not supported
assurancePolicyId (string) Not supported Supported
assuranceLevel (string) Not supported Supported
authMethodId Not supported Supported
authSchema (string) Not supported Supported

Initialize with subjectCredentials

When the client sends Initialize with subjectCredentials, it provides the server with credentials to be verified in 
advance.  W
  hen the client sends Initialize without subjectCredentials, the server returns information to the 
client indicating what credentials are required. subjectCredentials is optional for the Initialize call.

The following table describes how Initialize and subjectcredentials works when sent to the Cloud Authentication 
Service.

Client Request to the Cloud Authentication Service Results

Primary authentication is not performed or 
expected. The server requests the client to provide 
Initialize without subjectCredentials
the authentication methods required by the access 
policy.
The request includes the primary authentication 
credentials and the credentials required by the 
Initialize with subjectCredentials
access policy. If the client provides an incorrect 
primary authentication credential (for example, 

Chapter 2: Using the RSA SecurID Authentication API 23

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

Client Request to the Cloud Authentication Service Results

wrong password), the server returns a request for 
the primary method in addition to the methods 
required by the access policy.

When the client sends Initialize with subjectCredentials  to Authentication Manager,  the client provides the 
user's SecurID passcode in advance, before the server can return it as a challenge in a response. The caller can 
complete a single-step authentication without multiple round-trips to the server. If the user's token is in New 
PIN mode or requires the next tokencode to complete the authentication, calling Initialize with credentials still 
results in a CHALLENGE response.

The following graphic shows the relationships among the  p roperties for subjectCredential.

Requirements for subjectCredential

The following table describes requirements for subjectCredential.

Parameter Description Type Required?

Method to verify.

Values for Cloud Authentication Service:

PASSWORD
methodId String Yes
SECURID

Value for Authentication Manager

SECURID
A NameValue pair. The named methods are a 
subset of those given in MethodIDs and 
Attributes  on page 13.

For RSA Authentication Manager, the 
collectedInputs collectedInput name must be the same as the  Array Yes
methodId (SECURID).  T he collectedInputs value 
is the user's passcode.

For the Cloud Authentication Service, only 
SECURID or PASSWORD are accepted.

Initialize with clientDetails

Some clients, such as newer RSA authentication agents, can send Initialize with clientDetails. It provides the 
additional client information to the server for agent reporting purposes. When the client sends Initialize without 

Chapter 2: Using the RSA SecurID Authentication API 24

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

clientDetails, the server can only report partial information about the client.

The following graphic shows the relationships among the  p roperties for clientDetails.

Requirements for clientDetails

The following table describes requirements for clientDetails.

Parameter Description Type Required?

hostname Client fully qualified hostname. String Optional
version Version for the installed client. String Optional
softwareId Unique ID generated for each client installation. String Optional
The operating system on which the client is 
platform installed. The version of the operating system  String Optional
might be included.
component Installed client name. String Optional

Verify Request
Use the Verify interface to provide credential or confirmation values for challenge methods returned from a 
previous Initialize or Verify call (authnResponseCode is CHALLENGE). 

To invoke the verify call, the client does the following:

 1.  Sets the authnAttemptId field to the value returned by the server in its initialization response, in the 
context field of the verification request.
 2.  Creates a new messageId and sets it in context.
 3.  Sets the inResponseTo field to the value of messageId returned by the server, in context.
 4.  For the challenge method returned by the server, collect the user’s credentials. Create a credential 
object with user’s credentials in the collectedInputs field and method name in the methodId field. Add 
the credential object to the subjectCredentials list of the verification request. If the server generated a 
referenceID for this methodID, include the referenceID.
 5.  Invokes the verify call with a single  c redentials.

The following graphic illustrates the relationships among the Verify properties.

Chapter 2: Using the RSA SecurID Authentication API 25

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

Verify Request Example

The following example shows how to invoke verify in Java. 

// authentication attempt id returned by the server

MessageContext msgContext = new MessageContext();
msgContext.setAuthnAttemptId(serverAuthnAttemptId);

// new message id generated by the client

msgContext.setMessageId(clientNextMessageId);

// message id in the server’s last response

msgContext.setInResponseTo(serverLastMessageId);

// methodId of a challenge method returned by the

serverCredentials userCredentials = new Credentials();
NameValuePair cred = new NameValuePair();
cred.setName(expectedAttributeName);

// credential provided by the user

cred.setValue(userInput);
// methodId of a challenge method returned by the server
userCredentials.addCollectedInputsItem(cred);
userCredentials.setReferenceId(serverProvidedReferenceId)
userCredentials.setMethodId(challengeMethodName);

Verify verifyRequest = New Verify();

verifyRequest.setContext(msgContext);
verifyRequest.addSubjectCredentialsItem (userCredentials);
AuthNResponse serverResponse = mfaApi.verify(verifyRequest);

Verify Request Parameters

Property Description Type Required?

A list of credentials based on one or more of the 
subjectCredentials Array Yes
previous ChallengeMethods. 
Common authentication request context data  s ent to 
and returned by the server. The server response 
MessageContext Object Yes
contains the authentication attempt ID, which must be 
returned in subsequent calls.

Chapter 2: Using the RSA SecurID Authentication API 26

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

Verify Credential Properties

Property Description Type Required?

Method ID of the credential corresponding to the collected 
methodId inputs. Represents a challenge from a previous call. See  String Yes
Initialize and Verify Response below.
Yes  for the Cloud 
Version of the authentication method corresponding to the  Authentication 
collected inputs. This is the version ID, such as “1.0.0,” of the  Service.
versionId String
authentication method version to be verified. See Initialize and  Not implemented for 
Verify Response below.  Authentication 
Manager.
The server creates and returns a referenceId to the client. Any 
subsequent verify calls from client to poll the status of the 
method must contain the referenceId in the verify request.
Yes for the Cloud 
If a subsequent verify call for an IN_PROCESS method does not  Authentication 
contain the referenceId, the server assumes it is a new request,  Service
referenceID cancels the current inprocess method, and initiates a new one,  String
Not implemented for 
resulting in a new referenceId. From server to client, the server 
Authentication 
sets the referenceId in the method's 
Manager.
AuthenticationMethodVersion.referenceId field. From client to 
server, the client is expected to set the referenceId in the 
method's Credential.referenceId field.
NameValuePair objects containing the input obtained from the  
collectedInputs Array Yes
user that is verified by the server.

Verify Credential.collectedInputs (NameValuePair) Properties

Property Description
Name must be the same as the credential methodId. This is the method ID of a challenge from a 
name
previous call. For more information, see Initialize and Verify Response below.
The credential value entered by the end user, if applicable. This is the collected input value for 
value AuthenticationMethodVersion with a valueRequired property of “true.” This can be null and any 
value must be ignored if no value is required.

Initialize and Verify Response

The Initialize and Verify calls return an AuthNResponse. The response indicates if the credentials are valid and if 
the user must provide  additional authentication credentials.

AuthNResponse Properties

AuthNResponse returns the following information.  

Type
Parameter Description

Each element of this array corresponds one-to-one with a credential 
credentialValidationResults Array
provided in the Initialize or Verify call. 
Response status for the entire Initialize  c all. For example, the 
attemptResponseCode String
credentialValidationResults may indicate success, but this value may 

Chapter 2: Using the RSA SecurID Authentication API 27

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

Type
Parameter Description

be CHALLENGE if additional authentication is required. “SUCCESS” 
indicates that the request is complete and no further Verify calls are 
required.
attemptReasonCode A reason code for the entire Initialize request.  String
If the attemptResponseCode is CHALLENGE, this contains the 
authentication requirements that must be completed. For a list of 
challengeMethods challenge methods, see MethodIDs and Attributes  on page 13. Object

If the attemptResponseCode is SUCCESS this parameter is empty. 

The following parameters must be returned:

 l context (MessageContext)
 l challengeMethods (ChallengeMethods)

The server returns the MessageContext.authnAttemptID in the Initialize response.  T he client must provide this 
value in each subsequent response.  Each server response also contains a random message ID 
(MessageContext.messageId). RSA recommends that the client validate the MessageContext.inResponseTo 
property returned by the server as specified in the rsa-securid-authenticate-api.yaml file. This value should 
correspond to the messageId that the client provides in the prior Initialize or Verify call context property.

The following graphic illustrates the relationships among the AuthNResponse properties.

AuthNResponse credentialValidationResults Properties

If the Initialize call contains credentials, the server response must indicate if the credentials are valid. This table  
describes the content of the credentialValidationResults  that can be returned from the Initialize call.

Chapter 2: Using the RSA SecurID Authentication API 28

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

Property Description Value

See 
A method ID to indicate that the credential validation results  MethodIDs 
methodId contain a result from verification, for example, from verifying a and 
SecurID passcode authentication. Attributes  
on page 13
SUCCESS - Authentication is completed successfully. 

FAIL - Unsuccessful authentication. User credentials were 
incorrect.
SUCCESS 
IN_PROCESS - Authentication is not complete and is in 
process. For some out of band (PUSH) methods, the client  FAIL 
must retry with a Verify call. A Reference ID is returned in the  ERROR
method response. Subsequent verify calls must pass this ID 
methodResponseCode CHALLENGE
as part of the credential.

CHALLENGE - The method is incomplete and method(s) in the  IN_
challengeMethods are required. For example, the  PROCESS

challengeMethods may contain data requiring the client to  ERROR 
perform a secondary challenge. 

ERROR - An error occurred in processing the client request. 
The authnAttemptId is no longer valid. 
methodReasonCode Details about the result of the methodResponseCode. String
Authentication Manager returns no authentication attributes.

The Cloud Authentication Service may return an array of 
attributes resulting from a successful authentication. 

authnAttributes Attributes are specific to the authentication type and request.   
For example, this may contain RADIUS attributes or data to 
permit additional exchanges such as an offline data download 
ticket. This will only be optionally provided if the 
methodResponseCode is "SUCCESS".

AuthNResponse challengeMethods and Related Properties

The challengeMethods describe information the user must  p rovide or confirm to complete or continue the 
authentication. The client must use elements from the challengeMethods to generate an authentication user-
interface.

An exception is when the caller provides credentials to the Initialize interface and no further credentials may be 
needed. In this case, the challengeMethods must be empty. The server may respond with CHALLENGE even 
when correct credentials are provided with the Initialize call. For example, the user’s passcode may be correct, 
but the next tokencode may be required to complete the authentication.

Challenge methods are described in MethodIDs and Attributes  on page 13.

The following graphic shows the relationships among the ChallengeMethods properties. 

Chapter 2: Using the RSA SecurID Authentication API 29

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

In the following graphic, ChallengeMethods returns two ChallengeMethodSets, requiring the client to satisfy 
either two methods (Password and Approve) or  one method (SecurID Token), as determined by  the assurance 
level for the access policy being used.

AuthNResponse Content Returned By Initialize and Verify

The following sections describe  AuthNResponse content that may be returned from the Initialize and Verify 
calls. Some section titles use an ellipsis to abbreviate the complete path to the element in the hierarchy. The 
outermost property contains an array of ChallengeMethodSet objects. 

Any one of these challenge methods can be satisfied to complete the authentication.

AuthNResponse challengeMethods (ChallengeMethods) Properties

Property Description Values

Indicates how the user must be challenged to complete  An array of ChallengeMethodSet containing 
challenges
authentication. a single item.

AuthNResponse challengeMethods.challenges Properties

All  authentication methods returned in the challengeMethodSet must be satisfied to complete  authentication.

Property Values Description

An array of AuthenticationMethod  AuthenticationMethod  indicates what data the user must 
requiredMethods
containing a single item. provide to complete authentication.

AuthNResponse challengeMethods...requiredMethods Properties

AuthenticationMethod returns details about data the user must provide to successfully complete authentication.

Chapter 2: Using the RSA SecurID Authentication API 30

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

Property Values Description

See MethodIDs and  Method IDs associated with the data the user must provide to 
methodId
Attributes  on page 13. complete  authentication.
The display name of the authentication method. If the 
See MethodIDs and 
displayName authentication method does not contain a displayName, the 
Attributes  on page 13.
methodId displays.
Used by the Cloud Administration Console to indicate to the client 
the order or priority to use when processing methods. One is the 
highest priority. Higher numbers indicate lower priority. This value 
priority Number. The default is 50. helps ensure that users respond to time-sensitive methods first. 
For example, SecurID Next Tokencode and New PIN modes have a 
priority of 1. When a method does not apply the user, it is assigned 
a priority of 100.
An array of 
AuthenticationMethodVersion provides details on the data the user 
versions AuthenticationMethodVersion 
must provide to complete authentication.
containing a single item.

The server may return the priority, but because the versions array contains a single item, the client can ignore 
this property. 

AuthNResponse challengeMethods...versions Properties

AuthenticationMethodVersion returns details about data the user must provide to complete authentication.

Property Values Description

versionId “1.0.0” The version of the authentication method.
Array of 
NameValuePair. See Provided by the server for the applicable authentication methods, for 
methodAttributes MethodIDs and  example, SECURID_NEW_PIN or SECURID_SYSTEM_GENERATED_PIN 
Attributes  on  methods.
page 13.
True indicates  the user must enter a value. This value should be False 
for  methods  that do not require the user to enter a value, for example, 
valueRequired True or False
the Approve method or if Authentication Manager is generating a 
SECURID_SYSTEM_GENERATED_PIN. 
MethodPrompt provides details on how to prompt the user to obtain the 
prompt MethodPrompt
data that must be provided to complete authentication.

The following graphic illustrates the relationships among the AuthenticationMethodsVersion properties.

Chapter 2: Using the RSA SecurID Authentication API 31

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

AuthNResponse challengeMethods...prompt Properties

AuthenticationMethodVersion provides data to the client on how the  user should be prompted. The prompt 
(MethodPrompt) object is returned. 

Initialize and Verify Attempt Response Codes

The following table describes attemptResponseCodes and attemptReasonCodes for the Initialize and Verify 
interfaces. These response codes are provided in two places:

 l In the top level of the AuthNResponse for the entire request.
 l In the  c redentialValidationResult for each specific credential.

attemptRespon attemptReaso conte challengeMe credentialValidatio

Description
seCode nCode xt thods nResults
Possible 
reasons: 

VERIFY_
The server cannot handle the  MISSING_
Undefi
ERROR initialize request. The request  ATTEMPT_OR_ Undefined Undefined
ned
is malformed or invalid. MESSAGE_ID

No server cache 
found for 
attemptId: 

Chapter 2: Using the RSA SecurID Authentication API 32

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

attemptRespon attemptReaso conte challengeMe credentialValidatio

Description
seCode nCode xt thods nResults
<xxx>

Corrupt 
message chain. 
Got a 
inResponseToI
D as: <xxx>, 
but expected: 
<yyy>
Possible 
Access denied for this  Populat Contains 
reasons: Empty or populated 
FAIL request. The user might have  ed with challenge 
ATTEMPT_ with results.
entered the wrong credential. IDs. sets.
TIMED_OUT
The authentication request is  NO_ Populat
Empty or populated 
SUCCESS complete without further  CHALLENGES_ ed with Empty
with results.
challenge. REMAINING IDs.
Possible 
reasons: 

METHOD_
VERIFY_
FAILED_RETRY 

METHOD_
Populat Contains 
The authentication request  VERIFY_ Empty or populated 
CHALLENGE ed with challenge 
requires further challenge. ERROR_RETRY  with results.
IDs. sets.
METHOD_
VERIFY_
CHALLENGE   

METHOD_
VERIFY_IN_
PROCESS 
The server initiated the 
authentication request, but 
the request is not completed. 
Contains 
For such methods, server 
challenge 
creates and returns a 
sets, 
"referenceId" to the client. 
Populat including the 
Any subsequent/verify calls  VERIFICATION_
IN_PROCESS ed with current IN_ Populated with result.
(from client) to poll the status  PENDING
IDs PROCESS 
of such method must contain 
method with 
the referenceId in the verify 
its 
request. 
referenceId.
If a subsequent/verify call 
(for a IN_PROCESS method) 

Chapter 2: Using the RSA SecurID Authentication API 33

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

attemptRespon attemptReaso conte challengeMe credentialValidatio

Description
seCode nCode xt thods nResults
does not contain the 
referenceId, the server 
assumes it is a new request, 
cancels the current in-
process method, and initiates 
a new one, resulting in a new 
referenceId. From server to 
client, the referenceId is set 
by the server in the method's 
AuthenticationMethodVersion.
referenceId field. From client 
to server, the client is 
expected to set the 
referenceId in the method's 
Credential.referenceId field.

Chapter 2: Using the RSA SecurID Authentication API 34

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

Check Status Call

Check Status Request

There are two ways to check the status of the current authentication attempt: 

 l From the server’s response to the previous verify call
 l By calling status explicitly

Response to Verify

The server’s response to the verification request contains both the validation results of the last call to verify and 
the remaining challenge methods of the current authentication attempt.

The validation results contain the response code of the current authentication attempt and a list of results of the 
method verification from the last verify call. Each method verification result contains the method name and the 
response code that indicates either success or failure.

The remaining challenges are what is required of the client to complete the current authentication attempt. In 
the case of a successful authentication attempt, there should be no remaining challenge method.

Explicit Call to Check Status

The client can make an explicit call to check the status of the current authentication attempt. The response 
contains:

 l Response code of the current authentication attempt (success or challenge)
 l Subject name
 l Policy ID
 l List of the method names that have successfully completed during this attempt. 

Unlike the response to verify, the response of the status call does not include the list of the remaining challenge 
methods or the list of methods that have failed in the current attempt.

The following graphic illustrates the relationships among the Check Status properties.

Check Status Example

The following example shows how to use Check Status in Java: 

CheckStatus statusRequest = new CheckStatus();

statusRequest.setAuthnAttemptId(attemptId); // the current
authentication attempt id is all it needs
AuthNStatusResponse serverStatusResponse = mfaApi.status
(statusRequest);

Chapter 2: Using the RSA SecurID Authentication API 35

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

Check Status Parameters

Parameter Description Type Required?

The authentication ID provided as a 
result of an initialize call. This call may 
authnAttemptId string Required
have been performed in another client 
or session.
Requests to remove the authentication 
removeAttemptId attempt ID as a part of this "check"  boolean Optional
call. Default is true.

Check Status Response

The following graphic illustrates the relationships among the AuthNStatusResponse properties.

AuthNStatusReponse Properties

Element Description Type

A response status code representation.

SUCCESS - The authentication completed successfully. 

IN_PROCESS - The authentication is not complete but remains 
in-process. For some out-of-band (PUSH) methods, the client 
must retry with a verify call. For the Approve method the 
server receives IN_PROCESS status, and APPROVE_CHECK as 
method in challengeMethods field.
attemptResponseCode String
CHALLENGE - The method is incomplete requires method(s) in 
the challengeMethods. For example, the challengeMethods 
may contain data requiring the client to perform a secondary 
challenge. 

ERROR - A technical error occurred in processing the client 
request. The authnAttemptId is no longer valid. 

FAIL - The credentials presented were incorrect. The user 

Chapter 2: Using the RSA SecurID Authentication API 36

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

Element Description Type

failed authentication.
Specific details about the circumstances of result of the action 
attemptReasonCode String
requested.
subjectName Name of the user that completed the authentication. String
authnPolicyId Name of the policy ID provided with the initialize call. String
Not supported and is always empty, even if the client had 
sessionAttributes Array
passed sessionAttributes during Initialize.
An array of methodID strings of methods successfully  Array of 
successfulMethods
completed in association with this authentication. methodID strings.
Date and time when this authentication attempt expires.

This is the local time for the Authentication Manager server or 
the Cloud Authentication Service together with a time zone 
attemptExpires String
offset for UTC time. 

No  verify or status calls can be made after this time (or if the 
status check requests deletion of the attempt).

Chapter 2: Using the RSA SecurID Authentication API 37

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

Cancel Call

Cancel Request
The client may send a Cancel request to cancel an authentication attempt at any point after the initialize request 
has been sent.  T he  Cancel request must provide  the authnAttemptId string it received from the initialize 
response. After a user's authentication attempt has been canceled, all previous authentication results are 
discarded. The user must restart the authentication process. 

The following graphic illustrates the relationships among the Cancel request properties.

Cancel Request Example

The following example shows how a Cancel call provides the authnAttemptId  to cancel an authentication 
attempt.

{
"authnAttemptId":"106dd91f-22ab-4eec-92c8-a1a5e01b0da3",
"reason":"USER_ACTION"
}

Cancel Parameters

Parameter Description Type Required?

The authentication ID provided as a 
result of an initialize call. This call may 
authnAttemptId String Required
have been performed in another client 
or session.
Requests to remove the authentication 
removeAttemptId attempt ID as a part of this "cancel"  Boolean Optional
call. Default is true.
 l USER_ACTION: The user  
intentionally canceled the 
authentication attempt.

reason  l TIME_OUT: The client  String Optional

internally timed out and 
canceled the attempt.

Default is USER_ACTION.

Chapter 2: Using the RSA SecurID Authentication API 38

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

Chapter 3: Sample Clients for the RSA SecurID 
Authentication API

Sample Client Overview 40

Build Sample Clients for RSA Authentication Manager 40

Chapter 3: Sample Clients for the RSA SecurID Authentication API 39

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

Sample Client Overview

Sample client code for RSA Authentication Manager is available in the Extras.zip file in the directory \RSA
SecurID Authentication API.

This code demonstrates dynamically generating a Java client interface library from the OpenAPI YAML interface 
definition. It includes two sample programs that use the generated interface to perform authentication.

The first example calls the interface and generates user prompts based on the challenges returned by the 
server. It continues to prompt the user for challenges until the authentication succeeds or the authentication 
attempt is halted. This example contains Java examples of generating the HMAC HTTP header value, if that 
option is enabled at the server. It also configures the SSL client to validate the server's host SSL certificate.

The second example is a simplified example that provides a SecurID tokencode with the Initialize call to perform 
a single-step SecurID authentication.

Software Requirements
The sample client has the following requirements: 

 l Java SDK 1.7.0 with unlimited strength crypto extension
 l Apache Maven 3.0.4 or later

Maven must be configured to connect to a repository with the io.swagger:swagger-codegen-maven-plugin 
and associated OpenAPI dependencies. The default online repositories contain these components and their 
dependencies.

You must also change your PATH environment variable so that both the Java SDK and Maven are included.

Files and Directories

The sample client contains the following files and directories: 

 l pom.xml. Top-level Maven build file. Builds the client library and both client samples.
 l README.TXT. Instructions for compiling and running the sample client.
 l rest-java-client/. Dynamically constructs a Java client from the schema.
 l rest-test-auth/. Sample interactive console-based authentication client. This client supports using the 
Access ID and Access Key.
 l rest-test-cli/. Sample command-line authentication client.
 l openapi-yaml/rsa-securid-authenticate-api.yaml. Contains the OpenAPI interface definition source 
(YAML) file. This contains details on the endpoints and JSON objects. Download the most recent file from 
RSA Link at https://community.rsa.com/docs/DOC-71396.

Build Sample Clients for RSA Authentication Manager

The following procedure generates and compiles the client library, builds the test authentication client, and 
builds the command line client for two sample clients that call RSA Authentication Manager.

Chapter 3: Sample Clients for the RSA SecurID Authentication API 40

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

Before you begin

 l Meet the software requirements and obtain the necessary files. See  Sample Client Overview on the 
previous page.
 l The Authentication Manager Super Admin must do the following: 
 l Provide the root certificate.
 l Add a RESTful authentication agent to Authentication Manager
 l Enable the API.
 l Provide the  Access Key value. 

Procedure
 1.  Change to the directory where you extracted the OpenAPI REST Interface Source Example.
 2.  From the top level, run:

mvn clean install

 3.  You need to  g enerate or regenerate the  J  ava Client library, rest-java-client. Change to the rest-java-

client directory:

cd rest-java-client

 4.  From the top level, run:

mvn clean install

Note:  Warnings, such as "[main] WARN io.swagger.codegen.DefaultCodegen - escape..." can be safely 
ignored.   

The library is located at target/rest-java-client-version.jar, where version is the RSA Authentication 
Manager version.

The pom.xml file in this directory also generates HTML documentation from the YAML file. This is 
available in rest-java-client/target/generated-sources/swagger/index.html. 

The pom.xml file also has a commented-out example of how a C++ library can be created.

 5.  Run the test authentication client, rest-test-auth. Type:

cd rest-test-auth/target

java -jar rest-test-auth-jar-with-dependencies.jar

 6.  Run the single-step, command-line authentication client, rest-test-cli. Type:

cd rest-test-cli/target

java -jar rest-test-cli-jar-with-dependencies.jar user passcode accesskey [ server | server-

url ]

Where:

user. The user ID to be authenticated

passcode. The passcode to use for authentication.

Chapter 3: Sample Clients for the RSA SecurID Authentication API 41

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

accesskey. The Access Key provided by the server when the REST interface is enabled.

server. (Optional) Server hostname or IP address for default URL.

server-url. (Optional) Authentication service URL.

A property "authenticate.debug" can be set to "true" to enable debugging. For example, type:

java -Dauthenticate.debug=true -jar rest-test-cli-jar-with-dependencies.jar ...

Chapter 3: Sample Clients for the RSA SecurID Authentication API 42