Workflow Definitions Configuration Parameters

Tip:  Tokens (a.k.a. substitutable special text) may be used in the URL and request content fields. Tokens use a variable in the workflow definition that is replaced by data from the certificate request, certificate, or certificate metadata Metadata provides information about a piece of data. It is used to summarize basic information about data, which can make working with the data easier. In the context of Keyfactor Command, the certificate metadata feature allows you to create custom metadata fields that allow you to tag certificates with tracking information about certificates. at processing time. For example, you can take the revocation comment entered when the revocation request is approved—$(cmnt)—and insert it into a custom metadata field in the certificate by doing a PUT /Certificates/Metadata request for the $(id). Fields that support tokens are indicated with at the top right of the field. To use a token in a field, begin typing at the location where you want the token to appear, starting with $(. Once you have typed $(, a second ) will appear automatically along with a dropdown of available tokens to choose from. You may continue typing to narrow the values in the dropdown (e.g. type $(req to see only tokens that begin “req”).

Figure 172: Tokens are Highlighted

• Headers: Enter any headers needed for your request. For a Keyfactor API A set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command. request, this might look like:
  x-keyfactor-requested-with: APIClient
  x-keyfactor-api-version: 1
  Tip:  For a Keyfactor API request, version 1 is assumed if no version is specified. Content type and authorization headers do not need to be specified, since those are addressed elsewhere in the configuration.
• Variable to Store Response in: Provide a name for the parameter A parameter or argument is a value that is passed into a function in an application. in which to store the response data from your request. You can then reference this parameter from subsequent steps in the workflow.
  Tip:  The response is stored as a serialized JObject. To make use of only a portion of the response data in your subsequent step, use JSON path syntax. For example, say you returned the data from a GET /Agents request in a variable called MyResponse and you wanted to reference the ClientMachine name for the orchestrator Keyfactor orchestrators perform a variety of functions, including managing certificate stores and SSH key stores. in a subsequent email message. To limit the data to the first result (0) and only the ClientMachine name, in the email message you would enter the following:

  $(MyResponse.[0].ClientMachine)
• Verb: In the dropdown, select the type of request you wish to make (e.g. GET, POST).
• Use Basic Authentication: Check this box to use Basic authentication for the request. If you do not check this box, Windows authentication in the context of the Keyfactor Command application pool user will be used (see Create Service Accounts for Keyfactor Command).
• Username and [Password]: Enter the username and password to use for authentication if Use Basic Authentication is checked. In the Username and Password dialogs, the options are Load From Keyfactor Secrets or Load From PAM Provider.

  A Keyfactor secret is a user-defined password or other information that is encrypted and stored securely in the Keyfactor Command database. Although Keyfactor recommends using Privileged Access Management (see Privileged Access Management (PAM)) as a more secure solution to secure information, Keyfactor Secret is an option for customers that do not already have a relationship with a PAM provider such as CyberArk or Delinea.

  Important:  Keyfactor highly recommends that you use strong passwords for any accounts or certificates related to Keyfactor Command and associated products, especially when these have elevated or administrative access. A strong password has at least 12 characters (more is better) and multiple character classes (lowercase letters, uppercase letters, numeral, and symbols). Ideally, each password would be randomly generated. Avoid password re-use.

  Select the Load From Keyfactor Secrets radio button as the Secret Source if you want Keyfactor Command to encrypt and store the password in the Keyfactor Command database. Enter and confirm a password.

  Select the Load from PAM Provider radio button as the Secret Source if you want to store the password in a supported third-party PAM solution (see Privileged Access Management (PAM)). The remaining fields on the dialog will vary depending on the PAM provider. For example:

  CyberArk

  Select your CyberArk provider in the Providers dropdown if your PAM provider is CyberArk (see Adding or Modifying a PAM Provider). The remaining fields in the dialog will then be:

  • Safe—The name of the safe the credential resides in.
  • Object—The name of the username or password object in the safe.
  • Folder—The path and name of the folder that stores the object (e.g. Root or Root\MyDir).
  Delinea

  Select your Delinea provider in the Providers dropdown if your PAM provider is Delinea (see Adding or Modifying a PAM Provider). The remaining field in the dialog will then be:

  • Secret Server Secret ID—The numeric ID of the secret to retrieve from Secret Server.
  • Secret Field Name—The name of the field to use when retrieving a secret form Secret Server.
  Hashicorp

  Select your Hashicorp Vault provider in the Providers dropdown if your PAM provider is Hashicorp Vault (see Adding or Modifying a PAM Provider). The remaining field in the dialog will then be:

  • KV Secret Key—The key of the secret to retrieve from the Hashicorp Vault.
  • KV Secret Name—The name of the secret to retrieve from the Hashicorp Vault.
• URL: Enter the request URL for the request, including tokens if desired. For a Keyfactor API request, this might look like (with query parameters):
  https://keyfactor.keyexample.com/KeyfactorAPI/Certificates?pq.queryString=CN%20-contains%20%22appsrvr14%22%20AND%20CertStorePath%20-ne%20NULL

  Or, with tokens:

  https://keyfactor.keyexample.com/KeyfactorAPI/Certificates/$(certid)
  Note:  To prevent REST requests from being made to inappropriate locations by malicious users, configure a system environment variable of KEYFACTOR_BLOCKED_OUTBOUND_IPS on your Keyfactor Command server pointing to the IP address or range of addresses in CIDR format that you wish to block. Both IPv4 and IPv6 addresses are supported. More than one address or range may be specified in a comma-delimited list. For example:

  192.168.12.0/24,192.168.14.22/24

  When a REST request is made where the URL is either configured to a blocked IP address or resolves via DNS The Domain Name System is a service that translates names into IP addresses. to a blocked IP address, the REST request will fail.

• Content-Type: In the dropdown, select the content type for the request:

  • application/json

• Request Content: The request body of the REST request, if required, with tokens, if desired. For a Keyfactor API request, this will vary depending on the request and might look like (for a PUT /Certificates/Metadata request):

  Copy

  {
     "Id": "$(certid)",
     "Metadata":{
        "RevocationComment":"$(cmnt)"
     }
  }

  Note:  This example assumes you have a metadata field called RevocationComment (see Certificate Metadata).

For an example using a Keyfactor API endpoint An endpoint is a URL that enables the API to gain access to resources on a server. within a PowerShell script, see Use Custom PowerShell with Embedded REST Request, Send Email, and Require Approval. For an example using an Invoke REST Request and a PowerShell step passing data between them, see Invoke REST Request and Set Variable Data with Variable Passing.

# Declare your parameters at the beginning
param(
   [string]$Requester
)

#Convert the requester to JSON
$RequesterJSON = ($Requester | ConvertTo-Json)

# Build the query for the REST step
$Query = "Username -eq $RequesterJSON"

# Return the query to the workflow as a hashtable
$result = @{ "Query" = $Query }
return $result

Certificate Enrollment Request for $(request:cn)

Hello,

A certificate using the $(template) template was requested by $(requester:displayname) from $(CA) on $(subdate).

The certificate details include:

   <ul>
      <li>CN: $(request:cn)</li>
      <li>DN: $(request:dn)</li>
      <li>SANs: $(sans)</li>
      <li>App Owner First Name: $(metadata:AppOwnerFirstName)</li>
      <li>App Owner Last Name: $(metadata:AppOwnerLastName)</li>
   </ul>

The requester’s SSH information includes:

   <ul>
      <li>ID: $(MyResponse.Result[0].Key.Id)</li>
      <li>Email: $(MyResponse.Result[0].Key.Email)</li>
      <li>Comments: $(MyResponse.Result[0].Key.Comments.[*])</li>
   </ul>

Thanks!
Your Certificate Management Tool

This step type is used only for Keyfactor Command implementations using an identity provider other than Active Directory. If you’re using Active Directory, refer to the Invoke REST Request step type (see Invoke REST Request).

Tip:  Tokens (a.k.a. substitutable special text) may be used in the URL and request content fields. Tokens use a variable in the workflow definition that is replaced by data from the certificate request, certificate, or certificate metadata at processing time. For example, you can take the revocation comment entered when the revocation request is approved—$(cmnt)—and insert it into a custom metadata field in the certificate by doing a PUT /Certificates/Metadata request for the $(id). Fields that support tokens are indicated with at the top right of the field. To use a token in a field, begin typing at the location where you want the token to appear, starting with $(. Once you have typed $(, a second ) will appear automatically along with a dropdown of available tokens to choose from. You may continue typing to narrow the values in the dropdown (e.g. type $(req to see only tokens that begin “req”).

Figure 175: Tokens are Highlighted

• Headers: Enter any headers needed for your request. For a Keyfactor API request, this might look like:

  x-keyfactor-requested-with: APIClient
  x-keyfactor-api-version: 1
  Tip:  For a Keyfactor API request, version 1 is assumed if no version is specified. Content type and authorization headers do not need to be specified, since those are addressed elsewhere in the configuration.

• Variable to Store Response in: Provide a name for the parameter in which to store the response data from your request. You can then reference this parameter from subsequent steps in the workflow.

  Tip:  The response is stored as a serialized JObject. To make use of only a portion of the response data in your subsequent step, use JSON path syntax. For example, say you returned the data from a GET /Agents request in a variable called MyResponse and you wanted to reference the ClientMachine name for the orchestrator in a subsequent email message. To limit the data to the first result (0) and only the ClientMachine name, in the email message you would enter the following:

  $(MyResponse.[0].ClientMachine)
• Verb: In the dropdown, select the type of request you wish to make (e.g. GET, POST).
• Client ID: Enter the ID of the identity provider client that should be used to authenticate the session (see Authenticating to the Keyfactor API).

• Client Secret: Click the Set\UpdateClient Secret button and in the Client Secret dialog, enter the secret for the identity provider client that should be used to authenticate the session. In the Client Secret dialog, the options are Load From Keyfactor Secrets or Load From PAM Provider.

  A Keyfactor secret is a user-defined password or other information that is encrypted and stored securely in the Keyfactor Command database. Although Keyfactor recommends using Privileged Access Management (see Privileged Access Management (PAM)) as a more secure solution to secure information, Keyfactor Secret is an option for customers that do not already have a relationship with a PAM provider such as CyberArk or Delinea.

  Important:  Keyfactor highly recommends that you use strong passwords for any accounts or certificates related to Keyfactor Command and associated products, especially when these have elevated or administrative access. A strong password has at least 12 characters (more is better) and multiple character classes (lowercase letters, uppercase letters, numeral, and symbols). Ideally, each password would be randomly generated. Avoid password re-use.

  Select the Load From Keyfactor Secrets radio button as the Secret Source if you want Keyfactor Command to encrypt and store the password in the Keyfactor Command database. Enter and confirm a password.

  Select the Load from PAM Provider radio button as the Secret Source if you want to store the password in a supported third-party PAM solution (see Privileged Access Management (PAM)). The remaining fields on the dialog will vary depending on the PAM provider. For example:

  CyberArk

  Select your CyberArk provider in the Providers dropdown if your PAM provider is CyberArk (see Adding or Modifying a PAM Provider). The remaining fields in the dialog will then be:

  • Safe—The name of the safe the credential resides in.
  • Object—The name of the username or password object in the safe.
  • Folder—The path and name of the folder that stores the object (e.g. Root or Root\MyDir).
  Delinea

  Select your Delinea provider in the Providers dropdown if your PAM provider is Delinea (see Adding or Modifying a PAM Provider). The remaining field in the dialog will then be:

  • Secret Server Secret ID—The numeric ID of the secret to retrieve from Secret Server.
  • Secret Field Name—The name of the field to use when retrieving a secret form Secret Server.
  Hashicorp

  Select your Hashicorp Vault provider in the Providers dropdown if your PAM provider is Hashicorp Vault (see Adding or Modifying a PAM Provider). The remaining field in the dialog will then be:

  • KV Secret Key—The key of the secret to retrieve from the Hashicorp Vault.
  • KV Secret Name—The name of the secret to retrieve from the Hashicorp Vault.

• Token Endpoint: The URL of the token endpoint for your identity provider instance. For example:

  https://my-keyidp-server.keyexample.com/realms/Keyfactor/protocol/openid-connect/token

  For Keyfactor Identity Provider, this is included among the information that can be found on the OpenID Endpoint Configuration page, a link to which can be found on the Realm Settings page (see Configuring Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation).

• Scope: One or more scopes that are submitted with the token request, if desired. Multiple scopes should be separated by spaces.

  This value is not used for Keyfactor Identity Provider.

• Audience: An audience value that is submitted with the token request, if desired.

  This value is not used for Keyfactor Identity Provider.

• URL: Enter the request URL for the request, including tokens if desired. For a Keyfactor API request, this might look like (with query parameters):

  https://keyfactor.keyexample.com/KeyfactorAPI/Certificates?pq.queryString=CN%20-contains%20%22appsrvr14%22%20AND%20CertStorePath%20-ne%20NULL

  Or, with tokens:

  https://keyfactor.keyexample.com/KeyfactorAPI/Certificates/$(certid)
  Note:  To prevent REST requests from being made to inappropriate locations by malicious users, configure a system environment variable of KEYFACTOR_BLOCKED_OUTBOUND_IPS on your Keyfactor Command server pointing to the IP address or range of addresses in CIDR format that you wish to block. Both IPv4 and IPv6 addresses are supported. More than one address or range may be specified in a comma-delimited list. For example:

  192.168.12.0/24,192.168.14.22/24

  When a REST request is made where the URL is either configured to a blocked IP address or resolves via DNS to a blocked IP address, the REST request will fail.

• Content-Type: In the dropdown, select the content type for the request:

  • application/json

• Request Content: The request body of the REST request, if required, with tokens, if desired. For a Keyfactor API request, this will vary depending on the request and might look like (for a PUT /Certificates/Metadata request):

  Copy

  {
     "Id": "$(certid)",
     "Metadata":{
        "RevocationComment":"$(cmnt)"
     }
  }

  Note:  This example assumes you have a metadata field called RevocationComment (see Certificate Metadata).

For an example using a Keyfactor API endpoint within a PowerShell script, see Use Custom PowerShell with Embedded REST Request, Send Email, and Require Approval. For an example using an Invoke REST Request to do a data lookup on enrollment, see Invoke REST Request for Data Lookup on Enrollment.

# Declare your parameters at the beginning ($Comment, $Notes, $RevCode, $Date, and $RevokeBy)
param(
   [string]$Comment,
   [string]$Notes,
   [string]$RevCode,
   [datetime]$Date
   [string]$RevokeBy
)

# Append your additional text to the existing text in the metadata Notes field along with the revoker (removing
# the leading 'DOMAIN\' part), submission date, revocation code, and comment entered at revocation, 
# and beginning the entry with a newline.
$Notes += "`nRevoked on " + $Date.ToString("MMMM d, yyyy") + " by " + $RevokeBy.SubString($RevokeBy.IndexOf('\')+1) + " with revocation option '" + $RevCode + "' and comment '" + $Comment + "'."

# Return the updated metadata Notes value as MyNotes to the workflow as a hashtable
$result = @{ "MyNotes" = $Notes }
return $result

Tip:  Tokens (a.k.a. substitutable special text) may be used in the subject line, message and email recipient fields. Tokens use a variable in the workflow definition that is replaced by data from the certificate request, certificate, or certificate metadata at processing time. For example, you can select $(requester) in the workflow definition for an enrollment request and the email message will contain the specific certificate requester name instead of the variable $(requester). Fields that support tokens are indicated with at the top right of the field. To use a token in a field, begin typing at the location where you want the token to appear, starting with $(. Once you have typed $(, a second ) will appear automatically along with a dropdown of available tokens to choose from. You may continue typing to narrow the values in the dropdown (e.g. type $(req to see only tokens that begin “req”).

Figure 179: Tokens are Highlighted

• Minimum Approvals: Enter the minimum number of users who must approve the request to consider the request approved.
• Denial Email Subject: Enter the subject line for the email message that will be delivered if the request is denied, including tokens if desired.
• Denial Email Message: Enter the email message that will be delivered if the request is denied. The email message can be made up of regular text and tokens. If desired, you can format the message body using HTML. See Table 13: Tokens for Workflow Definitions for a complete list of available tokens.

• Denial Email Recipients: Click Add, enter a recipient for the denial email, and Save. Each email message can have multiple recipients. You can use specific email addresses and/or use tokens to replace an email address variable with actual email addresses at processing time. Available email tokens include:

  • $(requester:mail)

    The certificate requester, based on a lookup in Active Directory of the email address associated with the requester on the certificate.

    Note:  The $(requester:mail) substitutable special text token is only supported in environments using Active Directory as an identity provider.

  • Your custom email-based metadata field, which would be specified similarly to $(metadata:AppOwnerEmailAddress).

• Approval Email Subject: Enter the subject line for the email message that will be delivered if the request is approved, including tokens if desired.
• Approval Email Message: Enter the email message that will be delivered if the request is approved. The email message can be made up of regular text and tokens. If desired, you can format the message body using HTML. See Table 13: Tokens for Workflow Definitions for a complete list of available tokens.
• Approval Email Recipients: Click Add, enter a recipient for the approval email, and Save. Each email message can have multiple recipients. You can use specific email addresses and/or use tokens to replace an email address variable with actual email addresses at processing time. Available email tokens include:

  • $(requester:mail)

    The certificate requester, based on a lookup in Active Directory of the email address associated with the requester on the certificate.

    Note:  The $(requester:mail) substitutable special text token is only supported in environments using Active Directory as an identity provider.

  • Your custom email-based metadata field, which would be specified similarly to $(metadata:AppOwnerEmailAddress).

For an example using a require approval step with a condition, see Set Variable Data and Require Approval with a Condition.

# Declare your parameters at the beginning
param(
   [string]$StoreData,
   [string]$TimeData
)

# Pick one authentication mechanism for the Keyfactor API
# Basic authentication credentials to authenticate to the Keyfactor API
$user = 'KEYEXAMPLE\APIUser'
$pass = 'APIUserSuperSecretPassword'

# Encode Basic authentication credentials
$pair = "$($cred.Username):$($cred.GetNetworkCredential().Password)"
$encodedCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($pair))
$basicAuthValue = "Basic $encodedCreds"

# Token authentication credentials to authenticate to the Keyfactor API (uncomment the below 9 lines and update appropriately to use token authentication)
#$TokenBody = @{
#   grant_type = "client_credentials"
#   client_id = "Keyfactor-API-Workflow-User"
#   client_secret = "WorkflowAPIClientSecret"
#}
#$TokenHeaders = @{
#   'Content-Type' = 'application/x-www-form-urlencoded'
#}
#$TokenURL = "https://appsrvr18.keyexample.com:1443/realms/Keyfactor/protocol/openid-connect/token"

# Request token from Keyfactor Identity Provider for token authentication (uncomment the below line to use token authentication)
#$TokenValue = Invoke-RestMethod -Method Post -Uri $TokenURL -Headers $TokenHeaders -Body $TokenBody

# Pick an authentication type for the header
$headerAuth = $basicAuthValue
#$headerAuth = "Bearer " + $TokenValue.access_token

# Build the headers for the API request
$headers = @{
   "Authorization"=$headerAuth
   "Accept"="application/json"
   "x-keyfactor-requested-with"="APIClient"
}

# Convert incoming data from JSON
$StoreDataInfo = $StoreData | ConvertFrom-Json
$TimeDataInfo = $TimeData | ConvertFrom-Json

# Initialize Variables introduced in script
$JobTime = ""
$JobTimeHuman = ""
$TimeMessage = ""
$StoreMessage = ""
$StoreList = New-Object System.Collections.Generic.List[System.Object]
$CommandServer = 'keyfactor.keyexample.com'

# Evalulate the scheduled delivery time for the certificate store management job, if present, and populate a return message based on the content
if ("Immediate" -in $TimeDataInfo.PSobject.Properties.Name)
{
   $TimeMessage = "The certificate has been scheduled to be delivered at the next orchestrator run."
}
elseif ("ExactlyOnce" -in $TimeDataInfo.PSobject.Properties.Name)
{
   # Convert the certificate store job time to a human readable date/time
   $JobTime = [DateTime]($TimeDataInfo.ExactlyOnce.Time)
   $JobTimeHuman = $JobTime.ToString("M/dd/yyyy h:mm tt")
   $TimeMessage = "The certificate has been scheduled to be delivered at the following time: $JobTimeHuman."
}
else
{
   $TimeMessage = " "
}

# Pull out the display names of the certificate stores based on the store IDs in the incoming store info
foreach ($Store in $StoreDataInfo){
   $response = Invoke-WebRequest -Uri "https://$($CommandServer)/KeyfactorAPI/CertificateStores/$($store.StoreId)" -Method:Get -Headers $headers `
      -ContentType "application/json" -ErrorAction:Stop -TimeoutSec 60
   $responseContent = $response.Content | ConvertFrom-Json

   #Add the store to the store list
   $StoreList.Add($responseContent.DisplayName)
}

# Evaluate whether any stores were returned and build a message that includes the store list if so, and an alternate message if not
if ($StoreList.Count -gt 0)
{
   $StoreMessage = "If approved, the certificate will be delivered to the following stores:<br /><br />" + ($StoreList -join "<br />")
}
else
{
   $StoreMessage = "If approved, the certificate will be available for download in the Keyfactor Command Management Portal. It has not been scheduled for delivery to any certificate stores."
}

# Return the time message and store message to the workflow as a hashtable
$result = @{ "TimeMessage" = $TimeMessage; "StoreMessage" = $StoreMessage }
return $result

ACTION REQUIRED: Certificate Enrollment Request for $(request:cn)

Hello,

A certificate using the $(template) template was requested by $(requester:displayname) from $(CA) on $(subdate). $(StoreMessage)

$(TimeMessage) 

The certificate details include:

   <ul>
      <li>CN: $(request:cn)</li>
      <li>DN: $(request:dn)</li>
      <li>SANs: $(sans))</li>
      <li>App Owner First Name: $(metadata:AppOwnerFirstName)</li>
      <li>App Owner Last Name: $(metadata:AppOwnerLastName)</li>
   </ul>

Please review this request and issue the certificate as appropriate by going here:

$(reviewlink)

Thanks!
Your Certificate Management Tool

Certificate Enrollment Request Denied for $(request:cn)

Certificate Enrollment Request Approved for $(request:cn)

Hello $(requester:givenname),

The certificate you requested on $(subdate) in the name $(request:cn) has not been issued for the following reason:

$(approvalsignalcmnts)

The certificate details include:

   <ul>
      <li>CN: $(request:cn)</li>
      <li>DN: $(request:dn)</li>
      <li>SANs: $(sans))</li>
      <li>App Owner First Name: $(metadata:AppOwnerFirstName)</li>
      <li>App Owner Last Name: $(metadata:AppOwnerLastName)</li>
   </ul>

For assistance, please contact <a href="mailto:support@keyexample.com">support@keyexample.com</a>.

Thanks!
Your Certificate Management System

Hello $(requester:givenname),

The certificate you requested in the name $(request:cn) on $(subdate) was successfully approved with the following comment:

$(approvalsignalcmnts)

The certificate details include:

   <ul>
      <li>CN: $(request:cn)</li>
      <li>DN: $(request:dn)</li>
      <li>SANs: $(sans))</li>
      <li>App Owner First Name: $(metadata:AppOwnerFirstName)</li>
      <li>App Owner Last Name: $(metadata:AppOwnerLastName)</li>
   </ul>

You will receive an update when it has been issued. For assistance, please contact <a href="mailto:support@keyexample.com">support@keyexample.com</a>.

Thanks!
Your Certificate Management System

Tip:  Tokens (a.k.a. substitutable special text) may be used in the subject line, message and email recipient fields. Tokens use a variable in the workflow definition that is replaced by data from the certificate request, certificate, or certificate metadata at processing time. For example, you can select $(requester) in the workflow definition for an enrollment request and the email message will contain the specific certificate requester name instead of the variable $(requester). Fields that support tokens are indicated with at the top right of the field. To use a token in a field, begin typing at the location where you want the token to appear, starting with $(. Once you have typed $(, a second ) will appear automatically along with a dropdown of available tokens to choose from. You may continue typing to narrow the values in the dropdown (e.g. type $(req to see only tokens that begin “req”).

Figure 182: Tokens are Highlighted

• Subject: Enter the subject line for the email message that will be delivered when the workflow definition step is executed, including tokens if desired.

• Message: Enter the email message that will be delivered when the workflow definition step is executed. The email message can be made up of regular text and tokens. If desired, you can format the message body using HTML. For example, for an enrollment pending request notification:

  Copy

  Hello,
  A certificate using the $(template) template was requested by $(requester:displayname) from $(CA) on $(subdate). The certificate details include:
  
  <table>
  <tr><th>Certificate Details</th><th>Metadata</th></tr>
  <tr><td>CN: $(request:cn)</td><td>App Owner First Name: $(metadata:AppOwnerFirstName)</td></tr>
  <tr><td>DN: $(request:dn)</td><td>App Owner Last Name: $(metadata:AppOwnerLastName)</td></tr>
  <tr><td>SANs: $(sans)</td><td>App Owner Email Address: $(metadata:AppOwnerEmailAddress)</td></tr>
  <tr><td>&nbsp;</td><td>Business Critical: $(metadata:BusinessCritical)</td></tr>
  
  Please review this request and issue the certificate as appropriate by going here:
  
  $(reviewlink)
  
  Thanks!
  
  Your Certificate Management Tool

  See Table 13: Tokens for Workflow Definitions for a list of available tokens.

  Note:  The $(requester:displayname) substitutable special text token is only supported in environments using Active Directory as an identity provider.
• Recipients: Click Add, enter a recipient for the email, and Save. Each email message can have multiple recipients. You can use specific email addresses and/or use tokens to replace an email address variable with actual email addresses at processing time. Available email tokens include:

  • $(requester:mail)

    The certificate requester, based on a lookup in Active Directory of the email address associated with the requester on the certificate.

    Note:  The $(requester:mail) substitutable special text token is only supported in environments using Active Directory as an identity provider.

  • Your custom email-based metadata field, which would be specified similarly to $(metadata:AppOwnerEmailAddress).

For an example using Send Email in a Require Approval workflow, see Use Custom PowerShell with Embedded REST Request, Send Email, and Require Approval.

• Script Parameters: Add any parameters you will use to pass data into your script. These can contain static values or tokens (see Table 13: Tokens for Workflow Definitions). To add a parameter:

  1. In the Script Parameters section, click Add.

  2. In the Add/Edit Parameter dialog, enter a name for the parameter in the Parameter field. In the Value field, enter either a static value to be passed into the PowerShell script or select from the available tokens to pass the token value into the PowerShell in your parameter.

  3. Click Save to save your parameter.

  

  Figure 184: Add Parameters for PowerShell

• Insert PowerShell Script: Enter the PowerShell commands to execute. This should be the actual contents of the PowerShell script (the PowerShell commands and supporting components), not a path and filename to an external file.

  To receive your defined parameters from the previous step into the PowerShell script, begin the script by declaring the expected parameters like so (referencing the three parameters—TestOne, TestTwo, and TestThree):

  Copy

  param(
     [string]$TestOne,
     [int]$TestTwo,
     [string]$TestThree
  )

  You may then use these parameters within the script.

  To return data from the PowerShell script, create a hashtable of the data you wish to return like so (where $MyField1 and $MyField2 are parameters introduced within the script and the new value in $TestThree is reloaded back into that parameter and used to update that field if the original parameter was set to a token):

  Copy

  $result = @{ "MyFieldOne" = $MyField1; "MyFieldTwo" = $MyField2; "TestThree" = $TestThree }
  return $result

  This will result in the following dictionary entries being added to the database and available for output or use in subsequent steps in the workflow:

  Copy

  {["MyFieldOne", "[your value as defined in the script]", ["MyFieldTwo", "[your value as defined in the script]", ["TestThree", "[your value as defined in the script]",]}

  You can reference these as tokens in subsequent steps as follows: $(MyFieldOne), $(MyFieldTwo), $(TestThree).

# Declare your parameters at the beginning ($Comment, $SDate, and $Edate)
param(
   [string]$Comment,
   [datetime]$SDate,
   [datetime]$EDate
)

# Append your additional text to the existing comment along with the submission and effective dates
$Comment += " - Revocation requested on " + $SDate.ToString("g") + " and effective on " + $EDate.ToString("g")

# Return the updated comment to the workflow in the original parameter as a hashtable
$result = @{ "Comment" = $Comment }
return $result

# Declare your parameters at the beginning
param(
   [string]$AdditionalAttributes
)

# Trim brackets off incoming attribute string
$TrimmedAttributes = $AdditionalAttributes.Substring(1,$AdditionalAttributes.Length-2)

# Replace commas bracketed by quotes in attribute string with a temporary string to facilitate splitting (assumes no incoming values contain temp string)
$TempString = "`"######`""
$CleanAttributes = $TrimmedAttributes -replace "`",`"", $TempString

# Split the incoming attribute string into its component values at the temporary string
$SplitAttributes = $CleanAttributes.Split('######')

# Split the incoming attribute string key/value pairs
foreach($attribute in $SplitAttributes){
   $attributeComponents = $attribute.Trim() -split ":"
   $attributeComponents
   Switch($attributeComponents[0].Trim()){
      '"Department"' {$Department = $attributeComponents[1].Substring(1,$attributeComponents[1].Length-2)}
      '"Code"' {$Code = $attributeComponents[1].Substring(1,$attributeComponents[1].Length-2)}
   }
}

# Initialize a hashtable
$UpdatedAttributes = @{}

# Load original attributes in UpdatedAttributes for the else case
if(![string]::IsNullOrWhiteSpace($Code)) {
   $UpdatedAttributes['Code'] = $Code
}
if(![string]::IsNullOrWhiteSpace($Department)) {
   $UpdatedAttributes['Department'] = $Department
}

# If the value of Department is "Accounting", then the value of Code must be "G5N145"; override submitted value--if any--and use fixed value
if($UpdatedAttributes['Department'] -eq "Accounting") {
   $UpdatedAttributes['Code'] = "G5N145"
}

# Return the updated attributes to the workflow in the original parameter as a hashtable
$result = @{ "AdditionalAttributes" = $UpdatedAttributes }
return $result

• Script Parameters: Add any parameters you will use to pass data into your script. These can contain static values or tokens (see Table 13: Tokens for Workflow Definitions). To add a parameter:

  1. In the Script Parameters section, click Add.

  2. In the Add/Edit Parameter dialog, enter a name for the parameter in the Parameter field. In the Value field, enter either a static value to be passed into the PowerShell script or select from the available tokens to pass the token value into the PowerShell in your parameter.

  3. Click Save to save your parameter.

  

  Figure 189: Add Parameters for PowerShell

• PowerShell Script Name: The script contents are stored in the Keyfactor Command database. After uploading your script to the database, select a script from the dropdown on the step. All scripts in the database that have been configured for the workflow will be available for selection. See Extensions Scripts for information on adding scripts to the database. The file must be in JSON-escaped format and have an extension of .ps1. The script should use the same input and output method for parameters as described for the Set Variable Data step type (see Set Variable Data).

  Tip:  A sample PowerShell script, CustomPowershellExample.ps1, is provided in the workflow directory (default: C:\Program Files\Keyfactor\Keyfactor Platform\ExtensionLibrary\Workflow).

# Declare your parameters at the beginning ($InputCN, $Domain1, $Domain2, and $InputSANs)
param(
   [string]$InputCN,
   [string]$Domain1,
   [int]$Domain2,
   [string]$InputSANs
)

# Split the incoming SANs string into its component values
$SplitSANs = $InputSANs.Split(',')

# Initialize variables for the two types of SANs we're handling
$DnsSans = @()
$IpSans = @()

# Add the incoming SANs to the correct list (assumes only IPv4 addresses or DNS SANs will be encountered)
foreach($san in $SplitSANs){
   $sanComponents = $san.Trim() -split ":"
   Switch ($sanComponents[0].Trim()){
      "DnsName" {$DnsSans += ,$sanComponents[1].Trim()}
      "IPAddress" {$IpSans += $sanComponents[1].Trim()}
   }
}

# Check to see if the incoming CN ends with keyexample.com and, if so, add some SANs.
$Suffix = "keyexample.com"

if ($InputCN.EndsWith($Suffix))
{
   # Load just the portion of the CN without the domain name into a variable.
   $CNName = $InputCN.SubString(0,$InputCN.Length - $Suffix.Length)

   # Do a lookup on the requested CN to find its IPv4 address.
   $IPResult = Resolve-DnsName -Name $InputCN -Type A -ErrorAction SilentlyContinue

   # If an address is found, add that address as a SAN.
   # Also add SANs built with the contents of Domain1, Domain2, and the leading part of the CN
   # (e.g. mycert.my-first-other-domain.com and mycert.my-second-other-domain.com).
   if ($IPResult -ne $null)
   {
      $SAN1 = $IPResult.IPAddress
      $SAN2 = $CNName + $Domain1
      $SAN3 = $CNName + $Domain2
      $DnsSans += ,$SAN2
      $DnsSans += ,$SAN3
      $IpSans += ,$SAN1
   # If an IP address is not found, add only the SANs featuring Domain1 and Domain2.
   else {
      $SAN2 = $CNName + $Domain1
      $SAN3 = $CNName + $Domain2
      $DnsSans += ,$SAN2
      $DnsSans += ,$SAN3
   }
}

# Load the resulting IPv4 and DNS SANs into the SANS variable
$UpdatedSANs = @{}

if(![string]::IsNullOrWhiteSpace($DnsSans)) {
   $UpdatedSANs['dns'] = $DnsSans
}

if(![string]::IsNullOrWhiteSpace($IpSans)) {
   $UpdatedSANs['ip4'] = $IpSans
}

# Return the updated SANs to the workflow as a hashtable (case matters in the return value name "SANs" in order
# to reload the results back into the SANs token)
$result = @{ "SANs" = $UpdatedSANs; }
return $result

# Declare your parameters at the beginning
param(
   [string]$ApprovalComment,
   [string]$SignalComment,
   [string]$Metadata
)

# Initialize a hashtable to contain your metadata fields and populate it
$UpdatedMetadata = @{}
$jsonobject = $Metadata | ConvertFrom-Json
foreach( $property in $jsonobject.PSObject.Properties )
{
   $UpdatedMetadata[$property.Name] = $property.Value
}

# Append your signal comment(s) to any existing comment in the ApprovalComment metadata field
if([string]::IsNullOrWhiteSpace($ApprovalComment)) {
   $UpdatedMetadata['ApprovalComment'] = $SignalComment
}else {
   $UpdatedMetadata['ApprovalComment'] = $ApprovalComment + ", " + $SignalComment
}

# Return the updated metadata fields, including ApprovalComment, to the workflow in the original parameter as a hashtable
$result = @{ "ApprovalComment" = $UpdatedMetadata }
return $result

This step is used to create a new signed CSR to prepare an updated enrollment request for delivery to a Microsoft CA after a previous step in the workflow has been used to update either the SANs in the initial request, subject (DN A distinguished name (DN) is the name that uniquely identifies an object in a directory. In the context of Keyfactor Command, this directory is generally Active Directory. A DN is made up of attribute=value pairs, separated by commas. Any of the attributes defined in the directory schema can be used to make up a DN.) in the initial request or both. This step must be placed later in the workflow than the step(s) that modify the SANs and/or subject. The SANs and subject may be modified with either of the PowerShell step types (see Set Variable Data and Use Custom PowerShell) or a custom step type. This step is used for both PFX enrollment and CSR enrollment, since both use a CSR that is generated at the start of the workflow. A Microsoft CA will not accept a CSR for enrollment if the subject has been modified and will only accept a CSR for enrollment with modified SANs if the EDITF_ATTRIBUTESUBJECTALTNAME2 flag has been enabled on the CA—a security risk Keyfactor does not recommend. EJBCA doesn’t support enroll on behalf of (EOBO A user with an enrollment agent certificate can enroll for a certificate on behalf of another user. This is often used when provisioning technology such as smart cards.), so this step type does not apply to EJBCA CAs. EJBCA is able to handle subject and SAN changes without the need for this type of step based on end entity profile constraints.

• Enrollment Agent Certificate: Click Browse to search for the desired base-64 encoded PKCS#12 A PFX file (personal information exchange format), also known as a PKCS#12 archive, is a single, password-protected certificate archive that contains both the public and matching private key and, optionally, the certificate chain. It is a common format for Windows servers. (.PFX) enrollment agent certificate with private key Private keys are used in cryptography (symmetric and asymmetric) to encrypt or sign content. In asymmetric cryptography, they are used together in a key pair with a public key. The private or secret key is retained by the key's creator, making it highly secure. to sign the CSR. This can be either a user certificate or a computer certificate and must have a Certificate Request Agent EKU.

• Set Private Key Password: The password for the enrollment agent certificate. Click Set Private Key Password to open the Private Key Password dialog. Choose the No Value checkbox to not assign a password, or choose from Load From Keyfactor Secrets or Load From PAM Provider.

  A Keyfactor secret is a user-defined password or other information that is encrypted and stored securely in the Keyfactor Command database. Although Keyfactor recommends using Privileged Access Management (see Privileged Access Management (PAM)) as a more secure solution to secure information, Keyfactor Secret is an option for customers that do not already have a relationship with a PAM provider such as CyberArk or Delinea.

  Important:  Keyfactor highly recommends that you use strong passwords for any accounts or certificates related to Keyfactor Command and associated products, especially when these have elevated or administrative access. A strong password has at least 12 characters (more is better) and multiple character classes (lowercase letters, uppercase letters, numeral, and symbols). Ideally, each password would be randomly generated. Avoid password re-use.

  Select the Load From Keyfactor Secrets radio button as the Secret Source if you want Keyfactor Command to encrypt and store the password in the Keyfactor Command database. Enter and confirm a password.

  Select the Load from PAM Provider radio button as the Secret Source if you want to store the password in a supported third-party PAM solution (see Privileged Access Management (PAM)). The remaining fields on the dialog will vary depending on the PAM provider. For example:

  CyberArk

  Select your CyberArk provider in the Providers dropdown if your PAM provider is CyberArk (see Adding or Modifying a PAM Provider). The remaining fields in the dialog will then be:

  • Safe—The name of the safe the credential resides in.
  • Object—The name of the username or password object in the safe.
  • Folder—The path and name of the folder that stores the object (e.g. Root or Root\MyDir).
  Delinea

  Select your Delinea provider in the Providers dropdown if your PAM provider is Delinea (see Adding or Modifying a PAM Provider). The remaining field in the dialog will then be:

  • Secret Server Secret ID—The numeric ID of the secret to retrieve from Secret Server.
  • Secret Field Name—The name of the field to use when retrieving a secret form Secret Server.
  Hashicorp

  Select your Hashicorp Vault provider in the Providers dropdown if your PAM provider is Hashicorp Vault (see Adding or Modifying a PAM Provider). The remaining field in the dialog will then be:

  • KV Secret Key—The key of the secret to retrieve from the Hashicorp Vault.
  • KV Secret Name—The name of the secret to retrieve from the Hashicorp Vault.

# Declare your parameters at the beginning
param(
   [string]$CSRSubject,
   [string]$CSRSANs,
   [string]$OriginalDomain,
   [string]$NewDomain
)

# Split the incoming SANs string into its component values
$SplitSANs = $CSRSANs.Split(',')

# Initialize variables for the two types of SANs we're handling
$DnsSANs = @()
$IpSANs = @()

# Add the incoming SANs to the correct list (assumes only IPv4 addresses or DNS SANs will be encountered)
foreach($san in $SplitSANs){
   $sanComponents = $san.Trim() -split ":"
   Switch ($sanComponents[0].Trim()){
      "DnsName" {$DnsSANs += ,$sanComponents[1].Trim()}
      "IPAddress" {$IpSANs += $sanComponents[1].Trim()}
   }
}

# Load original SANs in UpdatedSANs for the else case
$UpdatedSANs = @{}

if(![string]::IsNullOrWhiteSpace($DnsSANs)) {
   $UpdatedSANs['dns'] = $DnsSANs
}

if(![string]::IsNullOrWhiteSpace($IpSANs)) {
   $UpdatedSANs['ip4'] = $IpSANs
}

# Load original subject in NewSubject for the else case
$NewSubject = $CSRSubject

# Replace escaped commas in the subject temporarily with a string to facilitate splitting
$TempString = "######"
$CleanSubject = $CSRSubject -replace "\\,", $TempString

# Split the incoming Subject string into its component values
$SplitSubject = $CleanSubject.Split(',')

# Initialize variables for the components of the subject
$SubjectCN = @()
$SubjectO = @()
$SubjectOU = @()
$SubjectL = @()
$SubjectST = @()
$SubjectC = @()
$SubjectE = @()

# Load subject values
foreach($element in $SplitSubject){
   $SplitElement = $element.Split('=')
   Switch($SplitElement[0]){
      "CN" {$SubjectCN = $SplitElement[1]}
      "O" {$SubjectO = $SplitElement[1]}
      "OU" {$SubjectOU = $SplitElement[1]}
      "E" {$SubjectE = $SplitElement[1]}
      "L"{$SubjectL = $SplitElement[1]}
      "ST"{$SubjectST = $SplitElement[1]}
      "C"{$SubjectC = $SplitElement[1]}
   }
}

# Check to see if the incoming CN ends with $OriginalDomain and, if so, add it as a SAN with $NewDomain and update the Subject with $NewDomain (assumes non-null CN)
if ($SubjectCN.EndsWith($OriginalDomain))
{
   # Load just the portion of the CN without the domain name into a variable.
   $CNName = $SubjectCN.SubString(0,$SubjectCN.Length - ($OriginalDomain.Length + 1)) # +1 to account for the '.'

   # Build new DNS SAN
   $NewSAN = $CNName + "." + $NewDomain

   # Add new SAN to DNS SANs
   $DnsSans += ,$NewSAN

   # Build new Subject with $NewDomain
   $NewSubject = "";

   if(![string]::IsNullOrWhiteSpace($SubjectCN)){
      $NewSubject += "CN=" + $CNName + "." + $NewDomain + ","
   }

   if(![string]::IsNullOrWhiteSpace($SubjectO)){
      $NewSubject += "O=" + $SubjectO + ","
   }

   if(![string]::IsNullOrWhiteSpace($SubjectOU)){
      $NewSubject += "OU=" + $SubjectOU + ","
   }

   if(![string]::IsNullOrWhiteSpace($SubjectL)){
      $NewSubject += "L=" + $SubjectL + ","
   }

   if(![string]::IsNullOrWhiteSpace($SubjectST)){
      $NewSubject += "ST=" + $SubjectST + ","
   }

   if(![string]::IsNullOrWhiteSpace($SubjectC)){
      $NewSubject += "C=" + $SubjectC + ","
   }

   if(![string]::IsNullOrWhiteSpace($SubjectE)){
      $NewSubject += "E=" + $SubjectE + ","
   }

   $NewSubject = $NewSubject.Remove($NewSubject.Length - 1) # remove the last ','

   # Replace temporary string with escaped commas in Subject
   $NewSubject = $NewSubject -replace $TempString, "\,"

   # Load the resulting IPv4 and updated DNS SANs into the SANs variable
   $UpdatedSANs = @{}

   if(![string]::IsNullOrWhiteSpace($DnsSANs)) {
      $UpdatedSANs['dns'] = $DnsSANs
   }

   if(![string]::IsNullOrWhiteSpace($IpSANs)) {
      $UpdatedSANs['ip4'] = $IpSANs
   }
}

# Return the updated subject and SANs as NewSubject and NewSANs to the workflow as a hashtable
$result = @{ "Subject" = $NewSubject; "SANs" = $UpdatedSANs }
return $result

This step is needed for any Keyfactor Windows Enrollment Gateway requests where the incoming template A certificate template defines the policies and rules that a CA uses when a request for a certificate is received. (the template from the client side) is configured to build the subject of the certificate request from Active Directory. It has no configuration parameters.