| 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 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). |
on Jun 6, 2017