Reset a password for a user (user self-service)
This topic describes how to reset a password on behalf of a user both during and after authentication.
Reset a password during authentication
Using the CyberArk Identity authentication APIs, you can reset a password on behalf of a user during authentication. This is typically used when a user forgets their password and needs to reset it in order to authenticate.
Before continuing, ensure that you are familiar with:
-
Invoke /Security/StartAuthentication.
-
Check the JSON response to see if
AllowForgotPassword
is set totrue
. For example:{ "success": true, "Result": { "ClientHints": { "PersistDefault": false, "AllowForgotPassword": true, "AllowPersist": true }, "TenantId": "AAA3226", ... } }
The value of the
AllowForgotPassword
field is based on whether the Forgot Password option is enabled in the user's policy. If the value istrue
, you can continue to the next step. If the value isfalse
, the password cannot be reset for the user. -
Provide a user interface element to the user, such as a Forgot Password button, which allows the user to trigger the password reset process.
-
When the user invokes this user interface element (for example, clicks a Forgot Password button), call the /Security/AdvanceAuthentication endpoint and set the
Action
field in the body of the request toForgotPassword
. For example:POST /Security/AdvanceAuthentication { "TenantId": "ABC1234", "SessionId": "1db90fe4-3b96-4c3e-a3c1-9a10fa7514c9-27f4e64e86ac08e8", "Action": "ForgotPassword" }
The result contains an updated list of mechanisms whereby the password mechanism has been removed and a new mechanism called
RESET
has been added:{ "success": true, "Result": { ... "TenantId": "AAA3226", "Summary": "NewPackage", "SessionId": "1db90fe4-3b96-4c3e-a3c1-9a10fa7514c9-27f4e64e86ac08e8", "Challenges": [ { "Mechanisms": [ { "PromptSelectMech": "Email... @idaptive.app", "Name": "EMAIL", "AnswerType": "StartTextOob", "PartialAddress": "idaptive.app", "MechanismId": "1234ip1oimn4lIa4JW0Wu3BZRWSQXQtLuW9dPh7i1234", "PromptMechChosen": "Click the link in the email sent to xxxx@idaptive.app" } ] }, { "Mechanisms": [ { "Name": "RESET", "AnswerType": "Text", "MechanismId": "1234wxOOZ31meg3XSB1EctdjX6mBBRJphuVX9jW30987" } ] } ], "Version": "1.0" }, ... }
The
RESET
mechanism performs the password reset. This is covered below in steps 6 and 7. -
Complete each the required authentication mechanism(s) using
/Security/AdvanceAuthentication
until you get to theRESET
mechanism. Each of these mechanisms may require a user interface where the user can provide a response to the challenge. After the user fulfills these challenges, they will have the opportunity to change their password as described below.For example:
POST /Security/AdvanceAuthentication { "TenantId": "ABC1234", "SessionId": "1db90fe4-3b96-4c3e-a3c1-9a10fa7514c9-27f4e64e86ac08e8", "MechanismId": "1234ip1oimn4lIa4JW0Wu3BZRWSQXQtLuW9dPh7i1234", "Action": "StartOOB" }
For out-of-bounds mechanisms, invoke the polling action repeatedly until the
Result
>Summary
field in the response is returned asStartNextChallenge
. For example:POST /Security/AdvanceAuthentication { "TenantId": "ABC1234", "SessionId": "1db90fe4-3b96-4c3e-a3c1-9a10fa7514c9-27f4e64e86ac08e8", "MechanismId": "1234ip1oimn4lIa4JW0Wu3BZRWSQXQtLuW9dPh7i1234", "Action": "Poll" }
The
Summary
field in the response indicates the status of the challenges:{ "success":true, "Result": { "Summary":"StartNextChallenge" }, ... }
-
Present a user interface requesting that the user enter a new password and confirmation password. Ensure that the password and confirmed password match.
-
Invoke the
/Security/AdvanceAuthentication
endpoint for theRESET
mechanism and set the following in the body of the request:-
Action: set to
Answer
. -
TenantID: set to the tenant ID.
-
SessionId: set the session ID.
-
MechanismId: specify the mechanism ID of the
RESET
mechanism. -
Answer: set to the user's new password.
For example:
POST /Security/AdvanceAuthentication { "TenantId": "ABC1234", "SessionId": "1db90fe4-3b96-4c3e-a3c1-9a10fa7514c9-27f4e64e86ac08e8", "MechanismId": "1234wxOOZ31meg3XSB1EctdjX6mBBRJphuVX9jW30987", "Action": "Answer", "Answer": "Pass4567" }
Depending on the user's policy settings, the response may indicate that the user has been successfully logged in, which means the password has been changed, or the response may indicate that the user's password has been changed and that they need to log in again, as shown here:
{ "success" : true, "Result" : { "ClientMessage" : "Password change was successful, please authenticate with your new credentials.", "Summary" : "NoncommitalSuccess" } }
-
Reset a password after authentication
Using the CyberArk Identity authentication APIs, you also can reset a password on behalf of a user after that user has authenticated.
To reset a password in this scenario, invoke the UserMgmt/ChangeUserPassword endpoint, passing the old password and new password into the respective body parameters:
POST UserMgmt/ChangeUserPassword
{
"newPassword": "ABC1234",
"oldPassword": "DEF789"
}
The response indicates if the password reset is successful:
{
"success": true,
...
}