# OpenLDAP

> Full-featured LDAP directory server.

- Category: Security & Networking
- Difficulty: advanced
- Components: openldap, phpldapadmin
- Tags: openldap, ldap, directory, authentication
- Source: https://docker.recipes/security/openldap

## Overview

OpenLDAP is an open-source implementation of the Lightweight Directory Access Protocol (LDAP), originally developed by the University of Michigan and now maintained by the OpenLDAP Foundation. As a robust directory server, OpenLDAP provides centralized authentication, authorization, and directory information services for organizations of all sizes. It serves as the backbone for user management, storing organizational data in a hierarchical tree structure that can be efficiently queried and maintained across distributed networks.

This Docker stack combines the osixia/openldap server with phpLDAPadmin, creating a complete directory service solution with web-based management capabilities. The OpenLDAP container handles all directory operations, user authentication, and LDAP protocol communications, while phpLDAPadmin provides an intuitive web interface for administrators to manage directory entries, organizational units, and user accounts without requiring command-line LDAP tools.

This combination is ideal for system administrators who need enterprise-grade directory services with modern web-based management. Small to medium businesses can deploy this stack to centralize user authentication across multiple applications, while developers can use it for testing LDAP integration in their applications. The containerized approach eliminates the complexity of traditional OpenLDAP installations while maintaining full functionality and security features.

## Features

- Full RFC-compliant LDAP v3 directory server with multi-master replication support
- Hierarchical directory structure with customizable organizational units and schema
- Built-in support for both plaintext (389) and TLS-encrypted (636) LDAP connections
- phpLDAPadmin web interface with tree-based directory browsing and entry editing
- SASL authentication mechanisms including GSSAPI, DIGEST-MD5, and PLAIN
- Advanced access control lists (ACL) for fine-grained permission management
- Schema extension capabilities for custom attributes and object classes
- Automatic LDIF import/export functionality for directory backup and migration

## Use cases

- Corporate user authentication for applications like GitLab, Jenkins, and wiki systems
- Centralized employee directory with contact information and organizational hierarchy
- Single sign-on (SSO) backend for web applications and enterprise software
- Development environment for testing LDAP integration in custom applications
- Small business network authentication replacing Active Directory
- Educational institutions managing student and faculty accounts across multiple systems
- Homelab environments for learning directory services and authentication protocols

## Prerequisites

- Minimum 512MB RAM allocated to Docker (OpenLDAP requires 256MB, phpLDAPadmin needs 128MB)
- Ports 389, 636, and 8080 available on the host system
- Basic understanding of LDAP concepts including DN, DC, CN, and OU structures
- Knowledge of LDIF format for importing/exporting directory data
- SSL/TLS certificates if planning to use secure LDAP connections in production
- Backup strategy for persistent volumes containing directory data and configuration

## docker-compose.yml

```yaml
services:
  openldap:
    image: osixia/openldap:latest
    container_name: openldap
    restart: unless-stopped
    environment:
      LDAP_ORGANISATION: "Example Inc."
      LDAP_DOMAIN: example.com
      LDAP_ADMIN_PASSWORD: ${ADMIN_PASSWORD}
    volumes:
      - openldap_data:/var/lib/ldap
      - openldap_config:/etc/ldap/slapd.d
    ports:
      - "389:389"
      - "636:636"

  phpldapadmin:
    image: osixia/phpldapadmin:latest
    container_name: phpldapadmin
    restart: unless-stopped
    environment:
      PHPLDAPADMIN_LDAP_HOSTS: openldap
      PHPLDAPADMIN_HTTPS: "false"
    ports:
      - "8080:80"
    depends_on:
      - openldap

volumes:
  openldap_data:
  openldap_config:
```

## .env

```bash
ADMIN_PASSWORD=changeme
```

## Usage notes

- Docs: https://www.openldap.org/doc/admin26/
- phpLDAPadmin web UI at http://localhost:8080
- Login DN: cn=admin,dc=example,dc=com with ADMIN_PASSWORD
- LDAP on port 389 (plaintext), 636 (TLS)
- Change LDAP_DOMAIN to match your organization
- Backup: slapcat > backup.ldif, restore: slapadd -l backup.ldif

## Troubleshooting

- phpLDAPadmin shows 'Could not connect to LDAP server': Verify openldap container is running and check PHPLDAPADMIN_LDAP_HOSTS environment variable matches service name
- Login fails with 'Invalid credentials' error: Ensure ADMIN_PASSWORD environment variable is set and use full DN format 'cn=admin,dc=example,dc=com' for login
- LDAP search returns 'No such object' errors: Check that LDAP_DOMAIN matches your directory structure and verify base DN configuration
- Container fails to start with 'Database already exists' error: Remove existing volumes or set LDAP_REMOVE_CONFIG_AFTER_SETUP=true to reinitialize
- TLS connection refused on port 636: Generate proper SSL certificates and mount them to /container/service/slapd/assets/certs/ directory
- Directory entries disappear after container restart: Ensure openldap_data and openldap_config volumes are properly mounted and persistent

