Настройка утилиты YandexADSCIM для синхронизации c Active Directory

Чтобы настроить синхронизацию пользователей из Active Directory, установите утилиту YandexADSCIM по инструкции и запустите ее от имени пользователя с правами чтения из каталога LDAP.

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

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

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

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

   • User SamAccountName;

   • E-mail.

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

1. Создайте свое OAuth-приложение по инструкции из Справки OAuth Яндекс ID. При этом:

   • авторизуйтесь в сервисе OAuth с аккаунтом владельца организации;
   • в разделе Доступ к данным введите scim и выберите предлагаемый доступ Управление федерациями.

2. На странице приложения скопируйте:

   • идентификатор приложения из поля ClientID;
   • секретный ключ из поля Client secret.

3. Отправьте POST-запрос, чтобы получить OAuth-токен. Например, через cURL это можно сделать при помощи следующей команды:

   curl -X POST https://oauth.yandex.ru/token -d "grant_type=client_credentials&client_id=значение1&client_secret=значение2"
   

   где значение параметра client_id — это идентификатор созданного приложения, а client_secret — его секретный ключ.

4. Скопируйте значение токена и сохраните его. Оно пригодится на следующих шагах.

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

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

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

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

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

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

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

Шаг 4. Настройте конфигурационный файл YandexADSCIM

1. Откройте конфигурационный файл. Как это сделать

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

   Для поискового запроса используйте путь из структуры DIT = Directory Information Tree (читается справа налево):

   LDAP = LDAP://CN=Users,OU=DomainGroup,DC=YourCompanyName,DC=com
   

   где

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

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

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

   Если путей несколько, укажите каждый с новой строки, например:

   LDAP = LDAP://OU=DomainGroup1,DC=YourCompanyName,DC=com
   LDAP = LDAP://OU=DomainGroup2,DC=YourCompanyName,DC=com
   

   Пути объединяются в список и синхронизируются в порядке их указания. Максимальное количество путей не ограничено.

   Конфигурация с несколькими LDAP-путями позволяет подключаться к нескольким лесам Active Directory, если между ними есть доверительные отношения (Trust Relationships).

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

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

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

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

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

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

   • objectSID;

   • objectGUID.

   Значение параметра должно соответствовать значению атрибута NameID.

   Если вы используете атрибут вида 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.

7. Чтобы запретить блокировку пользователей в Яндекс 360 при синхронизации, добавьте параметр AllowUsersDeletion со значением False. В этом случае пользователи не будут заблокированы в организации Яндекс 360 при удалении их из Active Directory. Значение по умолчанию: True.

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

   Если вы указываете несколько LDAP-путей в файле конфигурации, фильтр UsersFilter применяется ко всем путям.

   • Чтобы выбрать пользователей по их членству в определенной группе, используйте фильтр:

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

   • Если нужно дополнительно исключить из выборки заблокированных в Active Directory пользователей, используйте фильтр:

     UsersFilter =(&(memberOf=CN=groupname,CN=Users,DC=domainname,DC=com) (!(userAccountControl:1.2.840.113556.1.4.803:=2)))
     

     В результате синхронизации пользователи, которые зарегистрированы на почтовом домене вашей организации, но не попали в фильтр, будут заблокированы.

9. Чтобы синхронизировать алиасы почтовых ящиков из Active Directory:

   • Добавьте параметр EnableAliases со значением True.
   • Укажите алиасы с типом SMTP и префиксом smtp: или SMTP: в атрибуте proxyAdresses пользователя.

   Алиасы автоматически добавятся в аккаунт сотрудника в Яндекс 360 для бизнеса.

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

10. Для синхронизации алиасов только определенных доменов:

    • Добавьте параметр AliasesDomains.

    • Перечислите домены через пробел:

      AliasesDomains = domain1.com domain2.com domain3.org
      

    Правила обработки почтовых адресов:

    • адрес на домене из AliasesDomains передается как алиас в SCIM;
    • адрес на домене не из списка передается в атрибуте emails с параметром Primary = false;
    • если параметр AliasesDomains отсутствует, синхронизируются алиасы всех доменов организации.
    Как это работает

    Если есть организация с настройками:

    • в организации Яндекс 360 добавлен домен domain1.com;

    • в конфигурации SCIM задано: AliasesDomains = domain2.com;

    • в атрибуте proxyAddresses пользователя в Active Directory указаны адреса:

      • SMTP:user1@domain1.com;
      • smtp:user2@domain2.com;
      • smtp:user3@domain3.com.

    В результате синхронизации в список алиасов пользователя попадут:

    • user1 — домен domain1.com добавлен в организацию Яндекс 360;
    • user2 — домен domain2.com указан в AliasesDomains.

    Адрес user3@domain3.com будет полностью передан в атрибут emails с параметром Primary = false, поскольку домен domain3.com не добавлен в организацию Яндекс 360 и отсутствует в AliasesDomains.

    Параметр AliasesDomains доступен в версии 1.1.0.156 и выше. Как обновить до последней версии

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

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

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

    Если вы указываете несколько LDAP-путей в файле конфигурации, фильтр GroupsFilter применяется ко всем путям.

12. Чтобы запретить удаление групп в Яндекс 360 при синхронизации, добавьте параметр AllowGroupsDeletion со значением False. В этом случае группы не будут удалены в организации Яндекс 360 при удалении их из Active Directory. Значение по умолчанию: True.

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

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

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

14. Синхронизируйте внешние контакты, если вы используете их в Яндекс 360. Для этого добавьте параметр EnableContacts со значением True.

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

    По умолчанию в качестве контактов из Active Directory будут синхронизироваться все объекты, удовлетворяющие LDAP-запросу (&(objectClass=contact)). Чтобы ограничить список контактов, можно воспользоваться фильтром ContactsFilter и применить стандартный синтаксис запросов LDAP. Например, чтобы выгрузить только контакты из группы groupname, используйте фильтр:

    ContactsFilter = (&(objectClass=contact)(memberOf=CN=groupname,CN=Users,DC=domainname,DC=com))
    

    Если вы указываете несколько LDAP-путей в файле конфигурации, фильтр ContactsFilter применяется ко всем путям.

15. Чтобы запретить удаление контактов в Яндекс 360 при синхронизации, добавьте параметр AllowContactsDeletion со значением False. В этом случае контакты не будут удалены в организации Яндекс 360 при удалении их из Active Directory. Значение по умолчанию: True.

16. Синхронизируйте атрибуты контактов из Active Directory. Переназначить атрибуты при создании или синхронизации контактов в Яндекс 360 позволяют параметры, которые начинаются с PropertyContact.

    Название параметра утилиты YandexADSCIM	Название атрибута (рус.)	Значение по умолчанию из Active Directory	Пример
    PropertyContactFirstName	Имя	givenName	Иван
    PropertyContactMiddleName	Отчество	middleName	Иванович
    PropertyContactLastName	Фамилия	sn (SurName)	Иванов
    PropertyContactTitle	Должность	title	Разработчик
    PropertyContactDepartment	Отдел	department	Отдел разработки
    PropertyContactCompany	Компания	company	ООО «Страна чудес»
    PropertyContactMail	Основной email*	mail	I_ivanov@domain.ru
    PropertyContactWorkPhone	Основной рабочий телефон	telephoneNumber	+7 495 123-45-67
    PropertyContactOtherWorkPhone	Другие рабочие телефоны	otherTelephone	+7 495 765-43-21
    PropertyContactMobile	Основной мобильный телефон	mobile	+7 012 345-67-89
    PropertyContactOtherMobile	Другие мобильные телефоны	otherMobile	+7 987 654-32-10
    PropertyContactIpPhone	Основной IP-телефон	ipPhone	7495 012-34-56
    PropertyContactOtherIpPhone	Другие IP-телефоны	otherIpPhone	7495 987-65-43
    PropertyContactAddress1	Адрес - Улица	streetAddress	Юбилейная
    PropertyContactAddress2	Адрес - Город	l	Подольск
    PropertyContactAddress3	Адрес - Регион	st	Московская область
    PropertyContactAddress4	Адрес - Индекс	postalCode	142121

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

    Каждый из этих параметров также можно отключить, указав для него в качестве значения символ - (минус). Например, чтобы отключить синхронизацию атрибута «Должность», нужно указать PropertyContactTitle = -.

17. Установите значение параметра DryRun на True. Периодичность запуска сервиса определяется параметром UpdateEveryMins = N, где N  — интервал в минутах. Запустите сервис через оснастку и проанализируйте файл лога. Как это сделать

Пример заполненного файла конфигурации YandexADSCIM

# Частота обновления (в минутах)
UpdateEveryMins = 40

# Режим тестирования (True — не вносить изменения, False — применять изменения)
DryRun = True

# LDAP пути к контейнерам с пользователями, используйте вашу структуру Active Directory
LDAP = LDAP://OU=Sales,DC=yourcompany,DC=com
LDAP = LDAP://OU=Marketing,DC=yourcompany,DC=com

# Фильтр для выборки пользователей
UsersFilter = (&(memberOf=CN=SCIM-Sync,CN=Users,DC=yourcompany,DC=com)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))

# Автоматическое обновление утилиты YandexADSCIM
AutoUpdate = False

# OAuth токен для аутентификации — замените на свой
BearerToken = AQAAAAABBBBBBccccccdddddd

# ID домена Яндекс 360 — замените на свой
DomainID = d1234567890abcdef

# Основной атрибут пользователя для идентификации
PropertyLoginName = userPrincipalName
IgnoreUsernameDomain = False

# Сопоставление остальных атрибутов пользователя
PropertyFirstName = givenName
PropertyMiddleName = middleName
PropertyLastName = sn
PropertyLastName = surName
PropertyDisplayName = displayName
PropertyWorkMail = mail
PropertyTitle = title
PropertyMobilePhoneNumber = mobile
PropertyWorkPhoneNumber = telephoneNumber
PropertyIpPhoneNumber = ipPhone

# Запрет удаления пользователей при синхронизации
AllowUsersDeletion = False

# Синхронизация алиасов
EnableAliases = True
AliasesDomains = yourcompany.com company.org

# Синхронизация групп
EnableGroups = True
GroupsFilter = (&(objectClass=group)(!(groupType:1.2.840.113556.1.4.803:=2147483648)))
AllowGroupsDeletion = False

# Сопоставление атрибутов групп
PropertyGroupDisplayName = name
PropertyGroupDisplayName = cn
PropertyGroupDescription = description
PropertyGroupEmail = mail

# Синхронизация контактов
EnableContacts = True
ContactsFilter = (&(objectClass=contact)(memberOf=CN=External-Contacts,CN=Users,DC=yourcompany,DC=com))
AllowContactsDeletion = False

# Сопоставление атрибутов контактов
PropertyContactFirstName = givenName
PropertyContactMiddleName = middleName
PropertyContactLastName = sn
PropertyContactTitle = title
PropertyContactDepartment = department
PropertyContactCompany = company
PropertyContactMail = mail
PropertyContactWorkPhone = telephoneNumber
PropertyContactOtherWorkPhone = otherTelephone
PropertyContactMobile = mobile
PropertyContactOtherMobile = otherMobile
PropertyContactIpPhone = ipPhone
PropertyContactOtherIpPhone = otherIpPhone
PropertyContactAddress1 = streetAddress
PropertyContactAddress2 = l
PropertyContactAddress3 = st
PropertyContactAddress4 = postalCode

# URL SCIM API домена
DomainUrl = https://api360.yandex.net/directory/v1/domains/d1234567890abcdef/scim/

# Подробное логирование
VerboseLog = True

# Частичная синхронизация (только изменения)
EnablePartialSync = True

# REST API endpoint для мониторинга
RestApiEndpoint = http://*:8091/

Шаг 5. Сохраните изменения в конфигурационном файле

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

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