diff --git a/CHANGELOG.md b/CHANGELOG.md index c2e84d8..4a7cf59 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,6 @@ +## 3.1.1 +* bug fix: no longer stripping slashes from a mountpoint that includes them + ## 3.1.0 * Added support for enterprise namespaces and alternate mount-points during discovery by allowing the value to be entered in the "directories to search" field. diff --git a/README.md b/README.md index bc3634c..6123120 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ The Keyfactor Universal Orchestrator may be installed on either Windows or Linux |Supports Management Remove|✓ |✓ | |Supports Create Store|✓ |✓ | |Supports Discovery|✓ |✓ | -|Supports Renrollment| | | +|Supports Reenrollment| | | |Supports Inventory|✓ |✓ | @@ -50,13 +50,15 @@ The Keyfactor Universal Orchestrator may be installed on either Windows or Linux -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 -This integration supports 3 Hashicorp Secrets Engines; PKI, Key-Value store, and the Keyfactor Hashicorp Plugin (Keyfactor Secrets Engine). +This integration supports three Hashicorp Secrets Engines; **PKI**, **Key-Value** store, and the **Keyfactor** secrets engine. +The first part of this document describes setting up the store types available within the Hashicorp Vault Key-Value secrets engine. +If you are using the Keyfactor Secrets Engine, or the Hashicorp Vault PKI Secrets Engine, you can skip to [this section](#the-hashicorp-pki-and-keyfactor-plugin-secrets-engines). -### The Key-Value secrets engine +## The Key-Value secrets engine For the Key-Value secrets engine, we have 4 store types that can be used. @@ -67,11 +69,11 @@ For the Key-Value secrets engine, we have 4 store types that can be used. The following operations are supported by this integration for all of the Key-Value secrets engine types: -1. Discovery - Discovery all file repositories for the type -1. Inventory - Inventory all certificates in the path -1. Management (Add) - Add a certificate to a defined certificate store. -1. Management (Remove) - Remove a certificate from a defined certificate store. -1. Create - Create a new, empty certificate store at the path defined in Store Path. +1. **Discovery** - Discovery all file repositories for the type +1. **Inventory** - Inventory all certificates in the path +1. **Management (Add)** - Add a certificate to a defined certificate store. +1. **Management (Remove)** - Remove a certificate from a defined certificate store. +1. **Create** - Create a new, empty certificate store at the path defined in Store Path. Excluding *HCVKVPEM*, the discovery process requires that: 1. The entry for the certificate contain the base64 encoded certificate file. @@ -122,30 +124,17 @@ One way to encode a binary certificate store is to use the following command in `c:\> cat | base64` -### The Hashicorp PKI and Keyfactor Plugin secrets engines +## The Hashicorp PKI and Keyfactor Plugin secrets engines Both the Hashicorp PKI and Keyfactor Secrets Engine plugins are designed to allow managing certifications directly on the Hashicorp Vault instance. The store type for the PKI and/or the Keyfactor secrets engine is the same; `HCVPKI`. This integration supports the following in order to view your certificates from the platform: -1. Inventory - Return all certificates stored in a path. +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 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 path and permissions necessary to perform the intended operations. -1. The capabilities required to perform all operations on a cert store within vault are `["read", "list", "create", "update", "patch", "delete"]` -1. These capabilities should apply to the parent folder on file stores. -1. The token will also need `"list"` capability on the `/metadata` path to perform basic operations. +[View the Hashicorp documentation](https://developer.hashicorp.com/vault/api-docs/secret/pki) for more information on the Hashicorp Vault PKI Secrets Engine ## Extension Configuration @@ -161,7 +150,7 @@ This integration was built on the .NET Core 3.1 target framework and are compati ### In the Keyfactor Platform -#### Add a new Certificate Store Type - **Hashicorp Vault Key-Value PEM** +#### Add the 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" @@ -196,7 +185,7 @@ The 3 highlighted fields above will be added automatically by the platform, you - Click **Save** to save the new Store Type. -#### Add the Hashicorp Vault Certificate Store - **Key-Value Secrets Engine** +#### Add the Certificate Store - Navigate to **Locations** > **Certificate Stores** from the main menu - Click **ADD** to open the new Certificate Store Dialog @@ -215,13 +204,15 @@ In Keyfactor Command create a new Certificate Store that resembles the one below - If your organization utilizes Vault enterprise namespaces, you should include the namespace here. - **Subfolder Inventory** - Set to 'True' if all of the certificates . 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. -#### Set the server name and password +#### Set the server username and password -- The server name should be the full URL to the instance of Vault that will be accessible by the orchestrator. (example: `http://127.0.0.1:8200`) +- The server username should be the full URL to the instance of Vault that will be accessible by the orchestrator. (example: `http://127.0.0.1:8200`) - The server password should be the Vault token that will be used for authenticating. ### For the Keyfactor and PKI plugins +#### Add the Store Type + - 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" @@ -232,6 +223,7 @@ In Keyfactor Command create a new Certificate Store that resembles the one below - **Name:** "Hashicorp Vault PKI" (or another preferred name) - **Short Name:** "HCVPKI" - **Supported Job Types:** "Inventory" +- **Needs Server** - should be checked (true). ![](images/store_type_pki.PNG) @@ -241,12 +233,10 @@ In Keyfactor Command create a new Certificate Store that resembles the one below ![](images/cert-store-type-advanced.png) -- Click the "Custom Fields" tab to add the following custom fields: +- Click the "Custom Fields" tab to add the following field: - **MountPoint** - type: *string* - - **VaultServerUrl** - type: *string*, *required* - - **VaultToken** - type: *secret*, *required* - -![](images/store_type_fields.png) + +![](images/store_type_fields_pki.png) - Click **Save** to save the new Store Type. @@ -255,21 +245,26 @@ In Keyfactor Command create a new Certificate Store that resembles the one below - Navigate to **Locations** > **Certificate Stores** from the main menu - Click **ADD** to open the new Certificate Store Dialog +#### Add the Certificate Store + 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 +- **Client Machine** - Enter an identifier for the client machine. This could be the Orchestrator host name, or anything else useful. This value is not used by the extension. - **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. + - If using the PKI plugin, the default in Hashicorp is "pki". If using the Keyfactor plugin, the default is "keyfactor". - 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 +#### Set the server username and password (values hidden) + +- The **SERVER USERNAME** should be the full URL to the instance of Vault that will be accessible by the orchestrator. (example: `http://127.0.0.1:8200`) +- The **SERVER PASSWORD** should be the Vault token that will be used for authenticating. 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 @@ -312,5 +307,23 @@ At this point you should be able to enroll a certificate and store it in Vault u ## Notes / Future Enhancements +### 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 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 path and permissions necessary to perform the intended operations. +1. The capabilities required to perform all operations on a cert store within vault are `["read", "list", "create", "update", "patch", "delete"]` +1. These capabilities should apply to the parent folder on file stores. +1. The token will also need `"list"` capability on the `/metadata` path to perform basic operations. + - For the Key-Value stores we operate on a single version of the Key Value secret (no versioning capabilities through the Orchesterator Extension / Keyfactor). +When creating cert store type manually, that store property names and entry parameter names are case sensitive + + diff --git a/hashicorp-vault-orchestrator.sln b/hashicorp-vault-orchestrator.sln index bc02e16..341745a 100644 --- a/hashicorp-vault-orchestrator.sln +++ b/hashicorp-vault-orchestrator.sln @@ -1,17 +1,36 @@  Microsoft Visual Studio Solution File, Format Version 12.00 -# Visual Studio Version 16 -VisualStudioVersion = 16.0.32413.511 +# Visual Studio Version 17 +VisualStudioVersion = 17.11.35327.3 MinimumVisualStudioVersion = 10.0.40219.1 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "hashicorp-vault-orchestrator", "hashicorp-vault-orchestrator\hashicorp-vault-orchestrator.csproj", "{76771DD1-BDF1-4C3F-9EAB-C9096A1BBF7B}" EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{83623EBF-AC4C-4158-922D-959AEFC75453}" ProjectSection(SolutionItems) = preProject + images\cert-store-kv.PNG = images\cert-store-kv.PNG + images\cert-store-pki.PNG = images\cert-store-pki.PNG + images\cert-store-type-advanced.png = images\cert-store-type-advanced.png + images\cert_store_add_dialog.png = images\cert_store_add_dialog.png + images\cert_store_fields.png = images\cert_store_fields.png CHANGELOG.md = CHANGELOG.md + images\discovery.PNG = images\discovery.PNG integration-manifest.json = integration-manifest.json LICENSE = LICENSE + images\PEM-vault-example-1.PNG = images\PEM-vault-example-1.PNG + images\PEM-vault-example-2.PNG = images\PEM-vault-example-2.PNG + images\PEM-vault-example-3.PNG = images\PEM-vault-example-3.PNG + images\pfx_enrollment_blank.png = images\pfx_enrollment_blank.png + images\pfx_enrollment_certstore.png = images\pfx_enrollment_certstore.png + images\pfx_enrollment_filled.png = images\pfx_enrollment_filled.png README.md = README.md readme_source.md = readme_source.md + images\store-type-kv.PNG = images\store-type-kv.PNG + images\store_type_1.PNG = images\store_type_1.PNG + images\store_type_add.png = images\store_type_add.png + images\store_type_fields.png = images\store_type_fields.png + images\store_type_pki.png = images\store_type_pki.png + images\vault_cli_list.png = images\vault_cli_list.png + images\vault_cli_read.png = images\vault_cli_read.png EndProjectSection EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "readme-src", "readme-src", "{3266961F-0B1D-4DB6-9A58-C0DA958EB832}" diff --git a/hashicorp-vault-orchestrator/HcvKeyfactorClient.cs b/hashicorp-vault-orchestrator/HcvKeyfactorClient.cs index 325444d..a9aee7b 100644 --- a/hashicorp-vault-orchestrator/HcvKeyfactorClient.cs +++ b/hashicorp-vault-orchestrator/HcvKeyfactorClient.cs @@ -21,8 +21,6 @@ namespace Keyfactor.Extensions.Orchestrator.HashicorpVault { public class HcvKeyfactorClient : IHashiClient { - //private IVaultClient _vaultClient { get; set; } - private ILogger logger = LogHandler.GetClassLogger(); private string _vaultUrl { get; set; } @@ -36,9 +34,10 @@ public class HcvKeyfactorClient : IHashiClient public HcvKeyfactorClient(string vaultToken, string serverUrl, string mountPoint, string storePath) { _vaultToken = vaultToken; - _mountPoint = mountPoint ?? "keyfactor"; + _mountPoint = mountPoint ?? "keyfactor"; // the mount point, including the namespace. + _storePath = !string.IsNullOrEmpty(storePath) ? "/" + storePath : storePath; - _vaultUrl = $"{ serverUrl }/v1/{ _mountPoint.Replace("/", string.Empty) }"; + _vaultUrl = $"{ serverUrl }/v1/{ _mountPoint.Replace("//", "/") }"; } public async Task GetCertificateFromPemStore(string key) @@ -125,7 +124,6 @@ public async Task GetCertificateFromPemStore(string key) var content = JsonConvert.DeserializeObject(new StreamReader(res.GetResponseStream()).ReadToEnd()); string[] certKeys; - content.data.TryGetValue("keys", out certKeys); certKeys.ToList().ForEach(k => diff --git a/hashicorp-vault-orchestrator/Jobs/JobBase.cs b/hashicorp-vault-orchestrator/Jobs/JobBase.cs index c386332..6539b21 100644 --- a/hashicorp-vault-orchestrator/Jobs/JobBase.cs +++ b/hashicorp-vault-orchestrator/Jobs/JobBase.cs @@ -20,21 +20,13 @@ public abstract class JobBase public string ExtensionName => "HCV"; public string StorePath { get; set; } - public string VaultToken { get; set; } - public string ClientMachine { get; set; } - public string VaultServerUrl { get; set; } - public bool SubfolderInventory { get; set; } - public bool IncludeCertChain { get; set; } - public string MountPoint { get; set; } // the mount point of the KV secrets engine. defaults to kv-v2 if not provided. - - public string Namespace { get; set; } // for enterprise editions of vault that utilize namespaces; split from the passed in mount point. "namespace/mountpoint" - + public string Namespace { get; set; } // for enterprise editions of vault that utilize namespaces; split from the passed in mount point if needed. internal protected IHashiClient VaultClient { get; set; } internal protected string _storeType { get; set; } internal protected ILogger logger { get; set; } @@ -103,7 +95,6 @@ public void Initialize(DiscoveryJobConfiguration config) logger.LogTrace($"Directories to search (mount point): {MountPoint}"); logger.LogTrace($"Enterprise Namespace: {Namespace}"); - logger.LogTrace($"Directories to ignore (subpath to search): {subPath}"); InitProps(config.JobProperties, config.Capability); } @@ -112,11 +103,8 @@ public void Initialize(ManagementJobConfiguration config) logger = LogHandler.GetClassLogger(GetType()); ClientMachine = config.CertificateStoreDetails.ClientMachine; - VaultServerUrl = PAMUtilities.ResolvePAMField(PamSecretResolver, logger, "Server UserName", config.ServerUsername); - VaultToken = PAMUtilities.ResolvePAMField(PamSecretResolver, logger, "Server Password", config.ServerPassword); - StorePath = config.CertificateStoreDetails.StorePath; ClientMachine = config.CertificateStoreDetails.ClientMachine; dynamic props = JsonConvert.DeserializeObject(config.CertificateStoreDetails.Properties.ToString()); @@ -141,8 +129,8 @@ private void InitProps(dynamic props, string capability) } var mp = props.ContainsKey("MountPoint") ? props["MountPoint"].ToString() : null; - MountPoint = !string.IsNullOrEmpty(mp) ? mp : MountPoint; + SubfolderInventory = props.ContainsKey("SubfolderInventory") ? bool.Parse(props["SubfolderInventory"].ToString()) : false; IncludeCertChain = props.ContainsKey("IncludeCertChain") ? bool.Parse(props["IncludeCertChain"].ToString()) : false; @@ -156,7 +144,6 @@ private void InitProps(dynamic props, string capability) { VaultClient = new HcvKeyfactorClient(VaultToken, VaultServerUrl, MountPoint, StorePath); } - } } } \ No newline at end of file diff --git a/hashicorp-vault-orchestrator/hashicorp-vault-orchestrator.csproj b/hashicorp-vault-orchestrator/hashicorp-vault-orchestrator.csproj index a7c518b..5da53c4 100644 --- a/hashicorp-vault-orchestrator/hashicorp-vault-orchestrator.csproj +++ b/hashicorp-vault-orchestrator/hashicorp-vault-orchestrator.csproj @@ -1,14 +1,10 @@  - netstandard2.0 + netcoreapp3.1 Keyfactor.Extensions.Orchestrator.HashicorpVault Keyfactor.Extensions.Orchestrator.HCV true - Apache-2.0 - false - - true false @@ -33,10 +29,8 @@ - - - all - + + all @@ -45,13 +39,10 @@ all - - - - all - - - + + + + all diff --git a/images/store_type_fields_pki.png b/images/store_type_fields_pki.png new file mode 100644 index 0000000..e1d8b22 Binary files /dev/null and b/images/store_type_fields_pki.png differ diff --git a/images/store_type_pki.png b/images/store_type_pki.png index ff45833..fa66f47 100644 Binary files a/images/store_type_pki.png and b/images/store_type_pki.png differ diff --git a/integration-manifest.json b/integration-manifest.json index faaee31..aff62e9 100644 --- a/integration-manifest.json +++ b/integration-manifest.json @@ -66,7 +66,7 @@ "DisplayName": "Mount Point", "Type": "String", "DependsOn": "", - "DefaultValue": null, + "DefaultValue": "", "Required": false }, { @@ -74,7 +74,7 @@ "DisplayName": "Server Username", "Type": "Secret", "DependsOn": "", - "DefaultValue": null, + "DefaultValue": "", "Required": false }, { @@ -82,7 +82,7 @@ "DisplayName": "Server Password", "Type": "Secret", "DependsOn": "", - "DefaultValue": null, + "DefaultValue": "", "Required": false }, { @@ -94,7 +94,7 @@ "Required": true } ], - "EntryParameters": null, + "EntryParameters": [], "PasswordOptions": { "EntrySupported": false, "StoreRequired": false, @@ -125,27 +125,11 @@ "DisplayName": "Mount Point", "Type": "String", "DependsOn": "", - "DefaultValue": null, + "DefaultValue": "", "Required": true - }, - { - "Name": "VaultToken", - "DisplayName": "VaultToken", - "Type": "String", - "DependsOn": "", - "DefaultValue": null, - "Required": true - }, - { - "Name": "VaultServerUrl", - "DisplayName": "Vault Server URL", - "Type": "String", - "DependsOn": "", - "DefaultValue": null, - "Required": false } ], - "EntryParameters": null, + "EntryParameters": [], "PasswordOptions": { "EntrySupported": false, "StoreRequired": false, @@ -153,7 +137,7 @@ }, "PrivateKeyAllowed": "Optional", "JobProperties": [], - "ServerRequired": false, + "ServerRequired": true, "PowerShell": false, "BlueprintAllowed": false, "CustomAliasAllowed": "Optional" @@ -192,7 +176,7 @@ "DisplayName": "Mount Point", "Type": "String", "DependsOn": "", - "DefaultValue": null, + "DefaultValue": "", "Required": false }, { @@ -200,7 +184,7 @@ "DisplayName": "Server Username", "Type": "Secret", "DependsOn": "", - "DefaultValue": null, + "DefaultValue": "", "Required": false }, { @@ -208,7 +192,7 @@ "DisplayName": "Server Password", "Type": "Secret", "DependsOn": "", - "DefaultValue": null, + "DefaultValue": "", "Required": false }, { @@ -220,7 +204,7 @@ "Required": true } ], - "EntryParameters": null, + "EntryParameters": [], "PasswordOptions": { "EntrySupported": false, "StoreRequired": false, @@ -261,7 +245,7 @@ "DisplayName": "Mount Point", "Type": "String", "DependsOn": "", - "DefaultValue": null, + "DefaultValue": "", "Required": false }, { @@ -277,7 +261,7 @@ "DisplayName": "Server Username", "Type": "Secret", "DependsOn": "", - "DefaultValue": null, + "DefaultValue": "", "Required": false }, { @@ -285,7 +269,7 @@ "DisplayName": "Server Password", "Type": "Secret", "DependsOn": "", - "DefaultValue": null, + "DefaultValue": "", "Required": false }, { @@ -297,7 +281,7 @@ "Required": true } ], - "EntryParameters": null, + "EntryParameters": [], "PasswordOptions": { "EntrySupported": false, "StoreRequired": false, @@ -346,7 +330,7 @@ "DisplayName": "Mount Point", "Type": "String", "DependsOn": "", - "DefaultValue": null, + "DefaultValue": "", "Required": false }, { @@ -354,7 +338,7 @@ "DisplayName": "Server Username", "Type": "Secret", "DependsOn": "", - "DefaultValue": null, + "DefaultValue": "", "Required": false }, { @@ -362,7 +346,7 @@ "DisplayName": "Server Password", "Type": "Secret", "DependsOn": "", - "DefaultValue": null, + "DefaultValue": "", "Required": false }, { @@ -374,7 +358,7 @@ "Required": true } ], - "EntryParameters": null, + "EntryParameters": [], "PasswordOptions": { "EntrySupported": false, "StoreRequired": false, diff --git a/readme_source.md b/readme_source.md index edc7bdf..c475d82 100644 --- a/readme_source.md +++ b/readme_source.md @@ -1,12 +1,14 @@ -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 -This integration supports 3 Hashicorp Secrets Engines; PKI, Key-Value store, and the Keyfactor Hashicorp Plugin (Keyfactor Secrets Engine). +This integration supports three Hashicorp Secrets Engines; **PKI**, **Key-Value** store, and the **Keyfactor** secrets engine. +The first part of this document describes setting up the store types available within the Hashicorp Vault Key-Value secrets engine. +If you are using the Keyfactor Secrets Engine, or the Hashicorp Vault PKI Secrets Engine, you can skip to [this section](#the-hashicorp-pki-and-keyfactor-plugin-secrets-engines). -### The Key-Value secrets engine +## The Key-Value secrets engine For the Key-Value secrets engine, we have 4 store types that can be used. @@ -17,11 +19,11 @@ For the Key-Value secrets engine, we have 4 store types that can be used. The following operations are supported by this integration for all of the Key-Value secrets engine types: -1. Discovery - Discovery all file repositories for the type -1. Inventory - Inventory all certificates in the path -1. Management (Add) - Add a certificate to a defined certificate store. -1. Management (Remove) - Remove a certificate from a defined certificate store. -1. Create - Create a new, empty certificate store at the path defined in Store Path. +1. **Discovery** - Discovery all file repositories for the type +1. **Inventory** - Inventory all certificates in the path +1. **Management (Add)** - Add a certificate to a defined certificate store. +1. **Management (Remove)** - Remove a certificate from a defined certificate store. +1. **Create** - Create a new, empty certificate store at the path defined in Store Path. Excluding *HCVKVPEM*, the discovery process requires that: 1. The entry for the certificate contain the base64 encoded certificate file. @@ -72,30 +74,17 @@ One way to encode a binary certificate store is to use the following command in `c:\> cat | base64` -### The Hashicorp PKI and Keyfactor Plugin secrets engines +## The Hashicorp PKI and Keyfactor Plugin secrets engines Both the Hashicorp PKI and Keyfactor Secrets Engine plugins are designed to allow managing certifications directly on the Hashicorp Vault instance. The store type for the PKI and/or the Keyfactor secrets engine is the same; `HCVPKI`. This integration supports the following in order to view your certificates from the platform: -1. Inventory - Return all certificates stored in a path. +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 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 path and permissions necessary to perform the intended operations. -1. The capabilities required to perform all operations on a cert store within vault are `["read", "list", "create", "update", "patch", "delete"]` -1. These capabilities should apply to the parent folder on file stores. -1. The token will also need `"list"` capability on the `/metadata` path to perform basic operations. +[View the Hashicorp documentation](https://developer.hashicorp.com/vault/api-docs/secret/pki) for more information on the Hashicorp Vault PKI Secrets Engine ## Extension Configuration @@ -111,7 +100,7 @@ This integration was built on the .NET Core 3.1 target framework and are compati ### In the Keyfactor Platform -#### Add a new Certificate Store Type - **Hashicorp Vault Key-Value PEM** +#### Add the 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" @@ -146,7 +135,7 @@ The 3 highlighted fields above will be added automatically by the platform, you - Click **Save** to save the new Store Type. -#### Add the Hashicorp Vault Certificate Store - **Key-Value Secrets Engine** +#### Add the Certificate Store - Navigate to **Locations** > **Certificate Stores** from the main menu - Click **ADD** to open the new Certificate Store Dialog @@ -165,13 +154,15 @@ In Keyfactor Command create a new Certificate Store that resembles the one below - If your organization utilizes Vault enterprise namespaces, you should include the namespace here. - **Subfolder Inventory** - Set to 'True' if all of the certificates . 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. -#### Set the server name and password +#### Set the server username and password -- The server name should be the full URL to the instance of Vault that will be accessible by the orchestrator. (example: `http://127.0.0.1:8200`) +- The server username should be the full URL to the instance of Vault that will be accessible by the orchestrator. (example: `http://127.0.0.1:8200`) - The server password should be the Vault token that will be used for authenticating. ### For the Keyfactor and PKI plugins +#### Add the Store Type + - 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" @@ -182,6 +173,7 @@ In Keyfactor Command create a new Certificate Store that resembles the one below - **Name:** "Hashicorp Vault PKI" (or another preferred name) - **Short Name:** "HCVPKI" - **Supported Job Types:** "Inventory" +- **Needs Server** - should be checked (true). ![](images/store_type_pki.PNG) @@ -191,12 +183,10 @@ In Keyfactor Command create a new Certificate Store that resembles the one below ![](images/cert-store-type-advanced.png) -- Click the "Custom Fields" tab to add the following custom fields: +- Click the "Custom Fields" tab to add the following field: - **MountPoint** - type: *string* - - **VaultServerUrl** - type: *string*, *required* - - **VaultToken** - type: *secret*, *required* - -![](images/store_type_fields.png) + +![](images/store_type_fields_pki.png) - Click **Save** to save the new Store Type. @@ -205,21 +195,26 @@ In Keyfactor Command create a new Certificate Store that resembles the one below - Navigate to **Locations** > **Certificate Stores** from the main menu - Click **ADD** to open the new Certificate Store Dialog +#### Add the Certificate Store + 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 +- **Client Machine** - Enter an identifier for the client machine. This could be the Orchestrator host name, or anything else useful. This value is not used by the extension. - **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. + - If using the PKI plugin, the default in Hashicorp is "pki". If using the Keyfactor plugin, the default is "keyfactor". - 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 +#### Set the server username and password (values hidden) + +- The **SERVER USERNAME** should be the full URL to the instance of Vault that will be accessible by the orchestrator. (example: `http://127.0.0.1:8200`) +- The **SERVER PASSWORD** should be the Vault token that will be used for authenticating. 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 @@ -262,4 +257,19 @@ At this point you should be able to enroll a certificate and store it in Vault u ## Notes / Future Enhancements +### 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 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 path and permissions necessary to perform the intended operations. +1. The capabilities required to perform all operations on a cert store within vault are `["read", "list", "create", "update", "patch", "delete"]` +1. These capabilities should apply to the parent folder on file stores. +1. The token will also need `"list"` capability on the `/metadata` path to perform basic operations. + - For the Key-Value stores we operate on a single version of the Key Value secret (no versioning capabilities through the Orchesterator Extension / Keyfactor).