Technické informace o konektoru prostředí Windows PowerShell
Tento článek popisuje konektor Windows PowerShell. Článek se vztahuje na následující produkty:
- Microsoft Identity Manager 2016 (MIM2016)
Pro MIM2016 je konektor k dispozici ke stažení z webu Microsoft Download Center.
Přehled konektoru PowerShellu
Konektor Prostředí PowerShell umožňuje integrovat synchronizační službu s externími systémy, které nabízejí rozhraní API založená na Windows PowerShell. Konektor poskytuje most mezi možnostmi architektury ECMA2 (Extensib Connectivity Management Agent 2) na základě volání a Windows PowerShell. Další informace o architektuře ECMA najdete v tématu Extensible Connectivity 2.2 Management Agent Reference.
Požadavky
Před použitím konektoru se ujistěte, že na synchronizačním serveru máte následující:
- Microsoft .NET 4.6.2 Framework nebo novější
- Windows PowerShell 2.0, 3.0 nebo 4.0
Zásady spouštění na serveru synchronizační služby musí být nakonfigurované tak, aby konektor mohl spouštět Windows PowerShell skripty. Pokud skripty, které konektor spouští, nejsou digitálně podepsané, nakonfigurujte zásady spouštění spuštění spuštěním tohoto příkazu:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned
Nasazení tohoto konektoru bude vyžadovat jeden nebo více skriptů PowerShellu. Některé produkty Microsoftu můžou poskytovat skripty pro použití s tímto konektorem a prohlášení o podpoře těchto skriptů by tento produkt poskytl. Pokud vyvíjíte vlastní skripty pro použití s tímto konektorem, budete muset znát rozhraní API agenta pro správu připojení, abyste mohli tyto skripty vyvíjet a udržovat. Pokud integrujete se systémy třetích stran pomocí vlastních skriptů v produkčním prostředí, doporučujeme vám požádat o pomoc, pokyny a podporu pro tuto integraci s dodavatelem třetí strany nebo partnerem pro nasazení.
Vytvoření nového konektoru
Pokud chcete vytvořit konektor Windows PowerShell v synchronizační službě, musíte zadat řadu Windows PowerShell skriptů, které spouštějí kroky požadované synchronizační službou. V závislosti na zdroji dat, ke kterému se připojujete, a požadovaných funkcích se skripty, které musíte implementovat, liší. Tato část popisuje jednotlivé skripty, které je možné implementovat a kdy jsou potřeba.
Konektor Windows PowerShell je navržený tak, aby ukládaly všechny skripty v databázi synchronizační služby. I když je možné spouštět skripty, které jsou uložené v systému souborů, je jednodušší vložit text každého skriptu přímo do konfigurace konektoru.
Pokud chcete vytvořit konektor PowerShellu, v části Synchronizační služba vyberte Agent pro správu a vytvořit. Vyberte konektor PowerShellu (Microsoft).
Připojení
Zadejte parametry konfigurace pro připojení ke vzdálenému systému. Tyto hodnoty jsou bezpečně uloženy synchronizační službou a zpřístupněny skriptům Windows PowerShell při spuštění konektoru.
Můžete nakonfigurovat následující parametry připojení:
Připojení
| Parametr | Výchozí hodnota | Účel |
|---|---|---|
| Server | <Prázdné> | Název serveru, ke kterému se má konektor připojit. |
| Doména | <Prázdné> | Doména přihlašovacích údajů, které se mají uložit pro použití při spuštění konektoru. |
| Uživatel | <Prázdné> | Uživatelské jméno přihlašovacích údajů, které se mají uložit pro použití při spuštění konektoru. |
| Heslo | <Prázdné> | Heslo přihlašovacích údajů, které se mají uložit pro použití při spuštění konektoru. |
| Zosobnit účet konektoru | Ne | Pokud je hodnota true, synchronizační služba spustí skripty Windows PowerShell v kontextu zadaných přihlašovacích údajů. Pokud je to možné, doporučujeme, aby se každému skriptu místo zosobnění předá parametr $Credentials . Další informace o dalších oprávněních potřebných k použití této možnosti najdete v tématu Další konfigurace pro zosobnění. |
| Načtení profilu uživatele při zosobnění | Ne | Dává systému Windows pokyn, aby během zosobnění načetl profil uživatele přihlašovacích údajů konektoru. Pokud má zosobněný uživatel cestovní profil, konektor ho nenačte. Další informace o dalších oprávněních potřebných k použití tohoto parametru najdete v tématu Další konfigurace pro zosobnění. |
| Typ přihlášení při zosobnění | Žádné | Typ přihlášení během zosobnění. Další informace najdete v dokumentaci dwLogonType . |
| Pouze podepsané skripty | Ne | Pokud je hodnota true, konektor Windows PowerShell ověří, že každý skript má platný digitální podpis. Pokud je false, ujistěte se, že zásady spouštění Windows PowerShell serveru synchronizační služby mají hodnotu RemoteSigned nebo Unrestricted. |
Společný modul
Konektor umožňuje uložit sdílený modul Windows PowerShell v konfiguraci. Když konektor spustí skript, modul Windows PowerShell se extrahuje do systému souborů, aby ho každý skript mohl importovat.
V případě skriptů importu, exportu a synchronizace hesel se společný modul extrahuje do složky MAData konektoru. Pro skripty zjišťování schématu, ověřování, hierarchie a oddílů se společný modul extrahuje do složky %TEMP%. V obou případech je extrahovaný skript Common Module pojmenovaný podle nastavení Název skriptu společného modulu.
Pokud chcete načíst modul s názvem FIMPowerShellConnectorModule.psm1 ze složky MAData, použijte následující příkaz: Import-Module (Join-Path -Path [Microsoft.MetadirectoryServices.MAUtils]::MAFolder -ChildPath "FIMPowerShellConnectorModule.psm1")
Pokud chcete načíst modul s názvem FIMPowerShellConnectorModule.psm1 ze složky %TEMP%, použijte následující příkaz: Import-Module (Join-Path -Path $env:TEMP -ChildPath "FIMPowerShellConnectorModule.psm1")
Ověření parametru
Ověřovací skript je volitelný Windows PowerShell skript, který se dá použít k zajištění platnosti parametrů konfigurace konektoru zadaných správcem. Ověření serveru, přihlašovacích údajů pro připojení a parametrů připojení jsou běžná použití ověřovacího skriptu. Ověřovací skript se volá po úpravě následujících karet a dialogových oken:
- Připojení
- Globální parametry
- Konfigurace oddílu
Ověřovací skript obdrží z konektoru následující parametry:
| Name | Typ dat | Popis |
|---|---|---|
| ConfigParameterPage | ConfigParameterPage | Karta konfigurace nebo dialogové okno, které aktivovaly žádost o ověření. |
| Parametry konfigurace | KeyedCollection [string, ConfigParameter] | Tabulka parametrů konfigurace konektoru |
| Reference | Přihlašovací údaje PS | Obsahuje všechny přihlašovací údaje zadané správcem na kartě Připojení. |
Ověřovací skript by měl do kanálu vrátit jeden objekt ParameterValidationResult.
Zjišťování schémat
Skript zjišťování schématu je povinný. Tento skript vrátí typy objektů, atributy a omezení atributů, které synchronizační služba používá při konfiguraci pravidel toku atributů. Skript zjišťování schématu se spouští během vytváření konektoru a naplní schéma konektoru. Používá se také akcí Aktualizovat schéma v Service Manager synchronizace.
Skript zjišťování schématu obdrží z konektoru následující parametry:
| Name | Typ dat | Popis |
|---|---|---|
| ConfigParameters | KeyedCollection [string, ConfigParameter] | Tabulka konfiguračních parametrů konektoru |
| Reference | PSCredential | Obsahuje všechny přihlašovací údaje zadané správcem na kartě Připojení. |
Skript musí do kanálu vrátit jeden objekt schématu . Objekt Schema se skládá z objektů SchemaType , které představují typy objektů (například uživatelé a skupiny). Objekt SchemaType obsahuje kolekci objektů SchemaAttribute , které představují atributy (například: křestní jméno, příjmení a poštovní adresu) typu.
Další parametry
Kromě standardního nastavení konfigurace můžete definovat další vlastní nastavení konfigurace, která jsou specifická pro instanci konektoru. Tyto parametry je možné zadat na úrovni konektoru, oddílu nebo spuštění kroku a získat přístup z příslušného Windows PowerShell skriptu. Vlastní nastavení konfigurace mohou být uložena v databázi synchronizační služby ve formátu prostého textu nebo mohou být zašifrovaná. Synchronizační služba v případě potřeby automaticky šifruje a dešifruje nastavení zabezpečené konfigurace.
Pokud chcete zadat vlastní nastavení konfigurace, oddělte názvy jednotlivých parametrů čárkou ( , ).
Pokud chcete získat přístup k vlastnímu nastavení konfigurace ze skriptu, musíte název přidat podtržítkem ( _ ) a oborem parametru (Global, Partition nebo RunStep). Například pro přístup k parametru Global FileName použijte tento fragment kódu: $ConfigurationParameters["FileName_Global"].Value
Možnosti
Karta schopností agenta pro správu Designer definuje chování a funkce konektoru. Výběry provedené na této kartě nelze po vytvoření konektoru změnit. Tato tabulka obsahuje seznam nastavení schopností.
| Schopnost | Description |
|---|---|
| Styl rozlišujícího názvu | Určuje, jestli spojnice podporuje rozlišující názvy, a pokud ano, jaký styl. |
| Typ exportu | Určuje typ objektů, které jsou prezentovány ve skriptu exportu. |
| Normalizace dat | Dává synchronizační službě pokyn, aby normalizovala atributy ukotvení před jejich poskytnutím skriptům. |
| Potvrzení objektu | Konfiguruje chování čekajícího importu v synchronizační službě. |
| Použití DN jako ukotvení | Pokud je styl rozlišujícího názvu nastavený na LDAP, atribut ukotvení pro prostor konektoru je také rozlišující název. |
| Souběžné operace několika konektorů | Pokud je zaškrtnuté políčko, může současně běžet několik konektorů Windows PowerShell. |
| Oddíly | Pokud je zaškrtnuté, konektor podporuje více oddílů a zjišťování oddílů. |
| Hierarchie | Pokud je tato možnost zaškrtnutá, konektor podporuje hierarchickou strukturu stylu LDAP. |
| Povolit import | Pokud je tato možnost zaškrtnutá, konektor importuje data prostřednictvím importovacích skriptů. |
| Povolit rozdílový import | Po zaškrtnutí může konektor požadovat rozdíly ze skriptů importu. |
| Povolit export | Pokud je tato možnost zaškrtnutá, konektor exportuje data prostřednictvím exportních skriptů. |
| Povolit úplný export | Když je tato možnost zaškrtnutá, skripty pro export podporují export celého prostoru konektoru. Chcete-li použít tuto možnost, musí být zaškrtnuté také políčko Povolit export. |
| V prvním průchodu exportu nejsou žádné referenční hodnoty. | Pokud je zaškrtnuté, atributy odkazu se exportují v druhém průchodu exportu. |
| Povolit přejmenování objektů | Pokud je zaškrtnuté, rozlišující názvy se dají upravit. |
| Delete-Add Jako nahradit | Pokud je zaškrtnuté, operace odstranění a přidání se exportují jako jedna náhrada. |
| Povolení operací s hesly | Po zaškrtnutí se podporují skripty synchronizace hesel. |
| Povolení exportu hesla při prvním průchodu | Pokud je tato možnost zaškrtnutá, hesla nastavená během zřizování se exportují při vytvoření objektu. |
Globální parametry
Karta Globální parametry v agentu pro správu Designer umožňuje nakonfigurovat Windows PowerShell skripty, které konektor spouští. Můžete také nakonfigurovat globální hodnoty pro vlastní nastavení konfigurace definované na kartě Připojení.
Zjišťování oddílů
Oddíl je samostatný obor názvů v rámci jednoho sdíleného schématu. Například ve službě Active Directory je každá doména oddílem v rámci jedné doménové struktury. Oddíl je logické seskupení pro operace importu a exportu. Import a export mají oddíl jako kontext a všechny operace probíhají v tomto kontextu. Oddíly by měly představovat hierarchii v protokolu LDAP. Rozlišující název oddílu se používá při importu k ověření, že všechny vrácené objekty jsou v oboru oddílu. Rozlišující název oddílu se používá také při zřizování z metaverse do prostoru konektoru k určení oddílu, ke kterým by měl být objekt přidružen během exportu.
Skript zjišťování oddílů obdrží z konektoru následující parametry:
| Name | Typ dat | Popis |
|---|---|---|
| ConfigParameters | KeyedCollection[string, ConfigParameter] | Tabulka konfiguračních parametrů konektoru |
| Reference | PSCredential | Obsahuje všechny přihlašovací údaje zadané správcem na kartě Připojení. |
Skript musí do kanálu vrátit jeden objekt Partition nebo List[T] objektů Partition.
Zjišťování hierarchie
Skript zjišťování hierarchie se používá pouze v případech, kdy je funkce Styl rozlišujícího názvu ldap. Skript umožňuje procházet a vybrat sadu kontejnerů, které jsou považovány za operace importu a exportu nebo mimo jejich rozsah. Skript by měl poskytovat pouze seznam uzlů, které jsou přímými podřízenými uzly kořenového uzlu dodaného do skriptu.
Skript zjišťování hierarchie obdrží z konektoru následující parametry:
| Name | Typ dat | Popis |
|---|---|---|
| Parametry konfigurace | KeyedCollection[řetězec, ConfigParameter] | Tabulka parametrů konfigurace konektoru |
| Reference | Přihlašovací údaje PS | Obsahuje všechny přihlašovací údaje zadané správcem na kartě Připojení. |
| Parentnode | HierarchyNode | Kořenový uzel hierarchie, pod kterou by měl skript vracet přímé podřízené položky. |
Skript musí do kanálu vrátit jeden podřízený objekt HierarchyNode nebo List[T] podřízených objektů HierarchyNode.
Import
Konektory, které podporují operace importu, musí implementovat tři skripty.
Zahájit import
Skript pro zahájení importu se spustí na začátku kroku spuštění importu. Během tohoto kroku můžete navázat připojení ke zdrojovému systému a před importem dat z připojeného systému provést přípravné kroky.
Skript pro zahájení importu obdrží z konektoru následující parametry:
| Name | Typ dat | Popis |
|---|---|---|
| Parametry konfigurace | KeyedCollection[řetězec, ConfigParameter] | Tabulka parametrů konfigurace konektoru |
| Reference | Přihlašovací údaje PS | Obsahuje všechny přihlašovací údaje zadané správcem na kartě Připojení. |
| OpenImportConnectionRunStep | OpenImportConnectionRunStep | Informuje skript o typu spuštění importu (rozdílový nebo úplný), oddílu, hierarchii, vodoznaku a očekávané velikosti stránky. |
| Typy | Schéma | Schéma prostoru konektoru, který se importuje. |
Skript musí do kanálu vrátit jeden objekt OpenImportConnectionResults , například: Write-Output (New-Object Microsoft.MetadirectoryServices.OpenImportConnectionResults)
Import dat
Konektor volá datový skript pro import, dokud tento skript neuznačí, že už nejsou k dispozici žádná další data k importu. Konektor Windows PowerShell má velikost stránky 9 999 objektů. Pokud skript vrátí k importu více než 9 999 objektů, musíte stránkování podporovat. Konektor zveřejňuje vlastní vlastnost dat, kterou můžete použít k uložení vodoznaku, takže při každém zavolání skriptu importu dat skript obnoví import objektů tam, kde skončil.
Skript importu dat obdrží z konektoru následující parametry:
| Name | Typ dat | Popis |
|---|---|---|
| Parametry konfigurace | KeyedCollection[řetězec, ConfigParameter] | Tabulka parametrů konfigurace konektoru |
| Reference | Přihlašovací údaje PS | Obsahuje všechny přihlašovací údaje zadané správcem na kartě Připojení. |
| GetImportEntriesRunStep | ImportRunStep | Obsahuje vodoznak (CustomData), který je možné použít při stránkovaných a rozdílových importech. |
| OpenImportConnectionRunStep | OpenImportConnectionRunStep | Informuje skript o typu spuštění importu (rozdílový nebo úplný), oddílu, hierarchii, vodoznaku a očekávané velikosti stránky. |
| Typy | Schéma | Schéma prostoru konektoru, který se importuje. |
Skript importu dat musí do kanálu zapsat objekt List[CSEntryChange]. Tato kolekce se skládá z csEntryChange atributy, které představují každý importovaný objekt. Během úplného importu by tato kolekce měla mít úplnou sadu objektů CSEntryChange, které mají všechny atributy pro každý objekt. Během rozdílového importu by měl objekt CSEntryChange obsahovat rozdíly na úrovni atributů pro každý importovaný objekt nebo úplnou reprezentaci objektů, které se změnily (režim nahrazení).
Ukončit import
Na konci importu se spustí skript End Import. Tento skript by měl provádět všechny nezbytné úlohy čištění (například ukončení připojení k systémům a reakce na selhání).
Koncový skript importu obdrží z konektoru následující parametry:
| Name | Typ dat | Popis |
|---|---|---|
| Parametry konfigurace | KeyedCollection[řetězec, ConfigParameter] | Tabulka parametrů konfigurace konektoru |
| Reference | Přihlašovací údaje PS | Obsahuje všechny přihlašovací údaje zadané správcem na kartě Připojení. |
| OpenImportConnectionRunStep | OpenImportConnectionRunStep | Informuje skript o typu spuštění importu (rozdílový nebo úplný), oddílu, hierarchii, vodoznaku a očekávané velikosti stránky. |
| CloseImportConnectionRunStep | CloseImportConnectionRunStep | Informuje skript o důvodu ukončení importu. |
Skript musí kanálu vrátit jeden objekt CloseImportConnectionResults , například: Write-Output (New-Object Microsoft.MetadirectoryServices.CloseImportConnectionResults)
Export
Konektory, které podporují export, musí být stejně jako architektura importu konektoru implementovat tři skripty.
Zahájit export
Skript pro zahájení exportu se spustí na začátku kroku spuštění exportu. Během tohoto kroku můžete navázat připojení ke zdrojovému systému a provést přípravné kroky před exportem dat do připojeného systému.
Skript pro zahájení exportu obdrží z konektoru následující parametry:
| Name | Typ dat | Popis |
|---|---|---|
| Parametry konfigurace | KeyedCollection[řetězec, ConfigParameter] | Tabulka parametrů konfigurace konektoru |
| Reference | Přihlašovací údaje PS | Obsahuje všechny přihlašovací údaje zadané správcem na kartě Připojení. |
| OpenExportConnectionRunStep | OpenExportConnectionRunStep | Informuje skript o typu spuštění exportu (rozdílové nebo úplné), oddílu, hierarchii a očekávané velikosti stránky. |
| Typy | Schéma | Schéma pro prostor konektoru, který se exportuje. |
Skript by neměl do kanálu vracet žádný výstup.
Export dat
Synchronizační služba volá skript exportu dat tolikrát, kolikrát je potřeba ke zpracování všech čekajících exportů. Pokud je v prostoru konektoru více nevyřízených exportů, než je velikost stránky konektoru, může se skript exportu dat pro stejný objekt volat vícekrát a možná i vícekrát.
Skript exportu dat obdrží z konektoru následující parametry:
| Name | Typ dat | Popis |
|---|---|---|
| ConfigParameters | KeyedCollection[string, ConfigParameter] | Tabulka konfiguračních parametrů konektoru |
| Reference | PSCredential | Obsahuje všechny přihlašovací údaje zadané správcem na kartě Připojení. |
| CSEntries | IListCSEntryChange | Seznam všech objektů prostoru konektoru s čekajícími exporty, které se mají zpracovat během tohoto průchodu |
| OpenExportConnectionRunStep | OpenExportConnectionRunStep | Informuje skript o typu spuštění exportu (rozdílové nebo úplné), oddílu, hierarchii a očekávané velikosti stránky. |
| Typy | Schéma | Schéma pro prostor konektoru, který se exportuje. |
Skript exportu dat musí do kanálu vrátit objekt PutExportEntriesResults . Tento objekt nemusí obsahovat informace o výsledku pro každý exportovaný konektor, pokud nedojde k chybě nebo změně atributu ukotvení. Například pro vrácení objektu PutExportEntriesResults do kanálu: Write-Output (New-Object Microsoft.MetadirectoryServices.PutExportEntriesResults)
Ukončit export
Na konci spuštění exportu se spustí skript End Export. Tento skript by měl provádět všechny potřebné úlohy čištění (například uzavřít připojení k systémům a reagovat na chyby).
Koncový exportní skript obdrží z konektoru následující parametry:
| Name | Typ dat | Popis |
|---|---|---|
| ConfigParameters | KeyedCollection[string, ConfigParameter] | Tabulka konfiguračních parametrů konektoru |
| Reference | PSCredential | Obsahuje všechny přihlašovací údaje zadané správcem na kartě Připojení. |
| OpenExportConnectionRunStep | OpenExportConnectionRunStep | Informuje skript o typu spuštění exportu (rozdílové nebo úplné), oddílu, hierarchii a očekávané velikosti stránky. |
| CloseExportConnectionRunStep | CloseExportConnectionRunStep | Informuje skript o důvodu ukončení exportu. |
Skript by neměl do kanálu vracet žádný výstup.
Synchronizace hesel
Windows PowerShell konektory se dají použít jako cíl pro změny nebo resetování hesel.
Skript pro heslo obdrží z konektoru následující parametry:
| Name | Typ dat | Popis |
|---|---|---|
| ConfigParameters | KeyedCollection[string, ConfigParameter] | Tabulka konfiguračních parametrů konektoru |
| Reference | PSCredential | Obsahuje všechny přihlašovací údaje zadané správcem na kartě Připojení. |
| Oddíl | Oddíl | Oddíl adresáře, ve které se csEntry nachází. |
| CSEntry | CSEntry | Položka místa konektoru pro objekt, u kterého došlo ke změně nebo resetování hesla. |
| Typ operace | Řetězec | Označuje, jestli se jedná o operaci resetování (SetPassword) nebo změnu (ChangePassword). |
| Možnosti hesel | Možnosti hesel | Příznaky, které určují zamýšlené chování resetování hesla. Tento parametr je k dispozici pouze v případě, že operationType je SetPassword. |
| Staré heslo | Řetězec | Vyplněno starým heslem objektu pro změny hesla. Tento parametr je k dispozici pouze v případě, že je OperationType ChangePassword. |
| Newpassword | Řetězec | Vyplněno novým heslem objektu, které by měl skript nastavit. |
Neočekává se, že skript hesla vrátí do kanálu Windows PowerShell žádné výsledky. Pokud ve skriptu pro heslo dojde k chybě, měl by skript vyvolat jednu z následujících výjimek, aby o problému informoval synchronizační službu:
- PasswordPolicyViolationException – vyvolána, pokud heslo nesplňuje zásady hesel v připojeném systému.
- PasswordIllFormedException – vyvolána, pokud heslo není přijatelné pro připojený systém.
- PasswordExtension – vyvolání všech ostatních chyb ve skriptu hesla.
Ukázkové konektory
Úplný přehled dostupných ukázkových konektorů najdete v tématu kolekce konektorů Windows PowerShell.
Další poznámky
Další konfigurace zosobnění
Uživateli, který je zosobněný, udělte na serveru synchronizační služby následující oprávnění:
Přístup pro čtení k následujícím klíčům registru:
- HKEY_USERS\[SynchronizationServiceServiceAccountSID]\Software\Microsoft\PowerShell
- HKEY_USERS\[SynchronizationServiceServiceAccountSID]\Environment
Pokud chcete zjistit identifikátor zabezpečení (SID) účtu synchronizační služby, spusťte následující příkazy PowerShellu:
$account = New-Object System.Security.Principal.NTAccount "<domain>\<username>"
$account.Translate([System.Security.Principal.SecurityIdentifier]).Value
Přístup pro čtení k následujícím složkám systému souborů:
- %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}
Zástupný symbol {ConnectorName} nahraďte názvem konektoru Windows PowerShell.
Poradce při potížích
- Informace o tom, jak povolit protokolování pro řešení potíží s konektorem, najdete v tématu Jak povolit trasování trasování událostí pro windows pro konektory.