User Self Password Reset

Resetting a Password During Authentication

Centrify's authentication APIs provide a feature to reset a password on behalf of a user during authentication. This is typically used when the user forgot their password and needs to reset it in order to authenticate.

Before continuing, ensure you are familiar with:

To perform a password reset using the API:

Invoke /Security/StartAuthentication.
Check the JSON response to see if AllowForgotPassword is set to true. 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 is true then you can continue to the next step. If the value is false, then 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 (e.g. clicks a Forgot Password button), call the /Security/AdvanceAuthentication endpoint and set the Action field in the body of the request to ForgotPassword. 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... @centrify.com",
                        "Name": "EMAIL",
                        "AnswerType": "StartTextOob",
                        "PartialAddress": "centrify.com",
                        "MechanismId": "1234ip1oimn4lIa4JW0Wu3BZRWSQXQtLuW9dPh7i1234",
                        "PromptMechChosen": "Click the link in the email sent to [email protected]"
                    }
                ]
            },
            {
                "Mechanisms": [
                    {
                        "Name": "RESET",
                        "AnswerType": "Text",
                        "MechanismId": "1234wxOOZ31meg3XSB1EctdjX6mBBRJphuVX9jW30987"
                    }
                ]
            }
        ],
        "Version": "1.0"
    },
    ...
}

The RESETmechanism performs the password reset. This will be covered below in steps 6 and 7.

Complete each the required authentication mechanism(s) using /Security/AdvanceAuthentication until you get to the RESET 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 as StartNextChallenge. For example:

POST /Security/AdvanceAuthentication

{
     "TenantId": "ABC1234",
     "SessionId": "1db90fe4-3b96-4c3e-a3c1-9a10fa7514c9-27f4e64e86ac08e8",
     "MechanismId": "1234ip1oimn4lIa4JW0Wu3BZRWSQXQtLuW9dPh7i1234",
     "Action": "Poll"
}

The Summary field in the response will indicate 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 the RESET 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 login again as shown here:

{
	"success" : true,
	"Result" :
	{
		"ClientMessage" : "Password change was successful, please authenticate with your new credentials.",
		"Summary" : "NoncommitalSuccess"
	}
}

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

Resetting a Password After Authentication

Centrify also allows for a password to be reset after the user has authenticated.

To reset a password in this scenario, invoke the UserMgmt/ChangeUserPassword endpoint, passing in 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 as successful:

{
    "success": true,
    ...
}