- Overview
- Reference Guide
- Setup & Architecture
- Release Notes
- Workflow
- API Reference
- Integration Guide
- Discovery Agent Setup Guide
HashiCorp Vault PKI
CertSecure Manager uses a HashiCorp Vault PKI secrets engine as a CA through the Vault HTTP API. The connector is agentless: no installer or connector host is needed, and the CA is configured from the HashiCorp Vault tile under Administration > Certificate Authorities > Agentless CAs. CertSecure Manager signs in to Vault with an AppRole, issues certificates through the PKI mount, and synchronizes the certificates of the mount into the inventory.
Note: To discover certificates already stored in Vault, rather than issuing from it, see Vault Config under Discovery.
Prerequisites
- Your CertSecure Manager account has the Manage Certification Authorities permission.
- A reachable Vault cluster with the PKI secrets engine enabled at a known mount path and backed by a signing or intermediate CA.
- At least one PKI role on the mount. Roles set the allowed domains, the key type and size, and the TTL.
- An AppRole for CertSecure Manager (role ID and secret ID), bound to a policy that allows the PKI operations listed below.
- Network access from the CertSecure Manager backend to the Vault API over HTTPS, by default on TCP 8200.
| Item | Value |
|---|---|
| Vault address | HTTPS, by default port 8200, for example https://vault.example.com:8200 |
| Authentication | AppRole (Role ID and Secret ID) |
| PKI mount path | For example pki_int |
| Namespace | The Vault namespace that holds the PKI mount. The field is required in CertSecure Manager. |
| TLS trust | The CertSecure Manager backend must trust the Vault server certificate |
Preparing the PKI Secrets Engine
Make sure the PKI engine is enabled at the mount with a CA configured, and that at least one role exists.
vault secrets enable -path=pki_int pki
vault list pki_int/roles
vault read pki_int/roles/<role>Creating the CertSecure Manager Policy and Credential
Grant the credential only the calls that CertSecure Manager makes. Replace <mount> with the PKI mount path:
# certsecure-pki.hcl
path "<mount>/roles" { capabilities = ["list"] }
path "<mount>/roles/*" { capabilities = ["read"] }
path "<mount>/issue/*" { capabilities = ["create", "update"] }
path "<mount>/revoke" { capabilities = ["create", "update"] }
path "<mount>/certs" { capabilities = ["list"] }
path "<mount>/cert/*" { capabilities = ["read"] }
path "<mount>/config/urls" { capabilities = ["read"] }Write the policy, then create an AppRole for CertSecure Manager and read its role ID and secret ID:
vault policy write certsecure-pki certsecure-pki.hcl
vault auth enable approle
vault write auth/approle/role/certsecure token_policies=certsecure-pki token_period=768h
vault read auth/approle/role/certsecure/role-id
vault write -f auth/approle/role/certsecure/secret-idAdding the Vault CA
- Go to Administration > Certificate Authorities and select Configure on the HashiCorp Vault tile.
- Select Add New Configuration on the Hashicorp CA page. The Configure Hashicorp dialog opens.
-
Enter:
- Vault Address (required) – for example
https://vault.example.com:8200. - Namespace (required) – the Vault namespace of the PKI mount.
- Role ID and Secret ID (required) – the AppRole credential.
- PKI Mount (required) – the mount path of the PKI secrets engine, for example
pki_int. - CA Name – a name for the CA in CertSecure Manager.
- Renewal Period (in minutes) – how often the certificates of the mount are synchronized. At least 1; the default is 1.
- Vault Address (required) – for example
- Select Add.
The configuration list shows the CA Name, Vault Address, Namespace, PKI Mount, Last Updated and Status (Active or Inactive) of each configuration. Its right-click menu offers:
- View Details – opens the Configuration Details of the configuration.
- Manage Sync – shows the Active, Expired, Failed and Revoked certificate counts of the current synchronization and a history of earlier ones. Sync Now starts a synchronization; it is disabled while one is running.
- Delete – deletes the configuration after a confirmation.
Issuing, Renewing and Revoking
- Issue – in Enrollment > Generate Certificate, select the Vault CA and enter the subject and SANs. For a Vault CA the form also asks for the TTL (in hrs) of the certificate. Vault issues it through the PKI mount, under the rules of the PKI role.
- Renew – select the certificate in Inventory and renew it.
- Revoke – select the certificate and revoke it. CertSecure Manager calls
<mount>/revokewith its serial number. CRL and OCSP follow theconfig/urlsand CRL settings of the mount.
Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| No roles are listed | The policy does not allow list on <mount>/roles, or the mount path is wrong. |
Grant list on the roles path and check the exact PKI mount path. |
| 403 when issuing | The policy does not allow create on <mount>/issue/*, or the role name does not match. |
Align the policy and the role name. |
| TLS handshake fails | The CertSecure Manager backend does not trust the Vault server certificate. | Add the CA chain of the Vault server to the trust store of the backend. |
| New certificates do not appear | The renewal period is long, or the AppRole secret ID has expired. | Use Sync Now under Manage Sync, shorten the renewal period, or issue a new secret ID. |