Mutual TLS (mTLS)

Set up mutual TLS for Bindplane collector receivers with two-way authentication.

What is Mutual TLS?

Standard TLS vs Mutual TLS

Standard TLS (One-Way Authentication):

• Client verifies server's certificate

• Server does not verify client's identity

• Client can be anonymous

• Common for public web services

Mutual TLS (Two-Way Authentication):

• Client verifies server's certificate

• Server verifies client's certificate

• Both parties prove their identity

• Used in high-security environments

Benefits of Mutual TLS

• Strong Authentication: Cryptographic proof of client identity

• Access Control: Only clients with valid certificates can connect

• Zero Trust: Doesn't rely on network-level security (IP allowlists, VPNs)

• Non-Repudiation: Client identity is cryptographically verified

When to Use Mutual TLS

Consider using mTLS when:

• You need to restrict which clients can send data to the collector

• Compliance requires two-way authentication

• You're in a zero-trust security environment

• You want to authenticate clients by certificate rather than IP address

• You need cryptographic proof of client identity for audit purposes

mTLS vs IP Allowlisting

While IP allowlisting can restrict access by network location, mTLS provides stronger authentication that travels with the client, regardless of network location. This is especially valuable in cloud and containerized environments where IP addresses are dynamic.

mTLS Configuration Options

Bindplane collectors provide two parameters for client certificate verification with different behaviors:

Option 1: ca_file (Opportunistic Client Verification)

receivers:
  tcplog:
    listen_address: "0.0.0.0:10514"
    tls:
      cert_file: /path/to/server-fullchain.crt
      key_file: /path/to/server.key
      ca_file: /path/to/client-ca.crt  # Verifies clients IF they present a cert
      min_version: "1.2"

Behavior:

• Client certificates are optional

• If a client presents a certificate, it will be verified against the CA

• Clients without certificates can still connect

• Useful for mixed environments (some authenticated, some not)

Technical Details

This sets the RootCAs trust pool but does not enforce client certificate requirements. See the OTel configtls documentation for details on the underlying tls.Config mapping.

Option 2: client_ca_file (Required Client Verification)

receivers:
  tcplog:
    listen_address: "0.0.0.0:10514"
    tls:
      cert_file: /path/to/server-fullchain.crt
      key_file: /path/to/server.key
      client_ca_file: /path/to/client-ca.crt  # Requires and verifies client certs
      client_ca_file_reload: true
      min_version: "1.2"

Behavior:

• Client certificates are required

• Connections without valid client certificates are rejected

• Sets Go's ClientAuth to RequireAndVerifyClientCert

• Supports automatic reloading with client_ca_file_reload

• This is the recommended approach for enforcing mTLS

Recommended for mTLS

Use client_ca_file when you want to enforce mutual TLS. This ensures that all clients must present valid certificates.

Comparison Table

Feature	ca_file	client_ca_file
Client cert required	No (optional)	Yes (enforced)
Clients without certs	Allowed	Rejected
Auto-reload support	No	Yes (with client_ca_file_reload)
Use case	Mixed environments	Strict mTLS
ClientAuth mode	VerifyClientCertIfGiven	RequireAndVerifyClientCert

Setting Up mTLS Certificates

Server Side (Collector)

You'll need:

1. Server certificate and key (same as basic TLS)

   • cert_file: Server certificate (can include full chain)

   • key_file: Server private key (must be unencrypted)

2. Client CA certificate(s) to verify client certificates

   • client_ca_file: CA certificate(s) that signed the client certificates

   • Can contain multiple CA certificates (concatenated PEM)

Client Side

Each client needs:

1. Client certificate signed by the CA trusted by the server

2. Client private key (must be unencrypted if using OpenTelemetry clients)

3. Server CA certificate(s) to verify the collector's certificate

Certificate Authority Trust

The CA used to sign client certificates does NOT need to be the same CA that signed the server certificate. You can use different CAs for server and client certificates, as long as each side trusts the appropriate CA.

PKI Infrastructure Considerations

For production mTLS deployments:

• Use your organization's PKI infrastructure to issue certificates

• Implement certificate lifecycle management (issuance, renewal, revocation)

• Consider using different intermediate CAs for server and client certificates

• Plan for certificate rotation and revocation

For testing, see Generating Test Certificates.

Complete mTLS Configuration Examples

TCP Receiver with mTLS

receivers:
  tcplog:
    listen_address: "0.0.0.0:10514"
    tls:
      # Server certificate (what collector presents to clients)
      cert_file: /etc/collector/certs/server-fullchain.crt
      key_file: /etc/collector/certs/server.key

      # Client verification (enforces mTLS)
      client_ca_file: /etc/collector/certs/client-ca.crt
      client_ca_file_reload: true  # Auto-reload when CA file changes

      # Security settings
      min_version: "1.2"

Syslog Receiver with mTLS

receivers:
  syslog:
    protocol: rfc5424
    tcp:
      listen_address: "0.0.0.0:6514"
      tls:
        # Server certificate
        cert_file: /etc/collector/certs/server-fullchain.crt
        key_file: /etc/collector/certs/server.key

        # Client verification
        client_ca_file: /etc/collector/certs/client-ca.crt
        client_ca_file_reload: true

        # Security settings
        min_version: "1.2"

Production mTLS with Security Hardening

receivers:
  tcplog:
    listen_address: "0.0.0.0:10514"
    tls:
      # Server certificate
      cert_file: /etc/collector/certs/server-fullchain.crt
      key_file: /etc/collector/certs/server.key

      # Client verification
      client_ca_file: /etc/collector/certs/client-ca.crt
      client_ca_file_reload: true

      # Security hardening
      min_version: "1.2"
      cipher_suites:
        - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
        - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
        - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
        - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

      # Certificate rotation
      reload_interval: 24h

Configuring mTLS in the Bindplane UI

Important: There is no separate "Enable mTLS" checkbox in the UI for most receivers. mTLS is enabled by providing a CA certificate file.

Step-by-Step UI Configuration

1. Navigate to your source configuration (e.g., TCP or Syslog source)

2. Expand the Advanced section

3. Check "Enable TLS"

4. Configure server certificate:

   • TLS Certificate Path: /path/to/server-fullchain.crt

   • TLS Private Key Path: /path/to/server.key

5. Configure client verification (this enables mTLS):

   • Client CA File: /path/to/client-ca.crt

6. Optional: Set TLS Min Version to "1.2" or higher

UI Field Mapping

Bindplane UI Field	YAML Parameter	Purpose
Enable TLS	tls: block	Enables TLS configuration
TLS Certificate Path	cert_file	Server certificate
TLS Private Key Path	key_file	Server private key
CA File	ca_file	Optional client verification
Client CA File	client_ca_file	Enforced mTLS
TLS Min Version	min_version	Minimum TLS version

Testing mTLS Connections

Test with Valid Client Certificate

Linux/macOS

openssl s_client -connect collector.example.com:10514 \
  -cert client.crt \
  -key client.key \
  -CAfile server-ca.crt

Windows PowerShell

Expected result:

• Connection succeeds

• Handshake completes

• Verify return code: 0 (ok) or appropriate verification result

Test Rejection of Unauthorized Clients

When using client_ca_file, test that connections without client certificates are rejected:

Linux/macOS

# This should fail with "certificate required" error
openssl s_client -connect collector.example.com:10514

Windows PowerShell

Expected result:

• Connection rejected

• Error message: "certificate required" or "handshake failure"

Verify Client Certificate Details

Linux/macOS

# View client certificate information
openssl x509 -in client.crt -text -noout

# Verify client certificate is signed by the CA
openssl verify -CAfile client-ca.crt client.crt
# Should output: client.crt: OK

Windows PowerShell

For more testing commands, see Testing and Verification.

mTLS Troubleshooting

Issue: Client Certificate Required Errors

Symptoms:

• Clients receive "certificate required" or "handshake failure" errors

• Connections are rejected during TLS handshake

Cause: Client is not presenting a valid certificate when client_ca_file is configured.

Solution:

1. Verify the client is presenting a certificate:

2. Ensure the client certificate is signed by the CA specified in client_ca_file:

3. Check that the client certificate hasn't expired:

Issue: Client Certificate Verification Fails

Symptoms:

• Client presents a certificate but connection is still rejected

• Error: "bad certificate" or "unknown ca"

Cause: Client CA file doesn't match the CA that signed the client certificate.

Solution:

1. Check that client_ca_file contains the CA that signed the client certificate

2. If using intermediate CAs, ensure the full chain is included

3. Verify the certificate chain:

Issue: Connections Accepted Without Client Certificates

Symptoms:

• Clients without certificates can still connect

• mTLS is not being enforced

Cause: Using ca_file instead of client_ca_file.

Solution:

1. Verify you're using client_ca_file (not just ca_file)

2. ca_file alone does not enforce mTLS - it only provides optional verification

3. client_ca_file sets ClientAuth to RequireAndVerifyClientCert

Correct configuration:

tls:
  cert_file: /path/to/server.crt
  key_file: /path/to/server.key
  client_ca_file: /path/to/client-ca.crt  # Use this, not ca_file

Issue: Client CA Changes Not Taking Effect

Cause: Not using client_ca_file_reload or collector needs restart.

Solution:

Enable automatic CA file reloading:

tls:
  client_ca_file: /path/to/client-ca.crt
  client_ca_file_reload: true  # Auto-reload on file change

Or restart the collector after updating the CA file.