Resolution | - Enable the REST API interface from the Security Console
Note you must be running RSA Authentication Manager 8.2 SP1 to access this interface.
- Navigate to Setup > System Settings > RSA SecurID Authentication API.
- Check the box to Enable Authentication API.
- Note the values for the Access ID and Access Key.
- You can change the value for the communication port number to any free port.
- Add an agent entry in the Security Console:
- Select Access > Authentication Agents > Add New.
- Add the agent name. Any name will do, but note that it will be used as the clientId in the requests below.
- 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
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
{ "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.
{ "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
{ "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": "" } }
{ "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
{ "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).
|