Synchronization with the LDAP directory

LDAP (Lightweight Directory Access Protocol) is an application layer protocol for directory service access.

The directory service (LDAP directories) is a hierarchically structured system for storing key-value data. Usually directory services are used to store information about an organization, its assets and users. There are different implementations of LDAP directories. For example, OpenLDAP and FreeIPA for Linux, Microsoft Active Directory for Windows etc.

You can configure the platform to synchronize with one or more LDAP directories. User accounts from the directories will then be automatically created on the platform. When configuring synchronization, you specify the matching of LDAP DN groups to roles in the platform. For each VMmanager role, you can configure synchronization with one or more DN groups.

Work logic

The platform starts synchronization with the LDAP directories at intervals specified in the settings. During synchronization, the platform connects with specified parameters to the LDAP directory and receives a list of users. Information about users in the LDAP directory has a higher priority than the information in the platform.

Synchronization rules:

1. If a user in the LDAP directory does not have an email address, their account will not be used during synchronization. 
   This rule applies if synchronization was configured in a platform version lower than 2025.10.1 or if migration to the new user name scheme was not performed. For more details, see Synchronization with multiple LDAP directories section.
2. If an Active Directory user is not a member of the Users group, their account will not be used during synchronization.
3. f a user from the LDAP directory is not present in the platform, the platform will create an account with LDAP data.
4. If a user from the LDAP directory is already created in the platform, the platform will change the user account source from local to LDAP. After that, the user will be able to authorize in the platform with email and password from LDAP. The user's password will be stored in LDAP and will not be recorded in the platform database. The administrator will not be able to change the user's password using the platform means. 
   Example

   For example, an account with the name admin@example.com and the password secret1 has been created in the platform. In LDAP, there is an account with the name admin@example.com and the password secret2. After synchronization, the user admin@example.com will only be able to log in to the platform with the password secret2.
5. The platform does not change the account level to data from LDAP. Regardless of which group the account is in in LDAP, the account level is set in the platform in the LDAP synchronization settings (matching the DN of the LDAP group to the role in the platform).
6. If the administrator deletes from the platform the user created during synchronization with LDAP, the platform will create this user during the next synchronization.
7. If a user is deleted from the LDAP directory, the platform will set their status to "Blocked". Such a user will not be able to log in to the platform.
8. If a user is blocked in the LDAP directory, the platform will set their status to "Blocked in LDAP". Such a user will not be able to log in to the platform.
   

Synchronization with multiple LDAP directories

Starting with VMmanager version 2025.10.1, the platform supports synchronization with multiple LDAP directories.

Before version 2025.10.1, the mail attribute (email address) from LDAP was used as the username. Starting with version 2025.10.1, the username is formed using the username@domain format, where:

• username — user login in LDAP:
  • for standard LDAP implementation and FreeIPA — the uid attribute;
  • for Active Directory — the sAMAccountName attribute;
• domain — LDAP server domain.

For example, for a DN record in LDAP of the form uid=admin,cn=users,cn=accounts,dc=example,dc=com, the username admin@example.com will be created.

If synchronization with LDAP has already been configured in a platform version lower than 2025.10.1 and you need to connect another directory, there may be problems with the correct identification of user names. To avoid these problems, migrate to the new user name scheme. To migrate, use the curl utility or Swagger to make theAPI request:

POST /auth/v4/ldap/{ldap_id}/migrate

Comments:

• {ldap_id} — id of the existing connection to LDAP. Displayed in the Synchronization with LDAP section in the id column.

During migration, all existing users from LDAP will be renamed using the new scheme.

Preparation

Before synchronization, we recommend creating an administrator account on the platform with a login and domain that do not exist in LDAP. This will help to restore access to the platform if after synchronization the administrator account is blocked for some reason.

If the LDAP server has a self-signed SSL certificate

The connection to LDAP will fail if an SSL connection is required and a self-signed SSL certificate is installed on the server. To prevent connection errors, follow these steps before configuring synchronization:

1. Connect to the server with the platform via SSH. For more information about connecting via SSH, see Workstation setup.

2. Create a directory for LDAP configuration: 

   mkdir /opt/ispsystem/ldap/

3. Determine the OS version inside the container with LDAP service: 

   docker inspect auth | grep docker-registry

   The OS version will be specified in the last segment of the output. Example of command output for a container with AlmaLinux 8.9:

   "Image": "docker-registry.ispsystem.com/ispsystem/experimental/auth/alma:8.9"

4. For LDAP container with Debian OS:
   1. Create a file named ldap.conf in the /opt/ispsystem/ldap/ directory with the following content: 

      TLS_CACERT  /etc/ssl/certs/ca-certificates.crt
      TLS_REQCERT never

   2. Create a patch file /opt/ispsystem/ldap.yaml with the following content: 

      version: "3.5"
      services:
        auth_back4:
          volumes:
          - /opt/ispsystem/ldap/:/etc/ldap/

5. For LDAP container with AlmaLinux OS:

   1. Create a file named ldap.conf in the /opt/ispsystem/ldap/ directory with the following content:

      TLS_CACERT    /etc/ssl/certs/ca-bundle.crt   
      TLS_REQCERT never

   2. Create a patch file /opt/ispsystem/ldap.yaml with the following content:

      version: "3.5"
      services:
        auth_back4:
          volumes:
          - /opt/ispsystem/ldap/:/etc/openldap/

6. Apply the patch for the LDAP service: 

   vm add-patch -p=LDAP -f /opt/ispsystem/ldap.yaml

vm remove-patch -p=LDAP

Synchronization setup

To manage synchronization with LDAP, click the icon in the right menu → Synchronization with LDAP.

Section interface

Creating a connection

To create an LDAP connection, click the Add connection button and specify its settings:

1. Select the LDAP directory implementation:
   • LDAP — a standard directory service implementation;
   • Active Directory;
   • FreeIPA.
2. Specify the connection settings:
   1. Base DN — the directory object from which the search begins. For example, for the example.com directory, specify "dc=example,dc=com".
   2. For SSL connection, enable the Use SSL to connect option.
   3. Main server address.
   4. Connection Port.
   5. Bind DN — unique name for authentication. You can specify the name in the format name@example.com or "cn=name,ou=group,dc=example,dc=com".
   6. Password.
   7. For a standard LDAP implementation, specify the following:
      1. Users DN — parameter for searching and downloading users. For example, "ou=users".
      2. Groups DN — parameter for searching and downloading user groups. For example, "ou=groups".
      3. Groupname attribute — attribute for loading the group name. For example, CN or memberof.
      4. E-mail attribute — attribute for downloading the user's email address. For example, mail.
   8. Specify an arbitrary Note.
      
3. Click  Next. The platform will check the connection to the LDAP directory with the specified parameters.
4. Select which DN groups will match each Role in platform. To add a rule, click the Add group button. To delete a rule, click the icon.
5. For the platform to perform synchronization on a schedule:
   1. Enable the Synchronize users automatically option.
   2. Select the schedule parameters:
      • Hourly;
      • Daily → select the time;
      • Weekly → select the day → select the time;
      • arbitrary time in the cron format → specify the Cron c ommand. For example, 15 10 * * * 0 — synchronize on Sundays at 10:15 or 00 12 1,16 * * * — synchronize on the 1st and 16th of the month at 12:00.
6. To check which users will be synchronized, click the Download list of users for synchronization button. The list contains user names, their roles, and information about whether such users have been created on the platform.
7. Click Start synchronization button. The platform will start the synchronization process. The synchronization time depends on the number of users in LDAP and may take several minutes.
   
   

Managing connections

Connections are managed via the menu in the connection row. Possible actions:

• Edit — go to the connection card. To perform this action, you can also click on the connection name in the table. In the connection card, you can change its settings and synchronization rules;
• Synchronize — perform resynchronization;
• Note — change the note;
• Delete.

User authorization

The user authorization process depends on the number of LDAP directories with which the platform is synchronized:

• single directory or none — the user enters their username in the format username@domain and their password;
• two or more directories — the user enters their name in the format username or username@domain, selects the LDAP directory, and enters their password.

Diagnostics

Interaction with LDAP is handled by the auth service. Synchronization log files are stored on the server with the platform in the stdout of the auth container. 

To see detailed information about LDAP operation:

1. Connect to the server with the platform via SSH. For more information about connecting via SSH, see Workstation setup.
2. Set the DEBUG logging level for the auth container:

   sudo docker exec -it vm_box curl -k 'http://input:1500/auth/v4/internal/settings/log/level' -H 'internal-auth: on' -d "debug"

You can change the saved settings under → Synchronization with LDAP .

To synchronize manually, enter → Synchronization with LDAP → Synchronize now or Users → Synchronize with LDAP → Start synchronization.