How to enable mTLS between KGM and Source Adapters

Overview

This guide explains how to enable mutual TLS (mTLS) between the Knowledge Graph Manager (KGM) and HTTPS Source Adapters.

mTLS does not apply to adapters served over plain HTTP, because HTTP cannot support TLS handshakes or certificate-based authentication.

warning

Advanced Topic

This guide is intended for platform engineers or administrators configuring secure integrations. It requires knowledge of certificates, secret managers, and Helm deployments.

What mTLS is and when KGM uses it

Mutual TLS (mTLS) is a secure communication mechanism where:

• The Source Adapter verifies the identity of KGM using a client certificate
• KGM verifies the identity of the Source Adapter using a trusted Certificate Authority (CA)

KGM uses mTLS when:

• Downloading graph data from adapters in ingestion mode
• Forwarding SPARQL or search requests to adapters in passthrough mode

mTLS is enabled per Adapter.

You configure certificates once for the entire KGM instance and then selectively enable mTLS only for specific HTTPS adapters.

Components required for mTLS

To successfully establish mTLS, three elements must be provided:

1. A Client Certificate (required) — used by KGM to authenticate itself to HTTPS adapters
2. A Custom CA Certificate (optional) — needed only if adapters use a private or internal CA
3. An Adapter-level toggle — each adapter can individually enable or disable mTLS from KGM configuration

Create a Client Certificate

KGM requires a client certificate that includes the following X.509 extensions:

Extension	Required Value	Meaning
Key Usage	Digital Signature	The key can be used to sign data
Extended Key Usage	TLS Web Client Authentication	The certificate can be used by a client connecting to a server in a TLS session. This prevents misuse, e.g., using a server certificate as a client certificate
Basic Constraints	CA:FALSE	The certificate is an end-entity certificate, not allowed to issue other certificates. Ensures it can't act as or impersonate a CA

Verify your certificate

Run:

openssl x509 -in client.crt -text

Look for the X509v3 extensions section.

Package as PKCS#12

KGM expects a .p12 file containing certificate + private key:

openssl pkcs12 -export \
  -in client.crt \
  -inkey client.key \
  -out client.p12 \
  -name "kgm-client"

note

When you run this command, OpenSSL will prompt you to set an export password.

This password protects the .p12 file itself, and you will need to provide the same password later in the KGM configuration.

Store the certificate in your Secret Manager

Upload the client certificate (as binary content) in a secret of your organization's secret manager, under the client.p12 key.

tip

Refer to the Witboost Installation guide for additional details on secrets and secret manager.

Enable the Client Certificate in Helm

In the values.yaml provided to the Witboost Helm Chart add:

kgm:
  useClientCertificate:
    enabled: true
    # name of the secret in the secret manager where the certificate is stored
    remoteSecretName: '<secret name>' # CHANGE ME

(Optional) Enable a Custom CA

Enable this only if adapters use an internal or private CA:

kgm:
  customCA:
    enabled: true

The chart supports three ways of supplying the CA:

Option A — Use an existing Kubernetes secret

customCA:
  enabled: true
  # Pre-configured secret with CA certificate inside.
  # This secret MUST contain the following key: cacert.crt, with the base64-encoded certificate
  secretName: '<secret-name>' # CHANGE ME

Option B — Provide base64-encoded certificate

customCA:
  enabled: true
  caCrtBase64: '<base64-of-cacert.crt>' # CHANGE ME

Option C — Provide a certificate file during Helm rendering

customCA:
  enabled: true
  caCrtFilePath: 'ca/cacert.crt' # CHANGE ME

note

If using caCrtBase64 or caCrtFilePath, the chart automatically creates a Kubernetes secret.

Provide the PKCS#12 password

KGM needs the password you assigned when creating the client.p12 file so it can decrypt and load the certificate at startup.

Store this password in your secret manager and pass it to KGM through environment variables:

kgm:
  extraEnvVars:
    - name: KGM_MTLS_CLIENT_CERTIFICATE_PASSWORD
      valueFrom:
        secretKeyRef:
          name: witboost-secrets
          key: KGM_MTLS_CLIENT_CERTIFICATE_PASSWORD

(Optional) Bypass CA Filtering

In some mutual TLS deployments, the server (the Source Adapter) may send a restricted list of acceptable certificate authorities through the certificate_authorities TLS extension.

If the KGM client certificate is issued by a different (for example, internal or private) CA, the handshake may fail before the certificate is even presented.

To allow KGM to present its client certificate regardless of the server-provided acceptable issuers list, you can enable:

kgm:
  configOverride:
    kgm:
      security:
        mtls:
          client:
            bypassCAFiltering: true

When bypassCAFiltering is set to true, KGM ignores the server's acceptable CA list and always sends its configured client certificate.

Enable mTLS for HTTPS Source Adapters

Finally, enable mTLS per adapter.

Example:

kgm:
  configOverride:
    kgm:
      sources:
        - id: glossary
          baseUrl: 'https://example.com/adapter'
          mtls:
            enabled: true

        - id: taxonomy
          baseUrl: 'http://insecure-adapter.local' # HTTP → mTLS not supported
          mtls:
            enabled: false

warning

• mtls.enabled: true only works when baseUrl starts with https://
• KGM will not attempt mTLS on HTTP endpoints

Validation Checklist

Certificates

• Client certificate has correct Key Usage and Extended Key Usage
• client.p12 generated
• CA certificate prepared (if needed)

Secrets

• client.p12 uploaded to secret manager

Helm Values

• useClientCertificate.enabled = true
• remoteSecretName correct
• Custom CA enabled where required

KGM Configuration

• Certificate path and password set

Per Adapter

• baseUrl uses HTTPS
• mtls.enabled = true applied only to HTTPS adapters