Release 2.3 (#100)

Squash 2.3.1 to main

Author: fiddlermikey

CHANGELOG.md

@@ -1,3 +1,6 @@
+2.3.1
+* Added additional error trapping for WinRM connections to allow actual error on failure.
+
 2.3.0
 * Added Sql Server Binding Support
 * Modified WinCert Advanced PrivateKeyAllowed setting from Required to Optional

IISU/ClientPSCertStoreManager.cs

@@ -65,9 +65,8 @@ public JobResult AddCertificate(string certificateContents, string privateKeyPas
                         X509KeyStorageFlags.Exportable
                     );
 
-                _logger.LogTrace($"X509 Cert Created With Subject: {x509Cert.SubjectName}");
-                _logger.LogTrace(
-                    $"Begin Add for Cert Store {$@"\\{_runspace.ConnectionInfo.ComputerName}\{storePath}"}");
+                _logger.LogDebug($"X509 Cert Created With Subject: {x509Cert.SubjectName}");
+                _logger.LogDebug($"Begin Add for Cert Store {$@"\\{_runspace.ConnectionInfo.ComputerName}\{storePath}"}");
 
                 // Add Certificate 
                 var funcScript = @"
@@ -83,12 +82,13 @@ function InstallPfxToMachineStore([byte[]]$bytes, [string]$password, [string]$st
                         }";
 
                 ps.AddScript(funcScript).AddStatement();
-                _logger.LogTrace("InstallPfxToMachineStore Statement Added...");
+                _logger.LogDebug("InstallPfxToMachineStore Statement Added...");
 
                 ps.AddCommand("InstallPfxToMachineStore")
                     .AddParameter("bytes", Convert.FromBase64String(certificateContents))
                     .AddParameter("password", privateKeyPassword)
                     .AddParameter("storeName", $@"\\{_runspace.ConnectionInfo.ComputerName}\{storePath}");
+                
                 _logger.LogTrace("InstallPfxToMachineStore Command Added...");
 
                 foreach (var cmd in ps.Commands.Commands)
@@ -100,6 +100,7 @@ function InstallPfxToMachineStore([byte[]]$bytes, [string]$password, [string]$st
                 _logger.LogTrace("Invoking ps...");
                 ps.Invoke();
                 _logger.LogTrace("ps Invoked...");
+
                 if (ps.HadErrors)
                 {
                     _logger.LogTrace("ps Has Errors");
@@ -119,6 +120,7 @@ function InstallPfxToMachineStore([byte[]]$bytes, [string]$password, [string]$st
                 _logger.LogTrace("Clearing Commands...");
                 ps.Commands.Clear();
                 _logger.LogTrace("Commands Cleared..");
+                _logger.LogInformation($"Certificate was successfully added to cert store: {storePath}");
 
                 return new JobResult
                 {
@@ -129,6 +131,8 @@ function InstallPfxToMachineStore([byte[]]$bytes, [string]$password, [string]$st
             }
             catch (Exception e)
             {
+                _logger.LogError($"Error Occurred in ClientPSCertStoreManager.AddCertificate(): {e.Message}");
+
                 return new JobResult
                 {
                     Result = OrchestratorJobStatusJobResult.Failure,

IISU/ImplementedStoreTypes/Win/Management.cs

@@ -119,26 +119,22 @@ private JobResult performAddition(ManagementJobConfiguration config)
                 string storePath = config.CertificateStoreDetails.StorePath;
                 long jobNumber = config.JobHistoryId;
 
-                // Setup a new connection to the client machine
-                //var connectionInfo = new WSManConnectionInfo(new Uri($"{certStoreDetails?.WinRmProtocol}://{config.CertificateStoreDetails.ClientMachine}:{certStoreDetails?.WinRmPort}/wsman"));
-                //_logger.LogTrace($"WinRm URL: {certStoreDetails?.WinRmProtocol}://{config.CertificateStoreDetails.ClientMachine}:{certStoreDetails?.WinRmPort}/wsman");
-
                 if (storePath != null)
                 {
-                    _logger.LogTrace($"Attempting to get licenses from cert path: {storePath})");
+                    _logger.LogInformation($"Attempting to add certificate to cert store: {storePath}");
 
                     ClientPSCertStoreManager manager = new ClientPSCertStoreManager(_logger, myRunspace, jobNumber);
-                    JobResult result = manager.AddCertificate(certificateContents, privateKeyPassword, storePath);
-                    
-                    _logger.LogTrace($"Certificate was successfully added to cert store: {storePath})");
+                    return manager.AddCertificate(certificateContents, privateKeyPassword, storePath);
                 }
-
-                return new JobResult
+                else
                 {
-                    Result = OrchestratorJobStatusJobResult.Success,
-                    JobHistoryId = config.JobHistoryId,
-                    FailureMessage = ""
-                };
+                    return new JobResult
+                    {
+                        Result = OrchestratorJobStatusJobResult.Failure,
+                        JobHistoryId = config.JobHistoryId,
+                        FailureMessage = "Store Path is empty or null."
+                    };
+                }
             }
             catch (Exception e)
             {

README.md

@@ -1,10 +1,10 @@
+
 # WinCertStore Orchestrator
 
 The Windows Certificate Store Orchestrator Extension implements two certificate store types. 1) “WinCert” which manages certificates in a Windows local machine store, and 2) “IISU” which manages certificates and their bindings in a Windows local machine store that are bound to Internet Information Server (IIS) websites. These extensions replace the now deprecated “IIS” cert store type that ships with Keyfactor Command. The “IISU” extension also replaces the “IISBin” certificate store type from prior versions of this repository. This orchestrator extension is in the process of being renamed from “IIS Orchestrator” as it now supports certificates that are not in use by IIS.
 
 #### Integration status: Production - Ready for use in production environments.
 
-
 ## About the Keyfactor Universal Orchestrator Extension
 
 This repository contains a Universal Orchestrator Extension which is a plugin to the Keyfactor Universal Orchestrator. Within the Keyfactor Platform, Orchestrators are used to manage “certificate stores” — collections of certificates and roots of trust that are found within and used by various applications.
@@ -13,23 +13,22 @@ The Universal Orchestrator is part of the Keyfactor software distribution and is
 
 The Universal Orchestrator is the successor to the Windows Orchestrator. This Orchestrator Extension plugin only works with the Universal Orchestrator and does not work with the Windows Orchestrator.
 
-
 ## Support for WinCertStore Orchestrator
 
-WinCertStore Orchestrator is supported by Keyfactor for Keyfactor customers. If you have a support issue, please open a support ticket with your Keyfactor representative.
+WinCertStore Orchestrator is supported by Keyfactor for Keyfactor customers. If you have a support issue, please open a support ticket via the Keyfactor Support Portal at https://support.keyfactor.com
 
 ###### To report a problem or suggest a new feature, use the **[Issues](../../issues)** tab. If you want to contribute actual bug fixes or proposed enhancements, use the **[Pull requests](../../pulls)** tab.
 
-
 ---
 
 
+---
+
 
 
 ## Keyfactor Version Supported
 
 The minimum version of the Keyfactor Universal Orchestrator Framework needed to run this version of the extension is 10.1
-
 ## Platform Specific Notes
 
 The Keyfactor Universal Orchestrator may be installed on either Windows or Linux based platforms. The certificate operations supported by a capability may vary based what platform the capability is installed on. The table below indicates what capabilities are supported based on which platform the encompassing Universal Orchestrator is running.
@@ -124,6 +123,27 @@ In version 2.0 of the IIS Orchestrator, the certificate store type has been rena
 
 **Note: If Looking to use GMSA Accounts to run the Service Kefyactor Command 10.2 or greater is required for No Value checkbox to work**
 
+## 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, the following information may be helpful:
+ 
+*	The WinCert extensions (WinCert, IISU, WinSQL) create a WinRM (remote PowerShell) session to the target server in order to manipulate the Windows Certificate Stores, perform binding (in the case of the IISU extension), or to access the registry (in the case of the WinSQL extension). 
+ 
+*	When the WinRM session is created, the certificate store credentials are used if they have been specified, otherwise the WinRM session is created in the context of the Universal Orchestrator (UO) Service account (which potentially could be the network service account, a regular account, or a GMSA account)
+ 
+*	WinRM needs to be properly set up between the server hosting the UO and the target server. This means that a WinRM client running on the UO server when running in the context of the UO service account needs to be able to create a session on the target server using the configured credentials of the target server and any PowerShell commands running on the remote session need to have appropriate permissions. 
+ 
+*	Even though a given account may be in the administrators group or have administrative privledges on the target system and may be able to execute certificate and binding operations when running locally, the same account may not work when being used via WinRM. User Account Control (UAC) can get in the way and filter out administrative privledges. UAC / WinRM configuration has a LocalAccountTokenFilterPolicy setting that can be adjusted to not filter out administrative privledges for remote users, but enabling this may have other security ramifications. 
+ 
+*	The following list may not be exhaustive, but in general the account (when running under a remote WinRM session) needs permissions to:
+    -	Instantiate and open a .NET X509Certificates.X509Store object for the target certificate store and be able to read and write both the certificates and related private keys. Note that ACL permissions on the stores and private keys are separate.
+    -	Use the Import-Certificate, Get-WebSite, Get-WebBinding, and New-WebBinding PowerShell CmdLets.
+    -	Create and delete temporary files.
+    -	Execute certreq commands.
+    -	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.
+
 ## Creating New Certificate Store Types
 Currently this orchestrator handles two extensions: IISU for IIS servers with bound certificates and WinCert for general Windows Certificates.
 Below describes how each of these certificate store types are created and configured.

integration-manifest.json

@@ -12,6 +12,7 @@
     "orchestrator": {
       "UOFramework": "10.1",
       "pam_support": true,
+      "keyfactor_platform_version": "9.10",
       "win": {
         "supportsCreateStore": false,
         "supportsDiscovery": false,

readme_source.md

@@ -23,6 +23,27 @@ In version 2.0 of the IIS Orchestrator, the certificate store type has been rena
 
 **Note: If Looking to use GMSA Accounts to run the Service Kefyactor Command 10.2 or greater is required for No Value checkbox to work**
 
+## 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, the following information may be helpful:
+ 
+*	The WinCert extensions (WinCert, IISU, WinSQL) create a WinRM (remote PowerShell) session to the target server in order to manipulate the Windows Certificate Stores, perform binding (in the case of the IISU extension), or to access the registry (in the case of the WinSQL extension). 
+ 
+*	When the WinRM session is created, the certificate store credentials are used if they have been specified, otherwise the WinRM session is created in the context of the Universal Orchestrator (UO) Service account (which potentially could be the network service account, a regular account, or a GMSA account)
+ 
+*	WinRM needs to be properly set up between the server hosting the UO and the target server. This means that a WinRM client running on the UO server when running in the context of the UO service account needs to be able to create a session on the target server using the configured credentials of the target server and any PowerShell commands running on the remote session need to have appropriate permissions. 
+ 
+*	Even though a given account may be in the administrators group or have administrative privledges on the target system and may be able to execute certificate and binding operations when running locally, the same account may not work when being used via WinRM. User Account Control (UAC) can get in the way and filter out administrative privledges. UAC / WinRM configuration has a LocalAccountTokenFilterPolicy setting that can be adjusted to not filter out administrative privledges for remote users, but enabling this may have other security ramifications. 
+ 
+*	The following list may not be exhaustive, but in general the account (when running under a remote WinRM session) needs permissions to:
+    -	Instantiate and open a .NET X509Certificates.X509Store object for the target certificate store and be able to read and write both the certificates and related private keys. Note that ACL permissions on the stores and private keys are separate.
+    -	Use the Import-Certificate, Get-WebSite, Get-WebBinding, and New-WebBinding PowerShell CmdLets.
+    -	Create and delete temporary files.
+    -	Execute certreq commands.
+    -	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.
+
 ## Creating New Certificate Store Types
 Currently this orchestrator handles two extensions: IISU for IIS servers with bound certificates and WinCert for general Windows Certificates.
 Below describes how each of these certificate store types are created and configured.