• English

      • Synchronize User Data from LDAP

      Auth: LDAPProfessional Edition+

      Introduction

      The Auth: LDAP plugin can use an existing LDAP authenticator as a user data synchronization source. The synchronization source reuses the authenticator's LDAP connection, Bind DN, Search DN, search scope, and attribute mappings, then writes the resulting users and optional department hierarchy to NocoBase.

      Before you begin

      1. Install and enable the Auth: LDAP and User Data Synchronization plugins.
      2. Create and verify an LDAP authenticator. See Authentication: LDAP.
      3. Make sure the authenticator's attribute mappings include the fields needed by NocoBase, such as username or email, nickname, and phone number.

      Add an LDAP synchronization source

      Go to Users & Permissions > Synchronize, click Add new, and select LDAP as the type.

      Configure the following fields:

      FieldDescription
      Source nameA unique name for this synchronization source.
      EnabledEnables manual synchronization and LDAP synchronization tasks for this source.
      LDAP authenticatorThe existing LDAP authenticator whose connection and attribute mappings will be reused.
      Sync filterThe LDAP filter used to find users during synchronization. The default is (&(objectCategory=person)(objectClass=user)). Adjust it to match your directory schema.
      Size limitOptional maximum number of entries returned by an LDAP search. Leave it empty to use the LDAP server's default limit.
      Page sizeOptional page size for paged LDAP searches. Use this when the directory contains more entries than a single query can return.
      Sync departmentsAlso synchronizes the LDAP organizational hierarchy to NocoBase departments.
      Department search DNRequired when department synchronization is enabled. Specify the DN that contains the organizational units to synchronize, for example ou=departments,dc=example,dc=com.
      Info

      The synchronization source uses the selected authenticator's Bind DN and Bind password to search LDAP. It does not store a second copy of the LDAP connection credentials.

      Synchronize users

      Save and enable the source, then click Sync to start a full synchronization. Open Task to review the result and retry a failed task.

      User matching follows the field selected in the LDAP authenticator's Use this field to bind the user setting. Keep that setting and the authenticator's attribute mappings stable after the first synchronization to avoid creating duplicate users.

      Synchronize departments

      Enable Sync departments and enter a Department search DN when the LDAP directory contains a hierarchy that should be represented in NocoBase.

      The plugin searches organizational units below that DN, preserves their parent-child relationships, and associates users with departments based on their distinguished names. The configured Department search DN must cover the organizational units referenced by the users you expect to synchronize.

      Synchronized fields

      User fields

      User fields reuse the selected LDAP authenticator's Attribute mapping:

      LDAP attribute or settingNocoBase field or purpose
      Login account attributeUsed as the source-unique user identifier and written to the username or email selected by the authenticator's Use this field to bind the user setting. This attribute is usually inferred from {{account}} in the authenticator's search filter, such as uid, sAMAccountName, or mail. A user without this attribute is skipped.
      Attribute mapped to usernameUsername.
      Attribute mapped to nicknameUser nickname.
      Attribute mapped to emailEmail address.
      Attribute mapped to phonePhone number.
      distinguishedName, falling back to the entry DNFinds the nearest synchronized department in the DN path and sets it as the user's primary department. This applies only when department synchronization is enabled.

      For a multi-valued LDAP attribute, only the first value is currently synchronized. Other user attributes that are not included in the authenticator's attribute mapping are not synchronized.

      Department fields

      LDAP attribute or structureNocoBase field or purpose
      objectGUIDSource-unique department identifier. An organizational unit without this attribute is skipped.
      ou, cn, nameThe first non-empty value in this order becomes the department name. An organizational unit without a name is skipped.
      distinguishedName, falling back to the entry DNIdentifies the current department and its parent to build the department hierarchy.

      Department synchronization searches for organizationalUnit and container objects by default. It does not currently synchronize multiple user departments from attributes such as memberOf, or department owners.

      Troubleshooting

      • If no users are returned, verify the authenticator's Search DN, search scope, Bind DN permissions, and the synchronization filter.
      • If the result is truncated, configure a page size and verify the LDAP server's size limits.
      • If departments are missing, verify that department synchronization is enabled and the Department search DN covers the required organizational units.
      • Review the synchronization task details and application logs for LDAP connection, bind, and search errors.