Advancing Multifactor Authentication

If a server’s response to the /Security/StartAuthentication request contains an array of two challenges, Multi Factor Authentication (MFA) is required to authenticate the user. That is, the user is expected to fulfill one mechanism from each of the Challenges.

The following example response from a /Security/StartAuthentication request shows two challenges each with Mechanisms arrays. The first challenge contains one mechanism (a password challenge), while the second contains five challenges of various types:

{
  "success": true,
  "Result": {
    "ClientHints": {
        "PersistDefault": False,
        "AllowPersist": True,
        "AllowForgotPassword": False
    },
    "Version": "1.0",
    "SessionId": "1e5214e4-0921-4e9e-8ada-3ef2970f7c1f",
    "Challenges": [
        {
            "Mechanisms": [
                {
                    "AnswerType": "Text",
                    "Name": "UP",
                    "MechanismId": "4a23390d-dee9-4ead-aa33-2bacd93f81fa"
                }
            ]
        },
        {
            "Mechanisms": [
                {
                    "AnswerType": "Text",
                    "PartialAddress": "my.centrify.net",
                    "EmailType": "Primary",
                    "Name": "EMAIL",
                    "MechanismId": "06d82f0c-cb09-4420-a64f-ecd9efda74e8"
                },
                {
                    "AnswerType": "Text",
                    "PartialDeviceAddress": "6098",
                    "Name": "SMS",
                    "MechanismId": "2bcddd0b-37b9-4a6b-b393-9cd03eb7c9aa"
                },
                {
                    "AnswerType": "Text",
                    "Question": "Tonight's Homework",
                    "Name": "SQ",
                    "MechanismId": "5778ff68-4e65-4ceb-b9e8-361e281228a8"
                },
                {
                    "AnswerType": "Text",
                    "PartialPhoneNumber": "6098",
                    "Name": "PF",
                    "MechanismId": "2f0a3e0c-bea8-4c91-95f0-b9cdd736f668"
                },
                {
                    "AnswerType": "Text",
                    "PartialPhoneNumber": "5290",
                    "Name": "PF",
                    "MechanismId": "415a2e99-371a-49e3-bf3b-267b1a83be96"
                }
            ]
        }
    ],
    "Summary": "NewPackage",
    "TenantId": "ABC1234"
}

When your client receives this response, it must iterate through all of the Challenges elements.

In this example, the first Mechanisms collection contains one element, with an AnswerType of Text, so the client presents a UI for password entry. After the user submits the password, the client calls /Security/AdvanceAuthentication.

If the server determines that the challenge was fulfilled, the server responds with a Result similar to the following example:

{
  "success": true,
  "Result":
  {
   "Summary": "StartNextChallenge"
  },
  "Message": null, "MessageID": null, "Exception": null, "ErrorID": null, "ErrorCode": null, "InnerExceptions": null
 }

The Result element contains a Summary sub-element with a value of StartNextChallenge. This sub-element indicates that the client must present the next challenge to the user and advance the authentication when the user provides the credentials to that next challenge. That is, the client must iterate to the next element in Challenges, and then choose one mechanism from Mechanisms to present to the user.

In single-factor authentication, the Summary is set to LoginSuccess to indicate that authentication is complete, but for MFA, the value is set to StartNextChallenge to indicate that your client must now repeat the /Security/AdvanceAuthentication process with the next challenge.

Since the Mechanisms array of the second Challenges element contains multiple elements, the client must pick one of those mechanisms and repeat the /Security/AdvanceAuthentication process one more time with the chosen mechanism. Your client application can determine how to perform the mechanism selection. For example, it could provide a UI for the user to select the type of mechanism for this second level of authentication.

After the client completes the final /Security/AdvanceAuthentication process, the response contains the value: LoginComplete for the Summary element in the body and an .ASPXAUTH cookie containing the authentication code that the client can use to invoke subsequent endpoints.

Try the API in Postman:
.
Click here for help with using our sample Postman collection.