mirror of
https://github.com/awatertrevi/infisical.git
synced 2026-10-08 14:28:20 +00:00
Few changes on PKI ACME docs
This commit is contained in:
Carlos Monastyrski
@@ -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).
|
||||
|
||||
|
||||
Click on Reveal ACME EAB option to open the ACME details modal.
|
||||
Click the **Reveal ACME EAB** option to view the ACME configuration details.
|
||||
|
||||
|
||||
|
||||
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
|
||||
- `[email protected]`: 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>
|
||||
Reference in New Issue
Block a user