Request a Certificate via the KMS Agent
The KMS Agent is an installable client daemon that can request TLS and other X.509 certificates from Hanzo KMS using the API enrollment method configured on a certificate profile, persist it to a specified path on the filesystem, and automatically monitor and renew it before expiration.
Instead of manually requesting and renewing a certificate via the Issue Certificate API endpoint, you can install and launch the KMS Agent to have it perform these steps for you automatically.
Diagram
The following sequence diagram illustrates the certificate enrollment workflow for requesting a certificate using the KMS Agent from Hanzo KMS.
sequenceDiagram
autonumber
participant Agent as KMS Agent
participant Infis as Hanzo KMS
participant CA as CA<br/>(Internal or External)
Agent->>Infis: Request certificate<br/>(profileId, conditional subject/SANs, ttl,<br/>key usages, conditional CSR, etc.)
Infis->>Infis: Look up certificate profile<br/>(by profileId)
Infis->>Infis: Validate request<br/>against profile constraints<br/>(CN/SAN rules, key usages, max TTL, etc.)
alt Issuer Type = Self-Signed
Infis->>Infis: Generate keypair<br/>and self-sign certificate
else Issuer Type = Internal CA
Infis->>CA: Request certificate issuance
CA-->>Infis: Signed certificate<br/>(+ chain)
end
Infis-->>Agent: Return certificate, certificate chain,<br/>(and private key if server-generated)
Note over Agent: Persist certificate and begin lifecycle monitoring
loop Periodic certificate status check
Agent->>Agent: Check certificate expiration<br/>against renew-before-expiry threshold
alt Renewal not required
Agent-->>Agent: Continue monitoring
else Renewal required
Agent->>Infis: Request new certificate<br/>(same profile and constraints)
Infis->>Infis: Validate renewal request<br/>against profile constraints
alt Issuer Type = Self-Signed
Infis->>Infis: Generate keypair<br/>and self-sign certificate
else Issuer Type = Internal CA
Infis->>CA: Request certificate issuance
CA-->>Infis: Signed certificate<br/>(+ chain)
end
Infis-->>Agent: Return renewed certificate, certificate chain, and private key
end
endGuide
In the following steps, we explore an end-to-end workflow for requesting and continuously renewing a certificate using the KMS Agent.
Next, follow the guide here to create a certificate profile that will be referenced when requesting a certificate.
The certificate profile specifies which certificate policy and issuing CA should be used to validate an incoming certificate request and issue a certificate; it also specifies the enrollment method for how certificates can be requested against this profile to begin with.
You should specify the certificate policy from Step 2, the issuing CA from Step 1, and the API option in the Enrollment Method dropdown when creating the certificate profile.
Note that if you're looking to issue self-signed certificates, you should select the Self-Signed option in the Issuer Type dropdown when creating the certificate profile.
Next, install the KMS CLI on the target machine you wish to request the certificate on and follow the documentation here to set up the KMS Agent on it.
As part of the setup, you must create an agent configuration file that specifies how the agent should authenticate with Hanzo KMS using a machine identity, the certificate profile it should request against (from Step 3), what kind of certificate to request, where to persist the certificate, and how it should be managed in terms of auto-renewal.
Finally, start the agent with that configuration file so it can start requesting and continuously renewing the certificate on your behalf using the command below:
kms cert-manager agent --config /path/to/your/agent-config.yamlThe certificate, certificate chain, and private key will be persisted to the filesystem at the paths specified in the file-output section of the agent configuration file.
How is this guide?
Last updated on