Authenticate with On-Demand Authentication (ODA) using REST API authentication on RSA Authentication Manager 8.x

[#1]

Article Number

000038745

Applies To

RSA Product Set: SecurID
RSA Product/Service Type: Authentication Manager
RSA Version/Condition: 8.2.1.x, 8.3.x, 8.4.x
 

Issue

This article explains how to use REST API calls to authenticate with On-Demand Authentication (ODA) for RSA Authentication Manager 8.x.

Task

This article covers steps on how to authenticate with On-Demand Authentication (ODA) using the REST API, using the steps below:

1. Enable REST API authentication.
2. Enable ODA on the RSA Authentication Manager.
3. Confirm that the user is enabled for ODA and has an email address or mobile number.
4. Create an agent record in the Security Console (Access > Authentication Agent > Add New).
5. Test authentication using ODA on the Self-Service Console.
6. Use the postman or any REST API client to do the calls.
7. Initialize or verify requests to the RSA Authentication Manager.

Resolution

1. Enable the REST API authentication:
   1. Connect to the primary RSA Authentication Manager Security Console a as super admin user.
   2.  Go to Setup > System Settings > RSA SecurID Authentication API.
   3. Check the box to Enable Authentication API.
   4. Note the values for the Access ID and Access Key.
   5. You can change the value for the communication port number to any free port.

Image description

2. Go to Setup > System settings > On-demand Tokencode delivery.

• Configure email or SMS, depending on the deployment configuration.
• If you select email,
  1. Configure SMTP under Setup > System Settings > SMTP.
  2. Select the primary.
  3. Add the SMTP configuration information.
  4. Test email 
• If you use SMS,
  1. Confirm that you have configured the SMS provider configuration.
  2. Test with one mobile number.

Image description

3. Confirm that the user has an email address or mobile number assigned.
4. Create an agent for the API (Access > Authentication Agent > Add New).
5. Add any name in the hostname field. Ensure that the same name is used in the REST API call.

Image description

6. Log in to the internal or external Self-Service Console to test ODA for your user.
7. Download the postman and disable SSL (File > Settings > Disable SSL certificate verification).

For more details about the basic authentication calls for RSA SecurID software or hardware tokens, see article 000035143 - How to set up the REST RSA SecurID Authentication API for Authentication Manager 8.2 SP1.


The first call is to initialize. Use Initialize with SubjectCredentials.

Request

POST: https://<AM_FQDN>:5555/mfa/v1_1/authn/initialize

Headers

client-key: Access-key 
content-type: application/json

Body (raw)

{
    "clientId": "<Agent_Name>",
    "subjectName": "<USERID>",
    "subjectCredentials": [
        {
            "methodId": "SECURID",
            "collectedInputs": [
                {
                    "name": "SECURID",
                    "value": "<ODA_PIN>"
                }
            ]
        }
    ],
    "context": {
        "authnAttemptId": "",
        "messageId": "test5213021196242",
        "inResponseTo": ""
    }
}

Where, 

• ClientID is the name of the agent that is created in step 4.
• SubjectName is the user ID of the test user.
• Value is the ODA_PIN of the user after being changed on the Self-Service Console.
• methodId is the authentication request type.
• SECURID is for SecurID passcode or Authenticate Tokencode.
• messageID: This value can be anything.

This request responds back with body which puts the token into Next Tokencode Mode, which is the same tokencode that is used for the ODA request.

Response (raw) 

{
    "context": {
        "authnAttemptId": "651ee05a-f573-458b-afde-81b08cde3c84",
        "messageId": "19ee0265-5180-44c4-82d6-230fab13d0c9",
        "inResponseTo": "test5213021196242"
    },
    "credentialValidationResults": [
        {
            "methodId": "SECURID",
            "methodResponseCode": "SUCCESS",
            "methodReasonCode": null,
            "authnAttributes": []
        }
    ],
    "attemptResponseCode": "CHALLENGE",
    "attemptReasonCode": "AUTHENTICATION_REQUIRED",
    "challengeMethods": {
        "challenges": [
            {
                "methodSetId": null,
                "requiredMethods": [
                    {
                        "methodId": "SECURID_NEXT_TOKENCODE",
                        "priority": null,
                        "versions": [
                            {
                                "versionId": "1.0.0",
                                "methodAttributes": [],
                                "valueRequired": true,
                                "referenceId": null,
                                "prompt": {
                                    "promptResourceId": "SecurID.Resource.Prompt.Next.Tokencode",
                                    "defaultText": "Enter next token code:",
                                    "formatRegex": null,
                                    "defaultValue": null,
                                    "valueBeingDefined": false,
                                    "sensitive": true,
                                    "minLength": null,
                                    "maxLength": null,
                                    "promptArgs": []
                                }
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

Make note of the Attempt ID and Message ID in the response to use when verifying the call.

1. The response is still requesting challenge from the user, which is the ODA tokencode. The methodID in the response when it went into SECURID_NEXT_TOKENCODE. 
2. You should receive the ODA tokencode in your email or on your mobile device.
3. Use the tokencode in the Verify Call to authenticate the user.

Call

POST: https://<AM_FQDN>:5555/mfa/v1_1/authn/verify

Headers

client-key: Access-key 
content-type: application/json

Body (raw)

{
    "clientId": "<Agent_Name>",
    "subjectName": "<USERID>",
    "subjectCredentials": [
        {
            "methodId": "SECURID_NEXT_TOKENCODE",
            "collectedInputs": [
                {
                    "name": "SECURID_NEXT_TOKENCODE",
                    "value": "ODA_RECEIVED"
                }
            ]
        }
    ],
    "context": {
        "authnAttemptId": "<Attempt ID from the previous response>",
        "messageId": "test5213021196242",
        "inResponseTo": "<MessageID from the previous response>"
    }
}

 The methodID and name that is changed in the verify request to SECURID_NEXT_TOKENCODE received from the previous response.

Note: Only for Authentication Manager version 8.2 SP1, in the Verify Call you must remove the first two lines that have the clientId and subjectName .. Otherwise you will be seeing a Bad Request Error.

Notes

More information about using the RESTful RSA SecurID Authentication API can be found in the RSA SecurID Authentication API Developer's Guide.