Using the LDAP client utilities

The ldapadd, ldapchangepwd, ldapcompare, ldapdelete, ldapmodify, ldapmodrdn, and ldapsearch utilities support authenticating with LDAP version 2 or 3 to the targeted LDAP server. By default, the client utilities use LDAP version 3 unless -V 2 is specified on the command line.

If LDAP version 2 is used, the client utilities invoke the ldap_sasl_bind_s() routine to perform a simple or anonymous bind (authentication) to the targeted LDAP server.

If LDAP version 3 is used, the client utilities invoke the ldap_sasl_bind() routine to perform a simple, CRAM-MD5, DIGEST-MD5, GSSAPI (Kerberos), or EXTERNAL bind and send the password policy control (1.3.6.1.4.1.42.2.27.8.5.1) as a non-critical control to the targeted LDAP server. (If an anonymous bind is done while in LDAP version 3, the client utilities do not invoke a bind routine). The bind mechanism used by the client utilities is determined by the -m or -S parameter.

When the bind routine is invoked, several results can be returned. Following are bind results by using various combinations of user IDs and passwords:

  1. If a null or zero length DN is specified, the user receives unauthenticated access.
  2. If a non-null, nonzero length DN is specified, a password must also be specified.
    • If the DN falls outside the scope of the suffixes that are managed by the server, the DN must match one of the adminDN, masterServerDN, or peerServerDN configuration file options specified in the server configuration file, and the password must match the corresponding adminPW, masterServerPW, or peerServerPW configuration file option. In this case, the user is bound as the LDAP server root administrator or as the master or peer replica administrator.
    • If the DN falls within the scope of a suffix managed by the server, then there must be an entry in the server directory for that DN. The password specified by the user must match a password associated with the entry. The user is then bound with that identity. If the DN also matches one of the adminDN, masterServerDN, or peerServerDN configuration file options specified in the server configuration file, then the user is bound as the LDAP server root administrator or as the master or peer replica administrator. If the DN has been assigned one or more administrative roles, then the user is bound with those administrative roles. See Administrative group and roles in z/OS IBM Tivoli Directory Server Administration and Use for z/OS for more information about administrative roles.

An error is returned when binding with any other combination of user ID and password.

Note: If you are using an LDAP server other than the z/OS® LDAP server, the bind results might be different.
If the targeted LDAP server supports the password policy control and the user specified during the simple, CRAM-MD5, or DIGEST-MD5 bind is subject to password policy on the LDAP server, the LDAP server returns a password policy control response to the client utilities. If a password policy control response is returned by the targeted LDAP server, the client utilities parse and display the password policy warning or error message. The following are examples of password policy warnings and errors displayed by the client utilities after retrieving the bind result message.
  1. This example shows the results of a simple, CRAM-MD5, or DIGEST-MD5 authentication when the user's password is expired. In this example, the user does not successfully authenticate to the targeted LDAP server because the password has expired. The utility ends because authentication is not successful. 
    ldap_sasl_bind: Credentials are not valid
ldap_sasl_bind: additional info: R004196 The 'userpassword' attribute value has
 passed its maximum age of 999999 seconds (srv_pwd_bind_check:3412)
ldap_sasl_bind: Error, password has expired
  2. This example shows the results of a simple, CRAM-MD5, or DIGEST-MD5 authentication when the user's password must be changed after a reset and there is one grace login remaining. In this example, the user is authenticated to the targeted LDAP server because there are grace logins remaining. The utility continues running and attempts the operations specified in the input file, standard input, or on the command line. 
    ldap_sasl_bind: Password must be changed
ldap_sasl_bind: Warning, 1 grace logins remain
continuing processing...
  3. This example shows the results of a simple, CRAM-MD5, or DIGEST-MD5 authentication when the user's password is to expire in just over 10 days. In this example, the user is authenticated to the targeted LDAP server because the password has not yet expired. The utility continues running and attempts the operations specified in the input file, standard input, or on the command line. 
    ldap_sasl_bind: Warning, time before password expiration is 900643
ldap_sasl_bind: additional info: Time before password expiration is 10
 days and 10:10:43
continuing processing...
    The first message indicates the password expiration in number of seconds while the second message converts the number of seconds into a more readable format.
If LDAP version 3 is used in the ldapadd, ldapchangepwd, ldapcompare, and ldapmodify utilities, the password policy control is also automatically sent as a non-critical control to the targeted LDAP server on each add, compare, and modify operation. If the user being added, compared, or modified is subject to password policy on that server, the LDAP server returns a password policy control response to the client utilities. The client utilities parse and display the password policy warning or error message. The following are examples of password policy warnings and errors displayed by the client utilities after issuing the add, compare, or modify operation.
  1. This example shows the results of modifying a user's password value after already being successfully authenticated to the targeted LDAP server. The modify operation failed because the new password value is not 8 characters or longer. 
    ldap_modify: Constraint violation
ldap_modify: additional info: R004194 The 'userpassword' attribute
 value requires a minimum of 8 characters (pwd_validate_password_quality:2542)
ldap_modify: Error, password is too short
  2. This example shows the results of comparing a user's password value after authenticating to the targeted LDAP server. The compare operation failed because the user being compared has had their account locked. 
    ldap_compare: Credentials are not valid
ldap_compare: Error, account is locked
  3. This example shows the results of adding an entry after already being successfully authenticated to the targeted LDAP server. The add operation failed because the password value specified did not abide by the password syntax checking on the targeted LDAP server.
    ldap_add: Constraint violation
ldap_add: additional info: R004190 The 'userpassword' attribute value
 allows a maximum of 3 repeated characters (pwd_validate_password_quality:2508)
ldap_add: Error, password syntax is not valid
Note: When the client utilities display the password policy control response warning or error message, the LDAP routine called by the client utilities is indicated in the prefix of the output messages. The prefix of the output messages is everything before the colon (:). For example:
routine: message