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...
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
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:
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 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.
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 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.
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
.
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.
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 Enable-PSRemoting
.
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.
The Remote Procedure Call (RPC) and Windows Management Instrumentation services should be enabled and running on the target server to run the scripts in the examples below.
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.
This example uses the commonly used tool jq, 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.
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.
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.
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.
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
.
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.
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 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.
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.