Technické informace o konektoru Windows PowerShellu
Tento článek popisuje konektor Windows PowerShellu. Článek se vztahuje na následující produkty:
- Microsoft Identity Manager 2016 (MIM2016)
Pro MIM2016 je konektor k dispozici ke stažení z Centra pro stahování Microsoft.
Přehled konektoru PowerShellu
Konektor PowerShellu umožňuje integrovat synchronizační službu s externími systémy, které nabízejí rozhraní API založená na Prostředí Windows PowerShell. Konektor poskytuje most mezi schopnostmi struktury volacího modulárního agenta pro správu připojení (ECMA2) a Windows PowerShell. Další informace o rozhraní ECMA naleznete 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 skripty Windows PowerShellu. Pokud skripty, které konektor spouští, nejsou digitálně podepsané, nakonfigurujte zásady provádě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 příkaz podpory pro tyto skripty by byl poskytnut tímto produktem. Pokud vyvíjíte vlastní skripty pro použití s tímto konektorem, budete se muset seznámit s rozhraním API agenta Extensible Connectivity Management, 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 spolupracovat s dodavatelem třetí strany nebo partnerem pro nasazení, který vám poskytne pomoc, pokyny a podporu pro tuto integraci.
Vytvoření nového konektoru
Pokud chcete vytvořit konektor Windows PowerShellu ve synchronizační službě, musíte zadat řadu skriptů Windows PowerShellu, které provádějí kroky požadované synchronizační službou. V závislosti na zdroji dat, ke kterému se připojujete, a požadované funkčnosti se skripty, které musíte implementovat, liší. Tato část popisuje všechny skripty, které je možné implementovat a kdy jsou potřeba.
Konektor prostředí Windows PowerShell je navržený tak, aby ukládal každý z těchto skriptů uvnitř databáze Služby synchronizace. I když je možné spouštět skripty uložené v systému souborů, je jednodušší vložit tělo každého skriptu přímo do konfigurace konektoru.
Pokud chcete vytvořit konektor PowerShellu, v synchronizační službě vyberte Agent pro správu a Vytvořit. Vyberte konektor PowerShell (Microsoft).
konektoru
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 PowerShellu při spuštění konektoru.
Můžete nakonfigurovat následující parametry připojení:
Připojení
| Parametr | Výchozí hodnota | Účel |
|---|---|---|
| počítačový server | <Prázdné> | Název serveru, ke kterému se má konektor připojit. |
| Domain (Doména) | <Prázdné> | Doména přihlašovacích údajů k uložení 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ů k uložení pro použití při spuštění konektoru |
| Zosobnění účtu konektoru | Nepravda | Pokud je pravda, synchronizační služba spouští skripty Windows PowerShellu v kontextu zadaných přihlašovacích údajů. Pokud je to možné, doporučuje se předat parametr $Credentials každému skriptu a místo zosobnění jej použít. 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í | Nepravda | Instruuje systém Windows, aby během zosobnění načetl uživatelský profil podle přihlašovacích údajů konektoru. Pokud má zosobněný uživatel cestovní profil, konektor tento cestovní profil 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 | Nepravda | Pokud je pravda, konektor Windows PowerShellu ověří, že každý skript má platný digitální podpis. Pokud není splněno, ujistěte se, že zásady spouštění Windows PowerShellu na serveru synchronizační služby jsou nastaveny na RemoteSigned nebo Unrestricted. |
společného modulu
Konektor umožňuje uložit sdílený modul Windows PowerShellu v konfiguraci. Když konektor spustí skript, modul prostředí Windows PowerShell se extrahuje do systému souborů, aby jej mohl importovat každý skript.
Pro skripty importu, exportu a synchronizace hesel se společný modul extrahuje do složky MAData konektoru. Pro skripty pro 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 se extrahovaný skript modulu jmenuje podle nastavení Common Module Script Name.
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í parametrů
Ověřovací skript je volitelný skript prostředí Windows PowerShell, který lze použít k zajištění platnosti parametrů konfigurace konektoru, které zadal správce. Ověřování serveru, přihlašovacích údajů připojení a parametrů připojení jsou běžnými použití ověřovacího skriptu. Ověřovací skript se volá po změně 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:
| Název | Datový typ | Popis |
|---|---|---|
| StránkaKonfiguraceParametru | ConfigParameterPage | Karta konfigurace nebo dialogové okno, které aktivovalo žádost o ověření. |
| Konfigurační parametry | Kolekce na základě klíče [řetězec, KonfiguračníParametr] | Tabulka parametrů konfigurace konektoru |
| Pověření | PSCredential | Obsahuje všechny přihlašovací údaje zadané správcem na kartě Připojení. |
Ověřovací skript by měl vrátit do kanálu jeden objekt ParameterValidationResult.
zjišťování schématu
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 spustí během vytváření konektoru a naplní schéma konektoru. Používá se také akcí Aktualizovat schéma ve Správci synchronizační služby.
Skript pro zjišťování schématu obdrží z konektoru následující parametry:
| Název | Datový typ | Popis |
|---|---|---|
| Konfigurační parametry | KeyedCollection [řetězec, ConfigParameter] | Tabulka parametrů konfigurace konektoru |
| Pověření | PSCredential | Obsahuje všechny přihlašovací údaje zadané správcem na kartě Připojení. |
Skript musí vrátit do kanálu jeden objekt schématu. Objekt Schema se skládá z SchemaType objekty, které představují typy objektů (například uživatelé a skupiny). Objekt SchemaType obsahuje kolekci SchemaAttribute objekty, které představují atributy (například jméno, příjmení a poštovní adresa) typu.
další parametry
Kromě standardních 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 úrovni spuštění kroku a přistupovat k nim z příslušného skriptu Windows PowerShell. Vlastní nastavení konfigurace lze uložit v databázi synchronizační služby ve formátu prostého textu nebo mohou být šifrované. Synchronizační služba automaticky šifruje a dešifruje nastavení zabezpečené konfigurace v případě potřeby.
Pokud chcete zadat vlastní nastavení konfigurace, oddělte název každého parametru čárkou ( , ).
Pokud chcete získat přístup k vlastnímu nastavení konfigurace ze skriptu, musíte název přidat podtržítkem (_) a rozsahem parametru (Global, Partition nebo RunStep). Například pro přístup k parametru Global FileName použijte tento fragment kódu: $ConfigurationParameters["FileName_Global"].Value
Schopnosti
Karta Možnosti v Návrháři agenta pro správu 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 | Popis |
|---|---|
| Styl rozlišitelného názvu | Určuje, jestli konektor podporuje rozlišující názvy a jestli ano, v jakém stylu. |
| typ exportu | Určuje typ objektů, které jsou prezentovány do skriptu exportu. |
| normalizace dat | Uděluje synchronizační službě pokyn, aby atributy ukotvení normalizovala předtím, než budou poskytnuty skriptům. |
| potvrzení objektu | Konfiguruje chování čekajícího importu v synchronizační službě. |
| Použít DN jako Anchor | Pokud je styl rozlišujícího názvu nastaven na LDAP, atribut ukotvení prostoru konektoru je také rozlišující název. |
| Souběžné operace několika konektorů | Při zaškrtnutí se může spouštět více konektorů Windows PowerShell současně. |
| Oddíly | Pokud je tato možnost 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 | Když je tato možnost zaškrtnutá, konektor importuje data prostřednictvím skriptů importu. |
| Povolení rozdílového importu | Pokud je zaškrtnuto, konektor může vyžádat změny ze skriptů importu. |
| Povolit export | Když 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é možnost Povolit export. |
| V prvním exportním průchodu nejsou žádné referenční hodnoty. | Když je zaškrtnuto, atributy odkazu se exportují v dalším exportním průchodu. |
| Povolit přejmenování objektu | Při zaškrtnutí lze distingované názvy změnit. |
| Odstranit a přidat jako náhradu | Po zaškrtnutí se operace odstranění a přidání exportují jako jediná náhrada. |
| Povolení operací s hesly | Při zaškrtnutí jsou skripty synchronizace hesel podporovány. |
| Povolit heslo pro export při prvním pokusu | Při zaškrtnutí se při vytváření objektu exportují hesla nastavená během zřizování. |
Globální parametry
Karta Global Parameters v Management Agent Designeru umožňuje konfigurovat skripty Windows PowerShell, které jsou spouštěny prostřednictvím konektoru. Můžete také nakonfigurovat globální hodnoty pro vlastní nastavení konfigurace definovaná na kartě Připojení.
zjišťování oddílů
Partice 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 jedné doménové struktuře. 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 mají 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 rámci rozsahu oddílu. Rozlišovací 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ému by měl být objekt přidružen během exportu.
Skript pro zjišťování oddílů obdrží z konektoru následující parametry:
| Název | Datový typ | Popis |
|---|---|---|
| Konfigurační parametry | KeyedCollection[string, ConfigParameter] | Tabulka parametrů konfigurace konektoru |
| Pověření | PSCredential | Obsahuje všechny přihlašovací údaje zadané správcem na kartě Připojení. |
Skript musí do potrubí vrátit buď jeden objekt Oddíl, nebo seznam objektů oddílů [T].
zjišťování hierarchie
**
Skript pro zjišťování hierarchie se používá pouze v případech, když je funkce Styl rozlišeného názvu nastavena na LDAP. Skript slouží k procházení a výběru sady kontejnerů, které jsou považovány za nebo mimo rozsah operací importu a exportu. Skript by měl obsahovat pouze seznam uzlů, které jsou přímými podřízenými uzly kořenového uzlu zadaného do skriptu.
Skript zjišťování hierarchie obdrží z konektoru následující parametry:
| Název | Datový typ | Popis |
|---|---|---|
| ConfigParameters | KolekceSKlíči[řetězec, KonfiguračníParametr] | Tabulka parametrů konfigurace konektoru |
| Pověření | PSCredential | Obsahuje všechny přihlašovací údaje zadané správcem na kartě Připojení. |
| ParentNode | Uzel hierarchie | Kořenový uzel hierarchie, pod kterou by měl skript vracet přímé podřízené položky. |
Skript musí do potrubí vrátit buď jeden podřízený objekt HierarchyNode, nebo seznam (List[T]) podřízených objektů HierarchyNode.
Dovoz
Konektory, které podporují operace importu, musí implementovat tři skripty.
Zahájit import
Počáteční skript pro import 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:
| Název | Datový typ | Popis |
|---|---|---|
| Konfigurační parametry | KeyedCollection[string, ConfigParameter] | Tabulka parametrů konfigurace konektoru |
| Pověření | PSCredential | Obsahuje všechny přihlašovací údaje zadané správcem na kartě Připojení. |
| OpenImportConnectionRunStep | OpenImportConnectionRunStep | Informuje skript o typu provedení importu (delta nebo full), partition, hierarchii, vodoznaku a očekávané velikosti stránky. |
| Typy | Schéma | Schéma pro importovaný prostor konektoru |
Skript musí do kanálu vrátit jeden objekt OpenImportConnectionResults, například: Write-Output (New-Object Microsoft.MetadirectoryServices.OpenImportConnectionResults)
Import dat
Skript pro import dat je volán konektorem, dokud skript nezjistí, že žádná další data nejsou k importu. Konektor Windows PowerShellu má velikost stránky 9 999 objektů. Pokud váš skript vrátí více než 9 999 objektů pro import, musíte podporovat stránkování. Konektor zveřejňuje vlastní datovou vlastnost, kterou můžete použít k uložení označení, takže pokaždé, když je zavolán skript pro import dat, váš skript obnoví import objektů tam, kde jste přestali.
Skript pro import dat přijímá z konektoru následující parametry:
| Název | Datový typ | Popis |
|---|---|---|
| Konfigurační parametry | KolekceSKlíčem[řetězec, KonfiguračníParametr] | Tabulka parametrů konfigurace konektoru |
| Pověření | PSCredential | Obsahuje všechny přihlašovací údaje zadané správcem na kartě Připojení. |
| ZískatVloženéImportyKrokSpuštění | ImportRunStep | Obsahuje vodoznak (CustomData), který lze použít při stránkovaných importech 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 pro importovaný prostor konektoru |
Skript pro import dat musí do kanálu napsat objekt List[CSEntryChange]. Tato kolekce se skládá z atributů CSEntryChange, které představují každý importovaný objekt. Během běhu úplného importu by tato kolekce měla mít úplnou sadu objektů CSEntryChange, které mají všechny atributy pro každý objekt. Při importu Delta by objekt CSEntryChange měl buď obsahovat atributové změny každého importovaného objektu, nebo úplné zobrazení objektů, které se změnily (režim nahrazení).
Ukončit import
Na závěr importu se spustí skript pro ukončení importu. Tento skript by měl provádět všechny potřebné úlohy čištění (například zavření připojení k systémům a reakce na selhání).
Koncový skript importu obdrží z konektoru následující parametry:
| Název | Datový typ | Popis |
|---|---|---|
| ConfigParameters | KolekceSKlíčem[řetězec, ParametrKonfigurace] | Tabulka parametrů konfigurace konektoru |
| Pověření | PSCredential | Obsahuje všechny přihlašovací údaje zadané správcem na kartě Připojení. |
| OpenImportConnectionRunStep | OpenImportConnectionRunStep Postupujte podle těchto kroků: | Informuje skript o typu spuštění importu („delta“ nebo „úplný“), oddílu, hierarchii, vodoznaku a očekávané velikosti datové stránky. |
| UzavřítImportPřipojeníKrokSpuštění | CloseImportConnectionRunStep | Informuje skript o důvodu ukončení importu. |
Skript musí vrátit do kanálu jeden objekt CloseImportConnectionResults, například: Write-Output (New-Object Microsoft.MetadirectoryServices.CloseImportConnectionResults)
Vývoz
Identické s architekturou importu konektoru musí konektory podporující export implementovat tři skripty.
zahájení exportu
Počáteční skript pro export 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 před exportem dat do připojeného systému provést všechny přípravné kroky.
Skript pro zahájení exportu přijímá z konektoru následující parametry:
| Název | Datový typ | Popis |
|---|---|---|
| Konfigurační parametry | KeyedCollection[string, ConfigParameter] | Tabulka parametrů konfigurace konektoru |
| Pověření | PSCredential | Obsahuje všechny přihlašovací údaje zadané správcem na kartě Připojení. |
| OpenExportConnectionRunStep | OtevřítExportPřipojeníKroky | 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 prostoru konektoru, který je exportován |
Skript by neměl vracet žádný výstup do kanálu.
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 má prostor konektoru více nevyřízených exportů než je velikost stránky konektoru, může být skript pro export dat volán vícekrát, a případně opakovaně pro stejný objekt.
Skript pro export dat přijímá z konektoru následující parametry:
| Název | Datový typ | Popis |
|---|---|---|
| Konfigurační parametry | KeyedCollection[řetězec, ConfigParameter] | Tabulka parametrů konfigurace konektoru |
| Pověření | PSCredential | Obsahuje všechny přihlašovací údaje zadané správcem na kartě Připojení. |
| CsEntries | IListCSEntryChange | Seznam všech objektů v prostoru konektorů s nevyřízenými exporty, které se mají zpracovat během tohoto cyklu. |
| 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 prostoru konektoru, který je exportován |
Skript exportu dat musí vrátit objekt PutExportEntriesResults do pipeline. Tento objekt nemusí obsahovat informace o výsledku pro každý exportovaný konektor, pokud nedojde k chybě nebo změně atributu ukotvení. Pokud například chcete vrátit objekt PutExportEntriesResults do potrubí: Write-Output (New-Object Microsoft.MetadirectoryServices.PutExportEntriesResults)
Ukončit export
Na závěr spuštění exportu spusťte závěrečný skript exportu. Tento skript by měl provádět všechny potřebné úlohy čištění (například zavření připojení k systémům a reakce na selhání).
Koncový skript exportu obdrží z konektoru následující parametry:
| Název | Datový typ | Popis |
|---|---|---|
| Konfigurační parametry | KeyedCollection[string, ConfigParameter] | Tabulka parametrů konfigurace konektoru |
| Pověření | 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. |
| KrokProvozUkončeníExportníhoPřipojení | CloseExportConnectionRunStep | Informuje skript o důvodu ukončení exportu. |
Skript nesmí vracet žádný výstup do roury.
Synchronizace hesel
Konektory Windows PowerShellu je možné použít jako cíl pro změny a resetování hesla.
Skript hesla obdrží z konektoru následující parametry:
| Název | Datový typ | Popis |
|---|---|---|
| Konfigurační parametry | KeyedCollection[řetězec, ConfigParameter] | Tabulka parametrů konfigurace konektoru |
| Pověření | 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é je csEntry. |
| CSEntry | CSEntry | Položka prostoru konektoru pro objekt, který obdržel změnu nebo resetování hesla |
| Typ operace | Řetězec | Označuje, zda je operace reset (SetPassword) nebo změna (ChangePassword). |
| Možnosti hesla | Možnosti hesla | 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ěné starým heslem objektu pro změny hesla. Tento parametr je k dispozici pouze v případě, že operationType je ChangePassword. |
| NovéHeslo | Řetězec | Naplněno novým heslem objektu, které má skript nastavit. |
Skript hesla není očekáván, že vrátí jakékoliv výsledky do kanálu Windows PowerShell. Pokud ve skriptu hesla dojde k chybě, měl by skript vyvolat jednu z následujících výjimek, která informuje synchronizační službu o problému:
- PasswordPolicyViolationException – vyvolá se, pokud heslo nesplňuje zásady hesel v připojeném systému.
- PasswordIllFormedException – vyvolá se, pokud heslo není přijatelné pro připojený systém.
- PasswordExtension – vyvolá se pro všechny ostatní chyby ve skriptu hesla.
Ukázkové konektory
Úplný přehled dostupných ukázkových konektorů najdete v kolekci ukázkových konektorů Windows PowerShellu.
Další poznámky
Další konfigurace pro zosobnění
Udělte uživateli, který je zosobněný, následující oprávnění na serveru synchronizační služby:
Přístup pro čtení k následujícím klíčům registru:
- HKEY_USERS\[SynchronizationServiceServiceAccountSID]\Software\Microsoft\PowerShell
- HKEY_USERS\[SynchronizationServiceServiceAccountSID]\Prostředí
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 PowerShellu.
Řešení problémů
- Informace o tom, jak povolit protokolování pro řešení potíží s konektorem, najdete v tématu Povolení trasování událostí pro Windows pro konektory.