Advancing Out-of-bounds Authentication

Your client can present a mechanism, such as a password, to the user. Once the user has entered the data, your client would send that to the server. A more involved mechanism is an Out of Bounds (OOB) challenge, which involves an additional entity, such as a smartphone, in the authentication process.

For example, a user might be required to check a smartphone for a verification code and then enter that code in your client app. The smartphone runs a separate client application to obtain the verification code.

An OOB authentication process is slightly more complex because your client cannot collect the challenge information from the user. Your client will not receive the results of the authentication immediately; it must advance the OOB authentication and then poll the server for the verification result.

Your client first determines if one of the challenges returned from /Security/StartAuthentication is an OOB challenge. If so, the client invokes /Security/AdvanceAuthentication, specifying StartOOB for the Action field.

POST https://ABC1234.mycompany.centrify.com/Security/AdvanceAuthentication


X-CENTRIFY-NATIVE-CLIENT:true
Content-Type: application/json


{
     "TenantId": "ABC1234",
     "SessionId": "1db90fe4-3b96-4c3e-a3c1-9a10fa7514c9-27f4e64e86ac08e8",
     "MechanismId": "8110671b-7d6c-4604-98c5-4fd273f8063f-099e7f417e646300",
     "Action": "StartOOB"
}

The server responds with a Summary element set to OobPending, which indicates that the server is awaiting a response from the additional entity (such as a smartphone verification code).

{
    "Summary": "OobPending"   
}

Your client must then repeatedly poll CIAM until a result is available because it doesn’t have control over when the authentication step occurs. To accomplish this, your client repeatedly invokes /Security/AdvanceAuthentication for the tenant and user, specifying Poll for the Action field and re-supplying the MechanismId for polling:

POST https://ABC1234.mycompany.centrify.com/Security/AdvanceAuthentication


X-CENTRIFY-NATIVE-CLIENT:true
Content-Type: application/json


{
     "TenantId": "AB123",
     "SessionId": "1db90fe4-3b96-4c3e-a3c1-9a10fa7514c9-27f4e64e86ac08e8",
     "MechanismId": "8110671b-7d6c-4604-98c5-4fd273f8063f-099e7f417e646300",
     "Action": "Poll"
}

Your client must analyze the response to determine if the mechanism response is still pending or if it has been completed. If the server is still awaiting a response from the additional entity (e.g., smartphone), it continues to respond with Summary set to OobPending. If the mechanism is completed, then the response contains a Success element set to true and a Summary element set to LoginSuccess. Once LoginSuccess is received, the client can obtain the .ASPXAUTH authentication cookie from the response and continue to invoke subsequent endpoints on behalf of the user.

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