Merge to main

CHANGELOG.md

@@ -1,3 +1,8 @@
+2.6.1
+* documentation updates for the 2.6 release
+* fix a naming typo in the 2.5 migration SQL script
+* update integration-manifest.json
+
 2.6.0
 * Added the ability to run the extension in a Linux environment.  To utilize this change, for each Cert Store Types (WinCert/WinIIS/WinSQL), add ssh to the Custom Field <b>WinRM Protocol</b>.  When using ssh as a protocol, make sure to enter the appropriate ssh port number under WinRM Port.
 * NOTE: For legacy purposes the Display names WinRM Protocol and WinRM Port are maintained although the type of protocols now includes ssh.

Migration-Scripts/IISU Sni Flag 2.5 upgrade script.sql

@@ -37,28 +37,28 @@ BEGIN TRY
     -- perform batch processing on certstoreinventoryitems to alter their EntryParameters to change the SNiFlag value to be a simple character instead of lots of text
     -- replace 0 - No SNI
     UPDATE inventoryitems
-    SET inventoryitems.[EntryParameters] = REPLACE(inventory.[EntryParameters], '0 - No SNI', '0')
+    SET inventoryitems.[EntryParameters] = REPLACE(inventoryitems.[EntryParameters], '0 - No SNI', '0')
     FROM [cms_agents].[CertStoreInventoryItems] AS inventoryitems
         INNER JOIN #InventoryItems ON inventoryitems.[Id] = #InventoryItems.[Id]
     WHERE inventoryitems.[EntryParameters] LIKE '%0 - No SNI%'
 
     -- replace 1 - SNI Enabled
     UPDATE inventoryitems
-    SET inventoryitems.[EntryParameters] = REPLACE(inventory.[EntryParameters], '1 - SNI Enabled', '1')
+    SET inventoryitems.[EntryParameters] = REPLACE(inventoryitems.[EntryParameters], '1 - SNI Enabled', '1')
     FROM [cms_agents].[CertStoreInventoryItems] AS inventoryitems
         INNER JOIN #InventoryItems ON inventoryitems.[Id] = #InventoryItems.[Id]
     WHERE inventoryitems.[EntryParameters] LIKE '%1 - SNI Enabled%'
 
     -- replace 2 - Non SNI Binding
     UPDATE inventoryitems
-    SET inventoryitems.[EntryParameters] = REPLACE(inventory.[EntryParameters], '2 - Non SNI Binding', '2')
+    SET inventoryitems.[EntryParameters] = REPLACE(inventoryitems.[EntryParameters], '2 - Non SNI Binding', '2')
     FROM [cms_agents].[CertStoreInventoryItems] AS inventoryitems
         INNER JOIN #InventoryItems ON inventoryitems.[Id] = #InventoryItems.[Id]
     WHERE inventoryitems.[EntryParameters] LIKE '%2 - Non SNI Binding%'
 
     -- replace 3 - SNI Binding
     UPDATE inventoryitems
-    SET inventoryitems.[EntryParameters] = REPLACE(inventory.[EntryParameters], '3 - SNI Binding', '3')
+    SET inventoryitems.[EntryParameters] = REPLACE(inventoryitems.[EntryParameters], '3 - SNI Binding', '3')
     FROM [cms_agents].[CertStoreInventoryItems] AS inventoryitems
         INNER JOIN #InventoryItems ON inventoryitems.[Id] = #InventoryItems.[Id]
     WHERE inventoryitems.[EntryParameters] LIKE '%3 - SNI Binding%'

WindowsCertStore.sln

@@ -23,6 +23,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "images", "images", "{630203
 		images\IISUCertStoreBasic.png = images\IISUCertStoreBasic.png
 		images\IISUCustomFields.png = images\IISUCustomFields.png
 		images\IISUEntryParams.png = images\IISUEntryParams.png
+		images\orchestrator-agent.png = images\orchestrator-agent.png
 		images\ReEnrollment1.png = images\ReEnrollment1.png
 		images\ReEnrollment1a.png = images\ReEnrollment1a.png
 		images\ReEnrollment1b.png = images\ReEnrollment1b.png
@@ -36,6 +37,30 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "images", "images", "{630203
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "WinCertTestConsole", "WinCertTestConsole\WinCertTestConsole.csproj", "{D0F4A3CC-5236-4393-9C97-AE55ACE319F2}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docsource", "docsource", "{CFCAC7FE-C9E1-4822-A1B5-45F16E62F5FF}"
+	ProjectSection(SolutionItems) = preProject
+		docsource\content.md = docsource\content.md
+		docsource\iisu.md = docsource\iisu.md
+		docsource\wincert.md = docsource\wincert.md
+		docsource\winsql.md = docsource\winsql.md
+	EndProjectSection
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "images", "images", "{60C10FF8-54FC-4C18-A2EA-F3580ABF0405}"
+	ProjectSection(SolutionItems) = preProject
+		docsource\images\IISU-advanced-store-type-dialog.png = docsource\images\IISU-advanced-store-type-dialog.png
+		docsource\images\IISU-basic-store-type-dialog.png = docsource\images\IISU-basic-store-type-dialog.png
+		docsource\images\IISU-custom-fields-store-type-dialog.png = docsource\images\IISU-custom-fields-store-type-dialog.png
+		docsource\images\IISU-entry-parameters-store-type-dialog.png = docsource\images\IISU-entry-parameters-store-type-dialog.png
+		docsource\images\WinCert-advanced-store-type-dialog.png = docsource\images\WinCert-advanced-store-type-dialog.png
+		docsource\images\WinCert-basic-store-type-dialog.png = docsource\images\WinCert-basic-store-type-dialog.png
+		docsource\images\WinCert-custom-fields-store-type-dialog.png = docsource\images\WinCert-custom-fields-store-type-dialog.png
+		docsource\images\WinCert-entry-parameters-store-type-dialog.png = docsource\images\WinCert-entry-parameters-store-type-dialog.png
+		docsource\images\WinSql-advanced-store-type-dialog.png = docsource\images\WinSql-advanced-store-type-dialog.png
+		docsource\images\WinSql-basic-store-type-dialog.png = docsource\images\WinSql-basic-store-type-dialog.png
+		docsource\images\WinSql-custom-fields-store-type-dialog.png = docsource\images\WinSql-custom-fields-store-type-dialog.png
+		docsource\images\WinSql-entry-parameters-store-type-dialog.png = docsource\images\WinSql-entry-parameters-store-type-dialog.png
+	EndProjectSection
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -65,6 +90,8 @@ Global
 	EndGlobalSection
 	GlobalSection(NestedProjects) = preSolution
 		{6302034E-DF8C-4B65-AC36-CED24C068999} = {1A6C93E7-24FD-47FD-883D-EDABF5CEE4C6}
+		{CFCAC7FE-C9E1-4822-A1B5-45F16E62F5FF} = {1A6C93E7-24FD-47FD-883D-EDABF5CEE4C6}
+		{60C10FF8-54FC-4C18-A2EA-F3580ABF0405} = {CFCAC7FE-C9E1-4822-A1B5-45F16E62F5FF}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {E0FA12DA-6B82-4E64-928A-BB9965E636C1}

docsource/content.md

@@ -1,16 +1,30 @@
 ## Overview
+The Windows Certificate Orchestrator Extension is a multi-purpose integration that can remotely manage certificates on a Windows Server's Local Machine Store.  This extension currently manages certificates for the current store types:
+* WinCert - Certificates defined by path set for the Certificate Store
+* WinIIS - IIS Bound certificates 
+* WinSQL - Certificates that are bound to the specified SQL Instances
 
-The WinCertStore Orchestrator remotely manages certificates in a Windows Server local machine certificate store.  Users are able to determine which store they wish to place certificates in by entering the correct store path.  For a complete list of local machine cert stores you can execute the PowerShell command:
+By default, most certificates are stored in the “Personal” (My) and “Web Hosting” (WebHosting) stores.
+For a complete list of local machine cert stores you can execute the PowerShell command:
 
 	Get-ChildItem Cert:\LocalMachine
 
 The returned list will contain the actual certificate store name to be used when entering store location.
 
-By default, most certificates are stored in the “Personal” (My) and “Web Hosting” (WebHosting) stores.
-
 This extension implements four job types:  Inventory, Management Add/Remove, and Reenrollment.
 
-WinRM is used to remotely manage the certificate stores and IIS bindings.  WinRM must be properly configured to allow the orchestrator on the server to manage the certificates.  Setting up WinRM is not in the scope of this document.
+The Keyfactor Universal Orchestrator (UO) and WinCert Extension can be installed on either Windows or Linux operating systems.  A UO service managing certificates on remote servers is considered to be acting as an Orchestrator, while a UO Service managing local certificates on the same server running the service is considered an Agent.  When acting as an Orchestrator, connectivity from the orchestrator server hosting the WinCert extension to the orchestrated server hosting the certificate stores(s) being managed is achieved via either an SSH (for Linux orchestrated servers) or WinRM (for Windows orchestrated servers) connection.  When acting as an agent (Windows only), WinRM may still be used, OR the certificate store can be configured to bypass a WinRM connection and instead directly access the orchestrator server's certificate stores.
+
+![](images/orchestrator-agent.png)
+
+Please refer to the READMEs for each supported store type for more information on proper configuration and setup for these different stores.  The supported configurations of Universal Orchestrator hosts and managed orchestrated servers are detailed below:
+
+| | UO Installed on Windows | UO Installed on Linux |
+|-----|-----|------|
+|Orchestrated Server hosting certificate store(s) on remote Windows server|WinRM connection | SSH connection |
+|Certificate store(s) on same server as orchestrator service (Agent)| WinRM connection or local file system | Not Supported |  
+
+WinRM is used to remotely manage the certificate stores and IIS bindings on Windows machines only.  WinRM must be properly configured to allow the orchestrator on the server to manage the certificates.  Setting up WinRM is not in the scope of this document.
 
 **Note:**
 In version 2.0 of the IIS Orchestrator, the certificate store type has been renamed and additional parameters have been added. Prior to 2.0 the certificate store type was called “IISBin” and as of 2.0 it is called “IISU”. If you have existing certificate stores of type “IISBin”, you have three options:
@@ -24,6 +38,28 @@ In version 2.0 of the IIS Orchestrator, the certificate store type has been rena
 
 ## Requirements
 
+<details>
+<summary><b>Using the WinCert Extension on Linux servers:</b></summary>
+
+1. General SSH Setup Information: PowerShell 6 or higher and SSH must be installed on all computers.  Install SSH, including ssh server, that's appropriate for your platform.  You also need to install PowerShell from GitHub to get the SSH remoting feature.  The SSH server must be configured to create a SSH subsysten to host a PowerShell process on the remote computer.  It is suggested to turn off password authentication as this extension uses key-based authentication.  
+
+2. SSH Authentication: When creating a Keyfactor certificate store for the WinCert orchestrator extension, the only protocol supported to communicate with Windows servers is ssh.  When providing the user id and password, the connection is attempted by creating a temporary private key file using the contents in the Password textbox. Therefore, the password field must contain the full SSH Private key.  
+
+</details>
+
+<details>
+<summary><b>Using the WinCert Extension on Windows servers:</b></summary>
+
+1. When orchestrating management of external (and potentially local) certificate stores, the WinCert Orchestrator Extension makes use of WinRM to connect to external certificate store servers.  The security context used is the user id entered in the Keyfactor Command certificate store.  Make sure that WinRM is set up on the orchestrated server and that the WinRM port (by convention, 5585 for HTTP and 5586 for HTTPS) is part of the certificate store path when setting up your certificate stores jobs.  If running as an agent, managing local certificate stores, local commands are run under the security context of the user account running the Keyfactor Universal Orchestrator Service.
+
+</details>
+
+Please consult with your company's system administrator for more information on configuring SSH or WinRM in your environment.
+
+### PowerShell Requirements
+PowerShell is extensively used to inventory and manage certificates across each Certificate Store Type.  Windows Desktop and Server includes PowerShell 5.1 that is capable of running all or most PowerShell functions.  If the Orchestrator is to run in a Linux environment using SSH as their communication protocol, PowerShell 6.1 or greater is required (7.4 or greater is recommended).  
+In addition to PowerShell, IISU requires additional PowerShell modules to be installed and available.  These modules include:  WebAdministration and IISAdministration, versions 1.1.
+
 ### 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.
@@ -46,8 +82,8 @@ For customers wishing to use something other than the local administrator accoun
     -	Access any Cryptographic Service Provider (CSP) referenced in re-enrollment jobs.
     -	Read and Write values in the registry (HKLM:\SOFTWARE\Microsoft\Microsoft SQL Server) when performing SQL Server certificate binding.
 
-## Note Regarding Client Machine
+## Client Machine Instructions
+Prior to version 2.6, this extension would only run in the Windows environment.  Version 2.6 and greater is capable of running on Linux, however, only the SSH protocol is supported.
 
 If running as an agent (accessing stores on the server where the Universal Orchestrator Services is installed ONLY), the Client Machine can be entered, OR you can bypass a WinRM connection and access the local file system directly by adding "|LocalMachine" to the end of your value for Client Machine, for example "1.1.1.1|LocalMachine".  In this instance the value to the left of the pipe (|) is ignored.  It is important to make sure the values for Client Machine and Store Path together are unique for each certificate store created, as Keyfactor Command requires the Store Type you select, along with Client Machine, and Store Path together must be unique.  To ensure this, it is good practice to put the full DNS or IP Address to the left of the | character when setting up a certificate store that will be accessed without a WinRM connection.  
 
-Here are the settings required for each Store Type previously configured.

docsource/iisu.md

@@ -9,6 +9,8 @@ The IISU store type represents the IIS servers and their certificate bindings. I
 ### Limitations and Areas of Confusion
 
 - **Caveats:** It's important to ensure that the Windows Remote Management (WinRM) is properly configured on the target server. The orchestrator relies on WinRM to perform its tasks, such as manipulating the Windows Certificate Stores. Misconfiguration of WinRM may lead to connection and permission issues.
+<br><br>When performing <b>Inventory</b>, all bound certificates <i>regardless</i> to their store location will be returned.
+<br><br>When executing an Add or Renew Management job, the Store Location will be considered and place the certificate in that location.
 
 - **Limitations:** Users should be aware that for this store type to function correctly, certain permissions are necessary. While some advanced users successfully use non-administrator accounts with specific permissions, it is officially supported only with Local Administrator permissions. Complexities with interactions between Group Policy, WinRM, User Account Control, and other environmental factors may impede operations if not properly configured.