Skip to main content

mTLS for KGM

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.

mTLS in KGM​

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.

Prerequisites​

Before continuing, complete the certificate preparation steps described in Mutual TLS — Certificate Setup:

  1. Create a client certificate with the required X.509 extensions
  2. Package it as a PKCS#12 file (client.p12) with a secure export password
  3. Store it in your secret manager under the key client.p12

Note the secret name — you will reference it in remoteSecretName in the next step.

Enable the Client Certificate in Helm​

Follow the Enable the Client Certificate steps in the shared guide using kgm as the Helm key. The ExternalSecret will create witboost-kgm-cert-secret and mount it at /opt/docker/etc/tls/client.p12.

(Optional) Enable a Custom CA​

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

Configure the CA certificate source by following the Custom CA Configuration guide. Use kgm as the Helm key — the chart creates a Kubernetes Secret named kgm-ca-certificate when using Options B or C.

kgm:
  customCA:
    enabled: true
    # secretName, caCrtBase64, or caCrtFilePath — see the Custom CA Configuration guide

When customCA.enabled: true, an init container runs before KGM starts and imports the CA into the JVM truststore using keytool.

note

The custom CA is applied to the main KGM container only. The VKG sidecar that runs alongside KGM does not inherit the modified truststore. If VKG makes outbound HTTPS calls to adapters that use a private CA, those connections will use the default JVM truststore and may fail.

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. For it to be available in the witboost-secrets Kubernetes secret, add the key to one of the remote secrets referenced in globals.externalSecrets.refs (the same mechanism used for other Witboost secrets — refer to the Witboost Installation guide for details).

Then 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