Secret RPC Scripts

You can pass values calculated with a PowerShell script. For example, you can cycle an AWS IAM token. When changed within a PowerShell script, the new token is returned from the AWS API so it may be returned as a PSObject that will be used to update the secret.

DataItems

These return values from the script are called update "DataItems." These dataitems override any existing values and bypass any next values, including Auto-change Next Password. PowerShell RPC requires that you use a privileged account if a password is one of the items passed back in the DataItems.

Example returning a DataItems for a secret:

#at the end of the script add this return

$dataItem = New-Object –TypeName PSObject;$dataItem | Add-Member -MemberType NoteProperty -Name "Notes" -Value "NewValue1";$dataItem | Add-Member -MemberType NoteProperty -Name "Password" -Value " NewValue2";$dataItem | Add-Member -MemberType NoteProperty -Name "Machine" -Value " NewValue3";

return $dataItem

In this example, the fields “Notes”, “Password”, and “Machine” on the secret are updated with a “NewValue”. In your environment, these values are typically in relation to items that were generated during the RPC.

Dependencies

PowerShell dependencies can also return DataItems that are used to update a dependency.

This requires:

  • Using a dependency changer with a defined scan-item template.
  • The values passed back must be scan-item template fields. There are three built-in fields: "Description," "ServiceName," and "Machine." Advanced PowerShell dependency changers that use postscripts may also pass values between themselves.

Here is an example of returning a DataItem for a dependency:

# At the end of the script add this return

$dataItem = New-Object –TypeName PSObject;$dataItem | Add-Member -MemberType NoteProperty -Name "Description" -Value "NewValue1";$dataItem | Add-Member -MemberType NoteProperty -Name "ServiceName" -Value " NewValue2";$dataItem | Add-Member -MemberType NoteProperty -Name "Machine" -Value " NewValue3";

return $dataItem

In this example, the values on the dependency are updated to match the “NewValue” that is being passed back from the PowerShell dependency changer.

Dependency Tokens

The available tokens are:

  • $UPDATED.<Token> This give you the value the dependency script returned for the token DataItem. <Token> would be changed to match the field name returned that is needed in the script.
  • $SECRET.UPDATED.<Token> This returns the value the secret password change script returned for the token DataItem.

Limitations

Files:

Files are supported but need to be returned as a string value in the DataItem. There could be encoding complications to watch out for as it uses UT8F.

Run Dependency:

  • This loads the values from the current secret as DataItems.
  • When running a dependency manually from the UI, which is typically done to update a dependency that was offline during the secret's password reset, DataItems that are saved on the secret as files are not supported, so the run will fail.

Test Dependency:

Tests done from the UI do not use DataItems, so they may return false positives with advanced dependencies.

Privileged Account:

A privilege account is required if changing the password of a secret.