Configuring the LDAP or AD connection for phone number lookups

Last updated 2022.02.17

We have implemented a connection to a directory such as LDAP or Active Directory so users can search for phone numbers by the user's name directly in the app. That being said, the specifics of how this connection works are highly dependent on the directory's structure and schema. While we believe we have provided a sane set of defaults, the configuration is so dependent on the organization we felt it better to create a template php file which can be customized to each organization's needs. By providing a "getContacts.php.sample" file, changes to the upstream repository can be merged locally without directly overwriting customization an organization has made to the lookup system.

To get this working, you need to copy "includes/getContacts.php.sample" to "incluces/getContacts.php". From this point, any changes you make to the php file will NOT be overwritten by re-pulling from Git. That being said, updates to the upstream file will need to be reviewed manually going forward so local changes are not overwritten.

The areas of customization in that file are indicated by comments, but fall under 4 areas:

1. The array of attribute names to pull from AD when constructing the contact string in the dropdown; these can be added/removed as needed
2. An opportunity to create additional more granular filters. This arose from the need to filter out service accounts, regular user accounts, and inactive accounts, which were easily designated by a substring in the full DN. This is commented out by default, but can be adapted as needed and can even filter based on other attributes so long as they are brought in from step 1.
3. Should an attribute return an array instead of a string (for example, some directory fields can have multiple values), addressing a specific index is supported and a demonstration is left in place for the "homePhone" attribute.
4. If a new attribute should appear in the contact string in the dropdown, it will need to be brought into the array. The existing code is segmented into blocks per-attribute, and should be fairly intuitive to adapt to new attributes.

One final configuration option exists in the global config file; an object filter which serves as a global search filter based on the objectClass or objectCategory of objects based on your schema. While the default configuration will work for most AD/LDAP environments, this was added as a configuration element as our reference OpenLDAP test environment uses a custom schema for "domainAccount" in order to ensure the most adaptability possible.