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 set up synchronization of the platform with the LDAP directory. Then user accounts from the directory will be automatically created in the platform.

Work logic

The platform starts synchronization with the LDAP directory 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.

General synchronization rules:

If a user in the LDAP directory does not have an email address, their account will not be used during synchronization.
If a user from the LDAP directory is not present in the platform, the platform will create an account with LDAP data.
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.
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.
If the LDAP directory user has already been created in the platform, the platform will change the account level to LDAP data.
Example: An account with the name admin@example.com with the "Administrator” level has been created in the platform. In LDAP, there is an account with the name admin@example.com in the “Users” group. After synchronization, the account level will change to "User". If the user is the owner of the servers or VMs, operations with these objects will remain available to him.
If the administrator deletes from the platform the user created during synchronization with LDAP, the platform will create this user during the next synchronization.
If a user is deleted from the LDAP directory, the platform will delete his account during the next synchronization.
If a user is blocked in the LDAP directory, the platform will set his status to "Blocked in LDAP". Such a user will not be able to log in to the platform.

If you remove the configured synchronization, users from the LDAP directory will not be able to log in to the platform.

Preparation

If the LDAP server has a self-signed SSL certificate

If an SSL connection is required to connect to LDAP and a self-signed SSL certificate is installed on the server, the connection will fail.

To avoid connection errors, perform the following steps before configuring synchronization:

Connect to the server with the platform via SSH.
Create a directory for LDAP configuration:
```
mkdir /opt/ispsystem/ldap
```
Create an ldap.conf file in the /opt/ispsystem/ldap/ directory with the following content:
```
TLS_CACERT	/etc/ssl/certs/ca-certificates.crt
TLS_REQCERT never
```

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

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

Apply the patch to the LDAP service:

VMmanager

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

DCImanager 6

/usr/local/bin/dci add-patch -p=LDAP -f /opt/ispsystem/ldap.yaml

Synchronization setup

To configure synchronization, enter → Synchronization with LDAP:

Select the LDAP directory implementation:
1. LDAP — a standard directory service implementation;
2. Active Directory;
3. FreeIPA;
4. ALD Pro (available only in DCImanager 6 Infrastructure).
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. If necessary, 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.
Press Next. The platform will check the connection to the LDAP directory with the specified parameters.
Select DN groups for all roles used in the platform.
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 command. 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.
You can Download a full list of users to synchronization . The list contains the names of users, their roles and information about the presence of similar users in the platform.
Press Start synchronization. The platform will start the synchronization process. Synchronization can take several minutes.

Example of configuration

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.

Synchronization via API

To configure synchronization, use API of the LDAP service.

Connection settings example

Check the connection and get a list of groups:
```
curl -ks -X 'POST' \
  'https://domain.com/api/ldap/v4/connect' \
  -H 'Cookie: ses6=<auth_token>' \
  -H 'x-xsrf-token: <auth_token>' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "ldap",
  "base_dn": "dc=example,dc=com",
  "address": "192.168.0.5",
  "port": 389,
  "is_ssl": false,
  "bind_dn": "cn=admin,dc=example,dc=com",
  "password": "secret",
  "users_dn": "cn=users",
  "groups_dn": "cn=groups",
  "groupname_attr": "memberOf",
  "email_attr": "mail"
}'
```
Comments to the command

domain.com — IP address or domain name of the server with the platform
<auth_token> — authorization token
type — LDAP directory implementation
base_dn — directory object from which the search begins
address — IP address of the main server
port — connection port
is_ssl — "Use SSL to connect" option
bind_dn — unique name for authentication
password — LDAP administrator's password
users_dn — parameter for searching and downloading users
groups_dn — parameter for searching and downloading user groups
groupname_attr — attribute for loading the group name
email_attr — attribute for downloading the user's email address

Finish creating the connection:

curl -ks -X 'POST' \
  'https://domain.com/ldap/v4/setting' \
  -H 'Cookie: ses6=<auth_token>' \
  -H 'x-xsrf-token: <auth_token>' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "ldap",
  "base_dn": "dc=example,dc=com",
  "address": "192.168.0.5",
  "port": 389,
  "is_ssl": false,
  "bind_dn": "cn=admin,dc=example,dc=com",
  "password": "secret",
  "groups_bind": {
      "@admin": [
        "cn=admins,cn=groups,cn=accounts,dc=example,dc=com",
        "cn=devops,cn=groups,cn=accounts,dc=example,dc=com"
      ],
      "@user": [
            "cn=support,cn=groups,cn=accounts,dc=example,dc=com",
            "cn=developer,cn=groups,cn=accounts,dc=example,dc=com"
      ]
  },
  "auto_sync": "0 * * * *"
}'

Comments to the command

Diagnostics

Synchronization log files are stored on the server with the platform:

DCImanager 6 — /var/log/isp_ldap.log file in the dci_ldap_1 container;
VMmanager — /var/log/isp_ldap.log file in the vm_ldap_1 container.

Useful tips