mirror of
https://github.com/hanzoai/kms.git
synced 2026-10-17 11:18:16 +00:00
zeekay
0ebffbd529
- Fix 381 files where branding script corrupted variable names (e.g. isHanzo KMSTemplate -> isKmsTemplate) - Rebrand from "Hanzo KMS" to just "KMS" for white-label support (allows Lux KMS, Hanzo KMS, etc. via configuration) - 856 files, purely string replacements, no logic changes
96 lines
5.0 KiB
Plaintext
96 lines
5.0 KiB
Plaintext
---
|
|
title: "Request a Certificate via the KMS Agent"
|
|
---
|
|
|
|
import RequestCertSetup from "/snippets/documentation/platform/pki/guides/request-cert-setup.mdx";
|
|
|
|
The [KMS Agent](/integrations/platforms/certificate-agent) is an installable client daemon that can request TLS and other X.509 certificates from KMS using the [API enrollment method](/documentation/platform/pki/enrollment-methods/api) configured on a [certificate profile](/documentation/platform/pki/certificates/profiles), persist it to a specified path on the filesystem, and automatically monitor and renew it before expiration.
|
|
|
|
Instead of [manually requesting](/documentation/platform/pki/guides/request-cert-api) and renewing a certificate via the [Issue Certificate](/api-reference/endpoints/certificates/create-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 KMS.
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
autonumber
|
|
participant Agent as KMS Agent
|
|
participant Infis as 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
|
|
end
|
|
```
|
|
|
|
## Guide
|
|
|
|
In the following steps, we explore an end-to-end workflow for requesting and continuously renewing a certificate using the KMS Agent.
|
|
|
|
<Steps>
|
|
<RequestCertSetup />
|
|
<Step title="Create a certificate profile">
|
|
Next, follow the guide [here](/documentation/platform/pki/certificates/profiles#guide-to-creating-a-certificate-profile) to create a [certificate profile](/documentation/platform/pki/certificates/profiles)
|
|
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](/documentation/platform/pki/enrollment-methods/overview) 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>
|
|
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.
|
|
</Note>
|
|
|
|
</Step>
|
|
<Step title="Request a certificate">
|
|
Next, [install the KMS CLI](/cli/overview) on the target machine you wish to request the certificate on and follow the documentation [here](/integrations/platforms/certificate-agent#operating-the-agent) to set up the KMS Agent on it.
|
|
|
|
As part of the setup, you must create an [agent configuration file](/integrations/platforms/certificate-agent#agent-configuration) that specifies how the agent should authenticate with KMS using a [machine identity](/documentation/platform/identities/machine-identities), 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:
|
|
|
|
```bash
|
|
kms cert-manager agent --config /path/to/your/agent-config.yaml
|
|
```
|
|
|
|
The 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.
|
|
|
|
</Step>
|
|
</Steps>
|