Quarterly Release 12.3 Notes

August 2024

For a complete list of the items included in this release, see Release Note Details v12.3.

Highlights

• The concept of a certificate owner has been introduced to Keyfactor Command.The optional certificate owner is a security role defined in Keyfactor Command (see Security Roles and Claims). A certificate owner may be assigned to a certificate in any of these ways:

  • Automatically during 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. synchronization if the default 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). pattern associated with the certificate template A certificate template defines the policies and rules that a CA uses when a request for a certificate is received. or enrollment pattern system-wide settings policy has been configured with a default certificate owner prior to initial import of the certificate. Certificates already in Keyfactor Command are not updated on subsequent synchronizations. See Configuring System-Wide Settings and Enrollment Pattern - Enrollment Pattern: Policies Tab).

  • Automatically during SSL TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers. scanning if the default enrollment pattern associated with the certificate template or enrollment pattern system-wide settings policy has been configured with a default certificate owner prior to initial import of the certificate. Certificates already in Keyfactor Command are not updated on subsequent scans.

  • Automatically during certificate store inventories if the default enrollment pattern associated with the certificate template or enrollment pattern system-wide settings policy has been configured with a default certificate owner prior to initial import of the certificate. Certificates already in Keyfactor Command are not updated on subsequent inventory jobs.

  • Manually in 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 (seePFX Enrollment and POST Enrollment PFX) if the enrollment pattern or system-wide settings Certificate Owner Role policy has been configured as Optional or Required (rather than Hidden).

  • Manually in 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. Enrollment (see CSR Enrollment and POST Enrollment CSR) if the enrollment pattern or system-wide settings Certificate Owner Role policy has been configured as Optional or Required (rather than Hidden).

  • Manually in Add Certificate (see Add Certificate and POST Certificates Import).

  • Manually in Certificate Details (see Change Owner and PUT Certificates ID Owner).

  • As part of a workflow A workflow is a series of steps necessary to complete a process. In Keyfactor Command, it refers to the workflow builder, which allows you to automate event-driven tasks such as when a certificate is requested, revoked or found in a certificate store. by calling the PUT /Certificates/{id}/Owner Keyfactor API 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. endpoint An endpoint is a URL that enables the API to gain access to resources on a server. (see PUT Certificates ID Owner) from an Invoke REST Request workflow step.

  The certificate owner can be viewed on the Status tab of the certificate details dialog.

  An email address can be added to each security role for use with certificate owners. This address can be used from workflows to direct email messages to the owner of certificates for uses such as certificate expiration alerts (assuming the certificate owner for the certificates has been populated).

  Two new tokens have been added to workflow to reference the certificate owner: $(ownerroleid) and $(ownerroleemail)

  A new query field—OwnerRoleName—for certificate owner has been added to the certificate search page. This field supports exact matches against a provided list of one or more security role names. The new %ROLES% special value can be used in place of a specific security role in Owner Role Name queries to return all the certificates that are either marked as owned by a role of which the querying user is a member or not marked as owned by a role of which the querying user is a member. This option can be used only with the -in and -notin operators.

  To support the certificate owner addition, security roles can no longer contain a comma in the role name. Any existing security roles containing commas are still allowed, but if they are edited and the name changed, commas will no longer be allowed in the name.

  Certificate requests are now retained in the Keyfactor Command database for two synchronizations of their associated CA before being deleted to allow for linking of any certificate owner information from the certificate request to the resulting issued certificate.

• A new workflow step type—Update 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.—has been added that makes updating a metadata field with data from a workflow easier.

Changes & Improvements

• Alerts and Monitoring

  • An option has been added to select support for PowerShell 5.1 in alerts rather than PowerShell 7.

• Certificate Operations

  • On the Certificate Search page in the certificate download dialog, the options to download a certificate as a .cer or .crt file have been added. These will be available only if Include Private Key is not selected.
  • If a certificate is being revoked as part of Revoke All operation, Revoke All: is appended before the current audit log message so that users know that the certificate revocation was done as part of a revoke all operation.
  • A new PublishCRL field to enable or disable publication of a new CRL A Certificate Revocation List (CRL) is a list of digital certificates that have been revoked by the issuing Certificate Authority (CA) before their scheduled expiration date and should no longer be trusted. following revocation has been added to the POST /Certificates/Revoke Keyfactor API endpoint. This option is not available in the Management Portal.

• Dashboard and Reports

  • The Expiration Report now has a new column Renewed that states whether or not a certificate has been renewed. It's values are either Yes or No. It is a sortable column.
  • The Certificate Count Grouped by Single Metadata Field report now supports the new email metadata field type.
  • The Debug Dashboard and Embedded Reports application setting is now available that allows the user to enable debugging on both the dashboard and in reports. Previously this could only be enabled for reports.

• Enrollment

  • PFX Enrollment and CSR Enrollment now include a separate add dialog for SANs that simplifies the process of adding multiple SANs of the same type to a certificate request.

  • A new application setting, Allow Cryptographic Service Providers (CSPs), has been added that optionally displays the Target CSP field on the PFX enrollment page and the certificate details download dialog which allows the user to select a cryptographic service provider (CSP) to associate with the certificate in the 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. Cryptography Standard #12 (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.) key provider name attribute (OID Object identifiers or OIDs are a standardized system for identifying any object, concept, or "thing" with a globally unambiguous persistent name. 1.3.6.1.4.1.311.17.1). This option is only supported for certificates downloaded in PFX format. A field called MicrosoftTargetCSP has been added to the POST /Enrollment/PFX and POST /Certificates/Recover Keyfactor API endpoints to support this functionality.

  • A new application setting, Allow Periods in Certificate Filenames, offers the option to choose whether downloaded certificate file names are generated with periods (e.g., server123.keyexample.com.pfx), if set to True, or without (e.g., server123keyexamplecom.pfx), if set to False. The default value of the application setting is True.

    Important:  In previous versions of Keyfactor Command, the default file name for downloaded certificate files was the CN A common name (CN) is the component of a distinguished name (DN) that represents the primary name of the object. The value varies depending on the type of object. For a user object, this would be the user's name (e.g. CN=John Smith). For SSL certificates, the CN is typically the fully qualified domain name (FQDN) of the host where the SSL certificate will reside (e.g. servername.keyexample.com or www.keyexample.com). without periods. If you’re upgrading from a previous version and wish to continue to generate file names in the previous format, you will need to change this application setting to False.

  • A new application setting, Enable warning for CSR generated in Command, offers the option to disable the warning that appears in CSR enrollment if a user attempts to use a CSR generated in Keyfactor Command. The warning message says:

    It looks like you are using a CSR generated from the Command platform to perform a CSR enrollment. CSRs are intended to be generated where the private key will reside. To generate a PFX, use PFX enrollment. Do you still wish to enroll for this certificate?

• Identity Providers and Authentication

  • The functionality of the logout button is updated as following:

    • If a user logged in via Active Directory, clicking the logout button will log the user out and bring them to the Active Directory log out page.

    • If a user logged in via OAuth, clicking the logout button will log the user out and bring the user to the identity provider log in page for the identity provider the user used to log in.

    • A logout button is added to the header on these error pages, where it was missing previously: Permission Denied , General Error, Unsupported Browser, SSH The SSH (secure shell) protocol provides for secure connections between computers. It provides several options for authentication, including public key, and protects the communications with strong encryption. not using Active Directory.

  • When a user encounters an authentication error, they will be shown a failed login page which will direct them to IDP configuration in the documentation and will have a clear message that the login has failed.
  • Identity providers can now be enabled and disabled in the Keyfactor Command Management Portal or through the Keyfactor API. Newly added identity providers are always enabled. Existing identity providers may be disabled, if desired. Identity providers cannot be disabled if the provider is used as the default identity provider for login or as the Identity Provider Name selected in the Identity Provider Token Credentials section of the Authentication tab in the configuration wizard. When an identity provider is disabled, the following will not be available for that identity provider:

    • Users cannot authenticate to the Keyfactor Command Management Portal or Keyfactor API using a disabled identity provider.

    • Orchestrators cannot authenticate against the Orchestrators API using a disabled identity provider.

    • On the Orchestrator Keyfactor orchestrators perform a variety of functions, including managing certificate stores and SSH key stores. Management page, the orchestrators last seen time will not update when the orchestrator is configured to use a disabled identity provider.

    • Instances of the CA Connector The Keyfactor CA Connector is installed in the customer environment to provide a connection between a CA and Keyfactor Command when a direct connection is not possible. It is supported on both Windows and Linux and has versions for Microsoft (Windows only) or EJBCA CAs. Client cannot authenticate against the CA Connector API using a disabled identity provider.

    • On the 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. CA Connector page, CA connectors will display as not connected for CA Connector Clients using a disabled identity provider.

    • On the Application Settings page on the Console tab, only enabled identity providers will appear in the dropdown for the Default Identity Provider application setting.

    • In the configuration wizard, only enabled identity providers will appear in the dropdowns for the Identity Provider in the Identity Provider section and the Identity Provider Name in the Identity Provider Token Credentials section of the Authentication tab.

  • When trying to log into Keyfactor Command with a disabled identity provider, users will be redirected to an error page that clearly explains the authentication issue.
  • The Keyfactor API Reference and Utility and Keyfactor Command Management Portal dashboard now handle hybrid authentication deployments, where two Keyfactor Command servers using different authentication mechanisms share the same database.
  • When adding an identity provider in the Management Portal, you can now click Import Discovery Document to enter the discovery URL for the identity provider and automatically populate the Authority, AuthorizationEndpoint, TokenEndpoint, JSONWebKeySetUri, and UserInfoEndpoint fields.

• Logging

  • In the NLog_ Orchestrators. config log at Debug level, you can now see messages similar to the following indicating the processing time for each request:

    2024-06-26 02:06:01.1010 4000f383-0000-eb00-b63f-84710c7967bb b30d6779-1755-4314-b630-3d616b0b3dd6 Keyfactor. Web.AgentsWeb. Middleware. AgentAddLog RequestDuration Middleware [Debug] - Processed 'https://keyfactor. keyexample.com /KeyfactorAgents /AnyInventory /Update' in '183 ms'

  • In the API log (Command_API_Log.txt) at TRACE level, all queries which utilize the ExecuteDapperQuery operations will display a query elapsed time log similar to:

    Execution time elapsed : 1 minute, 34 seconds, 14 milliseconds.
    • If 0 minutes have passed, minutes will not be included
    • If 0 seconds have passed, seconds will not be included
    • Milliseconds will always be included

  • To make it easier to correlate log messages with a given orchestrator in the Orchestrator (Agent) API, especially if multiple orchestrators are making calls to the API at the same time, the following changes have been made:

    • The \WebAgentServices\Configuration\NLog_Orchestrators.config log file will display the correlation token ID regardless of the LogLevel configured.
    • For the Keyfactor Bash Orchestrator The Bash Orchestrator, one of Keyfactor's suite of orchestrators, is used to discover and manage SSH keys across an enterprise., orchestrator ID will be cached in an OrchestratorId.txt file and the orchestrator log file.
    • For the Keyfactor Universal Orchestrator 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., the orchestrator ID will be stored in the orchestratorId configuration field in the orchestrator's appsettings.json configuration file after the initial API request and, when the Nlog level is configured for TRACE, the orchestrator ID will be logged in the Orchestrators log.

• Orchestrators

  • An extended button menu () has been added to the orchestrator management page to support the number of actions available on the page. Several of the actions previously available at the top of the grid are now available through the extended button menu.
  • A new application setting, Orchestrator Job History Limit, offers the option to configure the number of orchestrator job history records to retain for inventory jobs.

• Security

  • The CSR generation permissions are now separate from the CSR enrollment permissions so that a user may be granted either CSR generation or CSR enrollment permissions but not both. On an upgrade from version 11.0 or higher, the following updates will be made:

    • Any permission set containing the /certificates/enrollment/csr/ permission will be updated to contain both the /certificates/enrollment/csr/ and /certificates/enrollment/csr_generation/ permissions.

    • Any permission set containing the /certificates/enrollment/csr/generation/ permission will switch to the /certificates/enrollment/csr_generation/ permission.

    • Any security role containing the /certificates/enrollment/csr/ permission will be updated to contain both the /certificates/enrollment/csr/ and /certificates/enrollment/csr_generation/ permissions.

    • Any security role containing the /certificates/enrollment/csr/generation/ permission will switch to the /certificates/enrollment/csr_generation/ permission.

  • Users with the following permissions are no longer automatically granted Certificates > Collections > Read permissions inherited from these permissions. This permission now must be specifically granted to the users at either the 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). level or globally if it is desired that these users have read access to certificates and collections.

    • Certificates > Collections > Delete
    • Certificates > Collections > Metadata Modify
    • Certificates > Collections > Download 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.
    • Certificates > Collections > Revoke

  • Keyfactor Command now offers the option of a PAM database stored in the Keyfactor Command database into which secrets may be stored. The local PAM PAM (Privileged Access Management): Controls privileged access by vaulting credentials, enforcing least-privilege/just-in-time access, rotating secrets, and auditing sessions. Across Keyfactor products, PAM protects diverse sensitive operations and secrets—for example certificate stores and CA credentials—via built-in or third-party providers; external integrations are delivered as custom PAM extensions (several published on Keyfactor’s public GitHub). provider is created with a provider type of LocalDB and then secrets are created and managed with the followed new Keyfactor API endpoints:

    • GET /PamProviders/Local/{providerId}/Entries
    • POST /PamProviders/Local/{providerId}/Entries
    • PUT /PamProviders/Local/{providerId}/Entries
    • DELETE /PamProviders/Local/{providerId}/Entries

    Once created, the local PAM secrets may be used in Keyfactor Command everywhere PAM secrets may be used.

  • Scheduling of CRL revocation monitoring locations (the Monitoring Execution Schedule) is now managed with a new permission: /monitoring/alerts/schedule/revocation/. As of this release, the /monitoring/alerts/schedule/ and /monitoring/alerts/schedule/revocation/ permissions have the same functionality, but future releases may expand on the /monitoring/alerts/schedule/ permission with additional scheduling permissions. Users with the new /monitoring/alerts/schedule/revocation/ permission and without /monitoring/alerts/modify/ can modify the Monitoring Execution Schedule for a CRL revocation monitoring endpoint but cannot make any other modifications to CRL endpoints or any modifications to OCSP endpoints.

• SSL Scanning

  • SSL scanning has been modified to support storing scan jobs with port ranges where possible, significantly streamlining scanning jobs and reducing the amount of data stored in the database for each job.
  • SQL queries used in SSL scanning have been improved to increase performance in high load environments.

• Workflow

  • There is a new token, $(InitiatingUserRoles), available for use with workflow definitions that will provide the role information about a workflow instance initiating user. This token resolves to a comma-separated array of strings containing role names. This token will be provided by default on non-timer service initiated workflows.
  • An option has been added to toggle on support for PowerShell 5.1 in Use Custom PowerShell steps rather than PowerShell 7. This option is not available in Set Variable Data steps.
  • Update: A workflow instance can now send email messages to all email addresses found in a comma-separated list such as might be built using a PowerShell script.

• System Requirements

  • The Keyfactor Universal Orchestrator now requires Microsoft .NET Runtime version 8.0 (x64).
  • Note: The SQL connection string for the KeyfactorAnalysis virtual application does not support MultiSubnetFailover.

• CA Connector

  • The following new application settings related to the CA Connector and Task Queue have been added:

    • AuthZ Cache Expiration (minutes)

    • Heartbeat Interval (minutes)

    • Queue Max Length

    • Job Pickup Wait Seconds

    • Job Data Retry Delay Seconds

    • Job Data Wait Seconds

    For more information, see Application Settings: CA Connectors Tab and Application Settings: Task Queue Tab.

  • A Refresh button has been added to the CA Connectors tab of the Certificate Authorities page.
  • The layouts of the Add/Edit CA Connector dialog and Task Queue Connection tab in Certificate Authorities have been updated for easier reading.
  • Modifications have been made to handling CA connector pools. The CA Connector Pool Name, Type and Enabled status cannot be modified on an edit if the pool is in use by a CA and the connector being edited is the last enabled connector in the pool. A CA connector cannot be deleted if it is the last one in its pool with an enabled status and the pool is configured for use by at least one CA.
  • When the CA Connector API starts, it attempts to establish a connection to the message queue. Configuration options have been added in the CA Connector appsettings.json file to control how frequently this connection attempt to the message queue should be retried (ConnectRetryOptions) if the first attempt fails.
  • The CA Connector Client install now does a connectivity test to Keyfactor Command and the OAuth identity provider before beginning the install to confirm a connection to both. If the connection to either fails, including SSL connectivity issues, the install will be terminated. Some connection states result in a warning and the installation will continue. For example, a warning will appear if no CA connector record matching the name of the CA Connector Client being installed is found in Keyfactor Command. See the CA Connector Client Preparing documentation.
  • A NoValidate parameter A parameter or argument is a value that is passed into a function in an application. has been added to the CA Connector Client to skip the connectivity test to Keyfactor Command and the OAuth identity provider.

• Data Migration

  • A new Keyfactor API endpoint has been added to support migration of user data from one user record to a new or existing alternate user record (see POST Users Migrate). User records are not the same as claims or identities. User records are generated from a number of different sources and used in a variety of ways. When a user logs into the Keyfactor Command Management Portal, a user record is generated for this user. If the user has been granted access to Keyfactor Command via a group security claim, there will not be a security claim for the individual user’s name, but a user record for the individual is required to track user-specific settings and data, including:

    • Management Portal dashboard settings for the user, which are unique to each user.
    • The requester field on certificates and certificate requests, which will contain the user’s account name, not the group claim used to grant the user access to Keyfactor Command.
    • User names associated with workflow instances—the user who initiated the workflow instance, the user who restarted the workflow instance, if applicable.
    • User names associated with providing input signals to workflow instances—e.g., users who approve requests that require approval.

    The migrate endpoint updates user data in all of the above locations. If the requester field on a certificate or certificate request is updated by the migrate endpoint, subsequent CA synchronizations will not overwrite this requester information with the older requester name.

    This is most commonly used to migrate users from Active Directory to an OAuth identity provider or from one OAuth identity provider to another but can also be used to migrate users from the “Unknown” identity provider to a known identity provider or handle changes in user information (e.g., a user name change). For more information, see POST Users Migrate.

Fixes

• Global permissions for users and groups other than Administrator were not displaying correctly in the certificate collections Permissions dialog accessed from the certificate collections page. Permissions assigned on a collection-by-collection basis were displayed correctly in this dialog.
• The SSL Default Agent Pool would disappear from the Orchestrator Pools Definition grid if no orchestrators were assigned to the pool.
• The Keyfactor Bash Orchestrator was encountering errors while processing a larger number of SSH keys and has been updated to avoid the previous limitations.
• OCSP monitoring requests were missing a content-type header, resulting in a 401 error when making queries against some types of OCSP servers. Both Microsoft and EJBCA OCSP servers are supported.
• It was possible in the Keyfactor Command configuration wizard to get into a state where a value entered on the Administrative Users tab was invalid but the user could not continue the configuration wizard after correcting it without browsing to another tab in the configuration wizard and making a change on one of these tabs first.
• When switching Keyfactor Command from one fully configured database to another fully configured database using the configuration wizard, the SQL connection strings configured for each virtual directory that allow Keyfactor Command to communicate with SQL were not updated unless the user went through the configuration wizard and checked the boxes for “This module has previously been configured. Check this checkbox to change or reapply settings.” on each tab associated with a virtual directory. Now all connection strings are updated without needing to make any changes in the configuration wizard.

• Search select dropdowns, where you begin typing something and valid values for the field matching those characters are populated in a dropdown from which you may select, have been performance tuned to reduce network load. This type of search select dropdown is found in workflow where you select the workflow step type.

• Certificate renewal with the Configure option was not setting the renew flag, which could cause the renewed certificate not to be pushed to all certificate store locations if it was found in multiple locations.
• Workflows using a REST step could get stuck in a running state if the REST request in the REST step threw an exception.
• SCEP enrollment requests were failing against the Keyfactor CA Policy Module.

Deprecation

• See the 12.0 release notes (Deprecation & Removals) regarding deprecation and removal of the following products: Keyfactor Java Agent 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., Keyfactor Windows Orchestrator, Keyfactor Mac Auto-Enroll Agent, and Classic API.

Known Issues

• The Expiration Alert Renewal Handler supported not specifying a CA or Template, forcing it to use the expiring certificate's CA and Template when submitting the enrollment request. This is not supported for the Expiration Renewal Workflow Step. Please take that into consideration when migrating alert handlers to workflows.

• When the response from a workflow REST step is returned as a JSON string containing an array of values, selected values from the array (as opposed to the response as a whole) cannot be specified in subsequent workflow steps such as email messages. In other words, $(MyResponse) will output the entire returned value, but $(MyResponse[0]) or $(MyResponse[0].DisplayName) will not output the first element of the array or the display name of the first element of the array. The data needs further processing in order to be used (see Invoke REST Request).

• Searches for workflow instances using the InitiatingUserName query parser fail with an “invalid column name” error. This will be corrected in a future release.

API Endpoint Change Log

Please review the information in the API Change Log for this release carefully if you have implemented any integration using these endpoints: API Change Log v12.3.