Skip to content

How to setup LDAP Authentication

Jump to bottom Edit New page
Alfred Syatsukwa edited this page Sep 24, 2025 · 2 revisions

How to config LDAP auth

Introduction

Cypht Webmail supports various authentication methods, including LDAP (Lightweight Directory Access Protocol), which allows integration with directory services like Active Directory, OpenLDAP, and other LDAP-compliant servers.

Integrating Lightweight Directory Access Protocol (LDAP) authentication is a critical feature for deploying Cypht in any organizational environment, especially within businesses, educational institutions, or any setting that requires centralized user management. Its importance extends far beyond a simple login method, offering strategic advantages in security, administration, and scalability.

This documentation covers two methods for setting up Cypht with LDAP authentication:

  1. Manual installation (using code or tarball)
  2. Docker-based installation

Prerequisites

  • An LDAP server (Active Directory, OpenLDAP, etc.)
  • LDAP server connection details (server, port, bind DN, etc.)

Manual Installation (Code/Tarball)

This section details the process of configuring LDAP authentication for a manual installation of Cypht. It is assumed that you have already successfully installed Cypht on your web server by following the official Cypht Installation Guide. This includes steps such as downloading the source code, setting appropriate file permissions, and configuring your web server (Apache, Nginx, etc.) to serve the application.

The installation guide provides the essential foundation. We will now focus exclusively on the LDAP-specific configuration steps that must be performed on top of that working base installation. This involves modifying configuration files to point to your LDAP server and tailoring the authentication settings to match your directory service's schema.

Prerequisites

Before you proceed, you must verify that the ldap extension is active in your PHP CLI and web server environments. Check via Command Line:

php -m | grep ldap

If the extension is not found, you need to install it.

Config Steps

You need to make this changes in your .env file:

AUTH_TYPE=LDAP

#app.php
LDAP_AUTH_PORT=389
LDAP_AUTH_SERVER=localhost
LDAP_AUTH_TLS=
LDAP_AUTH_BASE_DN="example,dc=com"
LDAP_UID_ATTR="cn"

AUTH_TYPE is the master switch. It tells the application to use the LDAP module for authenticating users instead of other methods (like database, OAuth, etc.). Must be set to LDAP (all caps) to activate this configuration.

LDAP_AUTH_SERVER Specifies the hostname or IP address of your LDAP server. Replace localhost with the actual server address. Examples: ldap.example.com, yourcompany.net, 192.168.1.50.

LDAP_AUTH_PORT defines the network port on which the LDAP server is listening. The standard port for enencypted and StartTLS is 389. The standard port for LDAP over SSL/TLS (LDAPS) is 636. OpenLDAP and other servers often use these standard ports.

LDAP_AUTH_TLS controls whether to use encrypted or unencrypted connection. This is a major security setting.

  • Leave empty (LDAP_AUTH_TLS=) or set to false: For unencrypted connections (insecure, recommended only for testing). This will automatically use ldap:// in the query.
  • Set to true: To enable LDAP over SSL/TLS. You need to use this with LDAP_AUTH_PORT=636 if your server is configured to use the standards ports or change with the used custom port. This setup will automatically use ldaps:// in the query

LDAP_AUTH_BASE_DN: This is your LDAP directory where the application will search for user account. Note: Cypht doesn't support a recursive search in your LDAP directory tree. This is a Distinguished Name (DN) that defines the scope of your search. You must change this to match your organization's structure.

  • Examples:
    • "dc=yourcompany,dc=com" (Search at the root of the domain)
    • "ou=Users,dc=yourcompany,dc=com" (Search in the "Users" organizational unit)
    • "ou=IT,ou=Departments,dc=yourcompany,dc=com" (Seach in the OU "IT" wich is a child OU of "Departments". Remember, the root on the right and the child on the left. If you have more than two levels, that's the rule).

LDAP_UID_ATTR: This is arguably the most important parameter. It defines which LDAP attribute matches the "username" that the user types into the login form. What to set depends entirely on your LDAP server's schema.

  • "cn" (Common Name): Often used for names like "John Doe".
  • "uid" (User ID): Common on OpenLDAP, Unix-based systems.
  • "sAMAccountName" (Security Account Manager Account Name): The most common setting for Microsoft Active Directory. This is the pre-Windows 2000 logon name (e.g., jdoe).
  • "userPrincipalName" (UPN): Often an email address format (e.g., [email protected]).

You must confirm this with your LDAP/Active Directory administrator. Using the wrong attribute will cause all logins to fail.

After this setup, access your Cypht installation through a web browser and attempt to log in with LDAP credentials.

Important note about LDAPS (LDAP over SSL/TLS)

Establishing an LDAP over SSL/TLS connection requires the web server hosting Cypht to trust the LDAP server's certificate. If this trust is not configured, the secure connection will be rejected, causing authentication to fail. While users see only a generic "Invalid username or password" message, the root cause is frequently this server-level certificate trust issue, not the user's credentials. To make sure the error is not from Cypht, you can try this CLI command:

ldapwhoami -x -H ldaps://<ip-address> -D "uid=user,dc=example,dc=com" -W

After this command you will be prompted the user password. On success you will get an output like this:

dn:uid=user,dc=example,dc=com

and on failure you will have this error:

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

How to solve this

There are two common scenarios:

  • If your LDAP server uses a SSL certificate signed by a public CA (like Let's Encrypt, DigiCert, etc.), the client will likely already trust it. Most operating systems come with a pre-installed bundle of trusted public CAs. In this case, no extra configuration should be needed. But in case you have this issue persistent, check the content of this file (/etc/ldap/ldap.conf) to make sure you have this line:
TLS_CACERT      /etc/ssl/certs/ca-certificates.crt
  • Using a Self-Signed Certificate (Common in Internal Networks): This is very common for internal corporate or lab LDAP servers. The certificate is often signed by an internal company CA or is self-signed. The client does not inherently trust this certificate, so you must explicitly add it to the client's trust store (the process depends on your OS). For test purpose, you can tell your client to ignore this verification by replacing the line 
    TLS_CACERT      /etc/ssl/certs/ca-certificates.crt
    by this 
    TLS_REQCERT    allow
    in your file config /etc/ldap/ldap.conf.

Docker Installation

This section details the process of configuring LDAP authentication for a Docker-based installation of Cypht. It is assumed that you have already successfully deployed a Cypht container using the official image from Docker Hub or another repository. This includes having Docker and Docker Compose installed on your host system, and understanding how to manage containers and volumes. The installation guide provides the essential foundation for running the application. We will now focus exclusively on the LDAP-specific configuration steps that must be performed by customizing the container's environment variables and ensuring secure network connectivity to your LDAP server.

Following the same core principles as the manual installation, we will be configuring the same essential LDAP parameters (such as server host, port, and base DN). However, in the Docker methodology, these settings will not be defined in a static .env file. Instead, they will be passed directly to the Cypht container as environment variables within the docker-compose.yaml file, leveraging the container's innate ability to dynamically generate its configuration upon startup.

Consider using this docker-compose.yaml example file content :

# this is a demo of using the production cypht image

services:
  db:
    image: mariadb:10
    ports:
      - "3306:3306"
    volumes:
      - ./data/mysql:/var/lib/mysql
    environment:
      - MYSQL_ROOT_PASSWORD=root_password
      - MYSQL_DATABASE=cypht
      - MYSQL_USER=cypht
      - MYSQL_PASSWORD=cypht_password
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-ucypht", "-pcypht_password"]
      interval: 10s
      timeout: 5s
      retries: 5

  cypht:
    image: cypht/cypht:2.4.2
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "80:80"
    environment:
      - DB_CONNECTION_TYPE=host
      - DB_DRIVER=mysql
      - DB_HOST=db
      - DB_NAME=cypht
      - AUTH_TYPE=LDAP
      - DB_USER=cypht
      - DB_PASS=cypht_password
      - SESSION_TYPE=LDAP
      - USER_CONFIG_TYPE=DB
      - LDAP_AUTH_PORT=389
      - LDAP_AUTH_SERVER=ldap.example.uk
      - LDAP_AUTH_TLS=
      - LDAP_AUTH_BASE_DN=ou=Departments,dc=example,dc=com
      - LDAP_AUTH_UID_ATTR=uid
    volumes:
      - ./data/log/nginx:/var/log/nginx
      - ./data/log/php:/var/log/php
      - ./data/log/supervisord:/var/log/supervisord
      - ./data/fonts:/usr/local/share/cypht/site/fonts

Important note about Docker ldap setup

Don't add quotes on the different values. This will not work:

      - LDAP_AUTH_SERVER="ldap.example.com"
      - LDAP_AUTH_TLS=true
      - LDAP_AUTH_BASE_DN="ou=Departments,dc=example,dc=com"
      - LDAP_UID_ATTR="uid"

Keep everything without any quotes like the example given above.

If you are using a self-signed certificate, the considerations given for the manual installation apply here also. You will need to fix this manually in your Cypht container (don't do it on the host computer).

Important Note on Docker Image Compatibility: As of the current cypht:2.4.2 release, the official Docker image was built without the PHP LDAP extension, which is a mandatory dependency for LDAP authentication. Consequently, LDAP will not work with this image version. Users requiring immediate LDAP functionality must either:

Build a custom Docker image that installs the PHP LDAP extension on top of the base image.

Wait for the official cypht:2.5.0 release, which is planned to include full LDAP support.

Final Notes

We hope this guide has been helpful in configuring LDAP authentication for your Cypht instance. Thank you for choosing Cypht as your webmail solution.

The Cypht project thrives on feedback and contributions from its community. If you encounter any errors or have suggestions for improving this documentation, please do not hesitate to open an issue on the official Cypht GitHub repository. Your input is invaluable in helping to improve the software for everyone.

###

>

Clone this wiki locally