Constrain Vault PKI roles before a certificate becomes a trust problem
A PKI role is a policy object that decides which names a caller can put into a certificate. Teams often review the requesting application and its Vault token, then overlook the role itself. That gap matters because one permissive role can turn a narrowly scoped token into authority over names the application was never meant to represent.
The role is the issuance contract
HashiCorp Vault documents PKI roles as a way to limit certificate issuance. allowed_domains defines the domain set for the role. allow_bare_domains permits the domain itself, while allow_subdomains permits names below it. These defaults are restrictive unless an operator changes them. A role that allows example.com and subdomains does not necessarily allow the bare name unless the corresponding option is enabled.
The API documentation describes more than the two common flags. Glob domains and wildcard certificates deserve separate consideration because their effects are easy to confuse. A role used by an internal service should be designed around the exact DNS identity or identity pattern that service needs. It should not inherit a broad platform domain merely because the certificate is convenient for testing.
TTL options are part of the same contract. A short maximum TTL limits the life of a wrongly issued certificate, but it does not repair an overbroad subject. A certificate for the wrong name remains a trust problem for every client that accepts it, even if the certificate expires tomorrow.
Separate issue from administer
Vault's quick-start guidance recommends ACLs that restrict role management to trusted operators while limiting applications to the credentials they may request. This separation is important. An application that can update its own PKI role can widen its name scope and then issue against the widened role. The application should normally be able to call the issuing endpoint for a named role, while a smaller group controls the role definition.
Use distinct roles for distinct trust purposes. A web frontend, a database service, and an internal migration job may all need certificates, but they do not need the same subject names or TTLs. Separate roles also make policy changes and revocation reviews easier to attribute. When a role is shared by unrelated services, an exception for one service becomes an exception for all.
Audit by exercising the boundary
List every PKI role and its allowed names, bare-domain behavior, subdomain behavior, wildcard behavior, and TTL. Then issue test certificates under those roles with one valid name and several invalid names. Confirm both the success case and the rejection case. A policy that returns an error only in the UI or validator is not a complete test. The API needs the same result.
Inspect the certificate that was issued. Check the subject alternative names, validity period, issuer, and key usage against the intended service identity. A common operational failure is to validate issuance and deployment separately. The deployment automation may select a different role or silently reuse a cached certificate. Testing the end-to-end path catches that mismatch.
When a role is updated, treat the change as an authorization change. The PKI API documentation warns that posting a role that already exists overwrites its contents, using defaults for omitted parameters. An update automation that sends a partial configuration can therefore remove a restriction. Compare the full role before and after, and require review for changes to name scope.
Handle exceptions as code
A temporary name expansion should be a reviewed change with an owner, an end date, and a removal check. Monitoring should record certificate requests, the role used, and the requested identities. Alerting on a new role, a new allowed domain, a wildcard request, or an unusual TTL gives the team a chance to respond before the certificate is distributed.
Vault provides the mechanism for constrained issuance. The certificate client, the upstream CA, and the relying applications still need to enforce their own trust policies. A clean PKI role lowers the chance that an accidental certificate becomes an accepted identity.
Top comments (1)
One extra boundary worth testing is issuer selection. If the application only needs the role's configured issuer, keep its ACL on
pki/issue/<role>orpki/sign/<role>. The issuer-specific variants let the caller override that choice. A negative test using a second intermediate in the same mount can catch this even when all the DNS-name tests pass. HashiCorp calls out this distinction in the issuing endpoints documentation.