Entra ID profile synchronisation - One-time setup

Embrace automatically populates employee profiles from Microsoft Entra ID. Synchronisation runs via a PowerShell script, usually as a runbook in Azure Automation. This article describes how to set up this environment: from app registration to scheduled execution.

The documentation consists of two parts:

• Part 1 (this article): the one-time setup - app registration, Azure Automation account and runbook.
• Part 2: configuring and maintaining the script - connection details, field mapping, group membership, output and troubleshooting of the synchronisation itself.

This article consists of the following sections:

• General
• Create an app registration in Azure
• Create an Azure Automation account
• Install the required modules
• Create Variables (optional)
• Create a runbook and add the script
• Testing and publishing
• Schedule the script to run
• Troubleshooting

General

The PowerShell script synchronises users from Microsoft Entra ID to Embrace. PowerShell was chosen because of the transparency it provides in the process. In addition, it enables administrators and IT professionals to implement exceptions and customer-specific modifications themselves.

Runbook or local machine

This documentation assumes that the script runs as a runbook within Azure Automation. The script can also be executed and scheduled in another way, for example using PowerShell on a local Windows server. In that case, only the app registration is required; the steps for the Automation account and the runbook do not apply. The configuration of the script (part 2) remains the same.

In summary, you complete the following steps:

• Create an app registration in Azure;
• Create an Azure Automation account;
• Install the required modules;
• Create a runbook within the Automation account;
• Add the script from the attachment to the runbook;
• Configure the script (see part 2);
• Test, publish and schedule the script.

Create an app registration in Azure

It is possible to use the existing Embrace app registration for Entra ID authentication, but that registration has too many permissions for push synchronisation. We therefore recommend creating a new app registration specifically for profile synchronisation.

• Log in to Azure -> https://portal.azure.com
• Click Microsoft Entra ID
• Choose App registrations -> New registration

• Give the app registration a recognisable name, for example: Embrace Social push-synchronisation
• For Supported account types, choose "Accounts in this organisational directory only"
• You do not need to specify a redirect URL
• Choose "Register"

• After registration, under Manage, choose API permissions
• Choose +Add a permission

• Choose Microsoft Graph and add the following application permissions:
  • User.Read.All
  • Group.Read.All
• Then grant Admin Consent using the "Grant admin consent for ..." button

• Then go to Certificates & secrets
• Choose New client secret

• Give the new client secret a recognisable name (for example: ClientSecret for Embrace Social push-synchronisation)
• Select the longest possible expiry period (24 months)
• Choose "Add"

Create an Azure Automation account

• Log in to Azure: https://portal.azure.com
• Click "Create a resource" in the top-left corner
• Search for "Automation" and select it from the list:
  
• Choose Create:
  

• Enter the details:
  

  Field	Value
  Subscription	Choose which subscription should be used
  Resource group	Choose a resource group or create a new one
  Automation account name	Choose a name, for example embrace-sync-automation
  Region	Choose the nearest location (usually West Europe)

• The remaining tabs can be left at their defaults (or adjusted as required)
• Go to Review + Create and choose "Create"

Install the required modules

• Remain in the Automation account and go to Shared Resources -> Modules
• Choose Add a module

• Choose Browse from gallery
• Add the following modules:
  • Microsoft.Graph.Authentication (version 2.0 or higher)
  • Microsoft.Graph.Users
  • Microsoft.Graph.Groups
• For "Runtime version", choose version 5.1. Installation may take some time; refresh the overview until all modules show the status "Available".

Create Variables under Shared Resources -> Variables (optional)

To prevent the client secret from appearing in plain text in the script, we recommend using an Automation variable. In the script, you then refer to the name of the variable instead of the value itself.

• Remain within the Automation account and choose Variables (under Shared Resources)
• Choose Add a variable

Create the following variable:

You then use the variable name as a reference in the script:

$azSecret = Get-AutomationVariable -Name "azureClientSecretValue"

Create a runbook and add the script

• Remain within the Automation account and choose Runbooks (under Process Automation)
• Choose Create a runbook

• Enter a recognisable name, for example embrace-social-push-synchronization
• Runbook type: PowerShell
• Runtime version: 5.1

• Choose "Create"

Then download the PowerShell script (attachment at the bottom of this article), open it, and copy and paste the contents into the runbook editor. Choose "Save".

Testing and publishing

• After configuring the script (part 2), test it in the Test pane of the runbook.
• Leave $dryRun set to $true: the script will then display an example of the output without sending anything. Check the SettingsUsed line (the active configuration), the number of users found and the JSON displayed.
  
• Is everything correct? Set $dryRun to $false and run the script again in the Test pane. The data will now actually be sent to Embrace. Check the summary line (Summary: ...) and verify in Embrace that the profile data has been processed correctly.
• Then publish the runbook (Edit -> Publish).

Schedule the script to run

Creating a schedule:

• Go to the Automation account, choose Schedules and Add a schedule:
  
• Create a recurring daily schedule

• 
• Choose "Create"

• the $dryRun variable in the script is set to $false;
• the script has been run once via the Test pane and it has been verified in Embrace that the profile data has been processed correctly;
• the script has been published (Edit -> Publish).

Link the schedule to the runbook

• For the runbook, choose "Link to schedule":
  
• Choose "Link a schedule to your runbook":
  
• Choose the schedule created earlier:
  
• Choose "OK"

Troubleshooting

• Invalid JWT access token
  Check whether the modules were imported with runtime version 5.1. Installation may take some time; refresh the overview until all modules show the status "Available".
• Invalid JWT access token (PowerShell 7.2)
  If you use PowerShell 7.2, make sure that the Microsoft.Graph.Authentication module is downgraded. Version 2.26.1 contains a known issue; more information is available on this page.
• "The following required PowerShell modules are missing: ..."
  The script indicates which modules are missing. Import these into the Automation account (runtime 5.1), or install them locally using Install-Module.
• "Microsoft.Graph.Authentication version ... was found, but version 2.0 or higher is required"
  An outdated version of the module has been imported. Import a newer version into the Automation account, or update the module locally using Update-Module Microsoft.Graph.Authentication.

Error messages about the configuration or the synchronisation itself are described in part 2: configuring and maintaining the script.