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

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

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

Схема синхронизации {sync-flow-chart}Схема синхронизации

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

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

  • 443 (TCP) — для HTTPS;

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

  • 389 (TCP) — для LDAP;
  • 636 (TCP) — для LDAPS;
  • 135 (TCP) — для MSRPC;
  • 49152:65535 (TCP) — диапазон портов для MSRPC dynamic;
  • 53 (TCP/UDP) и 88 (TCP/UDP) — для Kerberos.

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

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

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

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

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

  Имя атрибута в конфигурации агента	Имя атрибута в Active Directory (по умолчанию)	Имя атрибута в Yandex Identity Hub
  FullName	displayName	full_name
  GivenName	givenName	given_name
  FamilyName	sn	family_name
  Email	mail	email
  PhoneNumber	telephoneNumber	phone_number
  Username	userPrincipalName	username
  EmployeeId	employeeID	employee_id
  Department	department	department
  JobTitle	title	job_title
  CompanyName	company	company_name
  н/д	ObjectGUID	external_id

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

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

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

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

  Имя атрибута в конфигурации агента	Имя атрибута в Active Directory (по умолчанию)	Имя атрибута в Yandex Identity Hub
  Name	name	name
  Description	description	description
  н/д	ObjectGUID	external_id

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

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

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

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

  Внимание

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

Обратная запись паролей в Active DirectoryОбратная запись паролей в Active Directory

Агент синхронизации позволяет выполнять обратную запись паролей пользователей (password writeback) в Active Directory. Обратная запись паролей обновляет пароль пользователя в Active Directory, если пароль этого пользователя был изменен на стороне Yandex Identity Hub в следующих случаях:

• пользователь, для которого настроена синхронизация с Active Directory, изменил свой пароль в Yandex Identity Hub;
• администратор организации сбросил пароль пользователя, для которого настроена синхронизация с Active Directory;
• пользователь, для которого настроена синхронизация с Active Directory, установил новый пароль в Yandex Identity Hub после того, как пароль этого пользователя был сброшен администратором.

Обратная запись паролей выполняется в следующем порядке:

1. Пользователь или администратор выполняют запрос на изменение пароля пользователя в Yandex Identity Hub.

2. Агент синхронизации предпринимает попытку обновить пароль этого пользователя в Active Directory.

   Попытка смены пароля в Active Directory может завершиться неудачей. Например, если новый пароль не соответствует требованиям, которые установлены в политиках безопасности Active Directory.

3. Если попытка изменить пароль в Active Directory завершилась успехом, пароль пользователя изменяется также и на стороне Yandex Identity Hub.

4. Если попытка изменить пароль в Active Directory завершилась неудачей, пароль пользователя на стороне Yandex Identity Hub также остается неизменным.

Для работы обратной записи паролей аккаунту Active Directory, от имени которого агент выполняет синхронизацию, дополнительно нужны разрешения Change Password, Reset Password и Write pwdLastSet. Назначьте их на весь домен или на те Organization Units (OU), которые попадают под выбранные в конфигурации агента фильтры sync_settings.filter.

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

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

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

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

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

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

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

2. Выдайте этому аккаунту следующие разрешения на домен, указанный в конфигурации агента в секции sync_settings.filter:

   • Replicating Directory Changes;
   • Replicating Directory Changes All.

   Если вы используете обратную запись паролей, дополнительно выдайте аккаунту следующие разрешения на Organization Units (OU), указанные в конфигурации агента в секции sync_settings.filter, или на весь домен:

   • Change Password;
   • Reset Password;
   • Write pwdLastSet.

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

   • 389 (TCP) — для LDAP;
   • 636 (TCP) — для LDAPS;
   • 135 (TCP) — для MSRPC;
   • 49152:65535 (TCP) — диапазон портов для MSRPC dynamic;
   • 53 (TCP/UDP) и 88 (TCP/UDP) — для Kerberos.

4. (Опционально) Если вы планируете настраивать аутентификацию с использованием протокола Kerberos, настройте SPN.

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

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

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

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

  • organization-manager.userpools.syncAgent;
  • organization-manager.groups.viewer;
  • organization-manager.groups.externalCreator;
  • organization-manager.groups.externalConverter.

  Если вы планируете выгружать логи работы агента синхронизации в лог-группу Yandex Cloud Logging, дополнительно назначьте сервисному аккаунту роль logging.writer на соответствующую лог-группу или каталог, в котором она расположена.

• (Опционально) Создайте и сохраните авторизованный ключ сервисного аккаунта.

  Важно

  Авторизованный ключ не нужен, если агент синхронизации устанавливается на виртуальную машину Yandex Compute Cloud, к которой привязан сервисный аккаунт с необходимыми правами доступа.

Агент синхронизацииАгент синхронизации

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

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

• Linux;
• Windows.

Аутентификация на стороне Active DirectoryАутентификация на стороне Active Directory

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

Вне зависимости от операционной системы сервера, на котором установлен агент синхронизации, аутентификация агента на стороне Active Directory может осуществляться по имени и паролю пользователя домена или с использованием протокола Kerberos версии 5.

Кроме того, при установке агента синхронизации на сервер с ОС Windows аутентификацию агента на стороне Active Directory можно настроить от имени аккаунта gMSA.

Аутентификация на стороне Yandex CloudАутентификация на стороне Yandex Cloud

На стороне Yandex Cloud агент синхронизации управляет пользователями и группами пользователей от имени сервисного аккаунта с назначенными разрешениями на выполнение синхронизации. Запросы к Yandex Cloud направляются на публичный эндпоинт https://organization-manager.api.yandexcloud.kz по протоколу HTTPS. Для аутентификации агента в API Yandex Cloud используется авторизованный ключ сервисного аккаунта или (только при установке на ВМ Compute Cloud) — IAM-токен сервисного аккаунта, получаемый через сервис метаданных ВМ.

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

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

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

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

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

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

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

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

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

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

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

Тестовый запуск (dry run)Тестовый запуск (dry run)

Агент Yandex Identity Hub Sync Agent можно запустить в тестовом режиме (dry run). Этот режим позволяет убедиться в корректности вносимых в конфигурацию агента изменений, прежде чем применять эти изменения в рабочем режиме.

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

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

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

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

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

Если для учетной записи пользователя на стороне Active Directory задано значение поля accountExpires, агент синхронизирует это значение с полем Дата деактивации (expires_at) в свойствах локального пользователя Yandex Identity Hub. При наступлении момента, указанного в этом поле, локальный пользователь Yandex Identity Hub будет автоматически деактивирован.

В этом случае, чтобы повторно активировать пользователя, измените или удалите значение поля accountExpires для учетной записи пользователя на стороне Active Directory.

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

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

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

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

В конфигурации агента вы также можете настроить выгрузку логов в лог-группу Yandex Cloud Logging.

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

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

Проверка прав доступа к файлам с аутентификационными даннымиПроверка прав доступа к файлам с аутентификационными данными

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

• файл конфигурации агента может содержать пароль от учетной записи пользователя, от имени которого агент выполняет синхронизацию на стороне Active Directory;
• файл keytab содержит ключи шифрования, необходимые для аутентификации в Active Directory по протоколу Kerberos;
• файл с авторизованным ключом сервисного аккаунта содержит ключ, позволяющий получить доступ к Yandex Cloud.

Если проверка прав доступа включена, при запуске агент синхронизации проверяет соблюдение следующих условий:

Если при запуске агент выявляет нарушение указанных условий, запуск завершается ошибкой.

Включить или отключить проверку прав доступа к файлам с чувствительной информацией можно с помощью параметра check_config_permissions конфигурации агента.

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

Конфигурация агента синхронизации задается в YAML-файле и зависит от способа аутентификации на стороне Active Directory.

Примеры конфигурации приведены в инструкции по настройке синхронизации, а описание полей — в разделе Параметры конфигурации агента.

Полезные ссылкиПолезные ссылки

• Синхронизировать пользователей и группы с Microsoft Active Directory
• Синхронизация пользователей и групп с LDAP-совместимыми службами каталогов

gMSA (group Managed Service Account) — это тип учетных записей в Microsoft Active Directory, паролями для которых автоматически управляет контроллер домена, что упрощает запуск и работу одной и той же службы (SPN) на разных серверах. Подробнее читайте в документации Microsoft.