From ee09e54d80061e06facaa15bf8742ab69d1b3ddd Mon Sep 17 00:00:00 2001 From: Ryan Treat Date: Thu, 22 Oct 2020 16:25:37 -0700 Subject: [PATCH] Update Venafi Secrets Engine doc to account for recent enhancements (#10221) --- website/pages/docs/secrets/venafi/index.mdx | 71 +++++++++++++++------ 1 file changed, 53 insertions(+), 18 deletions(-) diff --git a/website/pages/docs/secrets/venafi/index.mdx b/website/pages/docs/secrets/venafi/index.mdx index 670a19db16..40f6f177b8 100644 --- a/website/pages/docs/secrets/venafi/index.mdx +++ b/website/pages/docs/secrets/venafi/index.mdx @@ -47,7 +47,10 @@ requirements. Within Trust Protection Platform, configure these settings. For more information see the _Venafi Administration Guide_. -- A user account that has been granted REST API (WebSDK) access. +- A user account that has an authentication token for the "Venafi Secrets + Engine for HashiCorp Vault" (ID "hashicorp-vault-by-venafi") API Application + as of 20.1 (or scope "certificate:manage" for 19.2 through 19.4) or has been + granted WebSDK Access (deprecated) - A Policy folder where the user has the following permissions: View, Read, Write, Create. - Enterprise compliant policies applied to the folder including: @@ -129,19 +132,19 @@ Venafi secrets engine: 1. Start your Vault using the [server command](/docs/commands/server). -1. Get the SHA-256 checksum of the `vault-pki-backend-venafi` plugin binary: +1. Get the SHA-256 checksum of the `venafi-pki-backend` plugin binary: ```text $ SHA256=$(sha256sum /etc/vault/vault_plugins/venafi-pki-backend| cut -d' ' -f1) ``` -1. Register the `vault-pki-backend-venafi` plugin in the Vault +1. Register the `venafi-pki-backend` plugin in the Vault [system catalog](/docs/internals/plugins#plugin-catalog): ```text $ vault write sys/plugins/catalog/secret/venafi-pki-backend \ sha_256="${SHA256}" command="venafi-pki-backend" - Success! Data written to: sys/plugins/catalog/secret/pki-backend-venafi + Success! Data written to: sys/plugins/catalog/secret/venafi-pki-backend ``` 1. Enable the Venafi secrets engine: @@ -151,22 +154,51 @@ Venafi secrets engine: Success! Enabled the pki-backend-venafi secrets engine at: venafi-pki/ ``` -1. Configure a [role](/docs/secrets/pki) - that maps a name in Vault to a procedure for enrolling certificate using Venafi. - The `zone` is a policy folder for Trust Protection Platform or a DevOps project - zone for Venafi Cloud. Avoid setting both `store_by_serial` and `store_by_cn` - to true. To see other available options for the role after it is created, use - `vault path-help venafi-pki/roles/:name`. +1. Configure a Venafi secret that maps a name in Vault to connection and authentication + settings for enrolling certificate using Venafi. The zone is a policy folder for Trust + Protection Platform or a DevOps project zone for Venafi Cloud. + + Obtain the `access_token` and `refresh_token` for Trust Protection Platform using the + [VCert CLI](https://github.com/Venafi/vcert/blob/master/README-CLI-PLATFORM.md#obtaining-an-authorization-token) + (`getcred` action with `--client-id "hashicorp-vault-by-venafi"` and + `--scope "certificate:manage"`) or the Platform's Authorize REST API method. + + To see all options available for venafi secrets, use + `vault path-help venafi-pki/venafi/:name` after creating the secret. + + **Trust Protection Platform**: + + ``` + $ vault write venafi-pki/venafi/tpp \ + url="https://tpp.venafi.example" \ + access_token="tn1PwE1QTZorXmvnTowSyA==" \ + refresh_token="MGxV7DzNnclQi9CkJMCXCg==" \ + zone="DevOps\\HashiCorp Vault" \ + trust_bundle_file="/path-to/bundle.pem" + Success! Data written to: venafi-pki/venafi/tpp + ``` + + **Venafi Cloud**: + + ``` + $ vault write venafi-pki/venafi/cloud \ + apikey="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \ + zone="zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz" + Success! Data written to: venafi-pki/roles/cloud + ``` + +1. Lastly, configure a [role](/docs/secrets/pki) + that maps a name in Vault to a Venafi secret for enrollment. To see all + options available for roles, including `ttl`, `max_ttl` and `issuer_hint` + (for validity), use `vault path-help venafi-pki/roles/:name` after + creating the role. **Trust Protection Platform**: ```text $ vault write venafi-pki/roles/tpp \ - tpp_url="https://tpp.venafi.example/vedsdk" \ - tpp_user="local:admin" tpp_password="password" \ - zone="DevOps\\HashiCorp Vault" \ - trust_bundle_file="/opt/venafi/bundle.pem" \ - generate_lease=true store_by_serial=true store_pkey=true \ + venafi_secret=tpp \ + store_by=serial store_pkey=true \ allowed_domains=example.com \ allow_subdomains=true Success! Data written to: venafi-pki/roles/tpp @@ -176,9 +208,8 @@ Venafi secrets engine: ```text $ vault write venafi-pki/roles/cloud \ - apikey="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \ - zone="zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz" \ - generate_lease=true store_by_serial=true store_pkey=true \ + venafi_secret=cloud \ + store_by=serial store_pkey=true \ allowed_domains=example.com \ allow_subdomains=true Success! Data written to: venafi-pki/roles/cloud @@ -188,6 +219,10 @@ Venafi secrets engine: After the Venafi secrets engine is configured and a user/machine has a Vault token with the proper permission, it can enroll certificates using Venafi. +To see all of the options available when requesting a certificate, including +`ttl` (for validity), `key_password`, and `custom_fields`, use +`vault path-help venafi-pki/issue/:role-name` and +`vault path-help venafi-pki/sign/:role-name`. 1. Generate a certificate by writing to the `/issue` endpoint with the name of the role: