Preparing

This section describes the steps that need to be taken prior to a Keyfactor Command upgrade to complete the prerequisites, create any required supporting components, and gather the necessary information to complete the Keyfactor Command upgrade process.

The following are some key things to be aware of and preparation steps that need to be addressed in order to upgrade to version 24.4.1.

Release 24.4 or Later

• Customers wishing to migrate from Keyfactor Command implementations on Windows under IIS to implementations in containers under Kubernetes who are using application-level encryption, will need to re-encrypt their Keyfactor Command databases using a raw AES key before migrating to an implementation in containers under Kubernetes. For more information, see Application-Level Encryption.
• Customers wishing to migrate from Keyfactor Command implementations on Windows under IIS to implementations in containers under Kubernetes who are using event handlers with the legacy alerting system (see Alerts), will need to migrate these alerts to workflows prior to migrating to an implementation in containers under Kubernetes. For more information, see Using Event Handlers.
• Release 24.4 introduces a separate, command-line, database upgrade tool that can be used ahead of the Keyfactor Command software installation to bring the database up to the current version. This can be used to test database upgrades and resolve any issues before going forward with a full Keyfactor Command upgrade. For more information, see Using the Database Upgrade Tool.
• Keyfactor Command now offers the option to store secret data such as passwords in a Keyfactor Command local PAM database. Consider whether you want to migrate to using this local Keyfactor Command PAM solution for your secrets. Note that this option was introduced in release 12.3 and fully realized in release 24.4 with the availability of secret management through the Keyfactor Command Management Portal.

Release 12.0 or Later

• Customers wishing to be FIPS-compliant should select Configure Encryption on the Database tab of the Keyfactor Command configuration wizard and then select Application and SQL and select an encryption certificate. For more information, see Application-Level Encryption.
• Keyfactor Command version 12.0 and later require ASP.NET Core version 8.0. For more information, see System Requirements.

Release 11.0 or Later

• Classic 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.

  Important:  The Classic API, also known as the CMS API or CMSAPI, was removed in Keyfactor Command version 11.0. Customers should migrate all uses of the Classic API to the Keyfactor API prior to upgrading to Keyfactor Command versions 11.0 or later.

• If you’re migrating from Active Directory to an OAuth identity provider in version 11.0 or later, be aware that it’s important to leave Basic Authentication and Windows Authentication disabled in IIS once you enable the OAuth option in the Keyfactor Command configuration. Attempting to use OAuth with Basic Authentication and/or Windows Authentication enabled can result in unexpected access to Keyfactor Command by users with lingering Active Directory permissions in Keyfactor Command from before the upgrade.

  Important:  Before migrating an existing implementation from Active Directory to OAuth or vice versa, please see Migrating to a New Identity Provider.

• Select substitutable special text tokens provide the ability for parts of the Keyfactor Command system to look up data in Active Directory to use in alerts and workflows. Lookups for these locate the object in Active Directory identified by the user or computer account that requested the certificate from the 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. and substitute the contents of the referenced attribute. For example, an alert might reference requester:displayname to look up the requester’s display name in Active Directory.

  The substitutable special text tokens that begin requester: or principal: (but not the standalone requester token) are only supported when using Active Directory as an identity provider. They cannot be used with other identity providers since there is no Active Directory to query. Customers wishing to use similar functionality with a different identity provider will need to do API calls to query the identity provider, populate the data into 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 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, and use the metadata field when populating alert and 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. messages.

• In Keyfactor Command version 11.0, the route information for each virtual application (the host name 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)., web site name, use ssl setting, and virtual directory name) was moved from being stored in the database to being stored in local files on the Keyfactor Command server (one appsettings.json file for each virtual application). On upgrade, the information is copied from the database to each local file. However, if you encounter any issues with the upgrade process, you may be required to re-enter this data. Be sure to make note of the values before beginning your upgrade.

  

  Figure 601: Configuration Wizard Route Information for the Keyfactor Portal

• Be aware of the following certificate store changes in Keyfactor Command version 11.0 and later:

  • The following store types have been deprecated and will no longer be shipped with Keyfactor Command:

    All F5 store types, AWS, NetScaler

    These store types will not be created with new databases. Upon upgrading, they will be removed if you do not have any stores or containers defined for the type (per type—i.e. if an AWS store or container is defined and the other types are not, the AWS type will not be removed on upgrade, but the other types will be removed).

  • The built-in functions for IIS and FTP certificate store management in 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. were deprecated in Keyfactor Command version 11.0.

    Customers should migrate all uses of IIS certificate store management to the Keyfactor Universal Orchestrator Keyfactor orchestrators perform a variety of functions, including managing certificate stores and SSH key stores. with the IIS custom extension publicly available at:

    https://github.com/Keyfactor/iis-orchestrator

    For more information, see Installing Custom-Built Extensions.

    For customers who have the FTP certificate store type, when you upgrade Keyfactor Command to version 11 your FTP stores and related data will not be removed on upgrade. In order to manage the FTP certificate store, you will need to use an older version of the Keyfactor Universal Orchestrator that still has the FTP extension.

• Customers using a Keyfactor Command Service (timer service) job status notification customization for sending notifications on completion of an orchestrator job in older implementations of Keyfactor Command need to prepare to migrate to using job completion handlers instead (see Editing Job Completion Handlers) before upgrading to versions 11.0 or later. Keyfactor Command Service job status notification customizations will be removed on upgrade to version 11.0 and later and will no longer be accessible or functional. Keyfactor Command Service job status notification customizations are found in the <unity> section of the CMSTimerService.exe.config configuration file in versions of Keyfactor Command prior to 11.0, which can be found in the following path by default:

  C:\Program Files\Keyfactor\Keyfactor Platform\Service

  A Keyfactor Command Service job status notification customization will look something like this:

  <register type="CSS.CMS.Service.TimerService.Core.ITimerJobListener, CSS.CMS.Service.TimerService.Core"
        mapTo="CSS.CMS.Service.Jobs.Maintenance.Managers.AgentJobCompletionManager, CSS.CMS.Service.Jobs"
        name="AgentJobCompletion">
     <property name="NotificationURL" value="http://example.keyxample.com/AgentNotify/api/Submit" />
  </register>

Release 10.0 or Later

• Keyfactor Command version 10.0 and later by default connects to SQL with an encrypted connection using an SSL TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers. certificate configured on your SQL server. Customers should acquire and install an SSL certificate for the SQL server before upgrading to Keyfactor Command version 10.0 or later. For information about configuring TLS TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers. for SQL server, seeUsing SSL to Connect to SQL Server) and:

  https://docs.microsoft.com/en-us/sql/database-engine/configure-windows/enable-encrypted-connections-to-the-database-engine?view=sql-server-ver15

  If you would prefer not to use an encrypted channel for your connection to SQL, see Configurable SQL Connection Strings.

• All CA Gateways must be upgraded to AnyGateway The Keyfactor AnyGateway is a generic third party CA gateway framework that allows existing CA gateways and custom CA connections to share the same overall product framework. v22.1 to work with Keyfactor Command v10.0 or later.
• Upgrade to SQL Server 2016 CU2 or higher and adjust the database compatibility level if needed. For more information, see System Requirements.
• As of Keyfactor Command version 10.0, Windows Server 2016 is no longer supported. Customers should upgrade to Windows Server 2019 or higher before upgrading to Keyfactor Command version 10.0 or later.

• If you have any saved certificate collections containing any of the following deprecated certificate search fields, these collections will need to be removed or updated to remove use of these fields that are no longer in version 10.0 and later:

  • KeyfactorRequestId
  • RequestResolutionDate
  • CARequestId

  These certificate search fields parsers have been removed to allow for native EJBCA support in Keyfactor Command as of version 10.0.

• If you have the CA Policy module version 7.0 installed on the same server as the Keyfactor Command Management Portal, you’ll need to upgrade the module to version 7.1 or later before running the Keyfactor Command version 10.0 or later upgrade.