Технический справочник по соединителю Windows PowerShell
В этой статье описывается соединитель Windows PowerShell. Статья относится к следующим продуктам:
- Microsoft Identity Manager 2016 (MIM2016)
Для MIM2016 коннектор доступен для скачивания из Центра загрузки Microsoft.
Общие сведения о соединителе PowerShell
Соединитель PowerShell позволяет интегрировать службу синхронизации с внешними системами, предлагающими API на основе Windows PowerShell. Соединитель предоставляет мост между возможностями основанной на вызовах расширяемой платформы управления подключениями 2 (ECMA2) и Windows PowerShell. Дополнительные сведения о платформе ECMA см. в справочнике по агенту управления Extensible Connectivity 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, в службе синхронизации выберите агент управления и создайте его. Выберите соединитель PowerShell (Майкрософт).
Связь
Укажите параметры конфигурации для подключения к удаленной системе. Эти значения безопасно хранятся службой синхронизации и предоставляются скриптам Windows PowerShell при запуске соединителя.
Можно настроить следующие параметры подключения:
Подключение
| Параметр | Значение по умолчанию | Цель |
|---|---|---|
| Сервер | <Пусто> | Имя сервера, к которому будет подключен соединитель. |
| Домен | <Пусто> | Домен учетных данных для хранения и использования при запуске соединителя. |
| Пользователь | <Пусто> | Имя пользователя учетных данных, которое будет сохранено для использования при запуске соединителя. |
| Пароль | <Пусто> | Пароль учетных данных, который будет сохранен для использования при запуске соединителя. |
| Имитация учетной записи коннектора | Неправда | Если задано значение true, служба синхронизации выполняет скрипты Windows PowerShell в контексте указанных учетных данных. По возможности рекомендуется передать параметр $Credentials каждому скрипту вместо олицетворения. Дополнительные сведения о дополнительных разрешениях, необходимых для использования этого параметра, см. в разделе "Дополнительная конфигурация для олицетворения". |
| Загрузить профиль пользователя при олицетворении | Неправда | Указывает Windows загрузить профиль пользователя из учетных данных соединителя при выполнении действий от имени пользователя. Если у имитируемого пользователя есть перемещаемый профиль, соединитель не загружает профиль перемещаемого пользователя. Дополнительные сведения о дополнительных разрешениях, необходимых для использования этого параметра, см. в разделе "Дополнительная конфигурация для олицетворения". |
| Тип входа при олицетворении | Отсутствует | Тип входа при олицетворении. Дополнительные сведения см. в документации по 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 | Вкладка конфигурации или диалоговое окно, активировающее запрос проверки. |
| Параметры настройки | KeyedCollection [string, ConfigParameter] | Таблица параметров конфигурации для соединителя. |
| Подтверждение компетенции | PSCredential | Содержит все учетные данные, введенные администратором на вкладке "Подключение". |
Скрипт проверки должен возвращать в конвейер один объект ParameterValidationResult.
Обнаружение схем
Скрипт обнаружения схем является обязательным. Этот скрипт возвращает типы объектов, атрибуты и ограничения атрибутов, которые служба Синхронизации использует при настройке правил потока атрибутов. Скрипт обнаружения схем выполняется во время создания соединителя и заполняет схему соединителя. Он также используется действием "Обновить схему" в диспетчере службы синхронизации.
Скрипт обнаружения схем получает следующие параметры из соединителя:
| Имя | Тип данных | Описание |
|---|---|---|
| Параметры конфигурации | KeyedCollection [string, 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. Различающееся имя секции используется для импорта, чтобы убедиться, что все возвращаемые объекты находятся в пределах области секции. Отличительное имя раздела также используется при обеспечении данных из метавселенной в пространство соединителя для определения раздела, с которым должен быть ассоциирован объект во время экспорта.
Скрипт обнаружения секций получает следующие параметры из соединителя:
| Имя | Тип данных | Описание |
|---|---|---|
| Параметры конфигурации | KeyedCollection[string, ConfigParameter] | Таблица параметров конфигурации для соединителя. |
| Подтверждение компетенции | PSCredential | Содержит все учетные данные, введенные администратором на вкладке "Подключение". |
Скрипт должен возвращать один объект Partition или список[T] объектов Partition в поток.
Обнаружение иерархий
Скрипт обнаружения иерархии используется только в том случае, если функция "Различающееся имя" — LDAP. Скрипт используется для просмотра и выбора набора контейнеров, которые считаются входящими или не входящими в область импорта и экспорта. Скрипт должен предоставлять только список узлов, которые являются прямыми дочерними элементами корневого узла, предоставленного скрипту.
Скрипт обнаружения иерархии получает следующие параметры из соединителя:
| Имя | Тип данных | Описание |
|---|---|---|
| ПараметрыКонфигурации | KeyedCollection[string, ConfigParameter] | Таблица параметров конфигурации для соединителя. |
| Подтверждение компетенции | PSCredential | Содержит все учетные данные, введенные администратором на вкладке "Подключение". |
| ParentNode | HierarchyNode | Корневой узел иерархии, в которой скрипт должен возвращать прямые дочерние элементы. |
Скрипт должен возвращать либо один дочерний объект HierarchyNode, либо список[T] дочерних объектов HierarchyNode для конвейера.
Импорт
Соединители, поддерживающие операции импорта, должны реализовать три скрипта.
Начало импорта
Скрипт начального импорта выполняется в начале шага выполнения импорта. На этом этапе можно установить подключение к исходной системе и выполнить предварительные действия перед импортом данных из подключенной системы.
Скрипт начала импорта получает следующие параметры из коннектора:
| Имя | Тип данных | Описание |
|---|---|---|
| Параметры конфигурации | KeyedCollection[string, ConfigParameter] | Таблица параметров конфигурации для соединителя. |
| Подтверждение компетенции | PSCredential | Содержит все учетные данные, введенные администратором на вкладке "Подключение". |
| OpenImportConnectionRunStep | OpenImportConnectionRunStep | Сообщает скрипту о типе импорта (разностного или полного), разделе, иерархии, водяном знаке и ожидаемом размере страницы. |
| Типы | Схема | Схема для пространства подключения, которое импортируется. |
Скрипт должен возвращать в конвейер один объект OpenImportConnectionResults , например: Write-Output (New-Object Microsoft.MetadirectoryServices.OpenImportConnectionResults)
Импорт данных
Скрипт импорта данных вызывается соединителем до тех пор, пока скрипт не указывает, что импортируемых данных больше нет. Соединитель Windows PowerShell имеет предельный размер страницы 9 999 объектов. Если скрипт возвращает более 999 объектов для импорта, необходимо поддерживать разбиение по страницам. Соединитель предоставляет пользовательское свойство данных, которое можно использовать для хранения водяного знака, чтобы каждый раз при выполнении команды импорта данных ваш скрипт возобновлял импорт объектов с того места, где она остановилась в прошлый раз.
Скрипт импорта данных получает следующие параметры из соединителя:
| Имя | Тип данных | Описание |
|---|---|---|
| Параметры конфигурации | KeyedCollection[string, ConfigParameter] | Таблица параметров конфигурации для соединителя. |
| Подтверждение компетенции | PSCredential | Содержит все учетные данные, введенные администратором на вкладке "Подключение". |
| GetImportEntriesRunStep | ImportRunStep | Содержит подложку (CustomData), которую можно использовать во время страничных импортов и разностных импортов. |
| OpenImportConnectionRunStep | OpenImportConnectionRunStep | Сообщает скрипту о типе выполнения импорта (разностного или полного), секции, иерархии, водяного знака и ожидаемого размера страницы. |
| Типы | Схема | Схема для импортированного коннекторного пространства. |
Скрипт импорта данных должен записать объект List[CSEntryChange] в конвейер. Эта коллекция состоит из атрибутов CSEntryChange, представляющих импортируемый объект. Во время полного выполнения импорта эта коллекция должна иметь полный набор объектов CSEntryChange, имеющих все атрибуты для каждого объекта. Во время разностного импорта объект CSEntryChange должен содержать разностные значения уровня атрибута для каждого объекта для импорта, или полное представление измененных объектов (режим замены).
Завершение импорта
После завершения выполнения импорта выполняется скрипт завершения импорта. Этот скрипт должен выполнять все необходимые задачи очистки (например, закрывать подключения к системам и реагировать на сбои).
Скрипт конечного импорта получает следующие параметры из соединителя:
| Имя | Тип данных | Описание |
|---|---|---|
| ПараметрыКонфигурации | KeyedCollection[string, ConfigParameter] | Таблица параметров конфигурации для соединителя. |
| Подтверждение компетенции | PSCredential | Содержит все учетные данные, введенные администратором на вкладке "Подключение". |
| ОткрытьШагЗапускаИмпортногоПодключения | OpenImportConnectionRunStep | Сообщает скрипту о типе импорта (разностного или полного), секции, иерархии, отметке и ожидаемом размере страницы. |
| ЗакрытьИмпортСоединенияШагВыполнения | ЗакрытьШагЗапускаСоединенияИмпорта | Сообщает скрипту о причине завершения импорта. |
Скрипт должен возвращать в конвейер один объект CloseImportConnectionResults , например: Write-Output (New-Object Microsoft.MetadirectoryServices.CloseImportConnectionResults)
Экспорт
Соединители, поддерживающие экспорт, должны реализовывать три скрипта, аналогично архитектуре импорта соединителя.
Начало экспорта
Скрипт начала экспорта запускается в начале шага выполнения экспорта. На этом шаге можно установить подключение к исходной системе и выполнить все предварительные действия перед экспортом данных в подключенную систему.
Скрипт начала экспорта получает следующие параметры из соединителя:
| Имя | Тип данных | Описание |
|---|---|---|
| Параметры конфигурации | KeyedCollection[string, ConfigParameter] | Таблица параметров конфигурации для соединителя. |
| Подтверждение компетенции | PSCredential | Содержит все учетные данные, введенные администратором на вкладке "Подключение". |
| OpenExportConnectionRunStep | OpenExportConnectionRunStep | Сообщает скрипту о типе выполнения экспорта (разностного или полного), секционирования, иерархии и ожидаемого размера страницы. |
| Типы | Схема | Схема для экспортированного пространства соединителя. |
Скрипт не должен возвращать выходные данные в конвейер.
Экспорт данных
Служба синхронизации вызывает скрипт экспорта данных столько раз, сколько необходимо для обработки всех ожидающих экспорта данных. Если пространство соединителя имеет больше ожидающих экспорта, чем размер страницы соединителя, сценарий экспорта данных может вызываться несколько раз и, возможно, несколько раз для одного объекта.
Скрипт экспорта данных получает следующие параметры из соединителя:
| Имя | Тип данных | Описание |
|---|---|---|
| Параметры конфигурации | KeyedCollection[string, ConfigParameter] | Таблица параметров конфигурации для соединителя. |
| Подтверждение компетенции | PSCredential | Содержит все учетные данные, введенные администратором на вкладке "Подключение". |
| CSEntries | IListCSEntryChange | Список всех объектов пространства соединителя с ожидающими экспорт обработки, которые будут обрабатываться во время этого прохода. |
| ОткрытьЭкспортноеПодключениеВыполнитьШаг | OpenExportConnectionRunStep | Сообщает скрипту о типе выполнения экспорта (разностного или полного), секционирования, иерархии и ожидаемого размера страницы. |
| Типы | Схема | Схема для экспортированного пространства соединителя. |
Скрипт экспорта данных должен вернуть объект PutExportEntriesResults в конвейер. Этот объект не должен включать сведения о результатах для каждого экспортированного соединителя, если не возникает ошибка или изменение атрибута привязки. Например, чтобы вернуть объект PutExportEntriesResults в конвейер: Write-Output (New-Object Microsoft.MetadirectoryServices.PutExportEntriesResults)
Завершение экспорта
В конце выполнения экспорта должен быть запущен скрипт завершения экспорта. Этот скрипт должен выполнять все необходимые задачи очистки (например, закрывать подключения к системам и реагировать на сбои).
Скрипт конечного экспорта получает следующие параметры из соединителя:
| Имя | Тип данных | Описание |
|---|---|---|
| Параметры конфигурации | KeyedCollection[string, ConfigParameter] | Таблица параметров конфигурации для соединителя. |
| Подтверждение компетенции | PSCredential | Содержит все учетные данные, введенные администратором на вкладке "Подключение". |
| ОткрытьЭкспортноеПодключениеВыполнитьШаг | OpenExportConnectionRunStep | Сообщает скрипту о типе выполнения экспорта (разностного или полного), секционирования, иерархии и ожидаемого размера страницы. |
| ЗакрытьШагЗапускаЭкспортногоПодключения | CloseExportConnectionRunStep | Сообщает скрипту о причине завершения экспорта. |
Скрипт не должен возвращать выходные данные в конвейер.
Синхронизация паролей
Соединители Windows PowerShell можно использовать в качестве целевого объекта для изменения и сброса пароля.
Скрипт пароля получает следующие параметры из соединителя:
| Имя | Тип данных | Описание |
|---|---|---|
| Параметры настройки | KeyedCollection[string, ConfigParameter] | Таблица параметров конфигурации для соединителя. |
| Подтверждение компетенции | PSCredential | Содержит все учетные данные, введенные администратором на вкладке "Подключение". |
| Раздел | Раздел | Раздел каталога, в который входит CSEntry. |
| CSEntry | CSEntry | Запись пространства соединителя для объекта, для которого произошло изменение или сброс пароля. |
| Тип операции | Струна | Указывает, является ли операция установкой нового пароля (SetPassword) или изменением пароля (ChangePassword). |
| Параметры пароля | PasswordOptions | Флаги, указывающие предполагаемое поведение сброса пароля. Этот параметр доступен только в том случае, если Параметр OperationType имеет значение SetPassword. |
| Старый пароль | Струна | Заполнен старым паролем объекта для изменения пароля. Этот параметр доступен только в том случае, если OperationType — ChangePassword. |
| NewPassword | Струна | Заполняется новым паролем объекта, который должен быть задан скриптом. |
Скрипт пароля не должен возвращать результаты конвейеру Windows PowerShell. Если в скрипте пароля возникает ошибка, сценарий должен вызвать одно из следующих исключений, чтобы сообщить службе синхронизации о проблеме:
- PasswordPolicyViolationException — создается, если пароль не соответствует политике паролей в подключенной системе.
- PasswordIllFormedException — создается, если пароль не допускается для подключенной системы.
- PasswordExtension — вызывается для всех других ошибок в скрипте паролей.
Примеры соединителей
Полный обзор доступных примеров соединителей см. в коллекции примеров соединителей Windows PowerShell.
Другие примечания
Дополнительная конфигурация для олицетворения
Предоставьте пользователю олицетворенные следующие разрешения на сервере службы синхронизации:
Доступ на чтение к следующим разделам реестра:
- HKEY_USERS\[SynchronizationServiceServiceAccountSID]\Software\Microsoft\PowerShell
- HKEY_USERS\[SynchronizationServiceServiceAccountSID]\Environment
Чтобы определить идентификатор безопасности учетной записи службы синхронизации, выполните следующие команды 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}.
Устранение неполадок
- Сведения о том, как включить логирование для устранения неполадок соединителя, см. в разделе Включение трассировки ETW для соединителей.