Entra ID (Profielsynchronisatie)

Dit artikel bestaat uit de volgende secties:

• Algemeen
• Configuratie
  • Maak een app-registratie aan in Azure 
  • Maak een Azure Automation account aan  
  • Installeer de benodigde modules 
  • Script plaatsen en testen 
  • Schedulen van het script
• Geavanceerde inrichting
  • Groepslidmaatschap
• Troubleshoot

Algemeen

Het bijgevoegde PowerShell-script maakt het mogelijk om gebruikers van Microsoft Entra ID te synchroniseren met Embrace. PowerShell is gekozen vanwege de transparantie die het biedt in het proces. Bovendien stelt PowerShell beheerders en IT-professionals in staat om zelf uitzonderingen en andere klantspecifieke aanpassingen te implementeren. Het script kan ook op verschillende manieren worden uitgevoerd: als een runbook in Azure Automation of op een lokale Windows-server.

Locatie van het script: draaien als Azure Runbook of lokale machine

Deze documentatie veronderstelt dat het script als een runbook binnen Azure Automation zal worden gebruikt. Natuurlijk zijn er alternatieven om het script anders uit te voeren en te plannen, zoals PowerShell in een lokale omgeving. In dat geval is alleen app-registratie vereist. De stappen voor het creëren van een runbook zijn dan niet relevant. De uitleg over de gebruikte variabelen blijft echter ongewijzigd. 

Configuratie

Het script kan worden geïmplementeerd en gepland binnen Azure door de volgende stappen te volgen:

• Maak een app-registratie aan in Azure;
• Maak een Azure Automation-account aan;
• Maak een Runbook aan binnen het Automation-account;
• Plaats het script uit de bijlage in het Runbook;
• Vul de variabelen in het script in;
• Plan het script om op gezette tijden uit te voeren.

Maak een app-registratie aan in Azure

Het gebruik van de bestaande Embrace app-registratie voor Entra ID-authenticatie is mogelijk. Echter, voor het uitvoeren van de pushsynchronisatie beschikt deze registratie over 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 voor App registrations -> New registration

• Geef de appregistratie 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"

• Nadat de app geregistreerd is, kies onder Manage voor API permissions
• Kies vervolgens voor +Add permission

• Kies voor 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... "

• Vervolgens ga je naar Certificates & secrets 
• Kies voor New client secret

• Geef deze 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 resource aan

• Login in Azure: https://portal.azure.com.
• Klik linksboven op "create a resource".
• Zoek "Automation" en kies deze dan 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 bv embrace-sync-automation
  Region	kies de dichtstbijzijnde locatie (meestal West Europe)

• De overige tabs kunnen default gelaten worden (of indien gewenst aangepast naar behoefte).
• 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 voor Browse from gallery.
• Selecteer nu Browse from gallery.
• Voeg de volgende modules toe:
  • MSAL.PS
  • Microsoft.Graph.Authentication
  • Microsoft.Graph.Users
  • Microsoft.Graph.Groups
• Bij 'Runtime version', kies versie 5.1. De installatie kan enige tijd in beslag nemen. Vernieuw het overzicht van geïnstalleerde modules totdat alle modules de status 'Available' vertonen.

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

Om het gebruik van wachtwoorden in platte tekst binnen het script te vermijden, is het aan te bevelen om variabelen te gebruiken. In het PowerShell-script verwijs je dan naar de naam van de variabele, in plaats van de waarde in platte tekst te noemen

• Blijf binnen het automation-account en kies voor Variables (onder Shared Resources)
• Klik op Variables
• Kies voor Add variables

De volgende variabelen dienen aangemaakt te worden:

De naam die je opgeeft bij het aanmaken van de variabelen, gebruik je vervolgens als referentie in het script. 

Maak een runbook aan binnen het Automation account

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

• Vul een herkenbare naam in, bijvoorbeeld embrace-social-push-synchronization
• Runbook type: Powershell
• Runtime version: 5.1

• Kies 'create'. 

Plaats het script uit de bijlage in het runbook

Bij dit artikel kun je het PowerShell-script als bijlage downloaden. Zodra je dat hebt gedaan, kun je het openen en de inhoud kopiëren en plakken in de editor van het runbook.

• Plak het script van Embrace in de editor: (zie de bijlage onderaan deze documentatie).
• Kies 'save'. 

Vul de variabelen in binnen het script

In het script dien je de volgende variabelen in te vullen om verbinding te maken met de aangemaakte App-registratie

$azAppId     = '' vul hier het Application (client) ID in van de app-registratie. 
$azTenantId  = '' vul hier het ID van de Azure-tenant in.

Gebruik je de variabelen vanuit de stap hierboven? Gebruik dan deze waarde:

$azSecret    = Get-AutomationVariable -Name "azureClientSecretValue" 
 

Wil je plain-tekst gebruiken, vul dan hier de client secret in

$azSecret    = '' vul hier de Secret value toe van de app-registratie.

Daarnaast dienen deze instellingen ingevuld te zijn. De waarden hiervoor worden aangeleverd door  Embrace: 

$kcTenantId  = '' 

$authClientSecret ''

Het script is opgedeeld in een "Basic" en een "Advanced" configuratiegedeelte. Hieronder worden globaal de opties beschreven. Zie het script zelf voor meer gedetailleerde informatie.

Tijdens het configureren van onderstaande opties kan het script meerdere keren worden uitgevoerd om het resultaat te bekijken. Het uitvoeren en testen van dit script kan in het "Test pane".

Als het resultaat naar wens is, moet de variabele $upload op $true worden gezet zodat de gegevens daadwerkelijk naar Embrace worden verstuurd (zie verderop in dit document).

Basic
De basic configuratie moet minimaal uitgevoerd/gecontroleerd worden. Het configureren bestaat uit het correct invullen van een aantal PowerShell variabelen:

Over velden en mapping

We kunnen in principe alle velden uit Entra ID lezen en mappen naar de standaard velden van Embrace. 

Dit zijn de aanvullende velden die standaard in het script staan. Deze kun je aanpassen.

# $additionalFields = 
#     ("job-title", "jobTitle"),
#     ("company-name", "companyName"),
#     "department",
#     "displayname",
#     ("hire-date", "employeeHireDate"),
#     ("street-address", "streetAddress"),
#     ("office", "officeLocation"),
#     "city",
#     "country",
#     ("postal-code", "postalCode"),
#     ("office-phone", "businessPhones"),
#     ("mobile-phone", "mobilePhone")

Verplichte velden

Deze velden staan standaard aan en zijn nodig voor een geldige synchronisatie.

$requiredFields = 
    ("ExternalId", "Id"),
    ("FirstName", "GivenName"),
    ("LastName", "Surname"),
    ("Email", "Mail"),
    ("AccountEnabled", "AccountEnabled")

User extensions

Entra ID biedt de mogelijkheid om eigenschappen toe te voegen aan het profiel van een gebruiker. Als je ervoor kiest om gebruik te maken van deze 'user extensions' en ze wilt synchroniseren met Embrace, is dat mogelijk. De naam van deze eigenschap kan worden opgenomen in de andere veldtoewijzingen, bijvoorbeeld:

("birthdate", "extension_f946aada8c064232b6753f91f2ca3bf4_BirthDate")

Hetzelfde geldt voor custom Embrace profiel properties, bijvoorbeeld:

$custom = ,("Hobbies", "extension_f946aada8c064232b6753f91f2ca3bf4_Hobbies")

Een beheerder van Entra ID kan de juiste namen van deze eigenschappen verstrekken. Voor zover bekend is, kunnen deze eigenschappen alleen via PowerShell worden uitgelezen. Zie het volgende voorbeeld:

Import-Module MSAL.PS
Import-Module Microsoft.Graph.Authentication
Import-Module Microsoft.Graph.Users
Import-Module Microsoft.Graph.Groups
Import-Module Microsoft.Graph.Beta.Users

# General configuration for connecting to Azure Active Directory
$azureApplicationId = ''
$azureTenantId = '' 
$azureClientSecretValue = ''

#userid of testuser with extensions:
$userId = ''

#connect to Graph.
$MsalToken = Get-MsalToken -TenantId $azureTenantId -ClientId $azureApplicationId -ClientSecret ($azureClientSecretValue | ConvertTo-SecureString -AsPlainText -Force)
$passwordSecure = ConvertTo-SecureString -AsPlainText -Force $MsalToken.AccessToken

#if this gives a error, please try this $connect = Connect-Graph -AccessToken $MsalToken.AccessToken -NoWelcome
$connect = Connect-Graph -AccessToken $passwordSecure -NoWelcome

$userProperties = Get-MgBetaUser -UserId $userId
write-host $userProperties.AdditionalProperties

Testen script

• Nadat de variabelen in het script zijn ingevoerd kan het getest worden in de test pane van Azure. 
• Er zouden geen fouten moeten optreden en het script zou een deel van de JSON moeten tonen. Het geeft ook aan hoeveel gebruikers er gevonden zijn. Controleer of het aantal gebruikers correct is en of de JSON de gegevens bevat die naar Embrace verzonden moeten worden.
• Als alles correct functioneert, kan de dryRun-parameter op $false worden ingesteld. Voer het script vervolgens opnieuw uit in het testpaneel. De gegevens worden dan daadwerkelijk naar Embrace verzonden. Er zouden geen fouten moeten optreden. Controleer ook of de gegevens correct in Embrace zijn verwerkt.
• Als alles in orde is, kan het script worden gepubliceerd.
• En vervolgens kan het script gescheduled kunnen worden. 

Troubleshoot
Failed  JWT access code. > Controleer of de modules met versie 5.1 zijn geïmporteerd. 

Failed The term 'Get-MsalToken' is not recognized as a name of a cmdlet, function, script file, or executable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again. > Controleer of het Runbook op versie 5.1 staat. 

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 variable $dryRunmoet in het script op $false gezet zijn
• vervolgens moet het script nog eenmalig via de "Test pane" uitgevoerd zijn en in Embrace gecontroleerd worden of de profiel gegevens goed verwerkt zijn
• vervolgens moet het script gepubliceerd zijn (edit script en dan publish knop). 

Koppelen schedule aan script:

• Kies bij het script voor 'link to schedule':
  
• Kies 'Link a schedule to your runbook'. 
  
• Kies de eerder aangemaakte schedule.
  
• Kies 'Ok'. 

Geavanceerde inrichting

Groepslidmaatschap

In het script kun je inregelen dat een M365 EntraID groep geautomatiseerd lid wordt gemaakt van een groep binnen Embrace. Dit kan een intranetgroep en/of een rechtengroep zijn. 

Beide soorten groepen verwijzen naar Toegangsgroepen in Embrace. De intranetbeheerder (hier zijn specifieke rechten voor nodig) dient deze Toegangsgroepen aan te maken en de naamgeving te delen met de Entra ID beheerder voor verdere verwerking in het script. Zie hiervoor deze documentatie Users - Rechten en rollen.

Intranetgroepen

Via Toegangsgroepen maakt de intranetbeheerder een mapping aan voor synchronisatie groepen van Entra ID naar de Social intranetgroepen.

- Maak een Toegangsgroep aan > Management > Users > Toegangsgroepen.
- Koppel de Toegangsgroep > tabje Synchronisatie > zoek de Social intranetgroep.

In het Powershell script kan de koppeling gelegd worden via AD groepen (teamMemberships) of via custom/Additional fields (customMappings) die met de users meegestuurd worden. 

Hiervoor gebruik je de functie $teamMemberships of de $customMappings in het profielsynchronisatiescript.

Voorbeeld 1 groep op basis van teamMemberships (AD groepen): 

$teamMemberships = , ("Embrace Suite/Testers", "AD-Testgroep")

Voorbeeld meerdere groepen:

$teamMemberships =  ("Embrace Suite/Testers", "AD-Testgroep"), 
                    ("Embrace Suite/Testers2", "AD-Testgroep2")

Voorbeeld 1 custom mapping op basis van customMappings (AAD properties):

    $customMappings = @(
[PropertyMapping]::new([Action]::Assign, [EmbraceType]::Group, 'Embrace Suite/Testers', 'jobTitle', 'Tester', $false)
)

Voorbeeld meerdere custom mappings: 

    $customMappings = @(
[PropertyMapping]::new([Action]::Assign, [EmbraceType]::Group, 'Embrace Suite/Testers', 'jobTitle', 'Tester', $false)
[PropertyMapping]::new([Action]::Assign, [EmbraceType]::Group, 'Embrace Suite/Consultants', 'Department', 'Consultancy', $false)
)

Rechtengroepen

Voor het toekennen van rollen, is de best practice om een rechtengroep aan te maken en daar een rol aan te koppelen. 
- Maak een rol aan >Management >Users >Rollen.
- Maak een rechtengroep aan >Management >Users >Toegangsgroepen.

Koppel de aangemaakte rol(len) vervolgens aan de aangemaakte toegangsgroep. 
 

In het script regelen we in dat een M365 Entra ID groep via de sync lid wordt gemaakt van de aangemaakte toegangsgroep in Embrace en daarmee de gewenste rol(len) krijgt.

Groepslidmaatschap: rechtengroep
Bij 1 rechtengroep:
$teamMemberships = ,("Embrace Suite/[Naam Embrace rechtengroep]", "[Naam EntraID groep]")

Bij meerdere rechtengroepen:
$teamMemberships = 
("Embrace Suite/[Naam Embrace rechtengroep]", "[Naam EntraID groep]"),
("Embrace Suite/[Naam Embrace rechtengroep]", "[Naam EntraID groep]"),
("Embrace Suite/[Naam Embrace rechtengroep]", "[Naam EntraID groep]")

Wanneer je zowel intranetgroepen als rechtengroepen wil inregelen, kun je dit combineren. Dit ziet er bijvoorbeeld zo uit:

Groepslidmaatschap: intranetgroep + rechtengroep
$teamMemberships = 
("social/Group: [Naam Embrace intranetgroep] - members", "[Naam EntraID groep]"),
("social/Group: [Naam Embrace intranetgroep] - members", "[Naam EntraID groep]"),
("social/Group: [Naam Embrace intranetgroep] - members", "[Naam EntraID groep]"),
("Embrace Suite/[Naam Embrace rechtengroep]", "[Naam EntraID groep]"),
("Embrace Suite/[Naam Embrace rechtengroep]", "[Naam EntraID groep]"),
("Embrace Suite/[Naam Embrace rechtengroep]", "[Naam EntraID groep]")

Troubleshoot

• Invalid JWT access token
  Bij 'Runtime version', kies de versie 5.1. De installatie kan enige tijd in beslag nemen. Vernieuw het overzicht van geïnstalleerde modules totdat alle modules de status 'Available' vertonen.
• Invalid JWT access token
  Gebruik je Powershell 7.2, zorg dan dat de Microsoft.Graph.Authentication  module gedowngrade wordt. In versie 2.26.1 zit een known issue. Meer informatie hierover is te vinden op deze pagina

Bijlagen