Entra ID profielsynchronisatie - Eenmalige opzet

Vul profielen automatisch vanuit Entra ID. De synchronisatie draait via een PowerShell-script, meestal als runbook in Azure Automation. Dit artikel beschrijft hoe je die omgeving opzet: van app-registratie tot geplande uitvoering. 

De documentatie bestaat uit twee delen:

• Deel 1 (dit artikel): de eenmalige opzet - app-registratie, Azure Automation-account en runbook.
• Deel 2: het inrichten en onderhouden van het script - verbindingsgegevens, veldmapping, groepslidmaatschap, output en troubleshooting van de synchronisatie zelf.

Dit artikel bestaat uit de volgende secties:

• Algemeen
• Maak een app-registratie aan in Azure
• Maak een Azure Automation-account aan
• Installeer de benodigde modules
• Maak Variables aan (optioneel)
• Maak een runbook aan en plaats het script
• Testen en publiceren
• Laat het script ingepland draaien
• Troubleshoot

Algemeen

Het PowerShell-script synchroniseert gebruikers van Microsoft Entra ID naar Embrace. Er is voor PowerShell gekozen vanwege de transparantie die het biedt in het proces. Bovendien stelt het beheerders en IT-professionals in staat om zelf uitzonderingen en klantspecifieke aanpassingen te implementeren.

Runbook of lokale machine

Deze documentatie gaat ervan uit dat het script als runbook binnen Azure Automation draait. Het script kan ook op een andere manier uitgevoerd en ingepland worden, bijvoorbeeld met PowerShell op een lokale Windows-server. In dat geval is alleen de app-registratie vereist; de stappen voor het Automation-account en het runbook zijn dan niet van toepassing. De inrichting van het script (deel 2) blijft gelijk.

Samengevat doorloop je deze stappen:

• Maak een app-registratie aan in Azure;
• Maak een Azure Automation-account aan;
• Installeer de benodigde modules;
• Maak een runbook aan binnen het Automation-account;
• Plaats het script uit de bijlage in het runbook;
• Richt het script in (zie deel 2);
• Test, publiceer en plan het script in.

Maak een app-registratie aan in Azure

Het gebruik van de bestaande Embrace app-registratie voor Entra ID-authenticatie is mogelijk, maar die registratie heeft voor de pushsynchronisatie te veel rechten. Wij adviseren daarom een nieuwe app-registratie te creëren, speciaal voor de profielsynchronisatie.

• Log in op Azure -> https://portal.azure.com
• Klik op Microsoft Entra ID
• Kies App registrations -> New registration

• Geef de app-registratie een herkenbare naam, bijvoorbeeld: Embrace Social push-synchronisation
• Kies bij Supported account types voor "Accounts in this organizational directory only"
• Je hoeft géén redirect URL op te geven
• Kies "Register"

• Kies na registratie onder Manage voor API permissions
• Kies +Add a permission

• Kies Microsoft Graph en voeg de volgende application permissions toe:
  • User.Read.All
  • Group.Read.All
• Geef hierna Admin Consent via de knop "Grant admin consent for ..."

• Ga vervolgens naar Certificates & secrets
• Kies New client secret

• Geef de nieuwe client secret een herkenbare naam (bijvoorbeeld: ClientSecret for Embrace Social push-synchronisation)
• Geef een zo lang mogelijke verlooptijd (24 maanden)
• Kies "Add"

Maak een Azure Automation-account aan

• Log in op Azure: https://portal.azure.com
• Klik linksboven op "Create a resource"
• Zoek "Automation" en kies deze uit de lijst:
  
• Kies Create:
  

• Vul de gegevens in:
  

  Veld	Waarde
  Subscription	Kies welk abonnement gebruikt moet worden
  Resource group	Kies een resource group of maak een nieuwe
  Automation account name	Kies een naam, bijvoorbeeld embrace-sync-automation
  Region	Kies de dichtstbijzijnde locatie (meestal West Europe)

• De overige tabs kunnen op default blijven staan (of naar behoefte aangepast worden)
• Ga naar Review + Create en kies "Create"

Installeer de benodigde modules

• Blijf bij het Automation-account en ga naar Shared Resources -> Modules
• Kies Add a module

• Kies Browse from gallery
• Voeg de volgende modules toe:
  • Microsoft.Graph.Authentication (versie 2.0 of hoger)
  • Microsoft.Graph.Users
  • Microsoft.Graph.Groups
• Kies bij "Runtime version" voor versie 7.x. De installatie kan enige tijd duren; vernieuw het overzicht totdat alle modules de status "Available" tonen.

Maak Variables aan binnen Shared Resources -> Variables (optioneel)

Om te voorkomen dat de client secret in platte tekst in het script staat, is het aan te raden een Automation-variabele te gebruiken. In het script verwijs je dan naar de naam van de variabele in plaats van de waarde zelf.

• Blijf binnen het Automation-account en kies Variables (onder Shared Resources)
• Kies Add a variable

Maak de volgende variabele aan:

De naam van de variabele gebruik je vervolgens als referentie in het script:

$azSecret = Get-AutomationVariable -Name "azureClientSecretValue"

Maak een runbook aan en plaats het script

• Blijf binnen het Automation-account en kies Runbooks (onder Process Automation)
• Kies Create a runbook

• Vul een herkenbare naam in, bijvoorbeeld embrace-social-push-synchronization
• Runbook type: PowerShell
• Runtime version: 7.x
• Kies "Create"

Download vervolgens het PowerShell-script (bijlage onderaan dit artikel), open het, en kopieer en plak de inhoud in de editor van het runbook. Kies "Save".

Testen en publiceren

• Nadat het script is ingericht (deel 2), test je het in de Test pane van het runbook.
• Laat $dryRun op $true staan: het script toont dan een voorbeeld van de output zonder iets te versturen. Controleer de SettingsUsed-regel (de actieve configuratie), het aantal gevonden gebruikers en de getoonde JSON.
• Is alles correct? Zet $dryRun op $false en voer het script nogmaals uit in de Test pane. De gegevens worden nu daadwerkelijk naar Embrace verstuurd. Controleer de samenvattingsregel (Summary: ...) en controleer in Embrace of de profielgegevens goed verwerkt zijn.
• Publiceer daarna het runbook (Edit -> Publish).

Laat het script ingepland draaien

Aanmaken schedule:

• Ga naar het Automation-account, kies Schedules en Add a schedule:
  
• Maak een recurring daily schedule

• 
• Kies "Create"

• de variabele $dryRun staat in het script op $false;
• het script is eenmalig via de Test pane uitgevoerd en in Embrace is gecontroleerd dat de profielgegevens goed verwerkt zijn;
• het script is gepubliceerd (Edit -> Publish).

Koppelen schedule aan het runbook

• Kies bij het runbook voor "Link to schedule":
  
• Kies "Link a schedule to your runbook":
  
• Kies de eerder aangemaakte schedule:
  
• Kies "OK"

Troubleshoot

• Invalid JWT access token
  Controleer of de modules met runtime versie 5.1 zijn geïmporteerd. De installatie kan enige tijd duren; vernieuw het overzicht totdat alle modules de status "Available" tonen.
• Invalid JWT access token (PowerShell 7.2)
  Gebruik je PowerShell 7.2, zorg dan dat de module Microsoft.Graph.Authentication gedowngraded wordt. In versie 2.26.1 zit een known issue; meer informatie op deze pagina.
• "The following required PowerShell modules are missing: ..."
  Het script meldt zelf welke modules ontbreken. Importeer deze in het Automation-account (runtime 5.1), of installeer ze lokaal met Install-Module.
• "Microsoft.Graph.Authentication version ... was found, but version 2.0 or higher is required"
  Er is een verouderde versie van de module geïmporteerd. Importeer een nieuwere versie in het Automation-account, of werk de module lokaal bij met Update-Module Microsoft.Graph.Authentication.

Foutmeldingen over de configuratie of de synchronisatie zelf staan beschreven in deel 2: het inrichten en onderhouden van het script.