XO usernames (emails) should be unique. If an LDAP user signs in with a username that already exists in XO — whether a local account or from another provider — the LDAP identity is automatically linked to that existing account. The user keeps their existing permissions and settings.

Note: if several users have the same email address in different LDAP forest, it can lead to undefined behaviours.

If authentication.mergeProvidersUsers is enabled, it will silently merge the associated users.

If authentication.mergeProvidersUsers is disabled, it will throw an error.

If you have issues, you can use the provided CLI to gather more information:

> xo-server-auth-ldap
? uri ldap://ldap.company.net
? fill optional certificateAuthorities? No
? fill optional checkCertificate? No
? fill optional bind? No
? base ou=people,dc=company,dc=net
? fill optional filter? No
configuration saved in ./ldap.cache.conf
? Username john.smith
? Password *****
searching for entries...
0 entries found
could not authenticate john.smith

Failover URIs

If the primary URI is unreachable (firewall drop, host down, TCP reset), XO will retry each configured failover URI in order and use the first one that responds.

Note: all failover servers must share the same credentials and directory structure as the primary. Failover only covers TCP-level failures, authentication errors and search errors are not retried.

Additional domains (multi-forest)

The additionalDomains field lets you connect XO to multiple independent LDAP/AD forests. Each domain has its own URI, base, credentials, and group configuration.

Authentication flow: XO tries the primary domain first. If the user is not found there, it falls through to each additional domain in order. If the same username exists in both the primary and an additional domain, the primary always wins and the additional domain's entry is never reached.

Group sync: Groups are scoped per domain. Primary-domain groups keep their bare LDAP names for backward compatibility. Additional-domain groups are suffixed with the domain URI to avoid collisions, since the same group name (e.g. Developers) can exist in multiple forests.

Example of group sync in XO between two forests:

Primary domain (ldap://corp.net)

LDAP group: Developers -> XO group: Developers
LDAP group: Admins -> XO group: Admins

Additional domain (ldap://acme.net):

LDAP group: Developers -> XO group: Developers (ldap://acme.net)
LDAP group: Finance -> XO group: Finance (ldap://acme.net)

Note:

A primary-domain group named Developers and an additional-domain group named Developers are two distinct XO groups with different members. They do not merge.

Failover URIs within a domain are for high-availability only, not for cross-forest access. All failover URIs for a domain must replicate the same directory.

Removing a domain from the configuration does not delete the XO groups it created. Clean them up manually if needed.

Algorithm

If bind is defined, attempt to bind using this user.
Searches for the user in the directory starting from the base with the defined filter.
If found, a bind is attempted using the distinguished name of this user and the provided password.

Contributions

Contributions are very welcomed, either on the documentation or on the code.

You may:

report any issue you've encountered;
fork and create a pull request.

README.md

xo-server-auth-ldap

Usage

User email uniqueness

Failover URIs

Additional domains (multi-forest)

Example of group sync in XO between two forests:

Algorithm

Contributions

License