Configuring for Active Directory

1. Using Active Directory over TLS

Microsoft are now mandating the use of TLS when communicating with AD servers to check authentication details. This requires one set of changes in ZendTo's /opt/zendto/config/preferences.php file and possibly a change to an LDAP configuration file on your ZendTo server.

If you use locally-signed or non-standard certificates, and are having problems troubleshooting, here is a troubleshooting guide.

preferences.php

Assuming your are using just 1 AD forest, then the changes required are underlined below:

'authLDAPServers1' => array('ldaps://your-AD-server-here.example.com'),
'authLDAPUseSSL1' => false,
'authLDAPUseTLS1' => false,

ldap.conf

On your ZendTo server, the change depends on your version of Linux as follows:

• CentOS / RedHat
  Look in /etc/openldap/ldap.conf and you will need to add a line that tells the TLS library where to find the root certificate authority certs:
  TLS_CACERT /etc/pki/tls/certs/ca-bundle.crt
  and comment out the TLS_CACERTDIR line.
• Ubuntu / Debian
  No change needed, as the file /etc/ldap/ldap.conf should already contain the necessary line
  TLS_CACERT /etc/ssl/certs/ca-certificates.crt
• FreeBSD
  Look in /usr/local/etc/openldap/ldap.conf and add the line
  TLS_CACERT /usr/local/share/certs/ca-root-nss.crt
• SuSE / OpenSUSE
  Install the package libldap-data by running the command
  zypper install libldap-data
  then look in /etc/openldap/ldap.conf and add the line
  TLS_CACERT /var/lib/ca-certificates/ca-bundle.pem

In all cases, you can run the command "man ldap.conf" to read about other TLS_... settings you can add to the ldap.conf file, though other changes shouldn't be needed for most sites.

Here is how one user got the SSL certificates right for their setup, using an LDAP server:

1. Retrieve the CA and server certificates from the LDAP server in pem format.
2. Copy them into a folder on the ZendTo server and combine them into a single pem file.
3. Edit ldap.conf so the TLS_CACERT variable points to the new combined pem file.
4. Use ldapsearch on the ZendTo server to verify that you can connect to the LDAP server over port 636.
5. Edit the ZendTo preferences.php file so the URL For the LDAP server uses the format ldaps://your-ldap-server-name-or-ip.
6. Restart Apache on the ZendTo server.
7. Verify that logins now work.

2. BaseDN and Bind Details

Many people have trouble getting the BaseDN and bind details correct to successfully configure ZendTo to use your Active Directory authentication system.

The easiest way to get these configuration settings correct is to use the ldapsearch command (normally part of ldap-utils package or similar) to experiment with different values until it works on the command line.

For this example, we will use the site "example.com", connecting to the AD server "ad_server.example.com" as user "ad_read_user" with password "ad_read_password". The correct BaseDN will be "OU=Staff,OU=users,DC=example,DC=com". If you run the command

ldapsearch -x -LLL -E pr=200/noprompt -H ldaps://ad_server.example.com -D 'ad_read_user' -w 'ad_read_password' -b 'OU=Staff,OU=users,DC=example,DC=com' -s sub '(sAMAccountName=*)' cn mail memberOf

Experiment with different values for

• ad_server.example.com
• ad_read_user
• ad_read_password
• OU=Staff,OU=users,DC=example,DC=com

When you get them right, the command will output the username, email address and group information for all the users it finds. You should make sure this includes all the users you want to be able to use ZendTo (very often you don't want the "OU=Staff," bit if you want all your users to be able to use ZendTo).

When you have got them right, the corresponding preferences.php settings are

• 'authenticator' => 'AD',
• 'authLDAPBaseDN1' => array('OU=Staff,OU=users,DC=example,DC=com'),
• 'authLDAPServers1' => array('ad_server.example.com'),
• 'authLDAPAccountSuffix1' => '@example.com',
• 'authLDAPUseSSL1' => false, for testing, strongly advise true in production
• 'authLDAPBindUser1' => 'ad_read_user',
• 'authLDAPBindPass1' => 'ad_read_password',
• 'authLDAPOrganization1' => 'Example Company Inc',