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 12.3:

• 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 requires ASP.NET Core version 8.0 (see System Requirements).

• 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 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. 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 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, and use the metadata field when populating alert and 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. 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 638: Configuration Wizard Route Information for the Keyfactor Portal

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

  • 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. have been 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. 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>

• 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 (see Using SSL to Connect to SQL Server). If you would prefer not to use an encrypted channel for your connection to SQL, see Configurable SQL Connection Strings.
• 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. The installer will not check your server version nor prevent installation, but the product will not function properly in some instances. Customers should upgrade to Windows Server 2019 or higher before upgrading to Keyfactor Command version 10.0 or later. If you choose to use Server 2016, any PFXs will need to be configured to use SHA1 and 3DES for encryption for use by Keyfactor Command.

• Before upgrading to a major version, Keyfactor recommends first upgrading to the final incremental version of the previous major version—completing both the software installation and configuration with the configuration wizard—for the optimal upgrade experience. For example, if you are currently on version 9.4 and want to upgrade to version 10.0 or later, you should upgrade first to version 9.10.1 (the final incremental version of 9.x) before upgrading. Contact your Client Success Manager for more information.

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