Связаться с намиПодключиться

Синхронизация пользователей и групп с Microsoft Active Directory

Статья создана
Обновлена 19 ноября 2025 г.

Примечание

Функциональность находится на стадии Preview.

Если для управления пользователями ваша компания использует Microsoft Active Directory и вы хотите организовать для ваших пользователей доступ к Yandex Cloud, вам не нужно вручную создавать в Yandex Cloud учетные записи для ваших пользователей. Вместо этого вы можете синхронизировать с Yandex Identity Hub пользователей и группы, созданные в вашем каталоге Active Directory.

Примечание

В настоящее время пользователей из Active Directory можно синхронизировать только с локальными пользователями Yandex Cloud в пределах пулов пользователей.

Синхронизация пользователей и групп выполняется агентом синхронизации Identity Hub AD Sync Agent, который может быть запущен на любом сервере под управлением ОС Linux или Windows.

Схема синхронизации:

На сервере, где запущен агент синхронизации, должны быть открыты следующие TCP-порты для входящего и исходящего трафика:

  • Для обращения к API Yandex Cloud:

  • Для обращения к контроллеру домена Active Directory:

    • 389 — для LDAP;
    • 636 — для LDAPS;
    • 135 — для MSRPC;
    • 49152:65535 — диапазон портов для MSRPC dynamic.

Объекты синхронизации

Агент Identity Hub AD Sync Agent синхронизирует с каталогом Active Directory следующие объекты:

  • Пользователи.

  • Атрибуты пользователей.

    Таблица сопоставления атрибутов пользователей по умолчанию:

    Атрибут в Active Directory Атрибут в Identity Hub
    displayName full_name
    givenName given_name
    sn family_name
    mail email
    telephoneNumber phone_number
    userPrincipalName username
    ObjectGUID external_id

  • Группы пользователей.

  • Атрибуты групп пользователей.

    Таблица сопоставления атрибутов групп пользователей по умолчанию:

    Атрибут в Active Directory Атрибут в Identity Hub
    name name
    description description
    ObjectGUID external_id

  • Членства пользователей в группах.

  • Хэши паролей пользователей.

    Пароли пользователей хранятся в Active Directory не в открытом виде, а в виде хэшей. Yandex Cloud, получив из каталога Active Directory хэш пароля пользователя, формирует на его основе собственный хэш с использованием современного и устойчивого к взлому алгоритма Argon2.

    Внимание

    Yandex Cloud не хранит в своих базах данных пароли пользователей в открытом виде.

Настройка синхронизации

Чтобы реализовать синхронизацию пользователей и групп Identity Hub с Active Directory, необходимо выполнить предварительные настройки, как на стороне вашего контроллера домена с развернутыми службами Active Directory, так и на стороне Yandex Cloud.

Настройка на стороне контроллера домена Active Directory

Для корректной работы агента синхронизации на стороне Active Directory выполните следующие действия:

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

  2. Выдайте этому пользователю следующие разрешения:

    • Replicating Directory Changes;
    • Replicating Directory Changes All.

  3. На контроллере домена откройте сетевые TCP-порты для входящего трафика, поступающего с IP-адреса сервера, на котором установлен агент Identity Hub AD Sync Agent:

    • 389 — для LDAP;
    • 636 — для LDAPS;
    • 135 — для MSRPC;
    • 49152:65535 — диапазон портов для MSRPC dynamic.

Настройка на стороне Yandex Cloud

Для корректной работы агента синхронизации на стороне Yandex Cloud выполните следующие действия:

Агент Identity Hub AD Sync Agent

Агент синхронизации Identity Hub AD Sync Agent выполняет чтение данных о пользователях и группах пользователей в выбранных Organization Units (OU) в каталоге Active Directory и синхронизирует их с данными пользователей и групп пользователей в пуле Identity Hub.

На стороне Active Directory агент синхронизации получает данные пользователей и групп от имени пользователя, созданного в домене Active Directory. При получении этих данных используются протоколы LDAP и DRSR, запросы отправляются на адрес контроллера домена Active Directory, заданный в конфигурации агента.

На стороне Yandex Cloud агент синхронизации управляет пользователями и группами пользователей от имени сервисного аккаунта с назначенными разрешениями на выполнение синхронизации. Запросы к Yandex Cloud направляются на публичный эндпоинт https://organization-manager.api.yandexcloud.kz по протоколу HTTPS.

Скрипт установки агента синхронизации доступен для следующих операционных систем:

Процесс синхронизации

В процессе синхронизации данных агент Identity Hub AD Sync Agent может создавать, изменять или удалять пользователей и группы пользователей в Identity Hub. Синхронизация пользователей и групп Identity Hub с пользователями и группами в Active Directory выполняется в два этапа: первичная синхронизация и инкрементальная синхронизация.

Полная (первичная) синхронизация

При выполнении полной синхронизации агент считывает данные всех пользователей, групп и их атрибутов в выбранных Organization Units в каталоге Active Directory и создает аналогичных пользователей и группы с аналогичными атрибутами в пуле пользователей Identity Hub.

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

  • main_sync_replication_token.json
  • password_hash_replication_token.json
  • user_control_replication_token.json

После успешного завершения полной синхронизации агент, запущенный в виде сервиса или службы операционной системы, переходит к непрерывному выполнению частичной (инкрементальной) синхронизации.

Совет

Вы можете повторно запустить процесс полной синхронизации. Для этого удалите указанные выше файлы с токенами процессов и перезапустите агент.

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

Инкрементальная синхронизация непрерывно выполняется запущенным агентом со следующей периодичностью:

  • Синхронизация паролей и состояний пользователей — агент отслеживает статус блокировки/разблокировки пользователей в домене Active Directory и смену пользовательских паролей и переносит эти изменения в Identity Hub с интервалом в несколько секунд. Частоту выполнения этого типа синхронизации изменить нельзя.
  • Синхронизация иных значений — агент отслеживает прочие изменения свойств, атрибутов и параметров пользователей и групп с интервалом, установленным в файле конфигурации агента.

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

Отслеживаемые изменения

В процессе непрерывной синхронизации агент отслеживает следующие изменения в Active Directory и переносит их в Identity Hub:

  • создание, изменение, блокировка, разблокировка и удаление пользователей;
  • создание, изменение и удаление групп пользователей;
  • изменение атрибутов пользователей и групп;
  • добавление пользователей в группы и исключение их из групп;
  • изменение паролей пользователей.

Логирование процесса синхронизации

Агент Identity Hub AD Sync Agent регистрирует события, возникающие в процессе синхронизации.

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

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

Кроме того, в конфигурации агента можно задать следующие уровни логирования:

  • debug
  • info
  • warn
  • error
  • dpanic
  • panic
  • fatal

Конфигурация агента

Конфигурация агента синхронизации задается в YAML-файле в следующем формате:

# Default configuration for yc-identityhub-sync-agent
# This is a template - please update with your actual values

userpool_id: "<идентификатор_пула_пользователей>"
cloud_credentials_file_path: "<путь_к_файлу_с_авторизованным_ключом>"
replication_tokens_path: "<путь_к_директории_с_токенами_процессов>"
working_directory: "<путь_к_рабочей_директории_агента>"

# Active Directory replication API client settings
drsr:
  host: "<IP-адрес_контроллера_домена>"
  username: "username"
  password: "password"

# LDAP client settings
ldap:
  host: "ldaps://<IP-адрес_контроллера_домена>:636"
  username: "<имя_пользователя_Active_Directory>"
  password: "<пароль_пользователя_Active_Directory>"
  certificate_path: "<путь_к_сертификату>"
  insecure_skip_verify: false|true

# Logger configuration
logger:
  level: "<уровень_логирования>"
  format: "plain|json"
  file:
    filename: "<путь_к_файлу_с_логами>"
    maxsize: 30
    maxbackups: 10

# Sync settings
sync_settings:
  interval: "600s"
  allow_to_capture_users: true|false
  allow_to_capture_groups: true|false
  # Remove the following line if you don't need to replace domain
  replacement_domain: "<домен_пула_пользователей>"
  filter:
    domain: "<имя_домена_в_Active_Directory>"
    organization_units:
      - OU=IdPUsersOU,DC=example,DC=com
      - OU=IdPGroupsOU,DC=example,DC=com
  remove_user_behavior: "remove|block"

Где:

  • userpool_id — идентификатор пула пользователей в Identity Hub.

  • cloud_credentials_file_path — путь к файлу, содержащему авторизованный ключ сервисного аккаунта в Yandex Cloud. Например:

    • /etc/yc-identityhub-sync-agent/authorized_key.json (для Linux);
    • C:\\ProgramData\\YcIdentityHubSyncAgent\\authorized_key.json (для Windows).

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

  • replication_tokens_path — путь к директории, в которой сохраняются токены с информацией о текущем прогрессе процессов полной синхронизации. Необязательный параметр.

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

  • working_directory — путь к директории, в которой сохраняются другие файлы, необходимые агенту для работы. Необязательный параметр.

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

    • /etc/yc-identityhub-sync-agent/ (для Linux);
    • C:\\ProgramData\\YcIdentityHubSyncAgent\\ (для Windows).

    Примечание

    Если в параметрах cloud_credentials_file_path, replication_tokens_path и/или logger.level заданы пути, отличные от пути, заданного в параметре working_directory, будут использоваться пути, указанные в параметрах cloud_credentials_file_path, replication_tokens_path и/или logger.level.

  • drsr — настройки протокола DRSR для аутентификации на стороне Active Directory пользователя с назначенными правами на выполнение репликации данных в каталоге.

  • ldap — настройки протокола LDAPS/LDAP для аутентификации на стороне Active Directory:

    Важно

    Вы можете подключаться к контроллеру домена по протоколу LDAPS или LDAP. Рекомендованным и безопасным протоколом является LDAPS. Протокол LDAP используйте только при настройке и тестировании.

    • host — IP-адрес контроллера домена Active Directory. В зависимости от используемого протокола указываются схема и номер порта:

      • при использовании LDAPS — схема ldaps:// и порт 636;
      • при использовании LDAP — схема ldap:// и порт 389.

    • username — имя пользователя домена Active Directory, которому назначены права на выполнение репликации данных.

    • password — пароль пользователя домена Active Directory.

    • certificate_path — путь к файлу с сертификатом открытого ключа, необходимого для расшифрования трафика от контроллера домена. Обязательный параметр при использовании протокола LDAPS.

      Если в параметре working_directory задан путь к рабочей директории, вместо пути к файлу сертификата достаточно указать имя этого файла.

    • insecure_skip_verify — параметр, позволяющий игнорировать ошибки валидации сертификата открытого ключа при подключении к контроллеру домена. Необязательный параметр. Возможные значения:

      • false — ошибки валидации сертификата не будут игнорироваться. Значение по умолчанию.
      • true — агент синхронизации будет игнорировать ошибки валидации сертификата. Может быть полезно при настройке и тестировании синхронизации. Не рекомендуется использовать в рабочем режиме.

  • logger — настройки логирования процесса синхронизации:

    • level — уровень логирования. Возможные значения:

      • debug
      • info
      • warn
      • error
      • dpanic
      • panic
      • fatal

    • format — формат вывода информации о событиях. Необязательный параметр. Возможные значения:

      • plain — информация выводится в простом текстовом виде. Значение по умолчанию.
      • json — информация выводится в формате JSON.

    • file — настройки сохранения логов в файлы:

      • filename — путь к файлу, в который будет сохраняться информация о событиях при синхронизации.

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

        Необязательный параметр. Имя файла по умолчанию — identity_hub.log.

      • maxsize — максимальный размер одного файла с логами в мегабайтах.

      • maxbackups — максимальное количество файлов с логами, которые агент будет хранить. При превышении максимального количества файлов наиболее старый файл будет удален.

      Необязательный параметр. Если настройки в параметре file не заданы, информация не сохраняется в файлы, а выводится в поток stdout.

  • sync_settings — настройки процесса синхронизации:

    • interval — периодичность выполнения инкрементальной синхронизации. Необязательный параметр. Значение по умолчанию — 240 секунд.

      Примечание

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

    • allow_to_capture_users — параметр, позволяющий изменять существующего пользователя пула Identity Hub при совпадении его логина с логином пользователя Active Directory, которого требуется синхронизировать. Возможные значения:

      • true — агент синхронизации будет изменять существующих пользователей Identity Hub, приводя их в соответствие с учетной записью в Active Directory.
      • false — агент синхронизации не будет изменять существующих пользователей Identity Hub. При обнаружении совпадения логинов пользователя в пуле и в Active Directory процесс синхронизации выдаст ошибку.

    • allow_to_capture_groups — параметр, позволяющий изменять существующую группу пользователей Identity Hub при совпадении ее имени с именем группы в Active Directory, которую требуется синхронизировать. Возможные значения:

      • true — агент синхронизации будет изменять существующие группы пользователей Identity Hub, приводя их в соответствие с группами в Active Directory.
      • false — агент синхронизации не будет изменять существующие группы пользователей Identity Hub. При обнаружении совпадения имен групп в пуле и в Active Directory процесс синхронизации выдаст ошибку.

    • replacement_domain — домен, привязанный к пулу пользователей Identity Hub, в котором находятся синхронизируемые пользователи и группы. Например: newdomain.idp.yandexcloud.kz.

      Необязательный параметр. Значение параметра replacement_domain требуется задавать только в том случае, если имя домена, привязанного к пулу пользователей, отличается от имени домена на контроллере домена Active Directory.

    • filter — настройки фильтрации синхронизируемых объектов на стороне Active Directory:

      • domain — имя домена на контроллере домена Active Directory, в котором агент будет синхронизировать пользователей и группы.
      • organization_units — список Organization Units (OU) в каталоге Active Directory, в которых агент будет синхронизировать пользователей и группы.

      Если не настроить фильтрацию синхронизируемых объектов, агент Identity Hub AD Sync Agent попытается синхронизировать все доступные объекты в каталоге Active Directory.

    • remove_user_behavior — позволяет управлять действием в отношении пользователей на стороне Yandex Cloud, если соответствующие пользователи на стороне Active Directory были удалены или перестали удовлетворять условиям, заданным в параметрах sync_settings.filter (например, они были перенесены в другой Organization Unit). Необязательный параметр. Возможные значения:

      • remove — пользователи, удаленные или переставшие удовлетворять условиям фильтра, удаляются на стороне Identity Hub. Действие по умолчанию.
      • block — пользователи, удаленные или переставшие удовлетворять условиям фильтра, деактивируются на стороне Identity Hub.

    Примечание

    Если в процессе синхронизации выясняется, что на стороне Active Directory группа пользователей была удалена или перестала удовлетворять заданным фильтрам (например, она была перенесена в другой Organization Unit), то на стороне Identity Hub такая группа удаляется.

См. также

Предыдущая
Портал Мой аккаунт
Следующая
Квоты и лимиты