Синхронизация пользователей и групп с каталогом LDAP с помощью утилиты ADSCIM
Если в вашей компании развернута служба федерации Active Directory, вы можете настроить автоматическую синхронизацию сотрудников и групп с Яндекс 360 для бизнеса — для этого нужно установить и настроить специальную службу Windows.
Если вы хотите подключить синхронизацию пользователей из Active Directory, установите YandexADSCIM (утилита в виде службы Windows на компьютере) по инструкции ниже и запустите программу от имени пользователя с правами чтения из каталога LDAP. YandexADSCIM управляется через оснастку Сервисы. Настройки меняются в конфигурационном файле.
Сейчас полноценно поддерживаются каталоги Active Directory, Samba DC и Red ADM. Другие каталоги LDAP будут полноценно поддержаны в будущем, когда утилита YandexADSCIM будет портирована на *nix-платформы. Сейчас ее можно использовать для настройки работы с другими каталогами LDAP, но запускать нужно на устройстве с OC Windows.
Подключение и первоначальная настройка ADSCIM
Шаг 1. Начните настройку
-
Проверьте, что единый вход (SSO) подключен и правильно работает. Как подключить единый вход
-
Задайте уникальный идентификатор пользователя:
-
Выберите атрибут Active Directory для передачи в параметр утилиты ADSCIM PropertyLoginName, чтобы внести его в каталог Яндекса:
-
UPN (userPrincipalName в ADSCIM) – если имена для входа пользователей не будут меняться;
-
objectSID, objectGUID или другой — если запланированы изменения домена или бизнес-процессов, которые могут привести к изменению UPN пользователей.
-
Внимание
Атрибут, который вы зададите в качестве основного идентификатора, не должен меняться. Пользователь с другим атрибутом при входе будет считаться новым пользователем.
- Если ваши пользователи уже используют сервисы Яндекс 360 и проходят аутентификацию с помощью протокола SAML 2.0, проверьте совпадение атрибутов: значение атрибута NameID, которое указано в Active Directory, должно соответствовать основному идентификатору утилиты ADSCIM PropertyLoginName.
Больше информации про 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% не получается, включите отображение скрытых файлов. Как это сделать
Каждая настройка в конфигурационном файле записывается отдельной строкой в формате
ключ=значение
. Строки, которые начинаются с символа#
, служба игнорирует.Настройте конфигурационный файл:
-
Проверьте, что в значении параметра LDAP указан правильный путь для подключения к Active Directory. Если нет, исправьте его. Подставьте в поисковые параметры собственные значения.
Для поискового запроса используйте путь из структуры
DIT = Directory Information Tree
(читается справа налево):LDAP = LDAP://CN=Users,OU=DomainGroup,DC=YourCompanyName,DC=com
где
-
DC
– domainComponent, собственный домен и доменная зона; -
OU
– OrganizationUnit, компания, департамент или отдел, из которого вы хотите получить пользователей; -
CN
– commonName, наименование объекта, который хотите получить из каталога.
-
-
В значении параметра BearerToken укажите OAuth-токен, полученный на шаге 2.
-
В значении параметра DomainID укажите ID домена, полученный на шаге 3.
-
Значение параметра DryRun изначально установлено в значение
true
. Если оставить это значение, то на данном этапе служба будет работать в тестовом режиме. Запросы будут фиксироваться в логах, но синхронизация производиться не будет. Чтобы включить синхронизацию SCIM уже сейчас, поменяйте значение параметра наfalse
. -
Синхронизируйте пользовательские данные из 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
. -
-
Чтобы ограничить выгрузку пользователей, можно воспользоваться фильтром UsersFilter и применить стандартный синтаксис запросов LDAP.
-
Чтобы выбрать пользователей по их членству в определенной группе, используйте фильтр:
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)))
В результате синхронизации пользователи, которые зарегистрированы на почтовом домене вашей организации, но не попали в фильтр, будут заблокированы.
-
-
Если нужно, чтобы алиасы почтовых ящиков из Active Directory синхронизировались с Яндекс 360 для бизнеса, добавьте параметр EnableAliases со значением
true
. Доменные почтовые алиасы, которые указаны в Active Directory в атрибуте пользователяproxyAdresses
с типом SMTP, добавятся в аккаунт сотрудника в Яндекс 360 для бизнеса автоматически.Важно
Для корректной синхронизации алиасов версия утилиты YandexADSCIM должна быть 1.1.0.144 или выше. Скачать установочный файл
-
Синхронизируйте группы из Active Directory — добавьте параметр EnableGroups со значением
true
.Чтобы ограничить список групп, можно воспользоваться фильтром GroupsFilter и применить стандартный синтаксис запросов LDAP. Например, чтобы выгрузить все списки рассылок, используйте фильтр:
GroupsFilter =(&(objectClass=group)(!(groupType:1.2.840.113556.1.4.803:=2147483648)))
-
Синхронизируйте атрибуты групп из Active Directory. Переназначить атрибуты при создании или синхронизации групп в Яндекс 360 позволяют параметры, которые начинаются с PropertyGroup.
Название параметра утилиты YandexADSCIM
Название атрибута (рус.)
Значение по умолчанию из Active Directory
Пример
PropertyGroupDisplayName
Название
name
Проект интеграции
PropertyGroupDescription
Описание
description
Сотрудники, участвующие в проекте интеграции
PropertyGroupEmail
Рассылка
mail
int@domain.ru
Параметры, которые начинаются с PropertyGroup, можно указывать несколько раз — в таком случае значением параметра будет список. Порядок атрибутов при этом важен. Например, для получения названия группы можно задать атрибуты:
PropertyGroupDisplayName = name
,PropertyGroupDisplayName = cn
. Если существует атрибутname
, будет использовано его значение. Если этого атрибута нет, будет использовано значение атрибутаcn
. -
Синхронизируйте внешние контакты, если вы используете их в Яндекс 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))
-
Синхронизируйте атрибуты контактов из 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
- (*) Неосновные email — адреса с префиксом
smtp:
(proxyAddresses в Active Directory) — переопределить нельзя. Но их можно отключить, добавив параметр ContactIgnoreProxyAddresses со значениемtrue
.
Параметры, которые начинаются с PropertyContact, можно указывать несколько раз — в таком случае значением параметра будет список. Порядок атрибутов при этом важен.
Каждый из этих параметров также можно отключить, указав для него в качестве значения символ
-
(минус). Например, чтобы отключить синхронизацию атрибута «Должность», нужно указатьPropertyContactTitle = -
. - (*) Неосновные email — адреса с префиксом
-
Поменяйте значение параметра DryRun на
true
перед первым запуском сервиса, если ранее (п. 2.4) вы изменяли его наfalse
. Периодичность запуска сервиса определяется параметром UpdateEveryMins = N, где N — интервал в минутах. Запустите сервис через оснастку и проанализируйте файл лога.Системные сообщения в логах
Уведомление
Результат
CORE Update user: user@domain.ru (Active:true -> false)
Пользователь будет заблокирован.
SCIM Update user
Изменение атрибутов пользователя в каталоге Яндекса.
SCIM Add user
Добавление пользователя в каталог Яндекса.
CORE Users: added 0, removed 3 237, modified 0
Добавлено — 0, заблокировано — 3 237, изменено — 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
Ошибка в строке N конфигурационного файла.
AD Received contacts count: N
Из Active Directory загружено N контактов.
SCIM Add SharedContact:
Добавление контакта в каталог Яндекса.
-
-
Остановите службу и запустите снова, чтобы применить изменения из конфигурационного файла. Как это сделать
Изменение настроек
Если вы хотите изменить настройки, внесите изменения в конфигурационный файл, а затем перезапустите службу YandexADSCIM через командную строку или диспетчер задач по инструкции.
Просмотр логов
Все логи службы сохраняются в папке %ProgramData%\Yandex\YandexADSCIM
.
Обновление ADSCIM
Приложение обновляется автоматически: по умолчанию в конфигурационном файле указано значение AutoUpdate = True
либо этого параметра нет, так как значение True
является для него значением по умолчанию.
Если вы хотите обновлять приложение вручную, укажите AutoUpdate = False
. Теперь, чтобы обновить приложение, вам нужно будет скачать последнюю версию YandexADSCIM (скачать) и запустить установочный файл.
Остановка и перезапуск ADSCIM
YandexADSCIM — это служба Windows, поэтому исполняется автоматически при запуске системы и не зависит от статуса пользователя. Но вы можете отключить ее вручную — для этого в командной строке (cmd.exe) введите sc stop yandexadscim
или в диспетчере задач нажмите Остановить.
Для повторного запуска службы в командной строке введите sc start yandexadscim
. Также вы можете перезапустить ADSCIM в диспетчере задач на вкладке Службы.
Удаление ADSCIM
Если же вы хотите удалить службу насовсем, используйте команду sc delete yandexadscim
.
Возможные ситуации при работе c ADSCIM
Ситуация |
Результат |
У пользователя изменились атрибуты в Active Directory, но при этом уникальный идентификатор не изменился |
Система обновит атрибуты в каталоге Яндекса (кроме основной почты и NameID). |
У пользователя изменился уникальный идентификатор |
Система не сможет найти объект с исходным идентификатором и заблокирует предыдущего пользователя. Далее система попытается добавить пользователя с новым идентификатором, но не сможет этого сделать, так как логин пользователя уже занят предыдущим. Если удалить заблокированного пользователя, система добавит нового без переноса каких-либо данных со старого. |
Пользователь удален в Active Directory |
Пользователь будет заблокирован в каталоге Яндекса. |
Новый пользователь в Active Directory |
Пользователь будет добавлен в каталог Яндекса с соответствующими атрибутами. |
Все пользователи в каталоге Яндекса заблокированы |
Это могло произойти, если:
|
Протокол хранения данных об организации, каталогах, пользователях, позволяющий осуществлять аутентификацию.
Технология от компании Microsoft, позволяющая организовать единый вход для доступа к различным системам и приложениям. Обзор служб федерации Active Directory
Приложение, которое исполняется при запуске операционной системы Windows. (https://ru.wikipedia.org/wiki/Служба_Windows)
Стандарт безопасности, который позволяет обмениваться аутентификационными и авторизационными данными в интернете. Как работает SSO на базе SAML 2.0
Инструмент командной строки, который используется для передачи данных на сервер и с сервера. С его помощью можно взаимодействовать с веб-сайтами и API, отправлять и получать данные, загружать и скачивать файлы. Описание cURL
Про настройку атрибута, который указывается в поле Тип входящего утверждения (или Incoming claim type для интерфейса AD FS на английском языке) и используется для идентификации пользователя, читайте в разделе Настройка сопоставления утверждений (или Настройка Claims Mapping для интерфейса AD FS на английском языке).
Почтовые адреса-синонимы внутри одного домена. Об алиасах почтовых ящиков
Чтобы сотрудники организации могли пользоваться сервисами Яндекс 360, им нужны индивидуальные аккаунты. Аккаунт можно создать разными способами, в том числе автоматически синхронизировать с системой управления доступа (например, Active Directory). Инструкции
Неосновные email — адреса с префиксом smtp:
(proxyAddresses в Active Directory) — переопределить нельзя. Но их можно отключить, добавив параметр ContactIgnoreProxyAddresses со значением true
.
API-запрос на создание нового ресурса на сервере. Используется для отправки данных на сервер для создания нового объекта или выполнения какого-либо действия.
Специальный код, разрешающий доступ к данным от имени конкретного пользователя.
UPN (User Principal Name) — это имя пользователя, которое состоит из имени учетной записи, символа @ и домена организации. UPN используется для аутентификации пользователя в сервисах Microsoft, например Active Directory и Azure AD, и может не совпадать с почтовым адресом.