This open source project is community-supported. To report a problem or share an idea, use
Issues; and if you have a suggestion for fixing the issue, please include those details, too.
In addition, use Pull Requests to contribute actual bug fixes or proposed enhancements.
We welcome and appreciate all contributions. Got questions or want to discuss something with our team?
Join us on Slack!
This solution enables HashiCorp Vault users to have certificate requests fulfilled by the Venafi Trust Protection Platform or Venafi as a Service ensuring compliance with corporate security policy and providing visibility into certificate issuance enterprise wide.
Your certificate authority (CA) must be able to issue a certificate in under one minute. Microsoft Active Directory Certificate Services (ADCS) is a popular choice. Other CA choices may have slightly different requirements.
Within Trust Protection Platform, configure these settings. For more information see the Venafi Administration Guide.
-
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:
- Subject DN values for Organizational Unit (OU), Organization (O), City/Locality (L), State/Province (ST) and Country (C).
- CA Template that Trust Protection Platform will use to enroll general certificate requests.
- Management Type not locked or locked to 'Enrollment'.
- Certificate Signing Request (CSR) Generation unlocked or not locked to 'Service Generated CSR'.
- Generate Key/CSR on Application not locked or locked to 'No'.
- (Recommended) Disable Automatic Renewal set to 'Yes'.
- (Recommended) Key Bit Strength set to 2048 or higher.
- (Recommended) Domain Whitelisting policy appropriately assigned.
NOTE: If you are using Microsoft ACDS, the CRL distribution point and Authority Information Access (AIA) URIs must start with an HTTP URI (non-default configuration). If an LDAP URI appears first in the X509v3 extensions, some applications will fail, such as NGINX ingress controllers. These applications aren't able to retrieve CRL and OCSP information.
The Trust Protection Platform REST API (WebSDK) must be secured with a certificate. Generally, the certificate is issued by a CA that is not publicly trusted so establishing trust is a critical part of your setup.
Two methods can be used to establish trust. Both require the trust anchor
(root CA certificate) of the WebSDK certificate. If you have administrative
access, you can import the root certificate into the trust store for your
operating system. If you don't have administrative access, or prefer not to
make changes to your system configuration, save the root certificate to a file
in PEM format (e.g. /opt/venafi/bundle.pem) and reference it using the
trust_bundle_file parameter whenever you create or update a PKI role in your
Vault.
If you are using Venafi as a Service, verify the following:
- The Venafi as a Service REST API at https://api.venafi.cloud or https://api.venafi.eu (if you have an EU account) is accessible from the systems where Vault will be running.
- You have successfully registered for a Venafi as a Service account, have been granted at least the "Resource Owner" role, and know your API key.
- A CA Account and Issuing Template exist and have been configured with:
- Recommended Settings values for:
- Organizational Unit (OU)
- Organization (O)
- City/Locality (L)
- State/Province (ST)
- Country (C)
- Issuing Rules that:
- (Recommended) Limits Common Name and Subject Alternative Name to domains that are allowed by your organization
- (Recommended) Restricts the Key Length to 2048 or higher
- (Recommended) Does not allow Private Key Reuse
- Recommended Settings values for:
- An Application exists where you are among the owners, and you know the Application name.
- An Issuing Template is assigned to the Application, and you know its API Alias.
Before certificates can be issued, you must complete these steps to configure the Venafi secrets engine:
-
Create the directory where your Vault server will look for plugins (e.g. /etc/vault/vault_plugins). The directory must not be a symbolic link. On macOS, for example, /etc is a link to /private/etc. To avoid errors, choose an alternative directory such as /private/etc/vault/vault_plugins.
-
Download the latest
vault-pki-backend-venafirelease package for your operating system. Unzip the binary to the plugin directory. Note that the URL for the zip file, referenced below, changes as new versions of the plugin are released.$ wget https://github.com/Venafi/vault-pki-backend-venafi/releases/download/v0.0.1/venafi-pki-backend_v0.0.1+1_linux.zip $ unzip venafi-pki-backend_v0.0.1+1_linux.zip $ mv venafi-pki-backend /etc/vault/vault_plugins📌 NOTE: Release binaries are built and tested using the latest generally available version of Vault at the time. Backward compatibility with older versions of Vault is typical but not confirmed by testing.
-
Update the Vault server configuration to specify the plugin directory:
plugin_directory = "/etc/vault/vault_plugins"📌 NOTE: If plugin directory is a symbolic link, Vault responds with an error🔖. If you're configuring on a MacBook, /etc is default symlinked to /private/etc. To prevent the error from occurring, change the
plugin_directoryto a non-symlinked directory. For example "/private/etc/vault/vault_plugins". If you make this change, keep it in mind as you go through the remaining steps. -
Start your Vault using the server command.
-
Get the SHA-256 checksum of the
venafi-pki-backendplugin binary:SHA256=$(sha256sum /etc/vault/vault_plugins/venafi-pki-backend| cut -d' ' -f1) -
Register the
venafi-pki-backendplugin in the Vault system catalog:vault write sys/plugins/catalog/secret/venafi-pki-backend \ sha_256="${SHA256}" command="venafi-pki-backend"Expected output:
Success! Data written to: sys/plugins/catalog/secret/venafi-pki-backend📌 NOTE: If you get an error that says "can not execute files outside of configured plugin directory", it's probably because you didn't set the plugin directory correctly with a non-symlinked directory as mentioned earlier. Also, make sure this change is reflected when calling for the SHA-256 checksum.
-
Enable the Venafi secrets engine:
vault secrets enable -path=venafi-pki -plugin-name=venafi-pki-backend pluginExpected output:
Success! Enabled the pki-backend-venafi secrets engine at: venafi-pki/ -
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 an Application name and Issuing Template API Alias (e.g. "Business App\Enterprise CIT") for Venafi as a Service. Obtain the
access_tokenand (optional) bootstrap two refresh tokens forrefresh_tokenandrefresh_token_2for Trust Protection Platform using the VCert CLI (getcredaction with--client-id "hashicorp-vault-by-venafi"and--scope "certificate:manage") or the Platform's Authorize REST API method. To see other available options for the Venafi secret after it is created, usevault path-help venafi-pki/venafi/:name.📌 NOTE: When obtaining a
access_tokenandrefresh_tokenfrom Trust Protection Platform, make sure you use the same client id when configuring the Venafi secret in Vault. Default theclient_idis set to "hashicorp-vault-by-venafi".Trust Protection Platform:
vault write venafi-pki/venafi/tpp \ url="https://tpp.venafi.example" \ access_token="tn1PwE1QTZorXmvnTowSyA==" \ refresh_token="MGxV7DzNnclQi9CkJMCXCg==" \ refresh_token_2="p0WTt3sDPbzm2BDIkoJROQ==" \ zone="DevOps\\HashiCorp Vault" \ trust_bundle_file="/opt/venafi/bundle.pem"Expected output:
Success! Data written to: venafi-pki/venafi/tppIn order to set the refresh tokens you will need to get two token key pair. For example, you can execute
vcert getcredcommand twice as follows:$ vcert getcred ... OUTPUT: vCert: 2023/01/21 12:05:30 Getting credentials... access_token: access_token_1 access_token_expires: ... refresh_token: refresh_token_1 refresh_until: ...Then one more time:
$ vcert getcred ... OUTPUT: vCert: 2023/01/21 12:05:32 Getting credentials... access_token: access_token_2 access_token_expires: ... refresh_token: refresh_token_2 refresh_until: ...Now set 1st pair of
access_tokenandrefresh_tokenand from 2nd pair, set only the secondrefresh_token_2parameter as follows: (access_token_1andaccess_token_2are NOT interchangeable):vault write venafi-pki/venafi/tpp \ url="https://tpp.venafi.example" \ access_token=access_token_1 \ refresh_token=refresh_token_1 \ refresh_token_2=refresh_token_2 \ zone="DevOps\\HashiCorp Vault" \ trust_bundle_file="/opt/venafi/bundle.pem"Expected output:
Success! Data written to: venafi-pki/venafi/tpp📌 NOTE: You can also specify a
refresh_intervalfor the Venafi secret which represents the frequency at which secrets engine should refresh tokens. We default it to 30 days, but internally we validate it to be not longer than theaccess_tokenis valid. Generally,refresh_intervalshould not be more than half the token validity; example withaccess_tokenwith validity of 1 day:vault write venafi-pki/venafi/tpp \ url="https://tpp.venafi.example" \ access_token="tn1PwE1QTZorXmvnTowSyA==" \ refresh_token="MGxV7DzNnclQi9CkJMCXCg==" \ refresh_token_2="p0WTt3sDPbzm2BDIkoJROQ==" \ refresh_interval="12h" \ zone="DevOps\\HashiCorp Vault" \ trust_bundle_file="/opt/venafi/bundle.pem"Expected output:
Success! Data written to: venafi-pki/venafi/tpp⚠️ CAUTION: Do not create more than one Venafi secret for the same set of tokens. Supplying arefresh_tokenandrefresh_token_2(both must be set) allows the secrets engine to automatically obtain new tokens and operate without interruption whenever theaccess_tokenexpires.This behavior is important to understand because it may require you to provide a new
access_token,refresh_tokenandrefresh_token_2if you need to modify the Venafi secret in the future (i.e. depending upon whether the original set of tokens has been refreshed by the secrets engine plugin). Having more than one Venafi secret for the same set of tokens would result in all but one Venafi secret being rendered inoperable when the token is refreshed.Venafi as a Service:
vault write venafi-pki/venafi/vaas \ apikey="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \ zone="Business App\\Enterprise CIT"Expected output:
Success! Data written to: venafi-pki/roles/vaasVenafi as a Service EU:
vault write venafi-pki/venafi/vaas \ url="https://api.venafi.eu" \ apikey="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \ zone="Business App\\Enterprise CIT"Expected output:
Success! Data written to: venafi-pki/roles/vaas -
Lastly, configure a role that maps a name in Vault to a Venafi secret for enrollment. To see other available options for the role after it is created, use
vault path-help venafi-pki/roles/:name.Trust Protection Platform:
vault write venafi-pki/roles/tpp \ venafi_secret=tpp \ generate_lease=true store_by=serial store_pkey=trueExpected output:
Success! Data written to: venafi-pki/roles/tppVenafi as a Service:
vault write venafi-pki/roles/vaas \ venafi_secret=vaas \ generate_lease=true store_by=serial store_pkey=trueExpected output:
Success! Data written to: venafi-pki/roles/vaas📌 NOTE: The
ttlandmax_ttlrole parameters can be used specify the default and maximum allowed validity for certificate requests if the Venafi CA template supports flexible validity periods. If the CA is DigiCert, Entrust, or Microsoft with Trust Protection Platform, theissuer_hintparameter is also required forttlfunctionality (e.g.issuer_hint="m"for Microsoft). When issue or sign operations include thettlparameter it overrides the role defaultttland will be constrained by the rolemax_ttl.📌 NOTE: The
zonerole parameter allows multiple zones to be used with a single Venafi secret. Ifzoneis not specified by the role, thezonespecified by the Venafi secret applies.📌 NOTE: Starting version 0.13.0, you can use
server_timeoutin order to overwrite timeout to perform an enrollment request. Default is 180 seconds. Applicable to both TLSPDC (TPP) and TLSPC (VaaS). This attribute will have the following behaviors for TLSPDC and TLSPC:- TLSPDC: During enrollment, http client timeout will use the defined value of
server_timeoutfor every request. Also it will be used for TPP request attributeWorkToDoTimeoutwhich will override the waiting for set CA's in Policy to finish issuance. - TLSPC: During enrollment, http client timeout will use the defined value of
server_timeoutfor every request. Also it will be used for inner VCert retry logic to pickup certificate (as moment of adding this information 180 secs)
Example usage:
vault write venafi-pki/roles/tpp \ venafi_secret=tpp \ server_timeout="200s"Expected output:
Success! Data written to: venafi-pki/roles/tpp - TLSPDC: During enrollment, http client timeout will use the defined value of
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.
-
Generate a certificate by writing to the
/issueendpoint with the name of the role (add thekey_passwordparameter to get a password encrypted private key in the output):Trust Protection Platform:
vault write venafi-pki/issue/tpp common_name="common-name.example.com" \ alt_names="dns-san-1.example.com,dns-san-2.example.com"
Expected output:
Key Value --- ----- lease_id venafi-pki/issue/tpp/oLih42SCFzyjntxGc00vqmWH lease_duration 719h49m55s lease_renewable false certificate -----BEGIN CERTIFICATE----- certificate_chain -----BEGIN CERTIFICATE----- common_name common-name.example.com private_key -----BEGIN RSA PRIVATE KEY----- serial_number 1d:bc:a8:3c:00:00:00:05:5c:e8Venafi as a Service:
vault write venafi-pki/issue/vaas common_name="common-name.example.com" \ alt_names="dns-san-1.example.com,dns-san-2.example.com"
Expected output:
Key Value --- ----- lease_id venafi-pki/issue/vaas/1WCNvXKiwboWfRRfjzlPAwEi lease_duration 167h59m58s lease_renewable false certificate -----BEGIN CERTIFICATE----- certificate_chain -----BEGIN CERTIFICATE----- common_name common-name.example.com private_key -----BEGIN RSA PRIVATE KEY----- serial_number 17:47:8b:13:90:b8:3d:87:b0:dc:b6:9e:00:2b:87:02:c9:d3:1e:8a -
Or sign a CSR from a file by writing to the
/signendpoint with the name of the role:Trust Protection Platform:
vault write venafi-pki/sign/tpp [email protected]
Expected output:
Key Value --- ----- lease_id venafi-pki/sign/tpp/tQq3QNY45e4sJMqTTI9DXEGK lease_duration 719h49m57s lease_renewable false certificate -----BEGIN CERTIFICATE----- certificate_chain -----BEGIN CERTIFICATE----- common_name common-name.example.com serial_number 1d:c4:07:9a:00:00:00:05:5c:eaVenafi as a Service:
vault write venafi-pki/sign/vaas [email protected]
Expected output:
Key Value --- ----- lease_id venafi-pki/sign/vaas/fF44FdMAjuCdC29w3Ff81hes lease_duration 167h59m58s lease_renewable false certificate -----BEGIN CERTIFICATE----- certificate_chain -----BEGIN CERTIFICATE----- common_name common-name.example.com serial_number 76:55:e2:14:de:c8:3f:e1:64:4a:fa:37:d4:6e:f5:ef:5e:4c:16:5b
Custom Fields can be set when requesting certificates from Trust Protection
Platform using the custom_fields parameter (e.g.
custom_fields="field1_name=valueX,field2_name=valueY,field2_name=valueZ").
If you would like to insert commas within the values (assuming the Custom Field is type of string,
you would need to provide them as the following:
Vault CLI
vault write venafi-pki/sign/tpp csr="-----BEGIN CERTIFICATE REQUEST-----
MIICeTCCAWECAQAwGDEWMBQGA1UEAxMNbHVpcy50ZXN0LmNvbTCCASIwDQYJKoZI
...
+MuJtq1+tKhPdHo36v1qMDUEC7StRnoI0BMK0YzPP17BCdXBo9JHgoS08vaUisd7
OZPoXsqUv7B4eYKjuQ==
-----END CERTIFICATE REQUEST-----"
custom_fields="field1_name=valueX,valueY,valueZ" custom_fields="field2_name=valueA" custom_fields="field2_name=valueB"Vault API
vault write venafi-pki/sign/tpp csr="-----BEGIN CERTIFICATE REQUEST-----
MIICeTCCAWECAQAwGDEWMBQGA1UEAxMNbHVpcy50ZXN0LmNvbTCCASIwDQYJKoZI
...
+MuJtq1+tKhPdHo36v1qMDUEC7StRnoI0BMK0YzPP17BCdXBo9JHgoS08vaUisd7
OZPoXsqUv7B4eYKjuQ==
custom_fields="field1_name=valueX,valueY,valueZ" custom_fields="field2_name=valueA" custom_fields="field2_name=valueB"Where our Custom Fields in TLSPDC are:
- field1_name:
String - field2_name:
List Type (MultiSelect)
Notice we didn't use commas in field2_name since in our server the value is fixed for valueA which doesn't
include commas, unlike field1_name which is defined as string type.
Venafi Machine Identity Secrets Engine uses the same Vault API as the built-in PKI secrets engine. Some methods, such as those for managing certificate authorities, do not apply.
To upgrade to a new version of this plugin, review the release notes to understand the impact and then follow the standard procedure. The following command will trigger a plugin reload globally:
vault write sys/plugins/reload/backend plugin=venafi-pki-backend scope=globalExpected output:
Key Value
--- -----
reload_id d8180af4-01e0-d4d8-10ce-0daf69fbb6ed
In order to prevent an issuance of a new certificate if current certificate exists in Vault's storage, we added a capability to return that certificate instead. We rely on Venafi's platforms (TPP/VaaS) to find out is certificate already exist. To issue this feature you must set:
min_cert_time_left(optional): Golang's duration format string (e.g. 24h, 23h5m20s, 10000s, etc.). Default is 30 days.store_by="serial"(required)store_pkey=true(required)
If certificate was successfully loaded from Vault storage, you will encounter Loading certificate from storage message
in logs when [DEBUG] mode is set:
2022-08-30T13:41:49.007-0500 [DEBUG] secrets.venafi-pki-backend.venafi-pki-backend_5df77702.venafi-pki-backend.venafi-pki-backend: Loading certificate from storage: timestamp=2022-08-30T13:41:49.006-0500
2022-08-30T13:41:49.008-0500 [DEBUG] secrets.venafi-pki-backend.venafi-pki-backend_5df77702.venafi-pki-backend.venafi-pki-backend: Getting venafi certificate: timestamp=2022-08-30T13:41:49.008-0500
2022-08-30T13:41:49.010-0500 [DEBUG] secrets.venafi-pki-backend.venafi-pki-backend_5df77702.venafi-pki-backend.venafi-pki-backend: certificate is:-----BEGIN CERTIFICATE-----
MIIHvjCCBaagAwIBAgITbQCpUfV8kBfjsOaP8QAAAKlR9TANBgkqhkiG9w0BAQsF
ADBbMRMwEQYKCZImiZPyLGQBGRYDY29tMRYwFAYKCZImiZPyLGQBGRYGdmVuYWZp
MRUwEwYKCZImiZPyLGQBGRYFdmVucWExFTATBgNVBAMTDFFBIFZlbmFmaSBDQTAe
Fw0yMjA4MzAxODMxNDNaFw0yNDA4MjkxODMxNDNaMIHAMQswCQYDVQQGEwJVUzEN
MAsGA1UECBMEVXRhaDEXMBUGA1UEBxMOU2FsdCBMYWtlIENpdHkxFDASBgNVBAoT
C1ZlbmFmaSBJbmMuMRQwEgYDVQQLEwtFbmdpbmVlcmluZzEbMBkGA1UECxMSUHJv
ZHVjdCBNYW5hZ2VtZW50MRowGAYDVQQLExFRdWFsaXR5IEFzc3VyYW5jZTEkMCIG
A1UEAxMbbm9wcml2YXRla2V5LnZlbmFmaS5leGFtcGxlMIIBIjANBgkqhkiG9w0B
We enabled capability to store certificates by hash. The hash is generated by:
Common Name + SAN DNS + Zone
It's required to set any of (at least one): Common Name or SAN DNS.
In order to prevent an issuance of a new certificate if current certificate exists in Vault's storage, we added a capability to return that certificate instead. We rely on hash in order to get certificate from local storage (no TPP/VaaS is involved). To issue this feature you must set:
min_cert_time_left(optional): Golang's duration format string (e.g. 24h, 23h5m20s, 10000s, etc.). Default is 30 days.store_by="hash"(required)store_pkey=true(required)
If certificate was successfully loaded from Vault storage, you will encounter Loading certificate from storage message
in logs when [DEBUG] mode is set:
2022-08-30T13:41:49.007-0500 [DEBUG] secrets.venafi-pki-backend.venafi-pki-backend_5df77702.venafi-pki-backend.venafi-pki-backend: Loading certificate from storage: timestamp=2022-08-30T13:41:49.006-0500
2022-08-30T13:41:49.008-0500 [DEBUG] secrets.venafi-pki-backend.venafi-pki-backend_5df77702.venafi-pki-backend.venafi-pki-backend: Getting venafi certificate: timestamp=2022-08-30T13:41:49.008-0500
2022-08-30T13:41:49.010-0500 [DEBUG] secrets.venafi-pki-backend.venafi-pki-backend_5df77702.venafi-pki-backend.venafi-pki-backend: certificate is:-----BEGIN CERTIFICATE-----
MIIHvjCCBaagAwIBAgITbQCpUfV8kBfjsOaP8QAAAKlR9TANBgkqhkiG9w0BAQsF
ADBbMRMwEQYKCZImiZPyLGQBGRYDY29tMRYwFAYKCZImiZPyLGQBGRYGdmVuYWZp
MRUwEwYKCZImiZPyLGQBGRYFdmVucWExFTATBgNVBAMTDFFBIFZlbmFmaSBDQTAe
Fw0yMjA4MzAxODMxNDNaFw0yNDA4MjkxODMxNDNaMIHAMQswCQYDVQQGEwJVUzEN
MAsGA1UECBMEVXRhaDEXMBUGA1UEBxMOU2FsdCBMYWtlIENpdHkxFDASBgNVBAoT
C1ZlbmFmaSBJbmMuMRQwEgYDVQQLEwtFbmdpbmVlcmluZzEbMBkGA1UECxMSUHJv
ZHVjdCBNYW5hZ2VtZW50MRowGAYDVQQLExFRdWFsaXR5IEFzc3VyYW5jZTEkMCIG
A1UEAxMbbm9wcml2YXRla2V5LnZlbmFmaS5leGFtcGxlMIIBIjANBgkqhkiG9w0B
If certificates are stored locally in vault by serial or hash, normal behavior would be to always look into certificate locally before issuing a new certificate.
If ignore_local_storage flag is set to true, it would bypass the logic to check certificate locally (to prevent re-issue) and always issue a new certificate.
Default value is always false.
Copyright © Venafi, Inc. All rights reserved.
This solution is licensed under the Mozilla Public License, Version 2.0. See LICENSE for the full license text.
Please direct questions/comments to [email protected].
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
