DevDungeon Wiki

Lightweight Directory Access Protocol or LDAP is useful for authenticating and authorizing users. It's convenient for having a central location to manage users and groups that many different applications can use.

There are a few LDAP servers out there. Two popular ones that are available in Debian are Apache Directory Server and OpenLDAP.

Apache DS is a Java implementation of an LDAP server. Part of the larger project also includes Apache Directory Studio, a desktop application for interacting with any LDAP server and a Java library for interacting with LDAP.

# Install Apache Directory Server
apt install apacheds
 
# Start and stop with `systemctl`
systemctl restart apacheds

It will then be listening on port 10389 (ldap/StartTLS) and 10636 (TLS).

The default admin is uid=admin,ou=system with a password of secret.

If for some reason you have to totally wipe and restart, use:

apt remove --purge apacheds
rm -rf /var/lib/apacheds
rm -rf /etc/apacheds

Here are instructions on setup OpenLDAP on Debian with LetsEncrypt SSL certificates.

apt install slapd ldap-utils
 
# Show config, default admin is ''cn=admin,dc=nodomain''
slapcat
 
# Set proper domain and reset admin password
# Omit? No. Set domain e.g. devdungeon.com, Move old db yes
dpkg-reconfigure slapd  
 
# Now the admin is ''cn=admin,dc=devdungeon,dc=com''
slapcat
 
# Login and confirm new admin/pass is working
ldapwhoami -W -x -D "cn=admin,dc=devdungeon,dc=com" -H ldap://localhost

To enable StartTLS, you must generate and configure the certificates. It is critical that the openldap user gets read/execute access to the certs and the containing directory (and any symlinked destination). If you don't want to use LetsEncrypt, and would rather self-sign your own certificates, put them wherever you want, maybe /etc/openldap/ssl and make sure the openldap user or group has read/execute access.

apt install certbot
# Get a cert; E.g. `ldap.devdungeon.com`
certbot certonly
 
# Or if you want to generate self signed certs with openssl
# openssl req -newkey rsa:2048 -nodes \
#   -keyout /etc/openldap/ssl/privkey.pem \
#   -x509 -days 36500 \
#   -out /etc/openldap/ssl/cert.pem
 
# Setup permissions to certs properly (CRITICAL!)
chown -R root:openldap /etc/letsencrypt/{live,archive}/ldap.devdungeon.com
chmod -R 750 /etc/letsencrypt/{live,archive}/ldap.devdungeon.com
chmod 750 /etc/letsencrypt/{,live,archive}
 
# Update slapd to use the right cert/key
ldapmodify -H ldapi:/// -Y EXTERNAL << EOF
dn: cn=config
changetype: modify
replace: olcTLSCertificateFile
olcTLSCertificateFile: /etc/letsencrypt/live/ldap.devdungeon.com/cert.pem
-
replace: olcTLSCertificateKeyFile
olcTLSCertificateKeyFile: /etc/letsencrypt/live/ldap.devdungeon.com/privkey.pem
 
EOF
 
systemctl restart slapd

TODO: Setup certbot auto renew, with a post hook to restart slapd

At this point you can use StartTLS on the ldap: port. If you also want to enable the deprecated LDAPS on port 636, edit /etc/default/slapd and add the ldaps protocol: <code bash> # Update `SLAPD_SERVICES` to include `ldaps:/` vim /etc/default/slapd # And restart the service systemctl restart slapd </code>

Now you connect using no encryption, StartTLS, or LDAPS.

Then you can add new organizational units and users.

Add a new user with Apache Directory Studio, add an org unit first, with rdn: ou=hackers. Here are the raw ldif codes it generates.

| add_ou.ldif

dn: ou=hackers,dc=devdungeon,dc=com
changetype: add
ou: hackers
objectClass: organizationalUnit
objectClass: top

Then create a new entry with simpleSecurityObject (for password and cn) and organizationalRole for the structural

| add_user.ldif

dn: cn=nanodano,ou=hackers,dc=devdungeon,dc=com
changetype: add
cn: nanodano
objectClass: organizationalRole
objectClass: top
objectClass: simpleSecurityObject
userPassword:: e2NTSEF9UUlUdmFHQmRIR29RVTBFakl2UGdUL3VNc2ZjRmg2STJaeW4zQOE9PQ=
 =

If you need a hashed password to provide to the userPassword value, you can use slappasswd:

slappasswd

In Debian, you can simply install using the system package manager:

apt install ldap-utils

It comes with a few utilities like:

/usr/bin/ldapcompare
/usr/bin/ldapdelete
/usr/bin/ldapexop
/usr/bin/ldapmodify
/usr/bin/ldapmodrdn
/usr/bin/ldappasswd
/usr/bin/ldapsearch
/usr/bin/ldapurl
/usr/bin/ldapwhoami

You can use ldapwhoami to test logging in to a server. It's good to confirm the connections are working as expected and the credentials and distinguished name are correct.

# -W = prompt for password
# -x = Simple Authentication
# -D = bind DN
# -H = host URL
 
# Use ldap:// or ldaps://
ldapwhoami -W -x -D "uid=admin,ou=system" -H ldap://ldap.devdungeon.com:389

You can also use ldapadd and ldapmodify to add or change users and configs.

# 
ldapmodify -H ldapi:/// -Y EXTERNAL -f change.ldif

Apache Directory Studio, a desktop application for interacting with any LDAP server.

Libraries

apt install python3-ldap
# or
pip install python-ldap

| ldap_test.py

# `apt install python3-ldap` or `pip install python-ldap`
from getpass import getpass
import ldap
 
# This is needed for self-signed certs or when you don't have the CA locally
# But it makes the client less secure. Only enable the following line
# if you really need to (perhaps for troubleshooting).
# ldap.set_option(ldap.OPT_X_TLS_REQUIRE_CERT, ldap.OPT_X_TLS_NEVER)
 
# Use ldap:// or ldaps://
con = ldap.initialize('ldap://ldap.devdungeon.com')  
 
# If you are using ldaps:// you don't need to StartTLS too
try:
  con.start_tls_s()
  print("StartTLS initialized properly.")
except ldap.LDAPError as e:
  print("Could not start TLS.", e)
  exit(1)
 
try:
  print("Attempting to bind")
  password = getpass()
  con.bind_s('cn=dano,dc=devdungeon,dc=com', password)
except ldap.INVALID_CREDENTIALS:
  print('Invalid credentials')
except ldap.INVALID_DN_SYNTAX:
  print('Invalid distinguished name.')
 
print(f"I am bound as: {con.whoami_s()}")

https://directory.apache.org/api/

LDIF files are used to make changes to the LDAP server. They seem pretty gnarly at first, but you get used to them and they actually becomes a nice convenient way of documenting changes via code.

You can pass LDIF files directly as a heredoc or as a separate file:

# Pass a file
ldapmodify -H ldapi:/// -Y EXTERNAL -f change.ldif
 
# Pass the ldif directly
ldapmodify -H ldapi:/// -Y EXTERNAL << EOF
dn: cn=config
changetype: modify
replace: olcTLSCertificateFile
olcTLSCertificateFile: /etc/letsencrypt/live/ldap.devdungeon.com/cert.pem
-
replace: olcTLSCertificateKeyFile
olcTLSCertificateKeyFile: /etc/letsencrypt/live/ldap.devdungeon.com/privkey.pem
 
EOF