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

В терминале PowerShell:

1. Чтобы установить агент Identity Hub AD Sync Agent, выполните команду:

   iex (New-Object System.Net.WebClient).DownloadString('https://storage.yandexcloud.net/yc-identityhub-sync/install.ps1')
   

   Результат:

   Example config file downloaded to C:\ProgramData\YcIdentityHubSyncAgent\config.yaml. Modify it with your values
   yc-identityhub-sync-agent is installed to C:\Program Files\YcIdentityHubSyncAgent\bin\yc-identityhub-sync-agent.exe
   Config file is located at C:\ProgramData\YcIdentityHubSyncAgent\config.yaml
   
   Status   Name               DisplayName
   ------   ----               -----------
   Stopped  yc-identityhub-... Yandex Identity Hub Sync Agent
   yc-identityhub-sync-agent installed as Windows service 'yc-identityhub-sync-agent' (not started automatically)
   1. Modify the config file at C:\ProgramData\YcIdentityHubSyncAgent\config.yaml with your values
   2. Run: Start-Service yc-identityhub-sync-agent
   

2. Скопируйте на ваш сервер файл с сохраненным ранее авторизованным ключом сервисного аккаунта. Для этого вы можете воспользоваться любым подходящим инструментом.

3. В любом текстовом редакторе откройте YAML-файл конфигурации агента config.yaml, расположенный в папке C:\ProgramData\YcIdentityHubSyncAgent\.

4. В открывшемся файле задайте конфигурацию агента синхронизации. Конфигурация зависит от способа аутентификации, используемого агентом на стороне Active Directory, и задается в YAML-файле в следующем формате:

   От имени аккаунта gMSA

   По логину и паролю

   По протоколу Kerberos

   # Default configuration for yc-identityhub-sync-agent
   # This is a template - please update with your actual values
   
   userpool_id: "<идентификатор_пула_пользователей>"
   working_directory: "<путь_к_рабочей_директории_агента>"
   
   # Validate config, static credentials, and configured keytab file permissions at startup.
   check_config_permissions: true|false
   
   # Yandex Cloud authentication settings
   
   # Use the cloud_credentials_file_path parameter for authentication via an authorized key.
   # If you want the agent to authenticate via IAM tokens, remove the cloud_credentials_file_path line.
   cloud_credentials_file_path: "<путь_к_файлу_с_авторизованным_ключом>"
   
   # Enable the use_metadata_service parameter for authentication via IAM tokens
   # (only available when the agent is installed on a Compute Cloud VM).
   # If `true`, the cloud_credentials_file_path parameter will be ignored.
   use_metadata_service: true|false
   
   # Enable Password Writeback so the agent can synchronize password changes
   # back from Yandex Identity Hub to Active Directory.
   enable_password_writeback: true|false
   
   # Enable the Dry Run mode.
   # If `true`, no changes will be applied to users or groups in Yandex Identity Hub.
   # Instead, all pending operations will be saved to the current log file location.
   dry_run:
     enabled: true|false
   
   # Active Directory replication API client settings
   drsr:
     host: "<адрес_контроллера_домена>"
     use_windows_identity: true
   
   # LDAP client settings
   ldap:
     host: "ldaps://<адрес_контроллера_домена>:636"
     certificate_path: "<путь_к_CA_сертификату>"
     insecure_skip_verify: false|true
     use_windows_identity: true
   
   # Logger configuration
   logger:
     level: "<уровень_логирования>"
     format: "plain|json"
     file:
       filename: "<путь_к_файлу_с_логами>"
       maxsize: 30
       maxbackups: 10
     cloud_logger:
       log_group_id: <идентификатор_лог-группы>
   
   # Sync settings
   sync_settings:
     interval: "600s"
     allow_to_capture_users: true|false
     allow_to_capture_groups: true|false
     # Remove the replacement_domain line if you don't need to replace domain
     replacement_domain: "<домен_пула_пользователей>"
     # Remove the user_attribute_mapping section if you don't need to remap default user attribute names
     # If you need remapping, the user_attribute_mapping section should only contain the attributes you need to remap
     user_attribute_mapping:
       # The following syntax allows to reconfigure the default mapping ('displayName' --> 'full_name')
       # to custom mapping ('CustomAttributeName' --> 'full_name')
       - source: "CustomAttributeName"
         target: "FullName"
         type: "direct"
       # The following syntax allows to disable synchronization for attribute 'given_name'
       - source: ""
         target: "GivenName"
         type: "empty"
     # Remove the group_attribute_mapping section if you don't need to remap default group attribute names
     # If you need remapping, the group_attribute_mapping section should only contain the attributes you need to remap
     group_attribute_mapping:
       # The following syntax allows to reconfigure the default mapping ('name' --> 'name')
       # to custom mapping ('CustomAttributeName' --> 'name')
       - source: "CustomAttributeName"
         target: "Name"
         type: "direct"
       # The following syntax allows to disable synchronization for attribute 'description'
       - source: ""
         target: "Description"
         type: "empty"
     filter:
       domain: "<имя_домена_в_Active_Directory>"
       organization_units:
         - OU=IdPUsersOU,DC=example,DC=com
         - OU=IdPGroupsOU,DC=example,DC=com
       groups:
         - "GroupName1"
         - "GroupName2"
     remove_user_behavior: "remove|block"
   

   Описание параметров

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

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

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

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

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

     • true — проверка прав доступа к файлам конфигурации агента, содержащим чувствительные данные, включена.
     • false — проверка прав доступа к файлам конфигурации агента отключена. Значение по умолчанию.

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

     Примеры значений:

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

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

     Примечание

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

   • use_metadata_service — параметр, управляющий аутентификацией агента в API Yandex Cloud с помощью IAM-токена и позволяющий агенту получать IAM-токены через сервис метаданных ВМ.

     Возможные значения:

     • true — агент синхронизации будет получать IAM-токены сервисного аккаунта через сервис метаданных виртуальной машины и использовать их для аутентификации в API Yandex Cloud. Значение параметра cloud_credentials_file_path при этом будет игнорироваться.

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

     • false — агент синхронизации не будет получать IAM-токены, а аутентификация в API Yandex Cloud будет выполняться с помощью авторизованного ключа, заданного в параметре cloud_credentials_file_path.

   • enable_password_writeback — параметр, управляющий обратной записью паролей пользователей в Active Directory.

     Примечание

     Функциональность обратной записи паролей находится на стадии Preview. Чтобы получить к ней доступ, обратитесь в техническую поддержку или к вашему аккаунт-менеджеру.

     Возможные значения:

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

   • dry_run — настройки тестового запуска агента (dry run):

     • enabled: true — активирован режим dry run. Агент не вносит изменения в данные пользователей и групп Yandex Identity Hub. Вместо этого он тестирует выполнение всех предусмотренных конфигурацией агента операций и сохраняет результаты этих тестов в логах его работы.
     • enabled: false — агент функционирует в рабочем режиме, необходимые изменения вносятся в данные пользователей и групп Yandex Identity Hub.

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

     • host — домен или IP-адрес контроллера домена Active Directory.

     • use_windows_identity: true — параметр, который устанавливает для агента синхронизации требование аутентифицироваться на стороне Active Directory от имени аккаунта gMSA.

       Важно

       Чтобы агент синхронизации мог аутентифицироваться на стороне Active Directory от имени аккаунта gMSA, служба агента на сервере также должна быть запущена от имени этого аккаунта gMSA.

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

     Важно

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

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

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

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

       Укажите этот параметр, если вы используете протокол LDAPS и корневой сертификат отсутствует в системном хранилище доверенных сертификатов.

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

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

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

     • use_windows_identity: true — параметр, который устанавливает для агента синхронизации требование аутентифицироваться на стороне Active Directory от имени аккаунта gMSA.

       Важно

       Чтобы агент синхронизации мог аутентифицироваться на стороне Active Directory от имени аккаунта gMSA, служба агента на сервере также должна быть запущена от имени этого аккаунта gMSA.

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

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

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

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

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

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

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

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

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

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

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

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

     • cloud_logger — настройки сохранения логов в лог-группу Yandex Cloud Logging:

       • log_group_id — идентификатор лог-группы, в которую будут выгружаться логи работы агента синхронизации.

       Необязательный параметр. Если настройки в разделе cloud_logger не заданы, события не будут выгружаться в лог-группу.

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

     Примечание

     Если настройки в разделах logger.file и logger.cloud_logger не заданы, информация о событиях и ошибках будет выводиться в стандартный поток stdout. В противном случае логи будут сохраняться в файлы и/или лог-группу.

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

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

       Примечание

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

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

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

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

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

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

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

     • user_attribute_mapping — настройки сопоставления атрибутов пользователя:

       • source — имя атрибута пользователя, получаемое из Active Directory и отличное от имени, заданного по умолчанию.

         Если вы хотите отключить синхронизацию атрибута, оставьте значение пустым: source: "".

       • target — имя атрибута на стороне Yandex Cloud, с которым настраивается сопоставление (или для которого отключается синхронизация). Список доступных значений смотрите в таблице Атрибуты пользователей в разделе Объекты синхронизации.

       • type — выбор действия в отношении указанного атрибута. Возможные значения:

         • direct — настроить сопоставление атрибутов.
         • empty — отключить синхронизацию атрибута.

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

     • group_attribute_mapping — настройки сопоставления атрибутов групп пользователей:

       • source — имя атрибута групп пользователей, получаемое из Active Directory и отличное от имени, заданного по умолчанию.

         Если вы хотите отключить синхронизацию атрибута, оставьте значение пустым: source: "".

       • target — имя атрибута на стороне Yandex Cloud, с которым настраивается сопоставление (или для которого отключается синхронизация). Список доступных значений смотрите в таблице Атрибуты групп пользователей в разделе Объекты синхронизации.

       • type — выбор действия в отношении указанного атрибута. Возможные значения:

         • direct — настроить сопоставление атрибутов.
         • empty — отключить синхронизацию атрибута.

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

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

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

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

       • groups — список групп пользователей в каталоге Active Directory, в которых агент будет синхронизировать пользователей. Вы можете указать одну или несколько групп, при этом фильтр по нескольким группам будет применяться с логикой ИЛИ.

         Примечание

         Параметр groups влияет только на синхронизацию пользователей и не влияет на настройки синхронизации групп пользователей.

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

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

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

     Примечание

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

   # Default configuration for yc-identityhub-sync-agent
   # This is a template - please update with your actual values
   
   userpool_id: "<идентификатор_пула_пользователей>"
   working_directory: "<путь_к_рабочей_директории_агента>"
   
   # Validate config, static credentials, and configured keytab file permissions at startup.
   check_config_permissions: true|false
   
   # Yandex Cloud authentication settings
   
   # Use the cloud_credentials_file_path parameter for authentication via an authorized key.
   # If you want the agent to authenticate via IAM tokens, remove the cloud_credentials_file_path line.
   cloud_credentials_file_path: "<путь_к_файлу_с_авторизованным_ключом>"
   
   # Enable the use_metadata_service parameter for authentication via IAM tokens
   # (only available when the agent is installed on a Compute Cloud VM).
   # If `true`, the cloud_credentials_file_path parameter will be ignored.
   use_metadata_service: true|false
   
   # Enable Password Writeback so the agent can synchronize password changes
   # back from Yandex Identity Hub to Active Directory.
   enable_password_writeback: true|false
   
   # Enable the Dry Run mode.
   # If `true`, no changes will be applied to users or groups in Yandex Identity Hub.
   # Instead, all pending operations will be saved to the current log file location.
   dry_run:
     enabled: true|false
   
   # Active Directory replication API client settings
   drsr:
     host: "<адрес_контроллера_домена>"
     username: "<sAMAccountName_пользователя_Active_Directory>"
     password: "password"
   
   # LDAP client settings
   ldap:
     host: "ldaps://<адрес_контроллера_домена>:636"
     username: "<DN_пользователя_Active_Directory>"
     password: "<пароль_пользователя_Active_Directory>"
     certificate_path: "<путь_к_CA_сертификату>"
     insecure_skip_verify: false|true
   
   # Logger configuration
   logger:
     level: "<уровень_логирования>"
     format: "plain|json"
     file:
       filename: "<путь_к_файлу_с_логами>"
       maxsize: 30
       maxbackups: 10
     cloud_logger:
       log_group_id: <идентификатор_лог-группы>
   
   # Sync settings
   sync_settings:
     interval: "600s"
     allow_to_capture_users: true|false
     allow_to_capture_groups: true|false
     # Remove the replacement_domain line if you don't need to replace domain
     replacement_domain: "<домен_пула_пользователей>"
     # Remove the user_attribute_mapping section if you don't need to remap default user attribute names
     # If you need remapping, the user_attribute_mapping section should only contain the attributes you need to remap
     user_attribute_mapping:
       # The following syntax allows to reconfigure the default mapping ('displayName' --> 'full_name')
       # to custom mapping ('CustomAttributeName' --> 'full_name')
       - source: "CustomAttributeName"
         target: "FullName"
         type: "direct"
       # The following syntax allows to disable synchronization for attribute 'given_name'
       - source: ""
         target: "GivenName"
         type: "empty"
     # Remove the group_attribute_mapping section if you don't need to remap default group attribute names
     # If you need remapping, the group_attribute_mapping section should only contain the attributes you need to remap
     group_attribute_mapping:
       # The following syntax allows to reconfigure the default mapping ('name' --> 'name')
       # to custom mapping ('CustomAttributeName' --> 'name')
       - source: "CustomAttributeName"
         target: "Name"
         type: "direct"
       # The following syntax allows to disable synchronization for attribute 'description'
       - source: ""
         target: "Description"
         type: "empty"
     filter:
       domain: "<имя_домена_в_Active_Directory>"
       organization_units:
         - OU=IdPUsersOU,DC=example,DC=com
         - OU=IdPGroupsOU,DC=example,DC=com
       groups:
         - "GroupName1"
         - "GroupName2"
     remove_user_behavior: "remove|block"
   

   Описание параметров

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

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

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

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

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

     • true — проверка прав доступа к файлам конфигурации агента, содержащим чувствительные данные, включена.
     • false — проверка прав доступа к файлам конфигурации агента отключена. Значение по умолчанию.

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

     Примеры значений:

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

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

     Примечание

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

   • use_metadata_service — параметр, управляющий аутентификацией агента в API Yandex Cloud с помощью IAM-токена и позволяющий агенту получать IAM-токены через сервис метаданных ВМ.

     Возможные значения:

     • true — агент синхронизации будет получать IAM-токены сервисного аккаунта через сервис метаданных виртуальной машины и использовать их для аутентификации в API Yandex Cloud. Значение параметра cloud_credentials_file_path при этом будет игнорироваться.

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

     • false — агент синхронизации не будет получать IAM-токены, а аутентификация в API Yandex Cloud будет выполняться с помощью авторизованного ключа, заданного в параметре cloud_credentials_file_path.

   • enable_password_writeback — параметр, управляющий обратной записью паролей пользователей в Active Directory.

     Примечание

     Функциональность обратной записи паролей находится на стадии Preview. Чтобы получить к ней доступ, обратитесь в техническую поддержку или к вашему аккаунт-менеджеру.

     Возможные значения:

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

   • dry_run — настройки тестового запуска агента (dry run):

     • enabled: true — активирован режим dry run. Агент не вносит изменения в данные пользователей и групп Yandex Identity Hub. Вместо этого он тестирует выполнение всех предусмотренных конфигурацией агента операций и сохраняет результаты этих тестов в логах его работы.
     • enabled: false — агент функционирует в рабочем режиме, необходимые изменения вносятся в данные пользователей и групп Yandex Identity Hub.

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

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

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

     Важно

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

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

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

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

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

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

       Укажите этот параметр, если вы используете протокол 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 не заданы, события не будут сохраняться в файлы.

     • cloud_logger — настройки сохранения логов в лог-группу Yandex Cloud Logging:

       • log_group_id — идентификатор лог-группы, в которую будут выгружаться логи работы агента синхронизации.

       Необязательный параметр. Если настройки в разделе cloud_logger не заданы, события не будут выгружаться в лог-группу.

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

     Примечание

     Если настройки в разделах logger.file и logger.cloud_logger не заданы, информация о событиях и ошибках будет выводиться в стандартный поток stdout. В противном случае логи будут сохраняться в файлы и/или лог-группу.

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

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

       Примечание

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

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

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

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

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

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

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

     • user_attribute_mapping — настройки сопоставления атрибутов пользователя:

       • source — имя атрибута пользователя, получаемое из Active Directory и отличное от имени, заданного по умолчанию.

         Если вы хотите отключить синхронизацию атрибута, оставьте значение пустым: source: "".

       • target — имя атрибута на стороне Yandex Cloud, с которым настраивается сопоставление (или для которого отключается синхронизация). Список доступных значений смотрите в таблице Атрибуты пользователей в разделе Объекты синхронизации.

       • type — выбор действия в отношении указанного атрибута. Возможные значения:

         • direct — настроить сопоставление атрибутов.
         • empty — отключить синхронизацию атрибута.

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

     • group_attribute_mapping — настройки сопоставления атрибутов групп пользователей:

       • source — имя атрибута групп пользователей, получаемое из Active Directory и отличное от имени, заданного по умолчанию.

         Если вы хотите отключить синхронизацию атрибута, оставьте значение пустым: source: "".

       • target — имя атрибута на стороне Yandex Cloud, с которым настраивается сопоставление (или для которого отключается синхронизация). Список доступных значений смотрите в таблице Атрибуты групп пользователей в разделе Объекты синхронизации.

       • type — выбор действия в отношении указанного атрибута. Возможные значения:

         • direct — настроить сопоставление атрибутов.
         • empty — отключить синхронизацию атрибута.

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

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

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

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

       • groups — список групп пользователей в каталоге Active Directory, в которых агент будет синхронизировать пользователей. Вы можете указать одну или несколько групп, при этом фильтр по нескольким группам будет применяться с логикой ИЛИ.

         Примечание

         Параметр groups влияет только на синхронизацию пользователей и не влияет на настройки синхронизации групп пользователей.

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

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

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

     Примечание

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

   # Default configuration for yc-identityhub-sync-agent
   # This is a template - please update with your actual values
   
   userpool_id: "<идентификатор_пула_пользователей>"
   working_directory: "<путь_к_рабочей_директории_агента>"
   
   # Validate config, static credentials, and configured keytab file permissions at startup.
   check_config_permissions: true|false
   
   # Yandex Cloud authentication settings
   
   # Use the cloud_credentials_file_path parameter for authentication via an authorized key.
   # If you want the agent to authenticate via IAM tokens, remove the cloud_credentials_file_path line.
   cloud_credentials_file_path: "<путь_к_файлу_с_авторизованным_ключом>"
   
   # Enable the use_metadata_service parameter for authentication via IAM tokens
   # (only available when the agent is installed on a Compute Cloud VM).
   # If `true`, the cloud_credentials_file_path parameter will be ignored.
   use_metadata_service: true|false
   
   # Enable Password Writeback so the agent can synchronize password changes
   # back from Yandex Identity Hub to Active Directory.
   enable_password_writeback: true|false
   
   # Enable the Dry Run mode.
   # If `true`, no changes will be applied to users or groups in Yandex Identity Hub.
   # Instead, all pending operations will be saved to the current log file location.
   dry_run:
     enabled: true|false
   
   # Active Directory replication API client settings
   drsr:
     host: "<адрес_контроллера_домена>"
     use_kerberos: true
   
   # LDAP client settings
   ldap:
     host: "ldaps://<адрес_контроллера_домена>:636"
     certificate_path: "<путь_к_CA_сертификату>"
     insecure_skip_verify: false|true
     use_kerberos: true
   
   # Kerberos settings
   kerberos:
     keytab_path: "<путь_к_файлу_keytab>"
     principal: "<SPN_пользователя_в_Active_Directory>"
     krb5_config_path: "<путь_к_файлу_конфигурации_Kerberos>"  # optional, the default location is /etc/krb5.conf or whatever path is set in the KRB5_CONFIG environment variable
     disable_pa_fx_fast: true
   
   # Logger configuration
   logger:
     level: "<уровень_логирования>"
     format: "plain|json"
     file:
       filename: "<путь_к_файлу_с_логами>"
       maxsize: 30
       maxbackups: 10
     cloud_logger:
       log_group_id: <идентификатор_лог-группы>
   
   # Sync settings
   sync_settings:
     interval: "600s"
     allow_to_capture_users: true|false
     allow_to_capture_groups: true|false
     # Remove the replacement_domain line if you don't need to replace domain
     replacement_domain: "<домен_пула_пользователей>"
     # Remove the user_attribute_mapping section if you don't need to remap default user attribute names
     # If you need remapping, the user_attribute_mapping section should only contain the attributes you need to remap
     user_attribute_mapping:
       # The following syntax allows to reconfigure the default mapping ('displayName' --> 'full_name')
       # to custom mapping ('CustomAttributeName' --> 'full_name')
       - source: "CustomAttributeName"
         target: "FullName"
         type: "direct"
       # The following syntax allows to disable synchronization for attribute 'given_name'
       - source: ""
         target: "GivenName"
         type: "empty"
     # Remove the group_attribute_mapping section if you don't need to remap default group attribute names
     # If you need remapping, the group_attribute_mapping section should only contain the attributes you need to remap
     group_attribute_mapping:
       # The following syntax allows to reconfigure the default mapping ('name' --> 'name')
       # to custom mapping ('CustomAttributeName' --> 'name')
       - source: "CustomAttributeName"
         target: "Name"
         type: "direct"
       # The following syntax allows to disable synchronization for attribute 'description'
       - source: ""
         target: "Description"
         type: "empty"
     filter:
       domain: "<имя_домена_в_Active_Directory>"
       organization_units:
         - OU=IdPUsersOU,DC=example,DC=com
         - OU=IdPGroupsOU,DC=example,DC=com
       groups:
         - "GroupName1"
         - "GroupName2"
     remove_user_behavior: "remove|block"
   

   Описание параметров

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

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

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

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

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

     • true — проверка прав доступа к файлам конфигурации агента, содержащим чувствительные данные, включена.
     • false — проверка прав доступа к файлам конфигурации агента отключена. Значение по умолчанию.

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

     Примеры значений:

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

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

     Примечание

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

   • use_metadata_service — параметр, управляющий аутентификацией агента в API Yandex Cloud с помощью IAM-токена и позволяющий агенту получать IAM-токены через сервис метаданных ВМ.

     Возможные значения:

     • true — агент синхронизации будет получать IAM-токены сервисного аккаунта через сервис метаданных виртуальной машины и использовать их для аутентификации в API Yandex Cloud. Значение параметра cloud_credentials_file_path при этом будет игнорироваться.

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

     • false — агент синхронизации не будет получать IAM-токены, а аутентификация в API Yandex Cloud будет выполняться с помощью авторизованного ключа, заданного в параметре cloud_credentials_file_path.

   • enable_password_writeback — параметр, управляющий обратной записью паролей пользователей в Active Directory.

     Примечание

     Функциональность обратной записи паролей находится на стадии Preview. Чтобы получить к ней доступ, обратитесь в техническую поддержку или к вашему аккаунт-менеджеру.

     Возможные значения:

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

   • dry_run — настройки тестового запуска агента (dry run):

     • enabled: true — активирован режим dry run. Агент не вносит изменения в данные пользователей и групп Yandex Identity Hub. Вместо этого он тестирует выполнение всех предусмотренных конфигурацией агента операций и сохраняет результаты этих тестов в логах его работы.
     • enabled: false — агент функционирует в рабочем режиме, необходимые изменения вносятся в данные пользователей и групп Yandex Identity Hub.

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

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

     Важно

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

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

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

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

       Укажите этот параметр, если вы используете протокол LDAPS и корневой сертификат отсутствует в системном хранилище доверенных сертификатов.

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

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

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

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

   • kerberos — настройки протокола Kerberos для аутентификации на стороне Active Directory:

     • keytab_path — путь к файлу keytab с ключами шифрования.
     • principal — SPN пользовательского аккаунта для подключения к Active Directory.
     • krb5_config_path — путь к файлу конфигурации Kerberos. Необязательный параметр. По умолчанию используется путь /etc/krb5.conf или значение, заданное в переменной окружения KRB5_CONFIG.
     • disable_pa_fx_fast: true — параметр, управляющий режимом FAST.

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

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

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

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

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

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

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

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

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

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

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

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

     • cloud_logger — настройки сохранения логов в лог-группу Yandex Cloud Logging:

       • log_group_id — идентификатор лог-группы, в которую будут выгружаться логи работы агента синхронизации.

       Необязательный параметр. Если настройки в разделе cloud_logger не заданы, события не будут выгружаться в лог-группу.

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

     Примечание

     Если настройки в разделах logger.file и logger.cloud_logger не заданы, информация о событиях и ошибках будет выводиться в стандартный поток stdout. В противном случае логи будут сохраняться в файлы и/или лог-группу.

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

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

       Примечание

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

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

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

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

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

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

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

     • user_attribute_mapping — настройки сопоставления атрибутов пользователя:

       • source — имя атрибута пользователя, получаемое из Active Directory и отличное от имени, заданного по умолчанию.

         Если вы хотите отключить синхронизацию атрибута, оставьте значение пустым: source: "".

       • target — имя атрибута на стороне Yandex Cloud, с которым настраивается сопоставление (или для которого отключается синхронизация). Список доступных значений смотрите в таблице Атрибуты пользователей в разделе Объекты синхронизации.

       • type — выбор действия в отношении указанного атрибута. Возможные значения:

         • direct — настроить сопоставление атрибутов.
         • empty — отключить синхронизацию атрибута.

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

     • group_attribute_mapping — настройки сопоставления атрибутов групп пользователей:

       • source — имя атрибута групп пользователей, получаемое из Active Directory и отличное от имени, заданного по умолчанию.

         Если вы хотите отключить синхронизацию атрибута, оставьте значение пустым: source: "".

       • target — имя атрибута на стороне Yandex Cloud, с которым настраивается сопоставление (или для которого отключается синхронизация). Список доступных значений смотрите в таблице Атрибуты групп пользователей в разделе Объекты синхронизации.

       • type — выбор действия в отношении указанного атрибута. Возможные значения:

         • direct — настроить сопоставление атрибутов.
         • empty — отключить синхронизацию атрибута.

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

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

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

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

       • groups — список групп пользователей в каталоге Active Directory, в которых агент будет синхронизировать пользователей. Вы можете указать одну или несколько групп, при этом фильтр по нескольким группам будет применяться с логикой ИЛИ.

         Примечание

         Параметр groups влияет только на синхронизацию пользователей и не влияет на настройки синхронизации групп пользователей.

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

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

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

     Примечание

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

5. Запустите службу агента синхронизации:

   Start-Service yc-identityhub-sync-agent
   

   Важно

   Чтобы агент синхронизации мог аутентифицироваться на стороне Active Directory от имени аккаунта gMSA, служба агента на сервере также должна быть запущена от имени этого аккаунта gMSA.

6. Чтобы убедиться, что процесс синхронизации идет, посмотрите файл с логами агента. Например:

   cat C:\ProgramData\YcIdentityHubSyncAgent\identity_hub.log
   

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

7. Чтобы остановить процесс синхронизации, остановите созданную службу:

   Stop-Service yc-identityhub-sync-agent
   

   В результате процесс синхронизации пользователей и групп будет остановлен.

1. В терминале PowerShell остановите службу агента синхронизации:

   Stop-Service yc-identityhub-sync-agent
   

2. Внесите в конфигурацию агента изменения, которые вы хотите протестировать.

3. В секции dry_run файла конфигурации агента включите режим dry run:

   ...
   dry_run:
     enabled: true
   ...
   

4. В терминале PowerShell вручную запустите исполняемый файл агента и дождитесь завершения его работы:

   ./yc-identityhub-sync-agent.exe \
     --config C:\ProgramData\YcIdentityHubSyncAgent\config.yaml
   

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

   Например:

   2026-04-22T06:46:35.504Z	info	synchronization/sync_process.go:542	Would synchronize Users. Change type: Create. Successful: 10. Failed: 0
   2026-04-22T06:46:35.504Z	info	synchronization/sync_process.go:542	Would synchronize Users. Change type: Update. Successful: 0. Failed: 0
   2026-04-22T06:46:35.504Z	info	synchronization/sync_process.go:542	Would synchronize Users. Change type: Delete. Successful: 2. Failed: 0
   2026-04-22T06:46:35.504Z	info	synchronization/sync_process.go:542	Would synchronize Users. Change type: Activate. Successful: 0. Failed: 0
   2026-04-22T06:46:35.504Z	info	synchronization/sync_process.go:542	Would synchronize Users. Change type: Deactivate. Successful: 0. Failed: 0
   2026-04-22T06:46:35.504Z	info	synchronization/sync_process.go:542	Would synchronize Users. Change type: PasswordHashUpdate. Successful: 300. Failed: 0
   2026-04-22T06:46:35.504Z	info	synchronization/sync_process.go:542	Would synchronize Groups. Change type: Create. Successful: 5. Failed: 0
   2026-04-22T06:46:35.504Z	info	synchronization/sync_process.go:542	Would synchronize Groups. Change type: Update. Successful: 0. Failed: 0
   2026-04-22T06:46:35.504Z	info	synchronization/sync_process.go:542	Would synchronize Groups. Change type: Delete. Successful: 0. Failed: 0
   2026-04-22T06:46:35.504Z	info	synchronization/sync_process.go:542	Would synchronize Memberships. Change type: Create. Successful: 30. Failed: 0
   2026-04-22T06:46:35.504Z	info	synchronization/sync_process.go:542	Would synchronize Memberships. Change type: Delete. Successful: 0. Failed: 0
   

   Из приведенного примера видно, что после запуска синхронизации в Yandex Identity Hub:

   • будет создано 10 новых пользователей;
   • будет удалено 2 пользователя;
   • будут обновлены хеши паролей для 300 пользователей;
   • будет создано 5 групп пользователей;
   • будет добавлено 30 новых членств пользователей в группах.

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

   1. Отключите режим dry run, заменив в файле конфигурации в секции dry_run значение поля на enabled: false.

   2. В терминале PowerShell запустите службу агента Identity Hub AD Sync Agent, чтобы начать процесс синхронизации:

      Start-Service yc-identityhub-sync-agent