PowerShell Scripts

Within workflow A workflow is a series of steps necessary to complete a process. In the context of Keyfactor Command, it refers to the workflow builder, which allows you automate event-driven tasks when a certificate is requested or revoked. step definitions, PowerShell can be used with the step types Set Variable Data and Use Custom PowerShell. Only the Use Custom PowerShell step uses the /Extensions/Scripts API endpoints. Once imported, scripts will be available for selection from a dropdown in the workflow workspace on the step dialogue when creating a step of this type or with the workflow definition API endpoints. The Set Variable Data step allows PowerShell commands to be added to the step directly, thus are not stored in the database as scripts, but only with the workflow step. Many examples of using scripts with workflow can be found in Workflow Definitions Configuration Parameters.

Event handler scripts are available for use in multiple Keyfactor Command areas, including:

• Expiration Alerts

  Create email notifications that alert administrators and/or end users when certificates are coming up for expiration.

• Pending Certificate Request Alerts

  Create email notifications that alert PKI A public key infrastructure (PKI) is a set of roles, policies, and procedures needed to create, manage, distribute, use, store and revoke digital certificates and manage public-key encryption. administrators when a new pending certificate request is made.

• Issued Certificate Request Alerts

  Create email notifications that alert a certificate requester when a certificate he or she requested has been issued.

• Denied Certificate Request Alerts

  Create email notifications that alert a certificate requester when a certificate he or she requested has been denied.

• Key Rotation Alerts

  Create email notifications that alert end users and PKI administrators when an SSH The SSH (secure shell) protocol provides for secure connections between computers. It provides several options for authentication, including public key, and protects the communications with strong encryption. key is nearing the end of its lifetime.

Event handler scripts used in any of these areas need to be imported into Keyfactor Command before they will be available for use in the alerts.

To create a PowerShell script that works with the event handlers, there are just a few things to keep in mind:

• You need to declare the $context hashtable at the start of the script with this line:

  [hashtable]$context

• Parameters you want to use in your script are referenced using the $context syntax as follows (where MyName is the name you gave to the parameter A parameter or argument is a value that is passed into a function in an application. in the event handler configuration or the name of the built-in parameter from Table 11: PowerShell Event Handler Special Fields):

  $context["MyName"]

Table 11: PowerShell Event Handler Special Fields

Below is a simple script that takes as inputs all the parameters you defined in your event handler configuration as well as the built-in parameters and outputs them to a file along with a comment and the date, with configuration to skip output of a defined list of the built-in parameters:

# This is a sample script that can be set up as a Keyfactor Command event handler. The script will output
# data passed to the handler to a text file. This script will be called for the combination of each
# certificate involved in the corresponding event and each configured email recipient.

# In order to communicate with the extension script, the Keyfactor Command event handler framework injects
# a hashtable into the PowerShell runspace. This hashtable will include the fields configured by the
# administrator when setting up the handler as well as some built-in system fields used for communication
# with the handler.

# The following fields are provided for communication with the handler:
#   Subject -        Email subject line that will be sent if the alert has the email subject configured
#   Message -        Email body that will be sent if the alert has the email message body configured
#   Recipient -      Email address where the alert will be sent if the alert has this configured
#   Certificate -    For internal use only
#   SendEmail -      Boolean (true/false) indicating if Keyfactor Command is planning on sending an email
#                    for this certificate / recipient combination
#   FirstRecipient - Boolean (true/false) indicating if this extension invocation is the first recipient
#                    for a given certificate
#                    This can be used in the event it is desired to execute some logic once per certificate
#                    This field applies only to expiration alerts

[hashtable]$context

# Four of the built-in context fields can be modified and used as output fields to change how (and if)
# Keyfactor Command will send emails related to the alert being processed:
#   Subject - If an email is produced this new value will be used to create the email subject.
#   Message - If an email is produced this new value will be used to create the email message body.
#   Recipient - If an email is produced this new value will be used as the email recipient.
#   SendEmail - This value can be used to override whether an email will be sent.
#     A value of "true" will cause an email to be sent, while "false" will cause the associated email
#     to not be sent.
#     Examples:
#       $context["Subject"] = "new subject line"
#       $context["Message"] = "new message line"
#       $context["Recipient"] = "newRecipient@keyexample.com"
#       $context["SendEmail"] = "false"

# Typically output values would be used with some form of logic. As an example, to change the recipient
# of the email based on a metadata field provided to the handler, uncomment the following, provide
# appropriate values (including a metadata field that's being passed in to the handler in place of
# "SampleMetadataField"), and remove Recipient from ignoreKeys:
#
#    if ($context["SampleMetadataField"] -eq "SomeValue") {
#        $context["Recipient"] = "newRecipient@keyexample.com"
#        }

# This example will output to a file the $context values for the user configured fields and skip the system
# supplied ones. To output the system supplied fields, remove the desired items from the $ignoreKeys array.
$ignoreKeys = "Subject", "Message", "SendEmail", "Certificate", "FirstRecipient", "Recipient"

# Path to the output file
$outputFile = ("C:\PSScripts\Output\SampleScriptOutput" + (get-date -UFormat "%Y%m%d%H%M") + ".txt")

# Add a comment and the date at the start of each output block
Add-Content -Path $outputFile -Value "Starting Output: $(Get-Date -format G)"

# Loop through all passed in key/value keys and process
$context.GetEnumerator() | % {
    if (-not $ignoreKeys.Contains($_.key)) {
        Add-Content -Path $outputFile -Value ($_.key + ": " + $_.value)
    }
}

# Add a blank line between output blocks
Add-Content -Path $outputFile -Value ""