From 80329e69ddbb43792cd1108b89dff1023869b575 Mon Sep 17 00:00:00 2001 From: Tuan Dang Date: Wed, 5 Nov 2025 16:16:39 -0800 Subject: [PATCH] continue pki v3 docs --- docs/docs.json | 15 +- .../pki/certificates/certificates.mdx | 151 +++++++++++++++- .../platform/pki/certificates/overview.mdx | 5 +- .../platform/pki/certificates/profiles.mdx | 2 +- .../platform/pki/enrollment-methods/api.mdx | 162 ++++++++++++++++-- .../platform/pki/enrollment-methods/est.mdx | 64 +++++++ .../pki/enrollment-methods/overview.mdx | 11 ++ docs/documentation/platform/pki/overview.mdx | 7 +- .../PkiManagerLayout/PkiManagerLayout.tsx | 14 +- 9 files changed, 396 insertions(+), 35 deletions(-) diff --git a/docs/docs.json b/docs/docs.json index 616affd65..66976630b 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -741,14 +741,9 @@ "pages": [ "documentation/platform/pki/enrollment-methods/overview", "documentation/platform/pki/enrollment-methods/api", - "documentation/platform/pki/enrollment-methods/est", - "documentation/platform/pki/enrollment-methods/acme", - "documentation/platform/pki/enrollment-methods/scep" + "documentation/platform/pki/enrollment-methods/est" ] }, - "documentation/platform/pki/subscribers", - "documentation/platform/pki/certificates", - "documentation/platform/pki/est", "documentation/platform/pki/alerting" ] }, @@ -2975,6 +2970,14 @@ { "source": "/documentation/platform/pki/azure-adcs", "destination": "/documentation/platform/pki/ca/azure-adcs" + }, + { + "source": "/documentation/platform/pki/certificates", + "destination": "/documentation/platform/pki/certificates/certificates" + }, + { + "source": "/documentation/platform/pki/est", + "destination": "/documentation/platform/pki/enrollment-methods/est" } ] } diff --git a/docs/documentation/platform/pki/certificates/certificates.mdx b/docs/documentation/platform/pki/certificates/certificates.mdx index e4888db86..b27e50145 100644 --- a/docs/documentation/platform/pki/certificates/certificates.mdx +++ b/docs/documentation/platform/pki/certificates/certificates.mdx @@ -3,9 +3,158 @@ title: "Certificates" sidebarTitle: "Certificates" --- + + PKI architecture is a complex topic and there are many ways to orchestrate + certificate management including renewal operations. For specific guidance and + access to enterprise features, we recommend reaching out to + sales@infisical.com to schedule a demo. + + ## Concept -A certificate is the actual X.509 certificate issued for a certificate profile. +A certificate is the (X.509) leaf certificate issued for a certificate profile. Once issued, a certificate is kept track of in the certificate inventory where you can manage various aspects of its lifecycle including deployment to cloud key stores, server-side auto-renewal behavior, revocation, and more. + +## Guide to Issuing Certificates + +To issue a certificate, you must first create a [certificate profile](/documentation/platform/pki/certificates/profiles) and a [certificate template](/documentation/platform/pki/certificates/templates) to go along with it. + +The [enrollment method](/documentation/platform/pki/enrollment-methods/overview) configured on the certificate profile determines how a certificate is issued for it. +Refer to the documentation for each enrollment method below to learn more about how to issue certificates using it. + +- [API](/documentation/platform/pki/certificates/api): Issue a certificate over UI or by making an API request to Infisical. +- [EST](/documentation/platform/pki/certificates/est): Issue a certificate over the EST protocol. +- [ACME](/documentation/platform/pki/certificates/acme): Issue a certificate over the ACME protocol. +- [SCEP](/documentation/platform/pki/certificates/scep): Issue a certificate over the SCEP protocol. + +## Guide to Renewing Certificates + +To [renew a certificate](/documentation/platform/pki/concepts/certificate-lifecycle#renewal), you can either request a new certificate from a certificate profile or have the platform +automatically request a new one for you. Whether you pursue a client-driven or server-driven approach is totally dependent on the enrollment method configured on your certificate +profile as well as your infrastructure use-case. + +### Client-Driven Certificate Renewal + +Client-driven certificate renewal is when renewal is initiated client-side by the end-entity consuming the certificate. +This is the most common approach to certificate renewal and is suitable for most use-cases. + +### Server-Driven Certificate Renewal + +Server-driven certificate renewal is when renewal is initiated server-side by Infisical rather than by the end-entity consuming the certificate. +When a certificate considered for auto-renewal meets a specified _renewal days before expiration_ threshold, Infisical reaches out to the issuing CA bound to the [certificate profile](/documentation/platform/pki/certificates/profiles) of the expiring certificate +to request for a new one. +The resulting renewed certificate is stored in the platform and made available to be fetched back or pushed downstream to end-entities or external systems such as cloud key stores. + +Note that server-driven certificate renewal is only available for certificates issued via the [API enrollment method](/documentation/platform/pki/enrollment-methods/api) where key pairs are generated server-side. +A certificate can be considered for auto-renewal at time of issuance if the **Enable Auto-Renewal By Default** option is selected on its [certificate profile](/documentation/platform/pki/certificates/profiles) or after issuance by toggling this option manually. + +The following examples demonstrate different approaches to certificate renewal: + +- Using the ACME enrollment method, you may connect an ACME client like [certbot](https://certbot.eff.org/) to fetch back and renew certificates for Apache, Nginx, or other server. The ACME client will pursue a client-driven approach and submit certificate requests upon certificate expiration for you, saving renewed certificates back to the server's configuration. +- Using the ACME enrollment method, you may use [cert-manager](https://cert-manager.io/) with Infisical to issue and renew certificates for Kubernetes workloads; cert-manager will pursue a client-driven approach and submit certificate requests upon certificate expiration for you, saving renewed certificates back to Kubernetes secrets. +- Using the API enrollment method, you may push and auto-renew certificates to AWS and Azure using [certificate syncs](/documentation/platform/pki/certificate-syncs/overview). Certificates issued over the API enrollment method, where key pairs are generated server-side, are also eligible for server-side auto-renewal; once renewed, certificates are automatically pushed back to their sync destination. + +## Guide to Revoking Certificates + +In the following steps, we explore how to revoke a X.509 certificate and obtain a Certificate Revocation List (CRL) for a CA. + + + + + + Assuming that you've issued a certificate under a CA, you can revoke it by + selecting the **Revoke Certificate** option for it and specifying the reason + for revocation. + + ![pki revoke certificate](/images/platform/pki/cert-revoke.png) + + ![pki revoke certificate modal](/images/platform/pki/cert-revoke-modal.png) + + + + In order to check the revocation status of a certificate, you can check it + against the CRL of a CA by heading to its Issuing CA and downloading the CRL. + + ![pki view crl](/images/platform/pki/ca-crl.png) + + To verify a certificate against the + downloaded CRL with OpenSSL, you can use the following command: + +```bash +openssl verify -crl_check -CAfile chain.pem -CRLfile crl.pem cert.pem +``` + +Note that you can also obtain the CRL from the certificate itself by +referencing the CRL distribution point extension on the certificate. + +To check a certificate against the CRL distribution point specified within it with OpenSSL, you can use the following command: + +```bash +openssl verify -verbose -crl_check -crl_download -CAfile chain.pem cert.pem +``` + + + + + + + + Assuming that you've issued a certificate under a CA, you can revoke it by making an API request to the [Revoke Certificate](/api-reference/endpoints/certificate-authorities/revoke) API endpoint, + specifying the serial number of the certificate and the reason for revocation. + + ### Sample request + + ```bash Request + curl --location --request POST 'https://app.infisical.com/api/v1/pki/certificates//revoke' \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "revocationReason": "UNSPECIFIED" + }' + ``` + + ### Sample response + + ```bash Response + { + message: "Successfully revoked certificate", + serialNumber: "...", + revokedAt: "..." + } + ``` + + + In order to check the revocation status of a certificate, you can check it against the CRL of the issuing CA. + To obtain the CRLs of the CA, make an API request to the [List CRLs](/api-reference/endpoints/certificate-authorities/crls) API endpoint. + + ### Sample request + + ```bash Request + curl --location --request GET 'https://app.infisical.com/api/v1/pki/ca//crls' \ + --header 'Authorization: Bearer ' + ``` + + ### Sample response + + ```bash Response + [ + { + id: "...", + crl: "..." + }, + ... + ] + ``` + + To verify a certificate against the CRL with OpenSSL, you can use the following command: + + ```bash + openssl verify -crl_check -CAfile chain.pem -CRLfile crl.pem cert.pem + ``` + + + + + diff --git a/docs/documentation/platform/pki/certificates/overview.mdx b/docs/documentation/platform/pki/certificates/overview.mdx index e60acf1a0..a4688388a 100644 --- a/docs/documentation/platform/pki/certificates/overview.mdx +++ b/docs/documentation/platform/pki/certificates/overview.mdx @@ -3,11 +3,12 @@ title: "Overview" sidebarTitle: "Overview" --- -To issue a certificate with Infisical, you create a certificate profile and a certificate template to go along with it. You then issue a certificate by making a request against that specific profile. +To issue a certificate with Infisical, you create a certificate profile and a certificate template to go along with it. You then issue a certificate against +a specific profile depending on the enrollment method associated with it. There are three components to understand: -- [Certificate Profile](/documentation/platform/pki/certificates/profiles): A configuration set specifying how certificates should be issued under that profile including the [issuing CA](/documentation/platform/pki/ca/overview), a certificate template, and the enrollment method (such as ACME, EST, API, etc.) used to enroll certificates. +- [Certificate Profile](/documentation/platform/pki/certificates/profiles): A configuration set specifying how certificates should be issued under that profile including the [issuing CA](/documentation/platform/pki/ca/overview), a certificate template, and the [enrollment method](/documentation/platform/pki/enrollment-methods/overview) (such as ACME, EST, API, etc.) used to enroll certificates. - [Certificate Template](/documentation/platform/pki/certificates/templates): A policy structure specifying the permitted attributes for requested certificates including subject naming conventions, SAN fields, key usages, and extended key usages. diff --git a/docs/documentation/platform/pki/certificates/profiles.mdx b/docs/documentation/platform/pki/certificates/profiles.mdx index 30289138e..3d4fb9380 100644 --- a/docs/documentation/platform/pki/certificates/profiles.mdx +++ b/docs/documentation/platform/pki/certificates/profiles.mdx @@ -5,7 +5,7 @@ sidebarTitle: "Profiles" ## Concept -A certificate profile is a configuration set specifying how leaf certificates should be issued for a group of end-entities including the [issuing CA](/documentation/platform/pki/ca/overview), a [certificate template](/documentation/platform/pki/certificates/templates), and the enrollment method (e.g. ACME, EST, API, etc.) used to enroll certificates. +A certificate profile is a configuration set specifying how leaf certificates should be issued for a group of end-entities including the [issuing CA](/documentation/platform/pki/ca/overview), a [certificate template](/documentation/platform/pki/certificates/templates), and the [enrollment method](/documentation/platform/pki/enrollment-methods/overview) (e.g. ACME, EST, API, etc.) used to enroll certificates. You typically request certificates against a certificate profile through its associated enrollment method. Each method defines its own interaction flow which you can read more about in its respective documentation. diff --git a/docs/documentation/platform/pki/enrollment-methods/api.mdx b/docs/documentation/platform/pki/enrollment-methods/api.mdx index 22bf5c833..e628f736c 100644 --- a/docs/documentation/platform/pki/enrollment-methods/api.mdx +++ b/docs/documentation/platform/pki/enrollment-methods/api.mdx @@ -3,24 +3,156 @@ title: "Certificate Enrollment via API" sidebarTitle: "API" --- +## Concept + +The API enrollment method allows you to issue certificates against a specific certificate profile over Web UI or by making an API request to Infisical. + +## Guide to Certificate Enrollment via API + +In the following steps, we explore how to issue a X.509 certificate using the API enrollment method. + - -
    -
  • - Enable Auto-Renewal: Whether or not to opt-in issued certificates for - (server-side) auto-renewal. -
    • -
  • - Auto-Renewal Days: The number of days before the certificate expires to - trigger certificate renewal. -
    • -
+ + + + + Create a [certificate + profile](/documentation/platform/pki/certificates/profiles) with **API** + selected as the enrollment method. + + Notice that the API enrollment method supports an option called **Enable Auto-Renewal By Default**. + If selected, _eligible_ certificates are automatically considered for server-side auto-renewal based + on a specified renewal days before expiration threshold at the time of issuance; for more information + about server-side auto-renewal, refer to the documentation [here](/documentation/platform/pki/certificates/certificates#guide-to-renewing-certificates). + + + + To create a certificate, head to your Project > Certificates > Certificates and press **Issue**. + + TODO: Image + +Here, select the certificate profile from step 1 that will be used to issue the certificate and fill out the rest of the details for the certificate to be issued. + + + + Once you have created the certificate from step 1, you'll be presented with the certificate details including the **Certificate Body**, **Certificate Chain**, and **Private Key**. + + TODO: Image + - Note that auto-renewal only applies to certificates issued through - CSR-less enrollment where key generation is done internally by - Infisical; conversely certificates issued via CSR submission are not eligible for auto-renewal. + Make sure to download and store the **Private Key** in a secure location as it + will only be displayed once at the time of certificate issuance. The + **Certificate Body** and **Certificate Chain** will remain accessible and can + be copied at any time. + + + + + + + + A certificate template is a set of policies for certificates issued under that template; each template is bound to a specific CA and can also be bound to a certificate collection for alerting such that any certificate issued under the template is automatically added to the collection. + + With certificate templates, you can specify, for example, that issued certificates must have a common name (CN) adhering to a specific format like .*.acme.com or perhaps that the max TTL cannot be more than 1 year. + + To create a certificate template, make an API request to the [Create Certificate Template](/api-reference/endpoints/certificate-templates/create) API endpoint, specifying the issuing CA. + + ### Sample request + + ```bash Request + curl --location --request POST 'https://app.infisical.com/api/v1/pki/certificate-templates' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "caId": "", + "name": "My Certificate Template", + "commonName": ".*.acme.com", + "subjectAlternativeName": ".*.acme.com", + "ttl": "1y", + }' + ``` + + ### Sample response + + ```bash Response + { + id: "...", + caId: "...", + name: "...", + commonName: "...", + subjectAlternativeName: "...", + ttl: "...", + } + ``` + + + + To create a certificate under the certificate template, make an API request to the [Issue Certificate](/api-reference/endpoints/certificates/issue-cert) API endpoint, + specifying the issuing CA. + + ### Sample request + + ```bash Request + curl --location --request POST 'https://app.infisical.com/api/v1/pki/certificates/issue-certificate' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "certificateTemplateId": "", + "commonName": "service.acme.com", + "ttl": "1y", + }' + ``` + + ### Sample response + + ```bash Response + { + certificate: "...", + certificateChain: "...", + issuingCaCertificate: "...", + privateKey: "...", + serialNumber: "..." + } + ``` + + + Note that Infisical PKI supports issuing certificates without certificate templates as well. If this is desired, then you can set the **Certificate Template** field to **None** + and specify the **Issuing CA** and optional **Certificate Collection** fields; the rest of the fields for the issued certificate remain the same. + + That said, we recommend using certificate templates to enforce policies and attach expiration monitoring on issued certificates. + + + + Make sure to store the `privateKey` as it is only returned once here at the time of certificate issuance. The `certificate` and `certificateChain` will remain accessible and can be retrieved at any time. + + + If you have an external private key, you can also create a certificate by making an API request containing a pem-encoded CSR (Certificate Signing Request) to the [Sign Certificate](/api-reference/endpoints/certificates/sign-certificate) API endpoint, specifying the issuing CA. + + ### Sample request + + ```bash Request + curl --location --request POST 'https://app.infisical.com/api/v1/pki/certificates/sign-certificate' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "certificateTemplateId": "", + "csr": "...", + "ttl": "1y", + }' + ``` + + ### Sample response + + ```bash Response + { + certificate: "...", + certificateChain: "...", + issuingCaCertificate: "...", + privateKey: "...", + serialNumber: "..." + } + ``` + + + - Test diff --git a/docs/documentation/platform/pki/enrollment-methods/est.mdx b/docs/documentation/platform/pki/enrollment-methods/est.mdx index 56ec5bb7d..c0c6fc943 100644 --- a/docs/documentation/platform/pki/enrollment-methods/est.mdx +++ b/docs/documentation/platform/pki/enrollment-methods/est.mdx @@ -2,3 +2,67 @@ title: "Certificate Enrollment via EST" sidebarTitle: "EST" --- + +## Concept + +The API enrollment method allows you to issue and manage certificates against a specific certificate profile using the [EST protocol](https://en.wikipedia.org/wiki/Enrollment_over_Secure_Transport). +This method is suitable for environments requiring strong authentication and encrypted communication, such as in IoT, enterprise networks, and secure web services. + +Infisical's EST service is based on [RFC 7030](https://datatracker.ietf.org/doc/html/rfc7030) and implements the following endpoints: + +- **cacerts** - provides the necessary CA chain for the client to validate certificates issued by the CA. +- **simpleenroll** - allows an EST client to request a new certificate from Infisical's EST server +- **simplereenroll** - similar to the /simpleenroll endpoint but is used for renewing an existing certificate. + +These endpoints are exposed on port 8443 under the .well-known/est path (e.g. +`https://app.infisical.com:8443/.well-known/est/:estLabel/cacerts`). + +## Prerequisites + +- Your client devices need to have a bootstrap/pre-installed certificate. +- Your client devices must trust the server certificates used by Infisical's EST server. If the devices are new or lack existing trust configurations, you need to manually establish trust for the appropriate certificates. + + + For Infisical Cloud users, the devices must be configured to trust the [Amazon + root CA certificates](https://www.amazontrust.com/repository). + + +## Guide to Certificate Enrollment via EST + +In the following steps, we explore how to issue a X.509 certificate using the EST enrollment method. + + + + Create a [certificate + profile](/documentation/platform/pki/certificates/profiles) with **EST** + selected as the enrollment method and fill in EST-specific configuration. + + Here's some guidance on each EST-specific configuration field: + + - Disable Bootstrap CA Validation: Enable this if your devices are not configured with a bootstrap certificate. + - EST Passphrase: This is also used to authenticate your devices with Infisical's EST server. When configuring the clients, use the value defined here as the EST password. + - CA Chain Certificate: This is the certificate chain used to validate your devices' manufacturing/pre-installed certificates. This will be used to authenticate your devices with Infisical's EST server. + + Note that forsecurity reasons, Infisical authenticates EST clients using both client certificate and passphrase. + + + + Once the configuration of enrollment options is completed, a new EST Label field will appear in the enrollment settings. This is the value to use as label in the URL when configuring the connection of EST clients to Infisical. + + The complete URL of the supported EST endpoints may look like the following: + + - https://app.infisical.com:8443/.well-known/est/f110f308-9888-40ab-b228-237b12de8b96/cacerts + - https://app.infisical.com:8443/.well-known/est/f110f308-9888-40ab-b228-237b12de8b96/simpleenroll + - https://app.infisical.com:8443/.well-known/est/f110f308-9888-40ab-b228-237b12de8b96/simplereenroll + + + + To use the EST passphrase in your clients, configure it as the EST password. The EST username can be set to any arbitrary value. + Use the appropriate client certificates for invoking the EST endpoints. + - For `simpleenroll`, use the bootstrapped/manufacturer client certificate. + - For `simplereenroll`, use a valid EST-issued client certificate. + When configuring the PKCS#12 objects for the client certificates, only include the leaf certificate and the private key. + + + + diff --git a/docs/documentation/platform/pki/enrollment-methods/overview.mdx b/docs/documentation/platform/pki/enrollment-methods/overview.mdx index e69de29bb..f1af9375d 100644 --- a/docs/documentation/platform/pki/enrollment-methods/overview.mdx +++ b/docs/documentation/platform/pki/enrollment-methods/overview.mdx @@ -0,0 +1,11 @@ +--- +title: "Overview" +sidebarTitle: "Overview" +--- + +Enrollment methods determine how certificates are issued and managed for a [certificate profile](/documentation/platform/pki/certificates/profiles). + +Refer to the documentation for each enrollment method to learn more about how to enroll certificates using it. + +- [API](/documentation/platform/pki/enrollment-methods/api): Enroll certificates via API. +- [EST](/documentation/platform/pki/enrollment-methods/est): Enroll certificates via EST protocol. diff --git a/docs/documentation/platform/pki/overview.mdx b/docs/documentation/platform/pki/overview.mdx index 7faaad4d6..38a3e7a8b 100644 --- a/docs/documentation/platform/pki/overview.mdx +++ b/docs/documentation/platform/pki/overview.mdx @@ -12,7 +12,8 @@ Core capabilities include: - [Private CA](/documentation/platform/pki/ca/private-ca): Create and manage your own private CA hierarchy including root and intermediate CAs. - [External CA integration](/documentation/platform/pki/ca/external-ca): Integrate with external public and private CAs including [Azure ADCS](/documentation/platform/pki/ca/azure-adcs) and [ACME-compatible CAs](/documentation/platform/pki/ca/acme-ca) like Let's Encrypt and DigiCert. -- Certificate Enrollment: Support enrollment methods including API, ACME, EST, and more to automate certificate issuance for services, devices, and workloads. +- [Certificate Enrollment](/documentation/platform/pki/enrollment-methods/overview): Support enrollment methods including [API](/documentation/platform/pki/enrollment-methods/api), ACME, [EST](/documentation/platform/pki/enrollment-methods/est), and more to automate certificate issuance for services, devices, and workloads. - Certificate Inventory: Track and monitor issued X.509 certificates, maintaining a comprehensive inventory of all active and expired certificates. -- Certificate Lifecycle Automation: Automate issuance, renewal, and revocation with policy-based workflows, ensuring certificates remain valid, compliant, and up to date across your infrastructure. -- Certificate Syncs: Push certificates to cloud certificate managers like AWS Certificate Manager and Azure Key Vault. +- Certificate Lifecycle Automation: Automate issuance, [renewal](/documentation/platform/pki/certificates/certificates#guide-to-renewing-certificates), and [revocation](/documentation/platform/pki/certificates/certificates#guide-to-revoking-certificates) with policy-based workflows, ensuring certificates remain valid, compliant, and up to date across your infrastructure. +- [Certificate Syncs](/documentation/platform/pki/certificate-syncs/overview): Push certificates to cloud certificate managers like [AWS Certificate Manager](/documentation/platform/pki/certificate-syncs/aws-certificate-manager) and [Azure Key Vault](/documentation/platform/pki/certificate-syncs/azure-key-vault). +- [Certificate Alerts](/documentation/platform/pki/alerting): Receive real-time alerts and webhook events for certificate lifecycle changes such as certificate expiration. diff --git a/frontend/src/layouts/PkiManagerLayout/PkiManagerLayout.tsx b/frontend/src/layouts/PkiManagerLayout/PkiManagerLayout.tsx index 2c088c293..31c7aecf2 100644 --- a/frontend/src/layouts/PkiManagerLayout/PkiManagerLayout.tsx +++ b/frontend/src/layouts/PkiManagerLayout/PkiManagerLayout.tsx @@ -34,7 +34,7 @@ export const PkiManagerLayout = () => { return ( <>
-
+
{ App Connections )} - {showLegacySection && ( + { <> - {(subscription.pkiLegacyTemplates || hasExistingSubscribers) && ( + { { Subscribers (Legacy) )} - )} + } {(subscription.pkiLegacyTemplates || hasExistingTemplates) && ( { )} - )} + } {
{assumedPrivilegeDetails && } -
+
-
+

{` ${t("common.no-mobile")} `}