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

Upgrade AnyCAGateway REST on Windows

Note: An OIDCEventProviders folder exists under the above directory containing a manifest.json file used for Auth0 functionality. Be sure not to disturb or overwrite this directory.

Upgrading to 25.1

Tip:

There are a few new upgrade considerations for Client Certificate Authentication, and OAuth Authentication (Generic or Auth0).

Any Client Certificate Authentication parameters will always be required. OAuth Authentication (Generic or Auth0) configuration requirements depend on the state of the provided database:

If there are existing identity providers in the database, OAuth configuration parameters will not be required.
If there are NO existing identity providers in the database, OAuth configuration parameters will be required in order to add one to the database.
If the provided identity provider’s Auth Scheme matches an existing identity provider’s Auth Scheme in the database, an update will be performed on the values provided for the identity provider in the insdtall script.
If you intend to use Windows Authentication for database connections AND you are using the default app pool user on you IIS site, you will need to create a SQL login for your machine manually (e.g. in domain KEYEXAMPLE, for a machine name SRVR121 the SQL login will need the username KEYEXAMPLE\SRVR121 ).

Important: Review the release notes (Release Notes) thoroughly. There are several major changes for AnyCAGateway REST version 25.1 that will need to be addressed when upgrading, including:

The Keyfactor AnyCA Gateway REST is hosted using IIS by default via the AnyCAGatewayInstall.ps1 script. Set up IIS hosting prior to installing the AnyCA Gateway(See IIS Hosting). To continue to run as Windows Service, use the AnyCAGatewayInstallKestrel.ps1 install script instead.

Certificate profiles can only be used in one template A certificate template defines the policies and rules that a CA uses when a request for a certificate is received. per AnyCAGateway REST 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.. The dropdown in the CA templates tab only displays certificate profiles not already in use.
Important: On upgrade, where a CA was configured with multiple templates with the same certificate profile, the dialog will open but the CA cannot be saved until this is fixed.
Several installation parameters have been and and several have been removed.
On the Add/Edit 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. dialog, for both Gateway Registration Certificate or Client Auth Certificate specified via File Path, the paths provided must be relative paths to the install directory. All CAs from a previous version of the gateway utilizing the file path method will fail to execute operations upon upgrade until the file path is updated to be a relative path of the install directory, so any CA using a File Path will require an edit and re-save upon upgrade.The certificates are required to be inside of the install directory for both Container builds and non-container builds.

To upgrade the AnyCAGateway REST:

Turn off the existing Anygateway by stopping the service in Windows Services and stopping the synchronizations for the CA in Keyfactor Command.
Upgrade to .NET8.0 (see System Requirements).
Set up the IIS site prior to upgrading (See IIS Hosting).
Upgrade the gateway (see Install AnyCAGateway REST on Windows under IIS).

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 (see AnyCAGateway REST Windows Install Parameters for a full list of parameters).

Note: If you’re migrating from client certificate authentication to OAuth authentication, add the OAuth authentication information via the parameters in the install script. The upgrade can be done directly from client certificate authentication to OAuth authentication. OAuth fields are optional, but if one is provided, all are required.
Important:
Important considerations:
- All existing in-database OAuth claims get associated with the FIRST IDP to be added. This includes the Superadmin claim, so it is important that the first IDP you add (through the AnyCAGatewayInstall.ps1 script) is the previously existing IdP. Afterward, other IdP providers can be added. The SuperAdmin claim can also be reassigned to another provider, once the second provided is added.
- Because the config.json file has been removed and those settings now included in the appsettings.json file, existing SuperAdmin and IdP provider fields must be resupplied to the AnyCAGatewayInstall.ps1 script when upgrading from AnyCAGateway REST version 24.2.
- If the upgraded version will use OAuth, the SuperAdmin claim will now be associated with the new OAuth IdP provided on install.
- All existing Client Cert Auth claims are updated to be associated with the Client Cert Auth Provider type.
- The install script will populate the appsettings json file from the existing appsettings.json file (provided it is in the same directory as the install script). Any parameter A parameter or argument is a value that is passed into a function in an application. value that is not specified in the install script will be picked up from the appsettings.json file. The appsettings json file will not be overwritten during install.
On the install server, re-configure the AnyCA Plug-in type for your third-party CA (see Configure the AnyCAPlugin), updating the plug-in version if needed. The artifacts for this will come from the Keyfactor integrations on Keyfactor GitHub site:

https://keyfactor.github.io/integrations-catalog/content/ca-gateway
Start the new AnyCAGateway REST service.
Open the AnyCAGateway REST portal (see Working with the AnyCAGateway REST Portal). Your existing configurations should appear in the portal.
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).
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.
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 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)., revocation, and any automated processes making connections to the gateway are functioning as expected.
If you’ve migrated your gateway from client certificate authentication to OAuth authentication, 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.

Upgrade AnyCAGateway REST in Containers under Kubernetes

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

Stop the synchronizations for the CA in Keyfactor Command.

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
Open the AnyCAGateway REST portal (see Working with the AnyCAGateway REST Portal). Your existing configurations should appear in the portal.
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.

Migrate a AnyCAGateway REST Installation on Windows to Containers under Kubernetes

You may wish to work with a Keyfactor representative on a migration from an installation on Windows to an installation in containers under Kubernetes depending on the complexity of your environment, but if your environment is fairly straight-forward, you should have success without this. The basic process is:

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 (client certificate authentication)?
Stop the synchronizations for the CA in Keyfactor Command.
Install as per Install AnyCAGateway REST in Containers Under Kubernetes referencing your existing database.
Open the AnyCAGateway REST portal (see Working with the AnyCAGateway REST Portal). Your existing configurations should appear in the portal.
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.

Version v25.1

On this page: