Call /Security/AdvanceAuthentication to complete a single authentication challenge.
For most authentication requests, /Security/StartAuthentication creates a NewPackage consisting of one or two challenges. Packages with two challenges represent multi-factor authentication (MFA).
You should iterate through the Challenges array in the order in which you receive it. For each challenge, allow the user to choose one of the provided mechanisms.
Some challenges can only be answered with a single mechanism. In this case, you should automatically choose the mechanism without showing the user a list of options.
For each successful request, you receive a response with one of three Summary types:
LoginSuccess: The user has completed all challenges in the authentication package.StartNextChallenge: The user has completed the previous challenge and should proceed to the next one.OobPending: You have initiated an out-of-band mechanism flow, but the user has not yet completed it.
Access tokens
When you receive LoginSuccess, the response includes an .ASPXAUTH cookie:
.ASPXAUTH=11BA426199A9092FBF36746C5DB361934A9B0E3E6... Make sure your app saves this cookie. It contains an opaque access token you need to make API requests on behalf of the authenticated user. This token's scope is limited to the user's configured permissions.
If your app is browser-based, the cookie be automatically stored in the user's browser and forwarded with future requests. However, if you're planning to call the CyberArk Identity API from a server, you should explicitly store the access token. You can include the access token in API request headers using the format Authorization: Bearer 11BA426199A9092FBF....
In-band mechanisms
User passwords and security questions are in-band mechanisms. You directly collect their responses from users in your client. Then, you call /Security/AdvanceAuthentication, setting Action to Answer and Answer to the user-provided value:
{
"Action": "Answer",
"Answer": "password1234",
"TenantId":"ABC1234",
"SessionId":"3RrrrhXFcUS3UEvl-3wfgMYojGz44P76Or2Ym3zztyM1",
"MechanismId":"64Sn74WQXEaizC7mhZpeucoWNldHkc8z7vWc9XcIJLo1"
}
User password
When a user chooses the UP mechanism, they must enter their password into your client.
{
"Name":"UP",
"AnswerType":"Text",
"PromptMechChosen":"Enter Password",
"PromptSelectMech":"Password",
"MechanismId":"64Sn74WQXEaizC7mhZpeucoWNldHkc8z7vWc9XcIJLo1"
}
Security question
When a user chooses the SQ mechanism, they must answer at least one personal or admin-created security question.
{
"Name": "SQ",
"AnswerType": "Text",
"MultipartMechanism": {
"PromptSelectMech": "Security Question",
"MechanismParts": [{
"Uuid": "u_a4ed8e81-8e9b-416b-bc00-44ed5bf87744",
"QuestionText": "What is your cat's name?",
"PromptMechChosen": "Answer security question 'What is your cat's name?':"
}]
},
"Question": "What is your cat's name?",
"PromptMechChosen": "Answer security question 'What is your cat's name?':",
"PromptSelectMech": "Security Question",
"MechanismId": "UwGNuG9netHTOLrHFF91nO8zFBli_lVDl-0UF4Og4j01"
}
If the user only needs to answer a single question, you can reply with their answer directly:
{
...
"MechanismId": "OdzdNlLsH84bsmBiXabDHnIscu69RUpGpJ5oQrjWmZc1",
"Answer": "Smokey",
"Action": "Answer"
}
Depending on their tenant's authentication profile, the user might have to answer multiple questions. When this happens, MechanismParts contains one element for every question. In your response, place each answer in a UUID/answer key-value pair object:
{
...
"MechanismId": "OdzdNlLsH84bsmBiXabDHnIscu69RUpGpJ5oQrjWmZc1",
"Answer": {
"u_a4ed8e81-8e9b-416b-bc00-44ed5bf87744": "Arnold",
"u_144b2e18-9276-49ed-b67a-9e28692f4375": "Smokey"
},
"Action": "Answer"
}
Out-of-band mechanisms
Some mechanisms require the user to interact with a system outside of your client. These are known as out-of-band (OOB) mechanisms.
Once the user has chosen an OOB mechanism, call /Security/AdvanceAuthentication with the Action set to StartOOB. This officially begins the waiting period in which the user must either approve the request or provide a code.
While you wait for the user to take action, perform a "short poll" on /Security/AdvanceAuthentication. You build the poll request by simply changing the original request's Action from StartOOB to Poll.
For example, you would initiate an OOB mechanism using:
{
"Action":"StartOOB",
"TenantId":"ABC1234",
"SessionId":"3RrrrhXFcUS3UEvl-3wfgMYojGz44P76Or2Ym3zztyM1",
"MechanismId":"bFxWVmtoBTV_h4C26UVfMzOGJa94zHxOqoEG_XrjZE81"
}
After you receive a Success response, you would then immediately begin polling with:
{
"Action":"Poll",
"TenantId":"ABC1234",
"SessionId":"3RrrrhXFcUS3UEvl-3wfgMYojGz44P76Or2Ym3zztyM1",
"MechanismId":"bFxWVmtoBTV_h4C26UVfMzOGJa94zHxOqoEG_XrjZE81"
}
Send this request once every second until the response Summary changes from OobPending to either StartNextChallenge or LoginSuccess.
Answerability
Most out-of-band mechanisms provide a one-time passcode (OTP) the user can input into your app. These types of mechanisms are called answerable because you can complete them with an answer instead of waiting for polling.
When a user enters an answerable mechanism's OTP into your app, you should call /Security/AdvanceAuthentication using the original MechanismId. In your request, make sure to also set the Action to Answer and Answer to the user-provided code.
For example, if a user enters an OATH OTP into your app, your request should look like:
{
...
"Action":"Answer",
"Answer":"728133"
}
Batch operations
Instead of making separate API calls, you can batch Answer and StartOOB calls into one HTTP request. This is useful when you want to complete a user's in-band challenge at the same time that you initiate an out-of-band challenge.
Include these requests in the MultipleOperations top-level request body field, as in the following example:
{
"TenantId":"ABC1234",
"SessionId":"17Xg9ZtDjk2klVNWgICuJpFH_Tp66-7eRhJMpnCYY-k1",
"MultipleOperations":[
{
"MechanismId":"4TYsdsCI6E2bB1IFU_bww4JmtpC9Pz46DdGo_cFGykI1",
"Answer":"password1234",
"Action":"Answer"
},
{
"MechanismId":"Mfi55lKZ10eDCjkoezo5IsWSxv4Y3gdfkt0MaDoA9ts1",
"Action":"StartOOB"
}
]
}
Supported OOB mechanisms
The following out-of-band mechanisms are supported:
Phone call
Answerable: ❌ When a user chooses the PF mechanism, they receive a phone call. During the call, they must enter their PIN using the phone's keypad.
{
"Name":"PF",
"AnswerType":"StartOob",
"PartialPhoneNumber":"6789",
"PromptMechChosen":"We will now attempt to call your phone (6789). Please follow the instructions to proceed with authentication.",
"PromptSelectMech":"Phone Call... XXX-6789",
"MechanismId":"QqvZbCxYSkyDTEICR-6H6f_mzaxlfotu2wQxnVejsOo1"
}
Email
Answerable: ✔️
When a user chooses the EMAIL mechanism, they receive an email containing both a one-time passcode (OTP) and a link. If the user clicks the link, the challenge advances at your next poll request.
{
"Name":"EMAIL",
"MaskedEmailAddress":"***@cyberark.com",
"AnswerType":"StartTextOob",
"PromptMechChosen":"Email sent to [email protected] Click the link or manually enter the code to authenticate.",
"PromptSelectMech":"Email... @cyberark.com",
"PartialAddress":"cyberark.com",
"MechanismId":"RPcez9pD9AooKNT5UkEq7kozzer6e0BGn7GGzjDlQqc1"
}
SMS
Answerable: ✔️
When a user chooses the SMS mechanism, they receive an SMS text containing both a one-time passcode (OTP) and a link. If the user clicks the link, the challenge advances at your next poll request.
{
"Name":"SMS",
"AnswerType":"StartTextOob",
"PartialDeviceAddress":"6789",
"PromptMechChosen":"Sending a text to mobile phone ending... 6789. Enter the code or click the link in the message to proceed with authentication.",
"PromptSelectMech":"SMS... XXX-6789",
"MechanismId":"1YhBw3Gg4Z2etR8RBQebQdTcpRCD-UVBv27xTVNmSDM1"
}
OATH OTP
Answerable: ✔️
When a user chooses the OATH mechanism, they must generate an OATH one-time passcode (OTP) in either their mobile authenticator app (e.g. Google Authenticator) or the desktop CyberArk Authenticator app.
Most users manually enter their OTP into your app. However, users that have configured the CyberArk Identity mobile app as their OTP authenticator can choose to approve the login within that app.
For this reason, the OATH OTP mechanism supports Poll as a form of advancement.
{
"Name": "OATH",
"AnswerType": "StartTextOob",
"PromptMechChosen": "Enter Verification Code",
"UiPrompt": "OATH OTP Client",
"PromptSelectMech": "OATH OTP Client",
"MechanismId": "DKetaPxIW0yn8e-jBi7fTUz0H8OdsCNCscUijVXUR6s1"
}
Mobile Authenticator
Answerable: ✔️
When a user chooses the OTP mechanism, they must either generate an OTP or approve a push notification from within the CyberArk Identity mobile app.
{
"Name":"OTP",
"AnswerType":"StartTextOob",
"PromptMechChosen":"Sent Mobile Authenticator request to your device. Please follow the instructions to proceed with authentication or enter verification code here.",
"PromptSelectMech":"Mobile Authenticator",
"MechanismId":"rKgeXzVIKkKR5ERTUKhT7XuyaYS6LcLhpLkSythzHIA1"
}
FIDO2 Security Key
Answerable: ✔️
When a user chooses the U2F mechanism, they must insert a FIDO2 security key into their device.
{
"Name": "U2F",
"AnswerType": "StartTextOob",
"PromptMechChosen": "Insert security key and press its button",
"UiPrompt": "FIDO2 Security Key",
"PromptSelectMech": "FIDO2 Security Key",
"MechanismId": "xmbeXzVI8v15ERTUKh7TXuyaY133cLhpLkSythzHIA1",
"Type": "SECURITYKEY"
}
Your client must use a browser or native API such as WebAuthn to receive a code from the security key. This process occurs solely on the user's device.
CyberArk Identity cannot observe this process, and for that reason, polling is not supported. To advance U2F, you must submit the code as an answer.
QR Code
Answerable: ❌
When a user chooses the QR mechanism, they must scan a QR code using the QR Code Authenticator feature in the CyberArk Identity mobile app. The QR code your client should display is provided as a base64-encoded image.
The challenge advances at your next poll request once the user has scanned the code on their enrolled device.
{
"AnswerType": "StartOob",
"Name": "QR",
"PromptMechChosen": "Scan QR Code with the CyberArk Identity app on an enrolled device.",
"PromptSelectMech": "QR Code",
"MechanismId": "VuaMU...",
"Image": "data:image/png;base64,iVBORw..."
}
Interface text
Some mechanisms include the PromptSelectMech and PromptMechChosen descriptions. These provide user-friendly interface text tailored to each mechanism.
{
...
"PromptSelectMech":"Email... @cyberark.com",
"PromptMechChosen":"Email sent to [email protected] Click the link or manually enter the code to authenticate."
}
Use PromptSelectMech as a short description of the mechanism in a list of possible mechanism choices. Use PromptMechChosen to provide completion criteria once the user has selected the mechanism.
Failures
The following scenarios can cause a mechanism to fail:
- The user provides an invalid value for an in-band or out-of-band mechanism
- The user denies an OOB confirmation, such as a push notification
- An OOB mechanism times out due to a lack of user action
To mitigate brute force attacks, any of these failures invalidates the authentication package with the following generic message:
{
...
"success": false,
"Result": {
"Summary": "Failure"
},
"Message": "Authentication (login or challenge) has failed. Please try again or contact your system administrator.",
}
Your client should offer the user the ability to start the authentication process again. However, you must call /Security/StartAuthentication to receive a new authentication package.