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 196: 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 API 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 Use Custom PowerShell step, see Update Enrollment Request Requiring Approval with Certificate Store Info Using Embedded REST Request. For an example using an Invoke REST Request and a PowerShell step passing data between them, see Update Metadata Field with Revocation Code and Comment. For an example using a PowerShell step to manipulate data ahead of using an Invoke REST Request to retrieve data, see Retrieve Requester’s SSH Info with REST Request on Enrollment.

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 197: 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 Use Custom PowerShell step, see Update Enrollment Request Requiring Approval with Certificate Store Info Using Embedded REST Request. For an example using an Invoke REST Request to do a data lookup on enrollment, see Retrieve Requester’s SSH Info with REST Request on Enrollment. For an example using an Invoke REST Request and a PowerShell step passing data between them, see Update Metadata Field with Revocation Code and Comment.

This step is needed for any enrollment workflows. It has no configuration parameters.

• Expiration Renewal Template: In the dropdown, select the certificate template A certificate template defines the policies and rules that a CA uses when a request for a certificate is received. to use when requesting a new certificate on running expiration workflows with a renewal step. The template must be available from the selected certificate authority 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..

• Expiration Renewal Certificate Authority: In the dropdown, select the certificate authority to use when requesting a new certificate on running expiration workflows with a renewal step.

Tip:  The Keyfactor Command Service (timer service) needs permissions to enroll on the 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. and template used for renewal when this step is used.

This step is needed for any revocation workflows. It has no configuration parameters.

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

• Requester Can Approve: Click the Requester Can Approve toggle to enable or disable allowing the user who initiated a given workflow to approve that workflow. For example, Martha enrolled for a certificate that uses a template which has a workflow that requires approval from one approver. Martha holds one of the security roles that is allowed to approve that certificate request. If Requester Can Approve is enabled, Martha can then go approve that request with no interaction from any other user. If Requester Can Approve is disabled, even though Martha would normally be able to approve certificate requests for this workflow, she cannot for this particular certificate request. She must wait for another approver to approve it.

  If Requester Can Approve is disabled and Martha attempts to approve the request, Martha receives the following message, a message is logged in the Keyfactor API log (see Log Monitoring) at [Warn] level indicating that Martha attempted to approve or deny her own workflow instance, and the number of approvals required for the step remains the same.

  A user may not approve or deny a workflow that they requested. Awaiting [number as appropriate to the given workflow] more approval(s) from approval roles.

For an example using a Require Approval step with a Use Custom PowerShell step containing an embedded Keyfactor API request to retrieve extra certificate store data to be delivered in the approval email and a Send Email step, see Update Enrollment Request Requiring Approval with Certificate Store Info Using Embedded REST Request. For an example using a Require Approval step with a condition and a Set Variable Data step, see Require Approval on Enrollment for Selected Domains.

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 200: 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>
  </table>
  
  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 Update Enrollment Request Requiring Approval with Certificate Store Info Using Embedded REST Request. For an example using a PowerShell step to manipulate data ahead of using an Invoke REST Request to retrieve data and then a Send Email step to send the data, see Retrieve Requester’s SSH Info with REST Request on Enrollment.

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. 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”).

• 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 202: 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

  {<other values>, "MyFieldOne":"<your value as defined in the script>", "MyFieldTwo":"<your value as defined in the script>", "TestThree":"<your value as defined in the script>", <other values>}

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

For an example using Set Variable Data for an enrollment request, see Update Additional Enrollment Field on Enrollment. For an example using Set Variable Data for a revocation request, see Update Revocation Comment.

This step is used to create a new, signed 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. 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 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. 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 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. 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.

For an example using a Update Certificate Request Subject\SANs for Microsoft CAs step, see Update Subject and SANs on Enrollment.

Tip:  Tokens (a.k.a. substitutable special text) may be used in the metadata 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 approval comment entered when an enrollment or revocation request is approved—$(cmnt)—and place it in a metadata field for future reference. 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”).

This step is used to update a metadata field in Keyfactor Command. Before creating the step, you must create a metadata field to update (see Adding or Modifying a Metadata Field).

• Metadata Field Name: Enter the name of the metadata field you wish to populate with the workflow step.

• Metadata Value: Enter either a static value to populate into the field during the workflow step or select a token to populate the metadata field with a variable value at workflow runtime.

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. 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”).

• 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 205: Add Parameters for PowerShell

• Use PowerShell 5.1: By default, custom PowerShell steps use PowerShell 7. Click this toggle to enable PowerShell 5.1 instead for the current workflow step.

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

For an example using Use Custom PowerShell for an enrollment request, see DNS Lookup to Add Extra IP SAN Plus Add Two DNS SANs on Enrollment. For an example using Use Custom PowerShell and a Require Approval step, see Copy Approval Comment to Metadata Field on Enrollment.

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.