BYOC Approach 1: BYOC External Certificates Only

Replace only External (User-Facing) Certificates with your own public CA or enterprise PKI certificates. Keep installer-generated internal server/client certificates, admin client certificates, SAML signing certificate, and Secrets Manager keystore.

Overview

The recommended strategy for replacing External Certificates is

Generate a baseline certificate structure from the installer on backend-1. Deploy the generated structure and .env files to all other nodes.
Append the public or enterprise PKI Root CA to the installer-generated Root CA.
Generate BYOC External Certificate materials meeting all requirements.
Replace the installer-generated External Certificate in place.
1. Use the same filenames and directories as installer-generated material on all nodes.
Set replacement certificate and key file permissions to 400 (read-only for owner) after replacing.

Note on Enterprise PKI issuance methods:

You are responsible for obtaining the certificate material in the filenames and formats required by AgileSec as defined in the following sections. Generally, required files include a certificate, private key, and any intermediate chain in PEM format.

Depending on your PKI, you may either (a) generate a CSR and have the PKI sign it, or (b) request a certificate where the PKI generates and returns a keypair (often as a PKCS#12/PFX bundle). AgileSec supports both approaches, as long as you can provide the resulting materials as PEM files with the required filenames. If your PKI returns a PKCS#12/PFX bundle, extracting it into separate PEM files is your responsibility.

Important: Protective Certificate and Key File Permissions

generate_certs.sh applies restrictive permissions to protect installer generated certificate and key files.

BYOC certificate and key files should also be readable only by the owning user. Set replacement certificate and key file permissions to 400 (read-only for owner) after copying them into place.

Prerequisites

Ensure all BYOC: Prerequisites have been met, including correct variables in .env.

Important

Pre-Install BYOC: If .env does not align with BYOC certificates materials or models, update and regenerate .env or BYOC materials to align before proceeding.

Post-Install BYOC: It is not recommended to update configuration variables affecting BYOC post-installation. Align BYOC materials with the AgileSec installation’s current .env.

Set Environment Variable

Set variable $installer_dir on backend-1 to easily copy and paste guide instructions into terminal:
```
export installer_dir=</path-to-installer-directory>
```

If performing post-install BYOC, also set the installation directory variable $agilesec_installation_dir:
```
$agilesec_installation_dir=</path-to-agilesec-installation>
```

Step 1 (Pre-Install Only): Prepare Baseline Certificate Structure

When performing pre-install BYOC, follow these instructions for preparing the baseline certificate structure. This step does not need to be repeated for post-install BYOC.

Generate baseline certificate materials and directory structure.
Deploy baseline certificates and .env files to all nodes.

Generate Baseline Certificate Structure

Installer-generated certificate materials and directory structure can be created with generate_certs.sh. Use the same filenames and directory structure as the installer generates for any BYOC materials.

On backend-1 or single-node, run generate-certs.sh to generate and self-sign all required certificates:

cd $installer_dir/certificates/
./generate-certs.sh
cd ..

generate-certs.sh populates all required certificate files under the certificates directory and generates an archive file named kf-agilesec.internal-certs.tgz. kf-agilesec.internal-certs.tgz contains all generated certificate files as well as each node’s .env. After generation, kf-agilesec.internal-certs.tgz must be copied from backend-1 to all other nodes.

The script has the following additional option flags available. Installation options can also be found by running ./generate-certs.sh --help.

generate-certificates.sh short flag	Required	Description
`-n`	No	Non-interactive mode: no prompts, overwrite files.
`-e <path>`	No	Path to .env file. Defaults to `../.env`
`-v`	No	Verbose mode: outputs additional console statements for debugging.
`-V <directory>`	No	Validation-only mode: validates existing certificates in specified directory.

Info: The installer-generated CA cert self signs certificates generated by generate_certs.sh.

Deploy Generated Files to All Nodes

Copy kf-agilesec.internal-certs.tgz from backend-1 to all other nodes.

For each node, copy kf-agilesec.internal-certs.tgz to $installer_dir/certificates/.

4-Node Cluster Example

scp kf-agilesec.internal-certs.tgz <user@frontend-1 IP>:$installer_dir/certificates/
scp kf-agilesec.internal-certs.tgz <user@frontend-2 IP>:$installer_dir/certificates/
scp kf-agilesec.internal-certs.tgz <user@backend-2 IP>:$installer_dir/certificates/

Note: scp command is provided as an example. You may use any file transfer method suitable to your environment.

On each node, unarchive kf-agilesec.internal-certs.tgz to create the certificate structure:

cd $installer_dir/certificates/ 
tar zxvf kf-agilesec.internal-certs.tgz

Note: kf-agilesec.internal-certs.tgz also contains each node’s .env.

Step 2: Update Root CA Certificate Chain

When replacing only the external (user-facing) platform endpoint certificate, the external CA must be appended to the installer-generated CA to create a complete chain of trust.

The Root CA certificate chain establishes the trust anchor for all internal TLS and mTLS communication within the AgileSec Platform. Platform services validate peer certificates (and client certificates for mTLS) against this CA chain. In multi-node deployments, the same CA chain must be trusted consistently across all nodes to prevent service-to-service authentication failures.

Important: Do not replace the installer-generated internal CA files under $installer_dir/certificates/ca. The installer-generated CA chain will still be used for internal certificates.

Note: If you are using a public CA, download the Root CA certificate (and any required intermediate certificates, if your organization requires them) from the public CA’s official distribution page and use those PEM files in the steps below.

Update CA Trust Chains

The following steps must be performed on all nodes requiring trust with the external endpoint (backend, frontend, and scan nodes).

Pre-Install BYOC Steps

The following steps must be performed on all nodes requiring trust with the external endpoint (backend, frontend, and scan nodes).

Install the BYOC CA Root (and intermediate, if applicable) certificate on each node.

Backup the original trust file $installer_dir/certificates/ca/agilesec-rootca-cert.pem:

# Backup original AgileSec CA trust file
cp -a $installer_dir/certificates/ca/agilesec-rootca-cert.pem \
  $installer_dir/certificates/ca/agilesec-rootca-cert.pem.bak.$(date +%Y%m%d%H%M%S)

Append the external CA root certificate to the existing AgileSec CA trust file agilesec-$installer_dir/certificates/ca/agilesec-rootca-cert.pem in the following order:
Installer-Generated-CA -> BYOC Issuing/Intermediate CA (if applicable) -> BYOC Root CA
```
# Append external CA Root to AgileSec CA trust file
cat <external_ca_root>.pem >> $installer_dir/certificates/ca/agilesec-rootca-cert.pem
```

Protect the CA chain with chmod 400:

chmod 400 $installer_dir/certificates/ca/agilesec-rootca-cert.pem

Install CA into system trust store with tune.sh. On each node, run tune.sh to install the updated root CA chain into the node trust store.
```
cd $installer_dir
sudo ./scripts/tune.sh -u <user>
```

Post-Install BYOC Steps

Important: Shut down the cluster before performing these steps.

Perform these steps on all backend nodes, primary frontend (frontend-1), and the coordinator node:

Install the BYOC CA Root (and intermediate, if applicable) certificate on each node.

Backup the original trust file $installer_dir/certificates/ca/agilesec-rootca-cert.pem:

# Backup original AgileSec CA trust file
cp -a $installer_dir/certificates/ca/agilesec-rootca-cert.pem \
  $installer_dir/certificates/ca/agilesec-rootca-cert.pem.bak.$(date +%Y%m%d%H%M%S)

Append the external CA root certificate to the existing AgileSec CA trust file $agilesec_installation_dir/certificates/ca/agilesec-rootca-cert.pem in the following order:
Installer-Generated-CA -> BYOC Issuing/Intermediate CA (if applicable) -> BYOC Root CA
```
# Append external CA Root to AgileSec CA trust file
cat <external_ca_root>.pem >> $installer_dir/certificates/ca/agilesec-rootca-cert.pem
```
Copy the updated CA chain to the installer directory (tune.sh reads from this location) at $installer_dir/certificates/ca/agilesec-rootca-cert.pem.
Protect both copies of agilesec-rootca-cert.pem with chmod 400.
Install CA into system trust store with tune.sh. On each node, run tune.sh to install the updated root CA chain into the node trust store.
```
cd $installer_dir
sudo ./scripts/tune.sh -u <user>
```
Update the Root CA trust bundle copy maintained by OpenSearch under its service directory $agilesec_installation_dir/services/opensearch/config/certs/agilesec-rootca-cert.pem.

Update the JVM default truststore. tune.sh only updates the OS-level trust store, not the JVM's default cacerts truststore. Java service relying on the default JVM truststore for TLS trust will not pick up the new Root CA unless this update is done manually:

cd $agilesec_installation_dir
./bin/java/bin/keytool -delete -alias "root.<analytics_internal_domain>" \
  -keystore bin/java/lib/security/cacerts \
  -storepass changeit
  
./bin/java/bin/keytool -noprompt -importcert -trustcacerts \
  -alias "root.<analytics_internal_domain>" \
  -file certificates/ca/agilesec-rootca-cert.pem \
  -keystore bin/java/lib/security/cacerts \
  -storepass changeit

After completing all post-install BYOC certificate replacements, restart the cluster.

Step 3: External (User-Facing) Certificates

The external (user-facing) certificate secures HTTPS access to the AgileSec Platform for end users and API clients. By default, this certificate is presented by the frontend HAProxy, which terminates TLS for the platform’s external endpoint.

External Certificate Requirements

Generate External Server Certificates BYOC materials meeting the following requirements:

	Requirement	Detail
1	Certificate Filename	`agilesec-analytics-server-cert.pem` If signed by an intermediate CA, concatenate: Certificate → Intermediates. If your CA issues through one or more intermediates, concatenate them into the external certificate file: Leaf Certificate → Intermediates, in order. Warning: Do not add intermediates to the trust anchor file `agilesec-rootca-cert.pem`. `agilesec-rootca-cert.pem` is the trust anchor file for internal platform certificates and is not consulted for the external certificate's chain validation, even if the external certificate is signed by a different CA than your internal certificates.
2	Private Key Filename	`agilesec-analytics-key.pem`
3	Certificate Key Combo File	`agilesec-analytics-server-combo-cert-key.pem` Concatenate in the following order: certificate file (already including intermediates if applicable) → Key. Warning: Missing intermediates commonly cause client errors such as "unable to verify the first certificate."
4	SAN	`<analytics_hostname>.<analytics_domain>` must be included as a DNS SAN for clients to validate against.
5	CN	May be set to the same FQDN for readability but is not relied on for validation.
6	Protective Permissions	Apply `chmod 400` to all BYOC materials.

Recommended: Approach with Load Balancer

For production deployments, it is highly recommended to place an enterprise load balancer (or reverse proxy) in front of the platform HAProxy rather than replacing HAProxy entirely. This preserves the platform’s default ingress behavior while allowing centralized HA, TLS management, and enterprise controls.

TLS termination options for production environments

TLS Termination Option	Description	Approach
Terminate TLS at the enterprise load balancer	The load balancer presents the public/enterprise certificate to end users and forwards traffic to HAProxy.	Replace the BYOC external certificate on the load balancer. If you do not want to re-encrypt traffic between the load-balancer and HAProxy, no further steps are required. Leave the installer-generated certificate on the nodes alone.
Pass-through TLS to HAProxy	The load balancer forwards encrypted traffic and HAProxy presents the public/enterprise certificate to end users.	Install the BYOC external certificate on Frontend Nodes by replacing the installer-generated external certificate on all frontend nodes.

TLS Termination Option

Description

Approach

Terminate TLS at the enterprise load balancer

The load balancer presents the public/enterprise certificate to end users and forwards traffic to HAProxy.

Replace the BYOC external certificate on the load balancer.

If you do not want to re-encrypt traffic between the load-balancer and HAProxy, no further steps are required. Leave the installer-generated certificate on the nodes alone.

Pass-through TLS to HAProxy

The load balancer forwards encrypted traffic and HAProxy presents the public/enterprise certificate to end users.

Install the BYOC external certificate on Frontend Nodes by replacing the installer-generated external certificate on all frontend nodes.

Terminate TLS at the enterprise load balancer

For production deployments with TLS terminated at the enterprise load balancer, replace the external certificate on the load balancer with one issued by your enterprise PKI or a public CA (agilesec-analytics-server-combo-cert-key.pem). There is no need to replace installer-generated external certificates on the nodes.

Note: No further steps are required unless you want to re-encrypt traffic between the load balancer and HAProxy. If you want to re-encrypt traffic, you may do so. See your load balancer provider’s documentation for guidance. AWS example documentation is available here: https://repost.aws/questions/QUDFSStHDQSoGg-oBs53T9Eg/off-loading-and-re-encrypting-traffic-on-application-load-balancer

Pass-Through TLS to HAProxy

For production deployments with a load balancer set up with TLS Pass-through, replace the external certificate on all frontend nodes with one issued by your enterprise PKI or a public CA.

Deploy BYOC External Server Certificate materials to the following locations and nodes:

Requirement	Details / Permissions
BYOC Files	`agilesec-analytics-server-cert.pem` `agilesec-analytics-key.pem` `agilesec-analytics-server-combo-cert-key.pem`
BYOC Directory Location	`$installer_dir/certificates/<analytics_hostname>.<analytics_domain>` Note for Post-Install BYOC: Place BYOC certificates materials in the install directory location instead of installer directory, `$agilesec_installation_dir/certificates/<analytics_hostname>.<analytics_domain>`.
Nodes	All frontend nodes

Approach Without Load Balancer

If not using a load balancer, follow the same steps as Pass-through TLS to replace the External Certificate but only deploy to frontend-1. Without a load balancer, frontend-1 will be the single-point of failure.

Verification

Follow On-Prem AgileSec Validation Checklist to verify platform functionality.