ab#46718 2.0 Feature Set Complete (#20)

* Kv sub path support (#12) * updated to support 2 store types. HCVKV and HCV. * Updated to distinguish between multiple supported store types. * updated doc to reflect multiple store type configs. * removed sensitive info from tracelog. * Removed KEY_SECRET from PutCertificate Task * Modified PutCertificate to include ---BEGIN ----END banners (for key+cert) * Allows Cert Stores to be allow a boolean value for SubfolderInventory. Allows inventory to be done on a root storepath and all of the component/subdirectories. Included documentation update to README.md * Adding InputValidation for KeyValue secrets * Update generated README * Include pem chain (#17) * Fixed store path and mount point mapping * Fixed issue with path not being resolved before attempting to write cert. * Allows for Recursive subfolder inventory * Update readme to call out cert store limits * Adding InputValidation for KeyValue secrets * including certificate chain when enrolling via platform. * added flag on store type to indicate whether to include cert chain * fixed issue when checking for revocation time for inventory. * Combine chain certs (#19) * updated documentation to store Vault token as a secret instead of plain string. * Updated property names. now including full chain in ca_chain field. * fixed issue with revocation time check. * updated fields. the full chain is now stored in certificate if selected. * Fixed issue where improperly formatted secrets would cause inventory to bail. * Update changelog version info * updated integration manifest * Update generated README * Create keyfactor-merge-store-types.yml --------- Co-authored-by: Joe VanWanzeele <[email protected]> Co-authored-by: Keyfactor <[email protected]> Co-authored-by: Michael Henderson <[email protected]> Co-authored-by: JoeKF <[email protected]>
Keyfactor · Jun 28, 2023 · 7f756a6 · 7f756a6
1 parent df02b3c
commit 7f756a6
Show file tree

Hide file tree

Showing 26 changed files with 1,097 additions and 480 deletions.
diff --git a/.github/workflows/keyfactor-merge-store-types.yml b/.github/workflows/keyfactor-merge-store-types.yml
@@ -0,0 +1,27 @@
+name: Keyfactor Merge Cert Store Types
+on: [workflow_dispatch]
+
+jobs:
+  get-manifest-properties:
+    runs-on: windows-latest
+    outputs:
+      update_catalog: ${{ steps.read-json.outputs.update_catalog }}
+      integration_type:  ${{ steps.read-json.outputs.integration_type }}
+    steps:
+      - uses: actions/checkout@v3
+      - name: Store json
+        id: read-json
+        shell: pwsh
+        run: |
+          $json = Get-Content integration-manifest.json | ConvertFrom-Json
+          $myvar = $json.update_catalog
+          echo "update_catalog=$myvar" | Out-File -FilePath $Env:GITHUB_OUTPUT -Encoding utf8 -Append
+          $myvar = $json.integration_type
+          echo "integration_type=$myvar" | Out-File -FilePath $Env:GITHUB_OUTPUT -Encoding utf8 -Append
+
+  call-update-store-types-workflow:
+    needs: get-manifest-properties
+    if: needs.get-manifest-properties.outputs.integration_type == 'orchestrator' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
+    uses: Keyfactor/actions/.github/workflows/update-store-types.yml@main
+    secrets: 
+      token: ${{ secrets.UPDATE_STORE_TYPES }}
diff --git a/.github/workflows/keyfactor-starter-workflow.yml b/.github/workflows/keyfactor-starter-workflow.yml
@@ -5,6 +5,19 @@ jobs:
   call-create-github-release-workflow:
     uses: Keyfactor/actions/.github/workflows/github-release.yml@main
 
+  get-manifest-properties:
+    runs-on: windows-latest
+    outputs:
+      update_catalog: ${{ steps.read-json.outputs.prop }}
+    steps:
+      - uses: actions/checkout@v3
+      - name: Read json
+        id: read-json
+        shell: pwsh
+        run: |
+          $json = Get-Content integration-manifest.json | ConvertFrom-Json
+          echo "::set-output name=prop::$(echo $json.update_catalog)"
+
   call-dotnet-build-and-release-workflow:
     needs: [call-create-github-release-workflow]
     uses: Keyfactor/actions/.github/workflows/dotnet-build-and-release.yml@main
@@ -18,9 +31,12 @@ jobs:
   call-generate-readme-workflow:
     if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
     uses: Keyfactor/actions/.github/workflows/generate-readme.yml@main
+    secrets:
+      token: ${{ secrets.APPROVE_README_PUSH }}
 
   call-update-catalog-workflow:
-    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+    needs: get-manifest-properties
+    if: needs.get-manifest-properties.outputs.update_catalog == 'True' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
     uses: Keyfactor/actions/.github/workflows/update-catalog.yml@main
     secrets: 
       token: ${{ secrets.SDK_SYNC_PAT }}
diff --git a/.gitignore b/.gitignore
@@ -8,3 +8,4 @@
 /hashicorp-vault-orchestrator/hashicorp-vault-orchestrator.csproj.user
 .vs
 *.licenseheader
+README.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,18 @@
+## 2.0.0
+
+* Added support for storing certs in sub-paths
+* Updated documentation to specify storing the token as a secret.
+* Added inventory job support for the Hashicorp PKI secrets engine
+* Added inventory job support for the Keyfactor secrets engine
+
+* **Breaking Change**: the properties have been renamed from:
+    * `PUBLIC_KEY` to `certificate`
+    * `PRIVATE_KEY` to `private_key`
+    * `PUBLIC_KEY_<n>` has been removed.  Now the chain is stored in `certificate` if the option is selected.
+
+* **Breaking Change**: Added a flag on the Keyfactor Certificate store definition to indicate whether to store the full CA chain along with the certificate
+
+
+* **Breaking Change**: the cert store types are now:
+    * **HCVPKI** for the PKI and Keyfactor secrets engine
+    * **HCVKV** for the Key-Value secrets engine
diff --git a/README.md b/README.md
@@ -1,24 +1,38 @@
 # Orchestrator Extension for Hashicorp Vault
 
-The Hashicorp Vault Orchestrator extension allows you store certificates in Hashicorp Vault KeyValue secrets engine. 
+The Hashicorp Vault Orchestrator extension allows you to manage certificates in Hashicorp Vault KeyValue secrets engine and perform inventory on certificates stored in the PKI or Keyfactor secrets engines.
 
 #### Integration status: Production - Ready for use in production environments.
 
-## About the Keyfactor Universal Orchestrator Capability
 
-This repository contains a Universal Orchestrator Capability which is a plugin to the Keyfactor Universal Orchestrator. Within the Keyfactor Platform, Orchestrators are used to manage “certificate stores” &mdash; collections of certificates and roots of trust that are found within and used by various applications.
+## About the Keyfactor Universal Orchestrator Extension
 
-The Universal Orchestrator is part of the Keyfactor software distribution and is available via the Keyfactor customer portal. For general instructions on installing Capabilities, see the “Keyfactor Command Orchestrator Installation and Configuration Guide” section of the Keyfactor documentation. For configuration details of this specific Capability, see below in this readme.
+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” &mdash; collections of certificates and roots of trust that are found within and used by various applications.
 
-The Universal Orchestrator is the successor to the Windows Orchestrator. This Capability plugin only works with the Universal Orchestrator and does not work with the Windows Orchestrator.
+The Universal Orchestrator is part of the Keyfactor software distribution and is available via the Keyfactor customer portal. For general instructions on installing Extensions, see the “Keyfactor Command Orchestrator Installation and Configuration Guide” section of the Keyfactor documentation. For configuration details of this specific Extension see below in this readme.
 
+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 Orchestrator Extension for Hashicorp Vault
+
+Orchestrator Extension for Hashicorp Vault is supported by Keyfactor for Keyfactor customers. If you have a support issue, please open a support ticket with your Keyfactor representative.
+
+###### 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.
@@ -33,58 +47,71 @@ The Keyfactor Universal Orchestrator may be installed on either Windows or Linux
 
 
 
+
+
 ---
 
 
 <!-- add integration specific information below -->
 
-This integration for the Keyfactor Universal Orchestrator has been tested against Hashicorp Vault 1.10.  It utilizes the *Key/Value* secrets engine to store certificates issues via Keyfactor Command.
+This integration for the Keyfactor Universal Orchestrator has been tested against Hashicorp Vault 1.10.  It utilizes the **Key/Value** secrets engine to store certificates issues via Keyfactor Command.
 
 ## Use Cases
 
-The Hashicorp Vault Orchestrator Integration implements the following capabilities:
+This integration supports 3 Hashicorp Secrets Engines; PKI, Key-Value store, and the Keyfactor Hashicorp Plugin (Keyfactor Secrets Engine).
+
+### The Key-Value secrets engine
+
+The Following operations are supported by this integration **only** for the Key-Value secrets engine.
 
 1. Discovery - Discover all sub-paths containing certificate.
 1. Inventory - Return all certificates stored in a path.
 1. Management (Add) - Add a certificate to a defined certificate store.
 1. Management (Remove) - Remove a certificate from a defined certificate store.
 
+### The Hashicorp PKI and Keyfactor Plugin secrets engines
+
+Both the Hashicorp PKI and Keyfactor plugin are designed to allow managing certifications directly on the Hashicorp Vault instance.
+This integration does support the following in order to view your certificates from the platform:
+
+1. Inventory - Return all certificates stored in a path.
+
+[View the repository on Github](https://github.com/Keyfactor/hashicorp-vault-secretsengine) for more information about the Hashicorp Vault Keyfactor Secrets Engine plugin.
+
 ## Versioning
 
 The version number of a the Hashicorp Vault Orchestrator Extension can be verified by right clicking on the `Keyfactor.Extensions.Orchestrator.HCV.dll` file in the extensions installation folder, selecting Properties, and then clicking on the Details tab.
 
 ## Keyfactor Version Supported
 
-This integration was built on the .NET Core 3.1 target framework and are compatible for use with the Keyfactor Universal Orchestrator.
+This integration was built on the .NET Core 3.1 target framework and are compatible for use with the Keyfactor Universal Orchestrator and the latest version of the Keyfactor platform.
 
 ## Security Considerations
 
 1. It is not necessary to use the Vault root token when creating a Certificate Store for HashicorpVault.  We recommend creating a token with policies that reflect the minimum permissions necessary to perform the intended operations.
-1. The certificates are stored in 3 fields in the Key Value store.  
-
-- `PUBLIC_KEY` - The certificate public key
-- `PRIVATE_KEY` - The certificate private key
-- `KEY_SECRET` - The certificate private key password
-
-## Extension Configuration
 
-### On the Orchestrator Agent Machine
+1. For the Key-Value secrets engine, the certificates are stored as an entry with these fields.  
 
-1. Stop the Orchestrator service.
+- `certificate` - The PEM formatted certificate and intermediate CA chain (if selected)
+- `private_key` - The certificate private key
 
-- The service will be called "KeyfactorOrchestrator-Default" by default.
+**Note**: Key/Value secrets that do not include the keys `certificate` and `private_key` will be ignored during inventory scans. 
 
-1. Navigate to the "extensions" sub-folder of your Orchestrator installation directory
+## Extension Configuration
 
-- example: `C:\Program Files\Keyfactor\Keyfactor Orchestrator\extensions`
+### On the Orchestrator Agent Machine
 
-1. Create a new folder called "HCV" (the name of the folder is not important)
-1. Extract the contents of the release zip file into this folder.
-1. Re-start the Orchestrator service.
+1. Stop the Orchestrator service.
+    - The service will be called "KeyfactorOrchestrator-Default" by default.
+2. Navigate to the "extensions" sub-folder of your Orchestrator installation directory
+    - example: `C:\Program Files\Keyfactor\Keyfactor Orchestrator\extensions`
+3. Create a new folder called "HCV" (the name of the folder is not important)
+4. Extract the contents of the release zip file into this folder.
+5. Re-start the Orchestrator service.
 
 ### In the Keyfactor Platform
 
-1. Add a new Certificate Store Type
+#### Add a new Certificate Store Type - **Key-Value Secrets Engine**
 
 - Log into Keyfactor as Administrator or a user with permissions to add certificate store types.
 - Click on the gear icon in the top right and then navigate to the "Certificate Store Types"
@@ -93,33 +120,39 @@ This integration was built on the .NET Core 3.1 target framework and are compati
 ![](images/store_type_add.png)
 
 - Set the following values in the "Basic" tab:
-  - **Name** - "Hashicorp Vault" (or another preferred name)
-  - **Short Name** - "HCV"
+  - **Name:** "Hashicorp Vault Key-Value" (or another preferred name)
+  - **Short Name:** "HCVKV"
   - **Supported Job Types** - "Inventory", "Add", "Remove", "Discovery"
+
+![](images/store-type-kv.PNG)
+
+- Set the following values on the "Advanced" tab:
   - **Supports Custom Alias** - "Optional"
   - **Private Key Handling** - "Optional"
 
-![](images/store_type_1.png)
+![](images/cert-store-type-advanced.png)
 
 - Click the "Custom Fields" tab to add the following custom fields:
   - **MountPoint** - type: *string*
   - **VaultServerUrl** - type: *string*, *required*
-  - **VaultToken** - type: *string*, *required*
+  - **VaultToken** - type: *secret*, *required*
+  - **SubfolderInventory** - type: *bool* (By default, this is set to false. Not a required field)
+  - **IncludeCertChain** - type: *bool* (If true, the available intermediate certificates will also be written to Vault during enrollment)
 
 ![](images/store_type_fields.png)
 
 - Click **Save** to save the new Store Type.
 
-1. Add the Hashicorp Vault Certificate Store
+#### Add the Hashicorp Vault Certificate Store - **Key-Value Secrets Engine**
 
 - Navigate to **Locations** > **Certificate Stores** from the main menu
 - Click **ADD** to open the new Certificate Store Dialog
 
-![](images/cert_store_add_dialog.png)  
+![](images/cert_store_add_dialog.png)
 
-In Keyfactor Command create a new Certificate Store Type similar to the one below:
+In Keyfactor Command create a new Certificate Store that resembles the one below:
 
-![](images/cert_store_fields.png)  
+![](images/cert_store_fields.png)
 
 - **Client Machine** - Enter the URL for the Vault host machine
 - **Store Path** - This is the path after mount point where the certs will be stored.
@@ -128,11 +161,65 @@ In Keyfactor Command create a new Certificate Store Type similar to the one belo
   - If left blank, will default to "kv-v2".
 - **Vault Token** - This is the access token that will be used by the orchestrator for requests to Vault.
 - **Vault Server Url** - the full url and port of the Vault server instance
+- **Subfolder Inventory** - Set to 'True' if it is a requirement to inventory secrets at the subfolder/component level. The default, 'False' will inventory secrets stored at the root of the "Store Path", but will not look at secrets in subfolders. **Note** that there is a limit on the number of certificates that can be in a certificate store. In certain environments enabling Subfolder Inventory may exceed this limit and cause inventory job failure. Inventory job results are currently submitted to the Command platform as a single HTTP POST. There is not a specific limit on the number of certificates in a store, rather the limit is based on the size of the actual certificates and the HTTP POST size limit configured on the Command web server.
+
+### For the Keyfactor and PKI plugins
 
-## Testing
+- Add a new Certificate Store Type
+  - Log into Keyfactor as Administrator or a user with permissions to add certificate store types.
+  - Click on the gear icon in the top right and then navigate to the "Certificate Store Types"
+  - Click "Add" and enter the following information on the first tab:
+
+![](images/store_type_add.png)
+
+- **Name:** "Hashicorp Vault PKI" (or another preferred name)
+- **Short Name:** "HCVPKI"
+- **Supported Job Types:** "Inventory"
+
+![](images/store_type_pki.PNG)
+
+- Set the following values on the "Advanced" tab:
+  - **Supports Custom Alias** - "Optional"
+  - **Private Key Handling** - "Optional"
+
+![](images/cert-store-type-advanced.png)
+
+- Click the "Custom Fields" tab to add the following custom fields:
+  - **MountPoint** - type: *string*
+  - **VaultServerUrl** - type: *string*, *required*
+  - **VaultToken** - type: *secret*, *required*
+
+![](images/store_type_fields.png)
+
+- Click **Save** to save the new Store Type.
+
+1. Add the Hashicorp Vault Certificate Store
+
+- Navigate to **Locations** > **Certificate Stores** from the main menu
+- Click **ADD** to open the new Certificate Store Dialog
+
+In Keyfactor Command create a new Certificate Store similar to the one below:
+
+![](images/store_type_pki.png)
+
+- **Client Machine** - Enter the URL for the Vault host machine
+- **Store Path** - "/"  
+- **Mount Point** - This is the mount point name for the instance of the PKI or Keyfactor secrets engine plugin.
+  - If using the PKI plugin, the default in Hashicorp is pki.  If using the Keyfactor plugin, it should correspond to the mount point given when the plugin was enabled.
+  - It is possible to have multiple instances of the Keyfactor plugin running simultaneously, so be sure this corresponds to the one you would like to manage.
+
+- **Vault Token** - This is the access token that will be used by the orchestrator for requests to Vault.
+- **Vault Server Url** - the full url and port of the Vault server instance
+
+At this point, the certificate store should be created and ready to peform inventory on your certificates stored via the Keyfactor or PKI secrets engine plugin for Hashicorp Vault.
+
+## Testing the Key-Value store
 
 ### PFX Enrollment into Vault
 
+**Note**
+Enrollment via the platform is only supported by the Key-Value store type
+
 At this point you should be able to enroll a certificate and store it in Vault using the plugin.
 
 1. Navigate to `Enrollment > PFX Enrollment` from the main menu.
@@ -153,7 +240,7 @@ At this point you should be able to enroll a certificate and store it in Vault u
 
 - Make sure the vault is unsealed first
 
-1. Type `vault kv list kv/cert-store` (where "kv/cert-store" is <mount point>/<store path>)
+1. Type `vault kv list kv/cert-store` (where "kv/cert-store" is `<mount point>/<store path>`)
 
 - You should see the alias of the newly enrolled certificate
 
@@ -168,6 +255,5 @@ At this point you should be able to enroll a certificate and store it in Vault u
 
 ## Notes / Future Enhancements
 
-- Currently we only operate on a single version of the Key Value secret (no versioning capabilities through the Orchesterator Extension / Keyfactor).
-- Creating a new certificate store is done implicitly by adding a **store path** value that doesn't currently exist.  
+- For the Key-Value stores we operate on a single version of the Key Value secret (no versioning capabilities through the Orchesterator Extension / Keyfactor).
 
diff --git a/hashicorp-vault-orchestrator.sln b/hashicorp-vault-orchestrator.sln
@@ -7,6 +7,7 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "hashicorp-vault-orchestrato
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{83623EBF-AC4C-4158-922D-959AEFC75453}"
 	ProjectSection(SolutionItems) = preProject
+		CHANGELOG.md = CHANGELOG.md
 		integration-manifest.json = integration-manifest.json
 		LICENSE = LICENSE
 		README.md = README.md

diff --git a/hashicorp-vault-orchestrator/Constants.cs b/hashicorp-vault-orchestrator/Constants.cs
@@ -9,7 +9,8 @@ namespace Keyfactor.Extensions.Orchestrator.HashicorpVault
 {
     static class AzureKeyVaultConstants
     {
-        public const string STORE_TYPE_NAME = "HCV";
+        public const string KEY_VALUE_STORE_TYPE = "HCVKV";
+        public const string PKI_STORE_TYPE = "HCV"; //same for Keyfactor plugin store type
     }
 
     static class JobTypes