Preparing

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

Tip:  Please start with Upgrading if you are upgrading an existing installation.
  1. Review the system requirements. See System Requirements.
  2. Identify your installation method and server. The AnyCAGateway REST can be installed either on Windows or in containers under Kubernetes. In either case, it needs to connect to both the SQL server which will host the database and the Keyfactor Command server, which will integrate with the CAClosed 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., including on any of those servers themselves. When installing on Windows, by default the gateway installs under Kestrel. You may take steps following installation to switch the gateway to run under IIS (see IIS Hosting).

  3. Select an authentication mechanism. The AnyCAGateway REST supports both client certificate authentication and OAuth token authentication. Only one authentication method/provider is allowed for the initial installation. It is possible to add additional OAuth Identity Providers through the APIClosed 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. after installation. You can also switch between client certificate and OAuth authentication once one type is installed by rerunning the installation script. It is also possible to use both authentication types on the same database by implementing two installations using the same database on different servers or ports. In this preparation step, determine your initial (primary) authentication method.

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

  4. Determine the service accounts. The AnyCAGateway REST uses as many as three service accounts:

    • An account is used to connect to the database during installation. This account will create/update/populate the database and do the initial DB setup. The user running the create, populate, or update command must have sufficient permissions to create, populate or update databases as appropriate to the command being run. See the DatabaseManagementUsesSQLAuth and DatabaseManagementAuthCredentials parameters for the AnyCAGatewayInstall.ps1 install script in AnyCAGateway REST Windows Install Parameters and the dbmanagement > serviceUsername, dbmanagement > servicePasswordSecretName, and dbmanagement > servicePasswordSecretKey parameters in the container values file in Values File Settings for Containers Under Kubernetes.

    • The gateway needs ongoing connectivity to the SQL server. This is accomplished using a service account. For installations on Windows, the account specified can either be a Windows domain account or a SQL account (assuming the SQL server is configured to support mixed mode). If a Windows domain account is used, the same Windows domain account may also be used to run the gateway service. The account specified will be granted appropriate permissions to the gateway database. See the UseSQLAuth and SQLAuthCredentials parameters for the AnyCAGatewayInstall.ps1 install script in AnyCAGateway REST Windows Install Parameters. For installations in containers under Kubernetes, only SQL authentication is supported. See the connectionStrings > existingSecretName and existingSecretName > existingSecretKey parameters in the container values file in Values File Settings for Containers Under Kubernetes.

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

    • For installations on Windows, the gateway service runs as one service account on an ongoing basis. By default, this is the built-in NT AUTHORITY\Network Service account, but you may choose to run the gateway service as a Windows domain account. See the -ServiceCredential parameterClosed A parameter or argument is a value that is passed into a function in an application. for the AnyCAGatewayInstall.ps1 install script in AnyCAGateway REST Windows Install Parameters.

    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.

  5. Prepare the following certificates. You will need some or all—depending on the authentication mechanism you selected—of the following certificates installed on the installation server, or your local server, as indicated below. Have their information handy:

    Installations on Windows

    Download the Public Issuing CA certificate from your third-party CA website and install it on the AnyCA Gateway server. This is required on the Gateway Registration tab during configuration for both client certificate authentication and OAuth token authentication. See The Gateway Registration Tab. Either the file path, or the certificate store name, certificate store location and certificate thumbprint will be needed.

    Installations in Containers under Kubernetes

    The CA root and issuing certificates for all CAs in the environment that will have any relationship with the AnyCA Gateway need to be gathered and added to the root trust store on your Kubernetes server/cluster. Certificates in this category includes:

    Many publicly-rooted certificates will already be trusted, so if your TLS certificates have been issued by external vendors (e.g. DigiCert, Entrust), chain certificates for these may not be needed.

    These all need to be copied into the root trust store on your Kubernetes server before the root trust configmap is created. Methods for doing this vary depending on the Linux implementation. Beware of ending up with Windows line endings in the trusted root store, as this can create root trust issues inside the container.

    Tip:   DigiCert certificates are available for download:

    Entrust certificates are also available for download:

    https://www.entrust.com/resources/certificate-solutions/tools/root-certificate-downloads

    GoDaddy has four available Certificate Authorities:

    The AnyCAGateway REST requires TLS to connect to the server to secure the web portal connection.

    Installations on Windows

    Have handy the password and the file path of the location for the TLS (SSL) certificate issued in the FQDN of the installation server’s name for both client certificate authentication and OAuth token authentication. The certificate needs SANs of both the FQDN and the server name, for instance SQL241.keyexample.com and SQL241 for the server. Both the private and public keyClosed In asymmetric cryptography, public keys are used together in a key pair with a private key. The private key is retained by the key's creator while the public key is widely distributed to any user or target needing to interact with the holder of the private key. need to be available for the certificate. It could be the same certificate Keyfactor Command uses for TLS (SSLClosed TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers.), but it does not need to be. This is provided with the -ServerCertificatePath parameter during installation (see -Server Certificate Path.

    Installations in Containers under Kubernetes

    Acquire the TLS certificate using the Fully Qualified Domain Name (FQDN) of the server or alias used for the Kubernetes cluster where your AnyCAGateway REST implementation will be installed. This is the name that you will use to access AnyCAGateway REST via a browser for management purposes. You will need both the certificate and its private keyClosed Private keys are used in cryptography (symmetric and asymmetric) to encrypt or sign content. In asymmetric cryptography, they are used together in a key pair with a public key. The private or secret key is retained by the key's creator, making it highly secure.. For information on preparing the certificate for use, see Install AnyCAGateway REST in Containers Under Kubernetes.

    If you plan to use client certificate authentication, have a certificate identified, or request a new one from either a third-party or internal CA (optionally via Keyfactor Command) to use for the initial trusted client certificate to access the AnyCAGateway REST portal. This should be a certificate from a templateClosed A certificate template defines the policies and rules that a CA uses when a request for a certificate is received. that has at minimum an application policy of Client Authentication. You will need to have handy the thumbprint or serial number for the certificate. This is required for the -SuperAdminValue parameter during installation if client certificate authentication is used. The SuperAdmin is used to create users who will have SuperAdmin access to the AnyCA Gateway operations and configuration. See -Super Admin Value.

    Tip:  The AnyCAGateway REST checks the client authentication certificate's revocation status during install. To turn that setting off, set the CheckClientCertCRL appsetting.json setting to False prior to installation. The appsettings.json file will be in the file path AnyGatewayREST\net8.0 within the file location in which you placed the artifacts. For example:
    C:\MyFiles\AnyGatewayRESTInstall\AnyGatewayREST\net8.0\Configuration\appsetting.json

    For more information, see Appsettings.json File.

    Note:  The client authentication certificate does not need to be saved locally on the install server. It can be used from outside the installation server to access the AnyCAGateway REST portal. If using Chrome, it will need to be installed into the personal store or browsers wherever the portal will be accessed from. The certificate needs to have been generated prior to installation, so the thumbprint or serial number is available.

    If you plan to use client certificate authentication and to use the AnyCAGateway REST with Keyfactor Command, you will needs a client authentication certificate to allow Keyfactor Command to authentication to the gateway. You may use the SuperAdmin certificate for this, but you may prefer to acquire a dedicated certificate for this purpose. Have a certificate identified, or request a new one from either a third-party or internal CA (optionally via Keyfactor Command) to use for the Keyfactor Command connect client certificate. This should be a certificate from a template that has at minimum an application policy of Client Authentication. You will need to have handy the thumbprint or serial number for the certificate in order to create a claim for it in the AnyCAGateway REST portal. See Claims.

    Note:  The client authentication certificate needs to be available in PKCS#12Closed A PFX file (personal information exchange format), also known as a PKCS#12 archive, is a single, password-protected certificate archive that contains both the public and matching private key and, optionally, the certificate chain. It is a common format for Windows servers. format in order to upload it into Keyfactor Command.
    Tip:  Using a dedicated user certificate is preferable to using the superadmin certificate, as Keyfactor Command only needs user access to the AnyCAGateway REST.

    If you plan to use client certificate authentication, you will need the local file path for the Root CA certificate that issued the SuperAdmin client authentication certificate (and any other desired user authentication certificates). This is required for the -AuthCA File Path parameter during installation. This will be used to validate the Superadmin certificate and any other user certificates when you log into the gateway from your browser if client certificate authentication is used.

  6. Have login and all access details for all third-party CA accounts you will be configuring in the AnyCAGateway REST, including any username/password and/or API key(s) as required by your CA. Have handy the authentication details for the third-party CA including any required client authentication certificate, its thumbprint and the local file path or certificate store location. This information is required for the CA connection configuration when adding the CA to the AnyCA Gateway portal. See Add or Edit a Certificate Authority.

  7. Determine the configuration of the third-party CA(s) you want to deploy with AnyCAGateway REST.

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

  9. Acquire the Keyfactor gateway integration 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