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

The parameters for this step are:

• Function Name: Enter the name of the AWS Lambda function you want to invoke. This should match the exact name configured in your AWS account and is case-sensitive.

• Access Key: Enter your AWS Access Key ID. This is a unique identifier (similar to a client ID) for the IAM user or role that will authenticate the request. You can generate this key from the AWS IAM console when creating or managing IAM users. In the Access Key dialog, the options are Load From Keyfactor Secrets or Load From PAM Provider.

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

  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.

  Tip:  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 has historically been an option for customers that don’t already have a relationship with a PAM provider such as CyberArk or Delinea/Thycotic. More recent versions of Keyfactor Command offer Keyfactor Command local PAM databases, allowing you to store secrets in the Keyfactor Command database using PAM.

  Select the Load from PAM Provider radio button if you want to store the secret value in a Keyfactor Command local or supported third-party PAM solution (see Privileged Access Management (PAM)). Select a PAM provider in the Providers dropdown. The remaining fields on the dialog will vary depending on the PAM provider. For example:

  Keyfactor Command Local Database

  Select your Keyfactor Command local database provider in the Providers dropdown. The remaining field in the dialog will then be:

  • Secret Reference Name: The name given to the secret defined in Keyfactor Command (see Managing Secrets for a Local Keyfactor Command PAM Provider).

  CyberArk

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

  • PrivateArk Folder Name: The path and name of the folder that stores the secret (e.g., Root or Root\MyDir).
  • PrivateArk Protected Password Name: The name of the username or password to use for this instance.

  Delinea/Thycotic

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

  • Thycotic Secret ID: The numeric ID of the secret to retrieve from provider server.

  Hashicorp

  Select your Hashicorp Vault provider in the Providers dropdown (see Adding or Modifying a PAM Provider). The remaining fields 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.

• Access Key Secret: Enter your AWS Access Key Secret. This is the secret key (similar to a client secret) paired with the Access Key ID to securely sign requests to AWS services. Keep this value confidential to prevent unauthorized access. In the Access Key Secret dialog, the options are Load From Keyfactor Secrets or Load From PAM Provider.

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

  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.

  Tip:  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 has historically been an option for customers that don’t already have a relationship with a PAM provider such as CyberArk or Delinea/Thycotic. More recent versions of Keyfactor Command offer Keyfactor Command local PAM databases, allowing you to store secrets in the Keyfactor Command database using PAM.

  Select the Load from PAM Provider radio button if you want to store the secret value in a Keyfactor Command local or supported third-party PAM solution (see Privileged Access Management (PAM)). Select a PAM provider in the Providers dropdown. The remaining fields on the dialog will vary depending on the PAM provider. For example:

  Keyfactor Command Local Database

  Select your Keyfactor Command local database provider in the Providers dropdown. The remaining field in the dialog will then be:

  • Secret Reference Name: The name given to the secret defined in Keyfactor Command (see Managing Secrets for a Local Keyfactor Command PAM Provider).

  CyberArk

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

  • PrivateArk Folder Name: The path and name of the folder that stores the secret (e.g., Root or Root\MyDir).
  • PrivateArk Protected Password Name: The name of the username or password to use for this instance.

  Delinea/Thycotic

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

  • Thycotic Secret ID: The numeric ID of the secret to retrieve from provider server.

  Hashicorp

  Select your Hashicorp Vault provider in the Providers dropdown (see Adding or Modifying a PAM Provider). The remaining fields 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.
• AWS Region: Specify the AWS region where your Lambda function is deployed (e.g., us-east-1, eu-west-2). This determines the regional endpoint An endpoint is a URL that enables the API to gain access to resources on a server. used to send the request and must match the region of the target Lambda function.

• Property to Store Response in: Provide a name for the property in which to store the response data returned by the Lambda function. You can then reference this property in subsequent steps in your workflow.

  Tip:  The response is stored as a serialized JObject. If the function returns structured JSON (such as a list or an object), you can extract specific values using JSON path syntax. For example, imagine your function returns a response like:

  Copy

  [
    {
      "name": "Martha",
      "role": "IT",
      "region": "US-West"
    },
    {
      "name": "John",
      "role": "Sales",
      "region": "US-East"
    }
  ]
  

  You store this response in a variable named MyResponse. You could then reference the region value for the first result like this:

  $(MyResponse.[0].region)

  If your function returns a single object (rather than an array), omit the index. For example:

  Copy

  {
    "message": "Here is the result of your request.",
    "timestamp": "2025-08-13T10:30:00Z"
  }

  You would then use:

  $(MyResponse.message)

• Payload: Enter the JSON-formatted payload to send with the Lambda request. This field is optional, but if provided, the content must be valid JSON. Tokens are supported. For example:

  Copy

  {
    "action": "revoke",
    "certificateId": "$(certid)",
    "revocationComment": "$(cmnt)",
    "owner": "$(metadata:AppOwnerFirstName) $(metadata:AppOwnerLastName)"
  }
  

  Note:  This example assumes you have metadata fields as referenced (see Certificate Metadata).

• Assume Role: Enable this option to assume an IAM role before invoking the Lambda function. When enabled, the step uses the provided access key and secret to request temporary credentials for the specified role. This is useful for cross-account access or when enforcing more granular permissions.

• ARN of Role to Assume: Specify the Amazon Resource Name (ARN) of the IAM role to assume when Assume Role is enabled. The ARN must be in the format:

  arn:aws:iam::123456789012:role/YourLambdaRole

  This field is required if Assume Role is enabled. If disabled, the Lambda function is invoked directly using the access key credentials.

• Tags: Optional key-value pairs to include when assuming a role. These tags are passed to AWS STS during the AssumeRole request and can be used for access control, auditing, or session identification. To add a tag:

  1. In the Tags section, click Add.

  2. In the Add/Edit Parameter A parameter or argument is a value that is passed into a function in an application. dialog, enter the name of the tag in the Parameter field and its corresponding value in the Value field. You can enter a static value (such as Production or KeyfactorWorkflow) or use a token to dynamically populate the value at runtime. These tags will be included in the request to AWS when assuming the IAM role and may be used for access control or session tracking.

  3. Click Save to save your tag.

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

• Function Access Key : The function access key is used to authorize calls to the Azure Function. This key is required if either the function or its parent function app enforces function-level authorization. If the function is configured for anonymous access and the function app does not enforce additional authentication, the key may not be necessary (set the field to No Value). In the Function Access Key dialog, the options are No Value, Load From Keyfactor Secrets or Load From PAM Provider.

  Select No Value if your function is configured for anonymous access and the function app does not enforce additional authentication.

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

  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.

  Tip:  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 has historically been an option for customers that don’t already have a relationship with a PAM provider such as CyberArk or Delinea/Thycotic. More recent versions of Keyfactor Command offer Keyfactor Command local PAM databases, allowing you to store secrets in the Keyfactor Command database using PAM.

  Select the Load from PAM Provider radio button if you want to store the secret value in a Keyfactor Command local or supported third-party PAM solution (see Privileged Access Management (PAM)). Select a PAM provider in the Providers dropdown. The remaining fields on the dialog will vary depending on the PAM provider. For example:

  Keyfactor Command Local Database

  Select your Keyfactor Command local database provider in the Providers dropdown. The remaining field in the dialog will then be:

  • Secret Reference Name: The name given to the secret defined in Keyfactor Command (see Managing Secrets for a Local Keyfactor Command PAM Provider).

  CyberArk

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

  • PrivateArk Folder Name: The path and name of the folder that stores the secret (e.g., Root or Root\MyDir).
  • PrivateArk Protected Password Name: The name of the username or password to use for this instance.

  Delinea/Thycotic

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

  • Thycotic Secret ID: The numeric ID of the secret to retrieve from provider server.

  Hashicorp

  Select your Hashicorp Vault provider in the Providers dropdown (see Adding or Modifying a PAM Provider). The remaining fields 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.
• Headers: Enter any headers needed for your request. For example:
  User-Agent: KeyfactorCommand/25.5 (CommandWorkflow)

• 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. If the function returns structured JSON (such as a list or an object), you can extract specific values using JSON path syntax. For example, imagine your function returns a response like:

  Copy

  [
    {
      "name": "Martha",
      "role": "IT",
      "region": "US-West"
    },
    {
      "name": "John",
      "role": "Sales",
      "region": "US-East"
    }
  ]
  

  You store this response in a variable named MyResponse. You could then reference the region value for the first result like this:

  $(MyResponse.[0].region)

  If your function returns a single object (rather than an array), omit the index. For example:

  Copy

  {
    "message": "Here is the result of your request.",
    "timestamp": "2025-08-13T10:30:00Z"
  }

  You would then use:

  $(MyResponse.message)
• Verb: In the dropdown, select the type of request you wish to make (e.g., GET, POST).

• URL: Enter the full request URL for your Azure Function, including the HTTP method and any required query parameters (such as tokens) if they are not passed in headers.

  For example:

  https://my-function-app-name.azurewebsites.net/api/MyExampleFunction

  Or, with a Keyfactor Command workflow variable in the query string:

  https://my-function-app-name.azurewebsites.net/api/UpdateMetadata?certId=$(certid)
  Tip:  The Function Access Key is passed in the x-functions-key header and does not need to be included in the URL.

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

  • application/json

• Request Content: The request body of the request, if required, with tokens, if desired. For example:

  Copy

  {
    "CertificateId": "$(certid)",
    "SubjectName": "$(cn)",
    "Thumbprint": "$(thumbprint)",
    "Requester": "$(requester)",
    "RevocationDetails": {
      "Comment": "$(cmnt)",
      "Reason": "$(code)",
      "RevokedBy": "$(revoker)",
      "RevocationDate": "$(effdate)"
    },
    "ApplicationOwner": {
      "FirstName": "$(metadata:AppOwnerFirstName)",
      "LastName": "$(metadata:AppOwnerLastName)",
      "Email": "$(metadata:AppOwnerEmailAddress)"
    },
    "Environment": "$(metadata:Environment)",
    "Metadata": {
      "BusinessUnit": "$(metadata:BusinessUnit)",
      "CostCenter": "$(metadata:CostCenter)",
      "CustomTags": "$(metadata:CustomTags)"
    }
  }

  Note:  This example assumes you have metadata fields as referenced (see Certificate Metadata).

This step type is used for a REST (API) request against an Azure Function supporting OAuth authentication. To support an Azure Function with anonymous or function key authentication, refer to the Invoke Azure Function step type (see Invoke Azure Function).

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

• Function Access Key : The function access key is used to authorize calls to an Azure Function and is required. While OAuth handles user authentication, the function access key acts as a shared secret to validate the request against the Azure Function endpoint. Even if the function itself allows anonymous access, under OAuth Azure’s security model typically requires the key to invoke the function successfully from external systems like Keyfactor Command. In the Function Access Key dialog, the options are Load From Keyfactor Secrets or Load From PAM Provider.

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

  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.

  Tip:  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 has historically been an option for customers that don’t already have a relationship with a PAM provider such as CyberArk or Delinea/Thycotic. More recent versions of Keyfactor Command offer Keyfactor Command local PAM databases, allowing you to store secrets in the Keyfactor Command database using PAM.

  Select the Load from PAM Provider radio button if you want to store the secret value in a Keyfactor Command local or supported third-party PAM solution (see Privileged Access Management (PAM)). Select a PAM provider in the Providers dropdown. The remaining fields on the dialog will vary depending on the PAM provider. For example:

  Keyfactor Command Local Database

  Select your Keyfactor Command local database provider in the Providers dropdown. The remaining field in the dialog will then be:

  • Secret Reference Name: The name given to the secret defined in Keyfactor Command (see Managing Secrets for a Local Keyfactor Command PAM Provider).

  CyberArk

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

  • PrivateArk Folder Name: The path and name of the folder that stores the secret (e.g., Root or Root\MyDir).
  • PrivateArk Protected Password Name: The name of the username or password to use for this instance.

  Delinea/Thycotic

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

  • Thycotic Secret ID: The numeric ID of the secret to retrieve from provider server.

  Hashicorp

  Select your Hashicorp Vault provider in the Providers dropdown (see Adding or Modifying a PAM Provider). The remaining fields 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.

• Headers: Enter any headers needed for your request. For example:

  User-Agent: KeyfactorCommand/25.5 (CommandWorkflow)

• 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. For more information, see Workflow Variables.

  Tip:  The response is stored as a serialized JObject. If the function returns structured JSON (such as a list or an object), you can extract specific values using JSON path syntax. For example, imagine your function returns a response like:

  Copy

  [
    {
      "name": "Martha",
      "role": "IT",
      "region": "US-West"
    },
    {
      "name": "John",
      "role": "Sales",
      "region": "US-East"
    }
  ]
  

  You store this response in a variable named MyResponse. You could then reference the region value for the first result like this:

  $(MyResponse.[0].region)

  If your function returns a single object (rather than an array), omit the index. For example:

  Copy

  {
    "message": "Here is the result of your request.",
    "timestamp": "2025-08-13T10:30:00Z"
  }

  You would then use:

  $(MyResponse.message)
• Verb: In the dropdown, select the type of request you wish to make (e.g., GET, POST).
• Client ID: Enter the Application (client) ID from the Azure App Registration associated with the identity provider. This value identifies the client application that will authenticate with the function app.

• Client Secret: Click the Set\Update Client Secret button, then enter the client secret generated in the Azure App Registration. This secret authenticates the client when requesting tokens from Azure Active Directory. In the Client Secret dialog, the options are Load From Keyfactor Secrets or Load From PAM Provider.

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

  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.

  Tip:  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 has historically been an option for customers that don’t already have a relationship with a PAM provider such as CyberArk or Delinea/Thycotic. More recent versions of Keyfactor Command offer Keyfactor Command local PAM databases, allowing you to store secrets in the Keyfactor Command database using PAM.

  Select the Load from PAM Provider radio button if you want to store the secret value in a Keyfactor Command local or supported third-party PAM solution (see Privileged Access Management (PAM)). Select a PAM provider in the Providers dropdown. The remaining fields on the dialog will vary depending on the PAM provider. For example:

  Keyfactor Command Local Database

  Select your Keyfactor Command local database provider in the Providers dropdown. The remaining field in the dialog will then be:

  • Secret Reference Name: The name given to the secret defined in Keyfactor Command (see Managing Secrets for a Local Keyfactor Command PAM Provider).

  CyberArk

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

  • PrivateArk Folder Name: The path and name of the folder that stores the secret (e.g., Root or Root\MyDir).
  • PrivateArk Protected Password Name: The name of the username or password to use for this instance.

  Delinea/Thycotic

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

  • Thycotic Secret ID: The numeric ID of the secret to retrieve from provider server.

  Hashicorp

  Select your Hashicorp Vault provider in the Providers dropdown (see Adding or Modifying a PAM Provider). The remaining fields 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: Enter the Azure Active Directory token endpoint for your tenant. This endpoint is used to request access tokens during client credentials authentication. For example:

  https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token

  Replace {tenant-id} with your Directory (tenant) ID from Azure.

• Scope: Enter the scope required to request a token for your Azure Function. For client credentials flow, the scope must be the Application ID URI of the target resource with /.default appended. For example:

  api://{application-id}/.default

  Replace {application-id} with the Application (client) ID or custom App ID URI of your Azure Function’s registered app.

• Audience: (Optional) Enter the expected audience value (aud claim) for the token. In most Azure Function apps secured with Azure AD, this is typically the same as the Application ID URI used in the scope. For example:

  api://{application-id}

• URL: Enter the full request URL for your Azure Function, including the HTTP method and any required query parameters (such as tokens) if they are not passed in headers.

  For example:

  https://my-function-app-name.azurewebsites.net/api/MyExampleFunction

  Or, with a Keyfactor Command workflow variable in the query string:

  https://my-function-app-name.azurewebsites.net/api/UpdateMetadata?certId=$(certid)
  Tip:  The Function Access Key is passed in the x-functions-key header and does not need to be included in the URL.

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

  Copy

  {
    "CertificateId": "$(certid)",
    "SubjectName": "$(cn)",
    "Thumbprint": "$(thumbprint)",
    "Requester": "$(requester)",
    "RevocationDetails": {
      "Comment": "$(cmnt)",
      "Reason": "$(code)",
      "RevokedBy": "$(revoker)",
      "RevocationDate": "$(effdate)"
    },
    "ApplicationOwner": {
      "FirstName": "$(metadata:AppOwnerFirstName)",
      "LastName": "$(metadata:AppOwnerLastName)",
      "Email": "$(metadata:AppOwnerEmailAddress)"
    },
    "Environment": "$(metadata:Environment)",
    "Metadata": {
      "BusinessUnit": "$(metadata:BusinessUnit)",
      "CostCenter": "$(metadata:CostCenter)",
      "CustomTags": "$(metadata:CustomTags)"
    }
  }

  Note:  This example assumes you have metadata fields as shown (see Certificate Metadata).

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 202: 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. For more information, see Workflow Variables.

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

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

  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.

  Tip:  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 has historically been an option for customers that don’t already have a relationship with a PAM provider such as CyberArk or Delinea/Thycotic. More recent versions of Keyfactor Command offer Keyfactor Command local PAM databases, allowing you to store secrets in the Keyfactor Command database using PAM.

  Select the Load from PAM Provider radio button if you want to store the secret value in a Keyfactor Command local or supported third-party PAM solution (see Privileged Access Management (PAM)). Select a PAM provider in the Providers dropdown. The remaining fields on the dialog will vary depending on the PAM provider. For example:

  Keyfactor Command Local Database

  Select your Keyfactor Command local database provider in the Providers dropdown. The remaining field in the dialog will then be:

  • Secret Reference Name: The name given to the secret defined in Keyfactor Command (see Managing Secrets for a Local Keyfactor Command PAM Provider).

  CyberArk

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

  • PrivateArk Folder Name: The path and name of the folder that stores the secret (e.g., Root or Root\MyDir).
  • PrivateArk Protected Password Name: The name of the username or password to use for this instance.

  Delinea/Thycotic

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

  • Thycotic Secret ID: The numeric ID of the secret to retrieve from provider server.

  Hashicorp

  Select your Hashicorp Vault provider in the Providers dropdown (see Adding or Modifying a PAM Provider). The remaining fields 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)

• 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 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 203: 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. For more information, see Workflow Variables.

  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\Update Client 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.

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

  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.

  Tip:  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 has historically been an option for customers that don’t already have a relationship with a PAM provider such as CyberArk or Delinea/Thycotic. More recent versions of Keyfactor Command offer Keyfactor Command local PAM databases, allowing you to store secrets in the Keyfactor Command database using PAM.

  Select the Load from PAM Provider radio button if you want to store the secret value in a Keyfactor Command local or supported third-party PAM solution (see Privileged Access Management (PAM)). Select a PAM provider in the Providers dropdown. The remaining fields on the dialog will vary depending on the PAM provider. For example:

  Keyfactor Command Local Database

  Select your Keyfactor Command local database provider in the Providers dropdown. The remaining field in the dialog will then be:

  • Secret Reference Name: The name given to the secret defined in Keyfactor Command (see Managing Secrets for a Local Keyfactor Command PAM Provider).

  CyberArk

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

  • PrivateArk Folder Name: The path and name of the folder that stores the secret (e.g., Root or Root\MyDir).
  • PrivateArk Protected Password Name: The name of the username or password to use for this instance.

  Delinea/Thycotic

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

  • Thycotic Secret ID: The numeric ID of the secret to retrieve from provider server.

  Hashicorp

  Select your Hashicorp Vault provider in the Providers dropdown (see Adding or Modifying a PAM Provider). The remaining fields 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

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

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

  This value is not used for Keycloak.

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

• 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 search select 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.. The default is Use expiring certificate's Template. To narrow the list of results in a search select dropdown, begin typing in the input field. Matching results will appear as you type, and you can scroll to locate a record.

• Expiration Renewal Enrollment Pattern: In the search select dropdown, optionally select the enrollment pattern to use when requesting a new certificate on running expiration workflows with a renewal step. Only enrollment patterns for the selected template will be available. The default is either Use expiring certificate’s Enrollment Pattern or Use Template's default Enrollment Pattern depending on the selection made in the template dropdown. To narrow the list of results in a search select dropdown, begin typing in the input field. Matching results will appear as you type, and you can scroll to locate a record.

  Note:  If Use expiring certificate's Template is selected, the enrollment pattern field will default to Use expiring certificate’s Enrollment Pattern and will not be configurable.

• 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. The default selection depends on the template and enrollment pattern settings and may be one of the following: Use expiring certificate's Certificate Authority, Use Template's Certificate Authority, or Use Enrollment Pattern's Certificate Authority.

  If no 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. is explicitly configured, during enrollment the CA is chosen in the following order of priority:

  1. The CA(s) configured for the selected enrollment pattern

  2. The CA(s) configured for the selected template

  3. The CA used for the expiring certificate

• Key Algorithm: In the dropdown, select the key algorithm to use when requesting a new certificate on running expiration workflows with a renewal step. The default is Use expiring certificate's Key Algorithm.
• Key Size: In the dropdown, select the key size The key size or key length is the number of bits in a key used by a cryptographic algorithm. to use when requesting a new certificate on running expiration workflows with a renewal step. The default is Use expiring certificate's Key Size.
• Curve: In the dropdown, select the elliptic curve to use when requesting a new certificate on running expiration workflows with a renewal step. The default is Use expiring certificate's curve.
• Replace certificate in existing certificate store(s): Toggled on, this pushes the certificate to the appropriate certificate stores based on the original, expiring certificate. The default is on/enabled.

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).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 204: Tokens are Highlighted

Figure 205: 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 Recipients:In the Recipients grid, click Add to create a new recipient entry. You can add multiple recipients to each workflow. Each row in the grid represents a separate email message that will be sent when the workflow is triggered. For example:

  • You can enter specific email addresses (e.g., user@keyexample.com) or use substitutable special text variables (e.g., $(ownerroleemail)) that are replaced with actual email addresses when the workflow runs. This is useful for dynamically selecting recipients based on certificate data or metadata fields.

  • To include multiple recipients on the same email, where all recipients of the email will be able to see who the other recipients are, add them in a single row, separated by commas or semicolons (e.g., user1@keyexample.com, user2@keyexample.com).

  • To send to multiple recipients in separate emails, where all recipients will receive separate email messages appearing as though there were no other recipients, add them on separate rows.

  Each row on the Recipients grid can also be edited or deleted from the action buttons at the top of the grid, by selecting a row.

  Available email tokens include any custom email-based metadata fields, 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 21: Tokens for Workflow Definitions for a complete list of available tokens.

  Note:  When using HTML to format an email sent from Keyfactor Command, use inline styles and avoid linked stylesheets or embedded <style> rules. Many email clients do not fully support external or embedded CSS.

  Line breaks are not inserted automatically when HTML formatting is used. Define line breaks explicitly using tags such as <br>, <br/>, or <p></p>.

  Recommended:

  <p style="font-size:14px; color:#333; margin:0 0 12px;">Hello</p>

  Not Recommended:

  <link rel="stylesheet" href="https://cdn.keyexample.com/styles.css">

  or

  <style>p { color:#333; }</style>
• Approval Email Recipients: In the Recipients grid, click Add to create a new recipient entry. You can add multiple recipients to each workflow. Each row in the grid represents a separate email message that will be sent when the workflow is triggered. For example:

  • You can enter specific email addresses (e.g., user@keyexample.com) or use substitutable special text variables (e.g., $(ownerroleemail)) that are replaced with actual email addresses when the workflow runs. This is useful for dynamically selecting recipients based on certificate data or metadata fields.

  • To include multiple recipients on the same email, where all recipients of the email will be able to see who the other recipients are, add them in a single row, separated by commas or semicolons (e.g., user1@keyexample.com, user2@keyexample.com).

  • To send to multiple recipients in separate emails, where all recipients will receive separate email messages appearing as though there were no other recipients, add them on separate rows.

  Each row on the Recipients grid can also be edited or deleted from the action buttons at the top of the grid, by selecting a row.

  Available email tokens include any custom email-based metadata fields, which would be specified similarly to $(metadata:AppOwnerEmailAddress).

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

  Note:  When using HTML to format an email sent from Keyfactor Command, use inline styles and avoid linked stylesheets or embedded <style> rules. Many email clients do not fully support external or embedded CSS.

  Line breaks are not inserted automatically when HTML formatting is used. Define line breaks explicitly using tags such as <br>, <br/>, or <p></p>.

  Recommended:

  <p style="font-size:14px; color:#333; margin:0 0 12px;">Hello</p>

  Not Recommended:

  <link rel="stylesheet" href="https://cdn.keyexample.com/styles.css">

  or

  <style>p { color:#333; }</style>
  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 either an email step later in the workflow after the enrollment has taken place (see Send Email) or an issued certificate alert (see Issued Certificate Request Alerts).

• Approval Email Recipients:

  In the Recipients grid, click Add to create a new recipient entry. You can add multiple recipients to each workflow. Each row in the grid represents a separate email message that will be sent when the workflow is triggered. For example:

  • You can enter specific email addresses (e.g., user@keyexample.com) or use substitutable special text variables (e.g., $(ownerroleemail)) that are replaced with actual email addresses when the workflow runs. This is useful for dynamically selecting recipients based on certificate data or metadata fields.

  • To include multiple recipients on the same email, where all recipients of the email will be able to see who the other recipients are, add them in a single row, separated by commas or semicolons (e.g., user1@keyexample.com, user2@keyexample.com).

  • To send to multiple recipients in separate emails, where all recipients will receive separate email messages appearing as though there were no other recipients, add them on separate rows.

  You can also edit or delete a recipient by selecting a row in the Recipients grid and using the action buttons on the toolbar.

  Tip:  Keyfactor Command sends SMS (text) messages by leveraging the email to text gateways that many major mobile carriers provide. Check with your carrier for specific instructions. Keyfactor has tested that AT&T can be addressed using 10-digit-number@txt.att.net (e.g., 4155551212@txt.att.net) and Verizon can be addressed using 10-digit-number@vtext.com (e.g., 2125551212@vtext.com). T-Mobile can be addressed using 10-digit-number@tmomail.net (e.g., 2065551212@tmomail.net), but functionality can be spotty. Reliability of alerting via this method depends on the reliability of the carrier’s gateways.

  Available email tokens include: $(requester:mail) and any custom email-based metadata fields, which would be specified similarly to $(metadata:AppOwnerEmailAddress).

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

• Requester Can Approve: Controls whether the user who initiated a workflow is permitted to approve that workflow.

  • When Turned On

    The requester can approve their own certificate request if they are a member of an allowed approver role. No additional user interaction is required.

  • When Turned Off

    The requester cannot approve their own certificate request, even if they are normally authorized to approve requests for the workflow. Approval must be completed by another user.

  If requester approval is prevented and the requester attempts to approve the request:

  • An error message is displayed to the requester.

    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.

  • A warning entry is written to the log indicating that the requester attempted to approve or deny their own workflow instance.

  • The number of required approvals for the step remains unchanged.

For an example that combines a Require Approval step with a Use Custom PowerShell step containing an embedded REST request, see Update Enrollment Request Requiring Approval with Certificate Store Info Using Embedded REST Request. This example retrieves additional certificate store data and includes it in the approval email.

For an example that uses a Require Approval step with conditional logic and a Set Variable Data step, see Require Approval on Enrollment for Selected Domains.

For an example that uses a Require Approval step with a Set Variable Data step and an Invoke REST Request step to resolve an approver role dynamically and supply it to the approval status via a token, see Use Certificate Owner as Approver on Enrollment.

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

  <p>Hello,</p>
  
  <p>A certificate using the $(template) template was requested by $(requester) from $(CA) on $(subdate). The certificate details include:</p>
  
  <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>
  
  <p>Please review this request and issue the certificate as appropriate by going here:</p>
  
  <p>$(reviewlink)</p>
  
  <p>Thanks!</p>
  
  <p>Your Certificate Management Tool</p>

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

  Note:  When using HTML to format an email sent from Keyfactor Command, use inline styles and avoid linked stylesheets or embedded <style> rules. Many email clients do not fully support external or embedded CSS.

  Line breaks are not inserted automatically when HTML formatting is used. Define line breaks explicitly using tags such as <br>, <br/>, or <p></p>.

  Recommended:

  <p style="font-size:14px; color:#333; margin:0 0 12px;">Hello</p>

  Not Recommended:

  <link rel="stylesheet" href="https://cdn.keyexample.com/styles.css">

  or

  <style>p { color:#333; }</style>
• Recipients: In the Recipients grid, click Add to create a new recipient entry. You can add multiple recipients to each workflow. Each row in the grid represents a separate email message that will be sent when the workflow is triggered. For example:

  • You can enter specific email addresses (e.g., user@keyexample.com) or use substitutable special text variables (e.g., $(ownerroleemail)) that are replaced with actual email addresses when the workflow runs. This is useful for dynamically selecting recipients based on certificate data or metadata fields.

  • To include multiple recipients on the same email, where all recipients of the email will be able to see who the other recipients are, add them in a single row, separated by commas or semicolons (e.g., user1@keyexample.com, user2@keyexample.com).

  • To send to multiple recipients in separate emails, where all recipients will receive separate email messages appearing as though there were no other recipients, add them on separate rows.

  Each row on the Recipients grid can also be edited or deleted from the action buttons at the top of the grid, by selecting a row.

  Available email tokens include any custom email-based metadata fields, 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 21: 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 209: 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 more information, see Workflow Variables.

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) uniquely identifies an entry in an LDAP/X.500 directory by specifying a sequence of relative distinguished names (attribute=value pairs) from the entry up to the directory root. It’s written as a comma-separated string—for example: cn=Alice,ou=People,dc=keyexample,dc=com—with the specific attributes defined by the directory’s schema.) 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.

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

  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.

  Tip:  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 has historically been an option for customers that don’t already have a relationship with a PAM provider such as CyberArk or Delinea/Thycotic. More recent versions of Keyfactor Command offer Keyfactor Command local PAM databases, allowing you to store secrets in the Keyfactor Command database using PAM.

  Select the Load from PAM Provider radio button if you want to store the secret value in a Keyfactor Command local or supported third-party PAM solution (see Privileged Access Management (PAM)). Select a PAM provider in the Providers dropdown. The remaining fields on the dialog will vary depending on the PAM provider. For example:

  Keyfactor Command Local Database

  Select your Keyfactor Command local database provider in the Providers dropdown. The remaining field in the dialog will then be:

  • Secret Reference Name: The name given to the secret defined in Keyfactor Command (see Managing Secrets for a Local Keyfactor Command PAM Provider).

  CyberArk

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

  • PrivateArk Folder Name: The path and name of the folder that stores the secret (e.g., Root or Root\MyDir).
  • PrivateArk Protected Password Name: The name of the username or password to use for this instance.

  Delinea/Thycotic

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

  • Thycotic Secret ID: The numeric ID of the secret to retrieve from provider server.

  Hashicorp

  Select your Hashicorp Vault provider in the Providers dropdown (see Adding or Modifying a PAM Provider). The remaining fields 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 insert it into a custom metadata field in the certificate by doing a PUT /Certificates/Metadata request for the $(id).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”).

Figure 212: Tokens are Highlighted

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

  Note:  PowerShell 5.1 is not supported on Keyfactor Command servers running in a non-Windows environment.In non-Windows environments, configuring a handler/step with Use PowerShell 5.1 will result in being unable to save the workflow.

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

  For more information about variables, see Workflow Variables.

  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.