Gebruikers toewijzen in toepassingen met behulp van PowerShell

De volgende documentatie bevat informatie over configuratie en zelfstudie. Het laat zien hoe de algemene PowerShell-connector en de ECMA-connectorhost (Extensible Connectivity) worden gebruikt om Microsoft Entra ID te integreren met externe systemen die Windows PowerShell-API's bieden.

Zie voor meer informatie technische documentatie voor Windows PowerShell Connector

Vereisten voor configuratie via PowerShell

In de volgende secties worden de vereisten voor deze tutorial beschreven.

De Installatiebestanden van PowerShell downloaden

Download de Installatiebestanden van PowerShell vanuit onze GitHub-opslagplaats. De installatiebestanden bestaan uit het configuratiebestand, het invoerbestand, het schemabestand en de scripts die worden gebruikt.

Vereisten voor on-premises

De connector biedt een brug tussen de mogelijkheden van de ECMA Connector Host en Windows PowerShell. Voordat u de connector gebruikt, moet u ervoor zorgen dat u het volgende hebt op de server die als host fungeert voor de connector

• Een Windows Server 2016 of een nieuwere versie.
• Ten minste 3 GB RAM voor het hosten van een provisioneringsagent.
• .NET Framework 4.7.2
• Windows PowerShell 2.0, 3.0 of 4.0
• Connectiviteit tussen de hostingserver, de connector en het doelsysteem waarmee de PowerShell-scripts communiceren.
• Het uitvoeringsbeleid op de server moet zo worden geconfigureerd dat de connector Windows PowerShell-scripts kan uitvoeren. 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 vertrouwd zijn met de API van 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, richtlijnen en ondersteuning voor deze integratie.

Cloudvereisten

• Een Microsoft Entra-tenant met Microsoft Entra ID P1 of Premium P2 (of EMS E3 of E5). Voor het gebruik van deze functie zijn Microsoft Entra ID P1-licenties vereist. Zie Algemeen beschikbare functies van Microsoft Entra ID vergelijken als u een licentie zoekt die bij uw vereisten past.
• De rol Beheerder voor hybride identiteit voor het configureren van de inrichtingsagent en de rol Toepassingsbeheerder of Cloudtoepassingsbeheerder voor het configureren van inrichting in de Azure-portal.
• De Microsoft Entra-gebruikers die moeten worden ingericht, moeten al worden gevuld met alle kenmerken die vereist zijn voor het schema.

Het Microsoft Entra Connect Provisioning Agent-pakket downloaden, installeren en configureren

Als u de implementatieagent hebt gedownload en deze hebt geconfigureerd voor een andere on-premises toepassing, lees dan verder in de volgende sectie.

1. Meld u aan bij het Microsoft Entra-beheercentrum als ten minste een hybride identiteitsbeheerder.
2. Blader naar Entra ID>Entra Connect>Cloud Sync>Agents.

1. Selecteer On-premises agent downloaden, controleer de servicevoorwaarden en selecteer vervolgens Voorwaarden accepteren en downloaden.

   Notitie

   Gebruik verschillende inrichtingsagents voor het inrichten van on-premises toepassingen en Microsoft Entra Connect-cloudsynchronisatie /HR-gestuurde inrichting. Alle drie de scenario's mogen niet worden beheerd op dezelfde agent.

2. Open het installatieprogramma van de provisioning-agent, ga akkoord met de servicevoorwaarden en selecteer Installeren.

3. Wanneer de configuratiewizard van de Microsoft Entra-inrichtingsagent wordt geopend, gaat u door naar het tabblad Extensie selecteren en selecteert u De inrichting van de on-premises toepassing wanneer u wordt gevraagd om de extensie die u wilt inschakelen.

4. De inrichtingsagent gebruikt de webbrowser van het besturingssysteem om een pop-upvenster weer te geven waarmee u zich kunt authenticeren bij Microsoft Entra ID en eventueel de id-provider van uw organisatie. Als u Internet Explorer als browser op Windows Server gebruikt, moet u mogelijk Microsoft-websites toevoegen aan de lijst met vertrouwde websites van uw browser om JavaScript correct te laten worden uitgevoerd.

5. Geef referenties op voor een Microsoft Entra-beheerder wanneer u wordt gevraagd om toestemming te geven. De gebruiker moet ten minste de rol Hybrid Identity Administrator hebben.

6. Selecteer Bevestigen om de instelling te bevestigen. Zodra de installatie is voltooid, kunt u Afsluiten selecteren en tevens de installer van het provisioning-agentpakket sluiten.

De on-premises ECMA-app configureren

1. Meld u bij het Microsoft Entra-beheercentrum aan als ten minste een toepassingsbeheerder.
2. Navigeer naar Entra ID>Enterprise apps.
3. Selecteer Nieuwe toepassing.
4. Zoek de on-premises ECMA-app-toepassing , geef de app een naam en selecteer Maken om deze toe te voegen aan uw tenant.
5. Navigeer naar de pagina Inrichten van uw toepassing.
6. Selecteer Aan de slag.
7. Wijzig op de pagina Inrichting de modus in Automatisch.
8. Selecteer in de sectie On-premises connectiviteit de agent die u zojuist hebt geïmplementeerd, en selecteer Agent(s) toewijzen.
9. Houd dit browservenster geopend terwijl u de volgende stap van de configuratie voltooit met behulp van de configuratiewizard.

Het InputFile.txt- en Schema.xml-bestand op locaties plaatsen

Voordat u de PowerShell-connector voor deze zelfstudie kunt maken, moet u het InputFile.txt en Schema.xml bestand naar de juiste locaties kopiëren. Deze bestanden zijn de bestanden die u nodig hebt om te downloaden in de sectie Download de Installatiebestanden van PowerShell.

Het Microsoft Entra ECMA Connector Host-certificaat configureren

1. Klik met de rechtermuisknop op de Windows Server waarop de voorzieningenagent is geïnstalleerd, selecteer de Microsoft ECMA2Host-configuratiewizard in het menu Start en voer deze uit als beheerder. Het uitvoeren als Windows-beheerder is noodzakelijk voor de wizard om de benodigde Windows-gebeurtenislogboeken te maken.
2. Nadat de ecma-connectorhostconfiguratie is gestart, als dit de eerste keer is dat u de wizard hebt uitgevoerd, wordt u gevraagd een certificaat te maken. Laat de standaardpoort 8585 staan en selecteer Certificaat genereren om een certificaat te genereren. Het automatisch gegenereerde certificaat ondertekent zichzelf als onderdeel van het vertrouwde rootcertificaat. Het certificaat-SAN komt overeen met de hostnaam.
3. Selecteer Opslaan.

De PowerShell-connector maken

Algemeen scherm

1. Start de Microsoft ECMA2Host-configuratiewizard via het startmenu.

2. Selecteer bovenaan Importeren en selecteer het configuration.xml bestand uit stap 1.

3. De nieuwe connector moet worden gemaakt en in rood worden weergegeven. Selecteer bewerken.

4. Genereer een geheim token dat wordt gebruikt voor het authenticeren van Microsoft Entra ID bij de connector. Het moet minimaal 12 tekens en uniek zijn voor elke toepassing. Als u nog geen geheime generator hebt, kunt u een PowerShell-opdracht zoals hieronder gebruiken om een voorbeeld van een willekeurige tekenreeks te genereren.

   -join (((48..90) + (96..122)) * 16 | Get-Random -Count 16 | % {[char]$_})
   

5. Op de pagina Eigenschappen moeten alle gegevens worden ingevuld. De tabel wordt vermeld als referentie. Selecteer Volgende.

   Eigendom	Waarde
   Naam	De naam die u hebt gekozen voor de connector, die uniek moet zijn voor alle connectors in uw omgeving. Bijvoorbeeld: PowerShell.
   Timer voor automatische synchronisatie (minuten)	120
   Geheime token	Voer hier uw geheime token in. Deze moet minimaal 12 tekens bevatten.
   Extensie-DLL	Selecteer Microsoft.IAM.Connector.PowerShell.dll voor de PowerShell-connector.

Connectiviteit

Op het tabblad Connectiviteit kunt u configuratieparameters opgeven om verbinding te maken met een extern systeem. Configureer het connectiviteitstabblad met de informatie in de tabel.

• Op de pagina Connectiviteit moeten alle gegevens worden ingevuld. De tabel wordt vermeld als referentie. Selecteer Volgende.

Mogelijkheden

Het tabblad Mogelijkheden definieert het gedrag en de functionaliteit van de connector. De selecties op dit tabblad kunnen niet worden gewijzigd wanneer de connector wordt gemaakt. Configureer het tabblad Mogelijkheden met de informatie in de tabel.

• Op de pagina Mogelijkheden moeten alle gegevens worden ingevuld. De tabel wordt vermeld als referentie. Selecteer Volgende.

Globale parameters

Op het tabblad Algemene parameters 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. Configureer het tabblad Globale parameters met de informatie in de tabel.

• Op de pagina Globale parameters moeten alle gegevens worden ingevuld. De tabel wordt vermeld als referentie. Selecteer Volgende.

Partities, Uitvoeringsprofielen, Exporteren, FullImport

Behoud de standaardinstellingen en selecteer volgende.

Objecttypen

Configureer het tabblad Objecttypen met de informatie in de tabel.

• Op de pagina Objecttypen moeten alle gegevens worden ingevuld. De tabel wordt vermeld als referentie. Selecteer Volgende.

Kenmerken selecteren

Zorg ervoor dat de volgende kenmerken zijn geselecteerd:

• Op de pagina Kenmerken selecteren moeten alle gegevens worden ingevuld. De tabel wordt vermeld als referentie. Selecteer Volgende.

• AzureObjectID

• IsActive

• Schermnaam

• Medewerker-ID

• Titel

• Gebruikersnaam

• E-mailen

Inrichting ongedaan maken

Op de Deprovisioning-pagina kunt u opgeven of u wilt dat Microsoft Entra ID gebruikers uit de directory verwijdert wanneer ze buiten het bereik van de toepassing vallen. Als dat het zo is, selecteert u onder Stroom uitschakelen de optie Verwijderen en selecteert u Onder Stroom verwijderen de optie Verwijderen. Als de optie Kenmerkwaarde instellen is gekozen, zijn de kenmerken die op de vorige pagina zijn geselecteerd niet beschikbaar voor selectie op de deprovisioningpagina.

• Op de Deprovisioning-pagina moet alle informatie gevuld zijn. De tabel wordt vermeld als referentie. Selecteer Volgende.

Zorg ervoor dat de ECMA2Host-service wordt uitgevoerd en kan lezen uit het bestand via PowerShell

Volg deze stappen om te controleren of de connectorhost is gestart en bestaande gebruikers van het doelsysteem heeft geïdentificeerd.

1. Selecteer Start op de server waarop de Microsoft Entra ECMA Connector Host wordt uitgevoerd.
2. Selecteer uitvoeren indien nodig en voer services.msc in het vak in.
3. Zorg ervoor dat Microsoft ECMA2Host aanwezig is in de lijst Services en wordt uitgevoerd. Als het niet actief is, selecteer Start.
4. Start PowerShell op de server waarop de Microsoft Entra ECMA Connector Host wordt uitgevoerd.
5. Ga naar de map waarin de ECMA-host is geïnstalleerd, zoals C:\Program Files\Microsoft ECMA2Host.
6. Verander naar de submap Troubleshooting.
7. Voer het script TestECMA2HostConnection.ps1 uit in de map zoals weergegeven en geef de naam van de connector en de ObjectTypePath waarde cacheop als argumenten. Als uw connectorhost niet luistert op TCP-poort 8585, moet u mogelijk ook het -Port argument opgeven. Wanneer u hierom wordt gevraagd, typt u het geheime token dat is geconfigureerd voor die connector.

   PS C:\Program Files\Microsoft ECMA2Host\Troubleshooting> $cout = .\TestECMA2HostConnection.ps1 -ConnectorName PowerShell -ObjectTypePath cache; $cout.length -gt 9
   Supply values for the following parameters:
   SecretToken: ************
   

8. Als in het script een foutbericht of waarschuwingsbericht wordt weergegeven, controleert u of de service wordt uitgevoerd en of de naam en het geheime token van de connector overeenkomen met de waarden die u in de configuratiewizard hebt geconfigureerd.
9. Als het script de uitvoer Falseweergeeft, heeft de connector geen vermeldingen gevonden in het bron- en doelsysteem voor bestaande gebruikers. Als dit een nieuwe installatie van het doelsysteem is, wordt dit gedrag verwacht en kunt u doorgaan in de volgende sectie.
10. Als het doelsysteem echter al een of meer gebruikers bevat, maar het script de status Falseweergeeft, geeft dit aan dat de connector niet van het doelsysteem kon lezen. Als u probeert te provisioneren, kan Microsoft Entra ID gebruikers in die brondirectory mogelijk niet correct koppelen aan gebruikers in Microsoft Entra ID. Wacht enkele minuten totdat de connectorhost klaar is met het lezen van objecten uit het bestaande doelsysteem, en voer het script vervolgens opnieuw uit. Als de uitvoer False blijft, controleer dan de configuratie van uw connector en of de machtigingen in het doelsysteem zijn toegestaan, zodat de connector bestaande gebruikers kan lezen.

De verbinding van Microsoft Entra-id testen met de connectorhost

1. Ga terug naar het browservenster waarin u de inrichting van de toepassing in de portal hebt geconfigureerd.

   Notitie

   Als het venster een time-out had gehad, moet u de agent opnieuw selecteren.

   1. Meld u bij het Microsoft Entra-beheercentrum aan als ten minste een toepassingsbeheerder.
   2. Navigeer naar Entra ID>Enterprise apps.
   3. Selecteer de toepassing On-premises ECMA-app.
   4. Selecteer Provisioning.
   5. Als Aan de slag wordt weergegeven, wijzigt u de modus in Automatisch, selecteert u in de sectie On-premises connectiviteit de agent die u zojuist hebt geïmplementeerd, en selecteert u Agent(s) toewijzen. Wacht vervolgens tien minuten. Ga anders naar Voorziening bewerken.

2. Voer in de sectie Beheerdersreferenties de volgende URL in. Vervang het connectorName gedeelte door de naam van de connector op de ECMA-host, zoals PowerShell. Als u een certificaat hebt opgegeven van uw certificeringsinstantie voor de ECMA-host, vervangt u localhost de hostnaam van de server waarop de ECMA-host is geïnstalleerd.

   Eigendom	Waarde
   Tenant-URL	https://localhost:8585/ecma2host_connectorName/scim

3. Voer de waarde voor Geheim token in die u hebt gedefinieerd toen u de connector maakte.

   Notitie

   Als u de agent zojuist aan de toepassing hebt toegewezen, wacht u tien minuten totdat de registratie is voltooid. De connectiviteitstest werkt pas als de registratie is voltooid. Door het herstarten van de provisioningagent op uw server kan de registratie van de agent worden afgedwongen en het registratieproces worden versneld. Ga naar uw server, zoek naar services in de zoekbalk van Windows, identificeer de Microsoft Entra Connect Provisioning Agent-service, selecteer de service met de rechtermuisknop en start opnieuw.

4. Selecteer Verbinding testen en wacht één minuut.

5. Nadat de verbindingstest is geslaagd en is aangetoond dat de verstrekte referenties bevoegd zijn om de voorziening in te schakelen, selecteert u Opslaan.

De toepassingsverbinding configureren

Ga terug naar het browservenster waarin u de inrichting van de toepassing configureerde.

1. Meld u bij het Microsoft Entra-beheercentrum aan als ten minste een toepassingsbeheerder.

2. Navigeer naar Entra ID>Enterprise apps.

3. Selecteer de toepassing On-premises ECMA-app.

4. Selecteer Provisioning.

5. Als Aan de slag wordt weergegeven, wijzigt u de modus in Automatisch in de sectie On-Premises Connectiviteit , selecteert u de agent die u hebt geïmplementeerd en selecteert u Agent(en) toewijzen. Ga anders naar Voorziening bewerken.

6. Voer in de sectie Beheerdersreferenties de volgende URL in. Vervang het {connectorName} gedeelte door de naam van de connector op de ECMA-connectorhost, zoals CSV. De naam van de connector is hoofdlettergevoelig en moet precies hetzelfde hoofdlettergebruik hebben als dat in de wizard is geconfigureerd. U kunt ook vervangen door localhost de hostnaam van uw computer.

   Eigendom	Waarde
   Tenant-URL	https://localhost:8585/ecma2host_CSV/scim

7. Voer de waarde voor Geheim token in die u hebt gedefinieerd toen u de connector maakte.

   Notitie

   Als u de agent zojuist aan de toepassing hebt toegewezen, wacht u tien minuten totdat de registratie is voltooid. De connectiviteitstest werkt pas als de registratie is voltooid. Door het herstarten van de provisioningagent op uw server kan de registratie van de agent worden afgedwongen en het registratieproces worden versneld. Ga naar uw server, zoek naar services in de zoekbalk van Windows, identificeer de Microsoft Entra Connect Provisioning Agent Service, selecteer met de rechtermuisknop de service en start opnieuw.

8. Selecteer Verbinding testen en wacht één minuut.

9. Nadat de verbindingstest is geslaagd en is aangetoond dat de verstrekte referenties bevoegd zijn om de voorziening in te schakelen, selecteert u Opslaan.

Kenmerktoewijzingen configureren

U moet nu kenmerken toewijzen tussen de weergave van de gebruiker in Microsoft Entra-id en de weergave van een gebruiker in de on-premises InputFile.txt.

U gebruikt Azure Portal om de toewijzing te configureren tussen de kenmerken van de Microsoft Entra-gebruiker en de kenmerken die u eerder hebt geselecteerd in de wizard ECMA-hostconfiguratie.

1. Meld u bij het Microsoft Entra-beheercentrum aan als ten minste een toepassingsbeheerder.

2. Navigeer naar Entra ID>Enterprise apps.

3. Selecteer de toepassing On-premises ECMA-app.

4. Selecteer Provisioning.

5. Selecteer Inrichting bewerken en wacht 10 seconden.

6. Vouw Toewijzingen uit en selecteer Microsoft Entra-gebruikers inrichten. Als dit de eerste keer is dat u de kenmerktoewijzingen voor deze toepassing hebt geconfigureerd, is er slechts één toewijzing aanwezig voor een tijdelijke aanduiding.

7. Als u wilt controleren of het schema beschikbaar is in Microsoft Entra ID, schakelt u het selectievakje Geavanceerde opties weergeven in en selecteert u De lijst Kenmerken bewerken voor ScimOnPremises. Zorg ervoor dat alle kenmerken die in de configuratiewizard zijn geselecteerd, worden vermeld. Zo niet, wacht u enkele minuten totdat het schema is vernieuwd en laadt u de pagina opnieuw. Zodra u de vermelde kenmerken ziet, annuleert u deze pagina om terug te keren naar de lijst met toewijzingen.

8. Selecteer nu de userPrincipalName in het mappingveld. Deze toewijzing wordt standaard toegevoegd wanneer u een eerste keer on-premises voorziening configureert. Wijzig de waarde zodat deze overeenkomt met het volgende:

   Toewijzingstype	Bronkenmerk	Doelkenmerk
   Onmiddellijk	gebruikershoofdnaam	urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:UserName

9. Selecteer Nieuwe toewijzing toevoegen nu en herhaal de eerstvolgende stap voor elke toewijzing.

10. Geef de bron- en doelattributen op voor elke mapping in de volgende tabel.

    Toewijzingstype	Bronkenmerk	Doelkenmerk
    Onmiddellijk	objectId	urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:Gebruiker:AzureObjectID
    Onmiddellijk	gebruikershoofdnaam	urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:UserName
    Onmiddellijk	weergavenaam	urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:DisplayName
    Onmiddellijk	medewerkerId	urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:Gebruiker:EmployeeId
    Onmiddellijk	functietitel	urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:Title
    Onmiddellijk	e-mail	urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:Gebruiker:E-mail
    Expressie	Schakelaar([IsSoftDeleted],, "Onwaar", "Waar", "Waar", "Onwaar")	urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:Gebruiker:IsActive

    

11. Selecteer Opslaan nadat alle toewijzingen zijn toegevoegd.

Gebruikers toewijzen aan een toepassing

Nu u de Microsoft Entra ECMA Connector-host hebt die met Microsoft Entra ID communiceert en de kenmerktoewijzing is geconfigureerd, kunt u doorgaan met het configureren van wie binnen het bereik valt voor provisioning.

Als er bestaande gebruikers in de InputFile.txt staan, moet u toepassingsroltoewijzingen maken voor die bestaande gebruikers. Zie voor meer informatie over het bulksgewijs maken van toepassingsroltoewijzingen voor bestaande gebruikers van een toepassing in Microsoft Entra ID.

Als er geen huidige gebruikers van de toepassing zijn, selecteert u een testgebruiker van Microsoft Entra die wordt ingericht voor de toepassing.

1. Zorg ervoor dat de geselecteerde gebruiker alle eigenschappen heeft die zijn toegewezen aan de vereiste kenmerken van het schema.
2. Meld u bij het Microsoft Entra-beheercentrum aan als ten minste een toepassingsbeheerder.
3. Navigeer naar Entra ID>Enterprise apps.
4. Selecteer de toepassing On-premises ECMA-app.
5. Selecteer aan de linkerkant onder Beheren de optie Gebruikers en groepen.
6. Selecteer Gebruiker/groep toevoegen.
7. Selecteer Geen geselecteerd onder Gebruikers.
8. Selecteer gebruikers aan de rechterkant en selecteer de knop Selecteren .
9. Selecteer nu Toewijzen.

Testvoorbereiding

Nu uw kenmerken en gebruikers zijn toegewezen, kunt u inrichting op aanvraag testen met een van uw gebruikers.

1. Meld u bij het Microsoft Entra-beheercentrum aan als ten minste een toepassingsbeheerder.
2. Navigeer naar Entra ID>Enterprise apps.
3. Selecteer de toepassing On-premises ECMA-app.
4. Selecteer Provisioning.
5. Selecteer Voorziening op aanvraag.
6. Zoek een van uw testgebruikers en selecteer Inrichten.
7. Na enkele seconden wordt het bericht Succesvol gebruiker gemaakt in het doelsysteem weergegeven, samen met een lijst van de gebruikerskenmerken.

Inrichten van gebruikers starten

1. Nadat het inrichten op aanvraag is voltooid, gaat u terug naar de configuratiepagina van het inrichten. Zorg dat het bereik is ingesteld op alleen toegewezen gebruikers en groepen, schakel inrichting in en selecteer Opslaan.
2. Wacht enkele minuten totdat het inrichten is gestart. Dit kan maximaal 40 minuten duren. Nadat de inrichtingstaak is voltooid, zoals beschreven in de volgende sectie, als u klaar bent met testen, kunt u de inrichtingsstatus wijzigen in Uiten vervolgens Opslaanselecteren. Met deze actie wordt de inrichtingsservice niet meer uitgevoerd in de toekomst.

Volgende stappen

• App-inrichting
• ECMA Connector Host generic SQL-connector
• ECMA Connector Host LDAP-connector