Skip to main content

Configure LDAP SSL (LDAPS)

Pro

Introduction​

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

There are two common certificate setups:

Public Certificate Authority (CA)​

If your LDAP server uses an SSL 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 chained certificate (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 LDAPS servers.

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

Configure Passbolt to Trust a Private LDAPS Certificate​

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 Chained Certificate​

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

Quick Setup:​

# 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 bundle
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 LDAPS in a typical environment.
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.