Orchestrator Management Operations

To select a single row in the orchestratorClosed Keyfactor orchestrators perform a variety of functions, including managing certificate stores and SSH key stores. management grid, click to highlight it and then select an operation from either the top of the grid or the right-click menu. The approve, disapprove, apply blueprintClosed 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 operations can be done on multiple orchestrators at once. To select multiple rows, click the checkbox for each row on which you would like to perform an operation. Then select an operation from the top of the grid. The right-click menu supports operations on only one orchestrator at a time.

To view details of an orchestrator, double-click the orchestrator, right-click the orchestrator and choose View Details from the right-click menu, or highlight the row in the grid and click View Details at the top of the grid. The orchestrator details dialog includes this information:

The GUID of the orchestrator.

The host nameClosed The unique identifier that serves as name of a computer. It is sometimes presented as a fully qualified domain name (e.g. servername.keyexample.com) and sometimes just as a short name (e.g. servername). of the orchestrator machine, either short or fully qualified depending upon how the machine reports itself.

The account the orchestrator is using to authenticate to Keyfactor Command, which may or may not be the same as the account under which the orchestrator is running. For example, 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 (e.g. 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. service runs as a service account on the orchestrator machine that may be a local account on the machine, the Windows built-in Network Service account, or an Active Directory domain account. If it’s an Active Directory account, it will be an account in the forestClosed An Active Directory forest (AD forest) is the top most logical container in an Active Directory configuration that contains domains, and objects such as users and computers. to which the orchestrator server is joined. The orchestrator’s identity to make the connection to the Keyfactor Command server will be a service account for the identity provider configured for Keyfactor Command, which may be Active Directory, Keyfactor Identity Provider, Auth0, another OAuth 2.0 complient identity provider, or a federated identity provider. If it’s Active Directory, it will be an identity from the forest in which Keyfactor Command is installed, which may be a different forest from the forest in which the orchestrator is installed.

The platform of the orchestrator—Java for the Java AgentClosed The Java Agent, one of Keyfactor's suite of orchestrators, is used to perform discovery of Java keystores and PEM certificate stores, to inventory discovered stores, and to push certificates out to stores as needed., .NET Core for the Keyfactor Universal Orchestrator, Bash for the Keyfactor Bash OrchestratorClosed The Bash Orchestrator, one of Keyfactor's suite of orchestrators, is used to discover and manage SSH keys across an enterprise., and ObjectiveC for the Mac agent, for example.

The version number that the orchestrator has reported.

Whether the orchestrator has been approved for operations with the Keyfactor Command server. Newly registered orchestrators show New in this column. Disapproved orchestrators show Disapproved.

The date and time when the orchestrator last contacted the Keyfactor Command server.

The target capabilities that are supported by that orchestrator as appropriate for the type of orchestrator. This includes custom capabilities. Some of the follow capabilities have been deprecated and will only be found on upgraded systems. For example:

The column displays a comma-separated list of the certificate stores types associated with each orchestrator. In many cases, the short name matches the capability.

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

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.

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

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

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

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

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

Figure 271: View Details for an Orchestrator

When orchestrators first appear in Keyfactor Command, they have a status of New. The orchestrator cannot perform any jobs while it has this status. To approve an orchestrator, highlight the row in the orchestrator management grid and click Approve at the top of the grid or right-click the orchestrator in the grid and choose Approve from the right-click menu. Once you have approved a Keyfactor Universal Orchestrator or Keyfactor Java Agent, you can schedule jobs for the orchestrator. Once you have approved an SSH Orchestrator, you can configure server groups and servers for that orchestrator and begin scanning servers. Once you have approved a Mac enroll agent, users can enroll for certificates from that Mac. Some orchestrators may be configured for auto-approval via auto-registration (see Orchestrator Auto-Registration).

To disapprove an orchestrator, highlight the row in the orchestrator management grid and click Disapprove at the top of the grid or right-click the orchestrator in the grid and choose Disapprove from the 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 at the top of the grid to locate the orchestrator and then approve it again. If an orchestrator that has previously been disapproved in Keyfactor Command reconnects—after an update or corrections of an issue that took it offline, for example—it will not automatically appear as New again. You will need to locate it in the disapproved orchestrators list and Approve it again.

To generate a blueprint from an orchestrator, highlight the row in the orchestrator management grid and click Generate Blueprint at the top of the grid or right-click the orchestrator in the grid and choose Generate Blueprint from the right-click menu. For more information about blueprints, see Orchestrator Blueprints.

Figure 272: Generate a Blueprint from an Existing Orchestrator

To apply a blueprint to an orchestrator, highlight the row in the orchestrator management grid and click Apply Blueprint at the top of the grid or right-click the orchestrator in the grid and choose Apply Blueprint from the right-click menu. For more information about blueprints, see Orchestrator Blueprints.

Figure 273: Apply a Blueprint from a New Orchestrator

The orchestrator reset and renewal functions are both useful for orchestrator maintenance. 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.

To reset an orchestrator, highlight the row in the orchestrator management grid and click Reset at the top of the grid or right-click the agent in the grid and choose Reset from the right-click menu.

Figure 274: Reset an Orchestrator

The renewal function is used for orchestrators that are authenticating via client certificate to initiate a client certificate renewal before this would occur automatically based on approaching certificate expiration. The renewal function requests or requires that the orchestrator enroll for a new client authentication certificate on the orchestrator's next session registration. It is used in conjunction with a custom renewal extension on the orchestrator to force the orchestrator to enroll for a new certificate before it would normally do so based on the warning and expiry windows. See Register a Client Certificate Renewal Extension for more information and custom renewal extensions on the renewal process.

To request certificate renewal for an orchestrator, highlight the row in the orchestrator management grid and click Request Renewal at the top of the grid or right-click the agent in the grid and choose Request Renewal from the right-click menu. In the Renewal Status dropdown, select one of the available options:

  • None
    Unset the value so that the orchestrator will not request a new client authentication certificate (based on this value).

  • Request
    The orchestrator will request a new client authentication certificate when it next registers for a session. Orchestrator activity will be allowed to continue as usual.

  • Require
    The orchestrator will request a new client authentication certificate when it next registers for a session. A new session will not be granted and orchestrator activity will not be allowed to continue until the orchestrator acquires a new certificate.

Figure 275: Request Renewal for an Orchestrator

To view all the active jobs for an orchestrator, highlight the row in the orchestrator management grid and click View Jobs at the top of the grid or right-click the orchestrator in the grid and choose View Jobs from the right-click menu. This will take you to the scheduled jobs tab of the orchestrator job status page with the query field populated by the selected orchestrator.

Figure 276: View Active Jobs for an Orchestrator

To view job history for an orchestrator, highlight the row in the orchestrator management grid and click View Job Histories at the top of the grid or right-click the orchestrator in the grid and choose View Job Histories from the right-click menu. This will take you to the job history tab of the orchestrator job status page with the query field populated by the selected orchestrator.

Figure 277: View Job History for an Orchestrator

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

Figure 278: View Certificate Stores for an Orchestrator

Tip:  This option is only useful for orchestrators that have a capability that makes use of certificate stores (e.g. JKS, PEM, IIS, etc. not SSL 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.

To schedule a job to fetch the logs, click Fetch Logs from the actions buttons at the top of the Orchestrator Management grid or from the right-click menu. 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 right-click menu or at the top of the grid. 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 Keyfactor Universal Orchestrator, use the GET /OrchestratorJobs/JobStatus/Data Keyfactor APIClosed 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 enabled.
Note:  The orchestrator must be configured to write log entries to a file in order for the Fetch Logs function to be able to retrieve logs. The Keyfactor Universal Orchestrator does this by default, but the Native Agent needs to be configured appropriately to write to a file in order 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

Figure 279: Sample Native Agent Fetch Log Results

Tip:  If jobs for the Keyfactor Universal Orchestrator fail with messages similar to the following:

2021-08-05 10:47:23.1940 Keyfactor.Orchestrators.JobExecutors.OrchestratorJobExecutor [Debug] - Response status code does not indicate success: 413 (Request Entity Too Large).

at System.Net.Http.HttpResponseMessage.EnsureSuccessStatusCode() in /_/src/System.Net.Http/src/System/Net/Http/HttpResponseMessage.cs:line 172

at Keyfactor.Orchestrators.Services.HttpService.SendPostAsync[T](String uri, Object requestData, Dictionary`2 headers) in F:\BuildAgents\Default1\_work\24\s\src\OrchestratorServices\HttpService.cs:line 38

This indicates that the amount of data being returned on the job is greater than IIS on the Keyfactor Command server is configured to accept. You will need to make modifications to the IIS settings on your Keyfactor Command server to allow it to accept larger incoming pieces of content. You can do this using the configuration editor built into the IIS management console. Make the setting changes at the Default Web Site level (or other web site, if you installed your Keyfactor Command in an alternate web site). There are three settings that may need modification:

  • system.webServer/security/requestFiltering/requestLimits/maxAllowedContentLength

  • system.webServer/serverRuntime/uploadReadAheadSize

  • system.web/httpRuntime/maxRequestLength

The most important of these is maxAllowedContentLength. Set this value to at least 2,500,000 bytes to support the maximum returned data size for the Keyfactor Universal Orchestrator. The default values of 4096 KB for the maxRequestLength and 49,152 for uploadReadAheadSize will probably be sufficient in most environments, unless you are also using SSL scanning (see Monitoring Network Scan Jobs with View Scan Details). (The system.webServer values are set in bytes while the system.web values are set in kilobytes.)

Figure 280: Modify IIS Settings for Keyfactor Universal Orchestrator Custom Jobs: maxAllowedContentLength