Overview

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.

Using PowerShell Scripts

Prerequisites

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.

Pulling Parameters from the Record

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 Gateway will execute your script as follows
"BASE64STRING==" | .\your-script.ps1; Clear-History

Using Batch Files

Prerequisites

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.

Pulling Parameters from the Record

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.

# The Gateway will execute your script as follows
"BASE64STRING==" | .\your-script.bat && echo ####RC %errorlevel%

User Defined Parameters

In the below example, you will hard code two values:

1. The name of the service for which you wish to rotate the credential.

2. The DNS resolvable name of the server the service is running on.

$ServiceName = 'My Service'
$TargetMachine = 'my-server'

Updating the Service

You can decode the BASE64 string and convert it to a useable PowerShell object with:

$RecordJsonAsB64 = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($Record))
$RecordParams = ($RecordJsonAsB64 | ConvertFrom-Json)

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.

sc.exe \\$TargetMachine stop $ServiceName
sc.exe \\$TargetMachine config $ServiceName obj= $RecordParams.user password= $RecordParams.newPassword
sc.exe \\$TargetMachine start $ServiceName

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.

if( $LastExitCode -ne 0 ) {
    exit $LastExitCode
}

Full Example

[CmdletBinding()]
param (
    [Parameter(ValueFromPipeline=$true)]
    [string]
    $Record
)

# User defined parameters
$ErrorActionPreference = 'Stop'
$DebugPreference = 'Continue'
$ServiceName = 'My Service'
$TargetMachine =  'my-server'

$RecordJsonAsB64 = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($Record))
$RecordParams = ($RecordJsonAsB64 | ConvertFrom-Json)
Write-Debug "Running Post-Rotation Script on = $($RecordParams.userRecordUid)"

Write-Debug "Stopping $ServiceName"
sc.exe \\$TargetMachine stop $ServiceName
if( $LastExitCode -ne 0 ) {
    exit $LastExitCode
}

Write-Debug "Changing $ServiceName password"
sc.exe \\$TargetMachine config $ServiceName obj= $($RecordParams.user) password= $($RecordParams.newPassword)
if( $LastExitCode -ne 0 ) {
    exit $LastExitCode
}

Write-Debug "Restarting $ServiceName"
sc.exe \\$TargetMachine start $ServiceName
if( $LastExitCode -ne 0 ) {
    exit $LastExitCode
}

Using Admin Credentials

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.

Updating the Service

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.

$ScheduledTaskName = '<Task Name>'
$ScheduledTaskStatus = Invoke-Command `
    -ComputerName '<Target Machine>' `
    -Credential $AdminCredential `
    -ConfigurationName 'PowerShell.7' `
    -ScriptBlock { 
        Stop-ScheduledTask -TaskName $Using:ScheduledTaskName
        Set-ScheduledTask -TaskName $Using:ScheduledTaskName -User $Using:Params.user -Password $Using:Params.newPassword
        Start-ScheduledTask -TaskName $Using:ScheduledTaskName
        return Get-ScheduledTask -TaskName $Using:ScheduledTaskName | Select-Object "State"
}

Write-Debug "$ScheduledTaskName is: $($ScheduledTaskStatus.State)"

Full Example

[CmdletBinding()]
param (
    [Parameter(ValueFromPipeline=$true)]
    [string]
    $B64Input
)

$ErrorActionPreference = "Stop"
$DebugPreference = 'Continue'

function ConvertFrom-B64 {
    param (
        [string] $B64String
    )

    try {
        $Json = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($B64String))
        $Output = $Json | ConvertFrom-Json
    }
    catch {
        Write-Error "Failed to convert Base64 string: $B64String"
    }
    return $Output
}

function New-PSCredential {
    param (
        [string] $Username,
        [string] $Password
    )

    try {
        $SecurePassword = ConvertTo-SecureString $Password -AsPlainText -Force
        $Credential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $Username, $SecurePassword
        Write-Debug "New PSCredential created for: $Username" 
    }
    catch {
        Write-Error "Failed to create PSCredential for: $Username"
    }
    return $Credential
}

# The JSON data is passed to the Gateway as a Base64 encoded string.
$Params = ConvertFrom-B64 -B64String $B64Input
Write-Debug "Running Post-Rotation Script on: $($Params.userRecordUid)" 

# Create a PSCredential to be used to update the Service's `Log On As` property.
$ServiceAccountCredential = New-PSCredential -Username $Params.user -Password $Params.newpassword

# Convert the attached Resource Records from Base64 encoded JSON string and find the 
# Admin Record we need to update the Service's `Log On As` property by filtering by the 
# Admin Record's UID.
$ResourceCredentials = ConvertFrom-B64 -B64 $Params.records
$AdminRecord = $ResourceCredentials | Where-Object { $_.uid -eq '<Admin Record UID>' }

# Each record type will have a different JSON structure. In this instance, we are using 
# a PAM Directory record type, so we need to build the username from the `login` and 
# `domainName` properties.
$AdminCredential = New-PSCredential -Username "$($AdminRecord.login)@$($AdminRecord.domainName)" -Password $($AdminRecord.password)

# Rotate the Service's `Log On As` property
$ServiceName = '<Target Service>'
$ServiceStatus = Invoke-Command `
                    -ComputerName '<Target Machine>' `
                    -Credential $AdminCredential `
                    -ConfigurationName 'PowerShell.7' `
                    -ScriptBlock { `
                        Stop-Service $Using:ServiceName; `
                        Set-Service -Name $Using:ServiceName -Credential $Using:ServiceAccountCredential; `
                        Start-Service $Using:ServiceName; `
                        return Get-Service $Using:ServiceName;
                    }

Write-Debug "$ServiceName is: $($ServiceStatus.Status)"

Additional Prerequisites

To run this script, SSH public key authentication must be set up and enabled between the gateway server and the target server.

User Defined Parameters

In the below example, you will hard code three values:

1. The name of the service for which you wish to rotate the credential.

2. The DNS resolvable name of the server the service is running on.

3. The username of the SSH user

Updating the Service

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.

Full Example

Parsing the piped input

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.

Updating the Service

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.

Full Example