RSA SecurID Access RSA SecurID Authentication API Developer's Guide

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
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
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
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
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
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

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.

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.

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.

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.

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

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").

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

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

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.

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 2: Using the RSA SecurID Authentication API
Initialize and Verify Calls 20
Check Status Call 35
Cancel Call 38

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.

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


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
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
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
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.


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
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,

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.

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

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.

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.

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.

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

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.

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.

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.


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.

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.

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:


Description
<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)


Description
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.

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);

Check Status Parameters

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

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).

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

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 3: Sample Clients for the RSA SecurID
Authentication API
Sample Client Overview 40
Build Sample Clients for RSA Authentication Manager 40

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.

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.

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 ...

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

Caricato da

Informazioni sul documento

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

RSA SecurID Access RSA SecurID Authentication API Developer's Guide

Caricato da

Copyright:

Formati disponibili

RSA SecurID Authentication API

Note on Encryption Technologies

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

Chapter 2: Using the RSA SecurID Authentication API 19

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

About This Guide

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

RSA SecurID Access Support and Service

Support for RSA Authentication Manager

Support for the Cloud Authentication Service and Identity Routers

RSA Ready Partner Program

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

RSA SecurID Authentication API Overview

RSA SecurID Access Services

RSA SecurID Authentication API Definition File

Authentication Process Flow

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

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

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

Processing Results from Initialize and Verify

Data Required? Result

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

SSL Certificate Requirements

REST Endpoint URLs

REST Endpoint URL Purpose

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

Required Keys for REST Requests

RSA Authentication Manager Requirement

Cloud Authentication Service Requirement

MethodIDs and Attributes

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

SECURID_NEW_PIN and SECURID_SYSTEM_GENERATED_PIN Attributes

Method Attribute Name Type Value

SECURID_NEWPIN Attributes for the Cloud Authentication Service

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

Method Attributes Returned for Initialize

Evaluating Assurance Levels and Primary Authentication Status to

Assurance Level Evaluation

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

Assurance Level Evaluation Steps

Assurance Level Evaluation Examples

Default Methods Returned

LOW (APPROVE) OR (AUTHENTICATE TOKENCODE) (AUTHENTICATE

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

Default Methods Returned

Methods Defined for Methods Returned to the Client Plus Higher

Scenario: Assurance level does not include the primary authentication

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

Server Returns These Access Policy

Scenario: Assurance level includes the primary authentication method

Server Returns These Access Policy

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

Chapter 2: Using the RSA SecurID Authentication API 19

Initialize and Verify Calls

Initialize Request Example

Chapter 2: Using the RSA SecurID Authentication API 20

ApiKeyAuth client-key = (ApiKeyAuth)mfaApi.getApiClient

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

Initialize initRequest = new Initialize();

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

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