docker_ldap_testing/examples/README.md

LDAP Docker Examples

This directory contains example scripts and applications demonstrating how to use the LDAP server for authentication and user management.

Available Examples

1. Simple Authentication (simple_auth.py)

A Python script demonstrating basic LDAP authentication and user information retrieval.

Features:

• Authenticate users with username/password
• Retrieve detailed user information
• Get user group memberships
• List all users in the directory

Usage:

# Authenticate a user (default: jdoe)
python examples/simple_auth.py

# Authenticate with custom credentials
python examples/simple_auth.py --username jsmith --password password123

# List all users
python examples/simple_auth.py --list-users

# Use a different LDAP server
python examples/simple_auth.py --server ldaps://localhost:636

Example Output:

🔐 LDAP Authentication Example
Server: ldap://localhost:389

Attempting to authenticate user: jdoe
✅ Authentication successful for user: jdoe
✅ Authentication successful!

Fetching user information...

==================================================
USER INFORMATION
==================================================
Username:    jdoe
Full Name:   John Doe
First Name:  John
Last Name:   Doe
Email:       jdoe@testing.local
UID Number:  10001
GID Number:  10001
DN:          uid=jdoe,ou=people,dc=testing,dc=local
==================================================

Fetching user groups...
User belongs to 2 group(s):
  • developers
  • users

Using in Your Application

Python with ldap3

from ldap3 import Server, Connection

# Connect and authenticate
server = Server('ldap://localhost:389')
conn = Connection(
    server,
    user='uid=jdoe,ou=people,dc=testing,dc=local',
    password='password123',
    auto_bind=True
)

# Search for users
conn.search(
    'dc=testing,dc=local',
    '(objectClass=inetOrgPerson)',
    attributes=['uid', 'cn', 'mail']
)

for entry in conn.entries:
    print(f"{entry.cn}: {entry.mail}")

conn.unbind()

Using ldapsearch (Command Line)

# Search for a user
ldapsearch -H ldap://localhost:389 \
  -D "cn=admin,dc=testing,dc=local" \
  -w admin_password \
  -b "dc=testing,dc=local" \
  "(uid=jdoe)"

# List all users
ldapsearch -H ldap://localhost:389 \
  -D "cn=admin,dc=testing,dc=local" \
  -w admin_password \
  -b "ou=people,dc=testing,dc=local" \
  "(objectClass=inetOrgPerson)" \
  uid cn mail

Web Application Integration

Flask Example

from flask import Flask, request, jsonify
from ldap3 import Server, Connection

app = Flask(__name__)

@app.route('/login', methods=['POST'])
def login():
    username = request.json.get('username')
    password = request.json.get('password')
    
    server = Server('ldap://localhost:389')
    user_dn = f'uid={username},ou=people,dc=testing,dc=local'
    
    try:
        conn = Connection(server, user=user_dn, password=password)
        if conn.bind():
            return jsonify({'status': 'success', 'message': 'Authenticated'})
        else:
            return jsonify({'status': 'error', 'message': 'Invalid credentials'}), 401
    except:
        return jsonify({'status': 'error', 'message': 'Authentication failed'}), 401

Django Example

# settings.py
import ldap
from django_auth_ldap.config import LDAPSearch

AUTH_LDAP_SERVER_URI = "ldap://localhost:389"
AUTH_LDAP_BIND_DN = "cn=admin,dc=testing,dc=local"
AUTH_LDAP_BIND_PASSWORD = "admin_password"
AUTH_LDAP_USER_SEARCH = LDAPSearch(
    "ou=people,dc=testing,dc=local",
    ldap.SCOPE_SUBTREE,
    "(uid=%(user)s)"
)

AUTHENTICATION_BACKENDS = [
    'django_auth_ldap.backend.LDAPBackend',
    'django.contrib.auth.backends.ModelBackend',
]

Common Integration Patterns

1. Simple Bind Authentication

The most straightforward approach - try to bind with user credentials:

def authenticate_user(username, password):
    server = Server('ldap://localhost:389')
    user_dn = f'uid={username},ou=people,dc=testing,dc=local'
    conn = Connection(server, user=user_dn, password=password)
    return conn.bind()

2. Search and Bind

Search for the user first, then authenticate:

def authenticate_user(username, password):
    # First, search for the user with admin credentials
    server = Server('ldap://localhost:389')
    admin_conn = Connection(
        server,
        user='cn=admin,dc=testing,dc=local',
        password='admin_password',
        auto_bind=True
    )
    
    admin_conn.search(
        'ou=people,dc=testing,dc=local',
        f'(uid={username})',
        attributes=['dn']
    )
    
    if not admin_conn.entries:
        return False
    
    user_dn = admin_conn.entries[0].entry_dn
    admin_conn.unbind()
    
    # Now authenticate as the user
    user_conn = Connection(server, user=user_dn, password=password)
    return user_conn.bind()

3. Group-Based Authorization

Check if user belongs to specific groups:

def user_has_role(username, required_group):
    server = Server('ldap://localhost:389')
    conn = Connection(
        server,
        user='cn=admin,dc=testing,dc=local',
        password='admin_password',
        auto_bind=True
    )
    
    user_dn = f'uid={username},ou=people,dc=testing,dc=local'
    
    conn.search(
        'ou=groups,dc=testing,dc=local',
        f'(&(objectClass=groupOfNames)(member={user_dn})(cn={required_group}))',
        attributes=['cn']
    )
    
    return len(conn.entries) > 0

Testing Your Integration

1. Start the LDAP Server

make start

2. Test Connection

python examples/simple_auth.py --list-users

3. Test Authentication

python examples/simple_auth.py --username jdoe --password password123

4. Test with Your Application

Point your application to:

• LDAP URL: ldap://localhost:389
• LDAPS URL: ldaps://localhost:636 (with SSL)
• Base DN: dc=testing,dc=local

Available Test Accounts

Username	Password	Groups	Purpose
admin	password123	admins	Administrative testing
jdoe	password123	developers, users	Regular user testing
jsmith	password123	developers, users	Regular user testing
testuser	password123	users	Basic user testing

SSL/TLS Configuration

For production-like testing with LDAPS:

import ssl
from ldap3 import Server, Connection, Tls

tls = Tls(
    ca_certs_file='certs/ca.crt',
    validate=ssl.CERT_REQUIRED
)

server = Server('ldaps://localhost:636', use_ssl=True, tls=tls)
conn = Connection(server, user=user_dn, password=password, auto_bind=True)

Troubleshooting

Connection Refused

# Check if LDAP server is running
make status

# Start if not running
make start

Authentication Fails

# Verify user exists
make test-users

# Check LDAP logs
make logs

Python ImportError

# Install ldap3 library
uv pip install ldap3
# or
pip install ldap3

Additional Resources

• ldap3 Documentation
• LDAP Protocol Overview
• Django LDAP Authentication
• Flask-LDAP3-Login

Contributing Examples

Have an example for a specific framework or use case? Contributions are welcome!

Examples we'd love to see:

• Express.js / Node.js authentication
• Ruby on Rails integration
• Go LDAP client
• Java Spring Security LDAP
• PHP authentication
• Docker Compose with application stack

Submit a pull request with your example!