The Active Directory sync module of Portail ZAPP creates and maintains the accounts of the people in your Active Directory (or any LDAP directory), and the membership of these accounts in the application's groups. Synchronization always goes one way: from the directory to Portail ZAPP. It never changes the directory.
The screens are reserved for administrators. They are reached through Administration › Connectors and automation › AD sync.
Rules
The Active Directory sync page (/ad-sync) lists the synchronization rules. A rule stands for one directory: it has its own server, secret, sources, mappings and schedule. For each rule, the list shows its status (Active, Inactive or Incomplete), its schedule and its last synchronization.
New rule opens the form; Open displays an existing rule.
Setting up the connection
The LDAP configuration block of a rule contains:
- Name: unique among the rules;
- LDAP/AD server: host name or IP address, for example
ldap.example.com; - LDAP port: 389 as standard, 636 for LDAPS; Use LDAPS (SSL/TLS) encrypts the connection. A warning appears if the port and the LDAPS box do not match, or if the connection is not encrypted (the bind password would then travel in clear text);
- AD connection account: as a UPN (
account@example.com), NetBIOS (DOMAIN\account) or full DN; - Base DN: where reads start, for example
dc=example,dc=com; - Bind password secret: the name of a secret from the Secrets vault module. The password is never typed into or stored in the rule. If the Secrets vault is not installed, you type the secret's name by hand;
- Outpost agent: keep Direct: the server queries the directory when the Portail ZAPP server can reach the directory. Pick an agent (Outpost agents module) to read a remote directory that the server cannot reach; the password is attached to each command and the agent does not keep it. A message warns you if the agent is not active or too old for directory synchronization; on Linux, prefer LDAPS;
- Orphan behavior and Orphan brake (%): see below;
- Schedule (cron): see below;
- Active: an active rule must be complete (server, account, base DN, secret). An incomplete rule can be saved as an inactive draft.
Test connection checks the form values as they are, even before saving. With an Outpost agent, the test is sent to the agent: the message “Waiting for the Outpost to answer...” appears, with a Cancel button, until the answer comes back.
Sources and mappings
Once the rule is saved, two blocks are added (before that, the message “Save the rule to configure its sources and mappings.” is shown).
User synchronization: the rule's sources, that is, the places in the directory where accounts are read. Choose the type, Organizational unit (OU) or Group, search for it in the rule's directory, then Add source. The search also goes through the Outpost agent if there is one.
Group membership synchronization: the mappings, which link a directory group to a Portail ZAPP group. At each synchronization, the members of the directory group who have an account in Portail ZAPP are added to the matching group; those who are no longer members are removed from it. Nested groups are not expanded: only direct members count.
What a synchronization does
For each person read from the sources:
- missing account: it is created with the first name, last name and address; the sign-in identifier is the email address. An entry without an identifier (
sAMAccountName) or without an address is skipped and counted as an error; - account already created by the directory: the first name, last name and contact address are updated if they changed in the directory. An empty attribute in the directory erases nothing, and the sign-in identifier never changes. An account is recognized by its directory identifier, even if its address changed;
- account that does not come from a directory (local account, account from another provider): it is neither changed, tracked nor disabled by the synchronization;
- account disabled in the directory: it is never created; if it was tracked, it is handled as an orphan.
The synchronization creates accounts without a password: it does not set up sign-in. How these people sign in is set up in Authentication.
In mappings, only accounts that come from the directory are removed from a group. A local account placed in the group by hand (administrator, service account) is never removed. If a group's member list is incomplete, nothing is removed from that group. A group already synchronized by another source (for example organizations) is not changed: the mapping is skipped and reported in the log.
Line manager
The AdSync:SyncManagers setting of the Configuration screen (AdSync category, off by default), set to true, also fills in the line manager of the synced accounts, from the directory's manager attribute. The manager is looked up among the accounts followed by all rules: it can come from another organizational unit. The rules are those of the Google Workspace sync:
- a locked link (entered by hand, by default) is never changed;
- the manager is only looked up among the accounts followed by this sync: an unknown manager, or one whose account was created by hand or by another connector, changes nothing;
- a user with no manager in the directory has their link ended only if that link came from a sync;
- a new manager ends the current link and opens a new one: the history stays on the account's Managers and history page, with the origin "Active Directory".
Orphan accounts
An orphan is an account tracked by the rule that no longer appears in the sources, or that is disabled in the directory.
- Ignore: nothing is done.
- Disable (default): the account is disabled in Portail ZAPP. This is reversible: if the person shows up in the directory again, the account is reactivated automatically. Only an account disabled by the rule is reactivated; an account you disabled by hand stays disabled.
The synchronization never deletes an account. An account still tracked and active through another rule is not disabled.
A brake protects against mass disabling. No orphan is handled, and the reason is written to the log, if:
- the directory read is incomplete (failed source, truncated result, entry that could not be processed);
- the directory returned no user;
- the share of orphans exceeds the rule's Orphan brake (%) (25 % by default, from 1 to 100).
Running and scheduling
Synchronize now runs the rule immediately. If a synchronization of this rule is already running (started by hand, by the schedule or by another instance), the message “A synchronization of this rule is already running.” appears and nothing is restarted.
The Schedule (cron) gives the rule its own task in the Scheduler. If it stays empty, the rule is picked up by the nightly sweep of the “AdSync” task, every night at 2 AM. This task is delivered disabled: enable it in the Scheduler for rules without their own schedule to run. An invalid cron expression is refused when saving.
If the rule targeted by a scheduled task has been deleted, the task history shows the code RuleNotFound with the rule identifier: delete the task or fix its parameters. The causes common to all tasks (database unreachable, timeout…) are described in "Scheduling tasks".
Following synchronizations
The rule's Recent synchronizations block gives, for each run, the date, the status (Success, PartialSuccess when there were partial errors, Error), the number of accounts created, updated, disabled and reactivated, the duration and the errors; when the Data grids module is installed, the grid adds the members added to and removed from groups. Click the number of errors (or double-click the grid row) to read the details, for example the reason for an orphan brake.
Deleting a rule
Delete rule removes the rule with its sources and mappings. A rule that already has a synchronization history cannot be deleted: deactivate it instead (clear Active).