Set up user sync with Active Directory (AD LDAP / OpenLDAP)
A guide for the UnSpot administrator and the directory administrator: how to connect employee synchronization from a local Active Directory or OpenLDAP, which fields to transfer and how to narrow the result. You connect it in Manage > Integrations > Synchronisations. The roles that may configure integrations are Super Administrator and Integrations Administrator. How the exchange itself works and what leaves the directory is covered in the companion article User sync with Active Directory (AD LDAP / OpenLDAP): how it works — that is also the one to hand to your information security team.
What you need
- An UnSpot role: Super Administrator or Integrations Administrator.
- Network access: the domain controller must accept inbound connections from the UnSpot addresses (request the current list from UnSpot support) on the LDAP or LDAPS port. Without it the form will not save — UnSpot tests the connection before writing the settings (on a later Edit the test runs only if a password is entered).
- A directory service account with read-only access to user, group and department objects.
- The DN of the container to search employees from.
- A free synchronization slot: only one method can be connected at a time — AD LDAP, OpenLDAP, Entra ID or Google Workspace. If another one is connected, disconnect it first.
Step 1. Connection parameters
Open Manage > Integrations > Synchronisations. The User synchronization block lists every method: AD LDAP, OpenLDAP, Entra ID (Azure AD), Google Workspace and SCIM 2.0 have a Connect button, while CSV and OpenID Connect open their own sections through a Go to settings link.
Click Connect on the AD LDAP card — the Synchronization settings dialog opens. Fill in the Connection parameters block:
| Field | What to enter |
|---|---|
| Host | The network address of the directory server with a protocol prefix — ldap:// or ldaps://. The form rejects an address without one. For example: ldaps://dc01.mycompany.com |
| DN | The distinguished name of the container to search users from. The example in the form is CN=Users, DC=mycompany, DC=com. The field is required: searching from the directory root is not possible |
| Port | 389 is filled in by default — for ldap:// and ldaps:// alike. If you connect over LDAPS, change it to 636 yourself. For a non-standard port, enter the actual value |
| Login | The account UnSpot will read the directory with. Read access is enough. The string is passed to bind as is — a UPN (svc-unspot@corp.local) or a full DN both work |
| Password | The password for that account. When you edit the settings later you may leave the field empty — the stored password is then kept. Note: with the field empty the form saves without testing the connection and the connection is marked healthy — to have the new settings tested, enter the password again |
We recommend ldaps:// and port 636. An ldap:// connection sends the login, the password and the directory contents over the network unencrypted. Note as well that UnSpot does not validate the directory server certificate — the companion article explains which compensating network controls are worth putting in place.
Step 2. Synchronization data
In the Synchronization data block, select the fields to transfer into the employee record. Email, First Name and Last Name are always selected and locked — the hint next to them reads that the data is required for synchronization and cannot be cancelled.
| Checkbox | Required | What is transferred |
|---|---|---|
| required | The employee login in UnSpot. Which attribute it comes from is covered in step 3 | |
| First Name | required | The givenName attribute |
| Last Name | required | The sn attribute |
| Department | optional | The department attribute. Mutually exclusive with organizational structure sync — see step 4 |
| Phone | optional | The telephoneNumber attribute |
| Position | optional | The title attribute. Values longer than 128 characters are truncated |
| Manager | optional | The manager attribute. In UnSpot the link is built by email address, so the manager record has to be part of the result as well |
| User profile picture | optional | The thumbnailPhoto attribute. Photos are transferred by a separate job: it starts right away when the integration is connected and when the checkbox is switched on, and later photo changes in the directory are picked up on the platform schedule; the daily cycle and the manual run button do not refresh photos |
| NumberPass | optional | The access control system (PACS) badge number, needed for PACS integrations and the Visitors module. Read from the numberPass attribute; this is not a standard directory schema attribute, so you have to create it yourself |
Step 3. Main attribute and user filter
In Please select the main attribute, choose which directory attribute counts as the employee email address: userPrincipalName or Email(mail). UnSpot matches directory entries to employee records by that value, so it has to be filled in for the users you synchronize. Entries without userPrincipalName are skipped regardless of the choice.
Filter for users narrows the result with a standard LDAP filter of up to 255 characters. Write the filter with its own brackets — it is inserted into the overall condition as is. To synchronize only the members of one group:
(memberOf=CN=UnSpotUsers,OU=Groups,DC=mycompany,DC=com)
With an empty filter, every matching object inside the given DN is synchronized. Check the limit on returned entries on your domain controller — in Active Directory that is MaxPageSize, 1000 by default. UnSpot reads the result in a single request, and if the directory returns it incomplete, the missing employees look as though they were deleted from the directory: their records are archived and their bookings cancelled. Keep the filter narrow enough to fit the limit.
Step 4. Groups and organizational structure
Further down the form there are two independent blocks, each with its own checkbox and filter. The filter fields are always visible but stay inactive until the checkbox is on.
| Block | Checkbox | Filter | What it does |
|---|---|---|---|
| Groups | Synchronisation of groups | Filter for groups | Directory groups are transferred into UnSpot groups, where they can be used in booking policies, locker access and permissions. The directory owns membership: synchronized employees added to such a group by hand are removed from it on the next cycle; records created in UnSpot manually and not linked to the directory are not affected. A group that drops out of the directory or out of the group filter is deleted from UnSpot entirely — together with its role in booking policies and access rights |
| Organizational structure | Organizational structure sync | Organizational structure filter | The department tree is transferred from the directory. For Active Directory the head of the department is transferred as well, from the managedBy attribute |
Department and Organizational structure sync are mutually exclusive. You cannot enable both: an employee department is filled from a single source. The form blocks the second option, and an attempt to save both is rejected.
The department tree is not refreshed on every cycle. It is read when the integration is connected and when the organizational structure checkbox is switched on. Neither the daily cycle nor the Update on-premise AD button touches it, so after a reorganization in the directory clear the checkbox and select it again.
Step 5. Welcome emails
The Send welcome emails toggle controls onboarding: after creating a user, an email with brief instructions will be sent to the user. The toggle is off by default. If you would rather set the workspace up first and invite people later, leave it off. Click Save: UnSpot tests the directory connection and starts the first exchange.
What is available after connecting
The card shows the connection address and the list of synchronization fields. From then on the synchronization runs automatically, once a day on the platform schedule. The buttons on the card:
| Button | When it is available | What it does |
|---|---|---|
| Update on-premise AD (Update on-premise on the OpenLDAP card) | while the connection is healthy, at most once an hour | Starts the exchange manually: users, groups and group membership. It does not refresh photos or the department tree. After you click it the button is disabled and the hint shows when the next run will be available |
| Edit | while the connection is healthy | Opens the settings: connection parameters, field set, filters, group and structure checkboxes. Newly added checkboxes apply right away — UnSpot starts an unscheduled exchange without waiting for the daily cycle; clearing a checkbox takes effect from the next cycle. This is also how you change the service account password — reconnecting is not needed for that |
| Reconnect | only while the connection is flagged as invalid — the card then reads that the account is not valid and asks you to reconnect it or use another one | Disconnects the integration and connects it again. It clears the settings and the links between directory entries and UnSpot records, after which objects are matched again by email address. If you only need to change the password, use Edit |
| Disconnect | always | Stops the synchronization. Employee records and the groups that were created stay in UnSpot, but the links to directory entries and the synced flag on departments are removed (when SCIM provisioning is connected in parallel, the flag on departments is kept) |
How the OpenLDAP card differs
Next to AD LDAP there is a separate OpenLDAP card, for OpenLDAP and compatible directories. The settings form is the same, the manual run button is called Update on-premise and is limited to one run per hour in the same way. The differences an administrator will notice:
| What | AD LDAP | OpenLDAP |
|---|---|---|
| User object class | objectClass=user | objectClass=inetOrgPerson |
| Group object class | objectClass=group | objectClass=posixGroup — gidNumber and cn are required |
| First option under “main attribute” | labelled userPrincipalName, and that is what is read | labelled userName, but uid is what is actually read |
| Mandatory entry attributes | userPrincipalName | uidNumber and mail — an entry missing either is skipped |
| Department attribute | department | departmentNumber |
| Photo attribute | thumbnailPhoto | jpegPhoto |
| Disabled accounts | filtered out automatically | not filtered — exclude them with the filter |
| Head of department | transferred | not transferred |
Ready-made templates for the OpenLDAP user filter. Members of two groups (the memberOf overlay must be enabled): (|(memberOf=cn=unspot-users,ou=groups,dc=example,dc=com)(memberOf=cn=contractors,ou=groups,dc=example,dc=com)). Excluding blocked accounts depends on your schema attribute — for example (!(nsAccountLock=TRUE)) in 389 Directory Server and FreeIPA. Remember that the filter is inserted into the service query together with its own brackets.
If something does not work
| What you see | Why | What to do |
|---|---|---|
| A message that the server could not be reached, asking you to check the host or port | UnSpot did not reach the directory | Check the address and the port, and that the firewall lets inbound connections from the UnSpot addresses through. A common cause is port 389 left at its default while the scheme is ldaps://. UnSpot waits 5 seconds for the directory to answer — on a slow link the check can fail even though the directory is alive |
| A message about incorrect connection credentials | The directory rejected the login or password | Check the service account, that it is not locked and that its password has not expired |
| Please enter host beginning with ldap:// or ldaps:// | The Host field has no protocol prefix | Add ldap:// or ldaps:// |
| A message that user synchronization is already connected through another directory service | Another synchronization method is already connected | Disconnect it first, then connect this one |
| A message that the synchronization time has not come yet | The manual run was less than an hour ago | Wait until the time shown in the button hint |
| A message that department and organizational structure cannot be synchronized at the same time | Both mutually exclusive settings are selected | Keep one of them — see step 4 |
| Not all employees were synchronized | The result was incomplete: the main attribute is empty, the entry was excluded by the filter, or the server-side entry limit kicked in | Check the filter and MaxPageSize on the domain controller. Missing employees are not merely skipped — they are archived, and their bookings are cancelled |
| The department tree is out of date | The organizational structure is not part of the daily cycle | Clear the Organizational structure sync checkbox and select it again |
| Avatars did not appear | Photos are moved by a separate job: an unscheduled run starts right after connecting or ticking the checkbox, later changes follow the platform schedule | If photos are missing right after you ticked the checkbox, check the account permissions on thumbnailPhoto; a photo changed in the directory appears after the next run of the job |
Changes made by the synchronization are visible in Analytics > Reports, the User management history report: such entries carry a synchronization marker in the initiator column.
