Use kfutil to bulk create Windows IIS bindings

This article will review the procedures required to create multiple Windows IIS-bound certificate stores in the Command platform. This solution will leverage a CSV file that contains the certificate store details like hostname, store path, and binding details to be managed by Command.

Prerequisites

This document requires:

• Keyfactor Command
• A Linux or Windows machine that is running the universal orchestrator
• The iis-orchestrator plugin installed and registered with the universal orchestrator
• A machine where kfutil is installed
• The user running kfutil to have the appropriate rights in Keyfactor Command to issue KeyfactorAPI and management functions (or an appropriate token, etc)
• WinRM is correctly configured on each IIS machine requiring management

Linux prerequisites

Linux systems require PowerShell installed on them. Depending on your operating system, here is how to install it.

Option 1: Debian-based distributions

sudo apt install -y wget
wget https://github.com/PowerShell/PowerShell/releases/download/v7.4.7/powershell_7.4.7-1.deb_amd64.deb
sudo dpkg -i powershell_7.4.7-1.deb_amd64.deb
rm powershell_7.4.7-1.deb_amd64.deb

Option 2: RHEL-based distributions

sudo dnf install -y wget
wget https://github.com/PowerShell/PowerShell/releases/download/v7.4.7/powershell-7.4.7-1.rh.x86_64.rpm
sudo dnf install -y powershell-7.4.7-1.rh.x86_64.rpm
rm powershell-7.4.7-1.rh.x86_64.rpm

Security and permission considerations

From an official support point of view, Local Administrator permissions are required on the target server. Some customers have been successful with using other accounts and granting rights to the underlying certificate and private key stores. Due to complexities with the interactions between Group Policy, WinRM, User Account Control, and other unpredictable customer environmental factors, Keyfactor cannot provide assistance with using accounts other than the local administrator account.

For customers wishing to use something other than the local administrator account, please note that this is not officially supported. Notes can be found in the appropriate section of the iis-orchestrator’s official documentation.

Create store type

The first step is to define the store types of the IIS-bound certificate, Windows certificate, and WinSQL. While IIS-bound certificates are the only required type, we should add the other certificate store types for management of the other store types the iis-orchestrator can manage.

Determine if store types exist

1. Run the kfutil program with the following command.

   kfutil store-types list | jq -r '.[].Name'

2. Look for these items in the output:
   • IIS-bound certificate
   • Windows certificate
   • WinSQL
3. If all items exist, skip the next step and begin the Procedure section.

Create store types

Run the kfutil program with the following commands to create the required store types.

For IIS-bound certificates

kfutil store-types create

A prompt for Choose an option: comes up.

IISU

For Windows certificates

kfutil store-types create

A prompt for Choose an option: comes up.

WinCert

For WinSQL certificates

kfutil store-types create

A prompt for Choose an option: comes up.

WinSql

Procedure

To bulk configure IIS servers, kfutil can utilize a CSV file. The kfutil program requires a defined set of columns to create the certificate stores in Keyfactor Command. These columns vary based on store types.

Step 1: Create CSV template

We can use the kfutil program to generate this template.

kfutil stores import generate-template --store-type-name=IISU

The output should look like the following:

Template file for store type with id 109 written to IISU_bulk_import_template.csv

Step 2: Populate the CSV

Populate the CSV with data about the certificate stores to be created.

Then save the CSV file and transfer it to the machine you have kfutil installed on. Be sure to save this without UTF-8 formatting, as kfutil cannot process UTF-8 files.

Do NOT use UTF-8 formatting for the CSV. If you do, you will get an error.

Step 3: Run the bulk upload

Run the kfutil program with the following commands to upload the contents of the CSV as certificate stores.

kfutil stores import csv --file <csv_filename> --store-type-name IISU

The output should look like the following:

3 records processed.
3 certificate stores successfully created.
Import results written to Book1_results.csv

Verify the results by opening the resulting CSV file.

cat Book1_results.csv

If there are any errors, they will also be reported in Book1_results.csv. For example, if you try and recreate the certificate stores again, Book1_results.csv will look like the following:

$ kfutil stores import csv --file Book1.csv --store-type-name IISU
3 records processed.
3 rows had errors.
Import results written to Book1_results.csv
$ cat Book1_results.csv 
Properties.ServerUsername,Properties.WinRM Protocol,Properties.ServerPassword,ContainerId,ClientMachine,InventorySchedule.Immediate,Id,StorePath,Properties.WinRM Port,Properties.ServerUseSsl,CreateIfMissing,InventorySchedule.Daily.Time,InventorySchedule.Weekly.Days,Errors,InventorySchedule.Interval.Minutes,InventorySchedule.Weekly.Time,Properties.spnwithport,AgentId
uo-login,https,my_password,,10.1.0.101,,error,My,5985,TRUE,FALSE,,,The certificate store already exists with client machine: '10.1.0.101' and store path: 'My'.,60,,FALSE,91dd52a9-8449-4535-a191-b9b6acf1d2b6
uo-login,https,my_password,,10.1.0.102,,error,My,5985,TRUE,FALSE,,,The certificate store already exists with client machine: '10.1.0.102' and store path: 'My'.,60,,FALSE,91dd52a9-8449-4535-a191-b9b6acf1d2b6
uo-login,https,my_password,,10.1.0.103,,error,My,5985,TRUE,FALSE,,,The certificate store already exists with client machine: '10.1.0.103' and store path: 'My'.,60,,FALSE,91dd52a9-8449-4535-a191-b9b6acf1d2b6

Step 4: Verify the results

If additional verification is required, use the Keyfactor Command Portal.

1. Access Orchestrators > Management.
2. Select the orchestrator that corresponds to the request above.
3. Select View Certificate Stores.

4. A list of certificate stores the orchestrator can manage will appear. The following image shows navigating to the certificate stores that the orchestrator will manage.
   
   

   The following image shows a list of all certificate stores that the orchestrator manages.