ldapwhoami Command Cheat Sheet: Verify OpenLDAP Binds

About	ldapwhoami performs the LDAP Who Am I extended operation after a bind. It is a compact way to verify the authorization identity seen by an OpenLDAP server.
Tested on	Rocky Linux 10.2; OpenLDAP 2.6.10; openldap-clients from EPEL
Package	openldap-clients (apt/deb) · openldap-clients (dnf/rpm)
Man page	ldapwhoami(1)
Privilege	unprivileged for anonymous checks; bind DN credentials for authenticated checks; root for LDAPI EXTERNAL
Distros	RHEL, Rocky Linux, AlmaLinux, Oracle Linux, CentOS Stream (openldap-clients package).
Related guide	Configure OpenLDAP TLS on RHEL Install and configure OpenLDAP on RHEL

ldapwhoami — quick reference

Check the bound identity

ldapwhoami sends the LDAP Who Am I extended operation after connecting and binding. It confirms the server's view of the authorization identity, not merely the DN you typed.

When to use	Command
Check anonymous identity	`ldapwhoami -x -H ldap://localhost`
Confirm an administrator simple bind over StartTLS	`ldapwhoami -x -ZZ -H ldap://localhost -D "cn=admin,dc=example,dc=com" -W`
Provide a lab password non-interactively	`ldapwhoami -x -ZZ -H ldap://localhost -D "cn=admin,dc=example,dc=com" -w 'PASSWORD'`
Read the bind password from a protected file	`ldapwhoami -x -ZZ -H ldap://localhost -D "cn=admin,dc=example,dc=com" -y /root/ldap-bind.txt`
Check the local SASL EXTERNAL identity	`sudo ldapwhoami -Q -Y EXTERNAL -H ldapi:///`
Verify a service account bind after ACL changes	`ldapwhoami -x -ZZ -H ldap://localhost -D "uid=replicator,ou=service-accounts,dc=example,dc=com" -W`

Troubleshoot a bind

Use verbose or no-execute modes to see how the client is constructing the request before testing an application configuration.

When to use	Command
Print connection and bind details	`ldapwhoami -v -x -ZZ -H ldap://localhost -D "cn=admin,dc=example,dc=com" -W`
Show the operation without sending it	`ldapwhoami -n -v -x -ZZ -H ldap://localhost -D "cn=admin,dc=example,dc=com" -W`
Print LDAP library debug messages	`ldapwhoami -d 1 -v -x -ZZ -H ldap://localhost -D "cn=admin,dc=example,dc=com" -W`
Test a remote LDAP URI	`ldapwhoami -x -ZZ -H ldap://ldap.example.com -D "cn=admin,dc=example,dc=com" -W`

Connection and TLS

When to use	Command
Require StartTLS for a simple bind	`ldapwhoami -x -ZZ -H ldap://localhost -D "cn=admin,dc=example,dc=com" -W`
Request StartTLS but allow fallback	`ldapwhoami -x -Z -H ldap://localhost -D "cn=admin,dc=example,dc=com" -W`
Use LDAPv3 explicitly	`ldapwhoami -P 3 -x -ZZ -H ldap://localhost -D "cn=admin,dc=example,dc=com" -W`
Point the client at a specific CA file	`ldapwhoami -x -ZZ -H ldap://localhost -D "cn=admin,dc=example,dc=com" -W -o TLS_CACERT=/etc/openldap/certs/ca.crt`

Help

When to use	Command
Show usage	`ldapwhoami -h`
Print version and exit	`ldapwhoami -VV`

ldapwhoami — command syntax

Synopsis from ldapwhoami --help:

text


ldapwhoami [-V[V]] [-d debuglevel] [-n] [-v] [-x] [-D binddn] [-W]
            [-w passwd] [-y passwdfile] [-H ldapuri]
            [-e [!]<ext>[=<extparam>]] [-E [!]<ext>[=<extparam>]]
            [-o opt[=optparam]] [-I] [-Q] [-Y mech] [-Z[Z]]

There is no search base or filter because this is an extended operation, not a directory search. Use it after following OpenLDAP installation on RHEL to verify a client bind path, then test a real user DN from OpenLDAP user and group management.

ldapwhoami — command examples

Essential Check the anonymous authorization identity

Run an anonymous simple bind first to learn what the server reports without credentials.

bash

ldapwhoami -x -H ldap://localhost

Sample output:

output

anonymous

This does not test whether anonymous users can search a particular subtree; ACLs still decide that.

Essential Confirm an administrator StartTLS bind

Use the same URI, DN, and TLS requirement as the application or administrative client you are diagnosing.

bash

ldapwhoami -x -ZZ -H ldap://localhost -D "cn=admin,dc=example,dc=com" -W

Sample output:

output

Enter LDAP Password:
dn:cn=admin,dc=example,dc=com

The dn: response confirms that the server accepted the bind as the expected administrator.

Essential Recognize invalid credentials

An incorrect password is rejected before the Who Am I operation runs.

bash

ldapwhoami -x -ZZ -H ldap://localhost -D "cn=admin,dc=example,dc=com" -w 'wrong-password'

Sample output:

output

ldap_bind: Invalid credentials (49)

Check the DN and secret; do not put real passwords in shell history outside a disposable lab.

Common Check the local LDAPI EXTERNAL identity

On the LDAP server, query the identity mapped from the local root process. Use sudo to run the client as root.

bash

sudo ldapwhoami -Q -Y EXTERNAL -H ldapi:///

Sample output:

output

dn:gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth

This is the SASL peer credential identity; ACLs decide whether it maps to configuration authority.

Common Trace a successful bind

Use -v when a successful or failed application bind needs a compact client-side trace.

bash

ldapwhoami -v -x -ZZ -H ldap://localhost -D "cn=admin,dc=example,dc=com" -W

Sample output:

output

ldap_initialize( ldap://localhost:389/??base )
Enter LDAP Password:
dn:cn=admin,dc=example,dc=com
Result: Success (0)

The final dn: line is still the server's reported authorization identity.

Common Bind without sending Who Am I

-n exercises the connection and bind path but skips the extended operation itself.

bash

ldapwhoami -n -v -x -ZZ -H ldap://localhost -D "cn=admin,dc=example,dc=com" -W

Sample output:

output

ldap_initialize( ldap://localhost:389/??base )
Enter LDAP Password:
Result: Success (0)

When the bind succeeds but no dn: line appears, the password and TLS path are fine and the extended operation was deliberately withheld.

Advanced Confirm TLS is mandatory for a simple bind

This server refuses a password bind without StartTLS. Configure the CA trust path first using the OpenLDAP TLS guide.

bash

ldapwhoami -x -H ldap://localhost -D "cn=admin,dc=example,dc=com" -W

Sample output:

output

Enter LDAP Password:
ldap_bind: Confidentiality required (13)
	additional info: confidentiality required

Add -ZZ; that both requests TLS and makes a negotiation failure fatal.

Advanced Bind using a password file

-y reads the bind password from a file instead of -w or -W, which keeps the secret out of the argument list.

bash

ldapwhoami -x -ZZ -H ldap://localhost -D "cn=admin,dc=example,dc=com" -y /root/ldap-bind.txt

Sample output:

output

dn:cn=admin,dc=example,dc=com

Restrict the file to the invoking user with chmod 600 and remove it after bootstrap when possible.

Advanced Verify a service account bind

After creating replication or application accounts in user and group management, confirm the server recognizes the intended DN.

bash

ldapwhoami -x -ZZ -H ldap://localhost -D "uid=replicator,ou=service-accounts,dc=example,dc=com" -W

Sample output:

output

Enter LDAP Password:
dn:uid=replicator,ou=service-accounts,dc=example,dc=com

A successful response here does not prove search or write ACLs—only that the bind identity is valid.

Advanced Print the installed client version

-VV is a quick sanity check that the EPEL openldap-clients build matches the server generation you are troubleshooting.

bash

ldapwhoami -VV

Sample output:

output

ldapwhoami: @(#) $OpenLDAP: ldapwhoami 2.6.10 (Dec 11 2025 00:00:00) $
	openldap
	(LDAP library: OpenLDAP 20610)

Match major versions between client utilities and slapd when chasing protocol or TLS extension issues.

ldapwhoami — when to use / when not

Use ldapwhoami when	Use something else when
You need to prove which identity a server accepted after a bind You are checking StartTLS, credentials, or SASL EXTERNAL before debugging an application You want a safe identity check with no directory modification You need to separate bind failures from search or ACL failures	You need to inspect entries or ACL-visible attributes → ldapsearch You need to create a user → ldapadd You need to change attributes → ldapmodify You need to remove entries → ldapdelete

ldapwhoami vs ldapsearch

	ldapwhoami	ldapsearch
Operation	Who Am I extended operation	LDAP search operation
Output	Authorization identity	Matching directory entries
Best use	Validate bind configuration	Validate data, filter, and ACL visibility
Requires a base DN	No	Yes

These client tools cover the normal OpenLDAP administration flow.

Command	One line
ldapsearch	Search and inspect directory entries.
ldapadd	Add entries from LDIF.
ldapmodify	Change attributes with LDIF.
ldapdelete	Remove entries by DN.
ldapwhoami	Confirm the authenticated identity.
slappasswd	Generate password hashes for OpenLDAP.

Browse Linux commands for more command references.

ldapwhoami — interview corner

What does ldapwhoami do?

It performs the LDAP Who Am I extended operation after binding and prints the authorization identity the server sees.

A strong answer is:

“I use it to prove the server accepted the intended bind identity before I debug searches or ACLs.”

What does ldapwhoami return without credentials?

With an anonymous bind, OpenLDAP returns anonymous.

A strong answer is:

“Anonymous is an identity too; it does not mean the server will allow every search.”

Why pair ldapwhoami with -ZZ?

It validates the same TLS-protected simple-bind path an application should use, and refuses a downgrade.

A strong answer is:

“It checks credentials and transport policy together, without changing data.”

What does LDAPI EXTERNAL return?

It commonly returns the operating-system peer credential identity, such as the root UID/GID SASL identity.

A strong answer is:

“That identity must still be authorized by the server ACLs; it is not automatically the directory admin DN.”

Why not just run ldapsearch to test a bind?

A search can fail because of base DN, filter, or read ACLs even when the bind itself is valid.

A strong answer is:

“ldapwhoami isolates authentication from authorization; I use ldapsearch only after the identity is confirmed.”

What does ldapwhoami -n prove?

It proves the URI, TLS negotiation, and bind credentials work without issuing the Who Am I extended operation.

A strong answer is:

“When -n succeeds but the normal command fails, I look at extended-operation support or proxy authorization—not the password.”

Troubleshooting

Symptom	Likely cause	Fix
`Invalid credentials (49)`	Wrong bind DN or password	Confirm the exact DN and reset or retrieve the correct secret with slappasswd for `olcRootPW`.
`Confidentiality required (13)`	Simple bind without TLS	Add `-ZZ` and configure CA trust.
`Can't contact LDAP server`	Wrong URI or unavailable service	Check listener, URI, firewall, and `slapd` status.
Unexpected SASL peer identity	Command was not run as expected local user	Run through `sudo` for root or inspect SASL mapping and ACLs.
Bind succeeds but searches fail	Identity is valid; read ACLs deny the base or attributes	Review ACLs in OpenLDAP ACL examples.
`dn:` missing after `-n`	Dry-run mode skipped the extended operation	Remove `-n` when you need the authorization identity printed.
TLS handshake errors with `-ZZ`	CA file or hostname mismatch	Set `TLS_CACERT` with `-o` and align the certificate SAN with the URI host.
`anonymous` when credentials were supplied	`-D` omitted or bind fell back to anonymous	Add `-D` and confirm `-W`, `-w`, or `-y` is present.

References

OpenLDAP ldapwhoami(1) manual{: target="_blank" rel="noopener" }
Install and configure OpenLDAP on RHEL Linux
Configure OpenLDAP TLS on RHEL
Manage OpenLDAP users and groups
OpenLDAP ACL examples

ldapwhoami — quick reference

Check the bound identity

Troubleshoot a bind

Connection and TLS

Help

ldapwhoami — command syntax

ldapwhoami — command examples

ldapwhoami — when to use / when not

ldapwhoami vs ldapsearch

Related commands

ldapwhoami — interview corner

Troubleshooting

References

Related Articles

OpenLDAP vs 389 Directory Server: Key Differences

Configure OpenLDAP Indexes with olcDbIndex

Migrate Local Linux Users and Groups to OpenLDAP

Search GoLinuxCloud