Technische naslaginformatie voor Windows PowerShell Connector

In dit artikel wordt de Windows PowerShell-connector beschreven. Het artikel is van toepassing op de volgende producten:

• Microsoft Identity Manager 2016 (MIM2016)

Voor MIM2016 is de connector beschikbaar als download van het Microsoft Downloadcentrum.

Overzicht van de PowerShell-connector

Met de PowerShell-connector kunt u de synchronisatieservice integreren met externe systemen die op Windows PowerShell gebaseerde API's bieden. De connector biedt een brug tussen de mogelijkheden van het ECMA2-framework (Extensible Connectivity Management Agent) op basis van aanroepen en Windows PowerShell. Zie de Extensible Connectivity 2.2 Management Agent Referencevoor meer informatie over het ECMA-framework.

Benodigdheden

Voordat u de connector gebruikt, moet u ervoor zorgen dat u het volgende op de synchronisatieserver hebt:

• Microsoft .NET 4.6.2 Framework of hoger
• Windows PowerShell 2.0, 3.0 of 4.0

Het uitvoeringsbeleid op de synchronisatieserviceserver moet worden geconfigureerd om de connector toe te staan Windows PowerShell-scripts uit te voeren. Tenzij de scripts die door de connector worden uitgevoerd digitaal zijn ondertekend, configureert u het uitvoeringsbeleid door deze opdracht uit te voeren:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

Voor het implementeren van deze connector zijn een of meer PowerShell-scripts vereist. Sommige Microsoft-producten bieden mogelijk scripts voor gebruik met deze connector en de ondersteuningsverklaring voor deze scripts wordt door dat product verstrekt. Als u uw eigen scripts ontwikkelt voor gebruik met deze connector, moet u bekend zijn met de Extensible Connectivity Management Agent-API om deze scripts te ontwikkelen en te onderhouden. Als u integreert met systemen van derden met behulp van uw eigen scripts in een productieomgeving, raden we u aan samen te werken met de leverancier van de derde partij of een implementatiepartner voor hulp, begeleiding en ondersteuning voor deze integratie.

Een nieuwe connector maken

Als u een Windows PowerShell-connector wilt maken in de synchronisatieservice, moet u een reeks Windows PowerShell-scripts opgeven waarmee de stappen worden uitgevoerd die door de synchronisatieservice zijn aangevraagd. Afhankelijk van de gegevensbron waarmee u verbinding maakt en de functionaliteit die u nodig hebt, variëren de scripts die u moet implementeren. In deze sectie worden alle scripts beschreven die kunnen worden geïmplementeerd en wanneer ze nodig zijn.

De Windows PowerShell-connector is ontworpen voor het opslaan van alle scripts in de synchronisatieservicedatabase. Hoewel het mogelijk is om scripts uit te voeren die zijn opgeslagen in het bestandssysteem, is het eenvoudiger om de hoofdtekst van elk script rechtstreeks in te voegen in de configuratie van de connector.

Als u een PowerShell-connector wilt maken, selecteert u in Synchronization Service, Management Agent en Maken. Selecteer de PowerShell (Microsoft) Connector.

Connectiviteit

Configuratieparameters opgeven om verbinding te maken met een extern systeem. Deze waarden worden veilig opgeslagen door de synchronisatieservice en beschikbaar gemaakt voor uw Windows PowerShell-scripts wanneer de connector wordt uitgevoerd.

U kunt de volgende connectiviteitsparameters configureren:

Connectiviteit

Algemene module
Met de connector kunt u een gedeelde Windows PowerShell-module opslaan in de configuratie. Wanneer de connector een script uitvoert, wordt de Windows PowerShell-module geëxtraheerd naar het bestandssysteem, zodat deze door elk script kan worden geïmporteerd.

Voor scripts voor importeren, exporteren en wachtwoordsynchronisatie wordt de algemene module geëxtraheerd naar de MAData-map van de connector. Voor scripts voor schema-, validatie-, hiërarchie- en partitiedetectie wordt de algemene module geëxtraheerd naar de map %TEMP%. In beide gevallen krijgt het geëxtraheerde algemene modulescript een naam volgens de instelling Common Module Script Name.

Gebruik de volgende instructie om een module met de naam FIMPowerShellConnectorModule.psm1 uit de MAP MAData te laden: Import-Module (Join-Path -Path [Microsoft.MetadirectoryServices.MAUtils]::MAFolder -ChildPath "FIMPowerShellConnectorModule.psm1")

Gebruik de volgende instructie om een module met de naam FIMPowerShellConnectorModule.psm1 uit de map %TEMP% te laden: Import-Module (Join-Path -Path $env:TEMP -ChildPath "FIMPowerShellConnectorModule.psm1")

Parametervalidatie
Het validatiescript is een optioneel Windows PowerShell-script dat kan worden gebruikt om ervoor te zorgen dat de configuratieparameters van de connector die door de beheerder zijn opgegeven, geldig zijn. Het valideren van server-, verbindingsreferenties en verbindingsparameters zijn veelvoorkomende gebruiksgegevens van het validatiescript. Het validatiescript wordt aangeroepen nadat de volgende tabbladen en dialoogvensters zijn gewijzigd:

• Connectiviteit
• Globale parameters
• Partitieconfiguratie

Het validatiescript ontvangt de volgende parameters van de connector:

Het validatiescript moet één ParameterValidationResult-object retourneren aan de pijplijn.

schemadetectie
Het Schema Discovery-script is verplicht. Dit script retourneert de objecttypen, kenmerken en kenmerkbeperkingen die de synchronisatieservice gebruikt bij het configureren van kenmerkstroomregels. Het Schema Discovery-script wordt uitgevoerd tijdens het maken van de connector en vult het schema van de connector. Het wordt ook gebruikt door de actie Schema vernieuwen in Synchronisatieservicebeheer.

Het schemadetectiescript ontvangt de volgende parameters van de connector:

Het script moet één Schema--object retourneren aan de pijplijn. Het schemaobject bestaat uit SchemaType objecten die objecttypen vertegenwoordigen (bijvoorbeeld: gebruikers en groepen). Het Object SchemaType bevat een verzameling van SchemaAttribute objecten die de kenmerken vertegenwoordigen (bijvoorbeeld de opgegeven naam, achternaam en postadres) van het type.

aanvullende parameters
Naast de standaardconfiguratie-instellingen kunt u aanvullende aangepaste configuratie-instellingen definiëren die specifiek zijn voor het exemplaar van de connector. Deze parameters kunnen worden opgegeven op het niveau van de connector, partitie of stapuitvoering en worden toegepast vanuit het relevante Windows PowerShell-script. Aangepaste configuratie-instellingen kunnen worden opgeslagen in de synchronisatieservicedatabase in tekst zonder opmaak of ze kunnen worden versleuteld. De synchronisatieservice versleutelt en ontsleutelt indien nodig beveiligde configuratie-instellingen.

Als u aangepaste configuratie-instellingen wilt opgeven, scheidt u de naam van elke parameter met een komma ( , ).

Als u toegang wilt krijgen tot aangepaste configuratie-instellingen vanuit een script, moet u de naam achtervoegen met een onderstrepingsteken (_ ) en het bereik van de parameter (Global, Partition of RunStep). Als u bijvoorbeeld toegang wilt krijgen tot de parameter Global FileName, gebruikt u dit codefragment: $ConfigurationParameters["FileName_Global"].Value

Capaciteiten

Het tabblad Mogelijkheden van de ontwerpfunctie voor beheeragenten definieert het gedrag en de functionaliteit van de connector. De selecties die op dit tabblad zijn gemaakt, kunnen niet worden gewijzigd wanneer de connector is gemaakt. Deze tabel bevat de mogelijkheidsinstellingen.

Globale parameters

Op het tabblad Globale parameters in De ontwerpfunctie voor beheeragenten kunt u de Windows PowerShell-scripts configureren die door de connector worden uitgevoerd. U kunt ook globale waarden configureren voor aangepaste configuratie-instellingen die zijn gedefinieerd op het tabblad Connectiviteit.

partitiedetectie
Een partitie is een afzonderlijke naamruimte binnen één gedeeld schema. In Active Directory is elk domein bijvoorbeeld een partitie binnen één forest. Een partitie is de logische groepering voor import- en exportbewerkingen. Importeren en exporteren hebben partitie als context en alle bewerkingen worden in deze context uitgevoerd. Partities moeten een hiërarchie in LDAP vertegenwoordigen. De DN-naam van een partitie wordt gebruikt bij het importeren om te controleren of alle geretourneerde objecten binnen het bereik van een partitie vallen. De gedistingeerde partitie-naam wordt ook gebruikt tijdens het voorbereiden van de metaverse naar de connectorruimte om te bepalen aan welke partitie een object moet worden gekoppeld tijdens het exporteren.

Het script voor partitiedetectie ontvangt de volgende parameters van de connector:

nl-NL: Het script moet ofwel één Partitie-object of een lijst van partitie-objecten (List[T]) retourneren aan de pijplijn.

Hiërarchieontdekking
Het detectiescript voor de hiërarchie wordt alleen gebruikt wanneer de Distinguished Name-stijl functionaliteit LDAP is. Het script wordt gebruikt om te bladeren en een set containers te selecteren die binnen of buiten het toepassingsgebied van import- en exportbewerkingen valt. Het script mag alleen een lijst met knooppunten opgeven die directe kinderen zijn van het hoofdknooppunt dat aan het script is meegegeven.

Het detectiescript voor de hiërarchie ontvangt de volgende parameters van de connector:

Het script moet één onderliggend HierarchyNode-object of een lijst [T] met onderliggende HierarchyNode-objecten teruggeven aan de pijplijn.

Importeren

Connectors die importbewerkingen ondersteunen, moeten drie scripts implementeren.

Begin met importeren
Het begin-importscript wordt uitgevoerd aan het begin van een importstap. Tijdens deze stap kunt u een verbinding maken met het bronsysteem en voorbereidende stappen uitvoeren voordat u gegevens uit het verbonden systeem importeert.

Het importscript begin ontvangt de volgende parameters van de connector:

Het script moet één OpenImportConnectionResults-object retourneren aan de pijplijn, bijvoorbeeld: Write-Output (New-Object Microsoft.MetadirectoryServices.OpenImportConnectionResults)

Gegevens importeren
Het importgegevensscript wordt door de connector aangeroepen totdat het script aangeeft dat er geen gegevens meer zijn om te importeren. De Windows PowerShell-connector heeft een paginaformaat van 9.999 objecten. Als uw script meer dan 9.999 objecten retourneert voor importeren, moet u paging ondersteunen. De connector maakt een aangepaste gegevenseigenschap beschikbaar die u kunt gebruiken om een watermerk op te slaan, zodat telkens wanneer het script voor het importeren van gegevens wordt aangeroepen, het importeren van objecten hervat waar het was gebleven.

Het importgegevensscript ontvangt de volgende parameters van de connector:

Het importgegevensscript moet een object List[CSEntryChange] naar de pijplijn schrijven. Deze verzameling bestaat uit CSEntryChange-kenmerken die elk object vertegenwoordigen dat wordt geïmporteerd. Tijdens een volledige importbewerking moet deze verzameling een volledige set CSEntryChange-objecten hebben met alle kenmerken voor elk object. Tijdens een Delta Import moet het CSEntryChange-object ofwel de deltas op kenmerkniveau voor elk te importeren object bevatten, of een volledige representatie van de objecten die zijn veranderd in vervangingsmodus.

importbewerking beëindigen
Aan het einde van de importuitvoering wordt het script End Import uitgevoerd. Dit script moet alle opschoontaken uitvoeren die nodig zijn (bijvoorbeeld verbindingen met systemen sluiten en reageren op fouten).

Het eindimportscript ontvangt de volgende parameters van de connector:

Het script moet één CloseImportConnectionResults-object retourneren aan de pijplijn, bijvoorbeeld: Write-Output (New-Object Microsoft.MetadirectoryServices.CloseImportConnectionResults)

Exporteren

Identiek aan de importarchitectuur van de connector, connectors die export ondersteunen, moeten drie scripts implementeren.

Exporteren starten
Het beginscript voor export wordt uitgevoerd aan het begin van een exportstap. Tijdens deze stap kunt u een verbinding maken met het bronsysteem en eventuele voorbereidende stappen uitvoeren voordat u gegevens naar het verbonden systeem exporteert.

Het exportscript begin ontvangt de volgende parameters van de connector:

Het script mag geen uitvoer retourneren naar de pijplijn.

Gegevens exporteren
De synchronisatieservice roept het exportgegevensscript zo vaak aan als nodig is om alle in behandeling zijnde exports te verwerken. Als de connectorruimte meer exportbewerkingen in behandeling heeft dan het paginaformaat van de connector, kan het exportgegevensscript meerdere keren en mogelijk meerdere keren voor hetzelfde object worden aangeroepen.

Het exportgegevensscript ontvangt de volgende parameters van de connector:

Het exportgegevensscript moet een PutExportEntriesResults-object retourneren aan de pijplijn. Dit object hoeft geen resultaatinformatie op te nemen voor elke geëxporteerde connector, tenzij er een fout of wijziging in het ankerkenmerk optreedt. Bijvoorbeeld, om een PutExportEntriesResults-object naar de pijplijn te retourneren: Write-Output (New-Object Microsoft.MetadirectoryServices.PutExportEntriesResults)

Export beëindigen
Aan het einde van de exportuitvoering moet het script End Export worden uitgevoerd. Dit script moet alle opschoontaken uitvoeren die nodig zijn (bijvoorbeeld verbindingen met systemen sluiten en reageren op fouten).

Het eindexportscript ontvangt de volgende parameters van de connector:

Het script mag geen uitvoer retourneren naar de pijplijn.

Wachtwoordsynchronisatie

Windows PowerShell-connectors kunnen worden gebruikt als doel voor wachtwoordwijzigingen/-resets.

Het wachtwoordscript ontvangt de volgende parameters van de connector:

Het wachtwoordscript retourneert naar verwachting geen resultaten naar de Windows PowerShell-pijplijn. Als er een fout optreedt in het wachtwoordscript, moet het script een van de volgende uitzonderingen genereren om de synchronisatieservice te informeren over het probleem:

• PasswordPolicyViolationException – Opgeworpen als het wachtwoord niet voldoet aan het wachtwoordbeleid in het verbonden systeem.
• PasswordIllFormedException – Opgeworpen als het wachtwoord niet acceptabel is voor het aangesloten systeem.
• PasswordExtension – Opgetreden voor alle andere fouten in het wachtwoordscript.

Voorbeeldverbindstukken

Zie Windows PowerShell Connector Sample Connector Collectionvoor een volledig overzicht van de beschikbare voorbeeldconnectors.

Andere opmerkingen

Aanvullende configuratie voor imitatie

Geef de geïmiteerde gebruiker de volgende machtigingen op de Synchronisatie Service-server:

Leestoegang tot de volgende registersleutels:

• HKEY_USERS\[SynchronizationServiceServiceAccountSID]\Software\Microsoft\PowerShell
• HKEY_USERS\[SynchronizationServiceServiceAccountSID]\Omgeving

Voer de volgende PowerShell-opdrachten uit om de beveiligings-id (SID) van het Service-account voor synchronisatieservice te bepalen:

$account = New-Object System.Security.Principal.NTAccount "<domain>\<username>"
$account.Translate([System.Security.Principal.SecurityIdentifier]).Value

Leestoegang tot de volgende mappen van het bestandssysteem:

• %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}

Vervang de naam van de Windows PowerShell-connector door de tijdelijke aanduiding {ConnectorName}.

Problemen oplossen

• Zie de ETW-tracering inschakelen voor connectorsvoor meer informatie over het inschakelen van logboekregistratie om problemen met de connector op te lossen.