awatertrevi/infisical
1
0
Fork 0
mirror of https://github.com/awatertrevi/infisical.git synced 2026-09-22 13:39:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update certificate / template docs

Browse Source
This commit is contained in:
Tuan Dang
2024-09-09 14:22:26 -07:00
parent e005e94165
commit 0b882ece8c
17 changed files with 87 additions and 128 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
docs/documentation/platform/pki/certificate-templates.mdx
View File

@@ -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>
Note that this workflow can be executed via the Infisical UI or manually such
as via API.
</Note>
## Guide to using Certificate Templates
In the following steps, we explore how to issue a X.509 certificate using a certificate template.
<Tabs>
<Tab title="Infisical UI">
<Steps>
<Step title="Creating the 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.
</Step>
<Step title="Using the certificate 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)
</Step>
</Steps>
</Tab>
<Tab title="API">
<Steps>
<Step title="Creating the certificate template">
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": "<string>",
"pkiCollectionId": "<string>",
"name": "<string>",
"commonName": "<string>",
"subjectAlternativeName": "<string>",
"ttl": "<string>"
}'
```
### Sample response
```bash Response
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"caId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "certificate-template-1",
"commonName": "<string>",
...
}
```
</Step>
<Step title="Using the certificate template">
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",
...
}'
```
</Step>
</Steps>
</Tab>
</Tabs>

98
docs/documentation/platform/pki/certificates.mdx
View File

@@ -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.
<Tab title="Infisical UI">
<Steps>
<Step title="Creating a certificate template">
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.
</Step>
<Step title="Creating a certificate">
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>
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.
</Note>
</Step>
<Step title="Copying the certificate details">
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)
<Note>
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.
</Steps>
</Tab>
<Tab title="API">
To create a certificate, make an API request to the [Issue Certificate](/api-reference/endpoints/certificates/issue-cert) API endpoint,
<Steps>
<Step title="Creating a certificate template">
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": "<ca-id>",
"name": "My Certificate Template",
"commonName": ".*.acme.com",
"subjectAlternativeName": ".*.acme.com",
"ttl": "1y",
}'
```
### Sample response
```bash Response
{
id: "...",
caId: "...",
name: "...",
commonName: "...",
subjectAlternativeName: "...",
ttl: "...",
}
```
</Step>
<Step title="Creating a certificate">
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/<ca-id>/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": "<certificate-template-id>",
"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>
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.
</Note>
<Note>
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.
</Note>
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/<ca-id>/sign-certificate' \
curl --location --request POST 'https://app.infisical.com/api/v1/pki/certificates/sign-certificate' \
--header 'Content-Type: application/json' \
--data-raw '{
"certificateTemplateId": "<certificate-template-id>",
"csr": "...",
"ttl": "1y",
}'
@@ -128,7 +197,8 @@ In the following steps, we explore how to issue a X.509 certificate under a CA.
serialNumber: "..."
}
```
</Step>
</Steps>
</Tab>
</Tabs>

2
docs/documentation/platform/pki/est.mdx
View File

@@ -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)

1
docs/documentation/platform/pki/private-ca.mdx
View File

@@ -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).
<Note>
The Organization, Country, State or Province Name, Locality Name, and Common Name make up the **Distinguished Name (DN)** or **subject** of the CA.

BIN
docs/images/platform/pki/cert-body.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 721 KiB

BIN
docs/images/platform/pki/cert-issue-modal.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 372 KiB

BIN
docs/images/platform/pki/cert-issue.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 579 KiB

BIN
docs/images/platform/pki/certificate-template/create-template-dashboard.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 715 KiB

BIN
docs/images/platform/pki/certificate-template/create-template-form.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 158 KiB

BIN
docs/images/platform/pki/certificate-template/select-template.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 97 KiB

BIN
docs/images/platform/pki/certificate/cert-body.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 779 KiB

BIN
docs/images/platform/pki/certificate/cert-issue-modal.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 379 KiB

BIN
docs/images/platform/pki/certificate/cert-issue.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 700 KiB

BIN
docs/images/platform/pki/certificate/cert-template-modal.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 517 KiB

BIN
docs/images/platform/pki/certs.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 462 KiB

BIN
docs/images/platform/pki/est/template-enroll-hover.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 723 KiB

After

Width:  |  Height:  |  Size: 865 KiB

3
docs/mint.json
View File

@@ -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"
]
},
{