Синхронизация пользователей и групп с каталогом LDAP

Если в вашей компании развернута служба федерации Active Directory, вы можете настроить ее автоматическую синхронизацию сотрудников и групп с Яндекс 360 для бизнеса — для этого нужно установить и настроить специальную службу Windows.

Внимание. Если вы хотите подключить синхронизацию пользователей из Active Directory, установите YandexADSCIM (утилита в виде службы Windows на компьютере) по инструкции ниже и запустите программу от имени пользователя с правами чтения из каталога LDAP. YandexADSCIM управляется через оснастку Сервисы. Настройки меняются в конфигурационном файле.

Другие каталоги LDAP будут полноценно поддержаны в будущем, когда утилита YandexADSCIM будет портирована на *nix платформы. Сейчас ее можно использовать для настройки работы с другими каталогами LDAP, но запускать нужно на устройстве с OC Windows.

Подключить и настроить утилиту ADSCIM

Шаг 1. Начните настройку

Проверьте, что единый вход (SSO) подключен и правильно работает .
Задайте уникальный идентификатор пользователя — выберите атрибут Active Directory для передачи в настройке утилиты ADSCIM PropertyLoginName, чтобы внести его в каталог Яндекс.
Внимание. Атрибут, который вы зададите в качестве основного идентификатора, не должен меняться. Пользователь с другим атрибутом при входе будет считаться новым пользователем.
Если ваши пользователи уже используют сервисы Яндекс 360 и проходят аутентификацию с помощью протокола SAML 2.0, например, в Active Directory или Keycloak, убедитесь, что указанное в поле Incoming claim type значение атрибута NameID совпадает с основным идентификатором PropertyLoginName:
- UserPrincipalName (UPN) – если параметры входа не будут меняться;
- objectSID — только если запланированы изменения домена или бизнес-процессов.
Больше информации про PropertyLoginName см. в шаге 4, п. 2.5, в тексте Подробнее.
Проверьте, что у пользователей в Active Directory заполнены атрибуты:
- идентификатор, выбранный в качестве основного;
- User SamAccountName;
- E-mail.

Шаг 2. Получите Client ID и OAuth-токен

Перейдите на страницу создания приложения.
Введите название сервиса и прикрепите его иконку.
В блоке Платформы приложения выберите Веб-сервисы. В поле Redirect URI нажмите ссылку Подставить URL для отладки.
В блоке Доступ к данным в начале строки введите название доступа Управление федерациями.
Укажите почту для связи. Внизу страницы нажмите Создать приложение.
Отправьте POST-запрос, чтобы получить OAuth-токен. Например, через cURL это можно сделать при помощи следующей команды:
```
curl -X POST https://oauth.yandex.ru/token -d "grant_type=client_credentials&client_id=значение1&client_secret=значение2"
Скопировано
```
(значение параметра client_id — это ID созданного приложения, а client_secret — его Пароль)
Сохраните полученные ID и OAuth-токен. Они пригодятся на следующих шагах.

Шаг 3. Укажите Client ID в Яндекс 360 и получите Domain ID

Откройте Яндекс 360 для бизнеса.
Перейдите на вкладку Единый вход (SSO).
Нажмите Настроить.
В блоке Синхронизация SCIM вставьте ID вашего приложения, полученный на шаге 2.
Скопируйте ваш Domain ID, он пригодится на следующем шаге.
Сохраните изменения.

Шаг 4. Установите и настройте службу Windows для синхронизации

Скачайте и установите службу YandexADSCIM.

Найдите и откройте в любом текстовом редакторе конфигурационный файл — %ProgramData%\Yandex\YandexADSCIM\AD_Users.config

Совет. Если найти папку %ProgramData% не получается, включите отображение скрытых файлов.

Настройте конфигурационный файл:

Проверьте, верно ли указан путь для подключения к Active Directory в значении параметра LDAP. Если нет, исправьте его.
В значении параметра BearerToken укажите OAuth-токен, полученный на шаге 2.
В значении параметра DomainID укажите ID домена, полученный на шаге 3.
Поменяйте значение параметра DryRun на false, если хотите запустить синхронизацию SCIM уже сейчас. Со значением true служба будет работать в тестовом режиме, фиксируя запросы в логах, но не синхронизируя сотрудников и группы.

Синхронизируйте типовой набор пользовательских данных из Active Directory. При этом строки, которые начинаются с символа #, приложение проигнорирует.


Название настройки утилиты YandexADSCIM	Название атрибута (рус)	Значение по умолчанию из Active Directory	Пример
PropertyFirstName	Имя	givenName	Иван
PropertyMiddleName	Отчество	middleName	Иванович
PropertyLastName	Фамилия	sn (SurName)	Иванов
PropertyWorkMail	Основная почта	mail	I_ivanov@domain.ru
PropertyTitle	Должность	Title	Разработчик


Название настройки утилиты YandexADSCIM	Название атрибута (рус)	Значение по умолчанию из Active Directory	Пример
PropertyFirstName	Имя	givenName	Иван
PropertyMiddleName	Отчество	middleName	Иванович
PropertyLastName	Фамилия	sn (SurName)	Иванов
PropertyWorkMail	Основная почта	mail	I_ivanov@domain.ru
PropertyTitle	Должность	Title	Разработчик

Атрибуты, которые начинаются с Property, позволяют переназначить параметры при создании или синхронизации пользователей в Яндекс 360.

Подробнее

PropertyLoginName = objectSID/objectGUID/UPN, где UPN — значение по умолчанию. Если вы используете атрибут вида username, а не username@domain.com, нужно добавить ключ IgnoreUsernameDomain = true. Значение этого атрибута должно быть равно значению атрибута NameID в поле Incoming claim type из настроек единого входа (SSO):

PropertyFirstName = User first name
PropertyMiddleName = User middle name
PropertyLastName = User last name
PropertyDisplayName = User display name
PropertyWorkMail = User e-mail
PropertyTitle = User job title
PropertyMobilePhoneNumber = Mobile phone number
PropertyWorkPhoneNumber = Work phone number
PropertyIpPhoneNumber = User ip phone number

Параметры, которые начинаются с Property, можно указывать несколько раз — в этом случае значением параметра будет список.

Например, для получения фамилии пользователя можно задать атрибуты: PropertyLastName = surName, PropertyLastName = sn, PropertyLastName = lastName. Если существует атрибут surName, будет использовано его значение. Если этого атрибута нет, будет использовано значение атрибута sn. Если он также отсутствует — значение атрибута lastName.

Если нужно, чтобы алиасы почтовых ящиков из Active Directory синхронизировались с Яндекс 360 для бизнеса, добавьте параметр EnableAliases со значением true. Доменные почтовые алиасы, которые указаны в Active Directory в атрибуте пользователя proxyAdresses с типом SMTP, добавятся в аккаунт сотрудника в Яндекс 360 для бизнеса автоматически.

Важно. Для корректной синхронизации алиасов версия утилиты YandexADSCIM должна быть 1.1.0.144 или выше.
Создайте адрес LDAP каталога — подставьте в поисковые параметры собственные значения.
Для поискового запроса используйте путь из структуры DIT = Directory Information Tree (читается справа налево): LDAP = LDAP://CN=Users,OU=DomainGroup,DC=YourCompanyName,DC=com
- DC – domainComponent, собственный домен и доменная зона;
- OU – OrganizationUnit, компания\департамент\отдел, из которого вы хотите получить пользователей;
- CN – commonName, наименование объекта, который хотите получить из каталога.
Чтобы ограничить выгрузку пользователей, можно воспользоваться фильтром UsersFilterи применить стандартный синтаксис запросов LDAP:
UsersFilter =(memberOf=CN=groupname,CN=Users,DC=domainname,DC=com)
Синхронизируйте группы из Active Directory — добавьте параметр EnableGroups со значением true.

Чтобы ограничить список групп, можно воспользоваться фильтром GroupsFilter и применить стандартный синтаксис запросов LDAP. Например, чтобы выгрузить все списки рассылок, используйте фильтр:

GroupsFilter =(&(objectClass=group)(!(groupType:1.2.840.113556.1.4.803:=2147483648)))

Синхронизируйте типовой набор атрибутов групп из Active Directory.


Название настройки утилиты YandexADSCIM	Название атрибута (рус)	Значение по умолчанию из Active Directory	Пример
PropertyGroupDisplayName	Название	name	Проект интеграции
PropertyGroupDescription	Описание	description	Сотрудники, участвующие в проекте интеграции
PropertyGroupEmail	Рассылка	mail	int@domain.ru


Название настройки утилиты YandexADSCIM	Название атрибута (рус)	Значение по умолчанию из Active Directory	Пример
PropertyGroupDisplayName	Название	name	Проект интеграции
PropertyGroupDescription	Описание	description	Сотрудники, участвующие в проекте интеграции
PropertyGroupEmail	Рассылка	mail	int@domain.ru

Атрибуты, которые начинаются с Property, позволяют переназначить параметры при создании или синхронизации групп в Яндекс 360.

Подробнее

Такие параметры можно указывать несколько раз — в этом случае значением параметра будет список.

Например, для получения названия группы можно задать атрибуты: PropertyGroupDisplayName = name, PropertyGroupDisplayName = cn. Если существует атрибут name, будет использовано его значение. Если этого атрибута нет, будет использовано значение атрибута cn.

Поменяйте значение параметра DryRun на true перед первым запуском сервиса. Периодичность запуска сервиса определяется параметром UpdateEveryMins = N, где N – интервал в минутах. Запустите сервис через оснастку и проанализируйте файл лога.

Системные сообщения в логах


Уведомление	Результат
CORE Update user: user@domain.ru (Active:true -> false)	Пользователь будет заблокирован.
SCIM Update user	Изменение атрибутов пользователя в каталоге Яндекс.
SCIM Add user	Добавление пользователя в каталог Яндекс.
CORE Users: added 0, removed 3237, modified 0	Добавлено – 0, заблокировано – 3237, изменено - 0.
SCIM GET Users: Response is successful	Пользователи успешно зачитаны из каталога Яндекс.
AD Received user count: N	Из Active Directory загружено N пользователей.
AD Received groups count: N	Из Active Directory загружено N групп.
AD_CONFIG Wrong line N	Ошибка в строке 31 конфигурационного файла.


Уведомление	Результат
CORE Update user: user@domain.ru (Active:true -> false)	Пользователь будет заблокирован.
SCIM Update user	Изменение атрибутов пользователя в каталоге Яндекс.
SCIM Add user	Добавление пользователя в каталог Яндекс.
CORE Users: added 0, removed 3237, modified 0	Добавлено – 0, заблокировано – 3237, изменено - 0.
SCIM GET Users: Response is successful	Пользователи успешно зачитаны из каталога Яндекс.
AD Received user count: N	Из Active Directory загружено N пользователей.
AD Received groups count: N	Из Active Directory загружено N групп.
AD_CONFIG Wrong line N	Ошибка в строке 31 конфигурационного файла.

Остановите службу и запустите снова, чтобы применить изменения из конфигурационного файла. Для этого в командной строке (cmd.exe) введите sc stop yandexadscim, а затем — sc start yandexadscim. Также вы можете сделать это в диспетчере задач на вкладке Службы.

Изменить настройки

Если вы хотите изменить настройки, внесите изменения в конфигурационный файл, а затем перезагрузите службу YandexADSCIM через командную строку или диспетчер задач.

Просмотреть логи

Все логи службы сохраняются в папке %ProgramData%\Yandex\YandexADSCIM.

Остановить службу

YandexADSCIM — это служба Windows, поэтому исполняется автоматически при запуске системы и не зависит от статуса пользователя. Но вы можете отключить ее вручную — для этого в командной строке введите sc stop yandexadscim или в диспетчере задач нажмите Остановить.

Если же вы хотите удалить службу насовсем, используйте команду sc delete yandexadscim.

Возможные ситуации при работе сервиса


Ситуация	Результат
У пользователя изменились атрибуты в Active Directory, но при этом уникальный идентификатор не изменился.	Система обновит атрибуты в каталоге Яндекс (кроме основной почты и NameID).
У пользователя изменился уникальный идентификатор.	Система не сможет найти объект с исходным идентификатором и заблокирует предыдущего пользователя. Далее система попытается добавить пользователя с новым идентификатором, но не сможет этого сделать, так как логин пользователя уже занят предыдущим. Если удалить заблокированного пользователя, система добавит нового без переноса каких-либо данных со старого.
Пользователь удален в Active Directory.	Пользователь будет заблокирован в каталоге Яндекс.
Новый пользователь в Active Directory.	Пользователь будет добавлен в каталог Яндекс с соответствующими атрибутами.
Все пользователи в каталоге Яндекс заблокированы.	Это могло произойти, если: изменилось поле основного идентификатора; по какой-то причине приложение не смогло прочитать пользователей в каталоге Active Directory.


Ситуация	Результат
У пользователя изменились атрибуты в Active Directory, но при этом уникальный идентификатор не изменился.	Система обновит атрибуты в каталоге Яндекс (кроме основной почты и NameID).
У пользователя изменился уникальный идентификатор.	Система не сможет найти объект с исходным идентификатором и заблокирует предыдущего пользователя. Далее система попытается добавить пользователя с новым идентификатором, но не сможет этого сделать, так как логин пользователя уже занят предыдущим. Если удалить заблокированного пользователя, система добавит нового без переноса каких-либо данных со старого.
Пользователь удален в Active Directory.	Пользователь будет заблокирован в каталоге Яндекс.
Новый пользователь в Active Directory.	Пользователь будет добавлен в каталог Яндекс с соответствующими атрибутами.
Все пользователи в каталоге Яндекс заблокированы.	Это могло произойти, если: изменилось поле основного идентификатора; по какой-то причине приложение не смогло прочитать пользователей в каталоге Active Directory.

Обновление приложения

Приложение обновляется автоматически: по умолчанию в конфигурационном файле указано значение AutoUpdate = True либо его нет.

Если вы хотите обновлять приложение вручную, измените значение на AutoUpdate = False или добавьте его. Чтобы обновить приложение, вам нужно будет скачать последнюю версию YandexADSCIM и запустить установочный файл.