(old) Entra ID (Profile Synchronisation, < v2.5)

This article consists of the following sections:

• General
• Configuration
  • Create an app registration in Azure
  • Create an Azure Automation account  
  • Install the required modules
  • Place and test the script
  • Schedule the script
• Advanced setup
   
  • Group membership
• Troubleshoot

General

The attached PowerShell script enables synchronisation of users from Microsoft Entra ID with Embrace. PowerShell was chosen due to the transparency it offers in the process. Furthermore, PowerShell allows administrators and IT professionals to implement exceptions and other customer-specific customisations themselves. The script can also be run in different ways: as a runbook in Azure Automation or on a local Windows server. 

Location of the script: running as Azure Runbook or local machine

This documentation assumes the script will be used as a runbook within Azure Automation. Of course, there are alternatives to run and schedule the script differently, such as PowerShell in a local environment. In that case, only an app registration is required. The steps for creating a runbook are then not relevant. However, the explanation of the variables used remains unchanged. 

Configuration

The script can be deployed and scheduled within Azure by following these steps:

• Create an app registration in Azure;
• Create an Azure Automation account;
• Create a Runbook within the Automation account;
• Place the script from the attachment in the Runbook;
• Fill in the variables in the script;
• Schedule the script to run at set times.

Create an app registration in Azure

It is possible to use the existing Embrace app registration for Entra ID authentication. However, this registration has too many permissions for performing the push synchronisation. Therefore, we advise creating a new app registration specifically for profile synchronisation.

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

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

• After the app is registered, under Manage choose API permissions
• Then choose +Add permission

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

• Next, go to Certificates & secrets
• Choose New client secret

• Give this new Client secret a recognisable name (for example: ClientSecret for Embrace Social push synchronisation).
• Set the longest possible expiry time (24 months).
• Choose 'Add'.

Create an Azure Automation resource

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

• Fill in the details:

  

  Field	Value
  Subscription	choose which subscription to use
  Resource group	choose a resource group or create a new one
  Automation account name	choose a name e.g. embrace-sync-automation
  Region	choose the nearest location (usually West Europe)

• The other tabs can be left as default (or adjusted if desired).
• Go to Review + Create and choose 'Create'.

Install the required modules 

• Stay within the Automation Account and go to Shared Resources -> Modules.
• Choose add a module. 

• Choose Browse from gallery.
• Select Browse from gallery now.
• Add the following modules:
  • MSAL.PS
  • Microsoft.Graph.Authentication
  • Microsoft.Graph.Users
  • Microsoft.Graph.Groups
• For 'Runtime version', choose the version not marked as preview. At the time of writing, that is version 5.1. Installation may take some time. Refresh the list of installed modules until all modules show the status 'Available'.

Create some Variables within Shared Resources -> Variables (optional)

To avoid using passwords in plain text within the script, it is recommended to use variables. In the PowerShell script, you then refer to the variable name instead of mentioning the value in plain text.

• Stay within the automation account and choose Variables (under Shared Resources)
• Click on Variables
• Choose Add variables

The following variables need to be created:

The name you provide when creating the variables is then used as a reference in the script. 

Create a runbook within the Automation account

• Stay 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'. 

Place the script from the attachment in the runbook

You can download the PowerShell script as an attachment with this article. Once you have done so, you can open it and copy and paste the content into the runbook editor.

• Paste the Embrace script into the editor: (see the attachment at the bottom of this documentation).
• Choose 'save'. 

Fill in the variables within the script

In the script, you need to fill in the following variables to connect to the created App registration

$azAppId     = '' enter the Application (client) ID of the app registration here. 
$azTenantId  = '' enter the ID of the Azure tenant here.

Using the variables from the step above? Then use this value:

$azSecret    = Get-AutomationVariable -Name "azureClientSecretValue" 
 

If you want to use plain text, enter the client secret here

$azSecret    = '' enter the Secret value of the app registration here.

In addition, the following settings need to be filled in. These values are provided by  Embrace: 

$kcTenantId  = '' 

$authClientSecret ''

The script is divided into a "Basic" and an "Advanced" configuration section. Below is a general description of the options. See the script itself for more detailed information.

While configuring the options below, the script can be run multiple times to view the results. Running and testing this script can be done in the "Test pane".

If the result is satisfactory, the variable $upload must be set to $true so that the data is actually sent to Embrace (see further in this document).

Basic
The basic configuration must be executed/checked at a minimum. Configuration consists of correctly filling in a number of PowerShell variables:

About fields and mapping

In principle, we can read all fields from Entra ID and map them to Embrace standard fields. Syncing from Entra ID to Embrace custom fields is not supported yet.

These additional fields are included in the script by default. You can adjust them per customer.

# $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")

Required fields

These fields are enabled by default and are required for a valid synchronization.

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

User extensions

Entra ID offers the possibility to add properties to a user's profile. If you choose to use these 'user extensions' and want to synchronise them with Embrace, that is possible. The name of this property can be included in the other field mappings, for example:

("birthdate", "extension_f946aada8c064232b6753f91f2ca3bf4_BirthDate")

The same applies to custom Embrace profile properties, for example:

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

An Entra ID administrator can provide the correct names of these properties. As far as is known, these properties can only be read via PowerShell. See the following example:

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

Testing the script

• After the variables have been entered in the script, it can be tested in the Azure test pane.
• No errors should occur and the script should display part of the JSON. It also indicates how many users were found. Verify that the number of users is correct and that the JSON contains the data to be sent to Embrace.
• If everything works correctly, the dryRun parameter can be set to $false. Then run the script again in the test pane. The data will then actually be sent to Embrace. No errors should occur. Also check whether the data is correctly processed in Embrace.
• If everything is in order, the script can be published.
• And then the script can be scheduled. 

Troubleshoot
Failed  JWT access code. > Check if the modules with version 5.1 are imported. 

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. > Check if the Runbook is set to version 5.1. 

Schedule the script to run

Create schedule:

• Go to the automation account, choose schedules and add a schedule:

• Create a recurring daily schedule: 

• 
• Choose 'Create'. 

• the variable $dryRun must be set to $false in the script
• then the script must be run once via the "Test pane" and it must be checked in Embrace whether the profile data has been processed correctly
• then the script must be published (edit script and then publish button). 

Link schedule to script:

• For the script, choose 'link to schedule':
  
• Choose 'Link a schedule to your runbook'. 
  
• Choose the previously created schedule.
  
• Choose 'Ok'. 

Advanced setup

Group membership

In the script, you can configure that an M365 EntraID group is automatically made a member of an Embrace group. This can be an intranet group and/or a permission group. For this, use the function $teamMemberships in the profile synchronisation script.

Group membership: intranet group
For 1 intranet group:
$teamMemberships = ,("social/Group: [Name Embrace intranet group] - members", "[Name EntraID group]"

For multiple intranet groups:
$teamMemberships = 
("social/Group: [Name Embrace intranet group] - members", "[Name EntraID group]",
("social/Group: [Name Embrace intranet group] - members", "[Name EntraID group]",
("social/Group: [Name Embrace intranet group] - members", "[Name EntraID group]"

For assigning roles, the best practice is to create a permission group and link a role to it. 
- Create a role >Management >Users >Roles
- Create a permission group >Management >Users >Groups
Then link the created role(s) to the created permission group. 
In the script, we arrange that an M365 Entra ID group is made a member of the created permission group in Embrace via the sync and thus receives the desired role(s).

Group membership: permission group
For 1 permission group:
$teamMemberships = ,("Embrace Suite/[Name Embrace permission group]", "[Name EntraID group]")

For multiple permission groups:
$teamMemberships = 
("Embrace Suite/[Name Embrace permission group]", "[Name EntraID group]"),
("Embrace Suite/[Name Embrace permission group]", "[Name EntraID group]"),
("Embrace Suite/[Name Embrace permission group]", "[Name EntraID group]")

If you want to configure both intranet groups and permission groups, you can combine this. It looks like this, for example:

Group membership: intranet group + permission group
$teamMemberships = 
("social/Group: [Name Embrace intranet group] - members", "[Name EntraID group]",
("social/Group: [Name Embrace intranet group] - members", "[Name EntraID group]",
("social/Group: [Name Embrace intranet group] - members", "[Name EntraID group]",
("Embrace Suite/[Name Embrace permission group]", "[Name EntraID group]"),
("Embrace Suite/[Name Embrace permission group]", "[Name EntraID group]"),
("Embrace Suite/[Name Embrace permission group]", "[Name EntraID group]")

Troubleshoot

• Invalid JWT access token
  For 'Runtime version', choose the version 5.1. Installation may take some time. Refresh the list of installed modules until all modules show the status 'Available'.
• Invalid JWT access token
  If you are using PowerShell 7.2, make sure to downgrade the Microsoft.Graph.Authentication module. Version 2.26.1 contains a known issue. More information about this can be found on this page.