Creating a HashiCorp Vault CA connector¶

This topic explains how to set up a HashiCorp Vault certificate authority (CA) connector in Certificate Manager - SaaS using the Venafi CA Connector Framework. The connector issues, renews, revokes, and imports certificates through a single PKI secrets engine mount in HashiCorp Vault Community Edition, Vault Enterprise, or HCP Vault.

Each PKI role in the mount appears as a product in Certificate Manager - SaaS, so your request policies issue certificates under the constraints you've already set on your Vault roles.

Before you begin¶

Before you set up the CA connector, you'll need:

• A deployed VSatellite that can resolve and reach your Vault server over HTTPS. Vault doesn't need to be reachable from the internet.
• Your HashiCorp Vault CA connector must already be deployed to Certificate Manager - SaaS using the Dev Central API. It won't appear in the Certificate Authority Type list until it has been deployed.

As a Vault administrator, prepare the following:

• A PKI secrets engine mount with at least one role that Certificate Manager - SaaS can issue with. Set no_store=false on those roles. Certificates from a no_store role aren't stored in Vault, so Certificate Manager - SaaS can't import, check, or revoke them.
• A Vault policy for the connector. See Write the Vault policy.
• Credentials bound to that policy, using one of these methods:
  • AppRole (recommended). A role ID and secret ID for an AppRole whose token policies include the connector's policy. AppRole issues short-lived tokens, and the connector revokes its login token at the end of every operation. Keep the AppRole's token TTL short. For details, see AppRole auth method in the HashiCorp documentation.
  • Token. A Vault token that carries the connector's policy and has a TTL. Don't use a root token. The connector never renews a direct token, so when the token expires, the connection fails until you replace it.
• For Vault Enterprise or HCP Vault, the namespace that contains the PKI mount.
• (Optional) The CA certificate that signed the Vault server's TLS certificate, in PEM format. You need this only if Vault's TLS certificate is issued by a private or internal CA.

Write the Vault policy¶

The connector needs the following capabilities on the PKI mount. In this example, the mount is pki and the role made for the connector is clm. Replace both with your own names.

path "pki/roles"              { capabilities = ["list"] }
path "pki/roles/clm"          { capabilities = ["read"] }
path "pki/certs"              { capabilities = ["list"] }
path "pki/certs/revoked"      { capabilities = ["list"] }
path "pki/sign/clm"           { capabilities = ["update"] }
path "pki/issuer/+/sign/clm"  { capabilities = ["update"] }
path "pki/revoke"             { capabilities = ["update"] }
path "pki/crl/rotate"         { capabilities = ["read"] }
path "pki/cert-metadata/*"    { capabilities = ["read"] }  # Vault Enterprise only, for renewing imported certificates

Keep the following in mind when you write the policy:

• Signing needs update, not create. Vault treats every request to the sign paths as an update, so a policy that grants only create is denied.
• Scope sign to the roles made for the connector, rather than pki/sign/*. Anyone who holds the connector's credentials can sign any certificate those roles allow. Constrain each role's allowed domains, SAN types, maximum TTL, and key usage flags to what Certificate Manager - SaaS needs.
• Don't add grants for pki/cert/* or pki/issuer/*. The connector also reads stored certificates and issuers, but Vault serves those paths without authentication.

When you click Test Connection, Certificate Manager - SaaS checks the capabilities the connector needs to issue, import, and revoke certificates, and names the first one that's missing. It doesn't check pki/crl/rotate or pki/cert-metadata/*, so a policy without those still passes.

Create a HashiCorp Vault CA connector in Certificate Manager - SaaS¶

Before you complete these steps, review Create a custom CA connector, including the prerequisites and notes.

1. Sign in to Certificate Manager - SaaS.

2. Click Integrations > Certificate Authorities.

3. Click New > Add Certificate Authority connector.

4. Under Connection, add the following.

   1. Enter a Name for the CA connector to use as its display name.

   2. Select HashiCorp Vault CA as the Certificate Authority Type.

      Note

      Your custom CA won't appear in this list until you have deployed your custom CA connector using the Dev Central API.

   3. Select the VSatellite that can resolve and reach your Vault server.

   4. Click Next.

5. Under Information, add the connection details for your Vault server.

   1. Enter the Vault server URL.

      This is the address of the Vault server, without the /v1 suffix. For example, https://vault.example.com:8200.

      Important

      The URL must begin with https://. Certificate Manager - SaaS rejects an http:// URL, because the connector sends the Vault token or secret ID with every request.

   2. Select the Authentication method:

      • Token (default)
      • AppRole

   3. If you selected AppRole, enter the AppRole mount path (optional).

      This is the path the AppRole auth method is mounted at. If you leave it empty, the connector uses approle.

   4. Enter the PKI mount path.

      This is the path the PKI secrets engine is mounted at, for example pki or pki_int. The default is pki. Nested paths such as team/pki are supported. A path can contain only letters, digits, underscores (_), hyphens (-), periods (.), and forward slashes (/).

   5. (Optional) Enter the Namespace.

      This is the Vault Enterprise or HCP Vault namespace that contains the PKI mount. The connector applies it to every request. Leave it empty for Vault Community Edition.

   6. (Optional) Paste the CA certificate.

      These are one or more PEM certificates to trust for the Vault server's TLS certificate, in addition to the system trust store. Include each full -----BEGIN CERTIFICATE----- block. The connector always verifies the Vault server's certificate, and there's no option to skip verification.

   7. (Optional) Enter the Renewal window (days).

      Certificates that expire within this many days are renewed; others are reissued. Enter a value from 1 through 397. If you leave the field empty, Certificate Manager - SaaS uses 32 days. For more information, see Reissuance. With Vault, renewal and reissuance make the same request. See What to expect from HashiCorp Vault.

   8. Enter the credentials for the authentication method you selected:

      • Token: Enter the Vault token. This is a token whose policy allows the PKI operations the connector uses.
      • AppRole: Enter the Role ID and the Secret ID of the AppRole.

      Warning

      Remember to store your username and password securely when creating a new machine. For security reasons, you will not be able to modify the fields under the "Access" tab without these credentials. This ensures that only authorized individuals can modify these fields.

   9. Click Test Connection.

      A successful test confirms that the VSatellite can reach Vault, that the credentials are valid, that the PKI mount exists, and that the token can issue with at least one role in the mount. If a capability is missing, the error message names it. If the connection isn't successful, resolve all issues and ensure you have a successful connection before continuing. For help, see Connection issues.

   10. Click Next.

6. Under Issuance, set the following options.

   1. In Product Options, choose the products you want to make available to request policies, and then click Add. To add every product, choose All product options.

      The list shows one product for each PKI role in the mount, named after the role. If the token can't read a role, that role doesn't appear, but the others still do.

   2. Click Next.

7. (Optional) Under Import, set the following options to configure certificate import.

   1. In Product Options, choose the product named after your PKI mount path, for example pki, and then click Add.

      This connector offers a single import product, which covers every certificate stored in the PKI mount. Its description is Import certificates from PKI mount followed by the mount path.

   2. Under Import options, set the following:

      • To import certificates that have already expired, turn on Include expired certificates. This option is off by default.
      • To import certificates that have been revoked in Vault, turn on Include revoked certificates. This option is off by default.
   3. To schedule certificate import, enable Scheduled import and choose a schedule.

8. Click Create. The new HashiCorp Vault CA appears on the Certificate Authorities page.

Set the issuance options on your request policy¶

The HashiCorp Vault CA connector adds the following fields to every request policy that uses this CA connector:

• Issuer - The ID or name of the issuer in the PKI mount to sign with. If you leave it empty, the role's default issuer signs. This is useful during a CA rotation, when the mount has more than one issuer.
• Exclude common name from SANs - Doesn't add the common name to the certificate's subject alternative names (SANs). This option is off by default.
• Remove roots from chain - Leaves self-signed root certificates out of the returned chain. This option is off by default.

If the role or issuer is later deleted or renamed in Vault, the request policy fails validation. Update the request policy, or re-create the role or issuer in Vault.

For the remaining settings, see Create a request policy.

What to expect from HashiCorp Vault¶

• Issuance is immediate. Vault returns the signed certificate and its CA chain in the same response, so a request never waits in a pending state.
• Every request needs a common name. Vault requires a common name in the certificate signing request (CSR). A request with only SANs fails.
• Validity is capped by Vault, not rejected. If you request a validity longer than the role's maximum TTL, or the mount's maximum when the role has none, Vault issues the certificate with the maximum instead. The certificate shows its real expiration date.
• Renewal and reissuance sign a new CSR. Vault has no renewal operation. For a certificate issued through Certificate Manager - SaaS, both renewal and reissuance sign the new CSR with the role that issued the original certificate, through the issuer that signed it. The Exclude common name from SANs and Remove roots from chain settings aren't part of a renewal, so renewed certificates use Vault's defaults for them.
• Renewing an imported certificate depends on your Vault edition. An imported certificate doesn't belong to an application, so when you renew it, Certificate Manager - SaaS asks you to choose an application and request policy.
  • On Vault Enterprise, the connector finds the role that issued the original certificate in Vault's certificate metadata and signs the renewal with that role. This needs read on <mount>/cert-metadata/*.
  • On Vault Community Edition, Vault doesn't record the issuing role, so Certificate Manager - SaaS issues a new certificate through the request policy you chose. To keep the same role, choose a request policy that uses it.
• The revocation reason stays in Certificate Manager - SaaS. Certificate Manager - SaaS records the reason you select on the certificate's Revocation tab, but Vault's revoke API has no reason field, so Vault's certificate revocation list (CRL) shows no reason code. After each revocation, the connector rotates the mount's CRL so that it updates right away.
• One CA connector covers one PKI mount. To manage several mounts, such as pki and pki_int, create one CA connector for each.
• Import reads every certificate in the mount. Certificates from no_store roles, certificates already removed by Vault's tidy operation, and certificates stored on another performance replication cluster don't appear. A certificate that no issuer in the mount signed is imported without a chain.
• A retried request can issue twice. Vault's sign operation has no way to detect a repeated request. If Certificate Manager - SaaS retries a request, for example after a timeout, the mount can end up with an extra certificate for the same CSR. It stays valid, and a later import picks it up.
• TLS certificate authentication isn't supported. The connector authenticates with a token or AppRole only.

Troubleshooting¶

Connection issues¶

Issuance issues¶

Revocation issues¶

Import issues¶

What's next?¶

This CA is now ready to be added to one or more request policies. To do this, select this CA when creating request policies.

Related Links¶

• CA Connector overview
• Creating a custom CA connector
• Custom CAs in the CA inventory
• Create a request policy