--- metadata: - name: generator content: Diplodoc Platform v5.50.5 alternate: - https://yandex.uz/support/id/ru/organizations/sso/scim.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.uz/support/id/ru/llms.txt # Синхронизация пользователей и групп с каталогом LDAP Если в вашей компании развернута [служба федерации Active Directory](https://learn.microsoft.com/ru-ru/windows-server/identity/ad-fs/ad-fs-overview), вы можете настроить автоматическую синхронизацию сотрудников и групп с организацией ID — для этого нужно установить и настроить специальную [службу Windows](https://ru.wikipedia.org/wiki/Служба_Windows). {% note alert %} Если вы хотите подключить синхронизацию пользователей из Active Directory, установите **YandexADSCIM** (утилита в виде службы Windows на компьютере) по инструкции ниже и запустите программу от имени пользователя с правами чтения из каталога [LDAP](*p_ldap). YandexADSCIM управляется через оснастку **Сервисы**. Настройки меняются в конфигурационном файле. Другие каталоги LDAP будут полноценно поддержаны в будущем, когда утилита YandexADSCIM будет портирована на *nix платформы. Сейчас ее можно использовать для настройки работы с другими каталогами LDAP, но запускать нужно на устройстве с OC Windows. {% endnote %} ## Подключить и настроить утилиту ADSCIM {#setup} ### Шаг 1. Начните настройку {#identifier} 1. Проверьте, что [единый вход (SSO) подключен](https://yandex.uz/support/id/ru/organizations/sso/setup.md) и правильно работает. 1. Задайте уникальный идентификатор пользователя — выберите атрибут Active Directory для передачи в параметр утилиты ADSCIM **PropertyLoginName**, чтобы внести его в каталог Яндекс. {% note alert %} Атрибут, который вы зададите в качестве основного идентификатора, не должен меняться. Пользователь с другим атрибутом при входе будет считаться новым пользователем. {% endnote %} 1. Если ваши пользователи уже используют организацию ID и проходят аутентификацию с помощью протокола [SAML 2.0](https://wiki.oasis-open.org/security), например, в Active Directory или Keycloak, убедитесь, что [указанное](https://yandex.uz/support/id/ru/organizations/sso/adfs-preset.md#claims-mapping) в поле **Incoming claim type** значение атрибута **NameID** соответствует основному идентификатору утилиты ADSCIM **PropertyLoginName**: - **UPN** (**userPrincipalName** в ADSCIM) – если имена для входа пользователей не будут меняться; - **objectSID**, **objectGUID** или другой — если запланированы изменения домена или бизнес-процессов, которые могут привести к изменению UPN пользователей. Больше информации про **PropertyLoginName** см. в шаге 4, п. 2.5. 1. Проверьте, что у пользователей в Active Directory заполнены атрибуты: - идентификатор, который выбран в качестве основного; - User SamAccountName; - E-mail. ### Шаг 2. Получите Client ID и OAuth-токен {#oauth} 1. Перейдите на страницу [создания приложения](https://oauth.yandex.ru/client/new). 1. Введите название сервиса и прикрепите его иконку. 1. В блоке **Платформы приложения** выберите **Веб-сервисы**. В поле **Redirect URI** нажмите ссылку **Подставить URL для отладки**. 1. В блоке **Доступ к данным** в начале строки введите название доступа **Управление федерациями**. 1. Укажите почту для связи. Внизу страницы нажмите **Создать приложение**. 1. Отправьте [POST-запрос](*p_post-request), чтобы получить [OAuth-токен](*p_oauth-token). Например, через [cURL](https://curl.se/download.html) это можно сделать при помощи следующей команды: ``` curl -X POST https://oauth.yandex.ru/token -d "grant_type=client_credentials&client_id=значение1&client_secret=значение2" ``` (значение параметра `client_id` — это **ID** созданного приложения, а `client_secret` — его **Секретный ключ**) 1. Сохраните полученные ID и OAuth-токен. Они пригодятся на следующих шагах. ### Шаг 3. Укажите Client ID в организации ID и получите Domain ID {#sso-settings} 1. Откройте организацию ID. 1. Перейдите в раздел **Настройки** → **Единый вход (SSO)**. 1. Нажмите **Настроить**. 1. В блоке **Синхронизация SCIM** вставьте ID вашего приложения, который получили на шаге 2. 1. Скопируйте ваш **Domain ID**, он пригодится на следующем шаге. 1. Сохраните изменения. ### Шаг 4. Установите и настройте службу Windows для синхронизации {#yandexadscim} 1. Скачайте и установите службу [YandexADSCIM](https://webdav.yandex.ru/share/dist/YandexADSCIMSetup.msi). 1. Найдите и откройте в любом текстовом редакторе конфигурационный файл — `%ProgramData%\Yandex\YandexADSCIM\AD_Users.config` {% note tip %} Если найти папку `%ProgramData%` не получается, включите [отображение скрытых файлов](https://support.microsoft.com/ru-ru/windows/отображение-скрытых-файлов-0320fe58-0117-fd59-6851-9b7f9840fdb2). {% endnote %} Каждая настройка в конфигурационном файле записывается отдельной строкой в формате `ключ=значение`. Строки, которые начинаются с символа `#`, служба игнорирует. Настройте конфигурационный файл: 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. 1. В значении параметра **DomainID** укажите ID домена, который получен на шаге 3. 1. Значение параметра **DryRun** изначально установлено в значение `true`. Если оставить это значение, то на данном этапе служба будет работать в тестовом режиме. Запросы будут фиксироваться в логах, но синхронизация производиться не будет. Чтобы включить синхронизацию SCIM уже сейчас, поменяйте значение параметра на `false`. 1. Синхронизируйте пользовательские данные из Active Directory. Переназначить атрибуты при создании или синхронизации пользователей в организации ID позволяют параметры, которые начинаются с **Property**. Параметр **PropertyLoginName**, который соответствует идентификатору пользователя, может принимать одно из трех значений: - `userPrincipalName` — [UPN](*p_upn), значение по умолчанию; - `objectSID`; - `objectGUID`. Значение параметра должно соответствовать значению атрибута **NameID** в поле **Incoming claim type** из [настроек единого входа](https://yandex.uz/support/id/ru/organizations/sso/adfs-preset.md) (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)` {% note tip %} Если при синхронизации необходимо отфильтровать пользователей по признаку их вхождения в группы, рекомендуется использовать универсальные группы Active Directory. Использование глобальных или локальных групп в фильтре может привести к некорректным результатам из-за особенностей репликации членства в этих группах для разных доменов. {% endnote %} 1. Если нужно, чтобы алиасы почтовых ящиков из Active Directory синхронизировались с организацией ID, добавьте параметр **EnableAliases** со значением `true`. Доменные почтовые алиасы, которые указаны в Active Directory в атрибуте пользователя `proxyAdresses` с типом SMTP, добавятся в аккаунт сотрудника в Яндекс ID для бизнеса автоматически. {% note warning %} Для корректной синхронизации алиасов версия утилиты [YandexADSCIM](#install-yandexadscim) должна быть 1.1.0.144 или выше. {% endnote %} 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 – интервал в минутах. Запустите сервис через оснастку и проанализируйте файл лога. {#log} {% cut "Системные сообщения в логах" %} #| || **Уведомление** | **Результат** || || 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 конфигурационного файла. || |# {% endcut %} 1. [Остановите службу](#stop) и [запустите снова](#log), чтобы применить изменения из конфигурационного файла. Для этого в командной строке (`cmd.exe`) введите `sc stop yandexadscim`, а затем — `sc start yandexadscim`. Также вы можете сделать это в диспетчере задач на вкладке **Службы**. ## Изменить настройки {#change-settings} Если вы хотите изменить настройки, внесите изменения в конфигурационный файл, а затем перезагрузите службу **YandexADSCIM** через командную строку или диспетчер задач. ## Просмотреть логи {#logs} Все логи службы сохраняются в папке `%ProgramData%\Yandex\YandexADSCIM`. ## Остановить службу {#stop} YandexADSCIM — это служба Windows, поэтому исполняется автоматически при запуске системы и не зависит от статуса пользователя. Но вы можете отключить ее вручную — для этого в командной строке введите `sc stop yandexadscim` или в диспетчере задач нажмите **Остановить**. Если же вы хотите удалить службу насовсем, используйте команду `sc delete yandexadscim`. ## Возможные ситуации при работе сервиса {#situations} #| || **Ситуация** | **Результат** || || У пользователя изменились атрибуты в Active Directory, но при этом уникальный идентификатор не изменился. | Система обновит атрибуты в каталоге Яндекс (кроме основной почты и NameID). || || У пользователя изменился уникальный идентификатор. | Система не сможет найти объект с исходным идентификатором и заблокирует предыдущего пользователя. Далее система попытается добавить пользователя с новым идентификатором, но не сможет этого сделать, так как логин пользователя уже занят предыдущим. Если удалить заблокированного пользователя, система добавит нового без переноса каких-либо данных со старого. || || Пользователь удален в Active Directory. | Пользователь будет заблокирован в каталоге Яндекс. || || Новый пользователь в Active Directory. | Пользователь будет добавлен в каталог Яндекс с соответствующими атрибутами. || || Все пользователи в каталоге Яндекс заблокированы. | Это могло произойти, если: - изменилось поле основного идентификатора; - по какой-то причине приложение не смогло прочитать пользователей в каталоге Active Directory. || |# ## Обновление приложения {#updating} Приложение обновляется автоматически: по умолчанию в конфигурационном файле указано значение `AutoUpdate = True` либо его нет. Если вы хотите обновлять приложение вручную, измените значение на `AutoUpdate = False` или добавьте его. Чтобы обновить приложение, вам нужно будет скачать последнюю версию [YandexADSCIM](https://webdav.yandex.ru/share/dist/YandexADSCIMSetup.msi) и запустить установочный файл. [*p_ldap]: Протокол хранения данных об организации, каталогах, пользователях, позволяющий осуществлять аутентификацию. [*p_post-request]: API-запрос на создание нового ресурса на сервере. Используется для отправки данных на сервер для создания нового объекта или выполнения какого-либо действия. [*p_oauth-token]: Специальный код, разрешающий доступ к данным от имени конкретного пользователя. [*p_upn]: UPN (User Principal Name) — это имя пользователя, которое состоит из имени учетной записи, символа @ и домена организации. UPN используется для аутентификации пользователя в сервисах Microsoft, например Active Directory и Azure AD, и может не совпадать с почтовым адресом.