Creating a Custom Password Changer

Terms preceded by $ are substitution tokens. Some resolve to secret template field values; others — including $PASSWORD, $CURRENTPASSWORD, $NEWPASSWORD and $PRIORPASSWORD — resolve to different values depending on where in the password-change lifecycle the command set runs. Before editing a command set, see Editing Custom Commands for the token list and Complete Scripting Token Reference for the full reference. Terms preceded by $[1]$ refer to the field of a linked secret and follow different rules — see Associated Reset Secrets. If you need to reference a secret template field, make sure you are using the exact secret template field name. To use a shell variable rather than a token, prefix it with an underscore — for example $_USERNAME.

To create a custom password changer, follow the procedure below.

1. Go to Remote Password Changing > Password Changers in the Settings menu. The Password Changers page appears.

2. Click the Create Password Changer button. A New Password Changer popup appears.

3. Choose a Base Password Changer with a command set that most closely matches the type of password changer you are creating, as this determines which customizable parameters and test actions are available to you. To create a custom SSH password changer, choose a base password changer with a name that ends in (SSH).

4. Give your new password changer a Name and click Save. The page for the new changer appears.

5. Click the Custom Commands tab.

6. Click the Edit button.

7. Click the Script tab for the Password Change Commands section.

8. Edit the Password Change Commands to contain the command set you need.

   • Use the Delete button (trash can) to remove a row.
   • Click and drag the dots on the left to move a row.
   • Click the + Add Command button to create a new row.

9. Edit the Verify Password Changed Commands to create the command set for checking that the password is valid. These commands are used by heartbeat and after a password change to verify that the change was successful. Because this command set runs in both contexts, authenticate with $CURRENTPASSWORD rather than $PASSWORD. If the target system needs time to commit the new password before verification runs, use Advanced: Delay Verify After Password Change (seconds) rather than enabling Bypass Verify After Password Change.

10. Using the same procedure, change the commands as desired in the under Post Successful Change Commands and Post Failure Change Commands.

11. When you are finished editing the commands, scroll to the bottom and click Save. To edit advanced commands and settings, see the instructions below.

Advanced Settings

To modify advanced settings, do the following:

1. Go to Remote Password Changing > Password Changers in the Settings menu. The Password Changers page appears.

2. Click the name of the desired password changer. Its page appears, set to the General tab.

3. Click the Edit button.

4. Adjust the settings as desired:

   • Remote Password Changing Timeout (minutes):
     Type: Integer (minutes)
     What it does: Sets the timeout (in minutes) used by the password changer when changing a password remotely.

   • Bypass Verify After Password Change:
     Type: Boolean (enable/disable)
     What it does: When enabled, bypasses the Heartbeat verification check after a successful password change. Note: Bypassing verification can lead to issues.

   • Heartbeat Unknown Error—Unable to Connect Translation (regex):
     Type: Regular expression
     What it does: Provides a regex used to reclassify an Unknown Error as "Unable To Connect" based on the contents of the error message.

   • Attempt Password Change with New Password When Error Contains (regex):
     Type: Regular expression (evaluated against the failure message)
     What it does: If an RPC password change fails, this regex runs against the failure message, which includes a FailureCode. If the regex matches and the number of failed attempts is five or fewer, a new password is generated for the next password attempt. Only the password field is updated; no other fields are changed.
     Examples (copy/paste):

     • .*UnknownError.* — Any error with UnknownStatus
     • .* — Any error
     • .*minimum.* — Minimum Password Requirements
     • .*0x80072035.* — Server rejects password
     • .*(0x80072035|minimum).* — Match either of the two above
   • Advanced: Delay Verify After Password Change (seconds):
     Type: Integer (seconds)
     What it does: Sets how many seconds to wait after a password has been changed before verifying the password.
     Limits/Defaults: Max: 90 seconds; Default: blank.
5. Click the Save button.
   

Troubleshooting

Symptom: The password was changed on the target system, but Secret Server reports the password change as failed, and the secret is marked out of sync.

Cause: The Verify Password Changed command set also runs immediately after a successful password change, not only on heartbeat. A $$CHECKFOR line that authenticates with $PASSWORD compares against the pre-change value in that context, so the check fails even though the change succeeded on the target.

Resolution: Use $CURRENTPASSWORD in the verify command set's authentication line. If the target system needs settling time before the new password is accepted, set Advanced: Delay Verify After Password Change (seconds) rather than enabling Bypass Verify After Password Change. A $$CHECKFOR failure aborts the command set and returns a failure result immediately.