RSA SecurID integrations

PingFederate Authentication API Support

The PingFederate Authentication API provides access to the current state of the authentication flow as a user steps through the PingFederate authentication policy. Learn more in PingFederate authentication API in the PingFederate documentation.

To integrate the RSA SecurID IdP Adapter into your authentication flow, configure your application based on the information in this section.

You can also explore the process using the PingFederate Authentication API Explorer. Learn more in Exploring the Authentication API in the PingFederate documentation.

Models, objects, and error codes

When using the RSA SecurID Integration Kit through the PingFederate Authentication API, the adapter uses the following state models, action models, objects, and error codes.

State models

SECURID_NEXT_TOKENCODE_REQUIRED

State details
Response model
authFailed (boolean)

Specifies whether the current attempt is the result of a failed authorization attempt.

additionalErrorInfo (string)

Additional error info if the current attempt resulted in failed authorization.

Actions

  • checkNextTokencode

  • cancel

Description

The next tokencode is required for authentication.

SECURID_NEXT_CODE_REQUIRED

Relevant only when the Authentication Manager is integrated with the Cloud Authentication Service.
State details
Response model
authFailed (boolean)

Specifies whether the current attempt is the result of a failed authorization attempt.

additionalErrorInfo (string)

Additional error info if the current attempt resulted in failed authorization.

Actions

  • checkNextTokencode

  • useAlternateMethod

  • cancel

Description

The next tokencode is required for authentication.

SECURID_TOKEN_REQUIRED

Relevant only when the Authentication Manager is integrated with the Cloud Authentication Service.
State details
Response model
authFailed (boolean)

Specifies whether the current attempt is the result of a failed authorization attempt.

additionalErrorInfo (string)

Additional error info if the current attempt resulted in failed authorization.

Actions

  • checkTokencode

  • useAlternateMethod

  • cancel

Description

The SecurID Authenticate OTP is required for authentication.

SECURID_REAUTHENTICATION_REQUIRED

State details
Response model

There is no model for this state.

Actions

  • checkPasscode

  • useAlternateMethod

  • cancel

Description

A passcode is required for reauthentication.

SECURID_SYSTEM_PIN_RESET_REQUIRED

State details
Response model
pin (string)

A new pin the system generated for the user.

Actions

  • continue

  • useAlternateMethod

  • cancel

Description

Generates a new pin for the user.

SECURID_CREDENTIAL_REQUIRED

State details
Response model
username (string)

The username used in first-factor authentication.

remainingTries (integer)

The number of tries left.

allowUsernameEdits (boolean)

The username isn’t editable if the adapter is being used in second-factor authentication.

authFailed (boolean)

Specifies whether the current attempt is the result of a failed authorization attempt.

resetFailed (boolean)

Specifies whether this attempt is the result of a failed pin reset attempt.

Actions

  • checkCredential

  • validatePasscode

  • useAlternateMethod

  • cancel

Description

The SecurID credential is required for authentication.

SECURID_USER_PIN_RESET_REQUIRED

State details
Response model
pinMinLength (integer)

The minimum length needed for the pin.

pinMaxLength (integer)

The maximum length needed for the pin.

pinAlphabeticCharCount (integer)

The minimum number of letters needed for the pin.

pinNumericCharCount (integer)

The minimum number of numbers needed for the pin.

pinAlphaNumeric (boolean)

Specifies whether the pin can be alphanumeric.

pinResetMessage (string)

Pin reset requirement.

authFailed (boolean)

Specifies whether this attempt is the result of failed authorization attempt.

Actions

  • resetPin

  • useAlternateMethod

  • cancel

Description

The user needs to reset the pin.

SECURID_CAS_CHALLENGE_METHOD_REQUIRED

State details
Response model
challengeMethodIds (array) (deprecated)

The method IDs of challenge methods as received from Cloud Authentication Service.

challengeMethodIds was deprecated in the 4.0.1 release, but is still usable. In this case, deprecated just means that you can switch to challengeMethods when you want to find more information about the challenge method.
challengeMethods (array[ChallengeMethodInfo])

List of objects containing challenge method details as received from Cloud Authentication Service. The adapter supports the APPROVE, SECURID and TOKEN authentication methods only.

authFailed (boolean)

Specifies whether the previous auth attempt failed.

resetFailed (boolean)

Specifies whether the previous pin reset attempt failed.

authenticationMethod (AuthenticationMethod)

You can find more information in the AuthenticationMethod object table.

authenticationMethodVersion (AuthenticationMethodVersion)

You can find more information in the AuthenticationMethodVersion object table.

challengeMethodInfo (ChallengeMethodInfo)

You can find more information in the ChallengeMethodInfo object table.

challengeMethodSet (AuthenticationMethodSet)

You can find more information in the AuthenticationMethodSet object table.

methodPrompt (MethodPrompt)

You can find more information in the MethodPrompt object table.

nameValuePair (NameValuePair)

You can find more information in the NameValuePair object table.

Actions

  • selectChallengeMethod

  • cancel

Description

The user needs to select a Cloud Authentication Service challenge method.

SECURID_CAS_APPROVE_METHOD_PENDING_VERIFICATION

State details
Response model
responseCode (string)

The response status code of the Approve method authentication request.

reasonCode (string)

The reason status code of the Approve method authentication request.

selectionCode (string)

The optional selection code needed to approve Selection-based Approve requests.

Actions

  • poll

  • useAlternateMethod

  • cancel

Description

The SecurID Cloud Authentication Service Approve method request has been initiated and is pending verification.

Action models

cancel

Action details
Request model

There is no model for this action.

Description

Cancels the current operation.

checkNextTokencode

Action details
Request model
tokencode (string) (required)

The tokencode used for authentication.

Description

Wait until the tokencode changes, then enter the next tokencode.

checkCredential

Action details
Request model
username (string) (required)

Username for authentication.

passcode (string)

Passcode for authentication

The passcode field was deprecated in the 4.0 release. In this context, deprecated just means that passcode is now an optional field when using the checkCredential action. However, best practice is to use the validatePasscode action instead.
Errors

  • Error: VALIDATION_ERROR

    ErrorDetail: USERNAME_REQUIRED, INVALID_USERNAME

Description

Authenticate using your SecurID credential.

checkPasscode

Action details
Request model
passcode (string) (required)

Passcode used for authentication.

Description

Reauthenticate using the passcode. Wait until the passcode changes, then enter the next passcode.

checkTokencode

Action details
Request model
tokencode (string) (required)

The tokencode used for authentication.

Description

Enter the SecurID Authenticate OTP code.

continue

Action details
Request model

There is no model for this action.

Description

Continue the current operation.

poll

Action details
Request model

There is no model for this action.

Errors

  • Error: VALIDATION_ERROR

  • Error: REQUEST_ERROR

Description

Poll for the status of the Approve method request.

resetPin

Action details
Request model
newPin (string) (required)

The new pin used for authentication.

confirmPin (string) (required)

Confirm the new pin used for authentication.

Errors

  • Error: VALIDATION_ERROR

    ErrorDetail: PIN_MISMATCH, INVALID_PIN

Description

Reset the pin used for getting passcode.

selectChallengeMethod

Action details
Request model
input (string)

The challenge method to proceed with authentication. Supported methods include SECURID, APPROVE, and TOKEN.

Errors

  • Error: VALIDATION_ERROR

    ErrorDetail: UNEXPECTED_METHOD

Description

Select the challenge method.

useAlternateMethod

Action details
Request model

There is no model for this action.

Errors

  • Error: VALIDATION_ERROR

  • Error: INVALID_REQUEST

Description

Use an alternate authentication method.

validatePasscode

Action details
Request model
passcode (string) (required)

The passcode used for authentication.

Description

Authenticate using the passcode.

Objects

AuthenticationMethod object

Object details
Parameter Name Type Description

methodId

String

The ID of the authentication method.

displayName

String

The authentication method’s name, as displayed to the user.

priority

Integer

The authentication method’s priority.

versions

An array of AuthenticationMethodVersion objects.

The versions associated with this authentication method.

AuthenticationMethodVersion object

Object details
Parameter Name Type Description

versionId

String

The ID of the authentication method version.

methodAttributes

An array of NameValuePair objects.

The attributes associated with this authentication method version.

valueRequired

Boolean

Indicates whether the authentication method version must be specified.

referenceId

String

The ID used to refer to the authentication method.

prompt

A MethodPrompt object.

The prompts associated with this authentication method version.

ChallengeMethodInfo object

Object details
Parameter Name Type Description

methodId

String

Specifies the method to verify.

methodPromptDefaultText

String

Provides a text prompt for the user to collect the data that must be provided to complete authentication.

methodAvailable

Boolean

Indicates whether the method is available. The value is false until the user registers a device or method.

challengeMethodSet

A ChallengeMethodSet object.

A ChallengeMethodSet object, as received from RSA Authentication Manager.

You can find internal details in the RSA Authentication API Developer’s Guide.

ChallengeMethodSet object

Object details
Parameter Name Type Description

methodSetId

String

The ID of the ChallengeMethodSet object received from RSA Authentication Manager.

requiredMethods

An array of AuthenticationMethod objects.

The methods that can be used to complete the authentication challenge.

MethodPrompt object

Object details
Parameter Name Type Description

promptResourceId

String

The prompt ID.

defaultText

String

The text displayed to the user regarding the data that must be collected to complete authentication.

formatRegex

String

The Regex format of the prompt.

defaultValue

String

The default method.

valueBeingDefined

Boolean

Indicates whether the user must enter a value.

sensitive

Boolean

Indicates whether the prompt requires sensitive information.

minLength

Integer

The minimum number of characters the user’s response must contain.

maxLength

Integer

The maximum number of characters the user’s response can contain.

promptArgs

Array

The prompt arguments.

subjectNameRequired

Boolean

Indicates whether the subject name is required.

NameValuePair object

Object details
Parameter Name Type Description

name

String

The attribute name.

value

String

The attribute value.

dataType

String

The type of data associated with the attribute value.

Error codes

The PingFederate Authentication API returns an error code if the call flow state hasn’t reached a dead end and the user can still authenticate with a device.

Top level error codes

Error code details
Error code Message HTTP status

VALIDATION_ERROR

One or more validation errors occurred.

400

REQUEST_FAILED

The request couldn’t be completed. There was an issue processing the request.

400

INVALID_REQUEST

The request was malformed or invalid.

400

Detail level error codes

Error code details
Error code Message Parent code

USERNAME_REQUIRED

Username is required.

VALIDATION_ERROR

INVALID_USERNAME

Username isn’t necessary for two-factor authentication.

VALIDATION_ERROR

PIN_MISMATCH

The two entered pins don’t match.

VALIDATION_ERROR

INVALID_PIN

The entered pin is invalid.

VALIDATION_ERROR

UNEXPECTED_METHOD

The provided authentication method is invalid, unavailable, or the adapter doesn’t support it.

VALIDATION_ERROR