On-Prem Certificates Management Guide

This guide describes how to configure and manage certificates for an on-premises AgileSec Platform deployment. It covers certificate types, requirements, initial setup, and both installer-generated and Bring Your Own Certificate (BYOC) options for root CAs, external and internal server certificates, client certificates, SAML IdP signing certificates, and the Secrets Manager keystore. It also provides guidance on file permissions, verification, and certificate renewal to ensure secure platform operation.

1. Overview

This guide explains how to manage TLS certificates for the AgileSec Platform (On-Prem), including how to generate, deploy, replace, and renew certificate material across single-node and multi-node installations.

It covers:

• External (user-facing) certificates used for platform access (Web UI and API ingress)

• Internal certificates used for TLS and mTLS within the platform (service-to-service and sensor-to-platform, where applicable)

• Client certificates (shared or per-service) used for mTLS client authentication

• The SAML (SSO) signing certificate used by the platform for integrated SSO components

• Certificate requirements (formats and SANs), file naming conventions, and file locations

• Verification commands and troubleshooting steps to validate certificate deployment and trust

AgileSec supports two approaches for certificate management:

• Option A: Installer-generated certificates — Use generate_certs.sh to generate and self-sign all required certificate material. Recommended for POCs and first-time installations.

• Option B: Bring Your Own Certificates (BYOC) — Use certificates issued by your enterprise PKI and/or a public CA. Recommended for production deployments.

Option B has two supported variants:

• Option B1: BYOC for external and internal certificates — Replace the external (user-facing) certificate and all internal server/client certificates with certificates issued by your enterprise PKI.

• Option B2: BYOC for external certificates only — Replace only the external (user-facing) certificate with a certificate issued by your enterprise PKI or a public CA, while keeping the installer-generated internal server/client certificates.

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.

1.1 Common Certificate Management Scenarios

Use the options below to choose the approach that best fits your environment and certificate policy.

Option 1: Installer-generated certificates

• Recommended for: POCs and first-time installations.

• Description: Use all certificate material generated by the installer (generate_certs.sh).

Sections to follow

• Section 4. Initial Certificate Setup

Option 2: Replace external certificates only

• Recommended for: Production (most common).

• Description: Replace external (user-facing) certificates with enterprise PKI or a public CA, but keep internal server/client certificates, admin client certificates, SAML signing certificate, and Secrets Manager keystore generated by the installer.

Sections to follow

• Section 4. Initial Certificate Setup

• Section 5. Root CA Certificate → follow 5.3 Option B2 (BYOC for external certificates only) in that section

• Section 6. External (User-Facing) Certificate → follow 6.3 Option B: BYOC.

Option 3: Replace all certificate material

• Recommended for: Production only if required by enterprise certificate policy (adds operational overhead for issuance and rotation).

• Description: Replace external certificates with enterprise PKI/public CA and replace all internal certificate material (internal server certificates, client certificates, admin client certificates, SAML signing certificate, and Secrets Manager keystore) using your enterprise PKI / organization process.

Sections to follow

• Section 4. Initial Certificate Setup

• Section 5. Root CA Certificate → follow 5.3 Option B: (BYOC for all internal certificates) in that section

• Section 6. External (User-Facing) Certificate → follow 6.3 Option B: BYOC.

• Section 7. Internal Server Certificates → follow 7.4 Option B: BYOC

• Section 8. Client Certificates (mTLS) → follow 8.3 Option B: BYOC

• Section 9. Admin Client Certificates → follow 9.3 Option B: BYOC

• Section 10. SAML IdP Signing Certificate → follow 10.4 Option B: BYOC

• Section 11. Secrets Manager Keystore → follow 11.6 Option B: BYOC

Notes

• If you replace internal certificates with enterprise PKI, follow the BYOC paths consistently for Root CA, Internal Server, Client (mTLS), Admin Client, SAML, and Secrets Manager sections.

• Option 2 (external-only) is the most common production approach.

2. Certificate Types

This section explains where certificates are deployed in the platform and how TLS trust is established across the main traffic paths. At a high level, the platform has an external entry point for user/API access and an internal service network where components communicate over encrypted channels. Certificate deployment is aligned to these paths so that inbound connections are terminated with the correct endpoint certificate and internal components can authenticate each other consistently.

In addition to runtime traffic, the platform includes a single SSO signing certificate used for SAML-based integrations within the platform. This certificate is used to sign assertions and is configured as part of the integrated SSO setup.

The AgileSec Platform uses the following certificate types, based on where TLS is terminated and which components require authentication.

• External (user-facing) certificates secure ingress traffic into the platform and are presented to end users and client applications when accessing the Web UI and API endpoints. For production deployments, these certificates should ideally be issued by a publicly trusted (public) CA to ensure browser and client trust. External TLS traffic is terminated at the frontend HAProxy.

• Internal (platform) certificates are used for TLS and mTLS within the platform. These certificates secure service-to-service communication and protect internal endpoints that are not intended to be publicly exposed. Internal certificates are commonly issued by an internal CA (enterprise PKI like EJBCA) or generated by the installer for proof-of-concepts and first-time installations.

• Client certificates are used for mTLS client authentication when services connect to internal endpoints. By default, the installer can generate a shared client certificate used by all services. You can also configure the installer to generate separate client certificates per service when stronger isolation is required.

• Admin client certificates (OpenSearch and MongoDB) are privileged client certificates used for administrative connections to OpenSearch and MongoDB (for example, during installation, bootstrap, and management operations). These are distinct from general service-to-service mTLS client certificates.

• SAML (SSO) IdP signing certificate and key are used by the platform when it acts as the Identity Provider (IdP) for SSO integrations (for example, OpenSearch Dashboards). The platform uses this credential to sign SAML assertions, and the corresponding public certificate is trusted by the integrated Service Provider to validate those assertions.

• Security Manager keystore (PKCS#12) is a service-specific keystore used by the Security Manager (SM) to generate and store the customer master key (CMK). The keystore is also used by SM for secure key material storage and retrieval.

3. Requirements

3.1 General Requirements

Before updating or replacing certificates, ensure you have the following:

• Administrative access to the installer host (and all nodes in a multi-node deployment), including permission to read/write under <installer_directory>/certificates.

• Platform DNS and domain details, including:

  • External platform FQDN: <analytics_hostname>.<analytics_domain>

  • Internal domain: <analytics_internal_domain>

• Certificate materials for the approach you plan to use:

  • If using your own CA/public CA: the server certificate, private key, and full certificate chain (intermediates/root as applicable)

  • If generating with the installer: access to the installer scripts and the .env file used for generation

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

• Java keytool available for inspecting keystores (.p12) and for generating sm-service keystore. If keytool is not already available on the node, extract it to <installer_directory>/tmp from the bundled JRE archive:

  CODE

  INST_DIR=<installer_directory>
  mkdir -p $INST_DIR/tmp
  tar -xzf \
    $INST_DIR/apps/openlogic-openjdk-jre-*17.0.14+7*-linux-x64.tar.gz \
    -C <installer_dir>/tmp
  export \
    JAVA_PATH=$INST_DIR/tmp/openlogic-openjdk-jre-17.0.14+7-linux-x64
  

After extraction, keytool will be available under: <installer_directory>/tmp/openlogic-openjdk-jre-17.0.14+7-linux-x64/bin/keytool

3.2 Certificate Requirements

The following requirements apply to all certificates used by the AgileSec Platform, regardless of whether you use installer-generated certificates (generate_certs.sh) or bring your own certificates (BYOC).

a. Subject (DN) conventions: When generating certificates, use the subject values defined in the .env file:

• Server certificates: use server_certificate_subject as the base Distinguished Name (DN).

• Client certificates: use client_certificate_subject as the base DN.

Set these values before generating certificates when using installer-generated certs. For BYOC, set these values before installation so the expected subjects match your environment.

b. Certificate validity periods: The default certificate lifetimes are controlled by the .env file:

• rootca_cert_expiry_days=3650 (Root CA validity)

• cert_expiry_days=365 (All other certificates)

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

c. Filenames and locations: Use the same filenames and directory structure as generated by generate_certs.sh. This applies to BYOC as well. Replace the existing files in place so service configuration files do not need to be modified.

d. File permissions: Certificate and key files should be readable only by the owning user. Set file permissions to 400 (read-only for owner).

4 Initial Certificate Setup

This section describes the initial, recommended workflow for preparing certificate files before installation. The goal is to ensure the platform has the correct .env configuration, the expected certificate directory layout exists, and (for BYOC) any custom certificate material is placed using the exact filenames AgileSec expects.

Recommended approach (all scenarios): Configure .env first, then run generate_certs.sh to create the baseline certificate structure. If using BYOC, replace the generated files in place using the same filenames and paths.

4.1 Configure .env

The .env file controls certificate subjects, expiry settings, and which certificate models are generated (shared vs per-service client certs, etc.).
Instead of editing .env directly, update the appropriate config template and then generate .env.

1. Edit the sample configuration file for your installation type:

   • Single-node: generate_envs/single_node_config.conf

   • Multi-node: generate_envs/multi_node_config.conf

At a minimum, review and set:

2. Generate .env :

cd <installer_directory>/generate_envs
./generate_envs.sh -t single-node
# or
./generate_envs.sh -t multi-node

Note: For BYOC, these settings still matter because the platform configuration and certificate expectations (CN/SANs and filenames) are derived from them.

4.2 Generate the baseline certificate structure

Run the certificate generation script to create the full set of expected directories and filenames:

cd <installer_directory>/certificates
./generate_certs.sh -t <install_type>

This will populate:

• <installer_directory>/certificates/ca

• <installer_directory>/certificates/<analytics_internal_domain>

• <installer_directory>/certificates/<analytics_hostname>.<analytics_domain>

It will generate baseline certificate assets using the filenames AgileSec expects.

Important Steps

• The script populates the certificate files under the certificates directory and generates an archived named <analytics-internal-domain>-certs.tgz, which you must copy to all other nodes.

• The archive also includes env.backend-2, env.backend-1, and env.frontend-1 in addition to the certificates. The environment configuration files must be copied to <installer_directory>/.env

4.3 File permissions

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

If you are using BYOC, ensure your replacement certificate and key files have the same restrictive permissions after copying them into place (for example, 0400 for key material), consistent with your organization’s requirements.

4.4 Next steps

After generating the baseline certificate structure, proceed based on the option selected in 1.1 Common Certificate Management Scenarios.

5 Root CA Certificate

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.

5.1 Requirements

• Provide the Root CA certificate and any required intermediate CA certificates as a complete CA chain.

• Ensure all internal server and client certificates used by the platform chain back to the trusted CA chain.

• Follow the installer’s expected filenames and directory structure so service configuration does not need to change.

• Apply standard file permissions (see General Requirements).

5.2 Option A: Installer Generated

For POCs and first-time installations, AgileSec can generate the Root CA certificate chain as part of the initial certificate setup. If you followed the steps in Initial Certificate Setup, the Root CA files have already been generated under <installer_directory>/certificates/ca on backend-1. For all other nodes the certificates archive file must be copied and extracted under <installer_directory>/certificates

Run <installer_directory>/scripts/tune.sh -u <user> on each node to install the internal CA chain into the system trust store.

No further action required for Option A.

The following files are generated:

5.3 Option B: Bring Your Own Certificates (BYOC)

For production deployments, you may use your organization’s internal CA (enterprise PKI) and/or a publicly trusted CA.

If using publicly trusted CA, the root certificate might already be present in system trust store. You can use following command to check

trust list --filter=ca-anchors | grep -i -n "<root ca name>"

Option B1 (BYOC for all internal certificates)

Use this option if you are replacing all internal certificates (internal server certificates, client certificates, and admin client certificates) with certificates issued by your enterprise PKI.

The following steps must be performed:

• Export the CA trust chain, including the Root CA and any required intermediate CA certificates.

• On each node, place the CA chain under the installer’s CA directory using the filename expected by AgileSec (so no configuration changes are required):

  • <installer_directory>/certificates/ca/agilesec-rootca-cert.pem
    (recommended: Root + intermediates concatenated in the correct order)

• Run <installer_directory>/scripts/tune.sh -u <user> on each node to install the internal CA chain into the system trust store.

In this model, AgileSec uses the enterprise CA chain for trust, and the installer-generated CA is not used for issuing internal certificates. As a result, the installer-generated CA private key (agilesec-rootca-key.pem) and serial file (agilesec-rootca-cert.srl) are not required for normal operation. They should be removed from the installer host after completing BYOC replacement.

Option B2 (BYOC for external certificates only)

Use this option if you are replacing only the external (user-facing) platform endpoint certificate and keeping the installer-generated internal certificates.

Do not replace the installer-generated internal CA files under: <installer_directory>/certificates/ca

Install the CA Root certificate on all nodes that must trust the external endpoint: backend, frontend, and scan nodes.

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.

Step 1: Append the external CA Root certificate**

Append the external CA root certificate to the AgileSec CA trust file: <installer_directory>/certificates/ca/agilesec-rootca-cert.pem

cp -a <installer_directory>/certificates/ca/agilesec-rootca-cert.pem \
  <installer_directory>/certificates/ca/agilesec-rootca-cert.pem.bak.$(date +%Y%m%d%H%M%S)

cat <external_ca_root>.pem >> <installer_directory>/certificates/ca/agilesec-rootca-cert.pem

Step 2: Run tune.sh

Run tune.sh to install/update the system trust stores:

sudo <installer_directory>/scripts/tune.sh -u <user>

tune.sh installs the updated CA chain into the node trust stores used by AgileSec components.

6 External (User-Facing) Certificate

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.

For production deployments, it is 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 (production):

• Terminate TLS at the enterprise load balancer: The load balancer presents the public/enterprise certificate to end users and forwards traffic to HAProxy.

• Pass-through TLS to HAProxy: The load balancer forwards encrypted traffic and HAProxy presents the public/enterprise certificate to end users.

6.1 Requirements (CN/SANs, chain)

• Hostname: The certificate must cover the external platform FQDN: <analytics_hostname>.<analytics_domain>.

• SANs: The external platform FQDN must be included as a DNS SAN. You may also set the CN to the same FQDN, but do not rely on CN alone.

• Certificate chain: Provide the complete chain (server certificate + required intermediates). Missing intermediates commonly cause client errors such as “unable to verify the first certificate.”

• Private key: The private key must match the issued certificate and must be protected (see General Requirements).

• Filenames and location: Use the installer’s expected filenames and directory structure so HAProxy configuration does not need to change.

6.2 Option A: Installer-generated (POC/testing)

For POCs and first-time installations, AgileSec can generate the external (user-facing) certificate as part of the initial certificate setup. If you followed the steps in Initial Certificate Setup, the external certificate files have already been generated under:

• <installer_directory>/certificates/<analytics_hostname>.<analytics_domain>

No further action is required for Option A.

The following files are generated:

This certificate is self-signed (signed by the installer-generated Root CA), so browsers and external clients will not trust it by default unless you import the installer CA into their trust stores.

6.3 Option B: Bring Your Own Certificates (BYOC)

For production deployments, replace the external certificate with one issued by your enterprise PKI or a public CA.

Step 1: Generate CSR for public/enterprise CA

Generate a CSR that includes the external platform FQDN (<analytics_hostname>.<analytics_domain>) as a DNS SAN. You may also set the certificate CN to the same FQDN for compatibility and readability.

AgileSec supports RSA or ECDSA certificates. Use RSA 2048 for maximum compatibility, or ECDSA P-256 if your PKI and clients support ECDSA.

Example RSA(2048)

CERT_DIR=<installer_directory>/certificates
cd $CERT_DIR$/<analytics_hostname>.<analytics_domain>
openssl genrsa -out agilesec-analytics-key.pem 2048

openssl req -new -key agilesec-analytics-key.pem \
  -out agilesec-analytics-server.csr \
  -subj "/CN=<analytics_hostname>.<analytics_domain>" \
  -addext "subjectAltName=DNS:<analytics_hostname>.<analytics_domain>"

Example (ECDSA P-256)

CERT_DIR=<installer_directory>/certificates
cd $CERT_DIR$/<analytics_hostname>.<analytics_domain>
openssl ecparam -name prime256v1 -genkey -noout \
  -out agilesec-analytics-key.pem

openssl req -new -key agilesec-analytics-key.pem \
   -out agilesec-analytics-server.csr \
  -subj "/CN=<analytics_hostname>.<analytics_domain>" \
  -addext "subjectAltName=DNS:<analytics_hostname>.<analytics_domain>"

Submit the CSR (agilesec-analytics-server.csr) to your enterprise PKI or public CA using your organization’s standard process.

Step 2: Install issued certificate + chain (AgileSec required filenames)

After the CA issues the certificate, place the returned certificate material into the external certificate location at <installer_directory/certificates/<analytics_hostname>.<analytics_domain> with the expected filenames:

• agilesec-analytics-server-cert.pem — issued server certificate

• agilesec-analytics-key.pem — private key used to generate the CSR

If your CA provides intermediate certificates (recommended), save them as intermediate-chain.pem (or use the CA-provided “full chain” file).

AgileSec expects a combined PEM for the external endpoint:

• agilesec-analytics-server-combo-cert-key.pem

Create the combined PEM in the following order (certificate → intermediates → key):

If your CA provides intermediate chain:

CERT_DIR=<installer_directory>/certificates
cd $CERT_DIR/<analytics_hostname>.<analytics_domain>
cat agilesec-analytics-server-cert.pem \
    intermediate-chain.pem \
    agilesec-analytics-key.pem \
  > agilesec-analytics-server-combo-cert-key.pem

chmod 400 agilesec-analytics-server-combo-cert-key.pem

If your CA does not require intermediate chain:

CERT_DIR=<installer_directory>/certificates
cd $CERT_DIR/<analytics_hostname>.<analytics_domain>
cat agilesec-analytics-server-cert.pem \
    agilesec-analytics-key.pem \
  > agilesec-analytics-server-combo-cert-key.pem

chmod 400 agilesec-analytics-server-combo-cert-key.pem

Note: agilesec-analytics-server-combo-cert-key.pem must be copied <installer directory>/certificates/<analytics_hostname>.<analytics_domain> on all nodes.

7 Internal Server Certificates

Internal server certificates secure intra-platform communication and protect service endpoints that are not intended to be publicly exposed. These certificates are presented by internal services when other platform components (and, in some cases, scan nodes) connect over TLS.

Internal server certificates are used in two main patterns:

• Internal TLS (server-auth only): The client verifies the service’s server certificate to establish an encrypted channel to an internal endpoint.

• Internal mTLS (mutual TLS): In addition to server certificate validation, the client presents a client certificate for authentication. This is used for service-to-service authentication and for validating sensor-to-platform connections where mTLS is enabled.

Internal certificates are typically issued by an installer-generated CA for POCs/first-time installs, or by an enterprise PKI for production deployments requiring centralized issuance and rotation.

7.1 Internal Certificate Models

AgileSec supports multiple models for internal server certificates. Choose the model that best matches your organization’s security and operational requirements. Regardless of the model, all internal clients must trust the issuing CA chain and the certificates must cover the hostnames used for internal connections.

• Wildcard certificate (default): A wildcard certificate for *.<analytics_internal_domain> is used across internal server endpoints. This is the simplest option to deploy and operate because all internal services can share the same certificate and key.

• Single certificate with SANs: A single certificate is used across all nodes, and includes all required internal hostnames as DNS SANs (for example, backend-1.<analytics_internal_domain>, backend-2.<analytics_internal_domain>, frontend-1.<analytics_internal_domain>, scan.<analytics_internal_domain>). This avoids wildcard usage while keeping certificate management centralized.

• Per-node certificates: Each node has its own internal server certificate containing only the DNS SANs required for that node. This provides stronger isolation and limits the impact of key exposure, at the cost of additional certificate lifecycle management and distribution.

7.2 Requirements

The following requirements apply to internal server certificates regardless of whether they are installer-generated or issued by your enterprise PKI (BYOC). Generation and installation steps are covered in the sections that follow.

• Internal hostnames: Certificates must be valid for the internal DNS names used by the platform.

  • Single-node: <hostname>.<analytics_internal_domain>

  • Multi-node: backend-1.<analytics_internal_domain>, backend-2.<analytics_internal_domain>, frontend-1.<analytics_internal_domain>, scan.<analytics_internal_domain>

• SANs: Include the required internal hostnames as DNS SANs. You may set the CN to a primary internal hostname for readability, but do not rely on CN alone.

• TLS protocol and ciphers (internal): Internal service-to-service communication enforces TLS 1.3 only. Ensure your certificates and clients are compatible with TLS 1.3, and restrict cipher suites to approved TLS 1.3 suites where required (for example, TLS_AES_256_GCM_SHA384, TLS_AES_128_GCM_SHA256, TLS_CHACHA20_POLY1305_SHA256).

• mTLS support: Internal endpoints may require mTLS. When clientAuth=need is enabled on a service, the server must be configured with a trusted CA chain used to validate client certificates.

• Chain and trust: Certificates must chain back to a CA trusted by all nodes and components that initiate connections to internal endpoints. Install the issuing CA chain into the system trust store, and into the bundled Java trust store where applicable.

• Key algorithm: RSA 2048 or ECDSA P-256 are supported. Use RSA 2048 for maximum compatibility unless your environment standardizes on ECDSA.

• File naming and location: Use the installer’s expected filenames and directory structure so service configuration does not need to be modified. Replace files in place when rotating or switching certificate sources.

• File permissions: Protect certificate and key files with restrictive permissions (see General Requirements).

7.3 Option A: Installer generated (default)

For POCs and first-time installations, AgileSec can generate all internal certificates as part of the initial certificate setup. If you followed the steps in Initial Certificate Setup, the internal certificate files have already been generated under:

• <installer_directory>/certificates/<analytics_internal_domain>

Default (and only) installer-generated internal server certificate model: wildcard

generate_certs.sh generates a wildcard internal server certificate for *.<analytics_internal_domain>. This wildcard certificate is used by all internal server endpoints.

The main benefit of this model is simplicity: internal services can share the same certificate and key, and internal clients only need to trust a single CA chain.

If your organization does not allow wildcard certificates, use Option B (BYOC) and deploy either a single SAN-based internal certificate or per-node internal certificates.

The following files are generated:

For multi-node deployments, certificates are generated on backend-1 and contents of <installer_directory>/certificates/<analytics_internal_domain>/ are copied to the same path on all other nodes.

7.4 Option B: Bring Your Own Certificates - BYOC

Use this option if you do not want to use the installer-generated wildcard internal certificate and instead require internal server certificates issued by your enterprise PKI.

Enterprise PKI issuance methods: 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 certificate, private key, and any intermediate chain in the required PEM filenames.

Assumption (pre-install): The steps in this doc assume you are providing certificates before installation by placing files under: <installer_directory>/certificates/<analytics_internal_domain>/

Option B1: BYOC internal wildcard certificate

Use a single wildcard internal server certificate for *.<analytics_internal_domain> across all internal endpoints.

Obtain a wildcard certificate (CSR or PKI-generated)

Choose one of the following based on your PKI process:

• CSR-based: Generate a private key and CSR that includes DNS:*.<analytics_internal_domain> as a SAN, then submit it to your PKI.

• PKI-generated (PFX/PKCS#12): Request a wildcard certificate for *.<analytics_internal_domain> and download the issued bundle (typically .pfx or .p12).

Example (CSR-based, RSA 2048):

openssl genrsa -out agilesec-internal-server-key.pem 2048

openssl req -new -key agilesec-internal-server-key.pem \
  -out agilesec-internal-server.csr \
  -subj "/CN=*.<analytics_internal_domain>" \
  -addext "subjectAltName=DNS:*.<analytics_internal_domain>"

Replacement steps

Step 1: Place the issued certificate material under: <installer_directory>/certificates/<analytics_internal_domain>/

AgileSec required filenames:

• agilesec-internal-server-cert.pem

• agilesec-internal-server-key.pem

• agilesec-internal-server-combo-cert-key.pem

If your PKI returns a PFX or *P12, extract PEM files first (example):

```bash
openssl pkcs12 -in internal-wildcard.pfx -clcerts -nokeys \
  -out agilesec-internal-server-cert.pem
openssl pkcs12 -in internal-wildcard.pfx -nocerts -nodes \
  -out agilesec-internal-server-key.pem
```

Notes:

• Extracted certificate may include chain depending on PKI.

• For unencrypted extracting private key, use -nodes only if your process allows it.

Step 2: If your PKI provides intermediates separately, save them as intermediate-chain.pem.

Step 3: Create the combined PEM expected by AgileSec (certificate → intermediates → key):

```bash
cat agilesec-internal-server-cert.pem \
  intermediate-chain.pem \
  agilesec-internal-server-key.pem \
  > agilesec-internal-server-combo-cert-key.pem

chmod 400 \
  agilesec-internal-server-cert.pem
  agilesec-internal-server-key.pem \
  agilesec-internal-server-combo-cert-key.pem
```

Note: if intermediate chain is not required then only append cert and key.

Deploy the same files to all nodes (same paths and filenames).

Option B2: BYOC per-node internal certificates

Use separate internal server certificates per node (backend-1, backend-2, frontend-1, scan). This provides stronger isolation but requires per-node certificate lifecycle management.

Obtain per-node certificates (CSR or PKI-generated)

Choose one of the following based on your PKI process:

• CSR-based: Generate one CSR per node with that node’s internal FQDN as a DNS SAN.

• PKI-generated (PFX/PKCS#12): Request one certificate per node (typically .pfx per node) and download the issued bundles.

Example (CSR-based, RSA 2048) — backend-1:

openssl genrsa -out agilesec-internal-server-key.pem 2048

openssl req -new -key agilesec-internal-server-key.pem \
  -out agilesec-internal-server.csr \
  -subj "/CN=backend-1.<analytics_internal_domain>" \
  -addext "subjectAltName=DNS:backend-1.<analytics_internal_domain>"

Repeat for:

• backend-2.<analytics_internal_domain>

• frontend-1.<analytics_internal_domain>

• scan.<analytics_internal_domain>

Replacement steps

On each node, replace the internal server cert files under: <installer_directory>/certificates/<analytics_internal_domain>/

AgileSec required filenames (per node):

• agilesec-internal-server-cert.pem

• agilesec-internal-server-key.pem

• agilesec-internal-server-combo-cert-key.pem

If your PKI returns a PFX or P12, extract PEM files first on that node (example):

openssl pkcs12 -in node-internal.pfx -clcerts -nokeys \
 -out agilesec-internal-server-cert.pem
openssl pkcs12 -in node-internal.pfx -nocerts -nodes \
 -out agilesec-internal-server-key.pem

Then create the combined PEM (certificate → intermediates → key):

cat agilesec-internal-server-cert.pem \
  intermediate-chain.pem \
  agilesec-internal-server-key.pem \
  > agilesec-internal-server-combo-cert-key.pem

chmod 400 agilesec-internal-server-key.pem \
  agilesec-internal-server-combo-cert-key.pem

Note: if intermediate chain is not required then only append cert and key.

Deploy the same files to all nodes (same paths and filenames).

8 Client Certificates (mTLS)

Client certificates are used for mutual TLS (mTLS) authentication when a component connects to an internal endpoint that requires client authentication (clientAuth=need). In mTLS, the server validates the client’s certificate against a trusted CA chain, and the client validates the server certificate as part of the normal TLS handshake. This provides strong service identity, prevents unauthorized internal clients, and protects internal APIs from impersonation.

8.1 Requirements

• TLS protocol: Internal mTLS uses TLS 1.3 by default. If required for compatibility, the platform can be configured to allow TLS 1.2 in addition to TLS 1.3. If TLS 1.2 is enabled, ensure you also allow an approved TLS 1.2 cipher suite set in accordance with your security standards.

• Trust chain: Client certificates must chain back to a CA trusted by the destination service (typically the internal Root CA chain used by the platform).

• Subject (DN): When generating certificates, use client_certificate_subject from the .env file as the base DN.

• Filenames and locations: Use the installer’s expected filenames and directory structure so service configuration does not need to change. Replace files in place when rotating or switching certificate sources.

• File permissions: Protect certificate and key files with restrictive permissions (recommended 400 for key and combo files), see General Requirements.

8.2 Option A: Installer-generated client certificates

The installer supports two modes for generating client certificates. Both modes use the .env settings below:

• client_certificate_name_prefix="shared-client": The prefix used for the certificate CN and filenames.

• use_single_client_cert=true|false: Controls whether one shared client certificate is used, or separate certificates are generated per service.

Option A1 (default): Single shared client certificate

When use_single_client_cert=true, generate_certs.sh generates a single shared client certificate that is used by all platform services for mTLS client authentication.

• Location: <installer_directory>/certificates/<analytics_internal_domain>/

• Files:

  • shared-client-cert.pem

  • shared-client-combo-cert-key.pem

  • shared-client-key.pem

  • shared-client.p12

If you followed the steps in Initial Certificate Setup, the single client certificate files have already been generated under:

• <installer_directory>/certificates/<analytics_internal_domain>

Option A2: Per-service client certificates

When use_single_client_cert=false, generate_certs.sh generates a separate client certificate per service. This provides stronger isolation and enables independent rotation of a single service credential without impacting others.

Client certificates are generated under the same internal certificates directory, using service-specific filenames derived from the configured prefix (client_certificate_name_prefix).

• Location: <installer_directory>/certificates/<analytics_internal_domain>/

• File:

  • FluentD:

    • fluentd-client-cert.pem

    • fluentd-client-key.pem

    • fluentd-client-combo-cert-key.pem

  • Ingestion Service:

    • ingestion-service-client-cert.pem

    • ingestion-service-client-key.pem

    • ingestion-service-client-combo-cert-key.pem

  • Manager:

    • analytics-manager-client-cert.pem

    • analytics-manager-client-key.pem

    • analytics-manager-client-combo-cert-key.pem

    • analytics-manager-client.p12

  • Platform Sensors

    • platform-sensor-client-cert.pem

    • platform-sensor-client-key.pem

  • Scheduler:

    • scheduler-client-cert.pem

    • scheduler-client-key.pem

    • scheduler-client-combo-cert-key.pem

    • scheduler-manager-client.p12

  • Web API:

    • api-client-cert.pem

    • api-client-key.pem

    • api-client-combo-cert-key.pem

8.3 Option B: Bring Your Own Certificates - BYOC

Using an enterprise PKI for internal mTLS client certificates is optional and is typically driven by organizational policy. Many production deployments continue to use installer-generated internal certificates (internal server and mTLS client certificates), while using a public/enterprise CA only for the external (user-facing) platform endpoint.

Choose BYOC for internal client certificates when you need one or more of the following:

• Policy or compliance requires all TLS/mTLS certificates to be issued by the enterprise PKI.

• Centralized lifecycle management is required (standard issuance, rotation, and revocation).

• You require stronger isolation (for example, per-service client certificates managed by PKI).

• You need alignment with existing certificate management tooling and operational processes.

When using BYOC, ensure you can provide the client certificate, private key, and any intermediate CA chain using the same filenames and locations expected by AgileSec, so service configuration does not need to be modified.

Assumption (pre-install): The steps below assume you are providing certificates before installation under <installer_directory>/certificates/<analytics_internal_domain>/.

Enterprise PKI issuance methods: Your PKI may use (a) CSR-based issuance (you generate key/CSR) or (b) PKI-generated keypairs (often delivered as PKCS#12/PFX). Either approach is supported as long as you provide the required PEM files in the expected filenames.

Option B1: Single shared mTLS client certificate (enterprise PKI)

Use one client certificate shared by all services (mirrors installer default behavior) but issued by your enterprise PKI.

Obtain the certificate (CSR or PKI-generated)

CSR-based (recommended) — Example (RSA 2048):

openssl genrsa -out shared-client-key.pem 2048

openssl req -new -key shared-client-key.pem -out shared-client.csr \
-subj "/CN=<client_certificate_name_prefix>.<analytics_internal_domain>"

CSR-based — Example (ECDSA P-256):

openssl ecparam -name prime256v1 -genkey -noout -out shared-client-key.pem

openssl req -new -key shared-client-key.pem -out shared-client.csr \
-subj "/CN=<client_certificate_name_prefix>.<analytics_internal_domain>"

Submit the CSR to your enterprise PKI and request a client authentication certificate (EKU: Client Authentication). Your PKI should return the issued certificate and any intermediate chain.

PKI-generated (PFX/PKCS#12):

Request a client certificate with CN <client_certificate_name_prefix>.<analytics_internal_domain> and download the .pfx, then extract PEMs:

openssl pkcs12 -in shared-client.pfx -clcerts -nokeys \
 -out shared-client-cert.pem
openssl pkcs12 -in shared-client.pfx -nocerts -nodes \
 -out shared-client-key.pem

Install (required filenames)

Place the following files under <installer_directory>/certificates/<analytics_internal_domain>/:

• shared-client-cert.pem (issued client certificate)

• shared-client-key.pem (private key)

• shared-client-combo-cert-key.pem (combined PEM used by some services. certificate → intermediates → key))

• shared-client.p12 (PKCS#12 bundle, no password)

Step 1: Create the combined PEM (certificate → intermediates → key):

cat shared-client-cert.pem \
  intermediate-chain.pem \
  shared-client-key.pem > shared-client-combo-cert-key.pem

Note: if intermediate chain is not required then only append cert and key.

Step 2: Create shared-client.p12 (no password):

openssl pkcs12 -export \
  -in shared-client-cert.pem \
  -inkey shared-client-key.pem \
  -certfile intermediate-chain.pem \
  -out shared-client.p12 \
  -name shared-client \
  -passout pass:

Step 3: Set restrictive permissions:

chmod 400 shared-client-key.pem shared-client-combo-cert-key.pem \
  shared-client.p12

Option B2: Per-service mTLS client certificates (enterprise PKI)

Use separate client certificates per service for stronger isolation and independent rotation. This mirrors installer behavior when use_single_client_cert=false, but certificates are issued by your enterprise PKI.

Assumption (pre-install): Place files under <installer_directory>/certificates/<analytics_internal_domain>/. Post-install: Use <installed_dir>/certificates/<analytics_internal_domain>/ and restart services.

Important: Use the exact filenames expected by AgileSec for per-service mode. The safest approach is to run generate_certs.sh once with use_single_client_cert=false to see the expected filenames, then replace those files in place using your enterprise-issued certificates.

Services and required files

For each service below, place the required files under: <installer_directory>/certificates/<analytics_internal_domain>/

• FluentD (service-name: fluentd-client):

  • fluentd-client-cert.pem

  • fluentd-client-key.pem

  • fluentd-client-combo-cert-key.pem

• Ingestion (service-name: ingestion-service-client):

  • ingestion-service-client-cert.pem

  • ingestion-service-client-key.pem

  • ingestion-service-client-combo-cert-key.pem

• Manager (service-name: analytics-manager-client):

  • analytics-manager-client-cert.pem

  • analytics-manager-client-key.pem

  • analytics-manager-client-combo-cert-key.pem

  • analytics-manager-client.p12 (no password)

• Platform Sensors (service-name: platform-sensor-client):

  • platform-sensor-client-cert.pem

  • platform-sensor-client-key.pem

• Scheduler: (service-name: scheduler-client):

  • scheduler-client-cert.pem

  • scheduler-client-key.pem

  • scheduler-client-combo-cert-key.pem

  • scheduler-manager-client.p12 (no password)

• Web API (service-name: api-client):

  • api-client-cert.pem

  • api-client-key.pem

  • api-client-combo-cert-key.pem

If your actual filenames differ, use the filenames produced by generate_certs.sh in per-service mode.

Step 1: Obtain certificates (CSR or PKI-generated)

For each service (Fluentd, Ingestion Service, Analytics Manager, Platform Sensors, Scheduler, Web API), obtain a client-auth certificate from your enterprise PKI (EKU: Client Authentication). Your PKI may support CSR-based issuance or PKI-generated keypairs (PFX).

Option 1 — CSR-based (RSA 2048)

openssl genrsa -out <service-name>-client-key.pem 2048

openssl req -new -key <service-name>-client-key.pem \
  -out <service-name>-client.csr \
  -subj "/CN=<service-name>.<analytics_internal_domain>"

Option 2 — CSR-based (ECDSA P-256)

openssl ecparam -name prime256v1 -genkey -noout \
  -out <service-name>-client-key.pem

openssl req -new -key <service-name>-client-key.pem \
  -out <service-name>-client.csr \
  -subj "/CN=<service>.<analytics_internal_domain>"

Option 3 — PKI-generated (PFX/PKCS#12)

If your PKI returns a .pfx bundle, extract the PEM certificate and key:

openssl pkcs12 -in <service-name>-client.pfx -clcerts -nokeys \
  -out <service-name>-client-cert.pem
openssl pkcs12 -in <service-name>-client.pfx -nocerts -nodes \
  -out <service-name>-client-key.pem

Repeat Step 1 for all services: Fluentd, Ingestion Service, Analytics Manager, Platform Sensors, Scheduler, and Web API.

Step 2: Install the per-service certificate and key using AgileSec filenames

For each service, copy the issued certificate and private key to: <installer_directory>/certificates/<analytics_internal_domain>/

Use the filenames expected by AgileSec for that service, for example:

• <service-name>-client-cert.pem

• <service-name>-client-key.pem

Repeat Step 2 for all services.

Step 3: Create the combo PEM (required for most services)

For each service that requires a combo file, create it in this order (certificate → intermediates → key):

cat <service-name>-client-cert.pem \
  intermediate-chain.pem \
  <service-name>-client-key.pem > \
  <service-name>-client-combo-cert-key.pem

Note: if intermediate chain is not required then only append cert and key.

Repeat Step 3 for all services that require a combo file (Fluentd, Ingestion Service, Analytics Manager, Scheduler, Web API).

Step 4: Create the .p12 client keystore (required for Manager, Scheduler, Ingestion)

For services that require a PKCS#12 file, generate an unencrypted .p12 (no password):

openssl pkcs12 -export \
  -in <service-name>-client-cert.pem \
  -inkey <service-name>-client-key.pem \
  -certfile intermediate-chain.pem \
  -out <service-name>-client.p12 \
  -name <service-name>-client \
  -passout pass:

Repeat Step 4 for:

• Analytics Manager

• Scheduler

• Ingestion Service

Step 5: Set permissions

Recommended permissions for all client key material:

chmod 400 *-client-key.pem *-client-combo-cert-key.pem *.p12

9 Admin Client Certificates

Admin client certificates are used for privileged, certificate-based authentication to internal infrastructure components that require elevated access. In the AgileSec Platform, these certificates are used for administrative connections to MongoDB and OpenSearch (for example, to perform secure administrative operations during installation, configuration, and troubleshooting).

Admin certificates are always separate from service-to-service mTLS client certificates and must be treated as sensitive credentials.

9.1 Requirements

• Must chain back to a CA trusted by the target component (typically the internal Root CA chain).

• Intended for client authentication (EKU: Client Authentication).

• Use the installer’s expected filenames so configuration does not need to change.

• Restrict file permissions (recommended 400 for key and combo files).

Assumption (pre-install): Place files under <installer_directory>/certificates/<analytics_internal_domain>/. Post-install: Use <installed_dir>/certificates/<analytics_internal_domain>/ and restart services.

9.2 Option A: Installer-generated (internal CA)

Admin certificates are generated by generate_certs.sh as part of certificate generation.

Option A1: Single admin certificate (use_single_client_cert=true)

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

• Location: `<installer_directory>/certificates/<analytics_internal_domain>/

• Files:

  • admin-user-cert.pem

  • admin-user-key.pem

  • admin-user-combo-cert-key.pem

• CN: admin-user.<analytics_internal_domain>

If you followed the steps in Initial Certificate Setup, the single admin user certificate files have already been generated under:

• <installer_directory>/certificates/<analytics_internal_domain>

No further action is needed.

Option A2: Separate admin certificates (use_single_client_cert=false)

Separate admin certificate assets are generated for MongoDB and OpenSearch.

• Location: <installer_directory>/certificates/<analytics_internal_domain>/

• MongoDB Admin Cert:

  • Files:

    • mongodb-admin-user-combo-cert-key.pem

  • CN: mongodb-admin-user.<analytics_internal_domain>

• OpenSearch Admin Cert:

  • Files:

    • opensearch-admin-user-cert.pem

    • opensearch-admin-user-key.pem

  • CN: opensearch-admin-user.<analytics_internal_domain>

9.3 Option B: Bring Your Own Certificates - BYOC

Use this option if your organization requires admin certificates to be issued by an enterprise PKI (centralized issuance, audit controls, rotation/revocation).

Enterprise PKI issuance methods: Your PKI may support CSR-based issuance or PKI-generated keypairs (PFX/PKCS#12). Either approach is supported as long as you provide the required PEM files using the expected filenames.

Option B1: Single admin certificate (use_single_client_cert=true)

Issue one admin client certificate from your enterprise PKI and install it using the filenames below.

• Location: `<installer_directory>/certificates/<analytics_internal_domain>/

• Files:

  • admin-user-cert.pem

  • admin-user-key.pem

  • admin-user-combo-cert-key.pem

• CN: admin-user.<analytics_internal_domain>

CSR example (RSA 2048):

openssl genrsa -out admin-user-key.pem 2048
openssl req -new -key admin-user-key.pem -out admin-user.csr \
  -subj "/CN=admin-user.<analytics_internal_domain>"

Alternative (ECDSA P-256):

openssl ecparam -name prime256v1 -genkey -noout \
  -out admin-user-key.pem
openssl req -new -key admin-user-key.pem -out admin-user.csr \
  -subj "/CN=admin-user.<analytics_internal_domain>"

Create the combo PEM (certificate → intermediates → key):

cat admin-user-cert.pem intermediate-chain.pem admin-user-key.pem \
  > admin-user-combo-cert-key.pem

chmod 400 admin-user-key.pem admin-user-combo-cert-key.pem

Option B2: Separate admin certificates (use_single_client_cert=false)

Issue separate admin certificates from your enterprise PKI and install them using the filenames below.

• Location: <installer_directory>/certificates/<analytics_internal_domain>/

• MongoDB Admin Cert:

  • Files:

    • mongodb-admin-user-combo-cert-key.pem

  • CN: mongodb-admin-user.<analytics_internal_domain>

• OpenSearch Admin Cert:

  • Files:

    • opensearch-admin-user-cert.pem

    • opensearch-admin-user-key.pem

  • CN: opensearch-admin-user.<analytics_internal_domain>

Step 1: Generate CSR

MongoDB admin CSR example (RSA 2048):

openssl genrsa -out mongodb-admin-user-key.pem 2048
openssl req -new -key mongodb-admin-user-key.pem \
  -out mongodb-admin-user.csr \
  -subj "/CN=mongodb-admin-user.<analytics_internal_domain>"

OpenSearch admin CSR example (RSA 2048):

openssl genrsa -out mongodb-admin-user-key.pem 2048
openssl req -new -key mongodb-admin-user-key.pem \
  -out mongodb-admin-user.csr \
  -subj "/CN=mongodb-admin-user.<analytics_internal_domain>"

Alternative (ECDSA P-256): replace openssl genrsa ... with:

openssl ecparam -name prime256v1 -genkey -noout -out <keyfile>.pem

Step 2: Build Combo PEM

After issuance, build the MongoDB combo PEM (certificate → intermediates → key):

cat mongodb-admin-user-cert.pem intermediate-chain.pem \
  mongodb-admin-user-key.pem > mongodb-admin-user-combo-cert-key.pem

chmod 400 opensearch-admin-user-key.pem mongodb-admin-user-key.pem \
  mongodb-admin-user-combo-cert-key.pem

If your PKI returns .pfx bundles, extract PEM cert/key first, then build the required combo file:

openssl pkcs12 -in <name>.pfx -clcerts -nokeys -out <name>-cert.pem
openssl pkcs12 -in <name>.pfx -nocerts -nodes -out <name>-key.pem

10 SAML IdP Signing Certificate

The AgileSec Platform includes a single SAML Identity Provider (IdP) signing certificate used when the platform acts as the IdP for SSO integrations (for example, OpenSearch Dashboards). This certificate is used to sign SAML assertions so the Service Provider (SP) can validate authenticity and integrity.

This certificate is not used for TLS. It is used specifically for SAML signing.

10.1 Files and location

• Location: <installer_directory>/certificates/<analytics_internal_domain>/

• Files:

  • idp-cert.pem — IdP signing public certificate (distributed to SPs for signature validation)

  • idp-enc-key.pem — IdP signing private key (encrypted)

  • saml.pass — Passphrase used to decrypt idp-enc-key.pem

Assumption (pre-install): Place files under <installer_directory>/certificates/<analytics_internal_domain>/. Post-install: Use <installed_dir>/certificates/<analytics_internal_domain>/ and restart services (and re-apply SSO configuration if required).

10.2 Subject DN:

Use the base DN from your .env (server_certificate_subject) and append a CN that clearly identifies this certificate as the SAML IdP signing certificate:

Subject DN (recommended): <server_certificate_subject>, CN=AgileSec SAML IdP Signing

Example:

OU=Server,O=Keyfactor,ST=Ohio,C=US, CN=AgileSec SAML IdP Signing

10.3 Option A: Installer-generated (default)

The SAML IdP signing certificate and key are generated automatically by generate_certs.sh and placed in the internal certificates directory as part of the initial certificate setup. If you followed the steps in Initial Certificate Setup, the Root CA files have already been generated under:

• <installer_directory>/certificates/<analytics_internal_domain>

No further action is required for Option A.

Handling guidance

• Treat idp-enc-key.pem and saml.pass as sensitive secrets. Restrict access and back them up securely.

• idp-cert.pem is safe to distribute internally to SPs that must validate SAML signatures.

10.4 Option B: Bring Your Own Certificate - BYOC

Use this option if your organization requires SAML signing keys to be generated/managed outside the installer (enterprise PKI, centralized key management, or HSM-backed keys).

AgileSec requires you to provide:

• idp-cert.pem (public certificate)

• idp-enc-key.pem (encrypted private key)

• saml.pass (passphrase used to decrypt the key)

Step 1: Generate Key + CSR (enterprise/public CA)

CSR-based — Example (RSA 2048):

openssl genrsa -out idp-key.pem 2048

openssl req -new -key idp-key.pem -out idp.csr \
-subj "/OU=Server/O=Keyfactor/ST=Ohio/C=US/CN=AgileSec SAML IdP Signing"

Alternative — Example (ECDSA P-256):

openssl ecparam -name prime256v1 -genkey -noout -out idp-key.pem

openssl req -new -key idp-key.pem -out idp.csr \
-subj "/OU=Server/O=Keyfactor/ST=Ohio/C=US/CN=AgileSec SAML IdP Signing"

Note: Replace subj with value from .env setting server_certificate_subject

Submit idp.csr to your enterprise PKI and request a certificate intended for SAML signing (digital signature usage). Save the issued certificate as:

• idp-cert.pem

If your PKI returns a .pfx, extract the certificate and key as PEM, then continue with the steps below:

openssl pkcs12 -in idp.pfx -clcerts -nokeys -out idp-cert.pem
openssl pkcs12 -in idp.pfx -nocerts -nodes -out idp-key.pem

Step 2: Create saml.pass and encrypt the key to idp-enc-key.pem

Generate a strong passphrase file:

openssl rand -hex 24 > saml.pass
chmod 400 saml.pass

Encrypt the private key in PKCS#8 format using the passphrase:

openssl pkcs8 -topk8 -inform PEM -outform PEM \
  -in idp-key.pem -out idp-enc-key.pem \
  -passout file:saml.pass

chmod 400 idp-enc-key.pem

Step 3: Install the files (AgileSec required filenames)

Copy these files to: <installer_directory>/certificates/<analytics_internal_domain>/

• idp-cert.pem

• idp-enc-key.pem

• saml.pass

If applying post-install, restart services and ensure the SP is configured with the updated idp-cert.pem.

10.5 Verification

Inspect the IdP certificate:

CERT_DIR=<installer_directory>/certificates/<analytics_internal_domain>
openssl x509 -in $CERT_DIR/idp-cert.pem \
  -noout -subject -issuer -dates -fingerprint

Validate the private key can be decrypted

CERT_DIR=<installer_directory>/certificates/<analytics_internal_domain>
openssl pkey -in $CERT_DIR/idp-enc-key.pem \
  -passin file:$CERT_DIR/saml.pass \
  -noout

11. Secrets Manager Keystore

The Security Manager (SM) service uses a dedicated keystore to generate and protect platform key material. This keystore is used for two related purposes:

1. CMK storage (primary purpose): SM stores the Customer Master Key (CMK) in the keystore as a SecretKeyEntry. This key is used to encrypt and decrypt data encryption keys (DEKs). Platform data is then encrypted and decrypted using those DEKs.

2. Key-pair entry (supporting purpose): SM also maintains an asymmetric NIST P-384 key pair in the keystore as a PrivateKeyEntry (certificate subject CN=sm-keystore). This key pair may be used by SM for cryptographic operations such as digital signatures.

Important: Because the CMK is stored in this keystore, replacing sm-service.p12 without a defined key migration/rotation process can make previously protected data unrecoverable.

11.1 Files and location

• Location (pre-install): <installer_directory>/certificates/<analytics_internal_domain>/

• Location (post-install): <installed_dir>/certificates/<analytics_internal_domain>/

• Files:

  • sm-service.p12 — SM keystore (PKCS#12)

  • sm-service-keystore.pass — Keystore password

11.2 Configuration settings (.env)

The SM service reads the keystore entry aliases from .env:

• sm_service_cmk_alias — Alias for the symmetric AES-256 CMK (SecretKeyEntry)

• sm_service_keypair_alias — Alias for the asymmetric NIST P-384 key pair (PrivateKeyEntry)

Example (installer-generated):

• sm_service_cmk_alias='561280514aa561b399df58dfadeab7e7'

• sm_service_keypair_alias='192851d9a7ead8e074dec80255727998'

These aliases must match the entries present in sm-service.p12. If you replace the keystore, ensure the aliases are preserved or update the .env accordingly.

11.3 Regenerating SM Keystore Aliases

For POCs, you can 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.

Generate new alias values

Step 1: Generate two new random identifiers (recommended 32 hex characters each):

New alias for the CMK (SecretKeyEntry):

openssl rand -hex 16

New alias for the key pair (PrivateKeyEntry):

openssl rand -hex 16

Step 2: Update your .env:

sm_service_cmk_alias='<new_hex_value_1>'
sm_service_keypair_alias='<new_hex_value_2>'

Note: Update .env before running generate_certs.sh so the keystore entries are created using the new aliases.

11.4 Handling guidance

• Treat sm-service.p12 and sm-service-keystore.pass as sensitive secrets.

• Restrict file permissions (recommended):

chmod 400 sm-service.p12 sm-service-keystore.pass

• Back up these files securely (vault/offline secure storage). Backups are strongly recommended before any upgrade, rotation, or replacement. If sm-service.p12 is lost, all encrypted data will be unrecoverable.

• Do not distribute broadly. Only the SM service and administrators performing maintenance should have access.

11.5 Option A: Installer-generated (default)

Use this option for most deployments. The installer generates the SM keystore and password file as part of certificate generation.

1. Ensure .env is present and configured: <installer_directory>/.env

2. (Recommended) Regenerate aliases in .env before generating certs and before installation:

• sm_service_cmk_alias

• sm_service_keypair_alias

3. Run certificate generation:

<installer_directory>/certificates/generate_certs.sh -t <install_type>

4. Confirm the generated files exist:

• <installer_directory>/certificates/<analytics_internal_domain>/sm-service.p12

• <installer_directory>/certificates/<analytics_internal_domain>/sm-service-keystore.pass

11.6 Option B: Bring Your Own Certificates - BYOC (organization-managed)

Use this option only if your organization requires SM keystore material to be generated and managed externally.

B1. Generate sm-service.p12 manually (same as installer behavior)

Inputs required

• .env values:

  • sm_service_cmk_alias

  • sm_service_keypair_alias

  • server_certificate_subject

  • cert_expiry_days

Output files

• sm-service.p12

• sm-service-keystore.pass

Step 1: Create a keystore password file

openssl rand -hex 24 > sm-service-keystore.pass
chmod 0400 sm-service-keystore.pass

SM_PASS="$(cat sm-service-keystore.pass)"

Step 2: Create the keystore and generate the AES-256 CMK entry

This creates the SecretKeyEntry under the alias sm_service_cmk_alias:

$JAVA_PATH/bin/keytool -genseckey \
  -alias "<sm_service_cmk_alias>" \
  -keyalg AES \
  -keysize 256 \
  -keystore sm-service.p12 \
  -storetype PKCS12 \
  -storepass "$SM_PASS" \
  -keypass "$SM_PASS"

Step 3: Generate the EC P-384 key pair entry

Convert the OpenSSL-style DN (e.g., /C=US/ST=Ohio/O=Keyfactor/OU=Server) into keytool format, then append CN=sm-keystore:

KEYTOOL_DNAME="$(echo "<server_certificate_subject>" \
| sed 's|^/||; s|/|,|g'),CN=sm-keystore"
echo "Using DN: $KEYTOOL_DNAME"

Generate the key pair under the alias sm_service_keypair_alias:

keytool -genkeypair \
  -alias "<sm_service_keypair_alias>" \
  -keyalg EC \
  -keysize 384 \
  -sigalg SHA384withECDSA \
  -keystore sm-service.p12 \
  -storetype PKCS12 \
  -storepass "$SM_PASS" \
  -keypass "$SM_PASS" \
  -dname "$KEYTOOL_DNAME" \
  -validity "<cert_expiry_days>"

Step 4: Set file permissions

chmod 0400 sm-service.p12 sm-service-keystore.pass

Step 5: Install the generated files

Copy into place using the expected filenames:

• <installer_directory>/certificates/<analytics_internal_domain>/sm-service.p12

• <installer_directory>/certificates/<analytics_internal_domain>/sm-service-keystore.pass

11.7 Verification

Inspect keystore entries

keytool -list -v -storetype PKCS12 \
  -keystore sm-service.p12 \
  -storepass "$(cat sm-service-keystore.pass)"

You should see:

• Entry type: SecretKeyEntry with alias matching sm_service_cmk_alias

• Entry type: PrivateKeyEntry with alias matching sm_service_keypair_alias

Quick alias check (optional)

keytool -list -v -storetype PKCS12 \
  -keystore sm-service.p12 \
  -storepass "$(cat sm-service-keystore.pass)" | \
  grep -E "Alias name:"

12. Renewing Certificates

This section describes how to renew certificates used by the AgileSec Platform. Renewal requirements depend on whether you are using installer-generated certificates (Option A) or custom/external certificates (BYOC).

Best practice: Plan renewals ahead of certificate expiration and schedule a maintenance window. After replacing certificates, restart affected services so the new certificates are loaded.

12.1 Installer-Generated Certificates

Installer-generated certificates follow the platform’s expected filenames and directory layout. A renewal script will be provided in a later release to rotate installer-generated certificate material in place:

• Planned script: <install_directory>/scripts/renew_certs.sh

• Run on: backend-1 (certificate authority node for multi-node deployments)

• Target directory: <install_directory>/certificates/

The renewal script will regenerate certificate material for all nodes and produce a packaged archive (for example, <analytics_internal_domain>-certs.tgz) that can be copied to other nodes, similar to the initial certificate generation workflow.

Planned behavior

• Regenerate installer-managed certificate material in <install_directory>/certificates/ using the existing naming conventions so service configuration does not need to change.

• Generate updated certificate assets for all nodes (backend-1, backend-2, frontend-1, scan nodes as applicable).

• Create an archive containing renewed certificate files (and per-node env files where applicable) for distribution to the other nodes.

Recommended renewal workflow (installer-generated)

1. Back up existing certificate material (entire <install_directory>/certificates/ directory is recommended).

2. Run the renewal script on backend-1 (once available):

cd <install_directory>
./scripts/renew_certs.sh

3. Copy the generated *.tgz archive from backend-1 to each other node and extract/replace into the same <install_directory>/certificates/ path on those nodes (or follow the script output instructions).

4. Restart services so all components load the renewed certificates.

Notes

• Renewing the Root CA is a separate operation from renewing leaf certificates and typically requires updating trust across all nodes and clients. In most environments, you renew leaf certificates while keeping the Root CA stable for a longer period.

• Renewing SM keystore material is sensitive because it contains the CMK used to protect DEKs. Treat any SM keystore change as a controlled operation (see 11. Security Manager Keystore ).

12.2 Custom/External Certificates (BYOC)

If you are using enterprise PKI and/or a public CA, renewal is performed using your organization’s standard certificate renewal process. AgileSec does not require configuration changes as long as you replace files in place and keep the expected filenames.

Renewal approach

1. Generate or request renewed certificates from your enterprise PKI / public CA.

2. Ensure the renewed certificate meets the same requirements:

3. Correct CN/SANs for the endpoint

4. Includes the full chain (intermediate + root as applicable)

5. Uses the expected file formats (PEM and required *-combo-cert-key.pem files)

6. Replace files in place using the same filenames under the expected directories in <install_directory>/certificates/.

7. Update trust stores if your CA chain changes (system trust store and bundled Java trust store if required).

8. Restart affected services and verify.

What typically gets renewed

• External (user-facing) certificate: renew via enterprise PKI/public CA and replace HAProxy endpoint certificate files.

• Internal server certificates: renew via enterprise PKI and replace the internal server certificate files for wildcard, SAN, or per-node model (depending on your chosen model).

• Client certificates (mTLS): renew shared or per-service certificates and regenerate any required .p12 bundles.

• Admin client certificates: renew MongoDB/OpenSearch admin certs as required.

• SAML IdP signing certificate: renew and update the SP configuration if it consumes the IdP signing public certificate.