mirror of
https://github.com/awatertrevi/infisical.git
synced 2026-09-22 13:39:35 +00:00
continue pki v3 docs
This commit is contained in:
Tuan Dang
@@ -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.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="API">
|
||||
<ul>
|
||||
<li>
|
||||
Enable Auto-Renewal: Whether or not to opt-in issued certificates for
|
||||
(server-side) auto-renewal.
|
||||
</li>
|
||||
<li>
|
||||
Auto-Renewal Days: The number of days before the certificate expires to
|
||||
trigger certificate renewal.
|
||||
</li>
|
||||
</ul>
|
||||
<Tab title="Infisical UI">
|
||||
|
||||
<Steps>
|
||||
<Step title="Create a certificate profile">
|
||||
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).
|
||||
|
||||
</Step>
|
||||
<Step title="Issue a certificate">
|
||||
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.
|
||||
|
||||
</Step>
|
||||
<Step title="Download 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**.
|
||||
|
||||
TODO: Image
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
</Tab>
|
||||
<Tab title="API">
|
||||
|
||||
<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/certificates/issue-certificate' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"certificateTemplateId": "<certificate-template-id>",
|
||||
"commonName": "service.acme.com",
|
||||
"ttl": "1y",
|
||||
}'
|
||||
```
|
||||
|
||||
### Sample response
|
||||
|
||||
```bash Response
|
||||
{
|
||||
certificate: "...",
|
||||
certificateChain: "...",
|
||||
issuingCaCertificate: "...",
|
||||
privateKey: "...",
|
||||
serialNumber: "..."
|
||||
}
|
||||
```
|
||||
|
||||
<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-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": "<certificate-template-id>",
|
||||
"csr": "...",
|
||||
"ttl": "1y",
|
||||
}'
|
||||
```
|
||||
|
||||
### Sample response
|
||||
|
||||
```bash Response
|
||||
{
|
||||
certificate: "...",
|
||||
certificateChain: "...",
|
||||
issuingCaCertificate: "...",
|
||||
privateKey: "...",
|
||||
serialNumber: "..."
|
||||
}
|
||||
```
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
</Tab>
|
||||
<Tab title="EST">Test</Tab>
|
||||
</Tabs>
|
||||
|
||||
@@ -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.
|
||||
|
||||
<Note>
|
||||
For Infisical Cloud users, the devices must be configured to trust the [Amazon
|
||||
root CA certificates](https://www.amazontrust.com/repository).
|
||||
</Note>
|
||||
|
||||
## Guide to Certificate Enrollment via EST
|
||||
|
||||
In the following steps, we explore how to issue a X.509 certificate using the EST enrollment method.
|
||||
|
||||
<Steps>
|
||||
<Step title="Set up up a certificate profile">
|
||||
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.
|
||||
|
||||
</Step>
|
||||
<Step title="Obtain the EST label">
|
||||
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
|
||||
</Step>
|
||||
|
||||
<Step title="Configure EST clients">
|
||||
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.
|
||||
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user