Workflow Definition Operations

The workflow builder workspace is laid out with the workflow steps running from top to bottom in the middle (initially), the Workflow Definition dialog in a collapsible window on the right, and workspace controls at the bottom left. If you create several steps in a workflow or are working on a smaller browser screen, you may have more workflow steps than will fit in the configuration window. To navigate around the workspace and personalize it:

• Click and drag the workspace background to move the steps around the workspace. In this way you can reach steps at the top or bottom of the workflow that do not initially appear.

• Click the open button () to open the Workflow Definition dialog and the close button () to close the Workflow Definition dialog.

• Click the plus button with a circle around it () to add a new workflow step at that point in the workflow.

• Click the plus button in the lower left of the workspace () to zoom in on the steps.

• Click the minus button in the lower left of the workspace () to zoom out on the steps.

• Click the auto size button in the lower left of the workspace () to recenter and fit the steps to the window.

To add a new workflow definition or modify an existing one:

1. In the Management Portal, browse to Workflow > Workflow Definitions.

2. On the Workflow Definitions page, click Add from the top menu to create a new blank workflow definition, Copy from either the top or right click menu to copy an existing workflow to create a new one, or Edit from either the top or right click menu, to modify an existing one. This will open the workflow in the workflow builder workspace with the Workflow Definition dialog open on the right.

   Note:  When you create a new workflow definition by copying an existing one, the word "copy" will be appended to the end of the definition name and the workflow key (template A certificate template defines the policies and rules that a CA uses when a request for a certificate is received.) will be cleared. Other data from the copied workflow will be retained.

3. In the Add/Edit Workflow Definition dialog on the Definition tab, enter a Name for your workflow.

   

   Figure 149: Create a New Workflow Definition

4. In the Description field, enter a description for the workflow definition.
5. In the Type dropdown, select the type of requests this workflow will handle. The following types are supported:
   • Enrollment (including renewals)
   • Revocation

   The workflow type cannot be changed on an edit.

6. Once you have selected a type, a Templates field will appear. Begin typing in the Templates field to search for available templates or click in the field and scroll down to locate your desired template. Templates that have been configured with a template friendly name will appear by friendly name. The template cannot be changed on an edit.

   Note:  Only one workflow definition can be created for each combination of Workflow Type and Key (Template). In other words, you cannot have two enrollment or revocation workflow definitions for the same template, though you can have one enrollment workflow definition and one revocation workflow definition for a given template.
   Tip:  A given custom workflow can only apply to one certificate template. If you need to run the same custom workflow steps for more than one template, you can either add these steps to the global workflow or, if you want to run the steps for more than one type of enrollment or revocation but not all, you can configure one custom workflow and then export and re-import that workflow to duplicate it (see Importing or Exporting a Workflow Definition) and edit the copy to change the template.

7. On the Workflow Configuration page, click the plus button in between two workflow steps where you want to add a new step. A new step box will be added below the plus that you clicked.

   

   Figure 150: Click Plus to Add a New Workflow Definition Step

   Tip:  To delete a step, click the X at the top right of the step box and confirm that you want to delete the step.
8. Click the new step box to load the step in the Add/Edit Workflow Definition dialog. If the dialog is not already open, clicking a step will open it, or you can open a step by clicking the open button () and then clicking the desired step to load it into the dialog.

9. In the Add/Edit Workflow Definition dialog on the Step tab in the General section, select a Step Type for the step in the dropdown. To narrow the list of step types in the dropdown, begin typing a search string in the Search field. The built-in types are:

   • Send Email

     Send an email message. This is a separate email message from those typically sent as part of a Require Approval step. You might send an email message as part of an enrollment request to notify approvers that a new request needs approval. The email messages can be customized to provide detailed information about, for example, the certificate request.

   • Set Variable Data

     Run PowerShell commands within the confines of the workflow to populate variables with information to pass back to the workflow. The PowerShell script contents are embedded within the step. This step does not call out to an external file. This provides a high level of security by greatly limiting the number of standard PowerShell cmdlets that can be executed by the workflow step. A small number of PowerShell cmdlets have been white listed to allow them to be included in workflow steps of this type, including:

     • Where-Object
     • ForEach-Object

     • Get-Command

   • Use Custom PowerShell

     Run a PowerShell script. The script contents are in a file placed in the ExtensionLibrary\Workflow directory or a subdirectory of it on the Keyfactor Command server under the install directory for Keyfactor Command. By default, this is:

     C:\Program Files\Keyfactor\Keyfactor Platform\ExtensionLibrary\Workflow

     The file must have an extension of .ps1. A sample PowerShell script is provided in the Workflow directory (CustomPowershellExample.ps1).

   • Require Approval

     Require approval for a workflow step before the step can be completed. The require approval step applies to certificate enrollments, renewals, and revocations and can require approval from just one approver or multiple approvers. The workflow will be suspended at this point until the correct number of approvals from users with the correct security roles is received or until one deny is received before continuing to the next step. As part of this step, an email message is sent indicating whether the step was approved or denied—typically to the requester. This step does not include logic to send an email initiating the approval process (letting users know something needs approval). Use a Send Email type step for this.

     Important:  Workflows are not supported with CA A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA. delegation when they contain steps that require approval. For more information, see the CA configuration Authorization Methods Tab.
     Note:  The users that you send email to initiating the approval process must be members of a security role that is allowed to submit signals (approve/deny) for the workflow in order to approve or deny the request.
     Tip:  The workflow builder does not include a step to send a notification to the requester of a certificate once the certificate is issued by the CA (as opposed to approved in Keyfactor Command). Use the issued alerts for this (see Issued Request Alert Operations).

   • Invoke REST Request

     Run a REST (API) request. The REST request contents are embedded within the step. It does not call out to an external file.

   • Update Certificate Request Subject\SANs for Microsoft CAs

     On an enrollment (either CSR A CSR or certificate signing request is a block of encoded text that is submitted to a CA when enrolling for a certificate. When you generate a CSR within Keyfactor Command, the matching private key for it is stored in Keyfactor Command in encrypted format and will be married with the certificate once returned from the CA. or PFX 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.), create a resigned 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) to modify the SANs and/or subject. The SANs and subject may be modified with either of the PowerShell step types or a custom step type. The step creates a new CSR using the same public key In asymmetric cryptography, public keys are used together in a key pair with a private key. The private key is retained by the key's creator while the public key is widely distributed to any user or target needing to interact with the holder of the private key. as the original CSR using the updated SAN The subject alternative name (SAN) is an extension to the X.509 specification that allows you to specify additional values when enrolling for a digital certificate. A variety of SAN formats are supported, with DNS name being the most common. and/or subject values. It signs the new CSR with the certificate provided in the step's configuration.

     For this type of step you will need an enrollment agent certificate available as a 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) file with included 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 import into Keyfactor Command. This can be a user certificate or a computer certificate (e.g. generated from a copy of the "Enrollment Agent" template or the "Enrollment Agent (Computer)" template) and must have a Certificate Request Agent EKU. Note that the built-in "Enrollment Agent" and "Enrollment Agent (Computer)" templates do not allow private keys to be exported by default. You will need a template that allows private key export or will need to manually override private key export to create a certificate with an exportable private key in order to create a PKCS#12 (.PFX) file.

     Important:  This step applies to Microsoft CAs only. If this step is added to workflow for requests directed to an EJBCA CA, it will fail on enrollment. Note that EJBCA supports submission of updated SAN or subject details as part of standard functionality.

   • Windows Enrollment Gateway - Populate from AD

     On an enrollment done through the Keyfactor Windows Enrollment Gateway using a client-side template configured with the Build from this Active Directory information option on the template, this workflow step handles formatting the incoming subject, SANs, and/or SID in the certificate request appropriately such that the enrollment will complete successfully with the target CA and Keyfactor Command template, which is not configured to build from AD. Any Keyfactor Windows Enrollment Gateway using a client-side template configured with the subject as Build from this Active Directory information must be configured with a workflow step of this type on the Keyfactor Command template that has been mapped in the gateway to that template in order to complete an enrollment through the gateway. There are no configuration parameters for the step.

     Important:  The template in Keyfactor Command that is mapped to the client-side template configured to build the subject from Active Directory also needs to be configured with three enrollment fields to support handling the incoming subject, SANs, and/or SID. For more information about configuring this, see the Keyfactor Windows Enrollment Gateway Installation and Configuration Guide.

   

   Figure 151: Select a Workflow Definition Step

10. In the Add/Edit Workflow Definition dialog on the Step tab in the General section, enter a Display Name for the step. This name appears as the title of the step box on the workflow workspace page.

    

    Figure 152: Display Name is Step Name Title

11. In the Add/Edit Workflow Definition dialog on the Step tab in the General section, either accept the automatically generated Unique Name for the step or modify it. This name must be unique among the steps within the particular workflow. It is intended to be used as a user-friendly reference ID.

12. In the Add/Edit Workflow Definition dialog on the Step tab in the Workflow Step Execution Conditions section, click the Workflow Step Enabled toggle to enable or disable the workflow. It is enabled by default.

13. In the Add/Edit Workflow Definition dialog on the Step tab in the Workflow Step Execution Conditions section, click Add in the Optional Workflow Step Conditions for Execution section to create a new condition for the step. Conditions are true/false statements indicating whether the step should run and can be based on tokens.

    Tip:  Tokens (a.k.a. substitutable special text) may be used in the condition field. 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 create a token in a PowerShell step that has a value of True or False based on something determined in the step and then evaluate that token in a subsequent require approval step to determine whether to execute the require approval step based on the results from the PowerShell step. 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 153: Tokens are Highlighted

    To add a new condition, click Add and in the Condition Variable field enter either a static value of True or False or a token that will have a value of True or False at the time the step is run. More than one condition may be added. If multiple conditions are used in the same step, all conditions must have a value of True at the time the step is evaluated to be run in order for the step to run. If any single condition evaluates to False, the step will not run.

    Example:  The following example takes the common name A common name (CN) is the component of a distinguished name (DN) that represents the primary name of the object. The value varies depending on the type of object. For a user object, this would be the user's name (e.g. CN=John Smith). For SSL certificates, the CN is typically the fully qualified domain name (FQDN) of the host where the SSL certificate will reside (e.g. servername.keyexample.com or www.keyexample.com). entered during an enrollment and evaluates it to determine whether the domain name on it matches "keyexample.com" or not. If the domain is "keyexample.com", the enrollment is allowed to proceed without requiring approval. If the domain does not match "keyexample.com", the request requires approval. This example uses both a PowerShell Set Variable Data step and a Require Approval step.

    To do this, first create the PowerShell step. Here we use a Set Variable Data step (see Set Variable Data) since no functions need to be called outside the confines of Keyfactor Command, though you could use a Custom PowerShell Script step instead. Add a Script Parameter A parameter or argument is a value that is passed into a function in an application. to pull the request CN A common name (CN) is the component of a distinguished name (DN) that represents the primary name of the object. The value varies depending on the type of object. For a user object, this would be the user's name (e.g. CN=John Smith). For SSL certificates, the CN is typically the fully qualified domain name (FQDN) of the host where the SSL certificate will reside (e.g. servername.keyexample.com or www.keyexample.com). into the script.

    

    Figure 154: Conditions Example: Add Parameters

    In the Insert PowerShell Script field, enter a script similar to the following:

    # Declare your parameter at the beginning
    param(
    [string]$SubjectCN
    )
    
    # Initialize a variable for the response
    $shouldRun = @()
    
    # Check to see if the requested CN ends with keyexample.com and require approval in the next step if it does not
    $Suffix = "keyexample.com"
    
    if ($SubjectCN.EndsWith($Suffix))
    {
       $shouldRun = "False"
    }else {
       $shouldRun = "True"
    }
    
    # Return the true/false value to the workflow as a hashtable
    $result = @{ "shouldRun" = $shouldRun; }
    return $result

    Next, create the require approval request step (see Require Approval) with $(shouldRun) as a condition like so:

    

    Figure 155: Conditions Example: Add Conditions for Require Approval Step

    This condition on the require approval step will cause the approvals configured in the step to be required only if the CN submitted in the request does not end with "keyexample.com", so a request for "CN=mycert.keyother.com" will require approval but a request for "CN=mycert.keyexample.com" will not.

14. The fields in the Configuration Parameters section of the Add/Edit Workflow Definition dialog on the Step tab will vary depending on the type of step you're configuring.

    Tip:  To open a pop-out dialog with more real-estate for editing content in large text areas, like scripts and email messages:

    1. Navigate to the field you want to edit on the workflow definition.

    2. Click at the top right above the large text field.

    3. An Edit Content or Edit PowerShell window will open to accept your input. The Edit Content window supports token replacement. The Edit PowerShell window will open with a text editor. Enter your information.

    4. Click at the top right to close the edit window and return to the workflow definition, populated with your text.

       

       Figure 156: Edit PowerShell Window

       

       Figure 157: Edit Content Window

    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 158: 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 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 Active Directory Service Accounts for Keyfactor Command in the Keyfactor Command Server Installation Guide).
    • 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 (formerly Thycotic).

      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.

      CyberArk

      Select CyberArk in the Providers dropdown if your PAM provider is CyberArk. The remaining fields in the dialog will then be:

      • PrivateArk Protected Password Name—The name of the username or password in the safe (see Create a CyberArk Password).
      • PrivateArk Folder Name—The path and name of the folder that stores the CyberArk Password (e.g. Root or Root\MyDir).
      Delinea (formerly Thycotic)

      Select Delinea in the Providers dropdown if your PAM provider is Delinea. The remaining field in the dialog will then be:

      • Delinea Secret ID—The numeric ID of the secret to retrieve from Secret Server (see Create a Delinea Secret Server Secret).
    • 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):

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

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

    

    Figure 159: Configuration Parameters for an Invoke REST Request Workflow Definition Step

    Example:  The following example takes the revocation comment entered when a certificate is revoked and puts it together with some other information into a custom metadata field, retaining any existing data in that metadata field. This example uses both a PowerShell step and a REST Request step to demonstrate passing of information from one step to the other.

    To do this, first create the PowerShell step. Here we use a Set Variable Data step (see Set Variable Data) since no functions need to be called outside the confines of Keyfactor Command, though you could use a Custom PowerShell Script step instead. Add Script Parameters to pull the revocation comment, submission date, revocation code, user making the revocation request, and the metadata field into which you will place your updated comment ("Notes" in this example) into the script. Figure 160: Metadata Update Example: Add Parameters shows only four of these. The metadata field "Notes" is a BigText type field in this example (see Metadata Field Operations).

    

    Figure 160: Metadata Update Example: Add Parameters

    In the Insert PowerShell Script field, enter a script similar to the following:

    # 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

    Next, create the REST request step with the following values:

    • Headers:

      {
         "x-keyfactor-requested-with": [
            "APIClient"
         ]
      }

      

      Figure 161: Metadata Update Example: Add Headers for REST Request

    • Variable to Store Response in: None (there is no output from this command on a success)

    • Verb: PUT

    • URL: (Where keyfactor.keyexample.com is your Keyfactor Command server name.)

      https://keyfactor.keyexample.com/KeyfactorAPI/Certificates/Metadata

    • Content-Type: application/json

    • Request Content:

      {
         "Id": "$(certid)",
         "Metadata": {
            "Notes": "$(MyNotes)"
         }
      }

    This REST step takes the MyNotes output from the PowerShell step and updates the metadata Notes field to match that value. The resulting value in your Notes field will look something like this (assuming lines one, two and three were preexisting):

    

    Figure 162: Metadata Update Example: Results

    Note:  You can achieve this same result of updating a metadata field entirely within PowerShell without using the REST step. This example uses both PowerShell and REST steps to demonstrate passing a value from one to the other.

    Note:  If your REST request takes a long time to complete, the step may time out and the workflow instance fail. The default timeout is 60 seconds and is configurable with the Workflow Step Run Timeout application setting (see Application Settings: Workflow Tab).
    Require Approval

    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 163: Tokens are Highlighted

    Note:  The users who will approve or deny the request must be members of a security role that is allowed to submit signals (e.g. approve requests) for the workflow in order to approve or deny the request.

    • 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 15: 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.

      • 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 15: 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.

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

    Tip:  The approval message is delivered before the enrollment actually takes place. To send an email alerting interested parties that the certificate was issued, including a link to download the certificate, use an issued certificate alert (see Issued Certificate Request Alerts).

    

    Figure 164: Configuration Parameters for a Require Approval Workflow Definition Step

    Send Email

    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 165: 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:

      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 15: Tokens for Workflow Definitions for a complete list of available tokens.

    • 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.

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

    

    Figure 166: Step Configuration for an Email Workflow Definition Step

    Set Variable Data

    Tip:  Tokens (a.k.a. substitutable special text) may be used in the script parameter value field. 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 append additional data to it using PowerShell.

    • Script Parameters: Add any parameters you will use to pass data into your script. These can contain static values or tokens (see Table 15: 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 167: 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):

      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):

      $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:

      {["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).

    

    Figure 168: Configuration Parameters for a Set Variable Data Workflow Definition Step

    Example:  The following example takes the revocation comment entered when a certificate is revoked and appends an additional comment, including dates, to it. To create this, add Script Parameters to pull the revocation comment, submission date and effective date into the script as shown in Figure 160: Metadata Update Example: Add Parameters.

    

    Figure 169: Revocation Comment Update Example: Add Parameters

    In the Insert PowerShell Script field, enter a script similar to the following:

    # 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

    The resulting comment will look something like:

    

    Figure 170: Revocation Comment Update Example: Results

    You may reference the updated comment using the standard revocation comment token ($(cmnt)) in subsequent steps in your workflow and may view the updated comment wherever the revocation comment is available for viewing within Keyfactor Command.

    Example:  The following example takes two additional enrollment fields submitted on an enrollment and sets the value of one to a fixed value if the value of the other (a multi-value field) is a given value. In other words, the possible values for Department (a multi-value field) are:

    • Accounting
    • E-Commerce
    • HR
    • IT
    • Marketing
    • R & D
    • Sales

    If the value of Department is anything other than Accounting, the value of Code (a string field) can be any value. If the value of Department is Accounting, anything submitted in the Code field by the end user is discarded and replaced by the fixed value for Code provided in the script.

    This example provides a solution using a Set Variable Data step type, which necessitates manually unpacking the JSON attribute string. One possible method of doing this is provided in the example. If you prefer, you may instead use a Use Custom PowerShell step with the ConvertFrom-Json cmdlet similarly to the example for putting approval comments in a metadata field and avoid the manual string manipulation steps.

    To create this, add Script Parameters to pull the additional attributes into the script as shown in Figure 171: Additional Attribute Update Example: Add Parameters

    

    Figure 171: Additional Attribute Update Example: Add Parameters

    In the Insert PowerShell Script field, enter a script similar to the following:

    # 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

    The updated attributes will be submitted to the CA as part of the enrollment package and can be viewed in the workflow instance (see Viewing a Workflow Instance).

    Use Custom PowerShell

    Tip:  Tokens (a.k.a. substitutable special text) may be used in the script parameter value field. 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 append additional data to it using PowerShell.

    • Script Parameters: Add any parameters you will use to pass data into your script. These can contain static values or tokens (see Table 15: 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 172: Add Parameters for PowerShell

    • PowerShell Script Name: Select a script in the dropdown. The script needs to be in the ExtensionLibrary\Workflow directory or a subdirectory of it on the Keyfactor Command server under the install directory. By default, this is:

      C:\Program Files\Keyfactor\Keyfactor Platform\ExtensionLibrary\Workflow

      The file must 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). A sample PowerShell script is provided in the Workflow directory (CustomPowershellExample.ps1).

    

    Figure 173: Step Configuration for a Custom PowerShell Workflow Definition Step

    Example:  The following example takes the common name entered during an enrollment and evaluates it to determine whether the domain suffix ends with "keyexample.com". If it does, the script does a DNS lookup of the full CN to find the IPv4 address for that name and, if found, adds that value as a SAN to the request. Two additional SANs are added to the request by removing the "keyexample.com" domain suffix and instead appending the domain suffixes provided in the Domain1 and Domain2 parameters (e.g. mycert.keyother.com and mycert.keyother2.com). If the CN does not have a domain suffix ending with "keyexample.com", the PowerShell script does nothing.

    This step needs to be a Use Custom PowerShell step rather than a Set Variable Data step because it calls a PowerShell command (Resolve-DnsName) that exists outside the confines of Keyfactor Command.

    To create this, add Script Parameters to pull the CN and SANs into the script as shown in Metadata Update Example: Add Parameters and add to static values to pass in your two additional domain names.

    

    Figure 174: Update SANs Example: Add Parameters

    In the PowerShell Script Name field, in the dropdown select the script containing content similar to the following:

    # 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

    Your enrollment will complete using the updated list of SANs, including any SANs you added manually on the PFX enrollment page or in the CSR. You may reference the updated SANs using the standard SANs token ($(sans)) in subsequent steps in your workflow and may view the complete SAN list wherever the SANs are available for viewing within Keyfactor Command.

    Note:  If you're using a Microsoft CA, in order to add SANs in the workflow you will need to do one of the following:

    • Include an Update Certificate Request Subject\SANs step in your workflow (see Update Certificate Request Subject\SANs for Microsoft CAs). This is Keyfactor's preferred solution for workflow due to the limited risk profile.
    • Use Keyfactor's SAN Attribute Policy Handler (see Installing the Keyfactor CA Policy Module Handlers). This opens security risks as well, which can be mitigated, however, this is not Keyfactor's preferred solution for workflow.
    • Configure your CA to support the addition of SANs outside the initial request (enable the EDITF_ATTRIBUTESUBJECTALTNAME2 flag). Keyfactor does not recommend this solution due to the inherent security risks.

    Example:  The following example takes the approval comment entered when a certificate is enrolled or the approval or denial comment entered when a certificate is revoked using a require approval step and stores the comment in a metadata field. There will be no certificate to associate the metadata field with for an enrollment request that is denied. Normally, approval and denial comments are discarded after a workflow instance is complete, so this allows the comment to be retained.

    To create this, after the Require Approval step(s) in the workflow, add a Use Custom PowerShell step. A Use Custom PowerShell step is used here because we are calling the external command ConvertFrom-Json. If you wanted to use a Set Variable Data step instead, you would need to go through a process of extracting all your metadata values from the incoming metadata string and placing them in a hashtable instead of using ConvertFrom-Json (see the additional attributes example).

    In the Use Custom PowerShell step, add Script Parameters to pull any approval comments and the metadata field you're planning to store them in (in this example, a field called ApprovalComments) into the script , along with the metadata bucket to include any remaining metadata values, as shown in Figure 175: Approval Comment Update Example: Add Parameters.

    

    Figure 175: Approval Comment Update Example: Add Parameters

    In the PowerShell Script Name field, in the dropdown select the script containing content similar to the following:

    # 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

    The resulting comment will look something like:

    

    Figure 176: Approval Comment Update Example: Results

    If the workflow requires multiple approvals or has multiple require approval steps, all the approval comments entered in the given workflow instance prior to the PowerShell step will be added to the metadata field. If you expect to have multiple comments, you may prefer to use a big text field rather than the string type fields shown here.

    Note:  If your PowerShell script takes a long time to execute, the step may time out and the workflow instance fail. The default timeout is 60 seconds and is configurable with the Workflow Step Run Timeout application setting (see Application Settings: Workflow Tab).
    Update Certificate Request Subject\SANs for Microsoft CAs

    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) 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 (.PFX) enrollment agent certificate with private key 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 (formerly Thycotic).

      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.

      CyberArk

      Select CyberArk in the Providers dropdown if your PAM provider is CyberArk. The remaining fields in the dialog will then be:

      • PrivateArk Protected Password Name—The name of the username or password in the safe (see Create a CyberArk Password).
      • PrivateArk Folder Name—The path and name of the folder that stores the CyberArk Password (e.g. Root or Root\MyDir).
      Delinea (formerly Thycotic)

      Select Delinea in the Providers dropdown if your PAM provider is Delinea. The remaining field in the dialog will then be:

      • Delinea Secret ID—The numeric ID of the secret to retrieve from Secret Server (see Create a Delinea Secret Server Secret).

    

    Figure 177: Update Certificate Request Subject\SANs for Microsoft CAs Workflow Definition Step

    Example:  The following example uses PowerShell to take the distinguished name (subject) and SANs entered during an enrollment along with two static domain names and evaluates the domain name of the common name in the subject to determine whether the domain suffix ends with the "original" domain name provided in the static value ("keyexample.com"). If it does, the script replaces the domain name in the subject with the value provided by the "new" static value and adds a SAN with CN prefix and the new domain name (e.g. CN=mycert.keyexample.com becomes CN=mycert.keyother.com and a SAN is added for mycert.keyother.com). If the CN does not have a domain suffix ending with "keyexample.com", the PowerShell script does nothing. Here we use a Set Variable Data step (see Set Variable Data) since no functions need to be called outside the confines of Keyfactor Command, though you could use a Custom PowerShell Script step instead. Then an Update Certificate Subject\SANs for Microsoft CAs step is used to re-sign the request before it is submitted to the CA.

    To create this, add Script Parameters to pull the DN and SANs into the script as shown in Metadata Update Example: Add Parameters and add to static values to pass in your two domain names.

    

    Figure 178: Update SANs and Subject Example: Add Parameters

    In the Insert PowerShell Script field, enter a script similar to the following:

    # 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

    Add an Update Certificate Request Subject\SANs for Microsoft CAs step at a point in the workflow after your PowerShell step to allow the request to be re-signed before it is submitted to the Microsoft CA for enrollment.

    Your enrollment will complete using the updated list of SANs, including any SANs you added manually on the PFX enrollment page or in the CSR, and the updated subject. You may reference the updated SANs using the standard SANs token ($(sans)) and updated subject using the standard DN token ($(request:dn)) in subsequent steps in your workflow and may view the subject and complete SAN list wherever the subject and SANs are available for viewing within Keyfactor Command.

    Windows Enrollment Gateway - Populate from AD

    This step is needed for any Keyfactor Windows Enrollment Gateway requests where the incoming template (the template from the client side) is configured to build the subject of the certificate request from Active Directory. It has no configuration parameters.

15. For Require Approval steps or custom steps requiring signals, in the Workflow Step Editor in the Signals section, select one or more security roles (see Security Overview) in the Approval Status dropdown. To narrow the list of security roles in the dropdown, begin typing a search string in the Search field. Click the erase icon () to clear your selections.

    Users who hold the security role(s) selected here will be able to submit signals (e.g. approve requests) for this workflow.

    Tip:  Signals represent data used at the point in the workflow step where the workflow needs to continue based on user input. Here, you're configuring which users are allowed to provide that input.

    

    Figure 179: Signals Configuration for a Requires Approval Workflow Definition Step

    Important:  If all the security roles configured for a workflow step are deleted from Keyfactor Command, no users will be able to submit signals for workflow instances initiated with that workflow definition. To remedy this, update the workflow definition with one or more current security roles, re-publish it, and then restart any outstanding workflow instances.
16. Click Save Workflow at the top of the workflow workspace to save the workflow step.
17. On the Workflow Configuration page, click the plus button in between two workflow steps to add another step in the workflow or click Save Workflow to save the workflow with its current steps.
18. Before you can use the workflow, it must be published to activate it. Click the Publish button at the top of the workflow workspace to publish it immediately or return to the workflow definitions page and publish it later, if desired (see Publishing a Workflow Definition).
    Tip:  Clicking Publish automatically saves the workflow.
19. To close the workflow workspace and return to the workflow definitions page, click the Close button at the top of the workflow workspace.

An audit log entry is created when you add or edit a workflow definition (see Audit Log).

To delete a workflow definition:

1. In the Management Portal, browse to Workflow > Workflow Definitions.
2. On the Workflow Definitions page, select a workflow definition and click Delete from either the top or right-click menu.
3. On the Confirm Operation alert, click OK to confirm or Cancel to cancel the operation.

An audit log entry is created when you delete a workflow definition (see Audit Log).

Workflow definitions are drafts that cannot be actively used until you take the step to publish them. This allows you to add new workflows or update existing ones without interrupting the flow of activity. Then, once the workflow definition is complete and ready for use, you can activate it. This can be done on the workflow workspace page while editing the workflow (see Adding or Modifying a Workflow Definition) or from the workflow definitions page.

To publish a workflow definition from the workflow definitions page:

1. In the Management Portal, browse to Workflow > Workflow Definitions.
2. On the Workflow Definitions page, select a workflow definition and click Publish from either the top or right-click menu.
3. On the Confirm Operation alert, click OK to confirm or Cancel to cancel the operation.

You may wish to use the import and export functions to:

• Import a new workflow customized for you by the Keyfactor team.

• Export a workflow for backup purposes.

• Export a workflow that you've fully configured and which you need to replicate and then import under another name to create a duplicate of it.

• Export a previous version of a workflow and import it as the current version to revert to using the previous version.

Exporting a Workflow

Workflow definitions can be exported either from the workflow workspace page while viewing or editing the workflow (see Adding or Modifying a Workflow Definition) or from the workflow definitions page.

To export a workflow definition from the workflow workspace:

1. In the Management Portal, browse to Workflow > Workflow Definitions.
2. On the Workflow Definitions page, click Edit from either the top or right click menu. This will open the workflow in the workflow workspace with the Workflow Definition dialog open on the right.
3. At the top of the workflow workspace, select a different Version of the workflow in the dropdown, if desired (see Workflow Versions).
4. At the top of the workflow workspace, click Export.
5. Browse to place the exported file on the local computer. The file will have an extension of .json.

To export a workflow definition from the workflow definitions page:

1. In the Management Portal, browse to Workflow > Workflow Definitions.
2. On the Workflow Definitions page, select a workflow definition and click Export from either the top or right-click menu.
3. In the Export Workflow Definition dialog, select a Version and click Export.

   

   Figure 180: Export Workflow Definition

4. Browse to place the exported file on the local computer. The file will have an extension of .json.

Importing a Workflow

Workflow definitions can be imported either to create a new workflow or to replace an existing workflow (e.g. to revert to a backup). When you import a workflow definition while editing an existing workflow definition, it will overwrite any changes you have made to the existing workflow since the last time it was published. Previously published versions of the workflow—including the most recent—will be retained. This is useful in cases where you want to export a previous version of a workflow and reimport it to make it the currently active version.

To import a workflow definition:

1. In the Management Portal, browse to Workflow > Workflow Definitions.
2. On the Workflow Definitions page, click Add from the top menu to create a new workflow definition into which you will import, or Edit from either the top or right click menu, to import into an existing one to revert to a previous version. This will open the workflow in the workflow workspace with the Workflow Definition dialog open on the right.
3. At the top of the workflow workspace, click Import.
4. Browse to locate the workflow definition file you wish to import. Only files with an extension of .json will appear.

   

   Figure 181: Browse to Locate a Workflow Definition to Import

   Tip:  In order to be successfully imported, the file must be correctly formatted JSON with at least WorkflowType and Steps properties. The maximum file upload size is 2 MB.
5. Click Import to import the workflow definition and populate it into the workflow workspace.
6. On the Confirm Operation alert, click OK to confirm or Cancel to cancel the operation.
7. In the workflow workspace, edit and save the workflow definition as needed as per Adding or Modifying a Workflow Definition. The following values will need attention:
   • Key (Template)

     When the workflow definition is imported into a new workflow definition, the template is cleared. You will need to set an appropriate template on the imported workflow definition before saving. The template is not cleared for imports into workflows with existing published versions.

     This is done both to support export of workflow definitions from one environment and import into another where the template set likely would be different and to support copying of workflow definitions, since you can't have two definitions for the same template.

   • Secrets

     Some types of workflow steps include secret values (e.g. passwords). Secret values are not imported. If your workflow includes steps with secret values, these will need to be re-entered. This is true for imports into new workflow definitions and workflow definitions with existing published versions.

   • Roles for Signals

     Some types of workflow steps make use of signals to allow users to provide input to the workflow midstream (e.g. provide approvals). This requires configuration of security roles that define who is allowed to provide this input. These security role values are not imported. You will need to set appropriate security roles on any workflow steps that use signals before saving. This is true for imports into new workflow definitions and workflow definitions with existing published versions.

     This is done to support export of workflow definitions from one environment and import into another where the security role set likely would be different.

   Important:  If you're importing a copy of a workflow definition that already exists in Keyfactor Command and you want to save it as a separate copy, be sure to change the Name of the workflow before saving the imported workflow to avoid overwriting the existing version of the workflow.

When you open a workflow definition for editing, you will see the version of the workflow shown at the upper left of the workflow workspace in a dropdown. By default, the current version will be shown.

When you have the current, most recent, version of the workflow loaded, you will see several options in the button bar at the top of the workflow workspace (if you have appropriate permissions) and the Add/Edit Workflow Definition Dialog will be active. If you select an older version in the dropdown, only the Version, Export, and Close options will appear on the workflow workspace button bar and the Add/Edit Workflow Definition Dialog will be read only.

This option is designed to allow you to review previous versions of a workflow or export them as backups or to be re-imported to be used as a base for generating new workflows.