Directory service

This page documents the exact queries, attributes and file formats the server module uses for each directory service type. Use it to diagnose why users, groups or specific attributes do not appear after a directory synchronization.

For the general configuration walkthrough see the Directory service page.

How a synchronization runs

For Active Directory and OpenLDAP every synchronization (scheduled, or triggered with Update Directory Cache) performs the same steps:

1. Connect and bind to the server.
2. Search for users and load their attributes.
3. Search for groups and resolve their members against the users loaded in step 2.
4. Derive the domain list from the Base DN.

The server module writes an info log line for every step: the connection URL and bind account, each search base, filter and queried attribute list, every fetched result page, per-group member resolution counts, and the final user/group/domain totals. When a sync returns unexpected results, read the application log first - it shows exactly which step lost the data.

Connection details (Active Directory and OpenLDAP)

• The connection URL is ldap://host:port, or ldaps://host:port when Use SSL (LDAPS) is enabled.
• Authentication is a simple LDAP bind (protocol version 3) with the configured account and password.
  • Active Directory binds with the Username field.
  • OpenLDAP binds with the Bind DN field.
• Referrals returned by the server are ignored.
• Searches use the subtree scope and are paged with the Paged Results control, 1000 entries per page. The control is sent as non-critical, so servers without paging support still answer with a single result set.

Active Directory

User query

• Search base: User Search Base, or Base DN when the user search base is empty.
• Filter: (&(objectCategory=person)(objectClass=user)(mail=*)) - only user objects that have a mail attribute are returned. Users without an email address are never imported.
• Entries without a sAMAccountName value are skipped (the skip count is logged).

Group query

• Search base: Group Search Base, or Base DN when the group search base is empty.
• Filter: (objectClass=group).
• Queried attributes: sAMAccountName (group ID, required - entries without it are skipped and logged with their DN), cn (group name), mail, member.
• Each value of member is a full DN. It is matched case-insensitively against the DNs of the users loaded by the user query of the same sync. A member that was not imported as a user (outside the user search base, no mail attribute, or no sAMAccountName) does not resolve and is dropped from the group. The log shows both numbers per group: Group 'name': X member entries, Y resolved to loaded users.

User attributes

Application field	Active Directory attribute
User ID	sAMAccountName (required)
Email	mail (required by the filter)
First name	givenName
Last name	sn
Display name	displayName
Notes	info
Phone number	telephoneNumber
Mobile number	mobile
Street address	streetAddress
City	l
Postal code	postalCode
Country	co
Job title	title
Department	department
Company	company
Employee ID	employeeID
Photo	thumbnailPhoto (binary, stored Base64 encoded)

OpenLDAP

User query

• Search base: User Search Base, or Base DN when the user search base is empty.
• Filter: (&(objectClass=inetOrgPerson)(mail=*)) - only inetOrgPerson entries that have a mail attribute are returned.
• Entries without a uid value are skipped (the skip count is logged).

Group query

• Search base: Group Search Base, or Base DN when the group search base is empty.
• Filter: (objectClass=groupOfNames).
• Queried attributes: cn (group ID and name, required - entries without it are skipped and logged with their DN), mail, member.
• Member resolution works the same way as for Active Directory: each member DN must match the DN of a user imported in the same sync, otherwise it is dropped from the group.

User attributes

Application field	OpenLDAP attribute
User ID	uid (required)
Email	mail (required by the filter)
First name	givenName
Last name	sn
Display name	displayName
Notes	description
Phone number	telephoneNumber
Mobile number	mobile
Street address	street
City	l
Postal code	postalCode
Country	c
Job title	title
Department	ou
Company	o
Employee ID	employeeNumber
Photo	jpegPhoto (binary, stored Base64 encoded)

Domains (Active Directory and OpenLDAP)

The domain list is derived from the DC= components of the Base DN. For example, DC=example,DC=com produces the domain example.com. If the base DN contains no DC= components, no domain is created and the log states it explicitly.

Manual import (CSV)

Both files must be UTF-8 encoded and start with a header row containing the column names below. The delimiter is detected automatically: the first data row is inspected and whichever of comma (,) or semicolon (;) occurs more often is used for the whole file. The detected delimiter is logged.

Users CSV

Column	Required	Application field
id	yes	User ID
mail	yes	Email
first_name	no	First name
last_name	no	Last name
display_name	no	Display name
notes	no	Notes
phone_number	no	Phone number
mobile_number	no	Mobile number
street_address	no	Street address
city	no	City
postal_code	no	Postal code
country	no	Country
job_title	no	Job title
department	no	Department
company	no	Company
employee_id	no	Employee ID
photo	no	Photo (Base64 encoded image data)

• Rows with an empty id or mail are skipped with a warning in the log.
• Rows whose id duplicates an already imported user (case-insensitive) are ignored - the first occurrence wins.
• Domains are derived from the domain part of each user's email address; each distinct domain is added once.

Groups CSV

Column	Required	Application field
id	yes	Group ID
name	no	Group name
mail	no	Group email
member_ids	no	Group members

• member_ids holds the user IDs of the group members (the id column of the users CSV), separated by commas or semicolons, e.g. jsmith;akowalski.
• Rows with an empty id are skipped with a warning in the log.
• Rows whose id duplicates an already imported group (case-insensitive) are ignored - the first occurrence wins.

Example files: users CSV, groups CSV.

Common symptoms

• A user is missing - the entry has no mail attribute (excluded by the search filter), no sAMAccountName / uid, or lies outside the User Search Base. The log reports the number of entries returned by the search and the number skipped.
• A group is empty or missing members - the member DNs do not match any imported user. Check the per-group log line: if X member entries is correct but Y resolved is lower, the missing members were not imported as users in the same sync.
• No domains - the Base DN contains no DC= components (LDAP/AD), or no users were imported (manual import).
• CSV import loads nothing - wrong delimiter detection due to an unusual first row, a missing header row, or missing required columns; the log warns about every skipped record.