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

---

⚠️ 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+
• curl with LDAP support
• fzf 0.30+
• 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:

• LDAP host FQDN(s) — single host or multiple for replication
• 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 can be deduced automatically
• CA certificate path

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 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
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
│   ├── .common_configvars
│   ├── .configvars
│   └── .deps
├── src/                     # source functions
├── docs/                    # description, help, version
├── data/                    # runtime data like snapshots
├── 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 confirmed to trigger 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

---

Built with ❤️ for MSPs, DevOps, sysadmins and homelabbers who live in the terminal