Windows PowerShell-anslutning för teknisk referens
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.
Översikt över PowerShell-anslutningsappen
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 ecma2-ramverket (Extensible Connectivity Management Agent 2) och Windows PowerShell. Mer information om ECMA-ramverket finns i Referens för extensible Connectivity 2.2 Management Agent.
Förutsättningar
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
Distribution av den här anslutningsappen kräver ett eller flera PowerShell-skript. Vissa Microsoft-produkter kan tillhandahålla skript för användning med den här anslutningsappen, och supportutdraget för dessa skript tillhandahålls 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 dessa skript. Om du integrerar med tredjepartssystem med dina egna skript i en produktionsmiljö rekommenderar vi att du samarbetar med tredjepartsleverantören eller en distributionspartner för att få hjälp, vägledning och support för den här integreringen.
Skapa en ny anslutningsapp
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. I det här avsnittet beskrivs vart och ett av de skript som kan implementeras och när de behövs.
Anslutningsappen Windows PowerShell ä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-anslutningsapp går du till Synkroniseringstjänst och väljer Hanteringsagent och Skapa. Välj PowerShell-anslutningsprogrammet (Microsoft).
Anslutning
Ange konfigurationsparametrar för att ansluta till ett fjärrsystem. Dessa värden lagras på ett säkert sätt av synkroniseringstjänsten och görs tillgängliga för dina Windows PowerShell skript när anslutningsappen körs.
Du kan konfigurera följande anslutningsparametrar:
Anslutningsmöjligheter
| Parameter | Standardvärde | Syfte |
|---|---|---|
| Server | <Tom> | Servernamn som anslutningsappen ska ansluta till. |
| Domain | <Tom> | Domän för autentiseringsuppgifterna som ska lagras för användning när anslutningsappen körs. |
| Användare | <Tom> | Användarnamn för autentiseringsuppgifterna som ska lagras för användning när anslutningsappen körs. |
| Lösenord | <Tom> | Lösenord för autentiseringsuppgifterna som ska lagras för användning när anslutningsappen körs. |
| Personifiera anslutningskonto | Falskt | När det är sant kör synkroniseringstjänsten Windows PowerShell skript i kontexten för de angivna autentiseringsuppgifterna. När det är möjligt rekommenderar vi att parametern $Credentials skickas till varje skript i stället för personifiering. 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 personifiering | Falskt | Instruerar Windows att läsa in användarprofilen för anslutningsappens autentiseringsuppgifter under personifieringen. Om den personifierade användaren har en nätverksväxlingsprofil 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 | Inloggningstyp under personifiering. Mer information finns i dwLogonType-dokumentationen . |
| Endast signerade skript | Falskt | Om det är sant verifierar Windows PowerShell-anslutningsappen att varje skript har en giltig digital signatur. Om det är falskt kontrollerar du att synkroniseringstjänstens 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 skript för import, export och lösenordssynkronisering extraheras den gemensamma modulen till anslutningsappens MAData-mapp. För skript för identifiering av schema, validering, hierarki och partition extraheras den gemensamma modulen till mappen %TEMP%. I båda fallen namnges det extraherade Common Module-skriptet enligt inställningen Common Module Script Name (Gemensamt modulskriptnamn).
Om du vill läsa in en modul med namnet FIMPowerShellConnectorModule.psm1 från MAData-mappen 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. Valideringsskriptet anropas efter att följande flikar och dialogrutor har ändrats:
- Anslutning
- Globala parametrar
- Partitionskonfiguration
Valideringsskriptet tar emot följande parametrar från anslutningsappen:
| Name | Datatyp | Beskrivning |
|---|---|---|
| ConfigParameterPage | ConfigParameterPage | Konfigurationsfliken eller dialogrutan som utlöste valideringsbegäran. |
| ConfigParameters | KeyedCollection [sträng, ConfigParameter] | Tabell med konfigurationsparametrar för anslutningsappen. |
| Merit | PSCredential | Innehåller alla autentiseringsuppgifter som administratören anger på fliken Anslutning. |
Valideringsskriptet ska returnera ett enda ParameterValidationResult-objekt till pipelinen.
Schemaidentifiering
Skriptet schemaidentifiering ä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 Service Manager.
Skriptet för schemaidentifiering tar emot följande parametrar från anslutningsappen:
| Name | Datatyp | Beskrivning |
|---|---|---|
| ConfigParameters | KeyedCollection [sträng, ConfigParameter] | Tabell med konfigurationsparametrar för anslutningsappen. |
| Merit | PSCredential | Innehåller alla autentiseringsuppgifter som administratören anger 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). Objektet SchemaType 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 anslutningsappen, partitionen eller körningsstegen och nås från relevant Windows PowerShell skript. 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 ett kommatecken ( , ).
För att få åtkomst till anpassade konfigurationsinställningar från ett skript måste du suffixa namnet med ett understreck ( _ ) och omfånget för parametern (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
Funktioner
Fliken Funktioner i hanteringsagenten Designer definierar anslutningsappens beteende och funktionalitet. Det går inte att ändra markeringen på den här fliken när anslutningsappen har skapats. I den här tabellen visas kapacitetsinställningarna.
| Funktion | Beskrivning |
|---|---|
| Formatmall för unikt namn | Anger om anslutningsappen stöder unika 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 väntande importbeteende i synkroniseringstjänsten. |
| Använda DN som fästpunkt | Om formatet För unikt namn är inställt på LDAP är fästpunktsattributet för kopplingsutrymmet också det unika namnet. |
| Samtidiga åtgärder för flera anslutningsappar | När kontrollen är markerad kan flera Windows PowerShell anslutningsappar köras samtidigt. |
| Partitioner | När den är markerad stöder anslutningsappen flera partitioner och partitionsidentifiering. |
| Hierarki | När den är markerad stöder anslutningsappen en hierarkisk struktur i LDAP-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 export | När den är markerad exporterar anslutningsappen data via exportskript. |
| Aktivera fullständig export | När det är markerat stöder exportskripten export av hela anslutningsutrymmet. Om du vill använda det här alternativet måste aktivera export också markeras. |
| Inga referensvärden i första exportpasset | När det är markerat exporteras referensattribut i ett andra exportpass. |
| Aktivera objektbyte | När det är markerat kan unika namn ändras. |
| Delete-Add som ersätt | När åtgärden delete-add är markerad exporteras de 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. |
Globala parametrar
På fliken Globala parametrar i Designer för hanteringsagenten 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.
Partitionsidentifiering
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. Partitionens unika namn används också under etableringen från metaversumet till anslutningsplatsen för att fastställa partitionen som ett objekt ska associeras med under exporten.
Skriptet för partitionsidentifiering tar emot följande parametrar från anslutningsappen:
| Name | Datatyp | Beskrivning |
|---|---|---|
| ConfigParameters | KeyedCollection[string, ConfigParameter] | Tabell med konfigurationsparametrar för anslutningsappen. |
| Merit | PSCredential | Innehåller alla autentiseringsuppgifter som administratören anger på fliken Anslutning. |
Skriptet måste returnera antingen ett enskilt partitionsobjekt eller en lista[T] över partitionsobjekt till pipelinen.
Hierarkiidentifiering
Hierarkiidentifieringsskriptet används bara när funktionen Förskild namnstil ä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 bör endast innehålla en lista över noder som är direkt underordnade till den rotnod som tillhandahålls till skriptet.
Skriptet för hierarkiidentifiering tar emot följande parametrar från anslutningsappen:
| Name | Datatyp | Beskrivning |
|---|---|---|
| ConfigParameters | KeyedCollection[string, ConfigParameter] | Tabell med konfigurationsparametrar för anslutningsappen. |
| Merit | PSCredential | Innehåller alla autentiseringsuppgifter som administratören anger på fliken Anslutning. |
| ParentNode | Hierarkinod | Rotnoden i hierarkin under vilken skriptet ska returnera direkta underordnade objekt. |
Skriptet måste returnera antingen ett enskilt underordnat HierarchyNode-objekt eller en lista[T] över underordnade HierarchyNode-objekt till pipelinen.
Importera
Anslutningsappar som stöder importåtgärder måste implementera tre skript.
Börja importera
Skriptet begin import 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:
| Name | Datatyp | Beskrivning |
|---|---|---|
| ConfigParameters | KeyedCollection[string, ConfigParameter] | Tabell med konfigurationsparametrar för anslutningsappen. |
| Merit | PSCredential | Innehåller alla autentiseringsuppgifter som administratören anger 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 | Schema | 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. Den Windows PowerShell-anslutningsappen 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 importerar objekt där det slutade varje gång importdataskriptet anropas.
Importdataskriptet tar emot följande parametrar från anslutningsappen:
| Name | Datatyp | Beskrivning |
|---|---|---|
| ConfigParameters | KeyedCollection[string, ConfigParameter] | Tabell med konfigurationsparametrar för anslutningsappen. |
| Merit | PSCredential | Innehåller alla autentiseringsuppgifter som administratören anger på fliken Anslutning. |
| GetImportEntriesRunStep | ImportRunStep | Innehåller vattenstämpeln (CustomData) som kan användas vid sidsidiga importer och deltaimporter. |
| OpenImportConnectionRunStep | OpenImportConnectionRunStep | Informerar skriptet om typen av importkörning (delta eller fullständig), partition, hierarki, vattenstämpel och förväntad sidstorlek. |
| Typer | Schema | Schema för det anslutningsutrymme som importeras. |
Importdataskriptet måste skriva ett List[CSEntryChange]-objekt 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ådeltat för varje objekt som ska importeras eller en fullständig representation av de objekt som har ändrats (Ersätt läge).
Slutimport
I slutet av importkörningen körs skriptet End Import ( Slutimport). Det här skriptet bör utföra alla rensningsuppgifter som krävs (till exempel stänga anslutningar till system och svara på fel).
Skriptet för slutimport tar emot följande parametrar från anslutningsappen:
| Name | Datatyp | Beskrivning |
|---|---|---|
| ConfigParameters | KeyedCollection[string, ConfigParameter] | Tabell med konfigurationsparametrar för anslutningsappen. |
| Merit | PSCredential | Innehåller alla autentiseringsuppgifter som administratören anger 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. |
| CloseImportConnectionRunStep | 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)
Exportera
Anslutningsprogram som stöder export är identiska med anslutningsappens importarkitektur och måste implementera tre skript.
Påbörja export
Skriptet begin export 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.
Skriptet begin export tar emot följande parametrar från anslutningsappen:
| Name | Datatyp | Beskrivning |
|---|---|---|
| ConfigParameters | KeyedCollection[string, ConfigParameter] | Tabell med konfigurationsparametrar för anslutningsappen. |
| Merit | PSCredential | Innehåller alla autentiseringsuppgifter som administratören anger på fliken Anslutning. |
| OpenExportConnectionRunStep | OpenExportConnectionRunStep | Informerar skriptet om typen av exportkörning (delta eller fullständig), partition, hierarki och förväntad sidstorlek. |
| Typer | Schema | 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 behövs för att bearbeta alla väntande exporter. Om anslutningsplatsen har fler väntande exporter än anslutningsappens 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:
| Name | Datatyp | Beskrivning |
|---|---|---|
| ConfigParameters | KeyedCollection[string, ConfigParameter] | Tabell med konfigurationsparametrar för anslutningsappen. |
| Merit | PSCredential | Innehåller alla autentiseringsuppgifter som administratören anger 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 | Schema | 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)
Slutexport
I slutet av exportkörningen kör du skriptet End Export som ska köras. Det här skriptet bör utföra alla rensningsuppgifter som krävs (till exempel stänga anslutningar till system och svara på fel).
Slutexportskriptet tar emot följande parametrar från anslutningsappen:
| Name | Datatyp | Beskrivning |
|---|---|---|
| ConfigParameters | KeyedCollection[string, ConfigParameter] | Tabell med konfigurationsparametrar för anslutningsappen. |
| Merit | PSCredential | Innehåller alla autentiseringsuppgifter som administratören anger på fliken Anslutning. |
| OpenExportConnectionRunStep | OpenExportConnectionRunStep | Informerar skriptet om typen av exportkörning (delta eller fullständig), partition, hierarki och förväntad sidstorlek. |
| CloseExportConnectionRunStep | CloseExportConnectionRunStep | Informerar skriptet om orsaken till att exporten avslutades. |
Skriptet ska inte returnera några utdata till pipelinen.
Lösenordssynkronisering
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:
| Name | Datatyp | Beskrivning |
|---|---|---|
| ConfigParameters | KeyedCollection[string, ConfigParameter] | Tabell med konfigurationsparametrar för anslutningsappen. |
| Merit | PSCredential | Innehåller alla autentiseringsuppgifter som administratören anger på fliken Anslutning. |
| Partition | Partition | Katalogpartition som CSEntry finns i. |
| CSEntry | CSEntry | Utrymmespost för anslutningsprogrammet för objektet som har fått en lösenordsändring eller återställning. |
| Åtgärdstyp | Sträng | Anger om åtgärden är en återställning (SetPassword) eller en ändring (ChangePassword). |
| PasswordOptions | PasswordOptions | Flaggor som anger det avsedda beteendet för lösenordsåterställning. Den här parametern är endast tillgänglig om OperationType är SetPassword. |
| OldPassword | Sträng | Fylls i med objektets gamla lösenord för lösenordsändringar. Den här parametern är endast tillgänglig om OperationType är ChangePassword. |
| NewPassword | Sträng | Fylls i med objektets nya lösenord som skriptet ska ange. |
Lösenordsskriptet förväntas inte returnera några resultat till Windows PowerShell pipeline. 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 – Utlöses om lösenordet inte uppfyller lösenordsprincipen i det anslutna systemet.
- PasswordIllFormedException – Utlöses om lösenordet inte är acceptabelt för det anslutna systemet.
- PasswordExtension – genereras för alla andra fel i lösenordsskriptet.
Exempelkopplingar
En fullständig översikt över tillgängliga exempelanslutningsprogram finns i Windows PowerShell Connector Sample Connector Collection.
Andra anteckningar
Ytterligare konfiguration för personifiering
Bevilja den användare som personifieras följande behörigheter på synkroniseringstjänstens server:
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äsbehörighet 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 namnet på Windows PowerShell-anslutningsappen med platshållaren {ConnectorName}.
Felsökning
- Information om hur du aktiverar loggning för att felsöka anslutningsappen finns i Så här aktiverar du ETW-spårning för anslutningsappar.