Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Perform automatic script execution after password rotation
Post-rotation scripts are user-defined code snippets that execute after a credential is rotated. Scripts can be attached to PAM records, and will execute on either the remote machine or on the gateway.
For more information on attaching Post Rotation Scripts to PAM records, visit:
Post-Rotation scripts empower Keeper customers to manage and automate their IT administrative processes and tasks ranging from restarting a resource to notifying relevant parties on credential updates. Here are some of the use cases made possible with Keeper Post Rotation:
Updating Access Control Lists (ACLs)
After changes to a password or private key, it may be necessary to update the ACLs of files directories or servers as to not disrupt access. A post-execution script can automate this process and ensure that the procedures and/or users have the necessary permissions.
Revoking old credentials
After changes to a password or private key, old credentials may need to be revoked to prevent unauthorized access. A post-execution script can automate this process by revoking the old credentials and updating the user's access permissions.
Notifying relevant parties on updated credentials
Relevant parties such as IT administrators or security personnel should be notified on credentials changes. A post-execution script can automate this process by sending out notifications or alerts.
Auditing
Password or private key changes should be audited for compliance and security purposes. A post-execution script can automate this process by logging the change and any associated actions, such as ACL updates or notifications.
For code snippets and examples of these use cases, visit:
Upon successful rotation of credentials on a PAM record, Keeper executes the attached Post-Rotation scripts with parameters containing information on the involved records, credentials, and user.
For more information visit:
Post Rotation scripts can be attached to any of the PAM Record Types. Depending on the PAM record the script is attached to, the script will run either on the gateway, or the remote host where rotation occurred.
The following table shows all the available PAM Records and where the attached script will execute:
Scripts will be executed in the following order:
Scripts attached to User Record types
Scripts attached to PAM Machine, PAM Database, or PAM Directory Record types
Scripts attached to PAM Network Configuration Record types
If multiple scripts are attached to a record, scripts will be executed in the order they're in on the PAM Record
When creating or editing a PAM record, towards the bottom, there is a Add PAM Script button:
Clicking on Add PAM Script will allow you to:
Browse locally and choose your Rotation Script(s). [Required]
Add additional Resource Credential(s). This is to add additional records which contains the necessary credentials required to execute the attached post rotation script(s). [Optional]
Specify a custom command to executed. In the below screenshot, I attached a python script (postRotationTest.py
) and specified the command to be used to execute the python script. [Optional]
Multiple Scripts can be attached to a record.
After successfully selecting the script(s), the record will be updated to show the attached Post Rotation scripts:
Click Save to create or update the record. Attached Post Rotation Scripts can be deleted or edited by clicking on their respective inline icons.
Record Type | Attached Post Execution Script will execute on |
---|---|
PAM Network Configuration
Gateway
PAM Machine
The Device specified in record
PAM Database
The Device specified in record
PAM Directory
The Device specified in record
PAM User
Gateway
Upon execution of the script, the following information is returned. The results are an an array containing instances of RotationResult
for each script that was executed. The class RotationResult
has the following attributes:
uid
- Keeper Vault record UID that has the script attached
command
- Command that was issued to the shell.
system
- Operating system the script will run upon.
title
- Title of the script file attached to the Keeper Vault record.
name
- Name of the script attached to the Keeper Vault record.
success
- Was the script successful?
Linux and macOS - Script returned in a 0 return code.
Windows - Script returned a True status.
stdout
- The standard out from the execution of the script.
stderr
- The standard error from the execution of the script.
Additionally, the following methods can be used to determine if the script was a success, or not:
With this, it is possible to customize logging:
The class RotationResult
has attribute stderr
which logs the errors from execution of the script.
Although post rotation script results and information are available via the RotationResult
class, errors and outputs of scripts are based on the type of shell the script is executed on. Keeper does not check the standard out or errors of the scripts as Keeper does not know what defined an error for a customer controlled script.
For example, if a BASH script does not contain a set -e
, the script will continue even if part of the script fails. If the script exits with a 0
return code, the script will be flagged as successful.
Therefore, it is up to the user to properly handle the outputs and errors of the script.
Method | Descripton |
---|---|
was_failure
boolean, return True if failure, False if success
was_success
boolean, returns True if success, False if failure
Example use cases for post-rotation scripts in Keeper
The following section contains code snippets on common post-rotation script use cases:
Database Use Cases
The Base64 encoded JSON object can be unpacked with various scripts and applications.
Linux and MacOS has no built in JSON parser, so, in order to parse JSON, a tool like jq is required.
Keeper will execute this as follows:
MacOS history
is not like Linux history
. Linux uses history -c
, macOS uses local HISTSIZE=0
to clear the history. This mainly affects SSH connections where BASH is not forced.
Keeper will execute this as follows:
The post rotation script is not limited to shell scripts. Applications can be written in languages like Python or C# to get the piped parameters.
Since the UIDs of the Rotation involved records are passed in the params, Application can also use the KSM SDKs to get additional information about the records.
For more information on the available SDKs, visit:
The next section will go over the results from the Post Rotation Scripts, post execution.
By default, debug statements will not appear in the Gateway logs, even if you set your $DebugPreference
to Continue
on your PowerShell Post-Rotation Script.
In order to view debug statements in the logs, such as with Write-Debug
, you must run the Gateway service with the -d
start parameter and set your $DebugPreference
accordingly.
Upon successful rotation of credentials on a PAM record, Keeper executes the attached Post-Rotation scripts with parameters containing information on the involved records, credentials, and user.
Parameters will be placed in a Base64 encoded JSON object and piped to the script. The following keys can be found in this JSON object:
records
fieldThe records key value is a Base64, JSON array of dictionaries. This array will include the following data:
PAM Network Configuration Data
PAM Machine, PAM Database, or PAM Directory Record Data
The PAM record type is depended on the PAM record type of the administrative credential
Additional Record Data
These are the Resource Credential(s) attached to the Post Rotation Script
User Record Data
Each dictionary object will contain:
uid
- The UID of the Vault record.
title
- The title of the Vault record.
The rest of the dictionary will contain key/value pairs of the record's data where
the key will be the label of the field.
If the field does not contain a label, the field type will be used.
If the key already exists, a number will be added to the key.
the value will be the corresponding field value
Note: The rotationScripts
field will be omitted from the data.
Since the parameters are piped to the script, the parameters will not appear on the command line.
The next section will go over how to access these parameters.
Example of a generic Bash script, equipped with error handling and input validation, to efficiently decode and process Base64-encoded JSON strings using the `jq` tool.
Example command to simulate how the script will be executed by the Gateway:
Key | Description |
---|---|
providerRecordUid
The UID of the Keeper Vault Provider record
resourceRecordUid
The UID of the Keeper Vault Resource record
userRecordUid
The UID of the Keeper Vault User record
newPassword
The new password for the User
oldPassword
The prior password for the User
user
The username for the User
records
Base64, JSON, array of record dictionaries. Additional info in the below section
This example will allow you to rotate the credential on a Windows Scheduled Task running as a Service Account that has its password rotated via Keeper PAM.
The data in the record being rotated is made available to your script via a BASE64-encoded JSON string. This is passed into your script for consumption. When your script has finished execution, Clear-History is executed to ensure that the record data is not available for future PowerShell sessions.
To rotate the credential of a service account, the user (which in this case is the Gateway's user account) will need to be part of the Administrator's group on the target machine. This means the Gateway must run as a Service account that is assigned the appropriate level of privilege to achieve this and not run as the default SYSTEM user.
The data in the record being rotated is made available to your script via a BASE64-encoded JSON string. This is passed into your script for consumption.
To use these scripts, PowerShell 7 must be available on the target machine and should be set up and configured to enable remoting using PowerShell 7 using .
The Remote Procedure Call (RPC) and should be enabled and running on the target server to run the scripts in the examples below.
This example uses the commonly used tool , for parsing the JSON data passed to the script containing the records data. This example assumes you have it installed and the jq
command is in PATH.
To update the 'Log On As' property on a Windows Scheduled Task, you will need a credential with the appropriate permissions, such as an Administrator account.
When attaching a PAM script to a record, you have the option to add a Resource Credential that is passed to the Gateway as part of the BASE64-encoded JSON data. The above credential will need to be attached as a Resource Credential.
As many Resource Credentials can be attached to a PAM script, knowing the UID
of the Resource Credential you have attached helps ensure your script uses the correct one to update the Service's 'Log On As' property.
You can use the schtasks
command to update the credentials on the Scheduled Task. This command also requires the admin credentials mentioned above to perform the task.
Unfortunately, as the schtasks
command is not a PowerShell cmdlet, so its output will not be captured by $error
. Without additional error checking, regardless of the exit status of the schtasks
command, the gateway will always show success. To solve for this, you can check $LastExitCode
after each call to schtasks
.
To run this script, SSH public key authentication must be set up and enabled between the gateway server and the target server.
In the below example, you will hard code three values:
The name of the Scheduled Task for which you wish to rotate the credential.
The DNS resolvable name of the server the service is running on.
The username of the SSH user
Native SSH remoting is still not fully implemented into PowerShell and is only reliably possible in PowerShell 7. The gateway defaults to Windows PowerShell (v5) when running a .ps1
script. However, when attaching the script, you can also specify an alternative script command and point to the path of your PowerShell 7 executable.
Once the rotation is complete, we will log the service status to DEBUG.
The following code snippets update the credential on a Windows Service running as a Service Account after its password has been rotated via Keeper Rotation.
The data in the record being rotated is made available to your script via a BASE64-encoded JSON
string. This is passed into your script for consumption. When your script has finished execution, Clear-History
is executed to ensure that the record data is not available for future PowerShell sessions.
To rotate the credential of a service account, the user (which in this case is the Gateway's user account) will need to be part of the Administrator's group on the target machine. This means the Gateway must run as a Service account that is assigned the appropriate level of privilege to achieve this and not run as the default SYSTEM user.
The data in the record being rotated is made available to your script via a BASE64-encoded JSON
string. This is passed into your script for consumption.
As mentioned above, a BASE64 string will be piped into your script, which includes the username and new password (among other data), which you will use to rotate the Windows Scheduled Task credentials.
Using the below snippet, we can take the piped input and use certutil
to decode the BASE64 string. These will be saved to temporary files and cleaned up later, as is the custom in bat
scripts, as certutil
only accepts files as input.
jq
can be used on the resulting JSON file to get the values of user
and newPassword
.
To update the 'Log On As' property on a Windows Scheduled Task, you will need a credential with the appropriate permissions, such as an Administrator account.
When attaching a PAM script to a record, you have the option to add a Resource Credential that is passed to the Gateway as part of the BASE64-encoded JSON data. The above credential will need to be attached as a Resource Credential.
As many Resource Credentials can be attached to a PAM script, knowing the UID
of the Resource Credential you have attached helps ensure your script uses the correct one to update the Service's 'Log On As' property.
We can use jq
to access the attached Resource Credential and filter by the records UID.
The schtasks
command is used to update the desired Scheduled Task using the values you just extracted. In addition to the new credentials, you will need the Admin credentials from above.
To use these scripts, PowerShell 7 must be available on the target machine and should be set up and configured to enable remoting using PowerShell 7 using .
The Remote Procedure Call (RPC) and services should be enabled and running on the target server to run the scripts in the examples below.
This example uses the commonly used tool , for parsing the JSON data passed to the script containing the records data. This example assumes you have it installed and the jq
command is in PATH.
In the below example, you will hard code two values:
The name of the service for which you wish to rotate the credential.
The DNS resolvable name of the server the service is running on.
You can decode the BASE64 string and convert it to a useable PowerShell object with:
The sc.exe
command is used to update the desired Windows service using the values extracted from the JSON
.
Note: sc is an aliase in Windows PowerShell for Set-Content. Therefore you must include the file extension or provide a full path to the executable.
After updating the Windows Service, we will restart it, which will confirm that the credentials have been updated successfully.
Note: The SC command has particular syntax. The whitespace after
=
matters! All server names must start with a double backslash.
Unfortunately, as the sc.exe
command is not a PowerShell cmdlet, so its output will not be captured by $error
. Without additional error checking, regardless of the exit status of the sc.exe
command, the gateway will always show success. To solve for this, you can check $LastExitCode
after each call to sc.exe
.
To update the 'Log On As' property on a Windows Service, you will need a credential with the appropriate permissions, such as an Administrator account.
When attaching a PAM script to a record, you have the option to add a Resource Credential that is passed to the Gateway as part of the BASE64-encoded JSON data. The above credential will need to be attached as a Resource Credential.
As many Resource Credentials can be attached to a PAM script, knowing the UID
of the Resource Credential you have attached helps ensure your script uses the correct one to update the Service's 'Log On As' property.
PowerShell 7 makes it easy to update service credentials. By default, even in PowerShell 7, when remoting, the default PSSession will be Windows Powershell (v5). To remote using PowerShell 7, you can specify the built-in PowerShell 7 configuration: PowerShell.7
. Once the rotation is complete, we will log the service status to DEBUG
.
To run this script, SSH public key authentication must be set up and enabled between the gateway server and the target server.
In the below example, you will hard code three values:
The name of the service for which you wish to rotate the credential.
The DNS resolvable name of the server the service is running on.
The username of the SSH user
Native SSH remoting is still not fully implemented into PowerShell and is only reliably possible in PowerShell 7. The gateway defaults to Windows PowerShell (v5) when running a .ps1
script. However, when attaching the script, you can also specify an alternative script command and point to the path of your PowerShell 7 executable.
Once the rotation is complete, we will log the service status to DEBUG.
As mentioned above, a BASE64 string will be piped into your script, which includes the username and new password (among other data), which you will use to rotate the Windows Service's credentials.
Using the below snippet, we can take the piped input and use certutil
to decode the BASE64 string. These will be saved to temporary files and cleaned up later, as is the custom in bat
scripts, as certutil
only accepts files as input.
jq
can be used on the resulting JSON file to get the values of user
and newPassword
.
The sc
command is used to update the desired Windows service using the values you just extracted. Replace the server and service names with your specific server and service details.
After updating the Windows Service, we will restart it, which will confirm that the credentials have been updated successfully.
Note: Server hostnames should start with a double backslash.
The target server must be running Windows Server 2012 and above and have the IISAdministration
module installed and enabled.
To update the 'Log On As' property on a IIS Application Pool, you will need a credential with the appropriate permissions, such as an Administrator account.
When attaching a PAM script to a record, you have the option to add a Resource Credential that is passed to the Gateway as part of the BASE64-encoded JSON data. The above credential will need to be attached as a Resource Credential.
As many Resource Credentials can be attached to a PAM script, knowing the UID
of the Resource Credential you have attached helps ensure your script uses the correct one to update the Service's 'Log On As' property.
Using the IISServerManager
, you can update the credentials and restart the ISS App Pool by invoking the script block below.
These examples will allow you to rotate the credential on an IIS Application Pool running as a Service Account that has its password rotated via Keeper PAM.
The data in the record being rotated is made available to your script via a BASE64-encoded JSON string. This is passed into your script for consumption. When your script has finished execution, Clear-History is executed to ensure that the record data is not available for future PowerShell sessions.
This example uses the IIS Management utility appcmd
and expects it on PATH. The executable is located in C:\Windows\System32\inetsrv
on any IIS-enabled server.
To update the 'Log On As' property on a Windows Scheduled Task, you will need a credential with the appropriate permissions, such as an Administrator account.
When attaching a PAM script to a record, you have the option to add a Resource Credential that is passed to the Gateway as part of the BASE64-encoded JSON data. The above credential will need to be attached as a Resource Credential.
As many Resource Credentials can be attached to a PAM script, knowing the UID
of the Resource Credential you have attached helps ensure your script uses the correct one to update the Service's 'Log On As' property.
Native ISS Management RPC commands are no longer available in modern versions of Windows Server and last appeared in Windows Server 2008. However, the IIS management utility, appcmd
, coupled with Invoke-WmiMethod
can achieve the same outcome.
To update the 'Log On As' property on a Windows Scheduled Task, you will need a credential with the appropriate permissions, such as an Administrator account.
When attaching a PAM script to a record, you have the option to add a Resource Credential that is passed to the Gateway as part of the BASE64-encoded JSON data. The above credential will need to be attached as a Resource Credential.
As many Resource Credentials can be attached to a PAM script, knowing the UID
of the Resource Credential you have attached helps ensure your script uses the correct one to update the Service's 'Log On As' property.
PowerShell 7 makes it easy to update service credentials. By default, even in PowerShell 7, when remoting, the default PSSession will be Windows Powershell (v5). To remote using PowerShell 7, you can specify the built-in PowerShell 7 configuration: PowerShell.7
. Once the rotation is complete, we will also log the service status to DEBUG.
Automatically any cloud-based account using a REST API with Keeper Secrets Manager
This guide includes pre-requisites, step-by-step instructions, and a Python script example.
KSM Application: Ensure that the Keeper Secrets Manager (KSM) application is set up.
Shared Folder: A shared folder should be set up where all the records will be stored.
PAM Configuration: Ensure that the PAM Configuration is set up and that the Gateway is running and attached to this configuration.
REST API Token: You will need an API Token to interact with the arbitrary API.
Follow the steps in your target application or service to generate an API token.
Store this API token in a Keeper record. The record can be of any type, but for this example, we will use a "Login" type.
Store the API Token in the "password" field.
Store the Organization URL in the "Website Address" field.
Name this record "API Access Details" as this title will be used to fetch the record in the script later.
Create a new PAM User record to store target User details whose password will be rotated.
Set the username to match the user's login ID.
Set the password to the current password set for the user (this really depends on the REST endpoint)
Add the "Rotation Credential" record, which is the record created in Step 1 containing the API Token and URL.
Enable No-Operation (NOOP) atomic execution:
In the current PAM User record where user's details are stored, create a new custom text field labeled NOOP
and set its value to True
.
Rotation Type: Set it to "On-Demand" for this example.
Password Complexity: Leave it as default unless you have specific requirements.
Rotation Settings: Point to the PAM Configuration set up earlier.
Administrative Credentials Record: Can should be left empty
Below steps are related to the environment where the Keeper Gateway is running.
Ensure that the Python environment has all necessary dependencies installed.
If you want to use a virtual environment, add a shebang line at the top of the script.
Note: Ensure that the shebang line does not contain spaces. If it does, create a symbolic link without spaces. Example to create a symbolic link on Linux:
sudo ln -s "/Users/john/PAM Rotation Example/.venv/bin/python3" /usr/local/bin/pam_rotation_venv_python3
The Python script is well-commented and follows best practices. It imports necessary modules, initializes variables, and defines a rotation function to call an arbitrary REST API that changes user's password.
This documentation provides generic instructions on how to set up password rotation using any cloud-based application or API endpoint and PAM Gateway using "NOOP mode". This is a which tells the Gateway to skip the primary rotation method and directly execute your custom Post-Rotation script.
Attach the below that will perform the password rotation. The script has additional comments inside that describe each line.