Skip to content

LDAP Server Setup Guide

This guide covers setting up and testing a local LDAP server for the Bank USSD application.

Quick Start

Windows

# Run the setup script
setup_ldap.bat

macOS/Linux

# Start the services
docker-compose -f compose.dev.yml up -d openldap phpldapadmin

# Wait 15 seconds, then load test users
docker cp ldap_init.ldif bank-ldap:/ldap_init.ldif
docker exec bank-ldap ldapadd -x -D "cn=admin,dc=bank,dc=local" -w "admin123" -H ldap://localhost:389 -f /ldap_init.ldif

Server Details

Property Value
LDAP Server ldap://localhost:389
LDAP SSL ldaps://localhost:636
Admin DN cn=admin,dc=bank,dc=local
Admin Password admin123
Base DN dc=bank,dc=local
Organization Bank USSD
Domain bank.local

Web Admin Interface

URL: https://localhost:6443

Login: - Login DN: cn=admin,dc=bank,dc=local - Password: admin123

Note: Accept the SSL warning (self-signed certificate)

Test Users

User 1: Admin

  • Username: admin
  • Password: admin123
  • Email: admin@bank.local
  • Groups: admins

User 2: John Doe

  • Username: john.doe
  • Password: password123
  • Email: john.doe@bank.local
  • Groups: admins, staff

User 3: Jane Smith

  • Username: jane.smith
  • Password: password456
  • Email: jane.smith@bank.local
  • Groups: staff, customers

User 4: Test Agent

  • Username: test.agent
  • Password: testpass789
  • Email: test.agent@bank.local
  • Groups: customers

Testing LDAP Login

Via API - Using curl

# Test User: John Doe
curl -X POST http://localhost:8000/auth/ldap/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=john.doe&password=password123&method=ldap"

# Expected Response:
# {
#   "access_token": "eyJhbGc...",
#   "token_type": "bearer",
#   "user": { "id": 123, "active": true },
#   "refresh_token": "...",
#   "permissions": [...],
#   "session_id": "..."
# }

Via API - Using Postman

  1. Method: POST
  2. URL: http://localhost:8000/auth/ldap/login
  3. Headers:
  4. Content-Type: application/x-www-form-urlencoded
  5. Body (form-data):
  6. username: john.doe
  7. password: password123
  8. method: ldap
  9. Send and check the response

Via Web Admin UI

  1. Go to https://localhost:6443
  2. Login with cn=admin,dc=bank,dc=local / admin123
  3. Navigate to the left panel: Bank USSD → users → Users
  4. You'll see all the test users created

LDAP Configuration in Backend

Your .env.docker.local is already configured:

# LDAP Configuration
LDAP_ENABLED=true
LDAP_URI=ldap://openldap:389
LDAP_BIND_DN=cn=admin,dc=bank,dc=local
LDAP_BIND_PASSWORD=admin123
LDAP_BASE_DN=dc=bank,dc=local
LDAP_USER_FILTER=(uid={username})
LDAP_ATTR_MAIL=mail
LDAP_ATTR_NAME=cn
LDAP_GROUP_MEMBER_ATTR=memberOf

Docker Compose Services

The compose.dev.yml includes:

OpenLDAP Container (openldap)

  • Image: osixia/openldap:latest
  • Ports:
  • 389:389 (LDAP)
  • 636:636 (LDAPS - SSL)
  • Volumes:
  • ldap_data: Persistent LDAP data
  • ldap_config: LDAP configuration

phpLDAPadmin Container (phpldapadmin)

  • Image: osixia/phpldapadmin:latest
  • Port: 6443:443 (HTTPS)
  • Purpose: Web UI for managing LDAP

Adding More Users

Via Web UI

  1. Login to https://localhost:6443
  2. Right-click on ou=users in the left tree
  3. Select "Create a child entry"
  4. Choose template: "New inetOrgPerson"
  5. Fill in:
  6. RDN: uid=newuser
  7. cn: User's full name
  8. sn: Last name
  9. userPassword: User's password
  10. mail: User's email

Via LDIF File

Create a new LDIF file (e.g., add_user.ldif):

dn: uid=alice.johnson,ou=users,dc=bank,dc=local
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
uid: alice.johnson
cn: Alice Johnson
sn: Johnson
userPassword: password999
mail: alice.johnson@bank.local

Then load it:

# Windows
docker cp add_user.ldif bank-ldap:/add_user.ldif
docker exec bank-ldap ldapadd -x -D "cn=admin,dc=bank,dc=local" -w "admin123" -H ldap://localhost:389 -f /add_user.ldif

Adding Users to Groups

Via Web UI

  1. Navigate to ou=groups in the left tree
  2. Select the group (e.g., cn=staff)
  3. Edit the member attribute
  4. Add: uid=alice.johnson,ou=users,dc=bank,dc=local

Via LDIF File

dn: cn=staff,ou=groups,dc=bank,dc=local
changetype: modify
add: member
member: uid=alice.johnson,ou=users,dc=bank,dc=local

Load it: 

docker cp modify_group.ldif bank-ldap:/modify_group.ldif
docker exec bank-ldap ldapadd -x -D "cn=admin,dc=bank,dc=local" -w "admin123" -H ldap://localhost:389 -f /modify_group.ldif

Troubleshooting

LDAP Server Not Starting

# Check logs
docker logs bank-ldap

# Restart the service
docker-compose -f compose.dev.yml restart openldap

Connection Refused

# Verify containers are running
docker ps | findstr openldap

# Check if port 389 is available
netstat -an | findstr 389

Wrong Credentials Error

  • Verify LDAP_BIND_DN and LDAP_BIND_PASSWORD match server config
  • Check that environment variables are loaded: docker exec backend env | grep LDAP

Cannot Access phpLDAPadmin UI

  • Browser might block SSL: Accept the self-signed certificate warning
  • Try private/incognito mode if issues persist

Stopping LDAP Services

# Stop only LDAP services
docker-compose -f compose.dev.yml stop openldap phpldapadmin

# Stop and remove containers
docker-compose -f compose.dev.yml down

# Remove LDAP data (WARNING: This deletes all users!)
docker volume rm bank_ussd_ldap_data bank_ussd_ldap_config

Next Steps

  1. ✅ LDAP server is running
  2. ✅ Test users are created
  3. 👉 Test LDAP login via API curl command above
  4. 📝 Implement SAML IdP (optional - see LDAP_SAML_WORKFLOW.md)

For more details on LDAP/SAML integration, see: - LDAP & SAML API Reference - LDAP & SAML Workflow