ldapbrowser

██╗     ██████╗  █████╗ ██████╗ ██████╗ ██████╗  ██████╗ ██╗    ██╗███████╗███████╗██████╗ 
██║     ██╔══██╗██╔══██╗██╔══██╗██╔══██╗██╔══██╗██╔═══██╗██║    ██║██╔════╝██╔════╝██╔══██╗
██║     ██║  ██║███████║██████╔╝██████╔╝██████╔╝██║   ██║██║ █╗ ██║███████╗█████╗  ██████╔╝
██║     ██║  ██║██╔══██║██╔═══╝ ██╔══██╗██╔══██╗██║   ██║██║███╗██║╚════██║██╔══╝  ██╔══██╗
███████╗██████╔╝██║  ██║██║     ██████╔╝██║  ██║╚██████╔╝╚███╔███╔╝███████║███████╗██║  ██║
╚══════╝╚═════╝ ╚═╝  ╚═╝╚═╝     ╚═════╝ ╚═╝  ╚═╝ ╚═════╝  ╚══╝╚══╝ ╚══════╝╚══════╝╚═╝  ╚═╝

Pure bash+curl+fzf interactive LDAP/AD directory browser for the terminal. No heavy GUI tools. No Java. No Python. No Go. Just bash+curl+fzf+core linux utils.

---

Table of Contents

• Demo
• Why ldapbrowser?
• Features
• Known Limitations
• Requirements
• Tested LDAP Directories
• Installation
• Configuration
• Usage
• Navigation & Key Bindings
• Uninstallation
• Architecture
• QA Compatibility Matrix
• Disclaimer
• License
• Acknowledgements

---

🎬 Demo

---

🤔 Why ldapbrowser?

Browsing LDAP and Active Directory directories has always required heavy tools:

• Apache Directory Studio — Java, heavy, GUI only
• ldap-utils — raw, no UX, hard to navigate large trees
• Web UIs — not always accessible, especially on jump servers

ldapbrowser fills that gap — a pure bash+curl+fzf interactive browser that works on any terminal, including jump servers where a browser is not an option.

Zero dependencies beyond what every Linux system already has.

---

✨ Features

• 🌳 Interactive tree browsing — navigate any LDAP directory tree with fzf
• 🔍 Object inspection — view full details of any LDAP object
• 💾 Snapshot to file — save object details to file with Ctrl+S
• 🎨 Themes — customizable terminal UI themes
• 🔐 Secure — FQDN + CA certificate validation, no insecure connections (LDAP with StartTLS or LDAPS)
• 🔄 Replication aware — supports multiple LDAP hosts in replication setup
• 🤖 Auto-detection — LDAP suffix deduced automatically during setup
• ⚙️ Full configuration lifecycle management — ldapbrowser setup reset/backup/restore
• 📟 Bash completion generation with one command — ldapbrowser completion
• 📜 Log management — view, show and clean the app logs with ldapbrowser log
• 📂 Interactive CA certificate selection — pick the CA certificate with an fzf file picker during setup
• 🧵 Multiple instances — several ldapbrowser instances can run side by side, each with its own temporary directory
• 🔍 Startup diagnostics — bash version and dependency checks with OS-aware install suggestions
• 📡 signal handling (SIGTERM/SIGHUP/SIGINT/EXIT)

---

⚠️ Known Limitations

• No LDAP write operations — ldapbrowser is a read-only tool by design. Creating, modifying or deleting LDAP objects is not supported. This is an intentional architectural decision — curl supports LDAP read queries only. Write operations are planned for v2.0.
• OneLogin VLDAP does not support StartTLS — LDAPS only
• Cloud LDAP directories with push-based MFA enabled will trigger a push notification per LDAP query — see QA matrix notes

---

📋 Requirements

• bash 4.4 or higher (checked at startup)
• curl 7.18.0+ with LDAP support (checked at startup)
• fzf 0.38.0 or higher
• FQDN hostname for LDAP host(s) — no IP addresses
• Valid certificate issued by internal or external CA
• Valid CA(s) certificate(s) to add to the configuration while setting up
• DNS resolution for the FQDN(s)

---

🧪 Tested LDAP Directories

Directory	Version	StartTLS	LDAPS	Status
Microsoft Active Directory	2019-2022	✅	✅	✅ Tested
FreeIPA	4.x	✅	✅	✅ Tested
OpenLDAP	2.6.x	✅	✅	✅ Tested
389 DS	3.1.2	✅	✅	✅ Tested
OpenDJ	5.1.1	✅	✅	✅ Tested
ApacheDS	2.0.0.AM26	✅	✅	✅ Tested
Okta LDAP	Cloud	✅	✅	✅ Tested
OneLogin VLDAP	Cloud	N/A	✅	✅ Tested
JumpCloud	Cloud	✅	✅	✅ Tested
FoxPass	Cloud	✅	✅	✅ Tested

---

🚀 Installation

# Clone the repository
git clone https://github.com/mytechspacexyz/ldapbrowser.git

# Add ldapbrowser to PATH via symlink in a folder already in PATH
cd ~/bin; ln -s <ldapbrowser folder>/ldapbrowser ldapbrowser

# Add autocompletion (optional but recommended)
ldapbrowser completion >> ~/.bashrc 
or
ldapbrowser completion >> <path to similar to your shell rc file>

# Run setup
ldapbrowser setup

---

⚙️ Configuration

During ldapbrowser setup you will be prompted for:

• TLS mode — StartTLS or LDAPS
• LDAP host FQDN(s) with ports — single host or multiple for replication
• LDAP directory type — picked with fzf (Ctrl+H shows help for each type)
• Bind DN username — recommended read-only LDAP administrator account (ldapbrowser is read-only, write operations are not supported)
• Bind DN password — stored as a base64 encoded value, not shown while typing
• LDAP suffix — entered manually or deduced automatically
• LDAP users DN — per-directory default offered
• CA certificate — selected with the fzf file picker

If a configuration already exists, ldapbrowser setup refuses to run. Use ldapbrowser setup reset first, or ldapbrowser setup backup to keep a copy.

Pay SPECIAL attention to the CA certificate(s) that has to be included (and will be copied to the conf folder) while running ldapbrowser setup. It is best to issue such a certificate for your LDAP host(s) with its FQDN using your internal/external CA or create a self-signed one — ldapbrowser is built with curl secure flags requiring the CA certificate for a session. No IP address will work for this setup.

All configuration is stored inside the ldapbrowser conf folder — nothing written outside the app directory.

For more details see the short video below:

---

💻 Usage

ldapbrowser setup           # configure your LDAP connection
ldapbrowser setup reset     # reset/zero the active configuration
ldapbrowser setup backup    # backup the active configuration
ldapbrowser setup restore   # restore configuration
ldapbrowser log view        # view the ldapbrowser logs
ldapbrowser log show        # show the ldapbrowser logs
ldapbrowser log clean       # clean the ldapbrowser logs
ldapbrowser completion      # generate bash completion block
ldapbrowser list            # interactively browse the directory tree
ldapbrowser describe        # show ldapbrowser description information
ldapbrowser themes          # customize the interface
ldapbrowser debug on        # enable debug logging
ldapbrowser debug off       # disable debug logging
ldapbrowser version         # show version
ldapbrowser help            # show usage

---

🧭 Navigation & Key Bindings

fzf Navigation

Key	Action
↑ / ↓	Move up/down in the list
Shift+↑ / Shift+↓	Scroll the preview window
Enter	Enter object like DN and show its children
Ctrl+S	Snapshot object details to file in app folder
Ctrl+P	Toggle the object details preview
Esc / Ctrl+C	Exit

---

🗑️ Uninstallation

# Remove the symlink from PATH
unlink <path to the ldapbrowser symlink>

# Remove bash completion (if added)
# Edit ~/.bashrc or similar and remove:
# - the _ldapbrowser_completion() function block
# - the complete -F _ldapbrowser_completion ldapbrowser line
# Then restart the shell:
exec $SHELL

# Remove the cloned repository
rm -rf <ldapbrowser folder>

---

🏗️ Architecture

ldapbrowser/
├── assets/                  # various assets like media files
├── ldapbrowser.bash         # main entry point
├── ldapbrowser              # symlink → ldapbrowser.bash
├── conf/                    # configuration
│   ├─── backups/            # configuration backups (setup backup)
│   ├── .common_configvars
│   ├── .configvars
│   └── .deps
├── src/                     # source functions
├── docs/                    # description, help, version
├── data/                    # runtime data like snapshots
├── tmp/                     # per-instance temporary data, removed on exit
├── logs/                    # debug logs
└── examples/                # configuration examples

---

🧪 QA Compatibility Matrix

Directory	Browse	Snapshot	StartTLS	LDAPS	Notes
Active Directory	✅	✅	✅	✅
FreeIPA	✅	✅	✅	✅
OpenLDAP	✅	✅	✅	✅
389 DS	✅	✅	✅	✅
OpenDJ	✅	✅	✅	✅
ApacheDS	✅	✅	✅	✅
Okta LDAP	✅	✅	✅	✅	Push MFA triggers per-query push notification — see Known Limitations
JumpCloud	✅	✅	✅	✅	Push MFA may trigger per-query push notification — see Known Limitations
OneLogin VLDAP	✅	✅	N/A	✅	Push MFA may trigger per-query push notification — see Known Limitations
FoxPass	✅	✅	✅	✅	Push MFA may trigger per-query push notification — see Known Limitations

---

⚠️ Disclaimer

ldapbrowser is provided as-is. Always test in a non-production environment first. The author is not responsible for any issues arising from use in production environments.

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

🙏 Acknowledgements

• fzf — the fuzzy finder that powers the entire UX

• curl — the curl utility that is the engine

• Some LDAP documentation that makes it all easier and possible:

  • LDAP for Rocket Scientists
  • Microsoft AD Overview
  • FreeIPA Directory Server Documentation
  • OpenLDAP 2.6 Documentation
  • 389 DS Documentation
  • OpenDJ Documentation
  • ApacheDS Documentation And Reference
  • Okta LDAP Interface Documentation Classic Engine
  • Okta LDAP Interface Documentation Identity Engine
  • OneLogin VLDAP Reference And Details
  • JumpCloud: Get Started: Cloud LDAP
  • JumpCloud: Connect to Cloud LDAP with TLS/SSL
  • FoxPass: LDAP Overview & Debugging

• The devops/sysadmin community, MSPs and homelabbers for the inspiration

---