Install the CA Connector Client on Linux

To begin the CA ConnectorClosed The Keyfactor CA Connector is installed in the customer environment to provide a connection between a CA and Keyfactor Command when a direct connection is not possible. It is supported on both Windows and Linux and has versions for Microsoft (Windows only) or EJBCA CAs. Client 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 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. Connector Client, 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 syntax shown in Table 1034: CA Connector Client Linux Install Parameters to begin the installation.

    Table 1034: CA Connector Client Linux Install Parameters

    Parameter Required? Description
    --audience Maybe

    This parameter specifies the audience that should be included in token requests to the identity provider.

    The OAuth mechanism in use in your Keyfactor Command environment may or may not require this.
    --auth-url Yes

    This is the token URL to the service providing OAuth authentication.

    For a managed instance of Keyfactor Command, this value should have been provided to you by your Keyfactor representative.
    --ca-config-cache-expiration No

    This parameter specifies the number of minutes that the CA configuration will be cached before being cleared.

    If this parameter is not specified, the default value of 10 minutes will be used.
    --client-id Yes

    This is a string issued by the authentication provider that identifies the application authenticating.

    For a managed instance of Keyfactor Command, this value should have been provided to you by your Keyfactor representative.
    --client-secret Yes*

    This is the secret shared between the Keyfactor CA Connector implementation and the authentication provider. See also --secret-file-path and --secret-std-in. Use one of --client-secret,--secret-file-path, or --secret-std-in. Keyfactor recommends using either --secret-file-path or --secret-std-in for greater security, since these avoid providing the client secret at the command line (--secret-file-path), storing it in command history (--secret-file-path), and potentially exposing it in process listings.

    For a managed instance of Keyfactor Command, this value should have been provided to you by your Keyfactor representative.

    One of --client-secret, --secret-file-path, or --secret-std-in parameter is required.
    --destination No

    This parameter specifies a location in which to install the CA Connector Client that is other than the default. The default installation location is:

    /opt/keyfactor/ca-connector

    This parameter cannot be used in conjunction with the in-place parameter.
    --force, -f No

    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.
    --in-place No

    This parameter is used to indicate that the installation should occur in the directory where the installation 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.
    --name No

    Specifying this parameter allows you to override the name the CA Connector Client will use when registered as a CA connector in Keyfactor Command. The name it uses must match the name used when creating a CA connector record in Keyfactor Command (see Preparing).

    By default, the CA Connector Client uses the value of the machine hostname without the domain.
    --no-validate No

    Specifying this parameter allows you to skip the test the CA Connector Client makes to confirm connectivity to Keyfactor Command and the presence in Keyfactor Command of a CA connector record matching the name of the CA Connector Client being installed (see Preparing).

    If you do not specify this option and the test is done, the installation will terminate if connectivity to Keyfactor Command cannot be confirmed. The connectivity test may also fails if a connection cannot be made to the OAuth provider to retrieve a token. Either of these may fail if an SSL connection cannot be established due to, for example, a missing root trust (see Configure a Certificate Root Trust for the Keyfactor CA Connector). If connectivity to Keyfactor Command succeeds but no CA connector record matching the name of the CA Connector Client being installed is found, a warning will be shown but the installation will continue.
    --scope Maybe

    This parameter specifies the scopes that should be included in token requests to the identity provider. If multiple scopes are desired, they should be separated by spaces.

    For a managed instance of Keyfactor Command, this value should have been provided to you by your Keyfactor representative.

    The OAuth mechanism in use in your Keyfactor Command environment may or may not require this.
    --secret-file-path Yes*

    A path to a text file containing the secret shared between the Keyfactor CA Connector implementation and the authentication provider. See also --client-secret and --secret-std-in. Use one of --client-secret,--secret-file-path, or --secret-std-in. Keyfactor recommends using either --secret-file-path or --secret-std-in for greater security, since these avoid providing the client secret at the command line (--secret-file-path), storing it in command history (--secret-file-path), and potentially exposing it in process listings.

    For a managed instance of Keyfactor Command, this value should have been provided to you by your Keyfactor representative.

    One of --client-secret, --secret-file-path, or --secret-std-in parameter is required.

    Note:  To use this parameter:
    1. Create a file that contains just the client secret. For example:
      vi /opt/kyf-connect/my_secret_file
    2. When using the secret file path parameter, reference the file. For example:
      --secret-file-path /opt/kyf-connect/my_secret_file
    3. Delete the client secret file after the install is complete. For example:
      rm /opt/kyf-connect/my_secret_file
    --secret-std-in Yes*

    Accept the secret shared between the Keyfactor CA Connector implementation and the authentication provider from standard in. See also --client-secret and --secret-file-path. Use one of --client-secret,--secret-file-path, or --secret-std-in. Keyfactor recommends using either --secret-file-path or --secret-std-in for greater security, since avoid providing the client secret at the command line (--secret-file-path), storing it in command history (--secret-file-path), and potentially exposing it in process listings.

    For a managed instance of Keyfactor Command, this value should have been provided to you by your Keyfactor representative.

    One of --client-secret, --secret-file-path, or --secret-std-in parameter is required.

    Note:  To use this parameter:
    echo "MySuperSecretPassword" | sudo ./install.sh --secret-std-in [other parameters here]
    --service-suffix No

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

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

    This is the local Linux service account that the service will run as (see CA Connector Client 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-caconnector will be used.
    --url Yes

    This is the URL to the CA connector application on the Keyfactor Command server. SSL is required to connect to the Keyfactor Command server. For example:

    https://kyf101.keyfactorpki.com/KeyfactorCAConnectors
    --what-if No 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.
    --verbose, -v No Specifying this parameter causes verbose messages to be output during installation.
    Tip:  While not required for operation, WebSockets may be used as the transport protocol between the CA Connector Client and the CA Connector 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. on the Keyfactor Command server (for Keyfactor Command installations on Windows under IIS). To leverage WebSockets, this feature must be installed in IIS on the Keyfactor Command server. This can be done via Server Manager under Add Roles > Web Server (IIS) > Web Server > Application Development > WebSocket Protocol. If the WebSockets feature is not enabled, HTTP LongPolling will be used as the transport protocol from the CA Connector Client. If desired, the CA Connector Client can be configured to force the transport protocol to WebSockets or LongPolling. For more information, see Appsettings.json File.

    The output from the command should look similar to the following, given the example commands shown. In this example, a CA connector record for the CA Connector Client was created in Keyfactor Command before running the installation (see Preparing) and so when the connection to Keyfactor Command was tested, no warning was generated.

    vi my_secret_file

    sudo ./install.sh --url https://kyf101.keyfactorpki.com/KeyfactorCAConnectors --scope api://a12b345c-1234-8qqe-7521-1d91e647f7bg/.default --auth-url https://keyexample.us.auth0.com/oauth/token --client-id 1a234567-8b90-123c-d456-7e89f0123ghi --name appsrvr162.keyexample.com --secret-file-path /opt/kyf-connect/my_secret_file --force
CA connector installation directory does not exist and will be created.
Testing connection to server...
Connection to CA Connector API validated successfully.
Creating user keyfactor-caconnector
Creating install directory...
Creating CA connector log location...
Installing Keyfactor CA Connector...
Saving app settings
Saving secret app settings
Setting file permissions
Creating service unit file (systemd or systemctl required)...
Created symlink /etc/systemd/system/multi-user.target.wants/keyfactor-ca-connector-default.service → /etc/systemd/system/keyfactor-ca-connector-default.service.
Starting CA Connector service...
  4. Review the output from the installation to confirm that no errors have occurred.

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

The CA Connector Client service, by default named keyfactor-ca-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 CA Connector Client is complete, you need to use the Keyfactor Command Management Portal to complete the configurations and add CAs (see Initial Configuration).