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

Document created by RSA Customer Support Employee on Apr 29, 2020Last modified by RSA Customer Support Employee on Apr 29, 2020
Version 2Show Document
  • View in full screen mode

Article Content

Article Number000038745
Applies ToRSA Product Set: SecurID
RSA Product/Service Type: Authentication Manager
RSA Version/Condition: 8.2.1.x, 8.3.x, 8.4.x
 
IssueThis article explains how to use REST API calls to authenticate with On-Demand Authentication (ODA) for RSA Authentication Manager 8.x.
TasksThis 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.

User-added image



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

  • Configure email or SMS, depending on 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.

User-added image



 



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

User-added image



 



  1. Log in to the internal or external Self-Service Console to test ODA for your user.
  2. 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 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 changed in the verify request to SECURID_NEXT_TOKENCODE received from the previous response.
NotesMore information about using the RESTful RSA SecurID Authentication API can be found in the RSA SecurID Authentication API Developer's Guide.

Attachments

    Outcomes