Install the Keyfactor Remote CA Gateway Connector on Linux

To begin the Keyfactor Remote 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. Gateway ConnectorClosed The Keyfactor Gateway Connector is installed in the customer forest to provide a connection between the on-premise CA and the Azure-hosted, Keyfactor managed Hosted Configuration Portal to provide support for synchronization, enrollment and management of certificates through the Azure-hosted instance of Keyfactor Command for the on-premise CA. It is supported on both Windows and Linux. installation on Linux, place the installation files in a temporary working directory on the Linux server and:

  1. On the Linux machine on which you wish to install the gateway connector, in a command shell change to the temporary directory where you placed the installation files.

  2. Use the chmod command to make the install.sh script file executable. The file ships in a non-executable state to avoid accidental execution. For example:

    sudo chmod +x install.sh

  3. In the command shell, run the install.sh script as root using the following syntax to begin the installation:

    This is the URL to the Keyfactor Remote CA Service server. SSLClosed TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers. is required to connect to the Keyfactor Remote CA Service server. This URL should be provided to you by your Keyfactor representative.

    This parameterClosed A parameter or argument is a value that is passed into a function in an application. is required.

    This is the mechanism by which the gateway connector makes a request for the specific access that it needs. This value should have been provided to you by your Keyfactor representative.

    This parameter is required.

    This is the URL to the service providing OAuth2 authentication. This value should have been provided to you by your Keyfactor representative.

    This parameter is required.

    This is a string issued by the authentication provider that identifies the application authenticating. This value should have been provided to you by your Keyfactor representative.

    This parameter is required.

    This is the secret shared between the components of the Keyfactor Remote CA Gateway implementation and the authentication provider. This value should have been provided to you by your Keyfactor representative.

    This parameter is required.

    Note:  If you prefer to avoid providing the client secret at the command line (and storing it in command history), use an input file instead as follows:
    1. Create a file that contains just the client secret. For example:
      vi my_secret_file
    2. When using the client secret parameter, reference the file. For example:
      --client-secret $(cat my_secret_file)
    3. Delete the client secret file after the install is complete. For example:
      rm my_secret_file

    Specifying this parameter allows you to override the name the gateway connector would by default use to register itself in the Keyfactor Remote CA Configuration Portal.

    By default, the gateway connector uses the results from a hostnameClosed The unique identifier that serves as name of a computer. It is sometimes presented as a fully qualified domain name (e.g. servername.keyexample.com) and sometimes just as a short name (e.g. servername). lookup for the server's name.

    This parameter specifies a location in which to install the gateway connector that is other than the default. The default installation location is:

    /opt/keyfactor-gateway-connector

    This parameter cannot be used in conjunction with the in-place parameter.

    This parameter specifies a path for the output log directory. The default location is the logs directory under the installed directory, which by default is:

    /opt/keyfactor-gateway-connector/logs

    This is the local Linux service account that the service will run as (see Keyfactor Remote CA Gateway Connector Service). It should be entered as just the user name. Entry of a password for this service account is not required. You may either create this account prior to running the installation script (or use an existing account) or use the force parameter to generate the account automatically during the installation process.

    If this parameter is not specified, the default service account name of keyfactor-gatewayconnector will be used.

    This parameter is used to add a suffix to the root service name of keyfactor-gateway-connector (e.g. instance1 for a resulting service name of keyfactor-gateway-connector-instance1). This is used primarily for implementations where the gateway connector will be installed multiple times on the same server.

    If this parameter is not specified, the default service name of keyfactor-gateway-connector-default will be used.

    Specifying this parameter causes verbose messages to be output during installation.

    Specifying this parameter causes the installation to warn and continue on certain potential problems, including:

    • The local service account does not exist. The default user will be created if force is specified.
    • The appsettings.json file does not exist or is invalid. A new one will be created if force is specified.
    • The secretAppsettings.json file does not exist or is invalid. A new one will be created if force is specified.
    • A service with either the default service name or the service name specified with the service-suffix parameter already exists. The service will be overwritten if force is specified.
    • Either the default installation location or the location specified with the destination parameter is not empty. The install will occur to the specified or default location anyway and files may be overwritten if force is specified.

    If this parameter is not specified and any of these problems are encountered, the installation will terminate prematurely. See also the what-if parameter.

    This parameter is used to indicate that the installation should occur in the current directory where the install files are located and no files should be copied to another location on the machine.

    This parameter cannot be used in conjunction with the destination parameter.

    This parameter is used to test the installation command without actually installing in order to see any errors that might arise and correct them before installing.

    The output from the command should look similar to the following, given the example commands shown.

    vi my_secret_file

    sudo ./install.sh --url https://kyf101.keyfactorpki.com/RemoteCAManagement --scope api://a12b345c-1234-8qqe-7521-1d91e647f7bg/.default --auth-url https://login.microsoftonline.com/mycred.onmicrosoft.com/oauth2/v2.0/token --client-id 1a234567-8b90-123c-d456-7e89f0123ghi --name appsrvr162.keyexample.com --client-secret $(cat my_secret_file) --force
Gateway connector installation directory does not exist and will be created.
Gateway connector log directory does not exist and will be created.
Creating user keyfactor-gatewayconnector
Creating install directory...
Creating gateway connector log location...
Installing Keyfactor Gateway Connector...
Saving app settings
Saving secret app settings
Setting file permissions
Creating service unit file...
Created symlink /etc/systemd/system/multi-user.target.wants/keyfactor-gateway-connector-default.service → /etc/systemd/system/keyfactor-gateway-connector-default.service.
Starting Gateway Connector...
  4. Review the output from the installation to confirm that no errors have occurred.

The script creates a directory, /opt/keyfactor-gateway-connector by default, and places the gateway connector files in this directory. Log files are found in /opt/keyfactor-gateway-connector/logs by default, though this is configurable (see Configure Logging).

The gateway connector service, by default named keyfactor-gateway-connector-default.service, should be automatically started at the conclusion of the install and configured to restart on reboot.

Note:  Once the installation of the gateway connector is complete, you need to use the Keyfactor Remote CA Configuration Portal to approve the gateway connector (see Gateway Connectors) and configure CAs (see Certificate Authorities). You can then add these CAs in Keyfactor Command as per the the Keyfactor Command Reference Guide instructions.