Skip to main content

Configure LDAP with TLS (SSL)

Pro

Introduction​

To use LDAP with TLS (SSL), your LDAP server must present a valid TLS certificate to the client — in this case, the Passbolt server. The certificate must also be trusted by Passbolt.

Connection Types​

LDAP with STARTTLS (explicit TLS)​

  • Port: 389 (typically)
  • Protocol: Upgrades to TLS after initial connection
  • Use case: Firewall-friendly, allows same port for encrypted and unencrypted connections

LDAPS (implicit TLS)​

  • Port: 636 (typically)
  • Protocol: TLS from connection start
  • Use case: Direct encrypted connection, more secure initial handshake

Port Configuration​

  • Port 389: LDAP with STARTTLS (explicit TLS upgrade)
  • Port 636: LDAPS (implicit TLS from start)
  • Custom ports: Both protocols support custom port configuration

Certificate Requirements​

Both STARTTLS and LDAPS require valid TLS certificates. There are two common certificate setups:

Public Certificate Authority (CA)​

If your LDAP server uses a TLS certificate from a public CA (e.g., Let's Encrypt), the certificate is usually trusted by Passbolt automatically.

✅ No extra configuration is typically required.

Private CA or Self-Signed Certificate​

In many on-premises environments, LDAP runs on a private network with self-signed or privately issued certificates.

If your LDAP server does not present a certificate chain (i.e., missing CA), you must manually upload the CA certificate to the Passbolt server.

💡 Passbolt provides an official certificate bundler tool to simplify retrieving and formatting certificates from LDAP servers with TLS.

LDAP with TLS - certificate error message
fig. LDAP with TLS - certificate error message

Configure STARTTLS​

LDAP with STARTTLS Configuration​

To configure LDAP with STARTTLS, use the standard LDAP port (389) and ensure your LDAP server supports STARTTLS:

# Test STARTTLS connection
ldapsearch -x -D "username" -W -H ldap://your_ldap_server.com:389 -b "dc=domain,dc=com" -Z

The -Z flag enables STARTTLS. If successful, the connection will upgrade to TLS after the initial handshake.

STARTTLS Configuration Details​

  • Port: 389 (typically) or custom ports
  • Protocol: Upgrades to TLS after initial connection
  • Server requirement: LDAP server must support STARTTLS extension

Configure LDAPS (Implicit TLS)​

LDAPS Configuration Steps​

Step 1: Ping the Server​

First, confirm basic connectivity:

ping your_ldap_server.com
  • If ping fails, check or add the IP in /etc/hosts
  • If ping works, proceed to test LDAPS with ldapsearch

Step 2: Test LDAPS with ldapsearch​

warning

Run the command as the web server user:
www-data (Debian/Ubuntu), wwwrun (OpenSUSE), or nginx (RHEL-based).

sudo su -s /bin/bash -c 'ldapsearch -x -D "username" -W -H ldaps://your_ldap_server.com -b "dc=domain,dc=com" -d 9' www-data

Replace:

  • username
  • your_ldap_server.com
  • domain, com

Example of a certificate trust failure:​

ldap_sasl_bind(SIMPLE): Can't contact LDAP server (-1)

If you see this error, it's likely a trust issue with the LDAPS certificate.

Step 3: Download a Certificate Chain​

Use our official utility to retrieve and bundle LDAPS certificates:
🔗 passbolt/passbolt-ldap-certificate-bundler

Quick Setup:​

Ensure you have any version of Python 3 installed in your environment. The activate step is to avoid polluting your python environment with unecessary pacakges. Python virtual environment (venv) folders keep dependencies separate from the system Python and other projects, so you don’t get version conflicts, and can delete the venv folder when you're finished with it.

# Clone the repository
git clone https://github.com/passbolt/passbolt-ldap-certificate-bundler.git
cd passbolt-ldap-certificate-bundler

# Set up the environment
chmod +x setup_python_env.sh
./setup_python_env.sh

# Activate the virtual environment
source venv/bin/activate

# Run the tool to get the certificate chain
python3 ldaps_cert_chain_retriever.py --server your.ldaps.server > /etc/ssl/certs/ldaps_bundle.crt

# Set proper permissions
sudo chown root:root /etc/ssl/certs/ldaps_bundle.crt
sudo chmod 644 /etc/ssl/certs/ldaps_bundle.crt

Docker Option:​

If you prefer using Docker:

# Using the provided Makefile
make build
make save SERVER=your.ldaps.server

# Manual Docker commands
docker build -t ldaps-cert-tool .
docker run --rm -v $(pwd):/out ldaps-cert-tool --server your.ldaps.server --output /out/ldaps_bundle.crt

The utility automatically handles:

  • Certificate chain retrieval
  • Self-signed certificates
  • Chain validation
  • Proper formatting for Passbolt

Step 4: Configure Certificate Trust​

Option 1: Via passbolt.php​

// config/passbolt.php
'plugins' => [
  'directorySync' => [
    'security' => [
      'sslCustomOptions' => [
        'enabled' => true,
        'verifyPeer' => true,
        'cadir' => '/etc/ssl/certs',
        'cafile' => '/etc/ssl/certs/ldaps_bundle.crt',
      ],
    ],
  ],
]

Option 2: Via Environment Variables​

export PASSBOLT_PLUGINS_DIRECTORY_SYNC_SECURITY_SSL_CUSTOM_OPTIONS_ENABLED=true
export PASSBOLT_PLUGINS_DIRECTORY_SYNC_SECURITY_SSL_CUSTOM_OPTIONS_VERIFY_PEER=true
export PASSBOLT_PLUGINS_DIRECTORY_SYNC_SECURITY_SSL_CUSTOM_OPTIONS_CADIR="/etc/ssl/certs"
export PASSBOLT_PLUGINS_DIRECTORY_SYNC_SECURITY_SSL_CUSTOM_OPTIONS_CAFILE="/etc/ssl/certs/ldaps_bundle.crt"
info

Use either the Passbolt config OR ldap.conf (below), not both.

(Deprecated) Option: Use ldap.conf​

On Debian:

nano /etc/ldap/ldap.conf

Add or update:

TLS_CACERT /etc/ssl/certs/ldaps_bundle.crt

Optional: Disable Certificate Verification (Test Only)​

warning

This is insecure and should only be used temporarily for testing. It exposes you to MITM attacks.

Option 1: Via passbolt.php​

// config/passbolt.php
'plugins' => [
  'directorySync' => [
    'security' => [
      'sslCustomOptions' => [
        'enabled' => true,
        'verifyPeer' => false,
      ],
    ],
  ],
]

Option 2: Via Environment Variables​

export PASSBOLT_PLUGINS_DIRECTORY_SYNC_SECURITY_SSL_CUSTOM_OPTIONS_ENABLED=true
export PASSBOLT_PLUGINS_DIRECTORY_SYNC_SECURITY_SSL_CUSTOM_OPTIONS_VERIFY_PEER=false

Option 3: Via ldap.conf (deprecated)​

nano /etc/ldap/ldap.conf

Add:

TLS_REQCERT never

Final Step: Re-Test with ldapsearch​

Re-run the ldapsearch command from Step 2.
If the certificate issue is resolved, the connection should succeed. You can now return to Passbolt and test the sync.

Looking for More Advanced Scenarios?​

This page covers the essentials for setting up and troubleshooting both STARTTLS and LDAPS in a typical environment.

Summary​

LDAP with STARTTLS​

  • Use when: You need firewall-friendly configuration or want to use standard LDAP ports
  • Port: 389 (typically) or custom ports
  • Security: Upgrades to TLS after initial connection
  • Configuration: Use ldap:// URLs with STARTTLS enabled

LDAPS (Implicit TLS)​

  • Use when: You want maximum security from connection start

  • Port: 636 (typically) or custom ports

  • Security: TLS from connection start

  • Configuration: Use ldaps:// URLs with proper certificate trust
    However, if you're dealing with:

  • edge cases like multi-domain forests,

  • sync behavior involving deleted users or group permissions,

  • ignored entries, pagination issues, or memory constraints during syncs,

then you should refer to the dedicated page on advanced topics:

👉 Advanced Directory Options

That page includes deeper coverage of sync error messages, directory-specific quirks, and diagnostics for large-scale or complex LDAP environments. We maintain that page as the single source of truth for advanced directory provisioning to avoid duplicating technical logic across guides.