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

finish updating ca docs

Browse Source
This commit is contained in:
Tuan Dang
2025-10-29 12:43:28 -07:00
parent a76d013ce0
commit c4c4ff4086
13 changed files with 128 additions and 208 deletions
Download Patch File Download Diff File Expand all files Collapse all files

341
docs/documentation/platform/pki/ca/acme-ca.mdx Normal file
View File

@@ -0,0 +1,341 @@
---
title: "ACME CA"
description: "Learn how to automatically provision and manage TLS certificates using ACME Certificate Authorities like Let's Encrypt with Infisical PKI"
---
## Concept
The Infisical ACME integration allows you to connect with ACME (Automatic Certificate Management Environment) Certificate Authorities to automatically issue and manage publicly trusted TLS certificates for your [subscribers](/documentation/platform/pki/subscribers). This integration enables you to leverage established public CA infrastructure like Let's Encrypt while centralizing your certificate management within Infisical.
ACME is a protocol that automates the process of certificate issuance and renewal through domain validation challenges. The integration is perfect for obtaining trusted X.509 certificates for public-facing services and is capable of automatically renewing certificates as needed.
<div align="center">
```mermaid
graph TD
A[ACME CA Provider<br>e.g., Let's Encrypt] <-->|ACME v2 Protocol| B[Infisical]
B -->|Creates TXT Records<br>via Route53/Cloudflare| C[DNS Validation]
B -->|Manages Certificates| D[Subscribers]
```
</div>
As part of the workflow, you configure DNS provider credentials, register an ACME CA provider with Infisical, and create subscribers to represent the certificates you wish to issue. Each issued certificate is automatically managed through its lifecycle, including renewal before expiration.
We recommend reading about [ACME protocol](https://tools.ietf.org/html/rfc8555) and [DNS-01 challenges](https://letsencrypt.org/docs/challenge-types/#dns-01-challenge) for a fuller understanding of the underlying technology.
## Workflow
A typical workflow for using Infisical with ACME Certificate Authorities consists of the following steps:
1. Setting up AWS Route53 or Cloudflare credentials with appropriate DNS permissions.
2. Creating an AWS/Cloudflare connection in Infisical to store the credentials.
3. Registering an ACME Certificate Authority (like Let's Encrypt) with Infisical.
4. Creating subscribers that use the ACME CA as their issuing authority.
5. Managing certificate lifecycle events such as issuance, renewal, and revocation through Infisical.
## Understanding ACME DNS-01 Challenge
The DNS-01 challenge is the method used by ACME CA providers to verify that you control a domain before issuing a certificate. Here's how Infisical handles this process:
1. **Challenge Request**: When you request a certificate, the ACME provider (like Let's Encrypt) issues a challenge token.
2. **DNS Record Creation**: Infisical creates a TXT record at `_acme-challenge.<YOUR_DOMAIN>` with a value derived from the challenge token.
3. **DNS Propagation**: The TXT record must propagate through the DNS system (usually takes a few minutes, depending on TTL settings).
4. **Validation**: The ACME provider checks for the existence of this TXT record to verify domain control.
5. **Cleanup**: After validation completes successfully, Infisical automatically removes the TXT record from your DNS.
This automated process eliminates the need for manual intervention in domain validation, streamlining certificate issuance.
## Guide
In the following steps, we explore how to set up ACME Certificate Authority integration with Infisical using Let's Encrypt as an example.
<Steps>
<Step title="Create App Connection with Required Permissions">
Before proceeding with the ACME CA registration, you need to set up an App Connection with the appropriate permissions for DNS validation:
<Tabs>
<Tab title="Route53">
1. Navigate to your Organization Settings > App Connections and create a new AWS connection.
2. Ensure your AWS connection has the following minimum permissions for Route53 DNS validation:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "route53:GetChange",
"Resource": "arn:aws:route53:::change/*"
},
{
"Effect": "Allow",
"Action": "route53:ListHostedZonesByName",
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"route53:ListResourceRecordSets"
],
"Resource": [
"arn:aws:route53:::hostedzone/YOUR_HOSTED_ZONE_ID"
]
},
{
"Effect": "Allow",
"Action": [
"route53:ChangeResourceRecordSets"
],
"Resource": [
"arn:aws:route53:::hostedzone/YOUR_HOSTED_ZONE_ID"
],
"Condition": {
"ForAllValues:StringEquals": {
"route53:ChangeResourceRecordSetsRecordTypes": [
"TXT"
]
}
}
}
]
}
```
Replace `YOUR_HOSTED_ZONE_ID` with your actual Route53 hosted zone ID.
For detailed instructions on setting up an AWS connection, see the [AWS Connection](/integrations/app-connections/aws) documentation.
</Tab>
<Tab title="Cloudflare">
1. Navigate to your Organization Settings > App Connections and create a new Cloudflare connection.
2. Ensure your Cloudflare token has the following minimum permissions for DNS validation:
```
Account:Account Settings:Read
Zone:DNS:Edit
```
For detailed instructions on setting up a Cloudflare connection, see the [Cloudflare Connection](/integrations/app-connections/cloudflare) documentation.
</Tab>
</Tabs>
</Step>
<Step title="Register ACME Certificate Authority">
<Tabs>
<Tab title="Infisical UI">
<Steps>
<Step title="Create ACME CA">
To register an ACME CA, head to your Project > Internal PKI > Certificate Authorities and press the **+** button in the External Certificate Authorities section.
![pki register external ca](/images/platform/pki/ca/external-ca/create-external-ca-button.png)
Fill out the details for the ACME CA registration:
![pki register external ca details](/images/platform/pki/ca/external-ca/create-external-ca-form.png)
Here's guidance on each field:
- **Type**: Select "ACME" as the External CA type.
- **Name**: Enter a name for the ACME CA (e.g., "lets-encrypt-production").
- **DNS App Connection**: Select from available DNS app connections or configure a new one. This connection provides Infisical with the credentials needed to create and remove DNS records for ACME validation.
- **Zone ID**: Enter the Zone ID for the domain(s) you'll be requesting certificates for.
- **Directory URL**: Enter the ACME v2 directory URL for your chosen CA provider (e.g., `https://acme-v02.api.letsencrypt.org/directory` for Let's Encrypt).
- **Account Email**: Email address to associate with your ACME account. This email will receive important notifications about your certificates.
- **Enable Direct Issuance**: Toggle on to allow direct certificate issuance without requiring subscribers.
- **EAB Key Identifier (KID)**: (Optional) The Key Identifier (KID) provided by your ACME CA for External Account Binding (EAB). This is required by some ACME providers (e.g., ZeroSSL, DigiCert) to link your ACME account to an external account you've pre-registered with them.
- **EAB HMAC Key**: (Optional) The HMAC Key provided by your ACME CA for External Account Binding (EAB). This key is used in conjunction with the KID to prove ownership of the external account during ACME account registration.
Finally, press **Create** to register the ACME CA with Infisical.
</Step>
<Step title="Verify ACME CA Registration">
Once registered, your ACME CA will appear in the External Certificate Authorities section.
![pki external ca list](/images/platform/pki/ca/external-ca/external-ca-list.png)
From here, you can:
- View the status of the ACME CA registration
- Edit the configuration settings
- Disable or re-enable the ACME CA
- Delete the ACME CA registration if no longer needed
You can now use this ACME CA to issue certificates for your subscribers.
</Step>
</Steps>
</Tab>
<Tab title="API">
To register an ACME CA with Infisical using the API, make a request to the Create External CA endpoint:
### Sample request
```bash Request
curl 'https://app.infisical.com/api/v1/pki/ca/acme' \
-H 'Authorization: Bearer <your-access-token>' \
-H 'Content-Type: application/json' \
--data-raw '{
"projectId": "0fccb6ee-1381-4ff1-8d5f-0cb93c6cc4d6",
"name": "lets-encrypt-production",
"type": "acme",
"status": "active",
"enableDirectIssuance": true,
"configuration": {
"dnsAppConnection": {
"id": "1e5f8c0d-09d2-492c-9b28-469acd8e841b",
"name": "acme-dns-test-connection"
},
"dnsProviderConfig": {
"provider": "route53",
"hostedZoneId": "Z040441124N1GOOMCQYX1"
},
"directoryUrl": "https://acme-v02.api.letsencrypt.org/directory",
"accountEmail": "admin@example.com",
"dnsAppConnectionId": "1e5f8c0d-09d2-492c-9b28-469acd8e841b"
}
}'
```
### Sample response
```bash Response
{
"id": "c48b701e-a20c-4a9a-8119-68f54e5fbb05",
"name": "lets-encrypt-production",
"type": "acme",
"status": "active",
"projectId": "0fccb6ee-1381-4ff1-8d5f-0cb93c6cc4d6",
"enableDirectIssuance": true,
"configuration": {
"accountEmail": "admin@example.com",
"directoryUrl": "https://acme-v02.api.letsencrypt.org/directory",
"dnsAppConnection": {
"id": "1e5f8c0d-09d2-492c-9b28-469acd8e841b",
"name": "acme-dns-test-connection"
},
"dnsAppConnectionId": "1e5f8c0d-09d2-492c-9b28-469acd8e841b",
"dnsProviderConfig": {
"provider": "route53",
"hostedZoneId": "Z040441124N1GOOMCQYX1"
}
}
}
```
</Tab>
</Tabs>
</Step>
<Step title="Create Subscriber for ACME CA">
Next, create a subscriber that uses your ACME CA for certificate issuance. Navigate to your Project > Subscribers and create a new subscriber.
Configure the subscriber with:
- **Issuing CA**: Select your registered ACME CA
- **Common Name**: The domain for which you want to issue certificates (e.g., `example.com`)
- **Alternative Names**: Additional domains to include in the certificate
Check out the [Subscribers](/documentation/platform/pki/subscribers) page for detailed instructions on creating and managing subscribers.
</Step>
<Step title="Issue Certificate">
Once your subscriber is configured, you can issue certificates either through the Infisical UI or programmatically via the API.
When you request a certificate:
1. Infisical generates a key pair for the certificate
2. Sends a Certificate Signing Request (CSR) to the ACME CA
3. Receives a DNS-01 challenge from the ACME provider
4. Creates a TXT record in Route53/Cloudflare to satisfy the challenge
5. Notifies the ACME provider that the challenge is ready for validation
6. Once validated, the ACME provider issues the certificate
7. Infisical stores and manages the certificate for your subscriber
The certificate will be automatically renewed before expiration according to your subscriber configuration.
</Step>
<Step title="Use Certificate in Your Applications">
The issued certificate and private key are now available through Infisical and can be:
- Downloaded directly from the Infisical UI
- Retrieved via the Infisical API for programmatic access using the [latest certificate bundle endpoint](/api-reference/endpoints/pki/subscribers/get-latest-cert-bundle)
</Step>
</Steps>
## Example: Let's Encrypt Integration
Let's Encrypt is a free, automated, and open Certificate Authority that provides domain-validated SSL/TLS certificates. Here's how the integration works with Infisical:
### Production Environment
- **Directory URL**: `https://acme-v02.api.letsencrypt.org/directory`
- **Rate Limits**: 50 certificates per registered domain per week
- **Certificate Validity**: 90 days with automatic renewal
- **Trusted By**: All major browsers and operating systems
### Staging Environment (for testing)
- **Directory URL**: `https://acme-staging-v02.api.letsencrypt.org/directory`
- **Rate Limits**: Much higher limits for testing
- **Certificate Validity**: 90 days (not trusted by browsers)
- **Use Case**: Testing your ACME integration without hitting production rate limits
<Note>
Always test your ACME integration using Let's Encrypt's staging environment
first. This allows you to verify your DNS configuration and certificate
issuance process without consuming your production rate limits.
</Note>
## Example: DigiCert Integration
DigiCert is a leading commercial Certificate Authority providing a wide range of trusted SSL/TLS certificates. Infisical can integrate with [DigiCert's ACME](https://docs.digicert.com/en/certcentral/certificate-tools/certificate-lifecycle-automation-guides/third-party-acme-integration/request-and-manage-certificates-with-acme.html) service to automate the provisioning and management of these certificates.
- **Directory URL**: `https://acme.digicert.com/v2/acme/directory`
- **External Account Binding (EAB)**: Required. You will need a Key Identifier (KID) and HMAC Key from your DigiCert account to register the ACME CA in Infisical.
- **Certificate Validity**: Typically 90 days, with automatic renewal through Infisical.
- **Trusted By**: All major browsers and operating systems.
<Note>
When integrating with DigiCert ACME, ensure you have obtained the necessary
External Account Binding (EAB) Key Identifier (KID) and HMAC Key from your
DigiCert account.
</Note>
## FAQ
<AccordionGroup>
<Accordion title="What DNS validation methods are supported?">
Currently, Infisical supports DNS-01 validation through AWS Route53 or Cloudflare. The DNS-01 challenge method is preferred for ACME integrations because it:
- Works with wildcard certificates
- Doesn't require your servers to be publicly accessible
- Can be fully automated without manual intervention
Support for additional DNS providers is planned for future releases.
</Accordion>
<Accordion title="Can I use wildcard certificates with ACME CAs?">
Yes! ACME CAs like Let's Encrypt support wildcard certificates (e.g., `*.example.com`) when using DNS-01 validation. Simply specify the wildcard domain in your subscriber configuration.
Note that wildcard certificates still require DNS-01 validation - HTTP-01 validation cannot be used for wildcard certificates.
</Accordion>
<Accordion title="How long are ACME certificates valid?">
Most ACME providers issue certificates with 90-day validity periods. This shorter validity period is designed to:
- Encourage automation of certificate management
- Reduce the impact of compromised certificates
- Ensure systems stay up-to-date with certificate management practices
When configured, Infisical automatically handles certificate renewal for subscribers.
</Accordion>
<Accordion title="Can I use multiple ACME providers?">
Yes! You can register multiple ACME CAs in the same project:
- Different providers for different domains or use cases
- Staging and production environments for the same provider
- Backup providers for redundancy
Each subscriber can be configured to use a specific ACME CA based on your requirements.
</Accordion>
</AccordionGroup>

212
docs/documentation/platform/pki/ca/azure-adcs.mdx Normal file
View File

@@ -0,0 +1,212 @@
---
title: "Azure ADCS"
description: "Learn how to issue and manage certificates using Microsoft Active Directory Certificate Services (ADCS) with Infisical."
---
Issue and manage certificates using Microsoft Active Directory Certificate Services (ADCS) for enterprise-grade certificate management integrated with your existing Windows infrastructure.
## Prerequisites
Before setting up ADCS integration, ensure you have:
- Microsoft Active Directory Certificate Services (ADCS) server running and accessible
- Domain administrator account with certificate management permissions
- ADCS web enrollment enabled on your server
- Network connectivity from Infisical to the ADCS server
- **IP whitelisting**: Your ADCS server must allow connections from Infisical's IP addresses
- For Infisical Cloud instances, see [Networking Configuration](/documentation/setup/networking) for the list of IPs to whitelist
- For self-hosted instances, whitelist your Infisical server's IP address
- Azure ADCS app connection configured (see [Azure ADCS Connection](/integrations/app-connections/azure-adcs))
## Complete Workflow: From Setup to Certificate Issuance
This section walks you through the complete end-to-end process of setting up Azure ADCS integration and issuing your first certificate.
<Steps>
<Step title="Navigate to External Certificate Authorities">
In your Infisical project, go to your **Certificate Project** →
**Certificate Authority** to access the external CAs page. ![External CA
Page](/images/platform/pki/azure-adcs/azure-adcs-external-ca-page.png)
</Step>
<Step title="Create New Azure ADCS Certificate Service CA">
Click **Create CA** and configure: - **Type**: Choose **Azure AD Certificate
Service** - **Name**: Friendly name for this CA (e.g., "Production ADCS CA") -
**App Connection**: Choose your ADCS connection from the dropdown ![External
CA Form](/images/platform/pki/azure-adcs/azure-adcs-external-ca-form.png)
</Step>
<Step title="Certificate Authority Created">
Once created, your Azure ADCS Certificate Authority will appear in the list
and be ready for use. ![External CA
Created](/images/platform/pki/azure-adcs/azure-adcs-external-ca-created.png)
</Step>
<Step title="Navigate to Subscribers">
Go to **Subscribers** to access the subscribers page. ![Subscribers
Page](/images/platform/pki/azure-adcs/azure-adcs-subscribers-page.png)
</Step>
<Step title="Create New Subscriber">
Click **Add Subscriber** and configure: - **Name**: Unique subscriber name
(e.g., "web-server-certs") - **Certificate Authority**: Select your ADCS CA -
**Common Name**: Certificate CN (e.g., "api.example.com") - **Certificate
Template**: Select from dynamically loaded ADCS templates - **Subject
Alternative Names**: DNS names, IP addresses, or email addresses - **TTL**:
Certificate validity period (e.g., "1y" for 1 year) - **Additional Subject
Fields**: Organization, OU, locality, state, country, email (if required by
template) ![Subscribers
Form](/images/platform/pki/azure-adcs/azure-adcs-subscribers-form.png)
</Step>
<Step title="Subscriber Created">
Your subscriber is now created and ready to issue certificates. ![Subscriber
Created](/images/platform/pki/azure-adcs/azure-adcs-subscribers-created.png)
</Step>
<Step title="Issue New Certificate">
Click into your subscriber and click **Order Certificate** to generate a new
certificate using your ADCS template. ![Issue New
Certificate](/images/platform/pki/azure-adcs/azure-adcs-subscriber-issue-new-certificate.png)
</Step>
<Step title="Certificate Created">
Your certificate has been successfully issued by the ADCS server and is ready
for use. ![Certificate
Created](/images/platform/pki/azure-adcs/azure-adcs-certificate-created.png)
</Step>
<Step title="View Certificate Details">
Navigate to **Certificates** to view detailed information about all issued
certificates, including expiration dates, serial numbers, and certificate
chains. ![Certificates
Page](/images/platform/pki/azure-adcs/azure-adcs-certificates-page.png)
</Step>
</Steps>
## Certificate Templates
Infisical automatically retrieves available certificate templates from your ADCS server, ensuring you can only select templates that are properly configured and accessible. The system dynamically discovers templates during the certificate authority setup and certificate issuance process.
### Common Template Types
ADCS templates you might see include:
- **Web Server**: For SSL/TLS certificates with server authentication
- **Computer**: For machine authentication certificates
- **User**: For client authentication certificates
- **Basic EFS**: For Encrypting File System certificates
- **EFS Recovery Agent**: For EFS data recovery
- **Administrator**: For administrative certificates
- **Subordinate Certification Authority**: For issuing CA certificates
### Template Requirements
Ensure your ADCS templates are configured with:
- **Enroll permissions** for your connection account
- **Auto-enroll permissions** if using automated workflows
- **Subject name requirements** matching your certificate requests
- **Key usage extensions** appropriate for your use case
<Info>
**Dynamic Template Discovery**: Infisical queries your ADCS server in
real-time to populate available templates. Only templates you have permission
to use will be displayed during certificate issuance.
</Info>
## Certificate Issuance Limitations
### Immediate Issuance Only
<Warning>
**Manual Approval Not Supported**: Infisical currently supports only
**immediate certificate issuance**. Certificates that require manual approval
or are held by ADCS policies cannot be issued through Infisical yet.
</Warning>
For successful certificate issuance, ensure your ADCS templates and policies are configured to:
- **Auto-approve** certificate requests without manual intervention
- **Not require** administrator approval for the templates you plan to use
- **Allow** the connection account to request and receive certificates immediately
### What Happens with Manual Approval
If a certificate request requires manual approval:
1. The request will be submitted to ADCS successfully
2. Infisical will attempt to retrieve the certificate with exponential backoff (up to 5 retries over ~1 minute)
3. If the certificate is not approved within this timeframe, the request will **fail**
4. **No background polling**: Currently, Infisical does not check for certificates that might be approved hours or days later
<Info>
**Future Enhancement**: Background polling for delayed certificate approvals
is planned for future releases.
</Info>
### Certificate Revocation
<Warning>
Certificate revocation is **not supported** by the Azure ADCS connector due to
security and complexity considerations.
</Warning>
## Advanced Configuration
### Custom Validity Periods
Enable custom certificate validity periods on your ADCS server:
```cmd
# Run on ADCS server as Administrator
certutil -setreg policy\EditFlags +EDITF_ATTRIBUTEENDDATE
net stop certsvc
net start certsvc
```
This allows Infisical to control certificate expiration dates directly.
## Troubleshooting
### Common Issues
**Certificate Request Denied**
- Verify ADCS template permissions for your connection account
- Check template subject name requirements
- Ensure template allows the requested key algorithm and size
**Revocation Service Unavailable**
- Verify IIS is running and the revocation endpoint is accessible
- Check IIS application pool permissions
- Test endpoint connectivity from Infisical
**Template Not Found**
- Verify template exists on ADCS server and is published
- Check that your connection account has enrollment permissions for the template
- Ensure the template is properly configured and available in the ADCS web enrollment interface
- Templates are dynamically loaded - refresh the PKI Subscriber form if templates don't appear
**Certificate Request Pending/Timeout**
- Check if your ADCS template requires manual approval - Infisical only supports immediate issuance
- Verify the certificate template is configured for auto-approval
- Ensure your connection account has sufficient permissions to request certificates without approval
- Review ADCS server policies that might be holding the certificate request
**Network Connectivity Issues**
- Verify your ADCS server's firewall allows connections from Infisical
- For Infisical Cloud: Ensure Infisical's IP addresses are whitelisted (see [Networking Configuration](/documentation/setup/networking))
- For self-hosted: Whitelist your Infisical server's IP address on the ADCS server
- Test HTTPS connectivity to the ADCS web enrollment endpoint
- Check for any network security appliances blocking the connection
**Authentication Failures**
- Verify ADCS connection credentials
- Check domain account permissions
- Ensure network connectivity to ADCS server
**SSL/TLS Certificate Errors**
- For ADCS servers with self-signed or private certificates: disable "Reject Unauthorized" in the SSL tab of your Azure ADCS app connection, or provide the certificate in PEM format
- Common SSL errors: `UNABLE_TO_VERIFY_LEAF_SIGNATURE`, `SELF_SIGNED_CERT_IN_CHAIN`, `CERT_HAS_EXPIRED`
- The SSL configuration applies to all HTTPS communications between Infisical and your ADCS server
- Only HTTPS URLs are supported - HTTP connections are not allowed for security reasons

50
docs/documentation/platform/pki/ca/external-ca.mdx Normal file
View File

@@ -0,0 +1,50 @@
---
title: "External CA"
sidebarTitle: "External CA"
description: "Learn how to connect External Certificate Authorities with Infisical."
---
## Concept
Infisical lets you integrate with External Certificate Authorities (CAs), allowing you to use existing PKI infrastructure or connect to public CAs to issue digital certificates for your end-entities.
<div align="center">
```mermaid
graph TD
A1[External Public CA<br>e.g. Let's Encrypt, ZeroSSL, ...] --> Infisical
A2[External Private CA<br>e.g. AWS Private CA, HashiCorp Vault PKI, ...] --> Infisical
```
</div>
As shown above, these CAs commonly fall under two categories:
- External Private CAs: CAs like AWS Private CA, HashiCorp Vault PKI, Azure ADCS, etc. that are privately owned and are used to issue certificates for internal services; these are often either cloud-hosted private CAs or on-prem / enterprise CAs.
- External Public CAs: CAs like Let's Encrypt, DigiCert, GlobalSign, etc. that are publicly trusted and are used to issue certificates for public-facing services.
Note that Infisical can also act as an _ACME client_, allowing you to integrate upstream with any ACME-compatible CA to automate certificate issuance and renewal.
## Workflow
A typical workflow for integrating an External CA with Infisical consists of choosing the desired External CA type
and specifying the configuration or connection details necessary to connect to the CA.
The specific steps and requirements vary depending on the External CA type you choose to integrate.
## Supported External CA Types
Infisical currently supports the following External CA types out of the box:
- [ACME CA](/documentation/platform/pki/ca/acme-ca): An ACME-compatible CA that supports the ACME protocol, such as Let's Encrypt, ZeroSSL, Buypass, Digicert, etc.
- [Azure ADCS](/documentation/platform/pki/ca/azure-adcs): A Microsoft Active Directory Certificate Services (ADCS) that supports the ADCS protocol, such as AWS Private CA, Azure ADCS, etc.
If you don’t see a specific external CA listed here or need a dedicated integration guide, please reach out to sales@infisical.com and we’ll help you set up the integration for your external CA.
## FAQ
<AccordionGroup>
<Accordion title="Can I use both Private CAs and External CAs in the same project?">
Yes. You can have both Private and External CAs in the same project.
</Accordion>
</AccordionGroup>

13
docs/documentation/platform/pki/ca/overview.mdx Normal file
View File

@@ -0,0 +1,13 @@
---
title: "Overview"
sidebarTitle: "Overview"
---
Before issuing and managing certificates with Infisical, you'll need to configure a Certificate Authority (CA).
This is the trusted entity that signs and validates the X.509 certificates used to secure your end-entities.
Infisical supports two categories of CAs:
- [Internal CA](/documentation/platform/pki/ca/private-ca): Internally operated root and intermediate CAs managed within Infisical. This is useful if you need complete control over your PKI and are issuing certificates for private networks, internal services, or managed devices.
- [External CA](/documentation/platform/pki/ca/external-ca): Third-party public (e.g. Let's Encrypt, DigiCert) or private (e.g. AWS Private CA, HashiCorp Vault PKI, etc.) CAs that can be integrated with Infisical. This is useful if you want to leverage existing PKI infrastructure or issue publicly trusted certificates.

334
docs/documentation/platform/pki/ca/private-ca.mdx Normal file
View File

@@ -0,0 +1,334 @@
---
title: "Internal CA"
sidebarTitle: "Internal CA"
description: "Learn how to create a Private CA hierarchy with Infisical."
---
## Concept
Infisical lets you build your Internal PKI through a Private Certificate Authority (CA) hierarchy, enabling you to issue and manage digital certificates for your end-entities.
<div align="center">
```mermaid
graph TD
A[Root CA]
A --> B[Intermediate CA]
A --> C[Intermediate CA]
```
</div>
## Workflow
A typical workflow for setting up a Private CA hierarchy consists of the following steps:
1. Configuring an Infisical root CA with details like name, validity period, and path length — This step is optional if you wish to use an external root CA with Infisical only serving the intermediate CAs.
2. Configuring and chaining intermediate CA(s) with details like name, validity period, path length, and imported certificate to your Root CA.
3. Managing the CA lifecycle events such as CA succession.
<Note>
Note that this workflow can be executed via the Infisical UI or manually such
as via API. If manually executing the workflow, you may have to create a
Certificate Signing Request (CSR) for the intermediate CA, create an
intermediate certificate using the root CA private key and CSR, and import the
intermediate certificate back to the intermediate CA as part of Step 2.
</Note>
## Guide to Creating a CA Hierarchy
In the following steps, we explore how to create a simple Private CA hierarchy
consisting of an (optional) root CA and an intermediate CA.
<Tabs>
<Tab title="Infisical UI">
<Steps>
<Step title="Creating a root CA">
If you wish to use an external root CA, you can skip this step and head to step 2 to create an intermediate CA.
To create a root CA, head to your Certificate Management Project > Certificate Authorities > Internal Certificate Authorities and press **Create CA**.
![pki create ca](/images/platform/pki/ca/ca-create.png)
Here, set the **CA Type** to **Root** and fill out details for the root CA.
![pki create root ca](/images/platform/pki/ca/ca-create-root.png)
Here's some guidance for each field:
- Valid Until: The date until which the CA is valid in the date time string format specified [here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#date_time_string_format). For example, the following formats would be valid: `YYYY`, `YYYY-MM`, `YYYY-MM-DD`, `YYYY-MM-DDTHH:mm:ss.sssZ`.
- Path Length: The maximum number of intermediate CAs that can be chained to this CA. A path of `-1` implies no limit; a path of `0` implies no intermediate CAs can be chained.
- Key Algorithm: The type of public key algorithm and size, in bits, of the key pair that the CA creates when it issues a certificate. Supported key algorithms are `RSA 2048`, `RSA 4096`, `ECDSA P-256`, and `ECDSA P-384` with the default being `RSA 2048`.
- Name: A slug-friendly name for the CA.
- Organization (O): The organization name.
- Country (C): The country code.
- State or Province Name: The state or province.
- Locality Name: The city or locality.
- Common Name: The name of the CA.
<Note>
The Organization, Country, State or Province Name, Locality Name, and Common Name make up the **Distinguished Name (DN)** or **subject** of the CA.
At least one of these fields must be filled out.
</Note>
</Step>
<Step title="Creating an intermediate CA">
2.1. To create an intermediate CA, press **Create CA** again but this time specifying the **CA Type** to be **Intermediate**. Fill out the details for the intermediate CA.
![pki create intermediate ca](/images/platform/pki/ca/ca-create-intermediate.png)
2.2. Next, press the **Install Certificate** option on the intermediate CA from step 1.1.
![pki install cert opt](/images/platform/pki/ca/ca-install-intermediate-opt.png)
2.3a. If you created a root CA in step 1, select **Infisical CA** for the **Parent CA Type** field.
Next, set the **Parent CA** to the root CA created in step 1 and configure the intended **Valid Until** and **Path Length** fields on the intermediate CA; feel free to use the prefilled values.
![pki install cert](/images/platform/pki/ca/ca-install-intermediate.png)
Here's some guidance on each field:
- Parent CA: The parent CA to which this intermediate CA will be chained. In this case, it should be the root CA created in step 1.
- Valid Until: The date until which the CA is valid in the date time string format specified [here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#date_time_string_format). The date must be within the validity period of the parent CA.
- Path Length: The maximum number of intermediate CAs that can be chained to this CA. The path length must be less than the path length of the parent CA.
Finally, press **Install** to chain the intermediate CA to the root CA; this creates a Certificate Signing Request (CSR) for the intermediate CA, creates an intermediate certificate using the root CA private key and CSR, and imports the signed certificate back to the intermediate CA.
![pki cas](/images/platform/pki/ca/cas.png)
Great! You've successfully created a Private CA hierarchy with a root CA and an intermediate CA. Now check out the Certificates section to learn more about how to issue X.509 certificates using the intermediate CA.
2.3b. If you have an external root CA, select **External CA** for the **Parent CA Type** field.
Next, use the provided intermediate CSR to generate a certificate from your external root CA and paste the PEM-encoded certificate back into the **Certificate Body** field; the PEM-encoded external root CA certificate should be pasted under the **Certificate Chain** field.
![pki ca csr](/images/platform/pki/ca/ca-install-intermediate-csr.png)
Finally, press **Install** to import the certificate and certificate chain as part of the installation step for the intermediate CA
Great! You've successfully created a Private CA hierarchy with an intermediate CA chained to an external root CA.
Now check out the [Subscribers](/documentation/platform/pki/subscribers) page to learn more about how to issue X.509 certificates using the intermediate CA.
</Step>
</Steps>
</Tab>
<Tab title="API">
<Steps>
<Step title="Creating a root CA">
If you wish to use an external root CA, you can skip this step and head to step 2 to create an intermediate CA.
To create a root CA, make an API request to the [Create CA](/api-reference/endpoints/certificate-authorities/create) API endpoint, specifying the `type` as `root`.
### Sample request
```bash Request
curl --location --request POST 'https://app.infisical.com/api/v1/pki/ca' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"projectSlug": "<your-project-slug>",
"type": "root",
"commonName": "My Root CA"
}'
```
### Sample response
```bash Response
{
ca: {
id: "<root-ca-id>",
type: "root",
commonName: "My Root CA",
...
}
}
```
By default, Infisical creates a root CA with the `RSA_2048` key algorithm, validity period of 10 years, with no restrictions on path length;
you may override these defaults by specifying your own options when making the API request.
</Step>
<Step title="Creating an intermediate CA">
2.1. To create an intermediate CA, make an API request to the [Create CA](/api-reference/endpoints/certificate-authorities/create) API endpoint, specifying the `type` as `intermediate`.
### Sample request
```bash Request
curl --location --request POST 'https://app.infisical.com/api/v1/pki/ca' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"projectSlug": "<your-project-slug>",
"type": "intermediate",
"commonName": "My Intermediate CA"
}'
```
### Sample response
```bash Response
{
ca: {
id: "<intermediate-ca-id>",
type: "intermediate",
commonName: "My Intermediate CA",
...
}
}
```
2.2. Next, get a certificate signing request from the intermediate CA by making an API request to the [Get CSR](/api-reference/endpoints/certificate-authorities/csr) API endpoint.
### Sample request
```bash Request
curl --location --request GET 'https://app.infisical.com/api/v1/pki/ca/<intermediate-ca-id>/csr' \
--header 'Authorization: Bearer <access-token>' \
--data-raw ''
```
### Sample response
```bash Response
{
csr: "..."
}
```
If using an external root CA, then use the CSR to generate a certificate for the intermediate CA using your external root CA and skip to step 2.4.
2.3. Next, create an intermediate certificate by making an API request to the [Sign Intermediate](/api-reference/endpoints/certificate-authorities/sign-intermediate) API endpoint
containing the CSR from step 2.2, referencing the root CA created in step 1.
### Sample request
```bash Request
curl --location --request POST 'https://app.infisical.com/api/v1/pki/ca/<root-ca-id>/sign-intermediate' \
--header 'Content-Type: application/json' \
--data-raw '{
"csr": "<csr>",
"notAfter": "2029-06-12"
}'
```
### Sample response
```bash Response
{
certificate: "...",
certificateChain: "...",
issuingCaCertificate: "...",
serialNumber: "...",
}
```
<Note>
The `notAfter` value must be within the validity period of the root CA that is if the root CA is valid until `2029-06-12`, the intermediate CA must be valid until a date before `2029-06-12`.
</Note>
2.4. Finally, import the intermediate certificate and certificate chain from step 2.3 back to the intermediate CA by making an API request to the [Import Certificate](/api-reference/endpoints/certificate-authorities/import-cert) API endpoint.
If using an external root CA, then import the generated certificate and root CA certificate under certificate chain back into the intermediate CA.
### Sample request
```bash Request
curl --location --request POST 'https://app.infisical.com/api/v1/pki/ca/<intermediate-ca-id>/import-certificate' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"certificate": "<certificate>",
"certificateChain": "<certificate-chain>"
}'
```
### Sample response
```bash Response
{
message: "Successfully imported certificate to CA",
caId: "..."
}
```
Great! You’ve successfully created a Private CA hierarchy with a root CA and an intermediate CA. Now check out the [Subscribers](/documentation/platform/pki/subscribers) page to learn more about how to issue X.509 certificates using the intermediate CA.
</Step>
</Steps>
</Tab>
</Tabs>
## Guide to CA Renewal
In the following steps, we explore how to renew a CA certificate.
<Note>
If renewing an intermediate CA chained to an Infisical CA, then Infisical will
automate the process of generating a new certificate for the intermediate CA for you.
If renewing an intermediate CA chained to an external parent CA, you'll be
required to generate a new certificate from the external parent CA and manually import
the certificate back to the intermediate CA.
</Note>
<Tabs>
<Tab title="Infisical UI">
Head to the CA Page of the CA you wish you renew and press **Renew CA** on
the left side. ![pki ca renewal
page](/images/platform/pki/ca-renewal-page.png) Input a new **Valid Until**
date to be used for the renewed CA certificate and press **Renew** to renew
the CA. ![pki ca renewal. modal](/images/platform/pki/ca-renewal-modal.png)
<Note>
The new **Valid Until** date must be within the validity period of the
parent CA.
</Note>
</Tab>
<Tab title="API">
To renew a CA certificate, make an API request to the [Renew CA](/api-reference/endpoints/certificate-authorities/renew) API endpoint, specifying the new `notAfter` date for the CA.
### Sample request
```bash Request
curl --location --request POST 'https://app.infisical.com/api/v1/pki/ca/<ca-id>/renew' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"type": "existing",
"notAfter": "2029-06-12"
}'
```
### Sample response
```bash Response
{
certificate: "...",
certificateChain: "...",
serialNumber: "..."
}
```
</Tab>
</Tabs>
## FAQ
<AccordionGroup>
<Accordion title="What key algorithms are supported as part of private key generation and certificate signing?">
Infisical supports `RSA 2048`, `RSA 4096`, `ECDSA P-256`, `ECDSA P-384` key
algorithms specified at the time of creating a CA.
</Accordion>
<Accordion title="Does Infisical support CA renewal via new key pair">
At the moment, Infisical only supports CA renewal via same key pair. We
anticipate supporting CA renewal via new key pair in the coming month.
</Accordion>
<Accordion title="Does Infisical support chaining an Intermediate CA to an external CA?">
Yes. You may obtain a CSR from the Intermediate CA and use it to generate a
certificate from your external CA. The certificate, along with the external
CA certificate chain, can be imported back to the Intermediate CA as part of
the CA installation step.
</Accordion>
</AccordionGroup>