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

Few changes on PKI ACME docs

Browse Source
This commit is contained in:
Carlos Monastyrski
2025-11-14 02:42:54 -03:00
parent ef14fd5aad
commit d770e0d9df
5 changed files with 515 additions and 267 deletions
Download Patch File Download Diff File Expand all files Collapse all files

181
docs/documentation/platform/pki/integration-guides/apache-certbot.mdx
View File

@@ -1,42 +1,37 @@
---
title: "Apache Server"
description: "Learn how to issue SSL/TLS certificates from Infisical PKI using ACME enrollment on Apache Server with Certbot"
description: "Learn how to issue SSL/TLS certificates from Infisical using ACME enrollment on Apache Server with Certbot"
---
This guide will provide a high level overview on how you can use [Infisical PKI](/documentation/platform/pki/overview) and Certbot to issue SSL/TLS certificates for your Apache web server environments using the [ACME protocol](/documentation/platform/pki/enrollment-methods/acme). For more background about the ACME protocol, see the [ACME specification (RFC 8555)](https://tools.ietf.org/html/rfc8555).
This guide demonstrates how to use Infisical to issue SSL/TLS certificates for your [Apache HTTP Server](https://httpd.apache.org/).
## Overview
Certbot is a free, open-source software tool for automatically using Let's Encrypt certificates on manually-administrated websites to enable HTTPS. When configured with [Infisical PKI](/documentation/platform/pki/overview), Certbot can automatically obtain and install certificates from your private PKI infrastructure, providing seamless integration with Apache for automated certificate enrollment and renewal.
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 proceeding, ensure you have:
Before you begin, make sure you have:
- An Apache web server running on a Linux system with administrative access
- A [certificate profile](/documentation/platform/pki/certificates/profiles) configured for [ACME enrollment](/documentation/platform/pki/enrollment-methods/acme) in Infisical
- Network connectivity from your Apache server to your Infisical instance
- Port 80 accessible for ACME HTTP-01 validation
- 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 Infisical PKI project and locate your [certificate profile](/documentation/platform/pki/certificates/profiles) configured for [ACME enrollment](/documentation/platform/pki/enrollment-methods/acme).
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 on Reveal ACME EAB option to open the ACME details modal.
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 your certificate profile's ACME configuration, you'll need to collect three essential pieces of information:
From the ACME configuration, gather the following values:
1. **ACME Directory URL**: The ACME endpoint URL for your Infisical instance
- Format: `https://your-infisical-instance.com/api/v1/pki/certificate-profiles/{profile-id}/acme/directory`
2. **EAB Key Identifier (KID)**: External Account Binding key identifier
3. **EAB Secret**: External Account Binding secret key
- 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.
@@ -44,19 +39,11 @@ Before proceeding, ensure you have:
</Step>
<Step title="Install Certbot">
Install Certbot with the Apache plugin on your server by following the official installation instructions:
Visit the [Certbot installation guide](https://certbot.eff.org/instructions) and select your web server (Apache) and operating system for detailed installation steps specific to your environment.
For most Ubuntu/Debian systems, you can use:
```bash
sudo apt install certbot python3-certbot-apache
```
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, verify that Certbot is working correctly:
After installation, you can verify that Certbot has been installed correctly by running:
```bash
certbot --version
@@ -64,7 +51,7 @@ Before proceeding, ensure you have:
</Step>
<Step title="Request Certificate Using Certbot">
Use Certbot with your Infisical ACME configuration to request a certificate:
Run the following command to request a certificate from Infisical:
```bash
sudo certbot certonly \
@@ -78,55 +65,121 @@ Before proceeding, ensure you have:
--non-interactive
```
**Parameter breakdown:**
- `certonly`: Obtain certificate without installing it
- `--apache`: Use Apache plugin for domain validation
- `--server`: Your Infisical ACME directory URL
- `--eab-kid`: Your EAB key identifier from Infisical
- `--eab-hmac-key`: Your EAB secret from Infisical
- `-d`: Domain name for your certificate
- `--email`: Contact email for important account notifications
- `--agree-tos`: Agree to ACME server's Terms of Service
- `--non-interactive`: Run in non-interactive mode
For guidance on each parameter:
<Note>
Replace the placeholder values with your actual configuration:
- `https://your-infisical-instance.com/api/v1/pki/certificate-profiles/{profile-id}/acme/directory`: Your Infisical ACME endpoint
- `your-eab-key-identifier` and `your-eab-secret`: Your External Account Binding credentials
- `example.infisical.com`: Your actual domain name
- `admin@example.com`: Your contact email
</Note>
- `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="Configure Automatic Renewal">
Certbot can automatically renew certificates. Test the renewal process manually:
<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
```
Manual renewal process:
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 can be configured for automatic renewal using systemd timers (`sudo systemctl enable certbot.timer`) or cron jobs. Certbot stores all configuration from the initial request, so renewals will automatically use the same Infisical [ACME endpoint](/documentation/platform/pki/enrollment-methods/acme) and EAB credentials.
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>
<Step title="Verify Certificate Installation">
Check that certificate files were created:
```bash
sudo ls -la /etc/letsencrypt/live/example.infisical.com/
```
You should see:
- `cert.pem` (leaf certificate)
- `chain.pem` (intermediate certificate)
- `fullchain.pem` (leaf + intermediate certificates)
- `privkey.pem` (private key)
</Step>
</Steps>

214
docs/documentation/platform/pki/integration-guides/jboss-certbot.mdx
View File

@@ -1,43 +1,38 @@
---
title: "JBoss/WildFly"
description: "Learn how to issue SSL/TLS certificates from Infisical PKI using ACME enrollment on JBoss/WildFly with Certbot"
description: "Learn how to issue SSL/TLS certificates from Infisical using ACME enrollment on JBoss/WildFly with Certbot"
---
This guide will provide a high level overview on how you can use [Infisical PKI](/documentation/platform/pki/overview) and Certbot to issue SSL/TLS certificates for your JBoss/WildFly application server environments using the [ACME protocol](/documentation/platform/pki/enrollment-methods/acme). For more background about the ACME protocol, see the [ACME specification (RFC 8555)](https://tools.ietf.org/html/rfc8555).
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.
## Overview
Certbot is a free, open-source software tool for automatically using Let's Encrypt certificates on manually-administrated websites to enable HTTPS. When configured with [Infisical PKI](/documentation/platform/pki/overview), Certbot can automatically obtain certificates from your private PKI infrastructure. JBoss/WildFly requires certificates to be converted to Java keystore format and configured through either the legacy security realms or modern Elytron subsystem.
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 proceeding, ensure you have:
Before you begin, make sure you have:
- A JBoss/WildFly application server running on a Linux system with administrative access
- A [certificate profile](/documentation/platform/pki/certificates/profiles) configured for [ACME enrollment](/documentation/platform/pki/enrollment-methods/acme) in Infisical
- Network connectivity from your JBoss/WildFly server to your Infisical instance
- Port 80 accessible for ACME HTTP-01 validation (JBoss/WildFly should be stopped during certificate issuance)
- Java Development Kit (JDK) installed for keystore management tools
- 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 Infisical PKI project and locate your [certificate profile](/documentation/platform/pki/certificates/profiles) configured for [ACME enrollment](/documentation/platform/pki/enrollment-methods/acme).
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 on Reveal ACME EAB option to open the ACME details modal.
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 your certificate profile's ACME configuration, you'll need to collect three essential pieces of information:
From the ACME configuration, gather the following values:
1. **ACME Directory URL**: The ACME endpoint URL for your Infisical instance
- Format: `https://your-infisical-instance.com/api/v1/pki/certificate-profiles/{profile-id}/acme/directory`
2. **EAB Key Identifier (KID)**: External Account Binding key identifier
3. **EAB Secret**: External Account Binding secret key
- 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.
@@ -45,19 +40,11 @@ Before proceeding, ensure you have:
</Step>
<Step title="Install Certbot">
Install Certbot on your JBoss/WildFly server by following the official installation instructions:
Install Certbot on the server where JBoss/WildFly is running by following the official Certbot [installation guide](https://certbot.eff.org/instructions).
Visit the [Certbot installation guide](https://certbot.eff.org/instructions) and select your operating system for detailed installation steps.
The installation guide provides up-to-date instructions for various Linux distributions and package managers, ensuring you get the most current version of Certbot.
For most Ubuntu/Debian systems, you can use:
```bash
sudo apt install certbot
```
The installation guide provides up-to-date instructions for various Linux distributions and package managers.
After installation, verify that Certbot is working correctly:
After installation, you can verify that Certbot has been installed correctly by running:
```bash
certbot --version
@@ -65,7 +52,9 @@ Before proceeding, ensure you have:
</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**: Stop JBoss/WildFly before running this command as Certbot needs to bind to port 80.
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
@@ -73,7 +62,7 @@ Before proceeding, ensure you have:
# sudo systemctl stop jboss
```
Then request the certificate:
Run the following command to request a certificate from Infisical:
```bash
sudo certbot certonly \
@@ -87,30 +76,27 @@ Before proceeding, ensure you have:
--non-interactive
```
**Parameter breakdown:**
- `certonly`: Obtain certificate without installing it
- `--standalone`: Use standalone authenticator (requires port 80)
- `--server`: Your Infisical ACME directory URL
- `--eab-kid`: Your EAB key identifier from Infisical
- `--eab-hmac-key`: Your EAB secret from Infisical
- `-d`: Domain name for your certificate
- `--email`: Contact email for important account notifications
- `--agree-tos`: Agree to ACME server's Terms of Service
- `--non-interactive`: Run in non-interactive mode
For guidance on each parameter:
<Note>
Replace the placeholder values with your actual configuration:
- `https://your-infisical-instance.com/api/v1/pki/certificate-profiles/{profile-id}/acme/directory`: Your Infisical ACME endpoint
- `your-eab-key-identifier` and `your-eab-secret`: Your External Account Binding credentials
- `example.infisical.com`: Your actual domain name
- `admin@example.com`: Your contact email
</Note>
- `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. Convert the PEM certificates obtained from Certbot:
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 PKCS#12 keystore from PEM files:**
Create a PKCS#12 keystore from the PEM files:
```bash
sudo openssl pkcs12 -export \
@@ -121,50 +107,120 @@ Before proceeding, ensure you have:
-passout pass:changeit
```
**Set appropriate permissions:**
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
```
<Note>
Replace `changeit` with a strong password and adjust the WildFly installation path if different. Modern WildFly versions support PKCS#12 keystores directly, while older versions may require conversion to JKS format using keytool.
</Note>
</Step>
<Step title="Configure Automatic Renewal">
To renew certificates, you can test the renewal process manually:
```bash
sudo certbot renew --dry-run
```
Manual renewal process:
```bash
sudo systemctl stop wildfly
sudo certbot renew --quiet
# Convert certificates to keystore format and restart WildFly
sudo systemctl start wildfly
```
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>
Since JBoss/WildFly requires certificate format conversion, automatic renewal requires a custom script. For production environments, consider creating a cron job that stops the server, renews certificates, converts them to keystore format, and restarts the server.
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 successful certificate installation, check that certificate files were created:
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:
- `cert.pem` (leaf certificate)
- `chain.pem` (intermediate certificate)
- `fullchain.pem` (leaf + intermediate certificates)
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>

20
docs/documentation/platform/pki/integration-guides/nginx-certbot.mdx
View File

@@ -29,7 +29,7 @@ Before you begin, make sure you have:
From the ACME configuration, gather the following values:
- ACME Directory URL: The URL that Cerbot 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`.
- 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.
@@ -75,7 +75,7 @@ Before you begin, make sure you have:
- `-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 Cerbot without prompting for user input (recommended for automation).
- `--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}/`.
@@ -108,6 +108,22 @@ Before you begin, make sure you have:
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.

244
docs/documentation/platform/pki/integration-guides/tomcat-certbot.mdx
View File

@@ -1,42 +1,37 @@
---
title: "Tomcat"
description: "Learn how to issue SSL/TLS certificates from Infisical PKI using ACME enrollment on Tomcat with Certbot"
description: "Learn how to issue SSL/TLS certificates from Infisical using ACME enrollment on Tomcat with Certbot"
---
This guide will provide a high level overview on how you can use [Infisical PKI](/documentation/platform/pki/overview) and Certbot to issue SSL/TLS certificates for your Tomcat application server environments using the [ACME protocol](/documentation/platform/pki/enrollment-methods/acme). For more background about the ACME protocol, see the [ACME specification (RFC 8555)](https://tools.ietf.org/html/rfc8555).
This guide demonstrates how to use Infisical to issue SSL/TLS certificates for your [Apache Tomcat](https://tomcat.apache.org/) application server.
## Overview
Certbot is a free, open-source software tool for automatically using Let's Encrypt certificates on manually-administrated websites to enable HTTPS. When configured with [Infisical PKI](/documentation/platform/pki/overview), Certbot can automatically obtain certificates from your private PKI infrastructure. Unlike Apache and NGINX, Tomcat doesn't have a native Certbot plugin, so certificates need to be obtained using the standalone authenticator and manually configured in Tomcat.
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 proceeding, ensure you have:
Before you begin, make sure you have:
- A Tomcat application server running on a Linux system with administrative access
- A [certificate profile](/documentation/platform/pki/certificates/profiles) configured for [ACME enrollment](/documentation/platform/pki/enrollment-methods/acme) in Infisical
- Network connectivity from your Tomcat server to your Infisical instance
- Port 80 accessible for ACME HTTP-01 validation (Tomcat should be stopped during certificate issuance)
- 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 Infisical PKI project and locate your [certificate profile](/documentation/platform/pki/certificates/profiles) configured for [ACME enrollment](/documentation/platform/pki/enrollment-methods/acme).
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 on Reveal ACME EAB option to open the ACME details modal.
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 your certificate profile's ACME configuration, you'll need to collect three essential pieces of information:
From the ACME configuration, gather the following values:
1. **ACME Directory URL**: The ACME endpoint URL for your Infisical instance
- Format: `https://your-infisical-instance.com/api/v1/pki/certificate-profiles/{profile-id}/acme/directory`
2. **EAB Key Identifier (KID)**: External Account Binding key identifier
3. **EAB Secret**: External Account Binding secret key
- 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.
@@ -44,19 +39,11 @@ Before proceeding, ensure you have:
</Step>
<Step title="Install Certbot">
Install Certbot on your Tomcat server by following the official installation instructions:
Install Certbot on the server where Tomcat is running by following the official Certbot [installation guide](https://certbot.eff.org/instructions).
Visit the [Certbot installation guide](https://certbot.eff.org/instructions) and select your operating system for detailed installation steps.
The installation guide provides up-to-date instructions for various Linux distributions and package managers, ensuring you get the most current version of Certbot.
For most Ubuntu/Debian systems, you can use:
```bash
sudo apt install certbot
```
The installation guide provides up-to-date instructions for various Linux distributions and package managers.
After installation, verify that Certbot is working correctly:
After installation, you can verify that Certbot has been installed correctly by running:
```bash
certbot --version
@@ -64,13 +51,15 @@ Before proceeding, ensure you have:
</Step>
<Step title="Request Certificate Using Certbot">
Since Tomcat doesn't have a native Certbot plugin, use the standalone authenticator to obtain certificates. **Important**: Stop Tomcat before running this command as Certbot needs to bind to port 80.
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
```
Then request the certificate:
Run the following command to request a certificate from Infisical:
```bash
sudo certbot certonly \
@@ -84,58 +73,179 @@ Before proceeding, ensure you have:
--non-interactive
```
**Parameter breakdown:**
- `certonly`: Obtain certificate without installing it
- `--standalone`: Use standalone authenticator (requires port 80)
- `--server`: Your Infisical ACME directory URL
- `--eab-kid`: Your EAB key identifier from Infisical
- `--eab-hmac-key`: Your EAB secret from Infisical
- `-d`: Domain name for your certificate
- `--email`: Contact email for important account notifications
- `--agree-tos`: Agree to ACME server's Terms of Service
- `--non-interactive`: Run in non-interactive mode
For guidance on each parameter:
<Note>
Replace the placeholder values with your actual configuration:
- `https://your-infisical-instance.com/api/v1/pki/certificate-profiles/{profile-id}/acme/directory`: Your Infisical ACME endpoint
- `your-eab-key-identifier` and `your-eab-secret`: Your External Account Binding credentials
- `example.infisical.com`: Your actual domain name
- `admin@example.com`: Your contact email
</Note>
</Step>
- `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).
<Step title="Configure Automatic Renewal">
To renew certificates, you can test the renewal process manually:
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 certbot renew --dry-run
```
Manual renewal process:
```bash
sudo systemctl stop tomcat
sudo certbot renew --quiet
# Copy certificates to Tomcat configuration directory and restart
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>
Since Tomcat requires manual certificate file copying, automatic renewal requires a custom script. For production environments, consider creating a cron job that stops the server, renews certificates, copies them to the configuration directory, and restarts the server.
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 successful certificate installation, check that certificate files were created:
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:
- `cert.pem` (leaf certificate)
- `chain.pem` (intermediate certificate)
- `fullchain.pem` (leaf + intermediate certificates)
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>

123
docs/documentation/platform/pki/integration-guides/windows-server-acme.mdx
View File

@@ -1,137 +1,147 @@
---
title: "Windows Server"
description: "Learn how to issue SSL/TLS certificates from Infisical PKI using ACME enrollment on Windows Server with win-acme"
description: "Learn how to issue SSL/TLS certificates from Infisical using ACME enrollment on Windows Server with win-acme"
---
This guide will provide a high level overview on how you can use [Infisical PKI](/documentation/platform/pki/overview) and win-acme to issue SSL/TLS certificates for your Windows Server environments using the [ACME protocol](/documentation/platform/pki/enrollment-methods/acme). For more background about the ACME protocol, see the [ACME specification (RFC 8555)](https://tools.ietf.org/html/rfc8555).
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.
## Overview
Win-acme is a feature-rich ACME client designed specifically for Windows environments, offering seamless integration with IIS, Windows Certificate Store, and various other certificate storage options. This integration enables Windows Server environments to leverage Infisical's certificate management capabilities with automated certificate enrollment and renewal.
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 proceeding, ensure you have:
Before you begin, make sure you have:
- A Windows Server instance running with administrative access
- A [certificate profile](/documentation/platform/pki/certificates/profiles) configured for [ACME enrollment](/documentation/platform/pki/enrollment-methods/acme) in Infisical
- Network connectivity from Windows Server to your Infisical instance
- 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 Infisical PKI project and locate your [certificate profile](/documentation/platform/pki/certificates/profiles) configured for [ACME enrollment](/documentation/platform/pki/enrollment-methods/acme).
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 on Reveal ACME EAB option to open the ACME details modal.
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">
Download and install win-acme on your Windows Server using one of the following methods
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
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 installed, you can install win-acme as a global tool:
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 `wacs` command available system-wide.
This makes the `wacs` command available system-wide.
</Tab>
</Tabs>
</Step>
<Step title="Request Certificate Using Command Line">
Use the following win-acme command structure to request a certificate from Infisical PKI:
Run the following win-acme command to request a certificate from Infisical:
```powershell
wacs.exe --target manual --host <your-certificate-dns> --baseuri "<ACME Directory URL>" --eab-key-identifier "<EAB KID>" --eab-key "<EAB Secret>" --validation selfhosting --store pemfiles --pemfilespath "<your-folder-path>" --verbose
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
```
**Parameter breakdown:**
- `--target manual`: Specifies manual target configuration
- `--host <domain>`: The domain name for your certificate
- `--baseuri`: Your Infisical ACME directory URL
- `--eab-key-identifier`: Your EAB key identifier from Infisical
- `--eab-key`: Your EAB secret from Infisical
- `--validation selfhosting`: Uses self-hosting validation method
- `--store pemfiles`: Stores certificates as PEM files
- `--pemfilespath`: Directory where certificates will be saved
- `--verbose`: Enables detailed logging
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:
- `<your-certificate-dns>`: Your actual domain name
- `<ACME Directory URL>`: Your Infisical ACME endpoint
- `<EAB KID>` and `<EAB Secret>`: Your External Account Binding credentials
- `<your-folder-path>`: Desired certificate storage location
- `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. Here are common alternatives to PEM files:
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:
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 "<ACME Directory URL>" --eab-key-identifier "<EAB KID>" --eab-key "<EAB Secret>" --validation selfhosting --store certificatestore --verbose
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 with password protection:
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 "<ACME Directory URL>" --eab-key-identifier "<EAB KID>" --eab-key "<EAB Secret>" --validation selfhosting --store pfxfile --pfxfilepath "C:\certificates" --pfxpassword "your-secure-password" --verbose
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:
For IIS Central SSL store integration in high-scale environments:
```powershell
wacs.exe --target manual --host example.infisical.com --baseuri "<ACME Directory URL>" --eab-key-identifier "<EAB KID>" --eab-key "<EAB Secret>" --validation selfhosting --store centralssl --centralsslstore "C:\CentralSSL" --verbose
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 for certificate 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:
Include the `--setuptaskscheduler` parameter in your initial command to automatically create the renewal task:
```powershell
wacs.exe --target manual --host example.infisical.com --baseuri "<ACME Directory URL>" --eab-key-identifier "<EAB KID>" --eab-key "<EAB Secret>" --validation selfhosting --store pemfiles --pemfilespath "C:\certificates" --setuptaskscheduler --verbose
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:
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:
@@ -140,22 +150,23 @@ Before proceeding, ensure you have:
Get-ScheduledTask -TaskName "*win-acme*"
```
The task will:
- Run under the SYSTEM account
- Check certificates daily for renewal eligibility
- Automatically renew certificates that are within the renewal threshold
- Log renewal activities to Windows Event Viewer and log files
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, so once a certificate is created, the renewal process will use the same parameters (ACME endpoint, EAB credentials, storage options) for future renewals.
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 the certificate files are created:
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:
Check your specified PEM files directory to ensure all certificate components are present:
```powershell
Get-ChildItem "C:\certificates" -Filter "*.pem"
@@ -170,11 +181,13 @@ Before proceeding, ensure you have:
![Windows Server Generated PEM files](/images/platform/pki/integrations/windows-server/certificates-created.png)
</Tab>
<Tab title="Windows Certificate Store">
Check the certificate store using PowerShell:
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>