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

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

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

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

1. Проверьте, что единый вход (SSO) подключен и правильно работает.

2. Задайте уникальный идентификатор пользователя — выберите атрибут Active Directory для передачи в параметр утилиты ADSCIM PropertyLoginName, чтобы внести его в каталог Яндекс.

   Внимание

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

3. Если ваши пользователи уже используют организацию ID и проходят аутентификацию с помощью протокола SAML 2.0, например, в Active Directory или Keycloak, убедитесь, что указанное в поле Incoming claim type значение атрибута NameID соответствует основному идентификатору утилиты ADSCIM PropertyLoginName:

   • UPN (userPrincipalName в ADSCIM) – если имена для входа пользователей не будут меняться;

   • objectSID, objectGUID или другой — если запланированы изменения домена или бизнес-процессов, которые могут привести к изменению UPN пользователей.

   Больше информации про PropertyLoginName см. в шаге 4, п. 2.5.

4. Проверьте, что у пользователей в Active Directory заполнены атрибуты:

   • идентификатор, который выбран в качестве основного;

   • User SamAccountName;

   • E-mail.

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

1. Перейдите на страницу создания приложения.

2. Введите название сервиса и прикрепите его иконку.

3. В блоке Платформы приложения выберите Веб-сервисы. В поле Redirect URI нажмите ссылку Подставить URL для отладки.

4. В блоке Доступ к данным в начале строки введите название доступа Управление федерациями.

5. Укажите почту для связи. Внизу страницы нажмите Создать приложение.

6. Отправьте 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 — его Секретный ключ)

7. Сохраните полученные ID и OAuth-токен. Они пригодятся на следующих шагах.

Шаг 3. Укажите Client ID в организации ID и получите Domain ID

1. Откройте организацию ID.

2. Перейдите в раздел Настройки → Единый вход (SSO).

3. Нажмите Настроить.

4. В блоке Синхронизация SCIM вставьте ID вашего приложения, который получили на шаге 2.

5. Скопируйте ваш Domain ID, он пригодится на следующем шаге.

6. Сохраните изменения.

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

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

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

   Совет

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

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

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

   1. Проверьте, что в значении параметра LDAP указан правильный путь для подключения к Active Directory. Если нет, исправьте его. Подставьте в поисковые параметры собственные значения.

   Для поискового запроса используйте путь из структуры DIT = Directory Information Tree (читается справа налево): LDAP = LDAP://CN=Users,OU=DomainGroup,DC=YourCompanyName,DC=com

   • DC – domainComponent, собственный домен и доменная зона;

   • OU – OrganizationUnit, компания\департамент\отдел, из которого вы хотите получить пользователей;

   • CN – commonName, наименование объекта, который хотите получить из каталога.

   1. В значении параметра BearerToken укажите OAuth-токен, который получен на шаге 2.

   2. В значении параметра DomainID укажите ID домена, который получен на шаге 3.

   3. Значение параметра DryRun изначально установлено в значение true. Если оставить это значение, то на данном этапе служба будет работать в тестовом режиме. Запросы будут фиксироваться в логах, но синхронизация производиться не будет. Чтобы включить синхронизацию SCIM уже сейчас, поменяйте значение параметра на false.

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

   Параметр PropertyLoginName, который соответствует идентификатору пользователя, может принимать одно из трех значений:

   • userPrincipalName — UPN, значение по умолчанию;

   • objectSID;

   • objectGUID.

   Значение параметра должно соответствовать значению атрибута NameID в поле Incoming claim type из настроек единого входа (SSO).

   Если вы используете атрибут вида username, а не username@domain.com, то дополнительно укажите параметр IgnoreUsernameDomain со значением true.

   Для остальных пользовательских атрибутов:

   Название параметра утилиты YandexADSCIM	Название атрибута (рус)	Значение по умолчанию из Active Directory	Пример
   PropertyFirstName	Имя	givenName	Иван
   PropertyMiddleName	Отчество	middleName	Иванович
   PropertyLastName	Фамилия	sn (SurName)	Иванов
   PropertyDisplayName	Выводимое имя	displayName	Иванов И. И.
   PropertyWorkMail	Основная почта	mail	I_ivanov@domain.ru
   PropertyTitle	Должность	title	Разработчик
   PropertyMobilePhoneNumber	Мобильный телефон	mobile	+7 012 345-67-89
   PropertyWorkPhoneNumber	Рабочий телефон	telephoneNumber	+7 495 123-45-67
   PropertyIpPhoneNumber	IP-телефон	ipPhone	7495 012-34-56

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

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

   UsersFilter =(memberOf=CN=groupname,CN=Users,DC=domainname,DC=com)

   Совет

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

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

   Важно

   Для корректной синхронизации алиасов версия утилиты YandexADSCIM должна быть 1.1.0.144 или выше.

   1. Синхронизируйте группы из Active Directory — добавьте параметр EnableGroups со значением true.

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

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

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

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

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

   1. Поменяйте значение параметра DryRun на true перед первым запуском сервиса, если ранее вы изменяли его на false. Периодичность запуска сервиса определяется параметром 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 конфигурационного файла.

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

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

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

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

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

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

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

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

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

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

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

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