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

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

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

   curl https://storage.yandexcloud.net/yc-identityhub-sync/install.sh | bash
   

   Результат:

   Example config file downloaded to /etc/yc-identityhub-sync-agent/config.yaml. Modify it with your values
   Service installed as yc-identityhub-sync-agent
   To start the service: sudo systemctl start yc-identityhub-sync-agent
   To enable the service to start on boot: sudo systemctl enable yc-identityhub-sync-agent
   To check service status: sudo systemctl status yc-identityhub-sync-agent
   yc-identityhub-sync-agent is installed to /usr/bin/yc-identityhub-sync-agent
   

2. (Опционально) Если для аутентификации агента в API Yandex Cloud вы будете использовать авторизованный ключ сервисного аккаунта, скопируйте на ваш сервер файл с сохраненным ранее авторизованным ключом.

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

3. В любом текстовом редакторе откройте YAML-файл с конфигурацией агента синхронизации. В примере ниже используется редактор nano:

   nano /etc/yc-identityhub-sync-agent/config.yaml
   

4. В открывшемся файле задайте конфигурацию агента синхронизации:

   # Default configuration for yc-identityhub-sync-agent
   # This is a template - please update with your actual values
   
   userpool_id: "<идентификатор_пула_пользователей>"
   replication_tokens_path: "<путь_к_директории_с_токенами_процессов>"
   working_directory: "<путь_к_рабочей_директории_агента>"
   
   # 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
   
   # 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 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.

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

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

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

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

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

   • 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, replication_tokens_path и/или logger.file.filename заданы пути, отличные от пути, заданного в параметре working_directory, для выбранных сущностей будут использоваться пути, указанные в параметрах cloud_credentials_file_path, replication_tokens_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.

   • 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 — параметр, позволяющий изменять существующего пользователя пула 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.net.

       Необязательный параметр. Значение параметра 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. Запустите сервис агента Identity Hub AD Sync Agent, чтобы начать процесс синхронизации:

   sudo systemctl start yc-identityhub-sync-agent
   

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

   sudo cat /etc/yc-identityhub-sync-agent/identity_hub.log
   

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

7. Чтобы остановить синхронизацию, остановите запущенный процесс агента синхронизации:

   sudo systemctl stop yc-identityhub-sync-agent
   

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