Skip to content

Deploying LLDAP as a backing directory on Ubuntu 22.04 (production-ready)

Stand up LLDAP on Ubuntu 22.04 as the directory behind Authentik, Keycloak, Vaultwarden — systemd, TLS via nginx, bind credentials, schema bootstrap.

You’ve been asked to give Authentik (or Keycloak, or Vaultwarden) a real backing directory so account lifecycle isn’t trapped inside one product. The LLDAP README is short — single Rust binary, embedded SQLite, a web UI for groups — you wire it to Authentik over ldap://127.0.0.1:3890, the SSO works, you hand it over. Six months later, the LDAP port is exposed on 0.0.0.0:3890, the admin password is still the bootstrap value, every relying party talks to LDAP in plaintext because LDAPS was never configured, and the directory that anchors every user in the company is the easiest box on the network to enumerate.

What’s happening

An LLDAP deployment that is actually production-ready needs more than ./lldap run. The plaintext ldap:// listener has to bind to 127.0.0.1 only — anything joining the directory either lives on the same host or comes in through ldaps:// via nginx stream TLS termination. The web admin UI has to sit behind nginx terminating TLS on a real Let’s Encrypt cert. The bootstrap admin password and the bind credentials your relying parties use to query the directory have to be rotated off the defaults and stored in your secrets manager. The base DN and initial groups have to be set before the first relying party reads them — changing a base DN after applications are wired is a multi-day cleanup. SSH needs password auth disabled while preserving root key access. None of these are individually critical — skip them and the directory that anchors every other identity system becomes the weakest link.

How to verify

After install, the listeners on the host should be:

ss -lntp | grep -E ':(80|443|636|3890|17170)\b'
# 127.0.0.1:3890   lldap (LDAP plain)
# 127.0.0.1:17170  lldap (web admin HTTP)
# 0.0.0.0:80       nginx
# 0.0.0.0:443      nginx (admin UI)
# 0.0.0.0:636      nginx stream (LDAPS for off-host relying parties)

If :3890 shows on 0.0.0.0, LLDAP is broadcasting plaintext LDAP — fix ldap_host in the config. Confirm an anonymous bind on LDAPS:

ldapsearch -H ldaps://dir.example.com -x -b "dc=example,dc=com" -s base
# returns "namingContexts: dc=example,dc=com"

curl -fsS https://dir.example.com/ | head -5
# should return the LLDAP admin UI HTML

Then verify TLS:

echo | openssl s_client -servername dir.example.com -connect dir.example.com:636 2>/dev/null \
  | openssl x509 -noout -dates

If LDAPS fails to negotiate or the cert is near expiry, every relying party caching that LDAPS connection will start failing silently.

The fix

Save the script below as /root/setup-lldap-ubuntu22.sh, then run it. It runs the installer flow on a fresh Ubuntu 22.04 VM: base update, kernel tuning, file limits, UFW (SSH + HTTP + HTTPS + LDAPS only), SSH hardening, unattended-upgrades, the LLDAP release binary pinned to a version, an lldap system user, a configuration file with the LDAP listener bound to 127.0.0.1, random JWT secret, admin password and key seed written to /etc/lldap/lldap_config.toml (mode 640), a systemd unit with LimitNOFILE=64000, nginx serving the admin UI over Let’s Encrypt HTTPS, an nginx stream block exposing LDAPS on :636 passing through to the local :3890 listener, and a poll loop that verifies :3890 and :636 before declaring success.

#!/usr/bin/env bash
set -euo pipefail

### Ubuntu 22.04 LLDAP clean VM installer
### Keeps root SSH key login enabled
### Disables SSH password login
### Enables automatic security updates
### Installs and configures LLDAP + nginx + Let's Encrypt + LDAPS
### No local backups; assumes VM-level backup
### Reboot remains manual

if [[ "$(id -u)" -ne 0 ]]; then
  echo "Run as root."
  exit 1
fi

: "${LLDAP_DOMAIN:?Set LLDAP_DOMAIN=dir.example.com}"
: "${LLDAP_EMAIL:?Set LLDAP_EMAIL=ops@example.com for Let's Encrypt}"
: "${LLDAP_BASE_DN:?Set LLDAP_BASE_DN=dc=example,dc=com}"
LLDAP_VERSION="${LLDAP_VERSION:-v0.6.1}"
LLDAP_ADMIN_PASSWORD="${LLDAP_ADMIN_PASSWORD:-$(openssl rand -base64 24 | tr -d '\n=' | head -c 24)}"
LLDAP_JWT_SECRET="${LLDAP_JWT_SECRET:-$(openssl rand -hex 32)}"
LLDAP_KEY_SEED="${LLDAP_KEY_SEED:-$(openssl rand -hex 32)}"

echo
echo "========================================"
echo "LLDAP Ubuntu 22.04 Setup"
echo "========================================"
echo

echo "==> Updating base OS"
export DEBIAN_FRONTEND=noninteractive
apt-get update
apt-get -y upgrade

echo "==> Installing base packages"
apt-get -y install \
  vim curl wget ca-certificates gnupg2 \
  chrony fail2ban unattended-upgrades \
  ufw lsof tcpdump dnsutils tar gzip \
  iproute2 net-tools openssl jq ldap-utils \
  software-properties-common

echo "==> Enabling time sync"
systemctl enable --now chrony
timedatectl set-ntp true

echo "==> Applying kernel/network tuning"
cat > /etc/sysctl.d/99-lldap.conf <<'SYSCTL'
net.core.default_qdisc = fq
net.ipv4.tcp_congestion_control = bbr

net.core.somaxconn = 4096
net.core.netdev_max_backlog = 250000
net.ipv4.tcp_max_syn_backlog = 8192
net.ipv4.tcp_syncookies = 1
net.ipv4.tcp_fin_timeout = 15
net.ipv4.ip_local_port_range = 10240 65535

net.ipv4.conf.all.accept_redirects = 0
net.ipv4.conf.default.accept_redirects = 0
net.ipv6.conf.all.accept_redirects = 0
net.ipv6.conf.default.accept_redirects = 0

net.ipv4.conf.all.send_redirects = 0
net.ipv4.conf.default.send_redirects = 0

kernel.dmesg_restrict = 1
kernel.kptr_restrict = 2
fs.file-max = 2097152
SYSCTL

modprobe tcp_bbr || true
echo tcp_bbr > /etc/modules-load.d/bbr.conf
sysctl --system

echo "==> Setting file limits"
cat > /etc/security/limits.d/99-lldap.conf <<'LIMITS'
* soft nofile 64000
* hard nofile 64000
root soft nofile 64000
root hard nofile 64000
LIMITS

echo "==> Configuring UFW"
ufw --force reset
ufw default deny incoming
ufw default allow outgoing
ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw allow 636/tcp
ufw --force enable

echo "==> Hardening SSH while keeping root SSH key login enabled"
cp /etc/ssh/sshd_config /etc/ssh/sshd_config.bak.$(date +%F-%H%M%S)

set_sshd_option() {
  local key="$1"
  local value="$2"
  if grep -qE "^[#[:space:]]*${key}[[:space:]]+" /etc/ssh/sshd_config; then
    sed -i "s|^[#[:space:]]*${key}[[:space:]].*|${key} ${value}|" /etc/ssh/sshd_config
  else
    echo "${key} ${value}" >> /etc/ssh/sshd_config
  fi
}

set_sshd_option PermitRootLogin prohibit-password
set_sshd_option PasswordAuthentication no
set_sshd_option PubkeyAuthentication yes
set_sshd_option KbdInteractiveAuthentication no
set_sshd_option ChallengeResponseAuthentication no
set_sshd_option X11Forwarding no
set_sshd_option ClientAliveInterval 300
set_sshd_option ClientAliveCountMax 2
set_sshd_option MaxAuthTries 4

sshd -t
systemctl restart ssh

echo "==> Configuring fail2ban"
mkdir -p /etc/fail2ban/jail.d
cat > /etc/fail2ban/jail.d/sshd.local <<'FAIL2BAN'
[sshd]
enabled = true
port = ssh
backend = systemd
maxretry = 4
findtime = 10m
bantime = 1h
FAIL2BAN

systemctl enable --now fail2ban

echo "==> Configuring unattended-upgrades for security"
cat > /etc/apt/apt.conf.d/20auto-upgrades <<'AUTOUPG'
APT::Periodic::Update-Package-Lists "1";
APT::Periodic::Unattended-Upgrade "1";
APT::Periodic::AutocleanInterval "7";
AUTOUPG

echo "==> Creating lldap user"
if ! id -u lldap >/dev/null 2>&1; then
  useradd --system --home-dir /var/lib/lldap --shell /sbin/nologin lldap
fi

mkdir -p /opt/lldap /var/lib/lldap /etc/lldap /var/log/lldap

echo "==> Downloading LLDAP ${LLDAP_VERSION}"
cd /opt/lldap
if [[ ! -x /opt/lldap/lldap ]]; then
  wget -q "https://github.com/lldap/lldap/releases/download/${LLDAP_VERSION}/amd64-lldap-linux-static-musl.tar.gz" -O lldap.tar.gz
  tar -xzf lldap.tar.gz --strip-components=1
  rm -f lldap.tar.gz
fi

chmod +x /opt/lldap/lldap
chown -R lldap:lldap /opt/lldap /var/lib/lldap /var/log/lldap

echo "==> Writing LLDAP configuration"
cat > /etc/lldap/lldap_config.toml <<CONF
ldap_host = "127.0.0.1"
ldap_port = 3890

http_host = "127.0.0.1"
http_port = 17170
http_url = "https://${LLDAP_DOMAIN}"

ldap_base_dn = "${LLDAP_BASE_DN}"
ldap_user_dn = "admin"
ldap_user_email = "admin@${LLDAP_DOMAIN}"
ldap_user_pass = "${LLDAP_ADMIN_PASSWORD}"

jwt_secret = "${LLDAP_JWT_SECRET}"
key_seed = "${LLDAP_KEY_SEED}"

database_url = "sqlite:///var/lib/lldap/users.db?mode=rwc"
verbose = false

[smtp_options]
enable_password_reset = false
CONF

chown root:lldap /etc/lldap/lldap_config.toml
chmod 640 /etc/lldap/lldap_config.toml

echo "==> Writing systemd unit"
cat > /etc/systemd/system/lldap.service <<'UNIT'
[Unit]
Description=LLDAP
After=network.target

[Service]
Type=simple
User=lldap
Group=lldap
Environment=LLDAP_CONFIG_FILE=/etc/lldap/lldap_config.toml
ExecStart=/opt/lldap/lldap run
WorkingDirectory=/opt/lldap
Restart=on-failure
RestartSec=10
LimitNOFILE=64000

[Install]
WantedBy=multi-user.target
UNIT

systemctl daemon-reload
systemctl enable --now lldap

echo "==> Waiting for LLDAP on 127.0.0.1:3890 and 127.0.0.1:17170"
for i in {1..60}; do
  if ss -lntp | grep -q '127.0.0.1:3890' && ss -lntp | grep -q '127.0.0.1:17170'; then
    break
  fi
  sleep 2
done

if ! ss -lntp | grep -q '127.0.0.1:3890'; then
  echo "LLDAP failed to listen on 127.0.0.1:3890"
  journalctl -u lldap -n 200 --no-pager || true
  exit 1
fi

echo "==> Installing nginx and certbot"
apt-get -y install nginx libnginx-mod-stream certbot python3-certbot-nginx

cat > /etc/nginx/sites-available/lldap <<NGINX
server {
    listen 80;
    listen [::]:80;
    server_name ${LLDAP_DOMAIN};
    return 301 https://\$host\$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name ${LLDAP_DOMAIN};

    client_max_body_size 10M;

    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    add_header X-Content-Type-Options nosniff always;
    add_header X-Frame-Options SAMEORIGIN always;
    add_header Referrer-Policy strict-origin-when-cross-origin always;

    location / {
        proxy_set_header Host \$host;
        proxy_set_header X-Real-IP \$remote_addr;
        proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto \$scheme;
        proxy_http_version 1.1;
        proxy_pass http://127.0.0.1:17170;
    }
}
NGINX

ln -sf /etc/nginx/sites-available/lldap /etc/nginx/sites-enabled/lldap
rm -f /etc/nginx/sites-enabled/default

nginx -t
systemctl enable --now nginx
systemctl reload nginx

echo "==> Requesting Let's Encrypt certificate for admin UI"
certbot --nginx --non-interactive --agree-tos \
  -m "${LLDAP_EMAIL}" -d "${LLDAP_DOMAIN}" --redirect

systemctl enable --now certbot.timer

echo "==> Configuring nginx stream for LDAPS on :636"
mkdir -p /etc/nginx/streams-available /etc/nginx/streams-enabled

cat > /etc/nginx/streams-available/ldaps <<STREAM
upstream lldap_ldap {
    server 127.0.0.1:3890;
}

server {
    listen 636 ssl;
    listen [::]:636 ssl;
    ssl_certificate     /etc/letsencrypt/live/${LLDAP_DOMAIN}/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/${LLDAP_DOMAIN}/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
    proxy_pass          lldap_ldap;
}
STREAM

ln -sf /etc/nginx/streams-available/ldaps /etc/nginx/streams-enabled/ldaps

if ! grep -q 'streams-enabled' /etc/nginx/nginx.conf; then
  cat >> /etc/nginx/nginx.conf <<'STREAMCONF'

stream {
    include /etc/nginx/streams-enabled/*;
}
STREAMCONF
fi

nginx -t
systemctl reload nginx

echo "==> Waiting for LDAPS on :636"
for i in {1..30}; do
  if ss -lntp | grep -q ':636'; then
    break
  fi
  sleep 1
done

echo "==> Final package update"
apt-get -y upgrade

echo
echo "========================================"
echo "DONE"
echo "========================================"
echo
echo "Kernel:"
uname -r

echo
echo "SSH effective settings:"
sshd -T | grep -E '^(permitrootlogin|passwordauthentication|pubkeyauthentication) ' || true

echo
echo "Listeners:"
ss -lntp | grep -E ':(80|443|636|3890|17170)\b' || true

echo
echo "Services:"
systemctl is-active lldap nginx fail2ban chrony || true

echo
echo "LDAPS reachability test:"
ldapsearch -H "ldaps://${LLDAP_DOMAIN}" -x -b "${LLDAP_BASE_DN}" -s base 2>&1 | grep -E '^(namingContexts|result)' || true

echo
echo "Admin UI:"
echo "https://${LLDAP_DOMAIN}/"

echo
echo "Admin login:"
echo "  Username: admin"
echo "  Password: ${LLDAP_ADMIN_PASSWORD}"

echo
echo "Bind DN for Authentik/Keycloak/Vaultwarden:"
echo "  uid=admin,ou=people,${LLDAP_BASE_DN}"

echo
echo "Final step:"
echo "Sign in to the admin UI, create per-app groups (admins, users, vaultwarden_users, etc.), then in each relying party configure LDAP backend pointing at ldaps://${LLDAP_DOMAIN}:636. Rotate the admin password from the wizard, store it in your secrets manager."

Make it executable and run it:

chmod 700 /root/setup-lldap-ubuntu22.sh
LLDAP_DOMAIN=dir.example.com LLDAP_EMAIL=ops@example.com LLDAP_BASE_DN="dc=example,dc=com" \
  /root/setup-lldap-ubuntu22.sh

The admin password is printed at the end — record it in your secrets manager. Sign in at https://dir.example.com/, change the admin password, create the groups you actually need before any relying party connects (admins, users, plus per-app groups like vaultwarden_users or grafana_admins), and add yourself to admins. Then in Authentik, Keycloak, or Vaultwarden, configure the LDAP backend pointing at ldaps://dir.example.com:636 with bind DN uid=admin,ou=people,dc=example,dc=com. Host-level backups are not configured here; /var/lib/lldap/users.db and /etc/lldap/lldap_config.toml should be covered by your VM snapshot policy — losing the key_seed costs you the directory.

When the directory anchoring every other identity system has to stay correct across LDAPS rotations, schema changes, and an on-call escalation at 3am, that’s part of the Cloud compute service under our managed plan — or book a quick infrastructure review.