Технический справочник по соединителю Windows PowerShell
В этой статье описан соединитель Windows PowerShell. Статья относится к следующим продуктам:
- Microsoft Identity Manager 2016 (MIM2016);
Для MIM2016 соединитель доступен для скачивания из Центра загрузки Майкрософт.
Общие сведения о соединителе PowerShell
Соединитель PowerShell позволяет интегрировать службу синхронизации с внешними системами, которые предоставляют API-интерфейсы на основе Windows PowerShell. Соединитель обеспечивает связь между возможностями платформы расширяемого агента управления подключением 2 (ECMA2) на основе вызова и Windows PowerShell. Дополнительные сведения о платформе ECMA см. в разделе Справочник по расширяемому агенту управления подключением 2.2.
Предварительные требования
Прежде чем использовать соединитель, установите на сервере синхронизации такие компоненты:
- Microsoft .NET 4.6.2 Framework или более поздней версии
- Windows PowerShell 2.0, 3.0 или 4.0.
Политику выполнения на сервере службы синхронизации необходимо настроить для выполнения сценариев Windows PowerShell. Если скрипты, выполняющиеся соединителем, не снабжены цифровой подписью, настройте политику выполнения с помощью следующей команды:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned
Для развертывания этого соединителя потребуется один или несколько сценариев PowerShell. Некоторые продукты Майкрософт могут предоставлять скрипты для использования с этим соединителем, и заявление о поддержке для этих скриптов будет предоставлено этим продуктом. Если вы разрабатываете собственные скрипты для использования с этим соединителем, для разработки и обслуживания этих скриптов вам потребуется знание API агента управления расширяемыми подключениями . Если вы выполняете интеграцию со сторонними системами, используя собственные скрипты в рабочей среде, мы рекомендуем обращаться к стороннему поставщику или партнеру по развертыванию, чтобы получить помощь, рекомендации и поддержку по этой интеграции.
Создание нового соединителя
Чтобы создать в службе синхронизации соединитель Windows PowerShell, необходимо задать ряд сценариев Windows PowerShell, выполняющих шаги по запросу службы синхронизации. Выбор скриптов для реализации зависит от источника данных, к которому будет подключаться система, и требуемых функций. В этом разделе описаны все скрипты, которые могут быть реализованы по мере необходимости.
Соединитель Windows PowerShell предназначен для хранения всех скриптов в базе данных службы синхронизации. Хотя можно выполнять скрипты, которые хранятся в файловой системе, гораздо проще вставить текст каждого скрипта непосредственно в конфигурацию соединителя.
Чтобы создать соединитель PowerShell, в Synchronization Service (Служба синхронизации) последовательно выберите элементы Management Agent (Агент управления)и Create (Создать). Выберите соединитель PowerShell (Microsoft) .
Соединение
Задайте параметры конфигурации для подключения к удаленной системе. Эти значения будут безопасно храниться в службе синхронизации и станут доступны для скриптов Windows PowerShell при запуске соединителя.
Можно настроить указанные ниже параметры подключения.
Соединение
| Параметр | Значение по умолчанию | Назначение |
|---|---|---|
| Сервер | <Пустой> | Имя сервера, к которому будет подключен соединитель. |
| Домен | <Пустой> | Домен учетных данных, который будет сохранен для использования при запуске соединителя. |
| Пользователь | <Пустой> | Имя пользователя учетных данных, которое будет сохранено для использования при запуске соединителя. |
| Пароль | <Пустой> | Пароль учетных данных, который будет сохранен для использования при запуске соединителя. |
| Выполнять олицетворение учетной записи соединителя | Неверно | Если задано значение true, служба синхронизации выполняет скрипты Windows PowerShell в контексте указанных учетных данных. По возможности вместо олицетворения рекомендуется использовать параметр $Credentials, передаваемый в каждый сценарий. Подробные сведения о дополнительных разрешениях для использования этого параметра см. в разделе Дополнительные настройки для олицетворения. |
| Загрузить профиль пользователя при олицетворении | Неверно | Указывает Windows загрузить профиль пользователя учетных данных для соединителя при олицетворении пользователя. Если олицетворяемый пользователь использует перемещаемый профиль, соединитель не загрузит этот профиль. Подробные сведения о дополнительных разрешениях для использования этого параметра см. в разделе Дополнительные настройки для олицетворения. |
| Тип входа при олицетворении | None | Тип входа при олицетворении. Дополнительные сведения см. в документации по dwLogonType. |
| Только для подписанных сценариев | Неверно | Если установлено значение «истина», соединитель Windows PowerShell проверяет, содержит ли каждый сценарий действительную цифровую подпись. Если установлено значение «ложь», убедитесь, что для политики выполнения Windows PowerShell на сервере службы синхронизации установлено значение RemoteSigned или Unrestricted. |
Общий модуль
Соединитель позволяет хранить в конфигурации общий модуль Windows PowerShell. При выполнении соединителем скрипта модуль Windows PowerShell извлекается в файловую систему, чтобы он мог импортироваться каждым скриптом.
Для сценариев импорта, экспорта и синхронизации паролей общий модуль извлекается в папку соединителя MAData. Для сценариев обнаружения схемы, проверки, иерархии и секций общий модуль извлекается в папку %TEMP%. В обоих случаях извлеченный сценарий общего модуля именуется в соответствии с настройкой имени общего модуля сценария.
Чтобы загрузить модуль с именем FIMPowerShellConnectorModule.psm1 из папки MAData, воспользуйтесь следующим оператором: Import-Module (Join-Path -Path [Microsoft.MetadirectoryServices.MAUtils]::MAFolder -ChildPath "FIMPowerShellConnectorModule.psm1")
Чтобы загрузить модуль с именем FIMPowerShellConnectorModule.psm1 из папки %TEMP%, воспользуйтесь следующим оператором: Import-Module (Join-Path -Path $env:TEMP -ChildPath "FIMPowerShellConnectorModule.psm1")
Проверка параметров
Сценарий проверки является необязательным сценарием Windows PowerShell, который может использоваться для проверки допустимости параметров конфигурации соединителя, установленных администратором. Как правило, этот скрипт используется для проверки сервера и учетных данных, а также параметров подключения. Сценарий проверки вызывается после изменения указанных ниже вкладок и диалоговых окон.
- Соединение
- Глобальные параметры
- Конфигурация секции
Сценарий проверки принимает от соединителя указанные ниже параметры.
| Имя | Тип данных | Описание |
|---|---|---|
| ConfigParameterPage | ConfigParameterPage | Вкладка или диалоговое окно «Конфигурация», где был активирован запрос на проверку. |
| ConfigParameters | KeyedCollection [строка, ConfigParameter] | Таблица параметров конфигурации для соединителя. |
| Подтверждение компетенции | PSCredential | Содержит все учетные данные, введенные администратором на вкладке «Подключение». |
Сценарий проверки должен вернуть в конвейер один объект ParameterValidationResult.
Обнаружение схем
Сценарий обнаружения схемы является обязательным для использования. Этот скрипт возвращает типы и атрибуты объектов, а также ограничения атрибутов, которые служба синхронизации использует при настройке правил потока атрибутов. Скрипт обнаружения схемы выполняется во время создания соединителя и заполняет схему соединителя. Он также используется действием "Обновление схемы" в Synchronization Service Manager.
Сценарий обнаружения схемы принимает от соединителя указанные ниже параметры.
| Имя | Тип данных | Описание |
|---|---|---|
| ConfigParameters | KeyedCollection [строка, ConfigParameter] | Таблица параметров конфигурации для соединителя. |
| Подтверждение компетенции | PSCredential | Содержит все учетные данные, введенные администратором на вкладке «Подключение». |
Сценарий должен возвращать в конвейер один объект Schema. Объект Schema состоит из объектов SchemaType, представляющих типы объектов (например, пользователи и группы). Объект SchemaType содержит коллекцию объектов SchemaAttribute, представляющих атрибуты типа (например, имя, фамилия и почтовый адрес).
Дополнительные параметры
Помимо стандартных настроек конфигурации, можно определить дополнительные настраиваемые параметры конфигурации, относящиеся к конкретному экземпляру соединителя. Эти параметры могут быть заданы на уровнях соединителя, секции или этапа выполнения. Доступ к ним можно получить из соответствующего сценария Windows PowerShell. Настраиваемые параметры конфигурации могут храниться в базе данных службы синхронизации в формате обычного текста или в зашифрованном виде. Служба синхронизации при необходимости автоматически шифрует и расшифровывает защищенные параметры конфигурации.
При установке настраиваемых параметров конфигурации их имена разделяются запятыми (,).
Чтобы получить доступ к пользовательским параметрам конфигурации из скрипта, необходимо суффикс имени с символом подчеркивания ( _ ) и область параметра (Global, Partition или RunStep). Например, чтобы получить доступ к параметру Global FileName, используйте следующий фрагмент кода: $ConfigurationParameters["FileName_Global"].Value
Возможности
На вкладке возможностей конструктора агента управления определяются поведение и функции соединителя. Выбранные на этой вкладке параметры после создания соединителя изменить нельзя. В таблице ниже перечислены параметры функций.
| Функция | Описание |
|---|---|
| Стиль различающегося имени | Указывает, поддерживает ли соединитель различающиеся имена, и, если это так, определяет их стили. |
| Тип экспорта | Определяет тип объектов, которые представлены в сценарии экспорта. |
| Нормализация данных | Указывает службе синхронизации нормализовать привязки атрибутов, перед тем как они будут заданы в сценариях. |
| Подтверждение объекта | Настраивает поведение при ожидании импорта в службу синхронизации. |
| Использование DN как привязки | Если для стиля различающегося имени установлено значение LDAP, атрибут привязки для пространства соединителя также является различающимся именем. |
| Параллельная работа нескольких соединителей | Если этот флажок установлен, можно одновременно запустить несколько соединителей Windows PowerShell. |
| Секции | Если этот флажок установлен, соединитель будет поддерживать несколько секций и функцию их обнаружения. |
| Иерархия | Если этот флажок установлен, соединитель будет поддерживать иерархическую структуру стиля LDAP. |
| Включить импорт | Если этот флажок установлен, соединитель импортирует данные с помощью скриптов импорта. |
| Включить импорт изменений | Если этот флажок установлен, соединитель может подавать в сценарии импорта запросы на изменения. |
| Включить экспорт | Если этот флажок установлен, соединитель экспортирует данные с помощью скриптов экспорта. |
| Включить полный экспорт | Если этот флажок установлен, сценарии экспорта будут поддерживать экспорт всего пространства соединителя. Для использования этого параметра должен быть установлен флажок «Включить экспорт». |
| Без ссылочных значений на первом этапе экспорта | Если этот флажок установлен, ссылочные атрибуты экспортируются на втором этапе экспорта. |
| Включить переименование объекта | Если этот флажок установлен, различающиеся имена можно изменить. |
| Удаление и добавление как замена | Если этот флажок установлен, операции удаления и добавления экспортируются как одна операция замены. |
| Включить операции паролей | Если этот флажок установлен, поддерживаются сценарии синхронизации паролей. |
| Включить пароль для экспорта на первом этапе | Если этот флажок установлен, пароли, заданные во время подготовки, экспортируются при создании объекта. |
Глобальные параметры
Скрипты Windows PowerShell, которые запускаются с помощью соединителя, можно настроить на вкладке "Глобальные параметры" в конструкторе агента управления. Можно также настроить глобальные значения настраиваемых параметров конфигурации на вкладке "Подключение".
Обнаружение секции
Секция — отдельное пространство имен в пределах одной общей схемы. Например, в Active Directory каждый домен представляет собой секцию в пределах одного леса. Секция является логической группой для операций импорта и экспорта. Импорт и экспорт разбиваются на секции по контексту, и все операции выполняются в этом контексте. Секции должны представлять иерархию в LDAP. Различающееся имя секции используется при импорте. Оно позволяет проверить, находятся ли все возвращаемые объекты в пределах секции. Различающееся имя секции также используется при подготовке передачи из метавселенной в пространство соединителя, чтобы определить, с какой секцией должен быть связан объект во время экспорта.
Сценарий обнаружения секции принимает от соединителя указанные ниже параметры.
| Имя | Тип данных | Описание |
|---|---|---|
| ConfigParameters | KeyedCollection [строка, ConfigParameter] | Таблица параметров конфигурации для соединителя. |
| Подтверждение компетенции | PSCredential | Содержит все учетные данные, введенные администратором на вкладке «Подключение». |
Сценарий должен возвращать в конвейер отдельный объект Partition или объект List[T] с объектами Partition.
Обнаружение иерархии
Сценарий обнаружения иерархии используется только в том случае, когда различающееся имя стиля возможностей является LDAP. Скрипт позволяет просматривать и выбирать контейнеры, которые будут учитываться в области операций импорта и экспорта или вне ее. Сценарий должен указывать только список узлов, которые являются непосредственными дочерними элементами корневого узла, заданного для сценария.
Сценарий обнаружения иерархии принимает от соединителя указанные ниже параметры.
| Имя | Тип данных | Описание |
|---|---|---|
| ConfigParameters | KeyedCollection [строка, ConfigParameter] | Таблица параметров конфигурации для соединителя. |
| Подтверждение компетенции | PSCredential | Содержит все учетные данные, введенные администратором на вкладке «Подключение». |
| ParentNode | HierarchyNode | Корневой узел иерархии, в которой сценарий должен возвращать непосредственные дочерние элементы. |
Сценарий должен возвращать в конвейер один дочерний объект HierarchyNode или список дочерних объектов HierarchyNode.
Импорт
Соединители, которые поддерживают операции импорта, должны реализовать три сценария.
Начало импорта
Сценарий начала импорта реализуется в начале этапа выполнения импорта. На этом этапе можно установить подключение к исходной системе и выполнить все необходимые подготовительные действия перед импортом данных из подключенной системы.
Сценарий начала импорта принимает от соединителя указанные ниже параметры.
| Имя | Тип данных | Описание |
|---|---|---|
| ConfigParameters | KeyedCollection [строка, ConfigParameter] | Таблица параметров конфигурации для соединителя. |
| Подтверждение компетенции | PSCredential | Содержит все учетные данные, введенные администратором на вкладке «Подключение». |
| OpenImportConnectionRunStep | OpenImportConnectionRunStep | Информирует сценарий о типе запуска импорта (измененный или полный), секции, иерархии, водяном знаке и ожидаемом размере страницы. |
| Типы | Схема | Схема для импортируемого пространства соединителя. |
Сценарий должен возвращать в конвейер один объект OpenImportConnectionResults, например: Write-Output (New-Object Microsoft.MetadirectoryServices.OpenImportConnectionResults).
Импорт данных
Соединитель вызывает сценарий импорта данных, пока сценарий не укажет, что данных для импорта больше нет. Размер страницы соединителя Windows PowerShell составляет 9999 объектов. Если скрипт возвращает более 9999 объектов для импорта, должна поддерживаться разбивка на страницы. Соединитель представляет свойство настраиваемых данных, которое можно использовать для хранения водяного знака, чтобы при каждом вызове сценарий импорта данных возобновлял импорт объектов с того момента, на котором он был остановлен.
Сценарий импорта данных принимает от соединителя указанные ниже параметры.
| Имя | Тип данных | Описание |
|---|---|---|
| ConfigParameters | KeyedCollection [строка, ConfigParameter] | Таблица параметров конфигурации для соединителя. |
| Подтверждение компетенции | PSCredential | Содержит все учетные данные, введенные администратором на вкладке «Подключение». |
| GetImportEntriesRunStep | ImportRunStep | Содержит водяной знак (CustomData), который можно использовать во время постраничного импорта и импорта изменений. |
| OpenImportConnectionRunStep | OpenImportConnectionRunStep | Информирует сценарий о типе запуска импорта (измененный или полный), секции, иерархии, водяном знаке и ожидаемом размере страницы. |
| Типы | Схема | Схема для импортируемого пространства соединителя. |
Сценарий импорта данных должен записать в конвейер объект List[CSEntryChange]. Эта коллекция состоит из атрибутов CSEntryChange, представляющих каждый импортируемый объект. При выполнении полного импорта эта коллекция должна содержать полный набор объектов CSEntryChange со всеми атрибутами для каждого объекта. При импорте изменений объект CSEntryChange должен содержать изменения уровня атрибутов для каждого импортируемого объекта или полное представление измененных объектов (режим замены).
Окончание импорта
По завершении импорта выполняется сценарий окончания импорта. Этот скрипт должен выполнять все необходимые задачи очистки (например, закрытие подключений к системам и реагирование на сбои).
Сценарий окончания импорта принимает от соединителя указанные ниже параметры.
| Имя | Тип данных | Описание |
|---|---|---|
| ConfigParameters | KeyedCollection [строка, ConfigParameter] | Таблица параметров конфигурации для соединителя. |
| Подтверждение компетенции | PSCredential | Содержит все учетные данные, введенные администратором на вкладке «Подключение». |
| OpenImportConnectionRunStep | OpenImportConnectionRunStep | Информирует сценарий о типе запуска импорта (измененный или полный), секции, иерархии, водяном знаке и ожидаемом размере страницы. |
| CloseImportConnectionRunStep | CloseImportConnectionRunStep | Информирует сценарий о причине завершения импорта. |
Сценарий должен возвращать в конвейер отдельный объект CloseImportConnectionResults, например: Write-Output (New-Object Microsoft.MetadirectoryServices.CloseImportConnectionResults).
Экспорт
Идентичен архитектуре импорта соединителя. Соединители, поддерживающие экспорт, должны реализовать три сценария.
Начало экспорта
Сценарий «Начало экспорта» реализуется в начале этапа выполнения экспорта. На этом этапе можно установить подключение к исходной системе и выполнить все необходимые подготовительные действия перед экспортом данных в подключенную систему.
Сценарий начала экспорта принимает от соединителя указанные ниже параметры.
| Имя | Тип данных | Описание |
|---|---|---|
| ConfigParameters | KeyedCollection [строка, ConfigParameter] | Таблица параметров конфигурации для соединителя. |
| Подтверждение компетенции | PSCredential | Содержит все учетные данные, введенные администратором на вкладке «Подключение». |
| OpenExportConnectionRunStep | OpenExportConnectionRunStep | Информирует сценарий о типе запуска экспорта (измененный или полный), секции, иерархии и ожидаемом размере страницы. |
| Типы | Схема | Схема для экспортируемого пространства соединителя. |
Сценарий не должен возвращать выходные данные в конвейер.
Экспорт данных
Служба синхронизации вызывает сценарий экспорта данных столько раз, сколько это необходимо для обработки всех операций экспорта в ожидании. Если количество операций экспорта в ожидании превышает размер страницы соединителя, скрипт экспорта данных может вызываться несколько раз (возможно, несколько раз для одного и того же объекта).
Сценарий экспорта данных принимает от соединителя указанные ниже параметры.
| Имя | Тип данных | Описание |
|---|---|---|
| ConfigParameters | KeyedCollection [строка, ConfigParameter] | Таблица параметров конфигурации для соединителя. |
| Подтверждение компетенции | PSCredential | Содержит все учетные данные, введенные администратором на вкладке «Подключение». |
| CSEntries | IListCSEntryChange | Список всех объектов пространства соединителя с операциями экспорта в ожидании для обработки на этом этапе. |
| OpenExportConnectionRunStep | OpenExportConnectionRunStep | Информирует сценарий о типе запуска экспорта (измененный или полный), секции, иерархии и ожидаемом размере страницы. |
| Типы | Схема | Схема для экспортируемого пространства соединителя. |
Сценарий экспорта данных должен возвращать в конвейер объект PutExportEntriesResults. Этот объект не должен включать данные результатов для каждого экспортируемого соединителя, если не произойдет ошибка или изменение атрибута привязки. Например, чтобы вернуть в конвейер объект PutExportEntriesResults: Write-Output (New-Object Microsoft.MetadirectoryServices.PutExportEntriesResults)
Окончание экспорта
По завершении экспорта выполняется сценарий окончания экспорта. Этот скрипт должен выполнять все необходимые задачи очистки (например, закрытие подключений к системам и реагирование на сбои).
Сценарий окончания экспорта принимает от соединителя указанные ниже параметры.
| Имя | Тип данных | Описание |
|---|---|---|
| ConfigParameters | KeyedCollection [строка, ConfigParameter] | Таблица параметров конфигурации для соединителя. |
| Подтверждение компетенции | PSCredential | Содержит все учетные данные, введенные администратором на вкладке «Подключение». |
| OpenExportConnectionRunStep | OpenExportConnectionRunStep | Информирует сценарий о типе запуска экспорта (измененный или полный), секции, иерархии и ожидаемом размере страницы. |
| CloseExportConnectionRunStep | CloseExportConnectionRunStep | Информирует сценарий о причине завершения экспорта. |
Сценарий не должен возвращать выходные данные в конвейер.
Синхронизация паролей
Соединители Windows PowerShell могут использоваться в качестве целевого объекта для изменения или сброса пароля.
Сценарий пароля принимает от соединителя указанные ниже параметры.
| Имя | Тип данных | Описание |
|---|---|---|
| ConfigParameters | KeyedCollection [строка, ConfigParameter] | Таблица параметров конфигурации для соединителя. |
| Подтверждение компетенции | PSCredential | Содержит все учетные данные, введенные администратором на вкладке «Подключение». |
| Секция | Секция | Секция каталога, содержащая CSEntry. |
| CSEntry | CSEntry | Запись пространства соединителя для объекта, который получил данные о смене или сбросе пароля. |
| OperationType | Строка | Указывает тип операции: сброс (SetPassword) или изменение (ChangePassword). |
| PasswordOptions | PasswordOptions | Флаги, определяющие предполагаемое поведение при сбросе пароля. Этот параметр доступен, только если для OperationType установлено значение SetPassword. |
| OldPassword | Строка | Содержит старый пароль объекта, необходимый для изменения пароля. Этот параметр доступен, только если для OperationType установлено значение ChangePassword. |
| NewPassword | Строка | Содержит новый пароль, который должен быть установлен сценарием. |
Сценарий пароля не должен возвращать результаты в конвейер Windows PowerShell. В случае ошибки в сценарии пароля сценарий должен вызывать одно из указанных ниже исключений, чтобы отправить сведения о проблеме в службу синхронизации.
- PasswordPolicyViolationException порождается, если пароль не соответствует политике паролей в подключенной системе.
- PasswordIllFormedException порождается, если пароль неприемлем для подключенной системы.
- PasswordExtension порождается при возникновении любых других ошибок в сценарии пароля.
Образцы соединителей
Полный обзор доступных примеров соединителей представлен в статье Windows PowerShell Connector for FIM 2010 R2 Sample Connector Collection (Коллекция примеров соединителей Windows PowerShell для FIM 2010 R2).
Другие примечания
Дополнительные настройки для олицетворения
Предоставляются олицетворяемому пользователю с указанными ниже разрешениями на сервере службы синхронизации.
Доступ для чтения к следующим разделам реестра:
- HKEY_USERS\[SynchronizationServiceServiceAccountSID]\Software\Microsoft\PowerShell
- HKEY_USERS\[SynchronizationServiceServiceAccountSID]\Среда
Чтобы определить идентификатор безопасности (SID) учетной записи службы синхронизации, необходимо выполнить указанные ниже команды PowerShell.
$account = New-Object System.Security.Principal.NTAccount "<domain>\<username>"
$account.Translate([System.Security.Principal.SecurityIdentifier]).Value
Доступ для чтения к следующим папкам файловой системы:
- %ProgramFiles%\Microsoft Forefront Identity Manager\2010\Synchronization Service\Extensions;
- %ProgramFiles%\Microsoft Forefront Identity Manager\2010\Synchronization Service\ExtensionsCache;
- %ProgramFiles%\Microsoft Forefront Identity Manager\2010\Synchronization Service\MaData\{ConnectorName}
Подставьте имя соединителя Windows PowerShell вместо заполнителя {ConnectorName}.
Устранение неполадок
- Сведения о том, как включить ведение журнала для устранения неполадок соединителя, см. в статье How to Enable ETW Tracing for Connectors (Включение трассировки событий Windows для соединителей).