github/infisical
1
0
Fork 0
mirror of https://github.com/Infisical/infisical.git synced 2026-01-09 07:28:09 -05:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #4866 from Infisical/feat/pkiIntegrationDocs

Browse Source 
Add PKI docs for ACME Infrastructure Integrations
This commit is contained in:
BlackMagiq
2025-11-14 04:18:09 -05:00
committed by GitHub
parent 6b30c9faef d770e0d9df
commit 627e6c87f3
9 changed files with 1037 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
docs/docs.json
View File

@@ -752,7 +752,12 @@
"group": "Infrastructure Integrations",
"pages": [
"documentation/platform/pki/pki-issuer",
"documentation/platform/pki/integration-guides/gloo-mesh"
"documentation/platform/pki/integration-guides/gloo-mesh",
"documentation/platform/pki/integration-guides/windows-server-acme",
"documentation/platform/pki/integration-guides/nginx-certbot",
"documentation/platform/pki/integration-guides/apache-certbot",
"documentation/platform/pki/integration-guides/tomcat-certbot",
"documentation/platform/pki/integration-guides/jboss-certbot"
]
},
{

185
docs/documentation/platform/pki/integration-guides/apache-certbot.mdx Normal file
View File

@@ -0,0 +1,185 @@
---
title: "Apache Server"
description: "Learn how to issue SSL/TLS certificates from Infisical using ACME enrollment on Apache Server with Certbot"
---
This guide demonstrates how to use Infisical to issue SSL/TLS certificates for your [Apache HTTP Server](https://httpd.apache.org/).
It uses [Certbot](https://certbot.eff.org/), an installable [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) client, to request and renew certificates from Infisical using the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme) configured on a [certificate profile](/documentation/platform/pki/certificates/profiles). Apache benefits from excellent Certbot integration, allowing both certificate-only mode and automatic SSL configuration.
## Prerequisites
Before you begin, make sure you have:
- An [Apache HTTP Server](https://httpd.apache.org/) running on a Linux system with administrative access.
- A [certificate profile](/documentation/platform/pki/certificates/profiles) configured with the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme) in Infisical.
- Network connectivity from your Apache server to Infisical.
- Port 80 open and reachable for ACME [HTTP-01](https://letsencrypt.org/docs/challenge-types/#http-01-challenge) validation.
## Guide
<Steps>
<Step title="Obtain ACME Configuration from Infisical">
Navigate to your certificate management project in Infisical and locate your [certificate profile](/documentation/platform/pki/certificates/profiles) configured with the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme).
![Certificate profile with ACME enrollment option](/images/platform/pki/acme/certificate-profile-acme-option.png)
Click the **Reveal ACME EAB** option to view the ACME configuration details.
![ACME configuration modal showing directory URL and EAB credentials](/images/platform/pki/acme/acme-configuration-modal.png)
From the ACME configuration, gather the following values:
- ACME Directory URL: The URL that Certbot will use to communicate with Infisical's ACME server. This takes the form `https://your-infisical-instance.com/api/v1/pki/certificate-profiles/{profile-id}/acme/directory`.
- EAB Key Identifier (KID): A unique identifier that tells Infisical which ACME account is making the request.
- EAB Secret: A secret key that authenticates your ACME client with Infisical.
<Note>
Keep your EAB credentials secure as they authenticate your ACME client with Infisical PKI. These credentials are unique to each [certificate profile](/documentation/platform/pki/certificates/profiles) and should not be shared.
</Note>
</Step>
<Step title="Install Certbot">
Install Certbot with the Apache plugin on the server where Apache is running by following the official Certbot [installation guide](https://certbot.eff.org/instructions).
The installation guide provides up-to-date instructions for various Linux distributions and package managers, ensuring you get the most current version and proper Apache plugin integration.
After installation, you can verify that Certbot has been installed correctly by running:
```bash
certbot --version
```
</Step>
<Step title="Request Certificate Using Certbot">
Run the following command to request a certificate from Infisical:
```bash
sudo certbot certonly \
--apache \
--server "https://your-infisical-instance.com/api/v1/pki/certificate-profiles/{profile-id}/acme/directory" \
--eab-kid "your-eab-key-identifier" \
--eab-hmac-key "your-eab-secret" \
-d example.infisical.com \
--email admin@example.com \
--agree-tos \
--non-interactive
```
For guidance on each parameter:
- `certonly`: Instructs Certbot to request a certificate without modifying your Apache configuration files; this mode is recommended if you prefer to manage your Apache SSL configuration manually or have a complex setup.
- `--apache`: Specifies the Apache plugin so Certbot can solve the [HTTP-01](https://letsencrypt.org/docs/challenge-types/#http-01-challenge) challenge by creating temporary files served by Apache.
- `--server`: The Infisical ACME directory URL from Step 1. This instructs Certbot to communicate with Infisical's ACME server instead of Let's Encrypt.
- `--eab-kid`: Your External Account Binding (EAB) Key Identifier from Step 1.
- `--eab-hmac-key`: The EAB secret associated with the KID from Step 1.
- `-d`: Specifies the domain name for which the certificate is being requested.
- `--email`: The contact email for expiration notices and account recovery.
- `--agree-tos`: Accepts the ACME server's Terms of Service.
- `--non-interactive`: Runs Certbot without prompting for user input (recommended for automation).
The Certbot command generates a private key on your server, creates a Certificate Signing Request (CSR) using that key, and sends the CSR to Infisical for certificate issuance. Certbot stores the private key and resulting leaf certificate and full certificate chain in `/etc/letsencrypt/live/{domain-name}/`.
If `--certonly` is used: Certbot does **not** modify your Apache configuration, so you must manually update your Apache virtual host to reference the new certificate files and reload the server to apply the changes.
Here's an example SSL virtual host configuration for Apache:
```apache
<VirtualHost *:443>
ServerName example.infisical.com
DocumentRoot /var/www/html
SSLEngine on
SSLCertificateFile /etc/letsencrypt/live/example.infisical.com/cert.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.infisical.com/privkey.pem
SSLCertificateChainFile /etc/letsencrypt/live/example.infisical.com/chain.pem
# Your existing configuration...
</VirtualHost>
```
After updating the virtual host configuration, test and reload Apache to apply the changes:
```bash
sudo apache2ctl configtest
sudo systemctl reload apache2
```
If `--certonly` was **not** used: Certbot uses installer mode, which attempts to automatically configure HTTPS by updating your Apache virtual host configuration and reloading the server if needed.
At this point, your Apache server should be successfully serving HTTPS using the certificate issued by Infisical.
</Step>
<Step title="Verify Certificate Installation">
After configuring Apache SSL, verify that your certificate was issued correctly and Apache is serving it properly.
Check that the certificate files were created by Certbot:
```bash
sudo ls -la /etc/letsencrypt/live/example.infisical.com/
```
You should see files like:
- `cert.pem` (your certificate)
- `chain.pem` (certificate chain)
- `fullchain.pem` (certificate + chain)
- `privkey.pem` (private key)
</Step>
<Step title="Renew Your Certificate with Certbot">
Certbot automatically installs a `systemd` timer during installation. This timer runs twice per day and checks whether any certificates are due for renewal. Because Certbot stores the ACME server URL and EAB credentials from your initial request, renewal will automatically use the same Infisical ACME configuration—no additional settings are required.
Note that Certbot automatically renews certificates when they are within 30 days of expiration; renewal settings can be adjusted in `/etc/letsencrypt/renewal/{domain-name}.conf`.
```ini
# ... your existing configuration ...
renew_before_expiry = 30 days
```
To test the renewal process, run the following command:
```bash
sudo certbot renew --dry-run
```
This command simulates the full renewal process without modifying your active certificate. If the dry run succeeds, automatic renewal will work as expected.
To trigger an actual renewal immediately, run the following command:
```bash
sudo certbot renew --force-renewal
```
Note that after a certificate is renewed, Apache must be reloaded so it can begin using the new certificate. To do this, run the following command:
```bash
sudo systemctl reload apache2
```
To automate the process of renewing a certificate and reloading Apache, you can create a simple deploy hook that Certbot will run after every successful renewal.
Inside `/etc/letsencrypt/renewal-hooks/deploy/reload-apache.sh`, add the following:
```bash
#!/bin/sh
systemctl reload apache2
```
Then make the hook executable:
```bash
sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/reload-apache.sh
```
Alternatively, you can use the `--post-hook` option when manually renewing:
```bash
sudo certbot renew --post-hook "systemctl reload apache2"
```
<Note>
Certbot automatically renews certificates when they are within 30 days of expiration using its built-in systemd timer. The deploy hook above will run after each successful renewal, handling the Apache reload automatically. Apache has native Certbot plugin integration, so no additional configuration is typically needed.
</Note>
</Step>
</Steps>

226
docs/documentation/platform/pki/integration-guides/jboss-certbot.mdx Normal file
View File

@@ -0,0 +1,226 @@
---
title: "JBoss/WildFly"
description: "Learn how to issue SSL/TLS certificates from Infisical using ACME enrollment on JBoss/WildFly with Certbot"
---
This guide demonstrates how to use Infisical to issue SSL/TLS certificates for your [JBoss](https://www.jboss.org/)/[WildFly](https://wildfly.org/) application server.
It uses [Certbot](https://certbot.eff.org/), an installable [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) client, to request and renew certificates from Infisical using the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme) configured on a [certificate profile](/documentation/platform/pki/certificates/profiles). JBoss/WildFly requires certificates in Java keystore format, which this guide addresses through the certificate conversion process.
## Prerequisites
Before you begin, make sure you have:
- A [JBoss](https://www.jboss.org/)/[WildFly](https://wildfly.org/) application server running on a Linux system with administrative access.
- A [certificate profile](/documentation/platform/pki/certificates/profiles) configured with the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme) in Infisical.
- Network connectivity from your JBoss/WildFly server to Infisical.
- Port 80 open and reachable for ACME [HTTP-01](https://letsencrypt.org/docs/challenge-types/#http-01-challenge) validation.
- [Java Development Kit (JDK)](https://openjdk.org/) installed for keystore management tools.
## Guide
<Steps>
<Step title="Obtain ACME Configuration from Infisical">
Navigate to your certificate management project in Infisical and locate your [certificate profile](/documentation/platform/pki/certificates/profiles) configured with the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme).
![Certificate profile with ACME enrollment option](/images/platform/pki/acme/certificate-profile-acme-option.png)
Click the **Reveal ACME EAB** option to view the ACME configuration details.
![ACME configuration modal showing directory URL and EAB credentials](/images/platform/pki/acme/acme-configuration-modal.png)
From the ACME configuration, gather the following values:
- ACME Directory URL: The URL that Certbot will use to communicate with Infisical's ACME server. This takes the form `https://your-infisical-instance.com/api/v1/pki/certificate-profiles/{profile-id}/acme/directory`.
- EAB Key Identifier (KID): A unique identifier that tells Infisical which ACME account is making the request.
- EAB Secret: A secret key that authenticates your ACME client with Infisical.
<Note>
Keep your EAB credentials secure as they authenticate your ACME client with Infisical PKI. These credentials are unique to each [certificate profile](/documentation/platform/pki/certificates/profiles) and should not be shared.
</Note>
</Step>
<Step title="Install Certbot">
Install Certbot on the server where JBoss/WildFly is running by following the official Certbot [installation guide](https://certbot.eff.org/instructions).
The installation guide provides up-to-date instructions for various Linux distributions and package managers, ensuring you get the most current version of Certbot.
After installation, you can verify that Certbot has been installed correctly by running:
```bash
certbot --version
```
</Step>
<Step title="Request Certificate Using Certbot">
Since JBoss/WildFly doesn't have a native Certbot plugin, use the standalone authenticator to obtain certificates. **Important**: You must stop JBoss/WildFly before running this command as Certbot needs to bind to port 80 for the [HTTP-01](https://letsencrypt.org/docs/challenge-types/#http-01-challenge) challenge.
Stop your JBoss/WildFly server:
```bash
sudo systemctl stop wildfly
# or for older JBoss versions
# sudo systemctl stop jboss
```
Run the following command to request a certificate from Infisical:
```bash
sudo certbot certonly \
--standalone \
--server "https://your-infisical-instance.com/api/v1/pki/certificate-profiles/{profile-id}/acme/directory" \
--eab-kid "your-eab-key-identifier" \
--eab-hmac-key "your-eab-secret" \
-d example.infisical.com \
--email admin@example.com \
--agree-tos \
--non-interactive
```
For guidance on each parameter:
- `certonly`: Instructs Certbot to request a certificate without modifying your JBoss/WildFly configuration; this mode is recommended because JBoss/WildFly requires certificates in Java keystore format rather than the PEM format that Certbot provides.
- `--standalone`: Uses Certbot's standalone authenticator to solve the [HTTP-01](https://letsencrypt.org/docs/challenge-types/#http-01-challenge) challenge by starting a temporary web server on port 80.
- `--server`: The Infisical ACME directory URL from Step 1. This instructs Certbot to communicate with Infisical's ACME server instead of Let's Encrypt.
- `--eab-kid`: Your External Account Binding (EAB) Key Identifier from Step 1.
- `--eab-hmac-key`: The EAB secret associated with the KID from Step 1.
- `-d`: Specifies the domain name for which the certificate is being requested.
- `--email`: The contact email for expiration notices and account recovery.
- `--agree-tos`: Accepts the ACME server's Terms of Service.
- `--non-interactive`: Runs Certbot without prompting for user input (recommended for automation).
The Certbot command generates a private key on your server, creates a Certificate Signing Request (CSR) using that key, and sends the CSR to Infisical for certificate issuance. Certbot stores the private key and resulting leaf certificate and full certificate chain in `/etc/letsencrypt/live/{domain-name}/`.
Because JBoss/WildFly requires certificates in Java keystore format, you'll need to convert the PEM certificates provided by Certbot in the next step.
</Step>
<Step title="Convert Certificate to Java Keystore">
JBoss/WildFly requires certificates in Java keystore format rather than the PEM format provided by Certbot. Convert the PEM certificates to PKCS#12 format, which is supported by modern JBoss/WildFly versions.
Create a PKCS#12 keystore from the PEM files:
```bash
sudo openssl pkcs12 -export \
-out /opt/wildfly/standalone/configuration/keystore.p12 \
-inkey /etc/letsencrypt/live/example.infisical.com/privkey.pem \
-in /etc/letsencrypt/live/example.infisical.com/cert.pem \
-certfile /etc/letsencrypt/live/example.infisical.com/chain.pem \
-passout pass:changeit
```
Set appropriate file permissions for security:
```bash
sudo chown wildfly:wildfly /opt/wildfly/standalone/configuration/keystore.p12
sudo chmod 600 /opt/wildfly/standalone/configuration/keystore.p12
```
You will need to configure JBoss/WildFly to use the new keystore. This process varies depending on your JBoss/WildFly version and security configuration (legacy security realms vs. Elytron subsystem). Refer to your [JBoss](https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform)/[WildFly](https://docs.wildfly.org/) administration guide for specific SSL/TLS configuration steps.
<Note>
Replace `changeit` with a strong password and adjust the WildFly installation path based on your environment. Modern WildFly versions support PKCS#12 keystores directly, while older versions may require conversion to JKS format using the [keytool](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html) utility.
</Note>
</Step>
<Step title="Verify Certificate Installation">
After configuring JBoss/WildFly SSL, verify that your certificate was issued correctly and the keystore was created properly.
Check that the certificate files were created by Certbot:
```bash
sudo ls -la /etc/letsencrypt/live/example.infisical.com/
```
You should see files like:
- `cert.pem` (your certificate)
- `chain.pem` (certificate chain)
- `fullchain.pem` (certificate + chain)
- `privkey.pem` (private key)
Verify the PKCS#12 keystore was created:
```bash
sudo ls -la /opt/wildfly/standalone/configuration/keystore.p12
```
Test the keystore contents (optional):
```bash
sudo keytool -list -storetype PKCS12 -keystore /opt/wildfly/standalone/configuration/keystore.p12 -storepass changeit
```
Once you've configured JBoss/WildFly to use the keystore and restarted the service, you can verify HTTPS is working by accessing your application over SSL.
</Step>
<Step title="Renew Your Certificate with Certbot">
Unlike standard web servers, JBoss/WildFly certificate renewal requires additional steps because certificates must be converted to Java keystore format and the application server must be restarted to use the new certificates.
To test the renewal process without affecting your live certificates, run the following command:
```bash
sudo certbot renew --dry-run
```
This command simulates the full renewal process without modifying your active certificate. If the dry run succeeds, the renewal mechanism itself will work as expected.
For actual renewal, since JBoss/WildFly requires the standalone authenticator, you'll need to stop the server, perform the renewal, convert the certificate, and restart:
```bash
# Stop JBoss/WildFly
sudo systemctl stop wildfly
# Renew the certificate
sudo certbot renew --quiet
# Convert to keystore format
sudo openssl pkcs12 -export \
-out /opt/wildfly/standalone/configuration/keystore.p12 \
-inkey /etc/letsencrypt/live/example.infisical.com/privkey.pem \
-in /etc/letsencrypt/live/example.infisical.com/cert.pem \
-certfile /etc/letsencrypt/live/example.infisical.com/chain.pem \
-passout pass:changeit
# Set permissions
sudo chown wildfly:wildfly /opt/wildfly/standalone/configuration/keystore.p12
sudo chmod 600 /opt/wildfly/standalone/configuration/keystore.p12
# Start JBoss/WildFly
sudo systemctl start wildfly
```
To automate this process, you can create a renewal script. Create `/etc/letsencrypt/renewal-hooks/deploy/jboss-renewal.sh`:
```bash
#!/bin/bash
# JBoss/WildFly certificate renewal hook
DOMAIN="example.infisical.com"
KEYSTORE_PATH="/opt/wildfly/standalone/configuration/keystore.p12"
KEYSTORE_PASSWORD="changeit"
# Convert certificate to keystore format
openssl pkcs12 -export \
-out "$KEYSTORE_PATH" \
-inkey "/etc/letsencrypt/live/$DOMAIN/privkey.pem" \
-in "/etc/letsencrypt/live/$DOMAIN/cert.pem" \
-certfile "/etc/letsencrypt/live/$DOMAIN/chain.pem" \
-passout "pass:$KEYSTORE_PASSWORD"
# Set permissions
chown wildfly:wildfly "$KEYSTORE_PATH"
chmod 600 "$KEYSTORE_PATH"
# Restart WildFly to load new certificate
systemctl restart wildfly
```
Make the hook executable:
```bash
sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/jboss-renewal.sh
```
<Note>
Certbot automatically renews certificates when they are within 30 days of expiration using its built-in systemd timer. The deploy hook above will run after each successful renewal, handling the keystore conversion and service restart automatically. Because JBoss/WildFly requires the standalone authenticator (which stops the service temporarily), plan for brief service interruptions during renewal.
</Note>
</Step>
</Steps>

175
docs/documentation/platform/pki/integration-guides/nginx-certbot.mdx Normal file
View File

@@ -0,0 +1,175 @@
---
title: "Nginx"
description: "Learn how to issue SSL/TLS certificates from Infisical using ACME enrollment on Nginx with Certbot"
---
This guide demonstrates how to use Infisical to issue SSL/TLS certificates for your [Nginx](https://nginx.org/) server.
It uses [Certbot](https://certbot.eff.org/), an installable [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) client, to request and renew certificates from Infisical using the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme) configured on a [certificate profile](/documentation/platform/pki/certificates/profiles).
## Prerequisites
Before you begin, make sure you have:
- An [Nginx](https://nginx.org/) web server running on a Linux system with administrative access.
- A [certificate profile](/documentation/platform/pki/certificates/profiles) configured with the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme) in Infisical.
- Network connectivity from your Nginx server to Infisical.
- Port 80 open and reachable for ACME [HTTP-01](https://letsencrypt.org/docs/challenge-types/#http-01-challenge) validation.
## Guide
<Steps>
<Step title="Obtain ACME Configuration from Infisical">
Navigate to your certificate management project in Infisical and locate your [certificate profile](/documentation/platform/pki/certificates/profiles) configured with the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme).
![Certificate profile with ACME enrollment option](/images/platform/pki/acme/certificate-profile-acme-option.png)
Click the **Reveal ACME EAB** option to view the ACME configuration details.
![ACME configuration modal showing directory URL and EAB credentials](/images/platform/pki/acme/acme-configuration-modal.png)
From the ACME configuration, gather the following values:
- ACME Directory URL: The URL that Certbot will use to communicate with Infisical's ACME server. This takes the form `https://your-infisical-instance.com/api/v1/pki/certificate-profiles/{profile-id}/acme/directory`.
- EAB Key Identifier (KID): A unique identifier that tells Infisical which ACME account is making the request.
- EAB Secret: A secret key that authenticates your ACME client with Infisical.
<Note>
Keep your EAB credentials secure as they authenticate your ACME client with Infisical PKI. These credentials are unique to each [certificate profile](/documentation/platform/pki/certificates/profiles) and should not be shared.
</Note>
</Step>
<Step title="Install Certbot">
Install Certbot on the server where Nginx is running by following the official Certbot [installation guide](https://certbot.eff.org/instructions).
The installation guide provides up-to-date instructions for various Linux distributions and package managers, ensuring you get the most current version and proper Nginx plugin integration.
After installation, you can verify that Certbot has been installed correctly by running:
```bash
certbot --version
```
</Step>
<Step title="Request Certificate Using Certbot">
Run the following command to request a certificate from Infisical:
```bash
sudo certbot certonly \
--nginx \
--server "https://your-infisical-instance.com/api/v1/pki/certificate-profiles/{profile-id}/acme/directory" \
--eab-kid "your-eab-key-identifier" \
--eab-hmac-key "your-eab-secret" \
-d example.infisical.com \
--email admin@example.com \
--agree-tos \
--non-interactive
```
For guidance on each parameter:
- `certonly`: Instructs Certbot to request a certificate without modifying and reloading your Nginx configuration file(s); this mode is recommended if you prefer to manage your Nginx TLS configuration manually, use automation tools, or integrate certificates into an existing deployment workflow.
- `--nginx`: Specifies the Nginx plugin so Certbot can solve the [HTTP-01](https://letsencrypt.org/docs/challenge-types/#http-01-challenge) challenge by creating temporary files served by Nginx.
- `--server`: The Infisical ACME directory URL from Step 1. This instructs Certbot to communicate with Infisical's ACME server instead of Let's Encrypt.
- `--eab-kid`: Your External Account Binding (EAB) Key Identifier from Step 1.
- `--eab-hmac-key`: The EAB secret associated with the KID from Step 1.
- `-d`: Specifies the domain name for which the certificate is being requested.
- `--email`: The contact email for expiration notices and account recovery.
- `--agree-tos`: Accepts the ACME server’s Terms of Service.
- `--non-interactive`: Runs Certbot without prompting for user input (recommended for automation).
The Certbot command generates a private key on your server, creates a Certificate Signing Request (CSR) using that key, and sends the CSR to Infisical for certificate issuance. Certbot stores the private key and resulting leaf certificate and full certificate chain in `/etc/letsencrypt/live/{domain-name}/`.
If `--certonly` is used: Certbot does **not** modify your Nginx configuration, so you must manually update your Nginx server block to reference the new certificate files and reload the server to apply the changes.
Here's how you can configure your server block:
```nginx
server {
listen 443 ssl;
server_name example.infisical.com;
ssl_certificate /etc/letsencrypt/live/example.infisical.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.infisical.com/privkey.pem;
# ...your existing configuration...
}
```
After updating the server block, you should test and reload Nginx to apply the changes:
```bash
sudo nginx -t
sudo systemctl reload nginx
```
If `--certonly` was **not** used: Certbot uses Nginx installer mode, which attempts to automatically configure HTTPS by updating your Nginx server block and reloading the server if needed.
At this point, your Nginx server should be successfully serving HTTPS using the certificate issued by Infisical.
</Step>
<Step title="Verify Certificate Installation">
After configuring Nginx SSL, verify that your certificate was issued correctly and Nginx is serving it properly.
Check that the certificate files were created by Certbot:
```bash
sudo ls -la /etc/letsencrypt/live/example.infisical.com/
```
You should see files like:
- `cert.pem` (your certificate)
- `chain.pem` (certificate chain)
- `fullchain.pem` (certificate + chain)
- `privkey.pem` (private key)
</Step>
<Step title="Renew Your Certificate with Certbot">
Certbot automatically installs a `systemd` timer during installation. This timer runs twice per day and checks whether any certificates are due for renewal. Because Certbot stores the ACME server URL and EAB credentials from your initial request, renewal will automatically use the same Infisical ACME configuration—no additional settings are required.
Note that Certbot automatically renews certificates when they are within 30 days of expiration; renewal settings can be adjusted in `/etc/letsencrypt/renewal/{domain-name}.conf`.
```ini
# ... your existing configuration ...
renew_before_expiry = 30 days
```
To test the renewal process, run the following command:
```bash
sudo certbot renew --dry-run
```
This command simulates the full renewal process without modifying your active certificate. If the dry run succeeds, automatic renewal will work as expected.
To trigger an actual renewal immediately, run the following command:
```bash
sudo certbot renew --force-renewal
```
Note that after a certificate is renewed, Nginx must be reloaded so it can begin using the new certificate. To do this, run the following command:
```bash
systemctl reload nginx
```
To automate the process of renewing a certificate and reloading Nginx, you can create a simple deploy hook that Certbot will run after every successful renewal.
Inside `/etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh`, add the following:
```bash
#!/bin/sh
systemctl reload nginx
```
Then make the hook executable:
```bash
sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh
```
</Step>
</Steps>

251
docs/documentation/platform/pki/integration-guides/tomcat-certbot.mdx Normal file
View File

@@ -0,0 +1,251 @@
---
title: "Tomcat"
description: "Learn how to issue SSL/TLS certificates from Infisical using ACME enrollment on Tomcat with Certbot"
---
This guide demonstrates how to use Infisical to issue SSL/TLS certificates for your [Apache Tomcat](https://tomcat.apache.org/) application server.
It uses [Certbot](https://certbot.eff.org/), an installable [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) client, to request and renew certificates from Infisical using the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme) configured on a [certificate profile](/documentation/platform/pki/certificates/profiles). Unlike web servers with native Certbot plugins, Tomcat requires certificates to be manually configured after issuance.
## Prerequisites
Before you begin, make sure you have:
- An [Apache Tomcat](https://tomcat.apache.org/) application server running on a Linux system with administrative access.
- A [certificate profile](/documentation/platform/pki/certificates/profiles) configured with the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme) in Infisical.
- Network connectivity from your Tomcat server to Infisical.
- Port 80 open and reachable for ACME [HTTP-01](https://letsencrypt.org/docs/challenge-types/#http-01-challenge) validation.
## Guide
<Steps>
<Step title="Obtain ACME Configuration from Infisical">
Navigate to your certificate management project in Infisical and locate your [certificate profile](/documentation/platform/pki/certificates/profiles) configured with the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme).
![Certificate profile with ACME enrollment option](/images/platform/pki/acme/certificate-profile-acme-option.png)
Click the **Reveal ACME EAB** option to view the ACME configuration details.
![ACME configuration modal showing directory URL and EAB credentials](/images/platform/pki/acme/acme-configuration-modal.png)
From the ACME configuration, gather the following values:
- ACME Directory URL: The URL that Certbot will use to communicate with Infisical's ACME server. This takes the form `https://your-infisical-instance.com/api/v1/pki/certificate-profiles/{profile-id}/acme/directory`.
- EAB Key Identifier (KID): A unique identifier that tells Infisical which ACME account is making the request.
- EAB Secret: A secret key that authenticates your ACME client with Infisical.
<Note>
Keep your EAB credentials secure as they authenticate your ACME client with Infisical PKI. These credentials are unique to each [certificate profile](/documentation/platform/pki/certificates/profiles) and should not be shared.
</Note>
</Step>
<Step title="Install Certbot">
Install Certbot on the server where Tomcat is running by following the official Certbot [installation guide](https://certbot.eff.org/instructions).
The installation guide provides up-to-date instructions for various Linux distributions and package managers, ensuring you get the most current version of Certbot.
After installation, you can verify that Certbot has been installed correctly by running:
```bash
certbot --version
```
</Step>
<Step title="Request Certificate Using Certbot">
Since Tomcat doesn't have a native Certbot plugin, use the standalone authenticator to obtain certificates. **Important**: You must stop Tomcat before running this command as Certbot needs to bind to port 80 for the [HTTP-01](https://letsencrypt.org/docs/challenge-types/#http-01-challenge) challenge.
Stop your Tomcat server:
```bash
sudo systemctl stop tomcat
```
Run the following command to request a certificate from Infisical:
```bash
sudo certbot certonly \
--standalone \
--server "https://your-infisical-instance.com/api/v1/pki/certificate-profiles/{profile-id}/acme/directory" \
--eab-kid "your-eab-key-identifier" \
--eab-hmac-key "your-eab-secret" \
-d example.infisical.com \
--email admin@example.com \
--agree-tos \
--non-interactive
```
For guidance on each parameter:
- `certonly`: Instructs Certbot to request a certificate without modifying your Tomcat configuration; this mode is recommended because Tomcat requires manual SSL connector configuration in its server.xml file.
- `--standalone`: Uses Certbot's standalone authenticator to solve the [HTTP-01](https://letsencrypt.org/docs/challenge-types/#http-01-challenge) challenge by starting a temporary web server on port 80.
- `--server`: The Infisical ACME directory URL from Step 1. This instructs Certbot to communicate with Infisical's ACME server instead of Let's Encrypt.
- `--eab-kid`: Your External Account Binding (EAB) Key Identifier from Step 1.
- `--eab-hmac-key`: The EAB secret associated with the KID from Step 1.
- `-d`: Specifies the domain name for which the certificate is being requested.
- `--email`: The contact email for expiration notices and account recovery.
- `--agree-tos`: Accepts the ACME server's Terms of Service.
- `--non-interactive`: Runs Certbot without prompting for user input (recommended for automation).
The Certbot command generates a private key on your server, creates a Certificate Signing Request (CSR) using that key, and sends the CSR to Infisical for certificate issuance. Certbot stores the private key and resulting leaf certificate and full certificate chain in `/etc/letsencrypt/live/{domain-name}/`.
Because Tomcat requires manual SSL configuration, you'll need to configure the SSL connector in your Tomcat server.xml file to reference these certificate files. You can restart Tomcat after the certificate is issued, but SSL won't be enabled until you complete the server configuration.
```bash
sudo systemctl start tomcat
```
</Step>
<Step title="Configure Tomcat SSL Connector">
To enable SSL/TLS in Tomcat, you need to configure an SSL connector in the server.xml configuration file. Tomcat can use the PEM certificates directly without conversion to Java keystore format (available in Tomcat 8.5+ with the NIO or NIO2 connector).
Edit your Tomcat server.xml file (typically located at `/opt/tomcat/conf/server.xml` or `/usr/share/tomcat/conf/server.xml`):
```xml
<Connector port="8443"
protocol="org.apache.coyote.http11.Http11NioProtocol"
maxThreads="150"
SSLEnabled="true">
<SSLHostConfig>
<Certificate certificateFile="/etc/letsencrypt/live/example.infisical.com/cert.pem"
certificateKeyFile="/etc/letsencrypt/live/example.infisical.com/privkey.pem"
certificateChainFile="/etc/letsencrypt/live/example.infisical.com/chain.pem"
type="RSA" />
</SSLHostConfig>
</Connector>
```
Restart Tomcat to apply the SSL configuration:
```bash
sudo systemctl restart tomcat
```
You can verify SSL is working by accessing your Tomcat application at `https://example.infisical.com:8443`. For production deployments, consider configuring a reverse proxy (like [Apache HTTP Server](https://httpd.apache.org/) or [Nginx](https://nginx.org/)) to handle SSL termination on standard port 443.
<Note>
The certificate paths must be readable by the Tomcat user. You may need to adjust file permissions or copy the certificates to a location accessible by Tomcat. For security, ensure the private key file has restricted permissions (600) and is owned by the Tomcat user.
</Note>
</Step>
<Step title="Verify Certificate Installation">
After configuring Tomcat SSL, verify that your certificate was issued correctly and Tomcat is serving it properly.
Check that the certificate files were created by Certbot:
```bash
sudo ls -la /etc/letsencrypt/live/example.infisical.com/
```
You should see files like:
- `cert.pem` (your certificate)
- `chain.pem` (certificate chain)
- `fullchain.pem` (certificate + chain)
- `privkey.pem` (private key)
</Step>
<Step title="Renew Your Certificate with Certbot">
Unlike web servers with native Certbot plugins, Tomcat certificate renewal requires stopping the server, renewing the certificate, and restarting to load the new certificates.
To test the renewal process without affecting your live certificates, run the following command:
```bash
sudo certbot renew --dry-run
```
This command simulates the full renewal process without modifying your active certificate. If the dry run succeeds, the renewal mechanism will work as expected.
For actual renewal, since Tomcat requires the standalone authenticator, you'll need to stop the server, perform the renewal, and restart:
```bash
# Stop Tomcat
sudo systemctl stop tomcat
# Renew the certificate
sudo certbot renew --quiet
# Start Tomcat
sudo systemctl start tomcat
```
**Important considerations for Tomcat renewal:**
Because Tomcat uses the standalone authenticator, the server must be stopped during renewal. This creates a service interruption that requires manual coordination:
1. **Plan maintenance windows** for certificate renewals (typically every 60-90 days)
2. **Monitor renewal dates** to schedule downtime appropriately
3. **Consider load balancers** or multiple instances for high availability during renewals
Create a deploy hook to automate post-renewal tasks. Create `/etc/letsencrypt/renewal-hooks/deploy/tomcat-renewal.sh`:
```bash
#!/bin/bash
# Tomcat certificate renewal hook
# This runs AFTER Certbot successfully renews certificates
DOMAIN="example.infisical.com"
TOMCAT_USER="tomcat"
# Ensure certificate files are readable by Tomcat
chown root:$TOMCAT_USER "/etc/letsencrypt/live/$DOMAIN/cert.pem"
chown root:$TOMCAT_USER "/etc/letsencrypt/live/$DOMAIN/privkey.pem"
chown root:$TOMCAT_USER "/etc/letsencrypt/live/$DOMAIN/chain.pem"
chown root:$TOMCAT_USER "/etc/letsencrypt/live/$DOMAIN/fullchain.pem"
# Set appropriate permissions
chmod 640 "/etc/letsencrypt/live/$DOMAIN/cert.pem"
chmod 640 "/etc/letsencrypt/live/$DOMAIN/privkey.pem"
chmod 640 "/etc/letsencrypt/live/$DOMAIN/chain.pem"
chmod 640 "/etc/letsencrypt/live/$DOMAIN/fullchain.pem"
# Start Tomcat (it was stopped for renewal)
systemctl start tomcat
# Wait for startup and verify service is running
sleep 10
if ! systemctl is-active --quiet tomcat; then
echo "ERROR: Tomcat failed to start after certificate renewal"
exit 1
fi
echo "Tomcat certificate renewal completed successfully"
```
Make the hook executable:
```bash
sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/tomcat-renewal.sh
```
<Note>
Certbot automatically renews certificates when they are within 30 days of expiration using its built-in systemd timer. The deploy hook above will run after each successful renewal, handling the certificate permissions and service restart automatically. Because Tomcat requires the standalone authenticator (which stops the service temporarily), plan for brief service interruptions during renewal.
</Note>
</Step>
<Step title="Using Renewed Certificates Manually">
If you need to manually apply renewed certificates to Tomcat (when the deploy hook isn't used), follow these steps:
**Step 1: Set certificate file permissions**
After Certbot renews your certificates, ensure they're readable by Tomcat:
```bash
sudo chown root:tomcat /etc/letsencrypt/live/example.infisical.com/cert.pem
sudo chown root:tomcat /etc/letsencrypt/live/example.infisical.com/privkey.pem
sudo chown root:tomcat /etc/letsencrypt/live/example.infisical.com/chain.pem
sudo chmod 640 /etc/letsencrypt/live/example.infisical.com/cert.pem
sudo chmod 640 /etc/letsencrypt/live/example.infisical.com/privkey.pem
sudo chmod 640 /etc/letsencrypt/live/example.infisical.com/chain.pem
```
**Step 2: Restart Tomcat to load new certificates**
```bash
sudo systemctl restart tomcat
```
That's it! Tomcat will automatically use the renewed certificates since your `server.xml` already points to the Let's Encrypt certificate files.
<Note>
Since Tomcat reads certificates from the file system on startup, you only need to restart the service after certificate renewal. The certificate file paths in `/etc/letsencrypt/live/` are symbolic links that automatically point to the latest certificates.
</Note>
</Step>
</Steps>

194
docs/documentation/platform/pki/integration-guides/windows-server-acme.mdx Normal file
View File

@@ -0,0 +1,194 @@
---
title: "Windows Server"
description: "Learn how to issue SSL/TLS certificates from Infisical using ACME enrollment on Windows Server with win-acme"
---
This guide demonstrates how to use Infisical to issue SSL/TLS certificates for your [Windows Server](https://www.microsoft.com/en-us/windows-server) environments.
It uses [win-acme](https://www.win-acme.com/), a feature-rich [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) client designed specifically for Windows, to request and renew certificates from Infisical using the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme) configured on a [certificate profile](/documentation/platform/pki/certificates/profiles). Win-acme offers excellent integration with IIS, Windows Certificate Store, and various certificate storage options.
## Prerequisites
Before you begin, make sure you have:
- A [Windows Server](https://www.microsoft.com/en-us/windows-server) instance running with administrative access.
- A [certificate profile](/documentation/platform/pki/certificates/profiles) configured with the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme) in Infisical.
- Network connectivity from your Windows Server to Infisical.
## Guide
<Steps>
<Step title="Obtain ACME Configuration from Infisical">
Navigate to your certificate management project in Infisical and locate your [certificate profile](/documentation/platform/pki/certificates/profiles) configured with the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme).
![Certificate profile with ACME enrollment option](/images/platform/pki/acme/certificate-profile-acme-option.png)
Click the **Reveal ACME EAB** option to view the ACME configuration details.
![ACME configuration modal showing directory URL and EAB credentials](/images/platform/pki/acme/acme-configuration-modal.png)
From the ACME configuration, gather the following values:
- ACME Directory URL: The URL that win-acme will use to communicate with Infisical's ACME server. This takes the form `https://your-infisical-instance.com/api/v1/pki/certificate-profiles/{profile-id}/acme/directory`.
- EAB Key Identifier (KID): A unique identifier that tells Infisical which ACME account is making the request.
- EAB Secret: A secret key that authenticates your ACME client with Infisical.
<Note>
Keep your EAB credentials secure as they authenticate your ACME client with Infisical PKI. These credentials are unique to each [certificate profile](/documentation/platform/pki/certificates/profiles) and should not be shared.
</Note>
</Step>
<Step title="Install win-acme">
Install win-acme on your Windows Server using one of the following methods.
<Tabs>
<Tab title="Download from GitHub">
1. Visit the [win-acme releases page](https://github.com/win-acme/win-acme/releases).
2. Download the latest stable release ZIP file.
3. Extract the contents to a folder (e.g., `C:\win-acme`).
4. Open Command Prompt or PowerShell as Administrator.
5. Navigate to the win-acme folder.
```powershell
cd C:\win-acme
```
</Tab>
<Tab title=".NET Tool (Global Install)">
If you have [.NET Core](https://dotnet.microsoft.com/en-us/download) installed, you can install win-acme as a global tool:
```powershell
dotnet tool install win-acme --global
```
This makes the `wacs` command available system-wide.
</Tab>
</Tabs>
</Step>
<Step title="Request Certificate Using Command Line">
Run the following win-acme command to request a certificate from Infisical:
```powershell
wacs.exe --target manual --host example.infisical.com --baseuri "https://your-infisical-instance.com/api/v1/pki/certificate-profiles/{profile-id}/acme/directory" --eab-key-identifier "your-eab-key-identifier" --eab-key "your-eab-secret" --validation selfhosting --store pemfiles --pemfilespath "C:\certificates" --verbose
```
For guidance on each parameter:
- `--target manual`: Specifies manual target configuration for domain specification.
- `--host`: The domain name for which the certificate is being requested.
- `--baseuri`: The Infisical ACME directory URL from Step 1. This instructs win-acme to communicate with Infisical's ACME server instead of other ACME providers.
- `--eab-key-identifier`: Your External Account Binding (EAB) Key Identifier from Step 1.
- `--eab-key`: The EAB secret associated with the KID from Step 1.
- `--validation selfhosting`: Uses self-hosting validation method to solve the [HTTP-01](https://letsencrypt.org/docs/challenge-types/#http-01-challenge) challenge.
- `--store pemfiles`: Stores certificates as PEM files in a specified directory.
- `--pemfilespath`: Directory where certificates will be saved on your Windows Server.
- `--verbose`: Enables detailed logging for troubleshooting and monitoring the certificate request process.
The win-acme command generates a private key on your server, creates a Certificate Signing Request (CSR) using that key, and sends the CSR to Infisical for certificate issuance. Win-acme stores the private key and resulting leaf certificate and full certificate chain in the specified directory path.
<Note>
Replace the placeholder values with your actual configuration:
- `example.infisical.com`: Your actual domain name
- `https://your-infisical-instance.com/api/v1/pki/certificate-profiles/{profile-id}/acme/directory`: Your Infisical ACME endpoint from Step 1
- `your-eab-key-identifier` and `your-eab-secret`: Your External Account Binding credentials from Step 1
- `C:\certificates`: Your desired certificate storage location
</Note>
</Step>
<Step title="Alternative Storage Options">
Win-acme supports various certificate storage options beyond PEM files. Here are common alternatives for different deployment scenarios:
<Tabs>
<Tab title="Windows Certificate Store">
Store certificates directly in the [Windows Certificate Store](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/certificate-stores) for integration with IIS and other Windows services:
```powershell
wacs.exe --target manual --host example.infisical.com --baseuri "https://your-infisical-instance.com/api/v1/pki/certificate-profiles/{profile-id}/acme/directory" --eab-key-identifier "your-eab-key-identifier" --eab-key "your-eab-secret" --validation selfhosting --store certificatestore --verbose
```
</Tab>
<Tab title="PFX Files">
Generate [PFX files](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/certutil) with password protection for easy deployment across Windows environments:
```powershell
wacs.exe --target manual --host example.infisical.com --baseuri "https://your-infisical-instance.com/api/v1/pki/certificate-profiles/{profile-id}/acme/directory" --eab-key-identifier "your-eab-key-identifier" --eab-key "your-eab-secret" --validation selfhosting --store pfxfile --pfxfilepath "C:\certificates" --pfxpassword "your-secure-password" --verbose
```
</Tab>
<Tab title="IIS Central SSL">
For IIS Central SSL store integration in high-scale environments:
```powershell
wacs.exe --target manual --host example.infisical.com --baseuri "https://your-infisical-instance.com/api/v1/pki/certificate-profiles/{profile-id}/acme/directory" --eab-key-identifier "your-eab-key-identifier" --eab-key "your-eab-secret" --validation selfhosting --store centralssl --centralsslstore "C:\CentralSSL" --verbose
```
</Tab>
</Tabs>
</Step>
<Step title="Configure Automatic Renewal">
Win-acme can automatically create a [Windows Scheduled Task](https://docs.microsoft.com/en-us/windows/win32/taskschd/about-the-task-scheduler) for certificate renewal. Because win-acme stores the ACME server URL and EAB credentials from your initial request, renewal will automatically use the same Infisical ACME configuration—no additional settings are required.
**Option 1: Enable during initial certificate request**
Include the `--setuptaskscheduler` parameter in your initial command to automatically create the renewal task:
```powershell
wacs.exe --target manual --host example.infisical.com --baseuri "https://your-infisical-instance.com/api/v1/pki/certificate-profiles/{profile-id}/acme/directory" --eab-key-identifier "your-eab-key-identifier" --eab-key "your-eab-secret" --validation selfhosting --store pemfiles --pemfilespath "C:\certificates" --setuptaskscheduler --verbose
```
**Option 2: Test manual renewal**
You can test the renewal process manually before setting up automation to ensure the configuration works correctly:
```powershell
wacs.exe --renew --force --verbose
```
This command simulates the full renewal process and verifies that win-acme can successfully contact Infisical and renew your certificate using the stored configuration.
**Option 3: Verify scheduled task creation**
Check that the scheduled task was created successfully:
```powershell
Get-ScheduledTask -TaskName "*win-acme*"
```
The automatic renewal task will:
- Run under the SYSTEM account for elevated privileges.
- Check certificates daily for renewal eligibility.
- Automatically renew certificates that are within the renewal threshold (typically 30 days before expiration).
- Log renewal activities to Windows Event Viewer and win-acme log files for monitoring and troubleshooting.
<Note>
Win-acme stores renewal configurations automatically in its settings directory, so once a certificate is created, the renewal process will use the same parameters (ACME endpoint, EAB credentials, storage options) for future renewals. The renewal threshold can be adjusted in the win-acme configuration files if needed.
</Note>
</Step>
<Step title="Verify Certificate Installation">
After successful certificate issuance, verify that the certificate files have been created correctly based on your chosen storage method.
<Tabs>
<Tab title="PEM Files">
Check your specified PEM files directory to ensure all certificate components are present:
```powershell
Get-ChildItem "C:\certificates" -Filter "*.pem"
```
You should see files like:
- `example.infisical.com-crt.pem` (certificate)
- `example.infisical.com-key.pem` (private key)
- `example.infisical.com-chain.pem` (complete certificate chain)
- `example.infisical.com-chain-only.pem` (only certificate chain)
![Windows Server Generated PEM files](/images/platform/pki/integrations/windows-server/certificates-created.png)
</Tab>
<Tab title="Windows Certificate Store">
If you used the certificate store option, check that the certificate was properly installed using PowerShell:
```powershell
Get-ChildItem -Path Cert:\LocalMachine\My | Where-Object {$_.Subject -like "*example.infisical.com*"}
```
The certificate should appear in the [Local Computer Personal certificate store](https://docs.microsoft.com/en-us/dotnet/framework/wcf/feature-details/working-with-certificates#certificate-stores), making it available for use with IIS, other Windows services, and applications that integrate with the Windows Certificate Store.
</Tab>
</Tabs>
</Step>
</Steps>

BIN
docs/images/platform/pki/acme/acme-configuration-modal.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 294 KiB

BIN
docs/images/platform/pki/acme/certificate-profile-acme-option.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 329 KiB

BIN
docs/images/platform/pki/integrations/windows-server/certificates-created.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 587 KiB