Perfect for local development and testing of applications that need LDAP authentication without setting up a complex infrastructure. Just run docker-compose up -d and you're ready to go!

Features

SSL/TLS Support - LDAPS on port {.env:LDAPS_PORT} with custom certificate support
Pre-populated Users - Test users and groups ready to use
Web Admin Interface - phpLDAPadmin for easy management
Docker-based - Easy deployment with Docker Compose
Fully Configurable - Customize ports, domain, credentials via .env file
Optional Management Tools - Makefile and Python scripts for convenience
Cross-platform - Works anywhere Docker runs

📝 Note: Throughout this documentation, values shown as {.env:VARIABLE_NAME} indicate they can be customized via environment variables. See Configuration for details.

Prerequisites
Quick Start
Verify Installation
Custom Certificates (Dev-CA)
Usage
Configuration
Test Users
Next Steps
Management Tools
Project Structure
Troubleshooting
Development

Prerequisites

Required

Docker - Any provider that can run Docker Compose
- Docker Desktop (Windows, Mac, Linux)
- Rancher Desktop (Alternative for Mac/Linux)
- Or native Docker on Linux
SSL Certificates - Either:
- Generate with the included Python script (requires Python 3.9+)
- OR bring your own certificates (see Custom Certificates)

That's it! Everything runs in Docker containers.

Optional Tools

These tools provide convenient shortcuts but are not required:

Make - For using make start instead of docker-compose up -d
Python 3.9+ - For certificate generation script and examples
UV Package Manager - Fast Python dependency management
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```
OpenSSL - For manual certificate verification
LDAP utilities - Command-line tools (ldapsearch, ldapadd, etc.)

Quick Start

Simple Way (Docker Only)

# 1. Generate certificates (requires Python)
python3 scripts/generate_certs.py

# 2. Start the server
docker-compose up -d

# 3. View logs
docker-compose logs -f openldap

# 4. Stop the server
docker-compose down

That's it! The server is now running at ldap://localhost:{.env:LDAP_PORT} and ldaps://localhost:{.env:LDAPS_PORT}.

Convenient Way (Using Make)

If you have Make installed, use these shortcuts:

# Complete setup (installs Python deps, generates certs, starts server)
make dev-setup

# Or step by step:
make install         # Install Python dependencies
make certs-generate  # Generate SSL certificates
make start           # Start the server
make verify-users    # Verify users are loaded
make logs            # View logs

Run make help to see all available commands.

Using Your Own Certificates

Instead of generating certificates, copy yours to the certs/ directory:

cp /path/to/ca.crt certs/ca.crt
cp /path/to/server.crt certs/server.crt
cp /path/to/server.key certs/server.key
docker-compose up -d

💡 Tip: Want to customize ports, passwords, or domain? Copy .env.example to .env and edit your settings. See the Configuration section for details.

Verify Installation

After starting the server, verify everything is working:

Test 1: List All Users

make verify-users

You should see output like:

Found 4 user(s):

  - Admin User: admin (admin@{.env:LDAP_DOMAIN})
  - John Doe: jdoe (jdoe@{.env:LDAP_DOMAIN})
  - Jane Smith: jsmith (jsmith@{.env:LDAP_DOMAIN})
  - Test User: testuser (testuser@{.env:LDAP_DOMAIN})

Test 2: Try the Web Interface

Open http://localhost:{.env:PHPLDAPADMIN_PORT} in your browser and login with:

Login DN: cn=admin,{.env:LDAP_BASE_DN}
Password: {.env:LDAP_ADMIN_PASSWORD}

Test 3: Run the Example Script (Optional - Requires Python)

python examples/simple_auth.py

This authenticates user jdoe and displays their information.

Custom Certificates (Dev-CA)

If you wish, you can use your own certificates instead of self-signed ones:

Using Your Certificates

# Copy your certificates to the certs directory
cp /path/to/your/dev-ca/certs/ldap-server.crt certs/server.crt
cp /path/to/your/dev-ca/private/ldap-server.key certs/server.key
cp /path/to/your/dev-ca/ca-cert.pem certs/ca.crt

# Ensure proper permissions
chmod 644 certs/ca.crt
chmod 644 certs/server.crt
chmod 600 certs/server.key

Important: The server certificate should be issued for the hostname {.env:LDAP_HOSTNAME} or include it as a Subject Alternative Name (SAN).

Certificate Requirements

The OpenLDAP container expects three files in the certs/ directory:

ca.crt - Your CA root certificate (filename: {.env:LDAP_TLS_CA_CRT_FILENAME})
server.crt - Server certificate for {.env:LDAP_HOSTNAME} (filename: {.env:LDAP_TLS_CRT_FILENAME})
server.key - Private key for the server certificate (filename: {.env:LDAP_TLS_KEY_FILENAME})

Generating Certificates with Your OpenSSL-based Dev-CA

If your dev-ca is script-based and uses OpenSSL:

# Example using your dev-ca
cd /path/to/your/dev-ca

# Generate server key
openssl genrsa -out ldap-server.key 4096

# Generate certificate signing request (use your LDAP_HOSTNAME value)
openssl req -new -key ldap-server.key -out ldap-server.csr \
  -subj "/CN={.env:LDAP_HOSTNAME}"

# Sign with your CA (adjust paths as needed)
openssl x509 -req -in ldap-server.csr \
  -CA ca-cert.pem -CAkey ca-key.pem \
  -CAcreateserial -out ldap-server.crt \
  -days 365 -sha256 \
  -extfile <(printf "subjectAltName=DNS:{.env:LDAP_HOSTNAME},DNS:localhost,IP:127.0.0.1")

# Copy to LDAP Docker project
cp ldap-server.crt /path/to/ldap_docker/certs/server.crt
cp ldap-server.key /path/to/ldap_docker/certs/server.key
cp ca-cert.pem /path/to/ldap_docker/certs/ca.crt

Usage

Accessing the Services

Once started, the following services are available:

Service	URL/Connection	Description
LDAP	`ldap://localhost:{.env:LDAP_PORT}`	Standard LDAP (unencrypted)
LDAPS	`ldaps://localhost:{.env:LDAPS_PORT}`	LDAP over SSL/TLS
phpLDAPadmin	`http://localhost:{.env:PHPLDAPADMIN_PORT}`	Web-based administration

Admin Credentials

Admin DN: cn=admin,{.env:LDAP_BASE_DN}
Password: {.env:LDAP_ADMIN_PASSWORD}
Base DN: {.env:LDAP_BASE_DN}

Note: Default values shown. Customize these by creating a .env file (see Configuration).

Common Commands

# Start the server
make start

# Stop the server
make stop

# View logs
make logs

# Check status
make status

# Run unit tests
make test

# Verify running server
make verify-all

# Open shell in container
make shell

# Clean up everything
make clean-all

Configuration

You can customize the LDAP server behavior using environment variables. The easiest way is to create a .env file in the project root.

Quick Configuration

# Copy the example configuration
cp .env.example .env

# Edit with your preferred settings
nano .env  # or vim, code, etc.

Available Configuration Options

The .env.example file includes all available options with documentation. Below is a comprehensive reference of all environment variables:

Variable	Default Value	Description	Usage Reference
Domain & Organization
`LDAP_DOMAIN`	`testing.local`	Your LDAP domain	Used in: Services, Test Users
`LDAP_ORGANISATION`	`Testing Organization`	Organization name	Used in LDAP server metadata
`LDAP_BASE_DN`	`dc=testing,dc=local`	Base Distinguished Name (auto-derived from domain)	Used in: Services, Admin Credentials, Test Users
Credentials
`LDAP_ADMIN_PASSWORD`	`admin_password`	Admin user password	Used in: Admin Credentials, Verify Installation
`LDAP_CONFIG_PASSWORD`	`config_password`	Configuration admin password	Used for LDAP server configuration
Ports
`LDAP_PORT`	`389`	Standard LDAP port (unencrypted)	Used in: Services, Testing Authentication
`LDAPS_PORT`	`636`	LDAPS/SSL port (encrypted)	Used in: Services, Testing Authentication
`PHPLDAPADMIN_PORT`	`8080`	Web UI port	Used in: Services, Verify Installation
SSL/TLS
`LDAP_TLS`	`true`	Enable TLS support	Controls SSL/TLS functionality
`LDAP_TLS_CRT_FILENAME`	`server.crt`	Server certificate filename	Used in: Custom Certificates
`LDAP_TLS_KEY_FILENAME`	`server.key`	Server private key filename	Used in: Custom Certificates
`LDAP_TLS_CA_CRT_FILENAME`	`ca.crt`	CA certificate filename	Used in: Custom Certificates
`LDAP_TLS_VERIFY_CLIENT`	`try`	Client certificate verification mode	Options: `never`, `allow`, `try`, `demand`
Container Configuration
`LDAP_HOSTNAME`	`ldap.testing.local`	LDAP server hostname	Used in certificate validation
`LDAP_CONTAINER_NAME`	`ldap-server`	LDAP container name	Used in Docker commands
`PHPLDAPADMIN_CONTAINER_NAME`	`ldap-admin`	phpLDAPadmin container name	Used in Docker commands
Other Options
`LDAP_LOG_LEVEL`	`256`	Logging verbosity	Higher = more verbose

Tip: Throughout this documentation, values shown as {.env:VARIABLE_NAME} indicate they are configured via these environment variables.

Summary by Category

Domain & Organization

LDAP_DOMAIN - Your LDAP domain (default: testing.local)
LDAP_ORGANISATION - Organization name (default: Testing Organization)
LDAP_BASE_DN - Base DN, auto-derived from domain if not set

Credentials

LDAP_ADMIN_PASSWORD - Admin password (default: admin_password)
LDAP_CONFIG_PASSWORD - Config admin password (default: config_password)

Ports

LDAP_PORT - Standard LDAP port (default: 389)
LDAPS_PORT - LDAPS/SSL port (default: 636)
PHPLDAPADMIN_PORT - Web UI port (default: 8080)

SSL/TLS

LDAP_TLS - Enable TLS (default: true)
LDAP_TLS_CRT_FILENAME - Server cert filename (default: server.crt)
LDAP_TLS_KEY_FILENAME - Server key filename (default: server.key)
LDAP_TLS_CA_CRT_FILENAME - CA cert filename (default: ca.crt)

Container Names

LDAP_HOSTNAME - LDAP server hostname (default: ldap.testing.local)
LDAP_CONTAINER_NAME - Container name (default: ldap-server)
PHPLDAPADMIN_CONTAINER_NAME - Admin UI container (default: ldap-admin)

Other Options

LDAP_LOG_LEVEL - Logging verbosity (default: 256)
DEBUG - Enable debug output (default: false)
TZ - Timezone (default: UTC)

Example Custom Configuration

# .env
LDAP_DOMAIN=mycompany.local
LDAP_ORGANISATION=My Company
LDAP_ADMIN_PASSWORD=mysecurepassword

# Use different ports
LDAP_PORT=1389
LDAPS_PORT=1636
PHPLDAPADMIN_PORT=9080

After creating or modifying .env, restart the containers:

docker-compose down
docker-compose up -d

For a complete list of options with detailed descriptions, see .env.example.

Default Test Users

The LDAP directory is pre-populated with the following test users:

Username	Full Name	Email	Password	UID
admin	Admin User	admin@`{.env:LDAP_DOMAIN}`	password123	10000
jdoe	John Doe	jdoe@`{.env:LDAP_DOMAIN}`	password123	10001
jsmith	Jane Smith	jsmith@`{.env:LDAP_DOMAIN}`	password123	10002
testuser	Test User	testuser@`{.env:LDAP_DOMAIN}`	password123	10003

Note: Email addresses are based on {.env:LDAP_DOMAIN} (default: testing.local). User DNs follow the pattern uid=username,ou=people,{.env:LDAP_BASE_DN}.

Test Groups

admins - Administrator group (member: admin)
developers - Development team (members: jdoe, jsmith)
users - General users (members: jdoe, jsmith, testuser)

Testing Authentication

# Test with ldapsearch (using default ports from .env)
ldapsearch -H ldap://localhost:{.env:LDAP_PORT} \
  -D "uid=jdoe,ou=people,{.env:LDAP_BASE_DN}" \
  -w password123 \
  -b "{.env:LDAP_BASE_DN}" \
  "(uid=jdoe)"

# Test LDAPS with SSL
ldapsearch -H ldaps://localhost:{.env:LDAPS_PORT} \
  -D "uid=jdoe,ou=people,{.env:LDAP_BASE_DN}" \
  -w password123 \
  -b "{.env:LDAP_BASE_DN}" \
  "(uid=jdoe)"

# Best practice: Test auth by searching for user's own entry
# This works for all users, not just admin
ldapsearch -H ldap://localhost:{.env:LDAP_PORT} \
  -D "uid=jdoe,ou=people,{.env:LDAP_BASE_DN}" \
  -w password123 \
  -b "uid=jdoe,ou=people,{.env:LDAP_BASE_DN}" \
  -s base \
  "(objectClass=*)"

Extended Directory Structure

This project includes a comprehensive enterprise directory structure with 240+ entries across multiple organizational units, providing a realistic testing environment.

What's Included

The directory structure now includes:

34 User Accounts across multiple departments (IT, Engineering, Sales, Marketing, Finance, HR, Operations, Legal, Executive)
30+ Service Accounts for applications, CI/CD, monitoring, automation, and integrations
45+ Computer/Device Accounts including workstations, laptops, servers (production, development, infrastructure), and network devices
50+ Groups covering departments, security/access control, applications, projects, and locations
40+ Shared Resources including conference rooms, printers, video conferencing equipment, and facilities
40+ Organizational Units with nested department and location structures

LDIF Files

The directory is populated from multiple LDIF files loaded in sequence:

01-users.ldif - Base users and groups (original test users)
02-organizational-structure.ldif - Comprehensive OU hierarchy
03-department-users.ldif - Departmental user accounts
04-computers.ldif - Computer and device accounts
05-service-accounts.ldif - Application service accounts
06-groups.ldif - Comprehensive group structure
07-resources.ldif - Shared resources and equipment

Key Features

Realistic Organization: Departments with nested sub-units (IT, Engineering, Sales, Marketing, etc.)
Geographic Distribution: Users and devices assigned to New York, San Francisco, London, Tokyo, and Remote locations
Network Infrastructure: Servers with IP addresses, MAC addresses, and proper attributes
Group Hierarchies: Department groups, security groups, application access groups, and project teams
Service Accounts: Dedicated accounts for CI/CD, monitoring, backup, automation, and integrations
Physical Resources: Conference rooms, printers, video conferencing equipment cataloged in LDAP

Documentation

For detailed information about the directory structure, including:

Complete listings of all users, computers, and resources
LDAP search examples
Customization instructions
Integration patterns

See ldif/README.md for comprehensive documentation.

Example Queries

# List all engineering team members
ldapsearch -x -H ldap://localhost:389 -D "cn=admin,dc=testing,dc=local" -w admin \
  -b "ou=people,dc=testing,dc=local" "(departmentNumber=Engineering*)" cn mail title

# Find all production servers
ldapsearch -x -H ldap://localhost:389 -D "cn=admin,dc=testing,dc=local" -w admin \
  -b "ou=computers,dc=testing,dc=local" "(cn=SRV-*-PROD-*)" cn ipHostNumber

# List conference rooms in New York
ldapsearch -x -H ldap://localhost:389 -D "cn=admin,dc=testing,dc=local" -w admin \
  -b "ou=resources,dc=testing,dc=local" "(&(cn=*-CR-*)(l=New York))" cn description

Python Explorer Script

A comprehensive directory explorer script is available to demonstrate working with the extended structure:

# From the project root
python examples/directory_explorer.py

This script demonstrates:

Searching users by department
Finding computers and servers by type
Querying service accounts
Exploring groups and memberships
Locating shared resources
Testing authentication

Next Steps

Now that your LDAP server is running, you can:

1. Integrate with Your Application

Point your application to the LDAP server:

LDAP URL: ldap://localhost:{.env:LDAP_PORT}
LDAPS URL: ldaps://localhost:{.env:LDAPS_PORT}
Base DN: {.env:LDAP_BASE_DN}

See examples/README.md for code samples and integration patterns.

2. Add Custom Users

Edit ldif/01-users.ldif to add more users or modify existing ones, then reload:

make down-volumes  # WARNING: Deletes all data
make start

3. Customize Configuration

Create a .env file to customize ports, credentials, and behavior:

cp .env.example .env
# Edit .env with your settings
docker-compose down && docker-compose up -d

See the Configuration section for all available options.

4. Learn More

certs/README.md - Certificate management guide
examples/README.md - Integration examples and patterns
OpenLDAP Documentation

Management Tools

You can manage the LDAP server using docker-compose commands directly, or use the included Makefile for convenience.

Using Docker Compose (No Additional Tools Required)

# Server management
docker-compose up -d              # Start server
docker-compose stop               # Stop server
docker-compose restart            # Restart server
docker-compose logs -f openldap   # View logs
docker-compose ps                 # Check status
docker-compose down               # Remove containers
docker-compose down -v            # Remove containers and data

# Generate certificates (requires Python)
python3 scripts/generate_certs.py

Using Make (Optional Convenience)

If you have Make installed, use these shortcuts:

make help            # View all available commands

# Server management
make start           # Start the LDAP server
make stop            # Stop the LDAP server
make restart         # Restart the LDAP server
make logs            # View server logs
make status          # Check server status

# Certificate management
make certs-generate  # Generate SSL certificates
make certs-check     # Verify SSL certificates

# Unit Testing (requires Python + pytest)
make test            # Run unit tests
make test-cov        # Run tests with coverage

# Verification (requires running container + ldap3)
make verify-connection # Verify LDAP connection
make verify-auth       # Verify authentication
make verify-users      # List all users
make verify-all        # Run all verification checks

# Setup
make install         # Install Python dependencies
make dev-setup       # Complete development setup

# Cleanup
make clean           # Clean build artifacts
make down-volumes    # Remove containers and data

Project Structure

ldap_docker/
├── certs/                    # SSL/TLS certificates (git-ignored)
│   ├── README.md            # Certificate documentation
│   ├── ca.crt               # CA certificate (your dev-ca)
│   ├── server.crt           # Server certificate
│   └── server.key           # Server private key
├── ldif/                     # LDAP Data Interchange Format files
│   └── 01-users.ldif        # Initial user and group data
├── scripts/                  # Management scripts
│   └── generate_certs.py    # Certificate generation utility
├── docker-compose.yml        # Docker Compose configuration
├── pyproject.toml           # Python project configuration (UV)
├── Makefile                 # Convenient command shortcuts
├── .gitignore               # Git ignore rules
└── README.md                # This file

Troubleshooting

Docker/Rancher Desktop Issues

Problem: docker command not found

# For Rancher Desktop on MacOS, ensure it's running and configured
# Check Docker settings in Rancher Desktop preferences

Problem: Cannot connect to Docker daemon

# Ensure Rancher Desktop or Docker Desktop is running
# On MacOS: Check if Rancher Desktop is in the menu bar

Certificate Issues

Problem: LDAPS connection fails with certificate error

# Verify certificates exist
make certs-check

# Check certificate details
openssl x509 -in certs/server.crt -text -noout

# Verify certificate chain
openssl verify -CAfile certs/ca.crt certs/server.crt

Problem: Wrong hostname in certificate

# Regenerate with correct hostname
make certs-generate

# Or copy certificates from your dev-ca with correct hostname

Connection Issues

Problem: Cannot connect to LDAP server

# Check if containers are running
docker-compose ps

# View logs for errors
make logs

# Test basic connectivity
telnet localhost {.env:LDAP_PORT}

Problem: Authentication fails

# Verify credentials
# Default admin: cn=admin,{.env:LDAP_BASE_DN} / {.env:LDAP_ADMIN_PASSWORD}

# Check LDAP logs
docker-compose logs openldap | grep -i error

Data Issues

Problem: Users not appearing

# Check if LDIF files were loaded
docker-compose logs openldap | grep -i ldif

# Restart and reload
make down-volumes  # WARNING: Deletes data
make start

Development

Adding Custom Users

Edit ldif/01-users.ldif to add more users or modify existing ones:

dn: uid=newuser,ou=people,{.env:LDAP_BASE_DN}
objectClass: inetOrgPerson
objectClass: posixAccount
objectClass: shadowAccount
uid: newuser
cn: New User
sn: User
mail: newuser@{.env:LDAP_DOMAIN}
userPassword: {SSHA}5en6G6MezRroT3XKqkdPOmY/BFQ=
uidNumber: 10004
gidNumber: 10004
homeDirectory: /home/newuser
loginShell: /bin/bash

Note: Replace {.env:LDAP_BASE_DN} and {.env:LDAP_DOMAIN} with your actual values from the .env file (defaults: dc=testing,dc=local and testing.local).

Then restart with fresh data:

make down-volumes
make start

Modifying Configuration

The easiest way to customize settings is with a .env file:

cp .env.example .env
# Edit .env with your preferences
docker-compose down && docker-compose up -d

See .env.example for all available options with detailed documentation, or the Configuration section.

For advanced customization, you can also edit docker-compose.yml to change volume mounts, resource limits, or other Docker-specific settings.

Python Development (Optional)

If you're contributing to the Python scripts:

# Install development dependencies (requires UV)
make install-dev

# Run tests
uv run pytest

# Format and lint code
ruff format scripts/
ruff check scripts/

Cross-Platform Compatibility

This project uses standard Docker images and docker-compose.yml format, so it works anywhere Docker runs:

Linux - Native Docker
MacOS - Docker Desktop, Rancher Desktop, or Colima
Windows - Docker Desktop (with WSL2)

No platform-specific code or configuration needed!

Security Notes

⚠️ This is a development tool only!

Default passwords are weak and well-known
Self-signed certificates are not trusted
No backup or disaster recovery
No monitoring or alerting
Not hardened for production use

Never use this in production or with real user data!

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! This is a development tool, so:

Keep it simple and easy to use
Maintain cross-platform compatibility
Update documentation for any changes
Test with both Docker Desktop and Rancher Desktop

Resources

Need Help? Check the Troubleshooting section or view logs with make logs

Releases 1

v0.1.0 - Initial Release Latest

2025-10-20 13:38:08 -07:00

Languages

Python 70.6%

Makefile 29.4%

README.md

LDAP Docker