POST Workflow Definitions

A string indicating the type of step. The currently supported types are:

• Email

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

• PowerShell

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

  • Where-Object
  • ForEach-Object

  • Get-Command

• CustomPowerShell

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

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

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

• RequireApproval

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

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

• RESTRequest

  Run a REST (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. The REST request contents are embedded within the step. It does not call out to an external file.

• EnrollmentAgent

  On an enrollment (either CSR A CSR or certificate signing request is a block of encoded text that is submitted to a CA when enrolling for a certificate. When you generate a CSR within Keyfactor Command, the matching private key for it is stored in Keyfactor Command in encrypted format and will be married with the certificate once returned from the CA. or PFX A PFX file (personal information exchange format), also known as a PKCS#12 archive, is a single, password-protected certificate archive that contains both the public and matching private key and, optionally, the certificate chain. It is a common format for Windows servers.), create a resigned CSR to prepare an updated enrollment request for delivery to a Microsoft CA after a previous step in the workflow has been used to update either the SANs in the initial request, subject (DN A distinguished name (DN) is the name that uniquely identifies an object in a directory. In the context of Keyfactor Command, this directory is generally Active Directory. A DN is made up of attribute=value pairs, separated by commas. Any of the attributes defined in the directory schema can be used to make up a DN.) in the initial request or both. This step must be placed later in the workflow than the step(s) to modify the SANs and/or subject. The SANs and subject may be modified with either of the PowerShell step types or a custom step type. The step creates a new CSR using the same public key In asymmetric cryptography, public keys are used together in a key pair with a private key. The private key is retained by the key's creator while the public key is widely distributed to any user or target needing to interact with the holder of the private key. as the original CSR using the updated SAN The subject alternative name (SAN) is an extension to the X.509 specification that allows you to specify additional values when enrolling for a digital certificate. A variety of SAN formats are supported, with DNS name being the most common. and/or subject values. It signs the new CSR with the certificate provided in the step's configuration.

  For this type of step you will need an enrollment agent certificate available as a PKCS#12 A PFX file (personal information exchange format), also known as a PKCS#12 archive, is a single, password-protected certificate archive that contains both the public and matching private key and, optionally, the certificate chain. It is a common format for Windows servers. (.PFX) file with included private key Private keys are used in cryptography (symmetric and asymmetric) to encrypt or sign content. In asymmetric cryptography, they are used together in a key pair with a public key. The private or secret key is retained by the key's creator, making it highly secure. to import into Keyfactor Command. This can be a user certificate or a computer certificate (e.g. generated from a copy of the "Enrollment Agent" template or the "Enrollment Agent (Computer)" template) and must have a Certificate Request Agent EKU. Note that the built-in "Enrollment Agent" and "Enrollment Agent (Computer)" templates do not allow private keys to be exported by default. You will need a template that allows private key export or will need to manually override private key export to create a certificate with an exportable private key in order to create a PKCS#12 (.PFX) file.

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

• SubjectFormatter

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

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

• EnrollStep

  Enroll for a certificate through Keyfactor Command. The enroll step must always fall as the last step in the workflow, immediately following the EndNOOP step.

• NOOPStep

  An entry or exit step in which no operation occurs. Steps of this type indicate the start and end of the workflow.

• RevokeStep

  Revoke a certificate through Keyfactor Command. The revoke step must always fall as the last step in the workflow, immediately following the EndNOOP step.

Tip:  For steps that send email messages, the SMTP Short for simple mail transfer protocol, SMTP is a protocol for sending email messages between servers. settings and sender information come from the standard Keyfactor Command SMTP configuration (see SMTP) and are not configured individually in the workflow steps.

An array containing the configuration parameters for the workflow definition step. These will vary depending on the type of workflow and the type of step (see ExtensionName). Show CustomPowerShell, Email, PowerShell, RequireApproval, or RestRequest parameter A parameter or argument is a value that is passed into a function in an application. details.

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 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 append additional data to it using PowerShell.

Value	Description
Headers	An array of key/value pair strings containing the header information for the request. The key is the name of the specific request header (for Keyfactor API request headers, see Table 65: Common Request Headers and the specific documentation for each endpoint An endpoint is a URL that enables the API to gain access to resources on a server.) and the value is the value that should be set for that header. For a Keyfactor API request, this might look like: "Headers": { "x-keyfactor-requested-with": [ "APIClient" ], "x-keyfactor-api-version": [ "2" ] } 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.
DataBucketProperty	A string containing the variable that the response from the request will be returned in, if any. 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 and only the ClientMachine name, in the email message you would enter the following: $(MyResponse.[0].ClientMachine)
Verb	A string indicating the HTTP verb for the type of request to perform. Supported values are: DELETE GET HEAD OPTIONS POST PUT TRACE
UseBasicAuth	A Boolean indicating whether Basic authentication should be used for the request (True) or not (False). If UseBasicAuth is False, Windows authentication in the context of the Keyfactor Command application pool user will be used (see Create Active Directory Service Accounts for Keyfactor Command in the Keyfactor Command Server Installation Guide).
BasicUsername	An array indicating the username information to use for authentication if UseBasicAuth is True. Supported methods to store credential information are: Store the credential information in the Keyfactor secrets table. A Keyfactor secret is a user-defined username or password that is encrypted and stored securely in the Keyfactor Command database. Load the credential information from a PAM provider. See PAM Providers and Privileged Access Management (PAM) in the Keyfactor Command Reference Guide for more information. Value Description SecretValue A string containing the username defined for basic authentication (in DOMAIN\\username format). Parameters An array indicating the parameters to supply for PAM authentication. These will vary depending on the PAM provider. Provider A string indicating the ID of the PAM provider. Use the GET /PamProviders method (see GET PAM Providers) to retrieve a list of all the PAM providers to determine the ID. For example, the username stored as a Keyfactor secret will look like: { "SecretValue": "KEYEXAMPLE\svc_MyServiceName" } The username stored as a CyberArk PAM secret will look like (where the Provider value—1 in this example—is the Id value from GET PAM Providers and the Folder and Object reference the folder name and object name in the CyberArk safe): { "Provider": "1", "Parameters":{ "Folder":"MyFolderName", "Object":"MyWorkflowUsername" } } The username stored as a Delinea PAM secret will look like (where the Provider value—1 in this example—is the Id value from GET PAM Providers and the SecretId is the ID if the secret created in the Delinea secret server for this purpose): { "Provider": "1", "Parameters":{ "SecretId":"MyUsernameId" } } Due to its sensitive nature, this value is not returned in responses.
BasicPassword	An array indicating the password information to use for authentication if UseBasicAuth is True. The syntax is the same as for BasicUsername. Due to its sensitive nature, this value is not returned in responses.
URL	A string containing the URL for the request, including tokens, if desired. For a Keyfactor API request, this might look like: 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.
ContentType	A string indicating the content type for the request. Supported values are: application/json
RequestContent	A string containing the body of the REST request, if needed. For a Keyfactor API request, this will vary depending on the request and might look like (for a PUT /Certificates/Metadata request): { "Id": "$(certid)", "Metadata":{ "RevocationComment": "$(cmnt)" } } Note:  This example assumes you have a metadata field called RevocationComment.

An object containing conditions indicating whether the step should run (true) or not (false). Conditions may either have a static value of True or False or a token that will have a value of True or False at the time the step is run. More than one condition may be added. If multiple conditions are used in the same step, all conditions must have a value of True at the time the step is evaluated to be run in order for the step to run. If any single condition evaluates to False, the step will not run. Show condition details.