How to Use ldapsearch

What is ldapsearch? Purpose and Key Use Cases

ldapsearch is a command-line tool for querying LDAP directories such as OpenLDAP, Active Directory, and other LDAPv3-compliant servers. Developers, admins, and identity engineers use ldapsearch to inspect directory contents, debug integration problems, test authentication, and automate directory management tasks.

Key use cases include:

• Retrieving user, group, or organizational data for troubleshooting or scripting
• Validating filters and queries before integrating with applications
• Debugging authentication, search, or schema issues
• Exploring directory structure and contents for integration or access control work

For example, a developer wanting to list all directory entries under the base domain dc=example,dc=com might run:

ldapsearch -x -b 'dc=example,dc=com' '(objectClass=*)'

This command connects using simple authentication (-x), specifies the base DN to search from (-b), and searches for all objects ((objectClass=*)).

ldapsearch works with any LDAPv3-compliant server, including OpenLDAP and Active Directory, making it a universal tool for directory work.

ldapsearch Syntax and Core Options Explained

The general structure of the ldapsearch command is:

ldapsearch [options] filter [attributes...]

Essential Options

• -x : Use simple authentication instead of SASL.
• -D <bindDN> : Bind Distinguished Name for authentication.
• -W : Prompt for password interactively (safer practice).
• -w <password> : Supply password on the command line (not recommended).
• -b <baseDN> : The base Distinguished Name from which to start the search (mandatory unless a default is configured).
• -H <ldapuri> : Specify the LDAP URI (e.g., ldap://host, ldaps://host).
• -h <host> and -p <port> : Legacy server/port flags.
• -s <scope> : Set search scope: base, one, or sub.
• filter : LDAP filter string in RFC4515 syntax.
• [attributes...] : List of specific attributes to return.

Example Breakdown

Find all users with a username starting with 'jdoe':

ldapsearch -x -b 'dc=example,dc=com' '(uid=jdoe*)' cn mail

• -x: Simple authentication.
• -b 'dc=example,dc=com': Start at this base DN.
• '(uid=jdoe*)': Filter for users with uid beginning with "jdoe".
• cn mail: Only return the cn (Common Name) and mail attributes.

Building Powerful LDAP Search Filters

LDAP filters are patterns to select entries based on object attributes, using a flexible, expressive syntax:

• Equality: (attribute=value) — e.g., (cn=John Doe)
• Presence: (attribute=*) — e.g., (mail=*)
• Substring/wildcard: (cn=John*) — matches any CN starting with 'John'
• Logical AND: (&(attr1=val1)(attr2=val2))
• Logical OR: (|(attr1=val1)(attr2=val2))
• Negation: (!(attr=value))

Example filter scenarios:

• All users with names starting "John": (cn=John*)
• Groups based on objectClass: (objectClass=groupOfNames)
• Users with email addresses: (mail=*)
• Users in Madrid or Milan: (|(l=Madrid)(l=Milan))
• Users named "Alice" belonging to a specific group: (&(cn=Alice)(memberOf=cn=mygroup,dc=example,dc=com))

Common mistakes include missing parentheses or incorrect attribute names, which yield no results.

Authentication: Securely Binding with ldapsearch

LDAP servers require authentication (binding) to access non-public data. The bind DN is the identifier (Distinguished Name) of the authenticating user.

Authentication Modes

• Simple authentication: -x (most common); combine with -D for a username and -W to be prompted for a password.

  ldapsearch -x -D 'cn=admin,dc=example,dc=com' -W -b 'dc=example,dc=com' '(uid=jdoe)'
  

  This securely prompts for a password at runtime, preventing accidental exposure.

• SASL authentication: Omitting -x enables SASL (for GSSAPI, DIGEST-MD5, etc.), with additional flags required for those mechanisms.

Warning:
Never use the -w <password> option unless strictly necessary; this exposes the password in your shell history and process listings. Always prefer -W for a safe, interactive prompt.

Connecting Securely: LDAPS and StartTLS

LDAP traffic—including passwords—is unencrypted by default. To protect credentials and data:

• Use ldaps:// (LDAP over SSL/TLS) in the server URI:

  ldapsearch -x -H 'ldaps://ldap.example.com' -b 'dc=example,dc=com' '(objectClass=*)'
  

• To upgrade an unencrypted LDAP connection to TLS, add -ZZ (StartTLS):

  ldapsearch -x -H 'ldap://ldap.example.com' -ZZ -b 'dc=example,dc=com' '(objectClass=*)'
  

Note:
Always use LDAPS or StartTLS for sensitive data or when authenticating. Binding securely to a non-SSL port will fail; verify port and protocol match the server setup.

Practical ldapsearch Examples and Real-World Scenarios

Enumerate all users (OpenLDAP or AD):

ldapsearch -x -b 'dc=example,dc=com' '(objectClass=person)' cn uid mail

Search for a group named "Finance":

ldapsearch -x -b 'dc=example,dc=com' '(cn=Finance)' dn member

Query the Root DSE (server metadata):

ldapsearch -x -s base -b "" '(objectClass=*)'

Retrieve directory schema:

ldapsearch -x -b 'cn=schema' -s base '(objectClass=*)'

Search for Active Directory users with sAMAccountName 'jdoe':

ldapsearch -x -H 'ldaps://ad.example.com' -D 'user@example.com' -W -b 'dc=example,dc=com' '(sAMAccountName=jdoe)' cn mail

Adjust the base DN and filter attributes to match your environment and server type. Active Directory often uses sAMAccountName for username and specific group object classes.

Troubleshooting ldapsearch: Common Errors and Fixes

For full error references and resolutions, consult authoritative documentation.

Security Best Practices and Warnings

• Never use -w <password> in the command line; this exposes credentials to process listings and audit trails.
• Always prefer secure connections (ldaps:// or -ZZ); unencrypted LDAP allows credentials and data to be intercepted.
• Do not embed plaintext passwords in scripts. If scripting is required, use .ldappasswd files with strict permissions or prompt securely within the script.
• Restrict access to sensitive output files, as ldapsearch can disclose private attribute values.
• Validate filters and attribute names to avoid accidental information disclosure or excessive directory queries.

Platform Notes: ldapsearch on Linux, macOS, and Windows

Linux

• On most distributions, ldapsearch is available via the openldap-clients or ldap-utils package (install via your package manager).
• Typically located at /usr/bin/ldapsearch.

macOS

• ldapsearch is often pre-installed as part of macOS or can be installed with OpenLDAP via Homebrew.
• Path is generally /usr/bin/ldapsearch or /opt/homebrew/bin/ldapsearch.

Windows

• Windows does not include ldapsearch by default.
• Obtain it via Cygwin, Windows Subsystem for Linux (WSL), or pre-built binaries as part of OpenLDAP packages for Windows.

Note:
Command syntax and core options are consistent across platforms; installation and binary locations may differ.

Sources

• OpenLDAP Software 2.4 Administrator's Guide: https://www.openldap.org/doc/admin24/guide.html
• OpenLDAP Quick-Start Guide: https://www.openldap.org/doc/admin26/quickstart.html
• OpenLDAP Common Errors: https://www.openldap.org/doc/admin24/appendix-common-errors.html

Sources

• www.openldap.org — guide.html
• www.openldap.org — quickstart.html
• www.openldap.org — appendix-common-errors.html