Preparing

This section describes the steps that need to be taken before the AnyCAGateway REST installation to install, create, and gather the necessary information and prerequisites to complete the gateway installation and configuration process.

1. Review the System Requirements.

2. Identify your installation method and server.

   Determine where the AnyCAGateway REST will be installed and which systems it must connect to. The gateway can be installed on a Windows server or deployed in containers under Kubernetes. In either case, the gateway must be able to connect to:

   • The SQL Server that hosts the gateway database

   • The Keyfactor Command server that integrates with the third-party 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.

   The gateway may be installed on the same server as SQL Server or Keyfactor Command, or on a separate server, provided network connectivity is available.

   For Windows installations, the AnyCAGateway REST is hosted using IIS by default. Installation as a Windows service using Kestrel is also supported. For more information about available installation options, see Installation Methods.

   Note:  Kestrel remains supported, but future development focuses on IIS. Support for Kestrel may be removed in a future release, so IIS is recommended for new deployments and for long-term planning.

3. For installations on Windows, establish the IIS site.

   For installations on Windows, the AnyCAGateway REST is hosted using IIS by default. You must select an existing IIS site or create a new one to host the gateway and ensure that the site has an appropriate TLS TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers. certificate binding configured for the machine on which you are installing the gateway (see AnyCAGateway REST TLS (SSL) Certificate).

   By default, the AnyCAGateway REST is installed under the Default Web Site. In this case, no new IIS site is required. You only need to ensure that the correct TLS bindings are configured.

   If you choose to use an IIS site other than the Default Web Site, the site must already exist, and the site name must match the value specified by the -SiteName installation parameter A parameter or argument is a value that is passed into a function in an application.. For more information, see IIS Hosting.

   For installations on Windows, the AnyCAGateway REST is hosted using IIS by default. An IIS Site must be created with a TLS certificate binding configured for the machine you are installing on (see AnyCAGateway REST TLS (SSL) Certificate). If you are using the Default Web Site, you just need to ensure the appropriate TLS bindings are configured. If you choose a site other than theDefault Web Site, the name of the site here must correspond to the SiteName install script parameter. See IIS Hosting.

4. Select an authentication mechanism.

   The AnyCAGateway REST supports two authentication methods:

   • Client certificate authentication (mTLS)

     See SuperAdmin Client Authentication Certificate for more information on the client authentication certificate requirements.

   • OAuth token authentication

     The AnyCAGateway REST supports open authorization (OAuth) 2.0 compliant identity providers with a complete implementation of the OpenID Connect (OIDC) protocol. Show OAuth identity provider details.

     OAuth identity providers must meet the following requirements to work with the AnyCAGateway REST:

     • They must be a complete implementation of OpenID Connect. For more information, see:

       https://openid.net/developers/how-connect-works/

     • Users should not be allowed to choose their own usernames and/or email addresses for access to the AnyCAGateway REST.

     • Usernames within the realm must be unique.

     • The identity provider must be configurable using the fields provided in the AnyCAGateway REST (see Table 1279: Identity Provider Parameters).

     • The token endpoint An endpoint is a URL that enables the API to gain access to resources on a server. must support POST Form URL requests, using the following parameters:

       • client_id

       • client_secrets

       • grant_type

     • The identity provider must support front-channel logout.

     To prepare your OAuth Identity provider for use with the AnyCAGateway REST:

     • Create a client in the identity provider for use with the AnyCAGateway REST.
     • Confirm that the client is configured with appropriate redirect URLs, if applicable.
     • Collect the information for the identity provider needed for installation, including (see full list of install parameters Table 1273: AnyCAGateway REST Windows Install Parameters):
       • Client ID
       • Client Secret
       • Discovery URL

   Only one authentication method can be selected during the initial installation. However, you can:

   • Add additional OAuth identity providers later through the AnyCAGateway REST portal or 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..

   • Switch between client certificate and OAuth authentication by rerunning the installation script.

   • Use both authentication types simultaneously by setting up two separate installations on different servers or ports, while sharing the same database.

   As part of your preparation, determine which authentication method you will use for the initial installation.

   Note:  Only OAuth is supported when installing the AnyCAGateway REST in containers under Kubernetes.

5. Determine required accounts.

   Administrative Access

   The AnyCAGateway REST requires a SuperAdmin user to perform initial administrative configuration. The SuperAdmin user is created during installation and provides access to the gateway portal for initial setup tasks, including creating additional users, configuring authentication, and managing gateway settings.

   The username for this account is SuperAdmin and cannot be changed during installation. The authentication method used by the SuperAdmin depends on whether client certificate authentication or OAuth authentication is configured.

   Service Accounts

   The AnyCAGateway REST uses as many as three service accounts, depending on the installation type and database configuration:

   • Installation Service Account

     This account connects to the database during installation. It creates, updates, and populates the database and performs the initial database setup. The user running the create, populate, or update command must have sufficient permissions to perform these actions.

     See the DatabaseManagementUsesSQLAuth and DatabaseManagementAuthCredentials parameters for the AnyCAGatewayInstall.ps1 script in AnyCAGateway REST Windows Install Parameters under IIS and the dbmanagement > serviceUsername, dbmanagement > servicePasswordSecretName, and dbmanagement > servicePasswordSecretKey parameters in the container values file in Values File Settings for Containers Under Kubernetes.

   • SQL Auth Service Account

     The gateway requires ongoing connectivity to the SQL Server, which is provided by a service account. For Windows installations, this can be a Windows domain account or a SQL account if the SQL Server is configured for mixed-mode authentication. The specified account is granted appropriate permissions to the gateway database.

     Note:  For container installations under Kubernetes, only SQL authentication is supported.

     See the UseSQLAuth and SQLAuthCredentials parameters for AnyCAGatewayInstall.ps1, and the connectionStrings > existingSecretName and existingSecretKey parameters in the container values file.

   • Windows Ongoing Service Account

     For installations on Windows, the gateway service runs continuously under a single service account:

     • Installations under IIS: By default, the built-in ApplicationPoolIdentity account is used. You may instead configure a Windows domain account. See the -AppPoolUser parameter for the AnyCAGatewayInstall.ps1 script in AnyCAGateway REST Windows Install Parameters under IIS.

     • Installations under Kestrel: By default, the built-in NT AUTHORITY\Network Service account is used. You may instead configure a Windows domain account. See the -ServiceCredential parameter for the AnyCAGatewayInstallKestrel.ps1 script in AnyCAGateway REST Windows Install Parameters under Kestrel.

   Important:  Keyfactor highly recommends that you use strong passwords for any accounts or certificates related to Keyfactor Command and associated products, especially when these have elevated or administrative access. A strong password has at least 12 characters (more is better) and multiple character classes (lowercase letters, uppercase letters, numeral, and symbols). Ideally, each password would be randomly generated. Avoid password re-use.

6. Prepare required certificates.

   Before installing or configuring the AnyCAGateway REST, identify the certificates required for your deployment and gather them. The certificates you need depend on the authentication method you select and whether the gateway will integrate with third-party certificate authorities.

   Have the required certificate files and identifying information available before starting installation or configuration.

1. Prepare third-party CA access credentials.

   Have the login and access details for each third-party certificate authority that will be configured in the AnyCAGateway REST. This includes any required usernames and passwords, API keys, or client authentication certificates.

   Have the authentication details available, including any required client authentication certificate, its thumbprint, and the local file path or certificate store location. This information is required when configuring the CA connection in the AnyCAGateway REST portal. For more information, see Add or Edit a Certificate Authority.

2. Determine the configuration of one or more third-party CAs.

   The AnyCAGateway REST supports multiple third-party CAs of the same type in one installation of the gateway. Determine the desired logical names and identify one or more accounts to associate it with the third-party CA provider.

   On Windows, you can install multiple AnyCAGateway REST instances on the same server to support different types of third-party certificate authorities. Each gateway instance runs independently and is configured with its own virtual directory, file location, and database. When installing multiple instances, determine your file structure and naming conventions, and specify the -Destination, -VirtualDirectory, -DatabaseName, and -SiteName parameters for each instance.

3. For installations on Windows, acquire the AnyCAGateway REST artifact.

   The artifact will be delivered with two folders—AnyGatewayREST and DatabaseManagementConsole. Note that the file location in which you placed the artifacts will be required during installation.

4. Acquire the Keyfactor gateway integration plugin for your third-party CA.

   The integration will include instructions which you will want to have handy during installation and configuration of the AnyCAGateway REST. Gateway integrations for common third-party CAs are publicly available in the Keyfactor GitHub:

   https://keyfactor.github.io/integrations-catalog/content/ca-gateway