Many command-line tools expose options for establishing an LDAP connection with a server. The --hostname option must be provided if the server cannot be accessed via 'localhost', and the --port option must be provided if the server is not listening on port 389. The server supports the use of SSL and StartTLS for encrypting network communication, and it supports a number of SASL mechanisms for alternate forms of authentication and authorization. The following examples demonstrate some of the most common uses of these options using the ldapsearch tool, but should generally apply to all tools capable of performing LDAP communication
If a bind DN and password are not provided and no SASL mechanism is selected, then no authentication will be performed and all requests will be processed with the permissions granted to the anonymous user
ldapsearch --hostname server.example.com --port 389 --baseDN dc=example,dc=com \
--searchScope sub '(objectclass=*)'
A simple bind requests that an operation be performed using credentials specified as DN and password
ldapsearch --hostname server.example.com --port 389 \
--bindDN uid=admin,dc=example,dc=com --bindPassword password \
--baseDN dc=example,dc=com --searchScope sub '(objectclass=*)'
In order to avoid typing the password on the command-line the password can be stored in a file and specified using the --bindPasswordFile option
ldapsearch --hostname server.example.com --port 389 \
--bindDN uid=admin,dc=example,dc=com \
--bindPasswordFile /path/to/password/file --baseDN dc=example,dc=com \
--searchScope sub '(objectclass=*)'
If the server has been configured to permit SSL access, network traffic between a client and the server may be encrypted by specifying the use of SSL and the LDAPS port. The --trustAll option can be used to bypass a server trust confirmation prompt without the need for a certificate truststore. This is convenient for testing purposes but is not recommended for production use because it introduces vulnerability to man-in-the-middle attacks
ldapsearch --hostname server.example.com --port 636 --useSSL --trustAll \
--bindDN uid=admin,dc=example,dc=com \
--bindPasswordFile /path/to/password/file --baseDN dc=example,dc=com \
--searchScope sub '(objectclass=*)'
A more secure method of encryption involves the use of a truststore which is a database file used to store server and issuer certificates that are considered trustworthy. Truststore files can be created and managed using the Java keytool utility. The password for the truststore can be specified on the command-line or by specifying a text file containing the password, although in most cases no truststore password will be required
ldapsearch --hostname server.example.com --port 636 --useSSL \
--trustStorePath /path/to/truststore --bindDN uid=admin,dc=example,dc=com \
--bindPasswordFile /path/to/password/file --baseDN dc=example,dc=com \
--searchScope sub '(objectclass=*)'
If the server has been configured to require clients to present their own certificates, a keystore can be used to store certificates for presentation. Keystores can be created and managed using the Java keytool utility. The server maps a client certificate to an entry obviating the need for --bindDN and --bindPassword options. The password for the keystore can be specified on the command-line or by specifying a text file containing the password. Note that simply presenting a client certificate to the server will not automatically be used to authenticate the user to the directory server, as that will only be attempted if the SASL EXTERNAL mechanism is requested
ldapsearch --hostname server.example.com --port 636 --useSSL \
--keyStorePath /path/to/keystore \
--keyStorePasswordFile /path/to/key/store/password/file \
--certNickname jdoe-cert --trustStorePath /path/to/truststore \
--baseDN dc=example,dc=com --searchScope sub '(objectclass=*)'
StartTLS may be used to initiate a secure communication channel over an existing non-secure connection. As with SSL, options must be provided to either supply information about a certificate truststore or the client must be configured to trust any certificate, and it may be necessary to supply information about a certificate keystore if a client certificate is required. When using StartTLS, communication is performed over an insecure (LDAP) port rather than a secure (LDAPS) port
ldapsearch --hostname server.example.com --port 389 --useStartTLS \
--trustStorePath /path/to/truststore --baseDN dc=example,dc=com \
--searchScope sub '(objectclass=*)'
The SASL EXTERNAL mechanism can be used to specify credentials established by means other than LDAP. SASL EXTERNAL can be used in conjunction with SSL or StartTLS to authenticate the client using information provided in a client certificate. The client must be provided with information about the keystore containing the desired client certificate
ldapsearch --hostname server.example.com --port 636 --useSSL \
--keyStorePath /path/to/keystore --certNickname jdoe-cert \
--keyStorePasswordFile /path/to/key/store/password/file \
--trustStorePath /path/to/truststore --saslOption mech=EXTERNAL \
--baseDN dc=example,dc=com --searchScope sub '(objectclass=*)'
The DIGEST-MD5 SASL mechanism can be used to perform password-based authentication without exposing the clear-text password over the network. The server must be configured to store passwords in the clear or using reversible encryption
ldapsearch --hostname server.example.com --port 389 \
--saslOption mech=DIGEST-MD5 \
--saslOption authid=dn:uid=admin,dc=example,dc=com \
--baseDN dc=example,dc=com --searchScope sub '(objectclass=*)'
The SASL GSSAPI mechanism can be used to authenticate clients in a Kerberos V environment
ldapsearch --hostname server.example.com --port 389 --saslOption mech=GSSAPI \
--saslOption 'authid=admin@EXAMPLE.COM' --baseDN dc=example,dc=com \
--searchScope sub '(objectclass=*)'
The SASL PLAIN mechanism can be used to authenticate clients using an authentication ID (which contains either a username or a DN) and a password
ldapsearch --hostname server.example.com --port 389 --saslOption mech=PLAIN \
--saslOption authid=u:john.doe --bindPasswordFile /path/to/password/file \
--baseDN dc=example,dc=com --searchScope sub '(objectclass=*)'