Orchestrator Management Operations

The Orchestrator Management page is used to view and manage individual orchestrators (such as the Keyfactor Universal OrchestratorClosed The Keyfactor Universal Orchestrator, one of Keyfactor's suite of orchestrators, is used to interact with servers and devices for certificate management, run SSL discovery and management tasks, and manage synchronization of certificate authorities in remote forests. With the addition of custom extensions, it can provide certificate management capabilities on a variety of platforms and devices (for example Amazon Web Services (AWS) resources, Citrix\NetScaler devices, F5 devices, IIS stores, JKS keystores, PEM stores, and PKCS #12 stores) and execute tasks outside the standard list of certificate management functions. It runs on either Windows or Linux servers or Linux containers.) that are currently, or were previously, connected to the Keyfactor Command server.

The orchestratorClosed Keyfactor orchestrators perform a variety of functions, including managing certificate stores and SSH key stores. management grid displays all orchestrators that have communicated with the server. You can sort the grid by clicking a column header (except for the Capabilities column), rearrange columns by dragging headers, and resize columns by dragging column dividers. By default, disapproved orchestrators are hidden. Select Include Disapproved to display them.

To perform an operation, select one or more orchestrators in the grid and choose an action from the toolbar or the right-click menu. Some actions—such as approve, disapprove, apply blueprintClosed A Blueprint in Keyfactor Command is a snapshot of the certificate stores and scheduled jobs on one orchestrator, which can be used to create matching certificate stores and jobs on another orchestrator with just a few clicks., reset, and request renewal—support multiple orchestrators. Other actions apply to a single orchestrator and are available only from the right-click menu. Additional actions may be available from the extended toolbar menu ().

For descriptions of the grid columns, see View Orchestrator Details.

Tip:  Where to find this in the Management Portal:
Orchestrators → Management → Orchestrator Management Tab

This page supports the standard query format described in Using Search in the Management Portal and includes its own set of query parsers specific to this operation. Use the following parsers to filter and refine results for this page.

Tip:  The following permissions (see Security Roles and Claims) are required to use this feature:

Agents > Management > Read

  • ClientMachine

    Complete or partial matches with the orchestrator name as listed in the Client Machine field.

  • ErrorCode

    Complete or partial matches with the last heartbeat or session registration error code.

    Note:  Heartbeat is used by older orchestrators to maintain connectivity with Keyfactor Command. Newer Universal Orchestrator versions instead re-register at regular intervals.

  • ErrorMessage

    Partial matches with the last heartbeat or session registration error message.

    Note:  Heartbeat is used by older orchestrators to maintain connectivity with Keyfactor Command. Newer Universal Orchestrator versions instead re-register at regular intervals.

  • HighAvailability

    Whether the orchestrator supports high availability (True or False).

    Orchestrators that support high availability can be added to user-managed pools with multiple orchestrators. Orchestrators that do not support high availability are assigned to auto-generated, one-to-one pools.

  • LastSeen

    The date and time when the orchestrator last contacted the Keyfactor Command server. For highly available orchestrators, this value is used with the orchestrator pool’s Remove Transient Orchestrators and Last Seen Threshold (minutes) settings. If removal of transient orchestrators is turned on and the orchestrator has not contacted Keyfactor Command within the configured threshold, the orchestrator is removed from the pool. The default threshold is 30 minutes.

  • OrchestratorPoolName

    Complete or partial matches with the orchestrator pool name.

  • Status

    Status matches the selected category:

    • New
    • Approved
    • Disapproved

  • Username

    Complete or partial matches with the user identity with which the orchestrator is connecting to Keyfactor Command.

  • Version

    Orchestrator version matches the specified comparison and value.

The View Details dialog provides detailed information about a selected orchestrator, including its identity, platform, version, status, capabilities, and recent activity. This information is useful for verifying orchestrator configuration, troubleshooting communication issues, and confirming eligibility for specific jobs or pools.

Tip:  The following permissions (see Security Roles and Claims) are required to use this feature:

Agents > Management > Read

To view details of an orchestrator, double-click an orchestrator or select the orchestrator and choose View Details from the toolbar or right-click menu. The orchestrator details dialog includes the information shown in the following sections.

Details Tab

  • Orchestrator Blueprints

    The last blueprint applied to the orchestrator, if any (see Orchestrator Blueprints).

  • Legacy Thumbprint

    The thumbprint of the certificate previously used by the orchestrator for client certificate authentication before a certificate renewal operation took place (rotating the current thumbprint into the legacy thumbprint). The legacy thumbprint is cleared once the orchestrator successfully registers with a new thumbprint.

  • Current Thumbprint

    The thumbprint of the certificate that Keyfactor Command is expecting the orchestrator to use for client certificate authentication.

  • Authentication Certificate Renewal Request Status

    The last error code, if any, reported from the orchestrator when trying to register a session. This code is cleared on successful session registration.

  • Last Thumbprint Used

    The thumbprint of the certificate that the orchestrator most recently used for client certificate authentication. Usually, this will match the Current Thumbprint.

  • Last Error Code

    The last error code, if any, reported from the orchestrator when trying to register a session. This code is cleared on successful session registration.

  • Last Error Message

    The last error code, if any, reported from the orchestrator when trying to register a session. This message is cleared on successful session registration.

  • Orchestrator Pool Id

    The GUID of the orchestrator pool to which the orchestrator belongs, if applicable.

  • Orchestrator Pool Name

    The name of the orchestrator pool to which the orchestrator belongs, if applicable.

  • High Availability

    Whether the orchestrator supports high availability (True or False).

    Orchestrators that support high availability can be added to user-managed pools with multiple orchestrators. Orchestrators that do not support high availability are assigned to auto-generated, one-to-one pools.

Figure 347: View Details for an Orchestrator

Capabilities Tab

The Capability tab shows a list of Job Types that are correlated to the selected orchestrator's capabilities. For Custom job types only the Name will display (Short Name and Job Type will be blank).

  • Name

    The name of the job type which includes each combination of capability and the job type.

  • Short Name

    The user-defined short name given to the certificate store associated with the job type.

Figure 348: View Details for an Orchestrator

Orchestrators registered with Keyfactor Command have a lifecycle status that controls whether they are allowed to perform jobs. When an orchestrator registers, it is assigned a status of New. Orchestrators in this state cannot perform any jobs until they are approved.

For orchestrators earlier than version 26.2, re-registering with new capabilities resets the status to New, even if the orchestrator was previously approved. Universal Orchestrators version 26.2 or later retain their current status when re-registering with new capabilities.

Tip:  The following permissions (see Security Roles and Claims) are required to use this feature:

Agents > Management > Modify

Approving an orchestrator authorizes it to communicate with Keyfactor Command and begin executing assigned jobs. Disapproving an orchestrator prevents it from performing jobs and removes it from active participation in orchestration tasks.

  • Approve

    To approve orchestrators, select one or more orchestrators and choose Approve from the toolbar or right-click menu. For orchestrators that support high-availability, in the Approve Orchestrators dialog, select an Orchestrator Pool and Save.

    Once an orchestrator is approved, you can schedule jobs for it (Universal Orchestrator) or configure server groups and servers and begin scanning servers (Keyfactor Bash Orchestrator).

    Universal Orchestrators version 26.2 or later support auto-approval with auto-registration. Auto-approval is triggered when the orchestrator specifies an Orchestrator Pool ID during initial registration. If the pool exists and is valid, the orchestrator is automatically approved and can begin executing jobs immediately.

    Important:  Auto-registration is successful only when all the following conditions are met:

    • The orchestrator must be version 26.2 or later.

    • The orchestrator installation must specify the pool ID that the orchestrator will join. Configure this using the following parameters:

      • Windows: -AutoRegistrationPoolId
      • Linux: --auto-registration-pool-id
      • Container: autoRegistrationPoolId

    • The identity presented by the orchestrator must satisfy at least one claim configured for the pool. Allowed claims are defined on the Orchestrator Pool: Claims Tab.

    • Allow Auto-Registration must be turned on for the orchestrator pool. This setting is configured on the Orchestrator Pool: Details Tab.

  • Disapprove

    To disapprove orchestrators, select one or more orchestrators and choose Disapprove from the toolbar or right-click menu. When an orchestrator is disapproved, operations with Keyfactor Command can no longer be carried out by this orchestrator.

Tip:  An orchestrator that has been disapproved can be re-approved. Click the Include Disapproved check box above the toolbar to locate the orchestrator and then approve it again. If an orchestrator that has previously been disapproved in Keyfactor Command reconnects, it will not automatically appear as New again. You will need to locate it in the disapproved orchestrators list and Approve it again.
Important:  With Universal Orchestrators, orchestrator blueprints are supported only in versions earlier than 26.2.

The Generate and Apply Blueprints features let you capture the certificate stores and scheduled jobs from one orchestrator and reuse them to configure another orchestrator. A blueprint represents a snapshot of an orchestrator’s configuration and can be applied to create matching certificate stores and jobs with minimal setup.

Tip:  The following permissions (see Security Roles and Claims) are required to use this feature:

Agents > Management > Modify

To generate a blueprint from an orchestrator, select an orchestrator, open the More options (…) menu from the toolbar, and select Generate Blueprint. For more information about blueprints, see Orchestrator Blueprints.

Figure 349: Generate a Blueprint from an Existing Orchestrator

To apply a blueprint to an orchestrator, select an orchestrator, open the More options (…) menu from the toolbar, and select Apply Blueprint. For more information about blueprints, see Orchestrator Blueprints.

Figure 350: Apply a Blueprint from a New Orchestrator

The orchestrator Reset and Renewal functions are both useful for orchestrator maintenance.

Tip:  The following permissions (see Security Roles and Claims) are required to use this feature:

Agents > Management > Modify

The Reset function can be used when an orchestrator is in an error state or if you've made some changes on the orchestrator side that necessitate a refresh. The orchestrator reset function:

  • Removes all current orchestrator jobs for the selected orchestrator.
  • Deletes all associated certificate stores.
  • Sets the orchestrator status to new.
  • For orchestrators configured to use client certificate authentication, clears the certificate thumbprints stored for the orchestrator to allow it to be reconfigured with a new certificate.
  • For highly available orchestrators, removes the orchestrator from the pool to which it is assigned.

To reset an orchestrator, select an orchestrator and choose Reset from the toolbar or right-click menu.

Figure 351: Reset an Orchestrator

The Renewal function is used for orchestrators that authenticate using a client certificate to initiate certificate renewal before it would occur automatically based on expiration timing.

Tip:  The following permissions (see Security Roles and Claims) are required to use this feature:

Agents > Management > Modify

When triggered, the Renewal function causes the orchestrator to enroll for a new client authentication certificate during its next session registration. This function is used in conjunction with a custom renewal extension to force renewal earlier than the configured warning and expiry windows. For more information, see Register a Client Certificate Renewal Extension.

To request certificate renewal for an orchestrator, select an orchestrator and choose Request Renewal from the toolbar or right-click menu. In the Renewal Status dropdown, select one of the following options:

  • None

    Clears the setting so the orchestrator does not attempt to enroll for a new client authentication certificate based on this control.

  • Request

    The orchestrator attempts to enroll for a new client authentication certificate the next time it registers for a session. Orchestrator activity continues as usual.

  • Require

    The orchestrator must enroll for a new client authentication certificate the next time it registers for a session. A new session is not granted, and orchestrator activity cannot continue until a new certificate is obtained.

Figure 352: Request Renewal for an Orchestrator

To view all active jobs for an orchestrator, select an orchestrator and choose View Jobs from the toolbar or right-click menu. This opens the Scheduled Jobs tab of the orchestrator job status page with the query field populated for the selected orchestrator.

Jobs are assigned at the orchestrator pool level. The results show jobs for the pool that the selected orchestrator belongs to. The query is populated using the selected orchestrator, but jobs are executed by any orchestrator in the pool, not necessarily the one selected.

Note:  All orchestrators are associated with an orchestrator pool. Older orchestrators that do not support high availability use auto-generated, one-to-one pools. These pools are created automatically and cannot be managed directly. Universal Orchestrator versions that support high availability can be added to user-managed pools, which can contain multiple orchestrators and are managed from Orchestrator Pool Management.
Tip:  The following permissions (see Security Roles and Claims) are required to use this feature:

Agents > Management > Read

Figure 353: View Active Jobs for an Orchestrator

To view job history for an orchestrator, select an orchestrator and choose View Job Histories from the toolbar or right-click menu. This opens the Job History tab of the orchestrator job status page with the query field populated for the selected orchestrator.

Jobs are scheduled at the orchestrator pool level, but job history is shown per orchestrator, reflecting the specific orchestrator that executed each job.

Tip:  The following permissions (see Security Roles and Claims) are required to use this feature:

Agents > Management > Read

Figure 354: View Job History for an Orchestrator

To view the certificate stores associated with an orchestrator, select a row in the orchestrator management grid and choose View Certificate Stores from the toolbar or right-click menu. This will take you to the certificate stores page with the query field populated by the orchestrator pool for the selected orchestrator.

Figure 355: View Certificate Stores for an Orchestrator

Tip:  This option applies to orchestrators that support certificate store–based capabilities (for example, JKS, PEM, and IIS). It does not apply to SSLClosed TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers. or SSH.

The fetch logs function is designed to retrieve a portion of the tail end of the orchestrator log for easy review. It is supported for both the Keyfactor Universal Orchestrator and the Native Agent.

Note:  The Fetch Logs job is supported only for Keyfactor Command instances running on Windows under IIS.

To schedule a job to fetch the logs, select an orchestrator, open the More options (…) menu from the toolbar, and select Fetch Logs. The job will be scheduled to run immediately, which means it should complete within a few minutes depending on other activity occurring at the same time. The fetch logs job will appear in Scheduled Jobs under Orchestrator Job Status with a job type of Fetch Logs and when complete will appear in Job History (see Job History).

For Native Agent fetch log jobs, when the job is complete, locate the completed job on the Job History tab and double-click or click Expand Message from the toolbar or right-click menu. The job status message details show 4000 characters of the tail end of the log.

To review the log data for logs fetched from a Universal Orchestrator, use the GET /OrchestratorJobs/JobStatus/Data Keyfactor APIClosed An API is 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. method. See GET Orchestrator Jobs Job Status Data for more information.

Tip:  The orchestrator must be approved and have the LOGS capability in order for the Fetch Logs function to be turned on.
Note:  The orchestrator must be configured to write log entries to a file to allow the Fetch Logs function to be able to retrieve logs. The Universal Orchestrator does this by default, but the Native Agent needs to be configured appropriately to write to a file to support this feature.

To set up logging on the Native Agent, see the Native Agent configuration instructions to configure logging and start the orchestrator with the appropriate logging level to allow for the use of the Fetch Logs feature:

https://github.com/Keyfactor/Keyfactor-CAgent
Tip:  If jobs for the Universal Orchestrator fail with messages similar to the following:
Response status code does not indicate success: 413 (Request Entity Too Large)

This indicates that the amount of data being returned for the job is larger than the Keyfactor Command server path is configured to accept. Contact Keyfactor support for assistance.

The Delete function is used to fully remove an orchestrator from Keyfactor Command along with any associated jobs, certificate stores, and configured SSH servers.

Tip:  The following permissions (see Security Roles and Claims) are required to use this feature:

Agents > Management > Modify

If you only want to remove an orchestrator from view without this impact, you can mark it Disapproved instead. It will then be hidden from view unless you select Include Disapproved.

To go forward with deletion, first disapprove the orchestrator. The Delete function can only be used on orchestrators that have been disapproved. Select the orchestrator and choose Delete from the toolbar or right-click menu. You will be prompted to confirm that you want to delete this orchestrator and understand the consequences of this action. Type the orchestrator name and click Submit to complete the deletion.

Figure 356: Deletion Confirmation for an Orchestrator