How to set up the REST RSA SecurID Authentication API for Authentication Manager 8.2 SP1

[#1]

Article Number

000035143

Applies To

RSA Product Set: SecurID
RSA Product/Service Type: Authentication Manager
RSA Version/Condition: 8.2 SP1

Issue

• Setting up the REST API as an authentication agent.
• The REST API is very useful as it doesn't restrict you to a specific code or programming language.
• This creates custom code that is easy to integrate with Authentication Manager.

Task

This article will cover the steps and some samples to be used in the REST API setup.

Resolution

1. Enable the REST API interface from the Security Console

Note you must be running RSA Authentication Manager 8.2 SP1 to access this interface.

1. Navigate to Setup > System Settings > RSA SecurID Authentication API.
2. Check the box to Enable Authentication API.
3. Note the values for the Access ID and Access Key.
4. You can change the value for the communication port number to any free port.

Image description

2. Add an agent entry in the Security Console:
   1. Select Access > Authentication Agents > Add New.
   2.  Add the agent name.  Any name will do, but note that it will be used as the clientId in the requests below.
3. Through a REST API client there are five methods that can be used, but for the sake of this tutorial will cover the main ones.  These are

• /authn/initialize
• /authn/verify
• /authn/cancel
• /authn/status
• /authn/resources

Details on those methods are covered in the RSA SecurID Authentication API Developer's Guide.

Headers

• There are two main headers that need to be added to all the requests:

  
  client-key:85o8xe8534r7g484581wi225c1h4oozf26rv8pz78r6b019v716o46nh3w36j7x5
  Content-Type:application/json

• The client-key is the Access Key that is acquired through step 1c, above.
• POST requests are used on HTTPS.

The URL

Our REST API uses the POST method and it is as follows:

https://<Authentication Manager primary's FQDN>:<communication port configured from Security Console>/mfa/v1_1/authn/<method to be used>

For example,

https://am82-1-primary.local:5555/mfa/v1_1/authn/verify

 

Body

Initialize (without credentials)

• Initialize is the first call the client sends to the server to start the authentication process.

https://<AM Primary Hostname>:5555/mfa/v1_1/authn/initialize

• Request body (RAW):

{
    "clientId": "apihost",
    "subjectName": "test01",
    "context": {
        "authnAttemptId": "",
        "messageId": "test4726375261635",
        "inResponseTo": ""
    }
}

where, 

cliendId is the name of the agent machine running the code.
subjectName is the userID used in testing.
messageId is any identifier.

• Response (RAW):

{
    "context": {
        "authnAttemptId": "213f5ca0-2654-4733-acbc-9065c3da3ad7",
        "messageId": "afc6350d-ceef-454a-b012-fb1b0fad6456",
        "inResponseTo": "test4726375261635"
    },
    "credentialValidationResults": [],
    "attemptResponseCode": "CHALLENGE",
    "attemptReasonCode": "AUTHENTICATION_REQUIRED",
    "challengeMethods": {
        "challenges": [
            {
                "methodSetId": null,
                "requiredMethods": [
                    {
                        "methodId": "SECURID",
                        "priority": null,
                        "versions": [
                            {
                                "versionId": "1.0.0",
                                "methodAttributes": [],
                                "valueRequired": true,
                                "referenceId": null,
                                "prompt": {
                                    "promptResourceId": "SecurID.Resource.Prompt.Passcode",
                                    "defaultText": "Enter passcode:",
                                    "formatRegex": null,
                                    "defaultValue": null,
                                    "valueBeingDefined": false,
                                    "sensitive": true,
                                    "minLength": null,
                                    "maxLength": null,
                                    "promptArgs": []
                                }
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

Verify (with SecurID)

• After Initialize succeeds, the server returns at least one challenge method. Use Verify to provide authentication credentials, such as an RSA SecurID passcode, to the server.  

https://<AM Primary Hostname>:5555/mfa/v1_1/authn/verify

Request body (RAW):

{
    "subjectCredentials": [
        {
            "methodId": "SECURID",
            "collectedInputs": [
                {
                    "name": "SECURID",
                    "value": "222222"
                }
            ]
        }
    ],
    "context": {
        "authnAttemptId": "213f5ca0-2654-4733-acbc-9065c3da3ad7",
        "messageId": "test7177617189202",
        "inResponseTo": "afc6350d-ceef-454a-b012-fb1b0fad6456"
    }
}

where:

methodId is the authentication request type
value is the passcode for authentication
SECURID is for SecurID passcode or Authenticate Tokencode

• Response (RAW):

{
    "context": {
        "authnAttemptId": "213f5ca0-2654-4733-acbc-9065c3da3ad7",
        "messageId": "adecc09b-f4a8-4172-8176-c9ab9a0bc682",
        "inResponseTo": "test7177617189202"
    },
    "credentialValidationResults": [
        {
            "methodId": "SECURID",
            "methodResponseCode": "SUCCESS",
            "methodReasonCode": null,
            "authnAttributes": []
        }
    ],
    "attemptResponseCode": "SUCCESS",
    "attemptReasonCode": "CREDENTIAL_VERIFIED",
    "challengeMethods": {
        "challenges": [
            {
                "methodSetId": null,
                "requiredMethods": []
            }
        ]
    }
}

Initialize (with SecurID)

• Same as initialize but added the user authentication request in one request.
• Same URL as the normal initialize.

Request (RAW):

{
    "clientId": "apihost",
    "subjectName": "test01",
    "subjectCredentials": [
        {
            "methodId": "SECURID",
            "collectedInputs": [
                {
                    "name": "SECURID",
                    "value": "222222"
                }
            ]
        }
    ],
    "context": {
        "authnAttemptId": "",
        "messageId": "test5213021196242",
        "inResponseTo": ""
    }
}

• Response (RAW):

{
    "context": {
        "authnAttemptId": "0484e87e-c70e-45cb-a340-8574f7594792",
        "messageId": "59a66e30-5591-4321-8a8d-9247aab9f66d",
        "inResponseTo": "test5213021196242"
    },
    "credentialValidationResults": [
        {
            "methodId": "SECURID",
            "methodResponseCode": "SUCCESS",
            "methodReasonCode": null,
            "authnAttributes": []
        }
    ],
    "attemptResponseCode": "SUCCESS",
    "attemptReasonCode": "CREDENTIAL_VERIFIED",
    "challengeMethods": {
        "challenges": [
            {
                "methodSetId": null,
                "requiredMethods": []
            }
        ]
    }
}

Status

• Checks the status of the authentication attempt.

https://<AM Primary Hostname>:5555/mfa/v1_1/authn/status

• Request(RAW):

{
    "authnAttemptId": "0484e87e-c70e-45cb-a340-8574f7594792",
    "removeAttemptId": false
}

Response (RAW):

{
    "attemptResponseCode": "FAIL",
    "attemptReasonCode": "ATTEMPT_ID_NOT_FOUND",
    "subjectName": null,
    "authnPolicyId": null,
    "sessionAttributes": [],
    "successfulMethods": [],
    "attemptExpires": null
}

​​​​​​​Note: In the above example it is a failure if you finished the attempt (authnAttemptId) already or the authnAttemptId is invalid. Though the /status method is useful if used with the basic initialization request (that is, /initialize followed by /verify).

Notes

Generate a Hash-based Message Authentication Code (HMAC) for Authentication Agents

• The administrator can generate a Hash-based Message Authentication Code (HMAC) that can be used to encrypt authentication requests between authentication agents and the RSA SecurID Authentication API.
• The HMAC provides a hash for the request body and an HMAC signature.
• More information and steps can be found in the document entitled Generate an HMAC for Authentication Agents.

API clients for running sample and testing

• There is a set of API examples inside the extras of Authentication Manager 8.2 SP1, also attached to this KB
• Postman REST client is really useful for testing and sampling, it has several flavors for different operating systems, including an add-on for Chrome.
• There are several API clients as plugins for Firefox and Chrome as well that can be used for testing

More info on using the RESTful RSA SecurID Authentication API can be found on RSA Link in Configure the RSA SecurID Authentication API for Authentication Agents and the RSA SecurID Authentication API Developer's Guide.