Skip to the content

The new REST authentication API

Authentication Manager 8.3+ or SecurID Access support a new REST based authentication API which will gradually replace the previous proprietary API that used a proprietary communication protocol on UDP port 5500 via SDKs available for selected platforms.

One of the big advantages of the new REST API is that it can be consumed from almost any platform capable of forming a valid REST request. The management of agent hosts is also simplified, as it doesn't require to establish a node secret.

The downside is that you'll have to take care of load balancing requests between your AM servers. Unlike the Authentication SDK, failover and load-balancing need to be taken care of by the consuming application or by infrastructure like a load balancer.

The REST API listens by default on TCP port 5555, although this can be changed to any other suitable port via the AM Security Console. On the same page you can enable the REST API.

As an example, to validate a user authenticating with a SecurID token, the following REST requests would need to be sent to the API. This example only shows the "happy path".

Initialize request and response

To initiate an authentication cycle, first send a REST "initialize" request as shown here:

POST https://am82ptest1.lab.safearea.com.au:5555/mfa/v1_1/authn/initialize HTTP/1.1
Content-Type: application/json; charset=utf-8
Content-Length: 242
Accept: application/json
client-key: 26xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxs8
User-Agent: Swagger-Codegen/1.0.0/java
X-Access-ID: 7q6739zxxxxxxxxxxxxxxxxxxx010e7q0w6w70bm95x2

{
"authnAttemptTimeout": 180,
"clientId": "test.agent",
"subjectName": "mike4",
"lang": "en_US",
"assurancePolicyId": " ",
"sessionAttributes": [],
"subjectCredentials": [],
"context": {
"messageId": "422cd078-6e6d-4318-93bf-8d5953535cef"
},
"keepAttempt": false
}

Make sure you obtain the client-key and X-Access-ID values from the AM Security Console.

The subjectname parameter should match the FQDN of one of the Agent Hosts configured in AM.

SubjectName contains the username of the actor to authenticate.

Date: Wed, 18 Jul 2018 09:17:34 GMT
Transfer-Encoding: chunked
Content-Type: application/json
OkHttp-Sent-Millis: 1531905455530
OkHttp-Received-Millis: 1531905455548

{
"context": {
"authnAttemptId": "62e86092-34f3-40e9-b491-eb23c128cd23",
"messageId": "1e94f73b-c1a2-4054-a39b-35189543f12a",
"inResponseTo": "422cd078-6e6d-4318-93bf-8d5953535cef"
},
"credentialValidationResults": [],
"attemptResponseCode": "CHALLENGE",
"attemptReasonCode": "AUTHENTICATION_REQUIRED",
"challengeMethods": {
"challenges": [
{
"requiredMethods": [
{
"methodId": "SECURID",
"versions": [
{
"versionId": "1.0.0",
"methodAttributes": [],
"valueRequired": true,
"prompt": {
"promptResourceId": "SecurID.Resource.Prompt.Passcode",
"defaultText": "Enter passcode:",
"valueBeingDefined": false,
"sensitive": true,
"promptArgs": []
}
}
]
}
]
}
]
}
}
The response indicates that the user is to be challenged with a SecurID authenticator.

Verify request and response (happy path, successful authentication)

To validate that the passcode or tokencode provided by the user is correct, invoke the "verify" method:

POST https://am82ptest1.lab.safearea.com.au:5555/mfa/v1_1/authn/verify HTTP/1.1
Content-Type: application/json; charset=utf-8
Content-Length: 315
Accept: application/json
client-key: 26v9365xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxvs8
User-Agent: Swagger-Codegen/1.0.0/java
X-Access-ID: 7q673xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx0bm95x2

{
"subjectCredentials": [
{
"methodId": "SECURID",
"versionId": "1.0.0",
"collectedInputs": [
{
"name": "SECURID",
"value": "123456",
"dataType": "STRING"
}
]
}
],
"context": {
"authnAttemptId": "62e86092-34f3-40e9-b491-eb23c128cd23",
"messageId": "0b03efa1-ac4b-412b-a651-26f24bff7936",
"inResponseTo": "1e94f73b-c1a2-4054-a39b-35189543f12a"
}
}
The "value" field should contain the passcode or tokencode entered by the customer.

Date: Wed, 18 Jul 2018 09:17:38 GMT
Transfer-Encoding: chunked
Content-Type: application/json
OkHttp-Sent-Millis: 1531905458891
OkHttp-Received-Millis: 1531905459103

{
"context": {
"authnAttemptId": "62e86092-34f3-40e9-b491-eb23c128cd23",
"messageId": "4fd6eccc-1916-4bff-9bed-953f6151d1db",
"inResponseTo": "0b03efa1-ac4b-412b-a651-26f24bff7936"
},
"credentialValidationResults": [
{
"methodId": "SECURID",
"methodResponseCode": "SUCCESS",
"authnAttributes": []
}
],
"attemptResponseCode": "SUCCESS",
"attemptReasonCode": "CREDENTIAL_VERIFIED",
"challengeMethods": {
"challenges": [
{
"requiredMethods": []
}
]
}
The "attemptResponseCode" field indicates that the authentication was successful.

If you need assistance integrating an application with the new AM REST authentication API please do not hesitate to get in touch with us.

About the author

Mike Lucini

IT consultant of (almost) everything Java, SOAP, REST or otherwise web-related, with a touch of .Net when needed. Sporadic trouble (maker|shooter|fixer).