diff --git a/docs/documentation/platform/pki/certificate-templates.mdx b/docs/documentation/platform/pki/certificate-templates.mdx deleted file mode 100644 index a52bf4364..000000000 --- a/docs/documentation/platform/pki/certificate-templates.mdx +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: "Certificate Templates" -sidebarTitle: "Certificate Templates" -description: "Learn how to use certificate templates to enforce policies." ---- - -## Concept - -In order to ensure your certificates follow certain policies, you can use certificate templates during the issuance and signing flows. - -A certificate template is linked to a certificate authority. It contains custom policies for certificate fields, allowing you to define rules based on your security policies. - -## Workflow - -The typical workflow for using certificate templates consists of the following steps: - -1. Creating a certificate template attached to an existing CA along with defining custom rules for certificate fields. -2. Selecting the certificate template during the creation of new certificates. - - - Note that this workflow can be executed via the Infisical UI or manually such - as via API. - - -## Guide to using Certificate Templates - -In the following steps, we explore how to issue a X.509 certificate using a certificate template. - - - - - - - To create a certificate template, head to your Project > Internal PKI > Certificate Templates and press **Create Certificate Template**. - - ![certificate-template create template dashboard](/images/platform/pki/certificate-template/create-template-dashboard.png) - - Here, set the **Issuing CA** to the CA you want to issue certificates under when the certificate template is used. - - ![certificate-template create template modal](/images/platform/pki/certificate-template/create-template-form.png) - - Here's some guidance on each field: - - Template Name: A descriptive name for the certificate template. - - Issuing CA: The Certificate Authority (CA) that will issue certificates based on this template. - - Certificate Collection: The collection where certificates issued with this template will be added. - - Common Name (CN): The regular expression used to validate the common name in certificate requests. - - Alternative Names (SANs): The regular expression used to validate subject alternative names in certificate requests. - - TTL: The maximum Time-to-Live (TTL) for certificates issued using this template. - - - - Once you have created the certificate template from step 1, you can select it when issuing certificates. - - ![certificate-template select template](/images/platform/pki/certificate-template/select-template.png) - - - - - - - To create a certificate template, make an API request to the [Create Certificate Template](/api-reference/endpoints/certificate-templates/create) API endpoint. - - ### Sample request - - ```bash Request - curl --request POST \ - --url https://app.infisical.com/api/v1/pki/certificate-templates \ - --header 'Content-Type: application/json' \ - --data '{ - "caId": "", - "pkiCollectionId": "", - "name": "", - "commonName": "", - "subjectAlternativeName": "", - "ttl": "" - }' - ``` - - ### Sample response - - ```bash Response - { - "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", - "caId": "3c90c3cc-0d44-4b50-8888-8dd25736052a", - "name": "certificate-template-1", - "commonName": "", - ... - } - ``` - - - To use the certificate template, attach the certificate template ID when invoking the API endpoint for [issuing](/api-reference/endpoints/certificates/issue-certificate) or [signing](/api-reference/endpoints/certificates/sign-certificate) new certificates. - - ### Sample request - - ```bash Request - curl --request POST \ - --url https://app.infisical.com/api/v1/pki/certificates/issue-certificate \ - --header 'Content-Type: application/json' \ - --data '{ - "certificateTemplateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a", - "friendlyName": "my-new-certificate", - "commonName": "CERT", - ... - }' - ``` - - - - - diff --git a/docs/documentation/platform/pki/certificates.mdx b/docs/documentation/platform/pki/certificates.mdx index 41a5cb8c9..a4f1ba02c 100644 --- a/docs/documentation/platform/pki/certificates.mdx +++ b/docs/documentation/platform/pki/certificates.mdx @@ -25,7 +25,7 @@ graph TD The typical workflow for managing certificates consists of the following steps: -1. Issuing a certificate under an intermediate CA with details like name and validity period. +1. Issuing a certificate under an intermediate CA with details like name and validity period. As part of certificate issuance, you can either issue a certificate directly from a CA or do it via a certificate template. 2. Managing certificate lifecycle events such as certificate renewal and revocation. As part of the certificate revocation flow, you can also query for a Certificate Revocation List [CRL](https://en.wikipedia.org/wiki/Certificate_revocation_list), a time-stamped, signed data structure issued by a CA containing a list of revoked certificates to check if a certificate has been revoked. @@ -43,28 +43,51 @@ In the following steps, we explore how to issue a X.509 certificate under a CA. + + 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. + + Head to your Project > Certificate Authorities > Your Issuing CA and create a certificate template. + + ![pki certificate template modal](/images/platform/pki/certificate/cert-template-modal.png) + + Here's some guidance on each field: + + - Template Name: A name for the certificate template. + - Issuing CA: The Certificate Authority (CA) that will issue certificates based on this template. + - Certificate Collection (Optional): The certificate collection that certificates should be added to when issued under the template. + - Common Name (CN): A regular expression used to validate the common name in certificate requests. + - Alternative Names (SANs): A regular expression used to validate subject alternative names in certificate requests. + - TTL: The maximum Time-to-Live (TTL) for certificates issued using this template. + - To create a certificate, head to your Project > Internal PKI > Certificates and press **Create Certificate**. + To create a certificate, head to your Project > Internal PKI > Certificates and press **Issue** under the Certificates section. - ![pki issue certificate](/images/platform/pki/cert-issue.png) + ![pki issue certificate](/images/platform/pki/certificate/cert-issue.png) - Here, set the **CA** to the CA you want to issue the certificate under and fill out details for the certificate. + Here, set the **Certificate Template** to the template from step 1 and fill out the rest of the details for the certificate to be issued. - ![pki issue certificate modal](/images/platform/pki/cert-issue-modal.png) + ![pki issue certificate modal](/images/platform/pki/certificate/cert-issue-modal.png) Here's some guidance on each field: - - Issuing CA: The CA under which to issue the certificate. - Friendly Name: A friendly name for the certificate; this is only for display and defaults to the common name of the certificate if left empty. - Common Name (CN): The (common) name for the certificate like `service.acme.com`. - Alternative Names (SANs): A comma-delimited list of Subject Alternative Names (SANs) for the certificate; these can be host names or email addresses like `app1.acme.com, app2.acme.com`. - TTL: The lifetime of the certificate in seconds. - + + + 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. + 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**. - ![pki certificate body](/images/platform/pki/cert-body.png) + ![pki certificate body](/images/platform/pki/certificate/cert-body.png) 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. @@ -74,16 +97,54 @@ In the following steps, we explore how to issue a X.509 certificate under a CA. - To create a certificate, make an API request to the [Issue Certificate](/api-reference/endpoints/certificates/issue-cert) API endpoint, + + + + 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/ca//issue-certificate' \ + curl --location --request POST 'https://app.infisical.com/api/v1/pki/certificates/issue-certificate' \ --header 'Content-Type: application/json' \ --data-raw '{ - "commonName": "My Certificate", + "certificateTemplateId": "", + "commonName": "service.acme.com", "ttl": "1y", }' ``` @@ -100,18 +161,26 @@ In the following steps, we explore how to issue a X.509 certificate under a CA. } ``` + + 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-cert) API endpoint, specifying the issuing CA. + 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/ca//sign-certificate' \ + 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", }' @@ -128,7 +197,8 @@ In the following steps, we explore how to issue a X.509 certificate under a CA. serialNumber: "..." } ``` - + + diff --git a/docs/documentation/platform/pki/est.mdx b/docs/documentation/platform/pki/est.mdx index ee66c32b6..a31a5672e 100644 --- a/docs/documentation/platform/pki/est.mdx +++ b/docs/documentation/platform/pki/est.mdx @@ -26,7 +26,7 @@ These endpoints are exposed on port 8443 under the .well-known/est path e.g. ## Guide to configuring EST -1. Set up a certificate template with your selected issuing CA. This template will define the policies and parameters for certificates issued through EST. For detailed instructions on configuring a certificate template, refer to the certificate templates [documentation](/documentation/platform/pki/certificate-templates). +1. Set up a certificate template with your selected issuing CA. This template will define the policies and parameters for certificates issued through EST. For detailed instructions on configuring a certificate template, refer to the certificate templates [documentation](/documentation/platform/pki/certificates#guide-to-issuing-certificates). 2. Proceed to the certificate template's enrollment settings ![est enrollment dashboard](/images/platform/pki/est/template-enroll-hover.png) diff --git a/docs/documentation/platform/pki/private-ca.mdx b/docs/documentation/platform/pki/private-ca.mdx index 0baa13abb..d7f3f896c 100644 --- a/docs/documentation/platform/pki/private-ca.mdx +++ b/docs/documentation/platform/pki/private-ca.mdx @@ -66,6 +66,7 @@ consisting of an (optional) root CA and an intermediate CA. - State or Province Name: The state or province. - Locality Name: The city or locality. - Common Name: The name of the CA. + - Require Template for Certificate Issuance: Whether or not certificates for this CA can only be issued through certificate templates (recommended). The Organization, Country, State or Province Name, Locality Name, and Common Name make up the **Distinguished Name (DN)** or **subject** of the CA. diff --git a/docs/images/platform/pki/cert-body.png b/docs/images/platform/pki/cert-body.png deleted file mode 100644 index 8ed67a7ec..000000000 Binary files a/docs/images/platform/pki/cert-body.png and /dev/null differ diff --git a/docs/images/platform/pki/cert-issue-modal.png b/docs/images/platform/pki/cert-issue-modal.png deleted file mode 100644 index 1516ab1cb..000000000 Binary files a/docs/images/platform/pki/cert-issue-modal.png and /dev/null differ diff --git a/docs/images/platform/pki/cert-issue.png b/docs/images/platform/pki/cert-issue.png deleted file mode 100644 index 6b3e5887b..000000000 Binary files a/docs/images/platform/pki/cert-issue.png and /dev/null differ diff --git a/docs/images/platform/pki/certificate-template/create-template-dashboard.png b/docs/images/platform/pki/certificate-template/create-template-dashboard.png deleted file mode 100644 index 6f193effa..000000000 Binary files a/docs/images/platform/pki/certificate-template/create-template-dashboard.png and /dev/null differ diff --git a/docs/images/platform/pki/certificate-template/create-template-form.png b/docs/images/platform/pki/certificate-template/create-template-form.png deleted file mode 100644 index e69791edd..000000000 Binary files a/docs/images/platform/pki/certificate-template/create-template-form.png and /dev/null differ diff --git a/docs/images/platform/pki/certificate-template/select-template.png b/docs/images/platform/pki/certificate-template/select-template.png deleted file mode 100644 index c10031a45..000000000 Binary files a/docs/images/platform/pki/certificate-template/select-template.png and /dev/null differ diff --git a/docs/images/platform/pki/certificate/cert-body.png b/docs/images/platform/pki/certificate/cert-body.png new file mode 100644 index 000000000..8c1433b54 Binary files /dev/null and b/docs/images/platform/pki/certificate/cert-body.png differ diff --git a/docs/images/platform/pki/certificate/cert-issue-modal.png b/docs/images/platform/pki/certificate/cert-issue-modal.png new file mode 100644 index 000000000..f73462c8f Binary files /dev/null and b/docs/images/platform/pki/certificate/cert-issue-modal.png differ diff --git a/docs/images/platform/pki/certificate/cert-issue.png b/docs/images/platform/pki/certificate/cert-issue.png new file mode 100644 index 000000000..614271d19 Binary files /dev/null and b/docs/images/platform/pki/certificate/cert-issue.png differ diff --git a/docs/images/platform/pki/certificate/cert-template-modal.png b/docs/images/platform/pki/certificate/cert-template-modal.png new file mode 100644 index 000000000..f3995b6e4 Binary files /dev/null and b/docs/images/platform/pki/certificate/cert-template-modal.png differ diff --git a/docs/images/platform/pki/certs.png b/docs/images/platform/pki/certs.png deleted file mode 100644 index 4e1b49959..000000000 Binary files a/docs/images/platform/pki/certs.png and /dev/null differ diff --git a/docs/images/platform/pki/est/template-enroll-hover.png b/docs/images/platform/pki/est/template-enroll-hover.png index 8b13cdd60..cc0f6f658 100644 Binary files a/docs/images/platform/pki/est/template-enroll-hover.png and b/docs/images/platform/pki/est/template-enroll-hover.png differ diff --git a/docs/mint.json b/docs/mint.json index c26245def..f85a6441a 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -108,7 +108,6 @@ "documentation/platform/pki/overview", "documentation/platform/pki/private-ca", "documentation/platform/pki/certificates", - "documentation/platform/pki/certificate-templates", "documentation/platform/pki/pki-issuer", "documentation/platform/pki/est", "documentation/platform/pki/alerting" @@ -707,7 +706,7 @@ "api-reference/endpoints/certificate-authorities/import-cert", "api-reference/endpoints/certificate-authorities/issue-cert", "api-reference/endpoints/certificate-authorities/sign-cert", - "api-reference/endpoints/certificate-authorities/crls" + "api-reference/endpoints/certificate-authorities/crl" ] }, {