Upgrade the AnyCAGateway REST to a New Version

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

The AnyCAGateway REST uses either the AnyCAGatewayInstall.ps1 or AnyCAGatewayInstallKestrel.ps1 PowerShell script, which take several command line parameters. This can be installed on any server. It does not need to be the existing Anygateway server.

Upgrade Considerations

Review the following changes and requirements before upgrading:

Hosting Changes (Windows)

• IIS is now the default hosting model when using the AnyCAGatewayInstall.ps1 script.
• Kestrel remains supported but is no longer the focus of development and may be removed in a future release.
• To continue using Kestrel, use the AnyCAGatewayInstallKestrel.ps1 script.

Certificate Profile Usage

• A certificate profile can only be used with one template A certificate template defines the policies and rules that a CA uses when a request for a certificate is received. per gateway 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..

• For existing configurations with multiple templates mapped to the same certificate profile:

  • CA changes cannot be saved until this is corrected.

  • 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). continues to function, but a warning is logged and the first template is used.

File Path Requirements

• Certificate file paths must be relative to the install directory.

• Existing configurations using absolute paths (versions prior to 25.1) must be updated and re-saved after upgrade.

• Certificates must reside within the install directory (applies to both Windows and container deployments).

Authentication and Identity Providers

• If client certificate authentication is used, entry of client certificate authentication parameters is required.

• To migrate from client certificate authentication to OAuth, provide the OAuth parameters to the install script.

  • Direct migration is supported.

  • OAuth parameters are optional. However, if any are provided, all required parameters must be specified.

• If OAuth authentication is used, entry of OAuth parameters depends on the existing configuration:

  • Required if no identity providers exist

  • Optional if providers already exist

• If an OAuth authentication scheme provided via parameter A parameter or argument is a value that is passed into a function in an application. matches an existing identity provider, that provider is updated.

• On upgrading from versions prior to 24.3:

  • Existing OAuth claims (including the SuperAdmin claim) are initially associated with the first identity provider added via the install script.
  • Ensure that the first identity provider added matches the previous configuration.

  • Claims can be reassigned after additional identity providers are added.

Configuration Changes

• When upgrading:

  • Existing configuration values can be retrieved from an appsettings.json seed file in the install directory.
  • Any values not supplied via an appsettings.json seed file must be provided via the install script.
  • The appsettings.json seed file is not overwritten.

• As of version 24.3:

  • The config.json file has been removed.

  • Settings are now stored in the appsettings.json file.

Installation Script Changes

• Parameters may be added, removed, or modified between releases.

• Always review the install script documentation before upgrading.

IIS and Database Access

• When using Windows Authentication with the default IIS application pool identity, ensure that a SQL login exists for the application pool identity (for example, KEYEXAMPLE\SERVER$) and that it has the required database permissions.

Auth0 Configuration

• Do not modify or overwrite the following directory:

  ...\Extensions\OIDCEventProviders

• This directory contains required Auth0 configuration (manifest.json).

Upgrade Existing IIS Installs

To upgrade an instance of AnyCAGateway REST running under IIS:

1. Back up any customization, included installing installed extensions and NLog configuration.
2. Back up the AnyCAGateway REST SQL database.
3. Stop the synchronizations for the CA in Keyfactor Command.
4. Upgrade the .NET version if required (see System Requirements).

5. Install the new version of the gateway using the -Force option to overwrite the existing installation (see Install AnyCAGateway REST on Windows under IIS).

   • Use the same database name.

   • If the -Destination option was used previously, specify the same location.

6. Verify installed extensions and update as needed (see Configure AnyCAGateway REST Plugins).
7. Restart the AnyCAGateway REST web site.

Upgrade Kestrel Installs to IIS

To upgrade the AnyCAGateway REST and migrate from Kestrel to IIS:

1. Turn off the existing Anygateway:

   • Stop the service in Windows Services.

   • Stop the synchronizations for the CA in Keyfactor Command.

2. Upgrade the .NET version if required (see System Requirements).
3. Set up the IIS site before upgrading (see IIS Hosting).
4. Install the new version of the gateway (see Install AnyCAGateway REST on Windows under IIS).
5. Re-configure the CA plugin type for your third-party CA (see Configure AnyCAGateway REST Plugins), updating the plugin version if needed.
6. Start the new AnyCAGateway REST service.

Upgrade AnyCAGateway REST in Containers under Kubernetes

Once you’ve confirmed that preparation is complete, you may move forward with the upgrade:

1. Stop the synchronizations for the CA in Keyfactor Command.

2. Upgrading AnyCAGateway REST in containers under Kubernetes is as simple as uninstalling and reinstalling using the Helm chart with your custom values file (see Install AnyCAGateway REST in Containers Under Kubernetes). For example:

   sudo helm uninstall Helm_Deployment_Name --namespace keyfactor-gateway
   sudo helm install Helm_Deployment_Name --namespace keyfactor-gateway --values values-local.yaml oci://repo.keyfactor.com/charts/command/anygateway-rest --version 1.0.1

Migrate a AnyCAGateway REST Installation on Windows to Containers under Kubernetes

Depending on the complexity of your environment, you may choose to work with a Keyfactor representative when migrating from a Windows-based installation to a containerized deployment on Kubernetes. In simpler environments, this assistance may not be necessary. The basic process is:

1. Prepare as for an upgrade (see Preparing), being sure to review all the components of your Windows installation and determine the correct equivalent configuration under Kubernetes. For example:

   • Which CA plugin are you using?

   • Are you using features that aren’t supported under Kubernetes (for example, client certificate authentication)?

2. Stop the synchronizations for the CA in Keyfactor Command.
3. Install per Install AnyCAGateway REST in Containers Under Kubernetes referencing your existing database.

Post-Upgrade Checks and Configuration

After the upgrade is complete, check the following:

• Open the AnyCAGateway REST portal (see Working with the AnyCAGateway REST Portal) and confirm that your existing configurations appear.
• In Keyfactor Command, review CA and template settings to confirm no further changes are needed (see Import Templates).
• In Keyfactor Command, observe that synchronization is completing successfully.
• Confirm that enrollment, revocation, and any automated processes making connections to the gateway are functioning as expected.
• If desired, 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.
• For Windows installations, if you’ve migrated your gateway from client certificate authentication to OAuth authentication:
  • In the Keyfactor Command Management Portal, update the CA record for the gateway from client certificate authentication to OAuth authentication (see Certificate Authority Authentication Methods Tab).
  • Once you have confirmed that everything is operating successfully with OAuth authentication, you may optionally delete the claims of type client certificate authentication from the AnyCAGateway REST portal.