No description
  • Python 71.3%
  • Shell 13.9%
  • HTML 13.8%
  • JavaScript 0.8%
  • CSS 0.2%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Lyra 84ddd2d703
All checks were successful
Tests / Scope (push) Successful in 1s
Tests / pytest (newest CPython, warning only) (push) Has been skipped
Tests / shellcheck (install.sh, update.sh, bootstrap-ldap.sh, webupdate.sh, get_ldap-webgui.sh, setup.sh, config-backup.sh, certtool.sh, accesstool.sh) (push) Successful in 34s
Tests / pytest (Python 3.13) (push) Successful in 22m34s
Tests / pytest (Python 3.14) (push) Successful in 23m59s
Tests / Publish release (push) Successful in 3s
release: v1.36.1
2026-11-13 21:10:39 +01:00
.forgejo/workflows release: v1.32.2 2026-11-08 01:42:40 +01:00
app release: v1.36.1 2026-11-13 21:10:39 +01:00
docs release: v1.36.0 2026-11-12 21:02:53 +01:00
nginx release: v1.34.0 2026-11-09 19:43:42 +01:00
scripts release: v1.20.1 2026-10-30 23:57:08 +01:00
systemd release: v1.32.2 2026-11-08 01:42:40 +01:00
tests release: v1.36.1 2026-11-13 21:10:39 +01:00
.gitignore release: v1.25.2 2026-11-02 02:05:59 +01:00
accesstool.sh release: v1.36.1 2026-11-13 21:10:39 +01:00
bootstrap-ldap.sh release: v1.36.1 2026-11-13 21:10:39 +01:00
certtool.sh release: v1.36.1 2026-11-13 21:10:39 +01:00
CHANGELOG.md release: v1.36.1 2026-11-13 21:10:39 +01:00
config-backup.sh release: v1.36.1 2026-11-13 21:10:39 +01:00
config.yaml.example release: v1.36.0 2026-11-12 21:02:53 +01:00
debian-packages.txt release: v1.22.0 2026-11-01 11:53:54 +01:00
get_ldap-webgui.sh release: v1.36.1 2026-11-13 21:10:39 +01:00
gunicorn.conf.py release: v1.20.1 2026-10-30 23:57:08 +01:00
install.sh release: v1.36.1 2026-11-13 21:10:39 +01:00
LICENSE release: v1.25.4 2026-11-02 14:13:30 +01:00
manage.py release: v1.35.0 2026-11-12 00:20:18 +01:00
pytest.ini release: v1.20.1 2026-10-30 23:57:08 +01:00
README.md release: v1.35.0 2026-11-12 00:20:18 +01:00
requirements-dev.txt release: v1.22.1 2026-11-01 13:01:28 +01:00
requirements.txt release: v1.22.1 2026-11-01 13:01:28 +01:00
run.py release: v1.20.1 2026-10-30 23:57:08 +01:00
setup.sh release: v1.36.1 2026-11-13 21:10:39 +01:00
update.sh release: v1.36.1 2026-11-13 21:10:39 +01:00
VERSION release: v1.36.1 2026-11-13 21:10:39 +01:00
webupdate.sh release: v1.36.1 2026-11-13 21:10:39 +01:00

LDAP WebGUI

A self-hosted web interface for managing an OpenLDAP directory. The initial setup takes one LDIF, adapted once from a shipped template (or none, if bootstrap-ldap.sh builds the directory) — after that, no LDIF by hand.

Designed for system administrators who need to manage users, groups, sudo rules and access rights on Linux systems backed by OpenLDAP. The interface is clean, clearly structured, and documented well enough that someone with basic Linux knowledge can operate it confidently from day one.

Current version: see VERSION | Platform: Debian 13 (Trixie) | Python: 3.13+


Table of Contents


Features

Category What you can do
Users Create, view, edit, delete users — individually or via CSV bulk import
Groups Create posixGroups, add/remove members, delete groups
Sudo Rules Manage fine-grained sudoRole entries (per-user, per-host, per-command)
Machines Per host, read-only: who may log in over SSH and who has sudo there, derived from sudoHost values and login-<host> groups, with the AllowGroups line to copy into sshd_config; an optional all-hosts group, spelling and wildcard warnings on the sudo form (docs/machines.md)
Sudo Access Toggle quick sudo membership (posixGroup toggle) per user
SSH Keys Store users' SSH public keys in the directory (sshPublicKey) for SSSD's AuthorizedKeysCommand
Service Accounts POSIX accounts for programs and bots: own OU, own uidNumber range, key-only, never able to sign in to the WebGUI
Passwords Reset any user's password; configurable strength policy
2FA / TOTP Per-admin TOTP setup with QR code and 10 backup codes
Settings Edit 13 non-sensitive settings live from the browser (no restart needed)
CSV Import Bulk-create or bulk-update up to 500 users from a CSV file with preview + validation
CSV Export Export all users to CSV (without passwords) for reference or re-import
Security CSRF protection, per-IP rate limiting, session expiry, security log
Security Log Read the security log in the browser — paged, filterable by event and account, raw download
Monitoring A read-only JSON status report behind a token at /health, and a shipped Zabbix 7.0 template: LDAP bind, certificate expiry, updates available and failed, lockouts, config backup (docs/monitoring.md)
Docs The operator documentation, rendered in the browser under /docs/ — both roles, nothing editable
Directory bootstrap bootstrap-ldap.sh builds the OpenLDAP directory on a bare Debian 13 host — slapd, schemas, tree, ACLs, TLS, first admin — and verifies it against the running server

Requirements

Requirement Notes
Debian 13 (Trixie) or newer The only tested platform
OpenLDAP (slapd) On the same host or reachable over the network — bootstrap-ldap.sh builds it on a bare Debian 13 host
Python 3.13+ Installed automatically by install.sh if not present
Root / sudo access Required for the installer only
Modern browser Chrome 111+, Safari 16.4+, Firefox 128+ — since v1.7.0 the stylesheet is built with Tailwind v4, which uses @property and color-mix(). Older browsers do not degrade gracefully, they render close to unstyled
Directory size Every read of an area (users, groups, sudo rules, hosts) is paged and complete — lists, search, exports, the Machines page and automatic ID assignment never see a partial area. slapd still caps a whole paged search at its size limit (500 entries by default), so above that the bind account needs one olcLimits line (size.prtotal=unlimited): bootstrap-ldap.sh sets it, update.sh offers it on the directory host (--ldap-limits), and the error names it otherwise — docs/ldap-acl-setup.md, Size limit for the bind account
Nginx 1.25.1+ Installed automatically; used as a TLS-terminating reverse proxy. The shipped vhost uses the http2 on; directive, which older Nginx does not know — Ubuntu 24.04 (Nginx 1.24) needs --no-nginx and a hand-written vhost. Since v1.33.0 the vhost is the application's file: install.sh and every update render it from the template and /etc/ldap-webgui/vhost.env (host names, certificate paths, listen addresses) — local edits are lost; a --no-nginx host without a vhost is never touched (docs/upgrade-1.33.md)

Quick Start

On a bare Debian 13 host, as root (sudo -i first):

bash -c "$(curl -fsSL https://git.dynnet.de/DravenTec/ldap-webgui/raw/branch/main/get_ldap-webgui.sh)"
# or, where curl is missing (a minimal Debian 13 has wget):
bash -c "$(wget -qO- https://git.dynnet.de/DravenTec/ldap-webgui/raw/branch/main/get_ldap-webgui.sh)"

get_ldap-webgui.sh installs git and curl, clones the newest release to /usr/local/src/ldap-webgui and starts its setup.sh. The setup asks everything first — a new directory on this host or an existing one (checked read-only before anything is written) — shows a summary, and only acts after Proceed? [y/N]. One question is from where the WebGUI is used: nginx admits those hosts or networks (and loopback) and nothing else — see Operating recommendation. At the end the WebGUI runs, the first admin can sign in, and, if you said yes, Settings → Software Update installs later releases. Its log is /var/log/ldap-webgui-setup.log.

bash -c "$(…)" downloads the whole script before anything runs, and the questions still reach your terminal. To read it first:

curl -fsSLO https://git.dynnet.de/DravenTec/ldap-webgui/raw/branch/main/get_ldap-webgui.sh
less get_ldap-webgui.sh
sudo bash get_ldap-webgui.sh

No access to PyPI (an isolated VLAN): the setup notices before it changes anything, prints the pip download command to stage the Python packages on a machine that has access, and how to call it again with --wheelhouse DIR (docs/isolated-hosts.md). Unattended: --answers FILE (KEY=value, see setup.sh --help). Host firewall: none of the scripts touch it — docs/firewall-ufw.md shows which ports to open for whom with ufw.

By hand

# 1. Clone the repository (root-owned, outside the install directory;
#    /usr/local/src itself must be root-owned and not writable by others)
sudo git clone https://git.dynnet.de/DravenTec/ldap-webgui.git /usr/local/src/ldap-webgui
cd /usr/local/src/ldap-webgui

# 2. Build the directory (bare Debian 13 host, run on the directory host)
sudo bash bootstrap-ldap.sh --domain example.com --org "Example Ltd" \
    --admin-uid jdoe --tls self-signed

# 3. Run the installer (requires root). --allow names the admin hosts or
#    networks nginx admits; without it the WebGUI answers on loopback only
sudo bash install.sh --allow 192.168.10.0/24

# 4. Put the LDAP values into config.yaml (same host as the directory)
sudo bash bootstrap-ldap.sh --write-config /opt/ldap-webgui/config.yaml

# 5. Start the service
sudo systemctl start ldap-webgui

# 6. Open the WebGUI from an allowed host and sign in as jdoe
#    https://<your-server>/

Keep the clone. It is the source install.sh installs from, and install.sh records it as the one sudo ldap-webgui-update updates from — see Updating.

Existing directory? Skip step 2 — the bootstrap refuses a directory that holds data. docs/initial-setup.md (Parts 1–2) is the manual path, and Part 0 explains the bootstrap's options (--tls self-signed | existing | none, --dry-run).

Installer options

sudo bash install.sh [OPTIONS]

  --install-dir DIR   Application directory  (default: /opt/ldap-webgui)
  --log-dir DIR       Log directory          (default: /var/log/ldap-webgui)
  --no-nginx          Skip Nginx configuration
  --server-name NAMES Host names nginx answers to, space-separated in one
                      argument; "_" = any (default on a new host: hostname -f
                      and "_"). Kept in /etc/ldap-webgui/vhost.env
  --listen ADDRS      IP addresses nginx listens on ("" = all, the default);
                      127.0.0.1 is always added. Kept in vhost.env
  --hsts MAX-AGE      Send HSTS, max-age 300, 86400 or 31536000 — refused
                      unless the certificate verifies for every server name
                      (docs/upgrade-1.33.md, section 9). Kept in vhost.env
  --no-hsts           Stop sending it (browsers keep it until max-age ends)
  --tls-cert FILE --tls-key FILE
                      Use an existing certificate (+ chain) and key instead
                      of generating one — checked, then copied to the paths
                      vhost.env names
  --allow LIST        Hosts/networks that may reach the WebGUI, comma-separated
                      (IPv4/IPv6, CIDR); loopback is always added. Rewrites
                      /etc/nginx/ldap-webgui-access.conf. Without it an existing
                      file is kept, a missing one becomes loopback only.
                      "any" (unrestricted) only together with --confirm-any
  --allow-monitoring LIST
                      Monitoring hosts that may reach /health only
                      (/etc/nginx/ldap-webgui-monitoring.conf; "" clears it)
  --confirm-any       Confirms --allow any: reachable from every network
                      this host is in. Refused without it.
  --no-ssl            Skip self-signed certificate generation
  --dev               Development mode (debug=true, localhost only)

Configuration

The main configuration file is /opt/ldap-webgui/config.yaml. It is never overwritten by a re-run of install.sh.

A fully annotated example is at config.yaml.example.

Minimum required settings

ldap:
  host: "ldap.example.com"          # Hostname, not an IP (TLS SAN check)
  port: 636                          # 636 LDAPS (recommended) · 389 STARTTLS
  base_dn: "dc=example,dc=com"      # Your LDAP base DN
  bind_dn: "cn=ldapwebgui,ou=service-accounts,dc=example,dc=com"
  bind_password: "your-service-account-password"
  user_search_base:  "ou=people,dc=example,dc=com"
  group_search_base: "ou=groups,dc=example,dc=com"
  sudoers_base:      "ou=sudoers,dc=example,dc=com"   # optional
  tls:
    verify:  true
    ca_cert: "/etc/ssl/certs/my-internal-ca.crt"   # empty = system trust store

auth:
  admin_group_dn: "cn=ldap-admins,ou=groups,dc=example,dc=com"
  # Optional (v1.5.0): members may view everything and change nothing.
  # Omit or leave empty to disable the role.
  readonly_group_dn: "cn=ldap-readers,ou=groups,dc=example,dc=com"
  secret_key: "auto-generated-64-char-hex"   # set by install.sh

password_policy:
  min_length: 8
  require_uppercase: true
  require_digit: true
  require_special: true

Settings you can edit live (no restart)

Log in → Settings → Editable Settings → change values → Save Changes.

Setting Key Default
Application title app.title LDAP WebGUI
Log level app.log_level INFO
Timezone app.timezone UTC
Session timeout (seconds) auth.session_timeout 3600
Max login attempts auth.max_login_attempts 5
Lockout duration (seconds) auth.lockout_duration 300
Sudo group name auth.sudo_group sudo
Min password length password_policy.min_length 8
Require uppercase password_policy.require_uppercase true
Require digit password_policy.require_digit true
Require special char password_policy.require_special true
Minimum UID number id_ranges.uid_number_min 10000
Minimum GID number id_ranges.gid_number_min 5000

First Login

The WebGUI authenticates against your LDAP directory — so the first admin account must be created manually before you can log in.

A step-by-step guide is included:

/opt/ldap-webgui/docs/initial-setup.md

In brief:

  1. Edit docs/initial-admin.ldif — replace all dc=example,dc=com placeholders with your actual base DN, generate password hashes with slappasswd -h {SSHA}, fill in the admin's name and username.
  2. Apply the LDIF: ldapadd -x -D "cn=admin,dc=example,dc=com" -W -f initial-admin.ldif
  3. Navigate to https://<your-server>/ and sign in.

Updating

Check for new releases directly in the WebGUI: Settings → Software Update → Check for Updates.

The check is off until configured — it has no built-in endpoint, because a check pointed at a remote that does not publish your releases reports "up to date" for a version that is behind. Set app.update_check.enabled, api_base and repo in config.yaml; for a private repository add a read-only API token as LDAP_WEBGUI_UPDATE_TOKEN to /etc/ldap-webgui/environment. See docs/settings.md for details.

Two places, two roles — do not mix them up:

Place Role
/usr/local/src/ldap-webgui The git clone (sudo git clone, root-owned). Source for install.sh and update.sh. Keep it. Every directory above it must be root-owned and writable by nobody else — otherwise ldap-webgui-update refuses, because whoever can write there can swap the clone root updates from. Check with stat -c '%n %U:%G %a' /usr/local/src; fix with chown root:root and chmod go-w.
/opt/ldap-webgui The installation: venv/, config.yaml. Owned by root (only config.yaml belongs to ldapwebgui), written only by install.sh / update.sh; not a git clone, and it holds no update.sh since v1.17.0.
/var/lib/ldap-webgui Runtime state the service writes: sessions, the login and 2FA lockout stores.
/usr/local/sbin/ldap-webgui-update The update command (v1.17.0), written by install.sh / update.sh. It runs update.sh from the clone recorded in /etc/ldap-webgui/update-clone.

Standard update (server has git access)

If the server can reach the git remote (deploy key / token for this repository), from any directory:

sudo ldap-webgui-update --preflight # check only: source, version, dependencies, disk, health
sudo ldap-webgui-update --dry-run   # print the plan without checking
sudo ldap-webgui-update             # perform the update

The command runs update.sh from the clone install.sh recorded (git mode only; it takes the same options as update.sh). Before that it checks that root owns the clone, every file in it and every directory above it, and that nobody else can write to any of them — root is about to run that code. It refuses otherwise and says which path failed.

Coming from v1.16.x or older, the command does not exist yet, and the update.sh that is running would be the old one (bash has read it before it fetches the new one). Pull first, so the new script runs once and installs the command:

cd /usr/local/src/ldap-webgui
sudo git pull --ff-only
sudo bash update.sh

What update.sh does — the same in every mode, no git pull needed:

  1. Check, change nothing: fetch the source (git mode: git fetch and stage origin/<branch>), compare versions, check that every dependency can be installed as a wheel with this host's pip configuration, disk space, and that the running service is healthy
  2. Snapshot the installed files, the venv and config.yaml to /var/backups/ldap-webgui/<timestamp>/ (the newest three are kept)
  3. stop the service, pip (wheels only), vendor assets, config migration (adds new keys, never changes existing values), copy the application files, start the service
  4. health check — the service must answer on the new version; any failure after step 2 restores the snapshot and starts the old version again
  5. the nginx vhost (v1.33.0): rendered from the new release's template and /etc/ldap-webgui/vhost.env, checked in step 1, replaced now, nginx -t, reload, confirmed served — on failure the previous vhost goes back and the new version keeps running (a manual step). A vhost from before 1.33 that was edited by hand is left alone until --replace-vhost. After editing vhost.env: sudo ldap-webgui-update --vhost-only. docs/upgrade-1.33.md
  6. git mode: fast-forward the clone

The same version as installed is a no-op (exit 0, no restart); --reinstall applies it anyway. An older version needs --allow-downgrade. Git mode follows the branch head, unreleased commits included. To install exactly one release, use --from-release or archive mode below.

Exit Meaning
0 Updated, nothing to do, or preflight passed
1 Failed before any change — the installation is untouched
2 Failed, rolled back, the previous version is running
3 Rollback failed — fix by hand (the snapshot is in /var/backups/ldap-webgui)
64 Wrong options
75 Another update is running

--status-file PATH writes the progress as JSON lines for scripts. Details — phases, checks, snapshot, status format — are documented in the comments of update.sh itself.

Hosts without PyPI access keep a wheelhouse in /etc/pip.conf (no-index + find-links) or open a firewall rule for the update window — docs/isolated-hosts.md covers both, and what the host needs to reach when.

Update to the newest release (--from-release)

sudo ldap-webgui-update --from-release --preflight
sudo ldap-webgui-update --from-release

Installs the newest published release (no draft, no prerelease) of the repository configured in app.update_check — the same api_base, repo and LDAP_WEBGUI_UPDATE_TOKEN in /etc/ldap-webgui/environment as Settings → Check for Updates. Forgejo/Gitea only; an api_base on GitHub is refused. No git credentials on the server needed, only HTTPS to the forge.

The clone must be root-owned (sudo git clone) and not group- or world-writable: ldap-webgui-update refuses anything else, and git refuses to work in a repository owned by someone else ("dubious ownership") when update.sh runs as root. It must also not sit below a 0700 home directory — the config migration runs as the service user and reads config.yaml.example from it.

Update WITHOUT git access on the server (--archive)

Use this when the server has no git credentials for the repository (common for private repos) or no direct access to the forge at all.

Step 1 — Get the release archive (on your workstation):

Download the source archive of the desired release from the forge (Releases → Source code (tar.gz)), or via CLI:

# Public repo:
curl -L -o ldap-webgui-1.3.0.tar.gz \
  https://git.dynnet.de/DravenTec/ldap-webgui/archive/v1.3.0.tar.gz

# Private repo (needs an access token with read access to the repository):
curl -L -H "Authorization: Bearer <YOUR_TOKEN>" \
  -o ldap-webgui-1.3.0.tar.gz \
  https://git.dynnet.de/api/v1/repos/DravenTec/ldap-webgui/archive/v1.3.0.tar.gz

Step 2 — Transfer it to the server:

scp ldap-webgui-1.3.0.tar.gz admin@your-server:/tmp/

Step 3 — Extract it and run the updater from the extracted tree:

mkdir /tmp/ldap-webgui-1.3.0
tar xzf /tmp/ldap-webgui-1.3.0.tar.gz -C /tmp/ldap-webgui-1.3.0 --strip-components=1
sudo bash /tmp/ldap-webgui-1.3.0/update.sh --archive /tmp/ldap-webgui-1.3.0.tar.gz

An archive install has no clone, so sudo ldap-webgui-update only prints this command. Since v1.17.0 there is no update.sh in /opt/ldap-webgui; an update removes the copy older versions left there.

Archive mode runs the same workflow as above from the archive instead of git — checks, snapshot, update, health check on the new version, rollback on any failure. --preflight and --dry-run work here too.

Fully manual update (fallback)

If you prefer doing it by hand, these steps mirror what update.sh --archive does:

# Extract
cd /tmp
tar xzf ldap-webgui-1.3.0.tar.gz
cd DravenTec-ldap-webgui-*/ 2>/dev/null || cd ldap-webgui-*/

# 1. Back up the current config (it is NEVER overwritten by the copy
#    below — this backup is just belt and braces)
sudo cp /opt/ldap-webgui/config.yaml \
        /opt/ldap-webgui/config.yaml.pre-update-$(date +%Y%m%d%H%M%S)

# 2. Copy the application files (config.yaml is not part of this list)
sudo cp -r app/ docs/ nginx/ requirements.txt debian-packages.txt \
           gunicorn.conf.py run.py manage.py \
           VERSION config.yaml.example \
           /opt/ldap-webgui/

# 3. Ownership: root owns everything but config.yaml (v1.17.0)
sudo chown -R -h root:ldapwebgui /opt/ldap-webgui
sudo chown -R -h root:root /opt/ldap-webgui/venv
sudo chmod -R a+rX,go-w /opt/ldap-webgui/venv
sudo chown -h ldapwebgui:ldapwebgui /opt/ldap-webgui/config.yaml
sudo find -P /opt/ldap-webgui -path /opt/ldap-webgui/venv -prune -o \
     -type f -name "*.py" -exec chmod 640 {} +

# 4. Update Python dependencies (as root — the venv is root's)
sudo /opt/ldap-webgui/venv/bin/pip install --root-user-action=ignore \
     --no-cache-dir --only-binary=:all: -r /opt/ldap-webgui/requirements.txt

# 5. Restart and verify
sudo systemctl restart ldap-webgui
curl -sk https://localhost/health

# 6. The nginx vhost (v1.33.0): render, check, replace, reload, confirm
sudo bash update.sh --vhost-only

Afterwards — check for new config keys (archive mode does this automatically; manually it looks like this):

New releases may introduce new config.yaml keys. Compare your config with the shipped example and add anything that is missing (defaults are documented inline):

diff <(grep -Ev '^\s*(#|$)' /opt/ldap-webgui/config.yaml.example) \
     <(grep -Ev '^\s*(#|$)' /opt/ldap-webgui/config.yaml) | less

Fully offline servers (no internet at all): the Python packages come from a wheelhouse, the JavaScript ships with the release — docs/isolated-hosts.md has the commands.

Rollback: keep the previous archive around. Rolling back is the same procedure with the old archive, plus restoring the config backup from step 1 if needed.


Feature Overview

User Management

Navigate to Users in the top navigation bar.

Create a user — click New User, fill in the form, submit. Required fields: username (uid), first name, last name, password. The UID number is assigned automatically.

Edit a user — click the username in the list, modify fields, click the yellow Save Changes button (turns green on success).

Reset a password — on the user detail page, expand Reset Password, enter the new password twice, submit.

Create a service account (v1.12.0) — click New Service Account. An account for a program or a bot: no first or last name, a required description, an optional password (none by default — key-only) and an optional first SSH key. It lands in ldap.service_account_base (default ou=services,<user_search_base>), is numbered from id_ranges.service_uid_number_min–_max (default 50000–59999), shows a service badge in the list, and can never sign in to the WebGUI — whatever group it is in. The list filters by type. docs/service-accounts.md has the OU setup, the ranges, the ldapmodrdn move for an existing account and how to keep service accounts off hosts meant for people.

Delete a user — on the user detail page, expand Danger Zone, type the username to confirm, click Delete.

Sudo access — on the user detail page, use the Sudo Access toggle to grant or revoke membership in the configured sudo posixGroup.

CSV Bulk Import

  1. Go to Users → Import CSV

  2. Download the template or prepare a CSV with these columns:

    Column Required Notes
    uid ✓ New accounts: lower-case letters, digits, ., _, -, starting with a letter or _ (max 32)
    givenName ✓ First name
    sn ✓ Last name
    password ✓ Must meet the configured password policy
    mail — Optional email address
    gidNumber — Primary group ID (default: 1000)
    loginShell — Absolute path (default: /bin/bash)
    homeDirectory — Absolute path (default: /home/<uid>)
    title — Job title
    telephoneNumber — Phone number
    description — Free text

    The four required columns are required to create an account. In Create and update existing users mode (step 3) only uid is a required column, and the other three are required of the rows that turn out to create a new account.

  3. Pick what should happen to rows whose uid already exists:

    • Create new users only (default) — such a row is reported and skipped, and nothing on the existing account is touched.
    • Create and update existing users — such a row is written to the existing account, with only the columns your file has and filled in. A column the file does not carry, or leaves empty, is left untouched; the defaults in the table above apply to new accounts only. A filled password cell resets that user's password.
  4. Upload the CSV → review the preview table (passwords are never shown). In update mode it says per row whether it will create or update.

  5. If all rows are valid, click Commit Import

  6. The result page shows how many users were created, updated, left unchanged, skipped (already exist) or failed

Limits: max 500 rows per import, max 512 KB file size.

Clearing an attribute from a CSV is not possible — an empty cell means "leave this alone", not "delete this". Use the user detail page to clear a field.


SSH Public Keys

On the user detail page, the SSH Public Keys panel holds the account's keys, one per line as in authorized_keys. Hosts running SSSD hand them to sshd through sss_ssh_authorizedkeys, so no authorized_keys file has to be copied around. A malformed key is refused and nothing is saved; the user list's SSH Key column shows who has one. The CSV import takes one key per cell and adds it; the export does not carry keys.

Prerequisite: the openssh-lpk schema must be loaded into slapd — Debian does not ship it. docs/ssh-keys.md covers the schema (the LDIF is docs/openssh-lpk.ldif), the ACL and the SSSD/sshd side.


Group Management

Navigate to Groups.

  • Create — click New Group, enter name and optional description. The GID number is assigned automatically.
  • Add member — on the group detail page, type a UID and click Add.
  • Remove member — click the ✕ button next to a member's name.
  • Delete — expand Danger Zone on the group detail page.

Sudo Rules

Navigate to Sudo Rules.

This section manages sudoRole LDAP objects — the server-side sudo policy stored in LDAP and read by sudo via nsswitch.conf.

Prerequisite: The sudoers LDAP schema must be loaded into slapd before any sudoRole entries can be created. See docs/sudoers-schema.md for a step-by-step guide.

Create a rule — click New Sudo Rule, fill in:

Field Example Meaning
Rule name developers-apt Unique identifier (CN)
sudoUser %developers Who the rule applies to (ALL, %group, uid)
sudoHost ALL Which hosts
sudoCommand /usr/bin/apt Which commands
sudoRunAsUser root Optional: run as this user
sudoOption !authenticate Optional: e.g. NOPASSWD:
sudoOrder 10 Optional: rule ordering integer

Edit a rule — click the rule name, modify fields, save. Delete — expand Danger Zone on the detail page.


Two-Factor Authentication

Each admin account can independently enable TOTP-based 2FA.

  1. Log in → click your username in the top-right corner
  2. Click Manage Two-Factor Authentication
  3. Scan the QR code with any TOTP app (Google Authenticator, Aegis, etc.)
  4. Enter the 6-digit code to confirm setup
  5. Save the 10 one-time backup codes in a safe place

Once enabled, every login will require the 6-digit code after the password.

Backup codes can be used instead of the TOTP code (each code is single-use).

To disable 2FA, click Disable Two-Factor Authentication and confirm with your current LDAP password.

Failed-code lockout & emergency recovery

Failed TOTP codes are counted per account (independent of IP). Every 5 consecutive failures escalate the lockout:

Failures Lockout
5 1 minute
10 5 minutes
15 15 minutes
20 Permanent — admin intervention required

If an admin account is locked out (or the authenticator device is lost), recovery is always possible from the server console. Run the tool as the service user, not as root — it writes the lockout stores the service reads, and works from any directory:

# Clear the 2FA lockout for an account
sudo -u ldapwebgui /opt/ldap-webgui/venv/bin/python /opt/ldap-webgui/manage.py unlock-totp <uid>

# Remove 2FA from an account entirely (lost authenticator)
sudo -u ldapwebgui /opt/ldap-webgui/venv/bin/python /opt/ldap-webgui/manage.py disable-2fa <uid>

# Reset an account's password (prompted, policy-checked)
sudo -u ldapwebgui /opt/ldap-webgui/venv/bin/python /opt/ldap-webgui/manage.py set-password <uid>

# Create a brand-new admin account (e.g. the last admin is locked out)
sudo -u ldapwebgui /opt/ldap-webgui/venv/bin/python /opt/ldap-webgui/manage.py create-admin \
    --uid newadmin --given-name Jane --sn Doe

# Clear the login rate-limit lockout for an IP
sudo -u ldapwebgui /opt/ldap-webgui/venv/bin/python /opt/ldap-webgui/manage.py unlock-ip <ip>

# Show all active lockouts (accounts with 2FA lockout, IPs with login lockout)
sudo -u ldapwebgui /opt/ldap-webgui/venv/bin/python /opt/ldap-webgui/manage.py list-locks

Full guide: docs/2fa-setup.md


Settings

Navigate to Settings.

The page is split into two sections:

LDAP Info (read-only) — live connection details and directory statistics. Use Test Connection to verify LDAP connectivity without leaving the page.

Editable Settings — the 13 settings listed in the Configuration section above. The Save Changes button shows the current state:

Colour Meaning
🟢 Green All changes saved
🟡 Yellow (pulsing) Unsaved changes exist
🔵 Blue (disabled) Save in progress

Changes are written to config.yaml with comments preserved. The application reloads the changed values without a service restart.


Security Model

Control Implementation
Authentication LDAP bind — password never stored by the WebGUI
Authorisation Membership check in auth.admin_group_dn on every login; optional read-only role via auth.readonly_group_dn
Write protection @write_required on every mutating route — a read-only session gets 403, not a hidden button. A test enumerates the URL map so a new route cannot skip the check
CSRF Per-session 256-bit token, constant-time comparison, HTTP header or form field
Rate limiting Per-IP failure counter with configurable lockout (file-backed, shared across workers, survives restarts)
2FA brute-force protection Per-account escalating lockout on failed TOTP codes: 1 min → 5 min → 15 min → permanent (console unlock via manage.py)
Client IP detection Only the proxy-set X-Real-IP header is trusted; the client-spoofable X-Forwarded-For is ignored
Session Flask-Session filesystem backend; SESSION_COOKIE_HTTPONLY, SESSION_COOKIE_SECURE, SameSite=Lax
Session fixation Session ID rotated at every privilege boundary (login, TOTP pending, 2FA verify); old server-side record deleted
Session expiry Configurable timeout; explicit server-side check on every request
LDAP injection DN components escaped per RFC 4514; filter values per RFC 4515
Password logging Passwords are never written to any log file
Sensitive routes All non-login routes protected by @login_required
2FA TOTP (RFC 6238) + 10 single-use backup codes (SHA-256 hashes stored in LDAP description); the TOTP secret there is encoded, not encrypted — since v1.25.4 the directory ACL leaves description to the bind account (docs/ldap-acl-setup.md; older directories: docs/upgrade-1.25.md)
Network access nginx admits only loopback and the hosts/networks in /etc/nginx/ldap-webgui-access.conf (/health also the monitoring list); shown in Settings → Access, editable there by full admins once the operator enables the root-owned access runner (password re-entry, lockout guard for your own address, any only after a second confirmation, nginx -t + rollback)
Monitoring report GET /health with Authorization: Bearer <token> — read-only, no session, no cookie; the token is generated by the WebGUI and stored only as its SHA-256; reachable only from loopback, the admin hosts and the monitoring list; counts instead of account names or addresses, no configuration values (docs/monitoring.md)
Audit log Logins, logouts, passwords, 2FA, and every successful write — create, update (changed attribute names, never values), delete, membership, sudo, settings, console recovery via manage.py — in security.log; optionally also to syslog (app.syslog_enabled)

Operating recommendation

The WebGUI manages the directory every host logs in through. Run it accordingly:

  • Never internet-facing. Reachable only from an admin network or a VPN. Certificates come from your own CA (or the bootstrap's self-signed one) — a public ACME http-01 challenge is not supported.
  • Allow the admins' machines, nothing else. The setup question and install.sh --allow write that list; Settings → Access shows it and which entry admits you, and lets full admins change it once ldap-webgui-access.path is enabled. A host updated from a release before 1.24.0 has no list until its vhost includes one — update.sh leaves such a vhost alone and says so in every update until --replace-vhost replaces it with the shipped one (docs/upgrade-1.33.md).
  • Use it from a jump host, or at least from a separate browser or browser profile that is not used for everyday browsing. A flaw in a client-side library needs a logged-in admin's browser to render hostile content; a browser that never sees any keeps that risk small.

The allow list is the enforcement, this section the reason for it.

Log files

/var/log/ldap-webgui/app.log       — application events (INFO and above)
/var/log/ldap-webgui/security.log  — security events (login, sudo, delete, ...)

Running the Tests

# Install development dependencies
pip install -r requirements.txt -r requirements-dev.txt

# Run all tests
pytest

# Run with coverage report
pytest --cov=app --cov-report=term-missing

# Run only unit tests (no Flask context needed)
pytest -m unit

# Run only integration tests (route-level)
pytest -m integration

The CI pipeline runs on every push to main / develop and on every pull request; on a version tag it tests the tagged tree and then publishes the release. See .forgejo/workflows/test.yml.

Test coverage targets

Module Tested areas
ldap_manager.py Everything: validation, DN/filter escaping, user/group/sudoRole CRUD, pagination, ID assignment, TOTP storage, the login bind (100 %)
routes/auth.py Login flow, CSRF, rate limiter, TOTP redirect, logout, change-password
routes/users.py CSV parse/validate helpers, list, export, import phases, CRUD, sudo toggle
totp_limiter.py + routes/totp.py Escalating 2FA lockout, fail-closed verify, client IP detection

Project Structure

ldap-webgui/
├── app/
│   ├── __init__.py              Application factory
│   ├── auth_helpers.py          @login_required, session helpers
│   ├── config.py                Typed config (dataclasses + YAML)
│   ├── csrf.py                  CSRF protection
│   ├── ldap_manager.py          All LDAP operations
│   ├── logger.py                Rotating file + security logger
│   ├── rate_limiter.py          Per-IP failure counter
│   ├── totp_limiter.py          Per-account escalating 2FA lockout
│   ├── totp_manager.py          TOTP encode/decode, QR generation
│   └── routes/
│       ├── auth.py              Login, logout, change-password
│       ├── groups.py            Group CRUD
│       ├── main.py              Dashboard
│       ├── settings.py          Settings read + write
│       ├── sudo.py              sudoRole CRUD
│       ├── totp.py              2FA setup, verify, disable
│       └── users.py             User CRUD + CSV import/export
├── app/templates/
│   ├── base.html                Navigation, flash messages, save button
│   ├── index.html               Dashboard with stats tiles
│   ├── auth/                    login, change_password, totp_*
│   ├── users/                   list, detail, create, import
│   ├── groups/                  list, detail, create
│   ├── sudo/                    list, detail, create
│   ├── settings/                index
│   └── errors/                  400, 403, 404, 500
├── tests/
│   ├── conftest.py              pytest fixtures
│   ├── helpers.py               TEST_CSRF_TOKEN, make_mock_ldap()
│   ├── test_ldap_manager.py     55 unit tests
│   ├── test_routes_auth.py      50 integration tests
│   └── test_routes_users.py     67 integration tests
├── docs/
│   ├── initial-setup.md         First-time setup guide ← read this first
│   ├── initial-admin.ldif       Bootstrap LDIF template
│   ├── groups-management.md
│   ├── sudo-management.md
│   ├── sudoers-schema.md
│   ├── ssh-keys.md              SSH keys: schema, ACL, SSSD/sshd (v1.10.0)
│   ├── openssh-lpk.ldif         The schema LDIF for cn=config
│   ├── 2fa-setup.md
│   ├── csv-import.md
│   └── settings.md
├── .forgejo/workflows/
│   └── test.yml                 CI (Python 3.13 + 3.14, shellcheck); a v* tag publishes the release
├── config.yaml.example          Annotated config template
├── requirements.txt             Production Python dependencies
├── requirements-dev.txt         Test dependencies (pytest, coverage)
├── install.sh                   Debian 13 installer
├── manage.py                    Console tool (create-admin, unlock-totp, ...)
├── gunicorn.conf.py             Gunicorn worker config
├── nginx/ldap-webgui.conf       Nginx virtual host (TLS) — a template
├── nginx/render_vhost.py        Renders it with /etc/ldap-webgui/vhost.env
├── systemd/ldap-webgui.service  systemd service unit
├── run.py                       Direct run entry point
├── CHANGELOG.md
└── VERSION

Tech Debt & Roadmap

# Issue Planned
1 Rate limiter is in-memory (not shared across Gunicorn workers) ✅ v1.3.0 — file-backed shared store, cross-process flock in v1.4.0
2 Passkey / YubiKey / WebAuthn 2FA v1.x
3 CSV import cannot update existing users (only creates) ✅ v1.9.0 — an import mode on the upload form; an update writes only the columns the file carries with a value, so a two-column file changes two attributes and nothing else
4 Sudo rule list filter is client-side only ✅ v1.6.0 — ?q= was already forwarded to LDAP; sudoHost joined the filter and two tests now pin the query to the fetch
5 Tailwind CDN dev build (too large for production) ✅ v1.7.0 — Tailwind v4, compiled at release time into app/static/dist/app-<VERSION>.css (59 KB, 10 KB gzipped) and committed; the 407 KB Play CDN build that compiled CSS in every browser is gone
6 Security log viewer in the WebGUI ✅ v1.6.0 — /logs/, paged and filterable across rotated files, readable by both roles, raw download; app/log_reader.py never reads a whole file for one page
7 Read-only admin role (second group DN) ✅ v1.5.0 — auth.readonly_group_dn, enforced by @write_required on every mutating route
8 Alpine.js CSP build (drop unsafe-eval from CSP) ✅ v1.8.0 — @alpinejs/csp, whose expression parser replaces new Function(); every component moved to app/static/js/components.js and server values now travel in data-* attributes. 'unsafe-inline' went too in v1.34.0: no template carries an inline script, handler or style any more
9 ID assignment has no reservation — two concurrent creates can pick the same uidNumber ✅ v1.4.3 — scan and add serialised with a cross-process flock; bulk import reserves once per batch. Single host only — the lock is a local flock; a second instance on another host against the same directory is not covered
10 CSV import preview keeps plaintext passwords in the filesystem session store until commit or expiry ✅ v1.4.3 — rows sealed with a per-import key that lives only in the admin's browser; preview expires after 15 minutes
11 set_password fallback writes an unsalted {sha512} hash that stock slapd does not recognise — if the RFC 3062 extended operation is ever refused, the account is created with a password no bind accepts (issue #6) ✅ v1.5.1 — fallback removed; RFC 3062 only, a refusal returns a failure and is logged as PASSWORD_SET_FAILED
12 LDAPManager reads conn.result["description"] unguarded — a result dict without that key raises past the layer's "no exception escapes" contract and into the route (issue #7) ✅ v1.5.1 — one _result_msg() helper behind all 16 read sites, falling back to the numeric code
13 Flask-Session store is hardcoded into the application directory — not configurable (issue #8) ✅ v1.5.1 — defaults to /var/lib/ldap-webgui/sessions, override with LDAP_WEBGUI_SESSION_DIR
14 totp_lockouts.json and login_ratelimit.json still sit in the application directory — same argument as #13, but moving them resets every lockout counter ✅ v1.17.0 — the two lockout stores and the ID-reservation lock default to /var/lib/ldap-webgui/; update.sh moves existing stores so counters survive
15 Password change / reset has no "generate" option — the admin has to invent a password that meets the policy. Offer a generated one (in the browser, policy-conformant, revealable and copyable). The admin's reset dialog on the user page also does not show the policy (length, uppercase, digit, special character) — create-user and change-own-password do; show the same checklist there ✅ v1.16.0 — Generate and Copy in all four password forms, made in the browser; one policy checklist partial, the reset dialog included
16 The security log has no event for creating or changing users, groups and sudo rules, nor for group membership or settings changes — only deletions, passwords, 2FA, sudo toggles and SSH keys are recorded. GROUP_DELETED logs admin=None (actor read from a session key that is never set) ✅ v1.16.0 — ten new events, updates name the changed attributes (never values); group events name the admin; optional syslog
17 No notice when a newer release is published — the admin has to open Settings and press Check for Updates. Show it in the header after login, checked on login (no background job), cached per host, never delaying a page ✅ v1.19.0 — header badge filled by htmx after the page, cache in /var/lib/ldap-webgui/update-check.json refreshed by a login past the TTL (6 h / 30 min), header_notice to switch it off
18 update.sh is not fit to run unattended: success lines after failed steps (config migration without ruamel.yaml, the rollback), exit 2 whether or not the rollback worked, an archive-mode rollback that dies with exit 1, rollback only after a failed restart or health check, no snapshot of the venv. Needs fail-fast exit codes, a full rollback, a dependency preflight (--preflight), the newest published release as a source, and machine-readable status ✅ v1.18.0 — exit codes 0/1/2/3/64/75, a snapshot of files, venv and config under /var/backups/ldap-webgui restored by replacement, --preflight (deps wheels-only, wheelhouse ownership, disk, health), --from-release, --status-file JSON lines
19 Updating means a shell on the host. Let a full admin install the newest published release from the configured source via the web UI — preflight shown first, a confirmation, no root in the web process (root-owned path unit + separate runner), opt-in per host ✅ v1.20.0 — Settings → Software Update, preflight first, a root-owned path unit runs the update
20 app/static/vendor/htmx-2.0.3.js contains htmx 1.9.12 (since v1.9.0); install.sh overwrites it with the real 2.0.3 from the CDN, update.sh keeps the git copy — so the htmx a host runs depends on how it was installed. test_vendor_assets.py checks names, not content. No license files for the vendored libraries (Alpine is MIT), no watch on their security advisories ✅ v1.19.1 — htmx-1.9.12.js, git the only source, SHA-256 and embedded-version pins, license files. Open: no advisory watch, htmx 1.x — planned: htmx 2.x and an OSV advisory check
21 The certificates the install generates are a starting point, not an operating state. nginx's self-signed certificate encrypts but authenticates nothing — no admin browser trusts it, so the warning gets clicked away; the bootstrap's CA must be trusted by every SSSD host and by a WebGUI on another host. In operation both should come from your own CA, which those clients already trust, and the WebGUI should say when a host still runs on the generated ones. Minor, alongside: the host's own trust of what it generated happens by accident (the nginx certificate in /etc/ssl/certs/, picked up by the next rehash) instead of explicitly through /usr/local/share/ca-certificates, and nothing removes it when the certificate is replaced done — nginx in v1.27.0 (renewal from Settings, generated certificate trusted explicitly, entry removed on replacement); slapd in v1.28.0 (renewal from Settings when WebGUI and slapd share a host, CA change as a confirmed step, the bootstrap CA in the system store). A directory on another host is renewed there
22 bootstrap-ldap.sh's closing summary always advises "Install the WebGUI" — also where the WebGUI is already installed ✅ v1.29.1 — the summary detects an installed WebGUI (its unit or the cert runner) and starts with the config step
23 No favicon.ico — every browser asks for /favicon.ico and gets a 404 ✅ v1.29.0 — the header logo as app/static/favicon.ico (16/32/48 px), where the vhost already pointed
24 Each area (users, groups, sudo rules) is read in one search without paging, so slapd's default size limit of 500 entries per search caps every list, export, the Machines page and automatic ID assignment ✅ v1.35.0 — every area read is paged and complete; the bind account needs olcLimits … size.prtotal=unlimited above 500 entries (slapd counts the whole paged search) — set by bootstrap-ldap.sh, offered by update.sh --ldap-limits, named by the limit error
25 install.sh's closing hint always says "Accept the self-signed certificate warning", also after --tls-cert with a certificate from your own CA. Cosmetic open
26 With LISTEN=<address>, https://<the host's own FQDN>/ fails from the host itself: Debian resolves its own hostname to 127.0.1.1, and nginx listens on the given address plus 127.0.0.1 only. setup, update and the runners use 127.0.0.1 and are not affected. The LISTEN documentation needs a sentence on it open
27 The CSRF validation failed security-log event has an empty ip=: it logs request.remote_addr, which is empty over the Unix socket, instead of the client address the other events use. Older than v1.34.0 open

Contributing

This repository holds the released state only — one commit per release. Development happens in a separate repository; the tests ship here, so pytest proves the released code is tested.

  1. Fork the repository and create a feature branch.
  2. Install dev dependencies: pip install -r requirements.txt -r requirements-dev.txt
  3. Make your changes. Add or update tests as appropriate.
  4. Run the test suite and ensure it passes: pytest
  5. Open a pull request against main.

Please follow the existing code style:

  • All public functions documented with docstrings
  • All LDAP operations return (bool, str, data|None) tuples
  • Passwords never logged — enforce this in code review
  • New routes must be protected with @login_required
  • New mutating routes must include CSRF token in the form

License

PolyForm Shield 1.0.0 — see LICENSE for the full text. Copyright (c) 2026 DravenTec.

You may use, change and run LDAP WebGUI for any purpose, commercial use inside your own organisation included. You may not offer it, or anything built on it, as a product that competes with it — selling it, bundling it into a product you sell, or providing it as a hosted service. For anything beyond that, ask for a separate license.

Third-party components keep their own licenses: the vendored JavaScript (app/static/vendor/*.LICENSE.txt — Alpine.js MIT, htmx 0BSD), the compiled Tailwind CSS (MIT, notice in the file) and the Python packages from requirements.txt, which pip installs on the host — all permissive (BSD, MIT, Apache-2.0) except ldap3, which is LGPL-3.0 and used unmodified.


For setup help, check docs/initial-setup.md. For bug reports and feature requests, open an issue on the repository.