Skip to content

Commit

Permalink
Update generated README
Browse files Browse the repository at this point in the history
  • Loading branch information
Keyfactor committed Nov 22, 2024
1 parent 97d863f commit 53bb02a
Showing 1 changed file with 39 additions and 34 deletions.
73 changes: 39 additions & 34 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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|✓ |✓ |


Expand All @@ -56,7 +56,7 @@ This integration for the Keyfactor Universal Orchestrator has been tested agains

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 Key-Value secrets engine

For the Key-Value secrets engine, we have 4 store types that can be used.

Expand All @@ -67,11 +67,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.
Expand Down Expand Up @@ -122,30 +122,16 @@ One way to encode a binary certificate store is to use the following command in

`c:\> cat <cert store file path> | 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 `<mount point>/metadata` path to perform basic operations.

## Extension Configuration

Expand Down Expand Up @@ -215,9 +201,9 @@ 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
Expand All @@ -232,6 +218,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)

Expand All @@ -241,12 +228,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.

Expand All @@ -259,14 +244,16 @@ 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.

Expand Down Expand Up @@ -312,5 +299,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 `<mount point>/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


0 comments on commit 53bb02a

Please sign in to comment.