Breadcrumbs

BYOC: Prerequisites

Prepare prerequisites for updating installer-generated certificates with your own public or enterprise certificates.

Overview

There are two approaches for BYOC certificate management:

BYOC Approach

Description

Recommended for

Approach 1: Replace external certificates only

Replace the external (user-facing) certificate with your enterprise PKI or public CA certificate, while keeping internal server/client certificates, admin client certificates, and SAML signing certificate generated by the installer.

Most production deployments.

Approach 2: Replace all certificate material

Replace the external certificate and replace internal server/client certificates, admin client certificates, and SAML signing certificate using your enterprise PKI / organization process.

Production only if required by policy (higher operational overhead).

Note: External TLS is typically terminated at the frontend HAProxy (or an external load balancer, if deployed in front of HAProxy), depending on your topology.

Secrets Manager Keystore: The Secrets Manager (SM) service uses a dedicated keystore to generate and protect platform key material. For Proof of Concepts, you may use the installer-generated alias values. For production, you must regenerate these aliases so they are unique to your environment and do not rely on defaults.

See BYOC: Update Secrets Manager Keystore.

For Single-Node Installations:

Single-node installations consider the Single Node to be both Frontend and Backend. All listed prerequisites and steps should be applied to the single node server.

System Prerequisites

Before updating or replacing certificates, ensure you have the following prepared.

Directory Path References:

There are two referenced directory locations in these instructions:

  1. installer_dir: the location where the unzipped install files reside, including all installation scripts and supporting files.

  2. agilesec_install_dir: the location where AgileSec is installed to.

Administrative Access (all nodes)

Administrative access to all node servers, including

  • Permission to read/write under $INSTALLER_DIR/certificates.

  • sudo permissions to run scripts such as ./scripts/tune.sh

  • Ability to restart services after certificate changes (for example, using ./scripts/manage.sh) and access to logs for troubleshooting.

Java keytool (all nodes)

Ensure Java keytool is available on all nodes for inspecting keystores (.p12) and for generating sm-service keystore. If keytool is not already available on the node, extract it to $INSTALLER_DIR/tmp from the bundled JRE archive:

# Set environment variable to installer files location
INSTALLER_DIR=<path-to-installer-dir>

# Extract java keytool to the correct location
mkdir -p $INSTALLER_DIR/tmp
tar -xzf \
  $INSTALLER_DIR/apps/openlogic-openjdk-jre-*17.0.14+7*-linux-x64.tar.gz \
  -C $INSTALLER_DIR/tmp
export \
  JAVA_PATH=$INSTALLER_DIR/tmp/openlogic-openjdk-jre-17.0.14+7-linux-x64

After extraction, keytool will be available under: $INSTALLER_DIR/tmp/openlogic-openjdk-jre-17.0.14+7-linux-x64/bin/keytool.

Note: Additional, specific guidelines for each certificate type are covered in their individual updating steps.

Configuration Decisions

Ensure stakeholders confirm the following configuration items prior to certificate management. Ensure your configuration file multi_node_config.conf aligns with these decisions when generating .env for AgileSec installation.

The following configuration parameters must align between BYOC materials and install configuration (or vice versa). Update multi_node_config.conf as needed and generate .env to match your organization’s certificate requirements prior to installation.

For Single-Node Installations:

Update single_node_config.conf instead of multi_node_config.conf.

Approach 1: Replace external certificates only

Description

multi_node_config.conf Parameter(s)

Default

Applicable Certificates

Root CA Validity

rootca_cert_expiry_days

3650 (days)

Root CA

Other Certificate Validity

cert_expiry_days

365 (days)

All BYOC Certificates

Platform External FQDN

The primary external facing FQDN for the platform.

<analytics_hostname>.<analytics_domain>

agilesec.<company-domain>

External (User-Facing) Certificates

Server Certificate Common Name (CN) and Filenames Prefix

If you override this default, ensure the replacement certificates are valid for your organization’s operational and renewal requirements.

server_certificate_name_prefix

agilesec-internal-server

External (User-Facing) Certificates, Internal Server Certificates

Approach 2: Replace all certificate material

Note: rootca_cert_expiry_days and cert_expiry_days are not relevant to Approach 2 as the installer-generated CA and other certificates will be completely replaced.

Description

multi_node_config.conf Parameter

Default

Applicable Certificates

Platform External FQDN

Primary external facing FQDN for the platform

<analytics_hostname>.<analytics_domain>

agilesec.<company-domain>

External (User-Facing) Certificates

Internal Domain

Internal domain used for node-to-node communication.

<analytics_internal_domain>

kf-agilesec.com

All internal certificates: Internal Server Certificates, mTLS Client Certificates, Admin Client Certificates, SAML IdP Signing Certificate, Secrets Manager Keystore

Server Certificates base Subject Distinguished Name (DN)

Set this value before installation so the expected subjects match your environment.

server_certificate_subject

OU=Server,O=Keyfactor,ST=Ohio,C=US

  • Must be X.500 standard format.

  • Must include OU=Server.

SAML IdP Signing Certificate, Secrets Manager Keystore

Client Certificates base Subject Distinguished Name (DN)

Set this value before installation so the expected subjects match your environment.

client_certificate_subject

OU=Client,O=Keyfactor,ST=Ohio,C=US

  • Must be X.500 standard format.

  • Must include OU=Client.

mTLS Client Certificates

Server Certificate Common Name (CN) and Filenames Prefix

If you override this default, ensure the replacement certificates are valid for your organization’s operational and renewal requirements.

server_certificate_name_prefix

agilesec-internal-server

External (User-Facing) Certificates, Internal Server Certificates

Client Certificates Common Name (CN) and Filenames Prefix

If you override this default, ensure the replacement certificates are valid for your organization’s operational and renewal requirements.

client_certificate_name_prefix

shared-client

mTLS Client Certificates

Client Certificate BYOC Model

See details below for choosing and setting the correct Client Certificate BYOC Model.

use_single_client_cert

true

mTLS and Admin Client Certificates

Server Certificate BYOC Model

Do NOT override this value. Using individual server certificates is not currently supported.

use_single_internal_server_cert

true

(Do not override this default.)

Internal Server Certificates

Choose Client Certificate BYOC Model

There are two BYOC models for mTLS and Admin Client Certificates. The model is determined by the configuration variable use_single_client_cert, which defaults to true.

Model 1: Single Shared Client Certificate (installer default)

Set use_single_client_cert=true to use one client certificate shared by all services:

  • A single shared client certificate is used by all platform services for mTLS client authentication.

  • A single admin client certificate is used for administrative authentication to both MongoDB and OpenSearch.

  • This approach mirrors installer behavior, but certificates will be issued by your enterprise PKI.

Model 2: Per-Service Client Certificates

Set use_single_client_cert=false for stronger isolation and independent rotation:

  • Use separate client certificates per service for mTLS client authentication.

  • Use separate client certificates for administrative authentication to both MongoDB and OpenSearch.

  • Enables independent rotation of a single service credential without impacting others.

Set use_single_client_cert according to the model you wish to use for mTLS and Admin Client Certificates.

Secrets Manager (SM) Keystore Aliases

For Proof of Concepts, you may use the installer-generated alias values. For production, you must regenerate these aliases so they are unique to your environment and do not rely on defaults.

Recommendation: Regenerate these aliases even for POCs to align with production practices and avoid accidental reuse across environments.

See BYOC: Update Secrets Manager Keystore.

SM Alias

multi_node_config.conf Parameter

Default Installer-Generated Example

Regeneration Instructions

Symmetric AES-256 CMK (SecretKeyEntry) Alias

sm_service_cmk_alias

sm_service_cmk_alias='561280514aa561b399df58dfadeab7e7'

openssl rand -hex 16

Asymmetric NIST P-384 key pair (PrivateKeyEntry) Alias

sm_service_keypair_alias

sm_service_keypair_alias='192851d9a7ead8e074dec80255727998'

openssl rand -hex 16