Install the CA Connector Client on Windows

To begin the CA Connector 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 Windows, place the installation files in a temporary working directory on the Windows server and:

1. On the Windows machine on which you wish to install the 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. Connector Client, open a PowerShell window using the “Run as Administrator" option and change to the temporary directory where you placed the installation files.

2. In the PowerShell window, run the following commands to populate a variable with the credentials for the service account, if you plan to run the CA Connector Client as a custom service account rather than the default of Network Service (see CA Connector Client Service), and populate a variable with the client secret for the access token (see Identify the CA Connector Client Access Token):

   $credService = Get-Credential
   $clientSecret = ConvertTo-SecureString -Force -AsPlainText 'MyTokenSecret'

   Enter the appropriate username and password when prompted and enter the appropriate client secret in place of MySecret. Usernames should be given in DOMAIN\username format.

   Or, to avoid being prompted for credentials:

   $serviceUser = "DOMAIN\myserviceusername"
   $servicePassword = "MySecurePassword"
   $secServicePassword = ConvertTo-SecureString $servicePassword -AsPlainText -Force
   $credService = New-Object System.Management.Automation.PSCredential ($serviceUser, $secServicePassword)
   $clientSecret = ConvertTo-SecureString -Force -AsPlainText 'MyTokenSecret'

3. In the PowerShell window, run the Install-CAConnector.ps1 script using the syntax shown in Table 1035: CA Connector Client Windows Install Parameters to begin the installation.

   Table 1035: CA Connector Client Windows 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.
   -AuthURL	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.
   -CAConfig Cache Expiration Minutes	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.
   -ClientId	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.
   -ClientSecret	Yes	This is the secret shared between the Keyfactor CA Connector implementation and the authentication provider. It is provided as a SecureString. For a managed instance of Keyfactor Command, this value should have been provided to you by your Keyfactor representative.
   -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: C:\Program Files\Keyfactor\Keyfactor CA Connector This parameter cannot be used in conjunction with the InPlace parameter.
   -Force	No	Specifying this parameter causes the installation to warn and continue on certain potential problems, including: A service with either the default service name or the service name specified with the ServiceSuffix parameter already exists. The service will be overwritten if Force is specified. Either the default installation location or the location specified with the Location 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.
   -InPlace	No	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.
   -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.
   -NoValidate	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.
   -ServiceSuffix	No	This parameter is used to add a suffix to the root service name of KeyfactorCAConnector (e.g. Instance1 for a resulting service name of KeyfactorCAConnector-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 KeyfactorCAConnector-Default will be used—with a display name of Keyfactor CA Connector Service (Default).
   -ServiceUser	No	This is the credential object of the service account the CA Connector Client service will run as (see CA Connector Client Service). It is provided as a PSCredential object. If this parameter is not specified, the built-in Network Service account will be used.
   -Source	No	Specify this parameter to point to a directory containing the installation files other than the directory in which the Install-CAConnector.ps1 file is found. This parameter is used primarily if a copy of the Install-CAConnector.ps1 file is made in an alternate directory, updated with some customizations, and then used for installation without being copied back to the directory where the remaining installation files are located.
   -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

   Tip:  While not required for operation, WebSockets may be used as the transport protocol between the CA Connector Client and the CA Connector 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. 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 not created in Keyfactor Command before running the installation (see Preparing) and so when the connection to Keyfactor Command was tested, a warning was generated, but the installation was allowed to proceed.

   $serviceUser = "KEYEXAMPLE\svc_kyfconnect"
   $servicePassword = "MySecurePassword"
   $secServicePassword = ConvertTo-SecureString $servicePassword -AsPlainText -Force
   $credService = New-Object System.Management.Automation.PSCredential ($serviceUser, $secServicePassword)
   $mySecret = ConvertTo-SecureString -Force -AsPlainText 'MySuperSecureClientSecret'
   
   .\Install-CAConnector.ps1 -URL https://kyf101.keyfactorpki.com/KeyfactorCAConnectors/ -Scope api://a12b345c-1234-8qqe-7521-1d91e647f7bg/.default -AuthURL https://keyexample.us.auth0.com/oauth/token -ClientID 1a234567-8b90-123c-d456-7e89f0123ghi -Name websrvr12.keyexample.com -ServiceUser $credService -clientSecret $mySecret
   
   Testing connection to server
   WARNING: Authorization error for provided user/name/ca type. Connection test failed.
   Copying files
   C:\Users\jsmith\Desktop\CAConnectorInstall\CAConnector.exe
   Setting configuration data
   Installing Windows Service
   Granting Log on as a Service permission to keyexample\svc_kyfconnect
   Starting service KeyfactorCAConnector-Default

4. Review the output from the installation to confirm that no errors have occurred.

The script creates a directory, C:\Program Files\Keyfactor\Keyfactor CA Connector by default, and places the CA Connector Client files in this directory. Log files are found in C:\Program Files\Keyfactor\Keyfactor CA Connector\Logs by default, though this is configurable (see Configure Logging).

The CA Connector Client service, by default given a display name of Keyfactor CA Connector Service (Default), should be automatically started at the conclusion of the install and configured to restart on reboot.