Upgrading the AnyCAGateway DCOM to AnyCAGateway REST

If you’re upgrading from an existing version of the AnyCAGateway DCOM, see the below upgrade instructions. If you’re upgrading an existing version of the AnyCAGateway REST, please see Upgrade the AnyCAGateway REST to a New Version.

Upgrade Overview

To upgrade the AnyCAGateway DCOM to AnyCAGateway REST:

1. Review the AnyCA Gateway Upgrade Compatibility Matrix to see if you need to upgrade to a previous version of AnyCAGateway REST prior to upgrading to this version.

   Tip:  An AnyCAGateway DCOM installation can only upgrade directly to an AnyCAGateway REST installation of the same version. For example, the AnyCAGateway DCOM version 24.2 can be upgraded to the AnyCAGateway REST version 24.2, but not to the AnyCAGateway REST version 24.1 or 24.4.

2. Resolve any pending requests for the existing Anygateway in Keyfactor Command. Any External Validation requests in Keyfactor Command will not resolve once the upgrade has completed and must be resubmitted. They will be removed if you choose to delete the existing Anygateway.

   Note:  The AnyCAGateway REST does not support the Pending status. Additionally, certificates with an Unknown status are not synchronized to Keyfactor Command from the AnyCAGateway REST. As a result, during upgrade of an existing Anygateway to the new AnyCAGateway REST, these records will be DELETED from the database. A warning will be logged during upgrade.
3. Turn off the existing Anygateway by stopping the service in Windows Services and stopping the DCOM synchronizations in Keyfactor Command.
4. Upgrade to .NET8.0 (see System Requirements).

5. Install the Gateway and upgrade the database (see Install AnyCAGateway REST on Windows under IIS). The AnyCAGateway REST uses the AnyCAGatewayInstall.ps1 PowerShell script, which takes several command line parameters. This can be installed on any server. It does not need to be the existing Anygateway server.

   Tip:  With each release version of AnyCAGateway REST new parameters may be required or available and existing parameters may be removed or changed, so review the AnyCAGatewayInstall.ps1 PowerShell script instructions carefully.
   Important:  The database upgrade is included in AnyCAGatewayInstall.ps1 script, eliminating the need for you to populate the dbconfig and run the DatabaseManagementConsole.exe. Both of these tasks are done by the install script and run in the background and then removed, as a result you will no longer see a dbconfig as part of the AnyCAGateway REST installation.

6. On the install server, configure the AnyCA Plug-in type for your third-party 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. (see Configure the AnyCAPlugin). The artifacts for this will come from the Keyfactor integrations on Keyfactor GitHub site:

   https://keyfactor.github.io/integrations-catalog/content/ca-gateway
7. Start the new AnyCAGateway REST service.

8. Open the AnyCAGateway REST portal (see Working with the AnyCAGateway REST Portal).

   1. The CA will appear on the certificate authorities page.

      • The AD templates from the existing Anygateway will be mapped to your third-party CA’s product IDs with all the key and parameter A parameter or argument is a value that is passed into a function in an application. settings from the existing Anygateway configuration. View this on the Template tab of the Edit CA details dialog.

      • The Gateway Registration tab and the CA Connection tab are populated from the existing Anygateway configuration.

   2. The certificate profile page will be populated with the existing Anygateway Active Directory template A certificate template defines the policies and rules that a CA uses when a request for a certificate is received. mappings with their key algorithms.

9. In the Keyfactor Command Management Portal, add the gateway as a CA. See Add the AnyCAGateway REST as a CA in Keyfactor Command.

   Note:  This step is necessary because the AnyCAGateway DCOM CA record in Keyfactor Command, if any, is of type DCOM and the AnyCAGateway REST CA record needs to be of type HTTPS. This setting cannot be changed on a CA record.

10. Restart the Keyfactor Command service to start a synchronization, which will automatically update the existing synchronized certificates and will start synchronizing any new certificates that have synchronized to the gateway from the third-party CA.
11. In Keyfactor Command, import templates from the configuration tenant A grouping of CAs. The Microsoft concept of forests is not used in EJBCA so to accommodate the new EJBCA functionality, and to avoid confusion, the term forest needed to be renamed. The new name is configuration tenant. For EJBCA, there would be one configuration tenant per EJBCA server install. For Microsoft, there would be one per forest. Note that configuration tenants cannot be mixed, so Microsoft and EJBCA cannot exist on the same configuration tenant. defined when you added the new AnyCAGateway REST CA to Keyfactor Command. Since the AnyCAGateway REST is added into Keyfactor Command as an HTTPS CA, the templates will import with an end-entity prefix (AnyCA_) and the certificate profile name, such as AnyCA_WebServer.
12. In Keyfactor Command, configure templates for 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). and add allowed requesters (see Import Templates).
13. In Keyfactor Command, observe that after the initial synchronization, the certificates for this CA have been updated to the new CA and template.
14. Optionally, remove the existing Anygateway CA from Keyfactor Command. Since the existing Anygateway would have had synchronizations run in Keyfactor Command, you will not be able to delete it from the Keyfactor Command Certificates Authorities page. If you would like to do this, see Keyfactor support for assistance.

Template Mapping on an Upgrade

The existing Anygateway will have templates configured similar to the example below, where the Active Directory template name is mapped to the third-party CA product ID. This can be seen in a config.json file generated using the Get-KeyfactorGatewayConfig cmdlet (see Get-KeyfactorGatewayConfig). The AnyCAGateway REST is Active Directory independent, so the template names will not have any meaning to the AnyCAGateway REST. To minimize the amount of reconfiguration required on an upgrade, template mapping will be handled by the upgrade as follows:

• The upgrade will pull the names and the configured Active Directory templates and their supported key-types and algorithms from Active Directory.

• A certificate profile will be created in the AnyCAGateway REST portal for each of the existing Active Directory template mappings.

• The CA in the AnyCAGateway REST portal will be populated with the mappings of the newly created certificate profiles and the third-party product IDs.