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.

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 open-source utility to retrieve a complete LDAPS certificate chain:
🔗 passbolt/ldaps_cert_util

Follow the README to bundle and save the .crt file.

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/cert.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/cert.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/cert.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.