Install the Keyfactor Remote CA Gateway Connector on Windows

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 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 gateway connector, 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 gateway connector as a custom service account rather than the default of Network Service (see Keyfactor Remote CA Gateway Connector Service), and populate a variable with the client secret for the access token (see Identify the Keyfactor Remote CA Gateway Connector Access Token):

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

    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 'MySecret'

  3. In the PowerShell window, run the Install-GatewayConnector.ps1 script 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.

    Specify this parameter to point to a directory containing the installation files other than the directory in which the Install-GatewayConnector.ps1 file is found. This parameter is used primarily if a copy of the Install-GatewayConnector.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.

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

    C:\Program Files\Keyfactor\Keyfactor Gateway Connector

    This parameter cannot be used in conjunction with the InPlace 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 add a suffix to the root service name of KeyfactorGatewayConnector (e.g. Instance1 for a resulting service name of KeyfactorGatewayConnector-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 KeyfactorGatewayConnector-Default will be used—with a display name of Keyfactor Gateway Connector Service (Default).

    This is the credential object of the service account the gateway connector service will run as (see Keyfactor Remote CA Gateway Connector Service). It is provided as a PSCredential object.

    If this parameter is not specified, the built-in Network Service account will be used.

    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 value of the machine 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). without the domain.

    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.

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

    $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 'h-TM53PDzM9w+!56Gk.z4#TmME=G4=h4r$'

    .\Install-GatewayConnector.ps1 -URL https://kyf101.keyfactorpki.com/RemoteCAManagement -Scope api://a12b345c-1234-8qqe-7521-1d91e647f7bg/.default -AuthURL https://login.microsoftonline.com/mycred.onmicrosoft.com/oauth2/v2.0/token -ClientID 1a234567-8b90-123c-d456-7e89f0123ghi -Name websrvr12.keyexample.com -ServiceUser $credService -clientSecret $mySecret

        Directory: C:\Program Files\Keyfactor\Keyfactor Gateway Connector\logs

    Mode                LastWriteTime         Length   Name
----                -------------         ------   ----
-a----          6/23/2021 8:21 AM            0     Gateway_Connector_Log.txt

    Created new file at C:\Program Files\Keyfactor\Keyfactor Gateway Connector\logs\Gateway_Connector_Log.txt
  4. Review the output from the installation to confirm that no errors have occurred.

The script creates a directory, C:\Program Files\Keyfactor\Keyfactor 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. by default, and places the gateway connector files in this directory. Log files are found in C:\Program Files\Keyfactor\Keyfactor Gateway Connector\Logs by default, though this is configurable (see Configure Logging).

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

Tip:  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.