Workflow Definitions

The workflow A workflow is a series of steps necessary to complete a process. In the context of Keyfactor Command, it refers to the workflow builder, which allows you automate event-driven tasks when a certificate is requested or revoked. builder in Keyfactor Command allows you to easily automate event-driven tasks to manage certificate enrollments, renewals, revocations on a per template A certificate template defines the policies and rules that a CA uses when a request for a certificate is received. basis. It can also monitor certificate collections on a periodic basis for certificates that change membership status based on the query criteria of a specified certificate collection The certificate search function allows you to query the Keyfactor Command database for certificates from any available source based on any criteria of the certificates and save the results as a collection that will be availble in other places in the Management Portal (e.g. expiration alerts and certain reports).. The workflows can be configured with multiple steps between the start and end of the operation that offer a simple way to configure notifications, approvals, and end-to-end automation throughout the environment. This provides for operational agility in an intuitive and easy-to-configure manner.

When a user begins one of the types of actions managed with workflow in Keyfactor Command on the usual Management Portal page (e.g. 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 Certificate enrollment refers to the process by which a user requests a digital certificate. The user must submit the request to a certificate authority (CA).) or using the Keyfactor API A set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command. or a certificate collection membership change is detected by an automated task, the workflow kicks in behind the scenes and executes however many steps have been configured in the workflow definition to bring the action to the appropriate conclusion along the desired path.

See Certificate Collection Manager for more information about creating certificate collections.

Workflow Types

The following types of workflow triggering events are supported:

• Certificate Entered Collection

  The workflow is initiated by an automated task that Keyfactor Command runs periodically against your collections to identify certificates that now meet the query criteria of the specified certificate collection.

  For example, when a certificate discovered on an SSL TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers. scan becomes part of the Weak Keys collection, an email message can be generated notifying the PKI A public key infrastructure (PKI) is a set of roles, policies, and procedures needed to create, manage, distribute, use, store and revoke digital certificates and manage public-key encryption. administrators that a new certificate with a weak key has been discovered.

• Certificate Left Collection

  The workflow is initiated by an automated task that Keyfactor Command runs periodically against your collections to identify certificates that no longer meet the query criteria of the specified certificate collection.

  For example, when a certificate in the Web Server Certificates collection disappears, a REST request can be made to open a support ticket request to investigate the removal of a web server certificate.

• Enrollment (Including Renewals)

  The workflow is initiated by enrollment for a new or renewed certificate. Steps during the workflow can be used to do things such as require manager approval for the enrollment or manipulate the subject and/or SANs for the certificate request.

• Revocation

  The workflow is initiated by revoking a certificate. Steps during the workflow can be configured to do things such as modify the revocation comment entered when the certificate is revoked, append an additional comment, and store the resulting extended comment in a 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. field.

Workflow Steps

The following customizable workflow steps are supported within the workflows:

• Send Email

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

• Set Variable Data

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

  • ConvertFrom-Csv

  • ConvertFrom-Json

  • ConvertFrom-Markdown

  • ConvertFrom-SddlString

  • ConvertFrom-StringData

  • ConvertTo-Csv

  • ConvertTo-Html

  • ConvertTo-Json

  • ConvertTo-Xml

  • ForEach-Object

  • Get-Command

  • Where-Object

• Use Custom PowerShell

  Run a PowerShell script that has been imported into the Keyfactor Command database. All scripts in the database that have been configured with the workflow category will be available for use. See Extensions Scripts for adding scripts to the database.

• Require Approval

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

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

• Invoke REST Request

  Run a REST (API) request using Active Directory as an identity provider and Basic or Windows authentication. The REST request contents are embedded within the step. It does not call out to an external file.

• Invoke REST Request with OAuth

  Run a REST (API) request using an identity provider other than Active Directory and Token authentication. The REST request contents are embedded within the step. It does not call out to an external file.

• Update Certificate Request Subject\SANS for MSFT CAs (Enrollment Only)

  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), create a resigned CSR to prepare an updated enrollment request for delivery to a Microsoft CA after a previous step in the workflow has been used to update either the SANs in the initial request, subject (DN A distinguished name (DN) is the name that uniquely identifies an object in a directory. In the context of Keyfactor Command, this directory is generally Active Directory. A DN is made up of attribute=value pairs, separated by commas. Any of the attributes defined in the directory schema can be used to make up a DN.) in the initial request or both. This step must be placed later in the workflow than the step(s) to modify the SANs and/or subject. The SANs and subject may be modified with either of the PowerShell step types or a custom step type. The step creates a new CSR using the same public key In asymmetric cryptography, public keys are used together in a key pair with a private key. The private key is retained by the key's creator while the public key is widely distributed to any user or target needing to interact with the holder of the private key. as the original CSR using the updated SAN The subject alternative name (SAN) is an extension to the X.509 specification that allows you to specify additional values when enrolling for a digital certificate. A variety of SAN formats are supported, with DNS name being the most common. and/or subject values. It signs the new CSR with the certificate provided in the step's configuration.

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

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

• Windows Enrollment Gateway - Populate from AD (Enrollment Only)

  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.

In addition to these customizable types of steps, there are built-in steps that you won't see unless you're using the Keyfactor API to view or edit the workflows (see Workflow Definitions). At the end of their respective workflow types there are an enroll step and a revoke step to initiate the actual enrollment or revocation if the workflow reaches the end without being denied or failing. These built-in steps cannot be modified or moved to a different location in the workflow. There are also NOOP steps that indicate the start and end of the workflow for housekeeping purposes.

There are two types of workflow definition:

• Global

  The global workflow definitions are built into the product and cannot be deleted, though they can be modified to add workflow steps, if desired. Global workflow definitions do not have a specific associated key—in the case of the currently available workflows, this is a certificate template—and apply to all requests of the workflow's type (e.g. enrollment) that are not otherwise handled by a custom workflow specifying a key.

• Custom

  Custom workflow definitions are any additional workflow definitions you define beyond the built-in ones. Custom workflows are associated with a specific key (certificate template or certificate collection) and each workflow only applies to requests made using that key.

When requiring approval for enrollment using workflow definitions in Keyfactor Command, templates do not need to be configured to require manager approval at the CA level in the certificate template. This is because the approval handling is fully controlled within Keyfactor Command. In fact, templates generally should not be configured to require CA manager approval when using Keyfactor Command workflow, since this would generally require approval both at the Keyfactor Command level and at the CA level.