sjones/docker_ldap_testing
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
0bac69c801fb9a7a61bf3d5d7882ec2c5ac8a2ed
docker_ldap_testing/README.md

11 KiB
Raw Blame History

LDAP Docker

This is a development tool project that, when deployed, offers an SSL-capable OpenLDAP server populated with test users for a fictional testing.local domain.

Perfect for local development and testing of applications that need LDAP authentication without setting up a complex infrastructure.

Features

  • 🔒 SSL/TLS Support - LDAPS on port 636 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
  • 🔧 Python Management Tools - UV-based CLI for convenience
  • 🍎 Cross-platform - Works on MacOS (Rancher Desktop), Linux, and Windows

Table of Contents

Prerequisites

Required

  • Docker or Rancher Desktop (recommended for MacOS)
  • Python 3.9+ (for management scripts)
  • UV Package Manager (recommended) 
    curl -LsSf https://astral.sh/uv/install.sh | sh

Optional

  • OpenSSL (for certificate verification)
  • LDAP utilities (ldapsearch, ldapadd, etc.) for testing

Quick Start

Option 1: Using Make (Recommended)

# 1. Install dependencies
make install

# 2. Generate certificates (or copy your own - see below)
make certs-generate

# 3. Start the server
make start

# 4. Test the connection
make test-connection

# 5. List users
make test-users

Option 2: Using Docker Compose Directly

# 1. Generate certificates
python scripts/generate_certs.py

# 2. Start services
docker-compose up -d

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

Option 3: Complete Dev Setup

This will install everything, generate certificates, and start the server:

make dev-setup

Custom Certificates (Dev-CA)

If you maintain your own dev-ca (as mentioned), you can use your own certificates instead of self-signed ones:

Using Your Dev-CA 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 ldap.testing.local 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
  • server.crt - Server certificate for ldap.testing.local
  • server.key - Private key for the server certificate

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
openssl req -new -key ldap-server.key -out ldap-server.csr \
  -subj "/CN=ldap.testing.local"

# 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:ldap.testing.local,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:389 Standard LDAP (unencrypted)
LDAPS ldaps://localhost:636 LDAP over SSL/TLS
phpLDAPadmin http://localhost:8080 Web-based administration

Admin Credentials

  • Admin DN: cn=admin,dc=testing,dc=local
  • Password: admin_password
  • Base DN: dc=testing,dc=local

Common Commands

# Start the server
make start

# Stop the server
make stop

# View logs
make logs

# Check status
make status

# Run tests
make test-all

# Open shell in container
make shell

# Clean up everything
make clean-all

Test Users

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

Username Full Name Email Password UID
admin Admin User admin@testing.local password123 10000
jdoe John Doe jdoe@testing.local password123 10001
jsmith Jane Smith jsmith@testing.local password123 10002
testuser Test User testuser@testing.local password123 10003

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
ldapsearch -H ldap://localhost:389 \
  -D "uid=jdoe,ou=people,dc=testing,dc=local" \
  -w password123 \
  -b "dc=testing,dc=local" \
  "(uid=jdoe)"

# Test LDAPS with SSL
ldapsearch -H ldaps://localhost:636 \
  -D "uid=jdoe,ou=people,dc=testing,dc=local" \
  -w password123 \
  -b "dc=testing,dc=local" \
  "(uid=jdoe)"

Management Tools

This project includes Python-based management tools using UV.

Installation

# Install dependencies with UV
make install

# Or manually
uv sync

CLI Tool Usage

# View available commands
uv run ldap-docker --help

# Server management
uv run ldap-docker server start
uv run ldap-docker server stop
uv run ldap-docker server logs -f

# Certificate management
uv run ldap-docker certs generate
uv run ldap-docker certs check

# Testing
uv run ldap-docker test connection
uv run ldap-docker test auth
uv run ldap-docker test users

# Initialize environment
uv run ldap-docker init

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
│   ├── cli.py               # CLI tool for managing LDAP
│   └── 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 389

Problem: Authentication fails

# Verify credentials
# Default admin: cn=admin,dc=testing,dc=local / 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,dc=testing,dc=local
objectClass: inetOrgPerson
objectClass: posixAccount
objectClass: shadowAccount
uid: newuser
cn: New User
sn: User
mail: newuser@testing.local
userPassword: {SSHA}5en6G6MezRroT3XKqkdPOmY/BFQ=
uidNumber: 10004
gidNumber: 10004
homeDirectory: /home/newuser
loginShell: /bin/bash

Then restart with fresh data:

make down-volumes
make start

Modifying Configuration

Edit docker-compose.yml to change:

  • Port mappings
  • Environment variables
  • Volume mounts
  • Resource limits

Python Development

# Install development dependencies
make install-dev

# Run tests
uv run pytest

# Format code
uv run black scripts/

# Lint code
uv run ruff check scripts/

# Type check
uv run mypy scripts/

Building on Other Platforms

This project is designed to work on:

  • MacOS (with Rancher Desktop or Docker Desktop)
  • Linux (with Docker and Docker Compose)
  • Windows (with Docker Desktop and WSL2)

The docker-compose.yml uses standard Docker images and should work anywhere Docker runs.

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:

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

Resources

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

Reference in New Issue View Git Blame Copy Permalink