Teknisk referens för Windows PowerShell Connector
I den här artikeln beskrivs Windows PowerShell Connector. Artikeln gäller för följande produkter:
- Microsoft Identity Manager 2016 (MIM2016)
För MIM2016 är anslutningsappen tillgänglig som en nedladdning från Microsoft Download Center.
Med PowerShell Connector kan du integrera synkroniseringstjänsten med externa system som erbjuder Windows PowerShell-baserade API:er. Anslutningsappen ger en brygga mellan funktionerna i det anropsbaserade ramverket för utökningsbar anslutningshanteringsagent 2 (ECMA2) och Windows PowerShell. Mer information om ECMA-ramverket finns i Extensible Connectivity 2.2 Management Agent Reference.
Innan du använder anslutningsappen kontrollerar du att du har följande på synkroniseringsservern:
- Microsoft .NET 4.6.2 Framework eller senare
- Windows PowerShell 2.0, 3.0 eller 4.0
Körningsprincipen på synkroniseringstjänstens server måste konfigureras så att anslutningsappen kan köra Windows PowerShell-skript. Om inte skripten som anslutningsappen kör är digitalt signerade konfigurerar du körningsprincipen genom att köra det här kommandot:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned
För att distribuera den här anslutningsappen krävs ett eller flera PowerShell-skript. Vissa Microsoft-produkter kan tillhandahålla skript för användning med den här connectorn, och supportuttalandet för dessa skript skulle tillhandahållas av den produkten. Om du utvecklar egna skript för användning med den här anslutningsappen måste du känna till api:et Extensible Connectivity Management Agent för att utveckla och underhålla skripten. Om du integrerar med tredjepartssystem med dina egna skript i en produktionsmiljö rekommenderar vi att du arbetar med tredjepartsleverantören eller en distributionspartner för att få hjälp, vägledning och support för den här integreringen.
Om du vill skapa en Windows PowerShell-anslutning i synkroniseringstjänsten måste du ange en serie Windows PowerShell-skript som kör de steg som begärs av synkroniseringstjänsten. Beroende på vilken datakälla du ansluter till och vilka funktioner du behöver varierar de skript som du måste implementera. Det här avsnittet beskriver vart och ett av de skript som kan implementeras och när de krävs.
Windows PowerShell-anslutningsappen är utformad för att lagra vart och ett av skripten i databasen för synkroniseringstjänsten. Även om det är möjligt att köra skript som lagras i filsystemet är det enklare att infoga brödtexten för varje skript direkt i anslutningsappens konfiguration.
Om du vill skapa en PowerShell-anslutning i Synchronization Service, välj Management Agent och Skapa. Välj PowerShell (Microsoft) Connector.
Ange konfigurationsparametrar för anslutning till ett fjärrsystem. Dessa värden lagras säkert av synkroniseringstjänsten och görs tillgängliga för dina Windows PowerShell-skript när anslutningsappen körs.
sv-SE: 
Du kan konfigurera följande anslutningsparametrar:
Anslutning
| Parameter | Standardvärde | Avsikt |
|---|---|---|
| Server | <Tomt> | Servernamn som anslutningsappen ska ansluta till. |
| Domän | <Tomt> | Domän för autentiseringsuppgifterna som ska lagras för användning när anslutningsappen körs. |
| Användare | <Tomt> | Användarnamn för autentiseringsuppgifterna som ska lagras för användning när anslutningsappen körs. |
| Lösenord | <Tomt> | Lösenordet för autentiseringsuppgifterna som ska lagras för användning när anslutningsappen körs. |
| Personifiera anslutningskonto | Falsk | När det är sant kör synkroniseringstjänsten Windows PowerShell-skripten i kontexten för de angivna autentiseringsuppgifterna. När det är möjligt rekommenderar vi att parametern $Credentials skickas till och används av varje skript i stället för imitering. Mer information om ytterligare behörigheter som krävs för att använda det här alternativet finns i Ytterligare konfiguration för personifiering. |
| Läs in användarprofil vid imitation | Falsk | Instruerar Windows att läsa in användarprofilen för anslutningsappens autentiseringsuppgifter under personifieringen. Om den personifierade användaren har en nätverksprofil läser inte anslutningsappen in roamingprofilen. Mer information om ytterligare behörigheter som krävs för att använda den här parametern finns i Ytterligare konfiguration för personifiering. |
| Inloggningstyp vid personifiering | Ingen | Typ av inloggning vid impersonation. Mer information finns i dwLogonType-dokumentationen. |
| Endast signerade skript | Falsk | Om det är sant verifierar Windows PowerShell-anslutningsappen att varje skript har en giltig digital signatur. Om det är falskt kontrollerar du att synkroniseringstjänstserverns Windows PowerShell-körningsprincip är RemoteSigned eller Unrestricted. |
Gemensam Modul
Med anslutningsappen kan du lagra en delad Windows PowerShell-modul i konfigurationen. När anslutningsappen kör ett skript extraheras Windows PowerShell-modulen till filsystemet så att den kan importeras av varje skript.
För import-, export- och lösenordssynkroniseringsskript extraheras den gemensamma modulen till anslutningsappens MAData-mapp. För skript för schema-, validerings-, hierarki- och partitionsidentifiering extraheras den gemensamma modulen till mappen %TEMP%. I båda fallen namnges det extraherade Common Module-skriptet enligt inställningen för Common Module Script Name.
Om du vill läsa in en modul med namnet FIMPowerShellConnectorModule.psm1 från mappen MAData använder du följande instruktion: Import-Module (Join-Path -Path [Microsoft.MetadirectoryServices.MAUtils]::MAFolder -ChildPath "FIMPowerShellConnectorModule.psm1")
Om du vill läsa in en modul med namnet FIMPowerShellConnectorModule.psm1 från mappen %TEMP% använder du följande instruktion: Import-Module (Join-Path -Path $env:TEMP -ChildPath "FIMPowerShellConnectorModule.psm1")
Parameterverifiering
Valideringsskriptet är ett valfritt Windows PowerShell-skript som kan användas för att säkerställa att konfigurationsparametrarna för anslutningsappen som tillhandahålls av administratören är giltiga. Validering av server, autentiseringsuppgifter för anslutning och anslutningsparametrar är vanliga användningar av valideringsskriptet. Verifieringsskriptet anropas när följande flikar och dialogrutor har ändrats:
- Uppkoppling
- Globala parametrar
- Partitionskonfiguration
Valideringsskriptet tar emot följande parametrar från anslutningsappen:
| Namn | Datatyp | Beskrivning |
|---|---|---|
| Konfigurationsparametersida | ConfigParameterPage | Konfigurationsfliken eller dialogrutan som utlöste valideringsbegäran. |
| Konfigurationsparametrar | KeyedCollection [string, ConfigParameter] | Tabell med konfigurationsparametrar för anslutningsappen. |
| Behörighet | PSCredential | Innehåller eventuella autentiseringsuppgifter som angetts av administratören på fliken Anslutning. |
Valideringsskriptet ska returnera ett enda ParameterValidationResult-objekt till pipelinen.
SchéUpptäckt
Schemadetekteringsskriptet är obligatoriskt. Det här skriptet returnerar de objekttyper, attribut och attributbegränsningar som synkroniseringstjänsten använder när du konfigurerar attributflödesregler. Skriptet schemaidentifiering körs när anslutningsappen skapas och fyller i anslutningsappens schema. Den används också av åtgärden Uppdatera schema i Synkroniseringstjänsthanteraren.
Skriptet för schemaidentifiering tar emot följande parametrar från anslutningsappen:
| Namn | Datatyp | Beskrivning |
|---|---|---|
| Konfigurationsparametrar | KeyedCollection [string, ConfigParameter] | Tabell med konfigurationsparametrar för anslutningsappen. |
| Behörighet | PSCredential | Innehåller eventuella autentiseringsuppgifter som angetts av administratören på fliken Anslutning. |
Skriptet måste returnera ett enda Schema-objekt till pipelinen. Schemaobjektet består av SchemaType objekt som representerar objekttyper (till exempel användare och grupper). SchemaType-objektet innehåller en samling SchemaAttribute objekt som representerar attributen (till exempel förnamn, efternamn och postadress) av typen.
ytterligare parametrar
Förutom standardkonfigurationsinställningarna kan du definiera ytterligare anpassade konfigurationsinställningar som är specifika för instansen av anslutningsappen. Dessa parametrar kan anges på nivåerna för kopplare, partition eller körningssteg och nås från det relevanta Windows PowerShell-skriptet. Anpassade konfigurationsinställningar kan lagras i synkroniseringstjänstens databas i oformaterat textformat eller så kan de vara krypterade. Synkroniseringstjänsten krypterar och dekrypterar automatiskt säkra konfigurationsinställningar vid behov.
Om du vill ange anpassade konfigurationsinställningar separerar du namnet på varje parameter med kommatecknet ( , ).
För att få åtkomst till anpassade konfigurationsinställningar från ett skript måste du suffixa namnet med understrecket ( _ ) och parameterns omfång (Global, Partition eller RunStep). Om du till exempel vill komma åt parametern Global FileName använder du det här kodfragmentet: $ConfigurationParameters["FileName_Global"].Value
Fliken Funktioner i Hanteringsagentdesignern definierar anslutningsappens beteende och funktioner. Det går inte att ändra de val som gjorts på den här fliken när anslutningsappen har skapats. I den här tabellen visas kapacitetsinställningarna.
| Kapacitet | Beskrivning |
|---|---|
| unikt namnformat | Anger om anslutningen stöder distingerade namn och i så fall vilken stil. |
| Exporttyp | Avgör vilken typ av objekt som visas för exportskriptet. |
| datanormalisering | Instruerar synkroniseringstjänsten att normalisera fästpunktsattribut innan de tillhandahålls till skript. |
| objektbekräftelse | Konfigurerar det väntande importbeteendet i synkroniseringstjänsten. |
| Använda DN som fästpunkt | Om formatmallen Unikt namn är inställt på LDAP är fästpunktsattributet för anslutningsutrymmet också det unika namnet. |
| Samtidiga operationer av flera kopplingar | När det är markerat kan flera Windows PowerShell-anslutningar köras samtidigt. |
| Partitioner | När den är markerad stöder anslutningen flera partitioner och upptäckt av partitioner. |
| Hierarki | När den är markerad stöder anslutningen en hierarkisk struktur i LDAP-liknande format. |
| Aktivera import | När den är markerad importerar anslutningsappen data via importskript. |
| Aktivera deltaimport | När den är markerad kan anslutningsappen begära delta från importskripten. |
| Aktivera exportfunktion | När den är markerad exporterar anslutningsappen data via exportskript. |
| Aktivera fullständig export | När kontrollen är markerad stöder exportskripten export av hela anslutningsutrymmet. Om du vill använda det här alternativet måste även Aktivera export kontrolleras. |
| Inga referensvärden i första exportpasset | När det är markerat exporteras referensattribut i ett andra exportpass. |
| Aktivera objektnamnbyte | När den är markerad kan distingerade namn ändras. |
| Ta bort-lägg till som ersättning | När kontrollrutan är markerad exporteras åtgärderna radera-lägg till som en enda ersättning. |
| Aktivera lösenordsåtgärder | När det är markerat stöds skript för lösenordssynkronisering. |
| Aktivera exportlösenord i första passet | När det är markerat exporteras lösenord som angetts under etableringen när objektet skapas. |
På fliken Globala parametrar i Hanteringsagentdesignern kan du konfigurera De Windows PowerShell-skript som körs av anslutningsappen. Du kan också konfigurera globala värden för anpassade konfigurationsinställningar som definierats på fliken Anslutning.
Partition Discovery
En partition är ett separat namnområde i ett delat schema. I Active Directory är till exempel varje domän en partition i en skog. En partition är den logiska gruppering för import- och exportåtgärder. Import och export har partition som kontext och alla åtgärder sker i den här kontexten. Partitioner ska representera en hierarki i LDAP. Det unika namnet på en partition används vid import för att verifiera att alla returnerade objekt ligger inom omfånget för en partition. Det distingerade namnet på partitionen används också under tillhandahållandet från metaversen till kopplingsutrymmet för att avgöra vilken partition ett objekt ska associeras med under exporten.
Skriptet för partitionsidentifiering tar emot följande parametrar från anslutningsappen:
| Namn | Datatyp | Beskrivning |
|---|---|---|
| Konfigurationsparametrar | KeyedCollection[string, ConfigParameter] | Tabell med konfigurationsparametrar för anslutningsappen. |
| Behörighet | PSCredential | Innehåller eventuella autentiseringsuppgifter som angetts av administratören på fliken Anslutning. |
Skriptet måste returnera antingen ett enda Partition-objekt eller en lista[T] över partitionsobjekt till pipelinen.
Hierarkiupptäckning
Hierarkiidentifieringsskriptet används endast när funktionen Distinguished Name Style är LDAP. Skriptet används för att du ska kunna bläddra och välja en uppsättning containrar som anses vara inom eller utanför omfånget för import- och exportåtgärder. Skriptet ska endast tillhandahålla en lista över noder som är direkta underordnade till rotnoden som levereras till skriptet.
Hierarkiidentifieringsskriptet tar emot följande parametrar från anslutningsappen:
| Namn | Datatyp | Beskrivning |
|---|---|---|
| Konfigurationsparametrar | KeyedCollection[sträng, ConfigParameter] | Tabell med konfigurationsparametrar för anslutningsappen. |
| Behörighet | PSCredential | Innehåller eventuella autentiseringsuppgifter som angetts av administratören på fliken Anslutning. |
| ParentNode | HierarchyNode | Rotnoden i hierarkin där skriptet ska returnera direkta underordnade objekt. |
Skriptet måste returnera ett enskilt underordnat HierarchyNode-objekt eller en lista[T] över underordnade HierarchyNode-objekt till pipelinen.
Anslutningsappar som stöder importåtgärder måste implementera tre skript.
Börja importera
Startimportskriptet körs i början av ett importkörningssteg. Under det här steget kan du upprätta en anslutning till källsystemet och utföra förberedande steg innan du importerar data från det anslutna systemet.
Startimportskriptet tar emot följande parametrar från anslutningsappen:
| Namn | Datatyp | Beskrivning |
|---|---|---|
| Konfigurationsparametrar | KeyedCollection[sträng, ConfigParameter] | Tabell med konfigurationsparametrar för anslutningsappen. |
| Behörighet | PSCredential | Innehåller eventuella autentiseringsuppgifter som angetts av administratören på fliken Anslutning. |
| OpenImportConnectionRunStep | OpenImportConnectionRunStep | Informerar skriptet om typen av importkörning (delta eller fullständig), partition, hierarki, vattenstämpel och förväntad sidstorlek. |
| Typer | Skema | Schema för det anslutningsutrymme som importeras. |
Skriptet måste returnera ett enda OpenImportConnectionResults-objekt till pipelinen, till exempel: Write-Output (New-Object Microsoft.MetadirectoryServices.OpenImportConnectionResults)
Importera data
Importdataskriptet anropas av anslutningsappen tills skriptet anger att det inte finns några fler data att importera. Windows PowerShell-anslutningen har en sidstorlek på 9 999 objekt. Om skriptet returnerar fler än 9 999 objekt för import måste du ha stöd för sidindelning. Anslutningsappen exponerar en anpassad dataegenskap som du kan använda för att lagra en vattenstämpel så att skriptet fortsätter importera objekt där det slutade varje gång importdataskriptet anropas.
Importdataskriptet tar emot följande parametrar från anslutningsappen:
| Namn | Datatyp | Beskrivning |
|---|---|---|
| Konfigurationsparametrar | KeyedCollection[string, ConfigParameter] | Tabell med konfigurationsparametrar för anslutningsappen. |
| Behörighet | PSCredential | Innehåller eventuella autentiseringsuppgifter som angetts av administratören på fliken Anslutning. |
| GetImportEntriesRunStep | ImportRunStep | Innehåller vattenstämpeln (CustomData) som kan användas vid sidimport och deltaimport. |
| OpenImportConnectionRunStep | OpenImportConnectionRunStep | Informerar skriptet om typen av importkörning (delta eller fullständig), partition, hierarki, vattenstämpel och förväntad sidstorlek. |
| Typer | Skema | Schema för det anslutningsutrymme som importeras. |
Importdataskriptet måste skriva ett listobjekt[CSEntryChange] till pipelinen. Den här samlingen består av CSEntryChange-attribut som representerar varje objekt som importeras. Under en fullständig importkörning bör den här samlingen ha en fullständig uppsättning CSEntryChange-objekt som har alla attribut för varje objekt. Under en deltaimport ska CSEntryChange-objektet antingen innehålla attributnivådelta för varje objekt som ska importeras eller en fullständig representation av de objekt som har ändrats (Ersätt läge).
Avsluta import
När importkörningen är slut körs skriptet Slutimport. Det här skriptet bör utföra alla nödvändiga rensningsuppgifter (till exempel stänga anslutningar till system och svara på fel).
Skriptet för slutimport tar emot följande parametrar från anslutningsappen:
| Namn | Datatyp | Beskrivning |
|---|---|---|
| Konfigurationsparametrar | KeyedCollection[string, ConfigParameter] | Tabell med konfigurationsparametrar för anslutningsappen. |
| Behörighet | PSCredential | Innehåller eventuella autentiseringsuppgifter som angetts av administratören på fliken Anslutning. |
| OpenImportConnectionRunStep | OpenImportConnectionRunStep | Informerar skriptet om typen av importkörning (delta eller fullständig), partition, hierarki, vattenstämpel och förväntad sidstorlek. |
| StängImportAnslutningKörsteg | CloseImportConnectionRunStep | Informerar skriptet om orsaken till att importen avslutades. |
Skriptet måste returnera ett enda CloseImportConnectionResults-objekt till pipelinen, till exempel: Write-Output (New-Object Microsoft.MetadirectoryServices.CloseImportConnectionResults)
Anslutningsprogram som har stöd för Export måste implementera tre skript som är identiska med anslutningsappens importarkitektur.
Börja exportera
Startexportskriptet körs i början av ett exportkörningssteg. Under det här steget kan du upprätta en anslutning till källsystemet och utföra eventuella förberedande steg innan du exporterar data till det anslutna systemet.
Startexportskriptet tar emot följande parametrar från anslutningsappen:
| Namn | Datatyp | Beskrivning |
|---|---|---|
| Konfigurationsparametrar | NyckladSamling[string, ConfigParameter] | Tabell med konfigurationsparametrar för anslutningsappen. |
| Behörighet | PSCredential | Innehåller eventuella autentiseringsuppgifter som angetts av administratören på fliken Anslutning. |
| OpenExportConnectionRunStep | ÖppnaExportanslutningsKörsteg | Informerar skriptet om typen av exportkörning (delta eller fullständig), partition, hierarki och förväntad sidstorlek. |
| Typer | Skema | Schema för det anslutningsutrymme som exporteras. |
Skriptet ska inte returnera några utdata till pipelinen.
Exportera data
Synkroniseringstjänsten anropar skriptet Exportera data så många gånger som krävs för att bearbeta alla väntande exporter. Om kontaktytan har fler väntande exporter än kontaktens sidstorlek kan exportdataskriptet anropas flera gånger och eventuellt flera gånger för samma objekt.
Exportdataskriptet tar emot följande parametrar från anslutningsappen:
| Namn | Datatyp | Beskrivning |
|---|---|---|
| Konfigurationsparametrar | KeyedCollection[string, ConfigParameter] | Tabell med konfigurationsparametrar för anslutningsappen. |
| Behörighet | PSCredential | Innehåller eventuella autentiseringsuppgifter som angetts av administratören på fliken Anslutning. |
| CSEntries | IListCSEntryChange | Lista över alla anslutningsobjekt med väntande exporter som ska bearbetas under det här passet. |
| OpenExportConnectionRunStep | OpenExportConnectionRunStep | Informerar skriptet om typen av exportkörning (delta eller fullständig), partition, hierarki och förväntad sidstorlek. |
| Typer | Skema | Schema för det anslutningsutrymme som exporteras. |
Exportdataskriptet måste returnera ett PutExportEntriesResults-objekt till pipelinen. Det här objektet behöver inte innehålla resultatinformation för varje exporterad anslutningsapp om inte ett fel eller en ändring av fästpunktsattributet inträffar. Om du till exempel vill returnera ett PutExportEntriesResults-objekt till pipelinen: Write-Output (New-Object Microsoft.MetadirectoryServices.PutExportEntriesResults)
Avsluta export
Vid exportkörningens slut körs skriptet End Export. Det här skriptet bör utföra alla nödvändiga rensningsuppgifter (till exempel stänga anslutningar till system och svara på fel).
Slutexportskriptet tar emot följande parametrar från anslutningsappen:
| Namn | Datatyp | Beskrivning |
|---|---|---|
| Konfigurationsparametrar | KeyedCollection[string, ConfigParameter] | Tabell med konfigurationsparametrar för anslutningsappen. |
| Behörighet | PSCredential | Innehåller eventuella autentiseringsuppgifter som angetts av administratören på fliken Anslutning. |
| OpenExportConnectionRunStep | OpenExportConnectionRunStep | Informerar skriptet om typen av exportkörning (delta eller fullständig), partition, hierarki och förväntad sidstorlek. |
| AvslutaExportAnslutningKörSteg | CloseExportConnectionRunStep | Informerar skriptet om orsaken till att exporten avslutades. |
Skriptet ska inte returnera några utdata till pipelinen.
Windows PowerShell-anslutningsappar kan användas som mål för lösenordsändringar/återställningar.
Lösenordsskriptet tar emot följande parametrar från anslutningsappen:
| Namn | Datatyp | Beskrivning |
|---|---|---|
| Konfigurationsparametrar | KeyedCollection[string, ConfigParameter] | Tabell med konfigurationsparametrar för anslutningsappen. |
| Behörighet | PSCredential | Innehåller eventuella autentiseringsuppgifter som angetts av administratören på fliken Anslutning. |
| Avdelning | Avdelning | Katalogpartition som CSEntry finns i. |
| CSEntry | CSEntry | Kopplingsutrymmespost för objektet som tar emot en lösenordsändring eller återställning. |
| Operationstyp | Sträng | Anger om åtgärden är en återställning (SetPassword) eller en ändring (ChangePassword). |
| Lösenordsalternativ | Lösenordsalternativ | Flaggor som anger det avsedda beteendet för lösenordsåterställning. Den här parametern är endast tillgänglig om OperationType är SetPassword. |
| GamlaLösenordet | Sträng | Fyllt med objektets gamla lösenord för lösenordsändringar. Den här parametern är endast tillgänglig om OperationType är ChangePassword. |
| Nytt Lösenord | Sträng | Fyllt med objektets nya lösenord som skriptet ska ange. |
Lösenordsskriptet förväntas inte returnera några resultat till Windows PowerShell-pipelinen. Om ett fel uppstår i lösenordsskriptet bör skriptet utlösa något av följande undantag för att informera synkroniseringstjänsten om problemet:
- PasswordPolicyViolationException – Genereras om lösenordet inte uppfyller lösenordsprincipen i det anslutna systemet.
- PasswordIllFormedException – Genereras om lösenordet inte är acceptabelt för det anslutna systemet.
- PasswordExtension – Används för alla andra fel i lösenordsskriptet.
En fullständig översikt över tillgängliga exempelanslutningar finns i Windows PowerShell Connector Sample Connector Collection.
Bevilja den användare som personifieras följande behörigheter på servern för synkroniseringstjänsten:
Läsbehörighet till följande registernycklar:
- HKEY_USERS\[SynchronizationServiceServiceAccountSID]\Software\Microsoft\PowerShell
- HKEY_USERS\[SynchronizationServiceServiceAccountSID]\Miljö
Kör följande PowerShell-kommandon för att fastställa säkerhetsidentifieraren (SID) för tjänstkontot för synkroniseringstjänsten:
$account = New-Object System.Security.Principal.NTAccount "<domain>\<username>"
$account.Translate([System.Security.Principal.SecurityIdentifier]).Value
Läs åtkomst till följande filsystemmappar:
- %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}
Ersätt platshållaren {ConnectorName} med namnet på Windows PowerShell-anslutningsappen.
- Information om hur du aktiverar loggning för att felsöka anslutningen finns i Så här aktiverar du ETW-spårning för anslutningar.