UnboundID Metrics Engine CLI Tool Reference

LDAP Connection Options

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

Unauthenticated Access

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=*)'

Simple Bind

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=*)'

Secure Communication Using SSL and Blind Server Trust

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 trust store. 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=*)'

Secure Communication Using SSL with a Trust Store

A more secure method of encryption involves the use of a trust store which is a database file used to store server and issuer certificates that are considered trustworthy. Trust store files can be created and managed using the Java keytool utility. The password for the trust store can be specified on the command line or by specifying a text file containing the password, although in most cases no trust store 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=*)'

Secure Communication with SSL and Client Certificates

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=*)'

Secure Communication Using StartTLS

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 trust store or the client must be configured to trust any certificate, and it may be necessary to supply information about a certificate key store 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=*)'

Certificate-Based Authentication with SASL EXTERNAL

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=*)'

Authentication Using SASL DIGEST-MD5

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=*)'

Authentication Using SASL GSSAPI

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=*)'

Authentication Using SASL PLAIN

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=*)'