Entra ID profile synchronisation – Setting up and maintaining the script

This article describes setting up and maintaining the Entra ID profile synchronisation script (version 2.5 and higher): the configuration sections, field mapping, group membership and what you see in the output and logs.

The documentation consists of two parts:

• Part 1: the one-time setup – app registration, Azure Automation account, runbook, testing and scheduling.
• Part 2 (this article): setting up and maintaining the script.

This article consists of the following sections:

• The configuration sections
• Field mapping
• Group membership and roles
• Output and logging
• Maintenance: replacing the client secret
• Troubleshooting

The configuration sections

The script is divided into three configuration sections:

• CONNECT – connection details and secrets. 
• BASIC – the options that every customer must fill in at a minimum.
• ADVANCED – optional configuration such as group membership and custom fields.

CONNECT

BASIC

ADVANCED

Order for determining Member/Guest: $forcedGuestGroup takes precedence over $makeAllUsersSocialMembers, which takes precedence over the UserType from Entra ID.

Field mapping ($additionalFields and $customProfileFields)

The mapping is a hashtable: 'Embrace-field-name' = 'Entra ID-field-name'. Each line stands on its own. You can freely enable and disable lines using a # without breaking the configuration.

$additionalFields = @{
    'job-title'      = 'jobTitle'
    'company-name'   = 'companyName'
    'department'     = 'department'
    'displayname'    = 'displayName'
    'hire-date'      = 'employeeHireDate'
    'street-address' = 'streetAddress'
    'office'         = 'officeLocation'
    'city'           = 'city'
    'country'        = 'country'
    'postal-code'    = 'postalCode'
    'office-phone'   = 'businessPhones'
    'mobile-phone'   = 'mobilePhone'
}

You can combine multiple Entra ID fields in one Embrace field by using a list as the value:

'department' = 'company', 'department'

Required fields

These fields are fixed in the script and are required for a valid synchronisation. They do not need to be (and must not be) included in the mapping:

User extensions (extensionAttributes)

Entra ID allows you to add custom properties to a user profile. To include an extensionAttribute in the mapping, set $syncExtensions = $true (under ADVANCED):

$additionalFields = @{
    'profile-birth-date' = 'extension_f946aada8c064232b6753f91f2ca3bf4_BirthDate'
}

The same applies to custom Embrace profile fields:

$customProfileFields = @{
    'hobbies' = 'extension_f946aada8c064232b6753f91f2ca3bf4_Hobbies'
    'skills'  = 'extensionAttribute1'
}

An Entra ID administrator can provide the correct names of these properties. You can also retrieve the names yourself using the PowerShell snippet below (enter the user ID of a test user with extensions):

Import-Module Microsoft.Graph.Authentication
Import-Module Microsoft.Graph.Beta.Users

# General configuration for connecting to Microsoft Entra ID
$azureApplicationId = ''
$azureTenantId = ''
$azureClientSecretValue = ''

# user ID of a test user with extensions:
$userId = ''

# connect to Graph (requires Microsoft.Graph.Authentication 2.0 or higher)
$clientSecretCredential = New-Object System.Management.Automation.PSCredential($azureApplicationId, (ConvertTo-SecureString -AsPlainText -Force $azureClientSecretValue))
Connect-MgGraph -TenantId $azureTenantId -ClientSecretCredential $clientSecretCredential -NoWelcome

$userProperties = Get-MgBetaUser -UserId $userId
Write-Host $userProperties.AdditionalProperties

Transforming values or populating them with a fixed value: the customFields function

If a value must first be modified (for example, a date conversion or language code), or if you want to populate a field with a fixed value, use the customFields function in the script. This function is called for each user and does not require $syncExtensions. Examples:

# Convert date of birth from an extensionAttribute to ISO format:
if (![string]::IsNullOrEmpty($entraUser.ExtensionProperty['extension_..._BirthDate']))
{
    $user.Attributes | Add-Member -type NoteProperty -name "profile-birth-date" -Value ([datetime]::ParseExact($entraUser.ExtensionProperty['extension_..._BirthDate'], 'dd-MM-yyyy', $null)).ToString("o") -Force
}

# Derive language from country:
$lang = "nl"
switch ($entraUser.Country) {
    "GB" { $lang = "en" }
    "DE" { $lang = "de" }
}
$user.Attributes | Add-Member -type NoteProperty -name "language" -Value $lang -Force

# Populate a field with a fixed value (no $syncExtensions or mapping is required for this):
$user.Attributes | Add-Member -type NoteProperty -name "profile-office" -Value 'Head office' -Force

Group membership and roles

In the script, you can configure members of an Entra ID group to automatically become members of a group within Embrace. This can be an intranet group and/or a permissions group.

Both types of groups refer to Access groups in Embrace. The intranet administrator (specific permissions are required for this) must create these Access groups and share the naming with the Entra ID administrator for further processing in the script. See Users – Permissions and roles.

Configure team membership as a hashtable: 'Embrace-team' = 'Entra ID-group-name'. Use / for subgroup paths. You can assign multiple Entra ID groups to the same team by using a list as the value.

Intranet groups

Using Access groups, the intranet administrator creates a mapping for synchronising Entra ID groups to the Social intranet groups:

• Make sure that Entra ID groups may be synchronised (toggle under Management > Group settings)
• Create an Access group: Management > Users > Access groups
• Link the Access group: Synchronisation tab > search for the Social intranet group

$teamMemberships = @{
    'Embrace Suite/[Name of Embrace intranet group]' = '[Name of Entra ID group]'
}

Permissions groups

For assigning roles, the best practice is to create a permissions group and link a role to it:

• Create a role: Management > Users > Roles
• Create a permissions group: Management > Users > Access groups
• Link the created role(s) to the access group

$teamMemberships = @{
    'Embrace Suite/[Name of Embrace permissions group]' = '[Name of Entra ID group]'
}

Combining multiple Entra ID groups into one Embrace group

If members of two (or more) Entra ID groups must be placed in the same Embrace group, specify a list as the value:

$teamMemberships = @{
    'Embrace Suite/[Name of Embrace group]' = '[Name of Entra ID group 1]', '[Name of Entra ID group 2]'
}

The members of both Entra ID groups are combined and deduplicated: a user who belongs to both Entra ID groups becomes a member of the Embrace group once. Conversely, the same Entra ID group may also be used for multiple Embrace groups.

Combining

Intranet groups and permissions groups can be combined in one configuration, and multiple Entra ID groups can refer to the same team:

$teamMemberships = @{
    'Embrace Suite/News'           = 'AD-Employees'
    'Embrace Suite/Editors'        = 'AD-Communications', 'AD-Marketing'
    'Embrace Suite/Testers'        = 'AD-TestGroup'
}

Role membership

Role membership works in the same way; specify a client role as 'client-name/role-name':

$roleMemberships = @{
    'Content Reader'    = 'F_Finance_users'
    'broker/read-token' = 'F_Sales_users'
}

Custom mappings

If you want to assign a team or role based on an Entra ID property instead of group membership, use $customMappings:

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

Output and logging

What exactly does a dry run do?

• Nothing is sent to Embrace.
• Only a sample of $dryRunSampleSize users is retrieved per group. The number of users found shown is therefore not the actual total.
• The deactivation phase ($disableNonProvidedUsers) is skipped entirely during a dry run: because only a sample is retrieved, a preview could incorrectly show users outside the sample.
• All messages are labelled DRY RUN.

SettingsUsed

At the start of every run, the script writes one line containing the complete active configuration (JSON) to both the console and the log:

SettingsUsed: {"scriptVersion":"2.5","dryRun":true,"entraGroup":"...","additionalFields":[...],...}

Connection details and secrets from the CONNECT section are, of course, not included here. Use this line to check whether the configuration is what you expect. Embrace can use this information when debugging issues

Summary at the end of the run

Summary: 143 users created or updated, 2 skipped (missing first name, last name or email), 5 users disabled, duration 00:04:12

If WARNING: ... sync calls failed appears afterwards, look higher up in the output for the FAILURE messages.

Maintenance: replacing the client secret

The client secret of the Azure app registration has a limited validity period (maximum 24 months). If the secret has expired, synchronisation fails immediately at startup with an Azure error message such as AADSTS7000222: The provided client secret keys ... are expired.

Replace the secret as follows:

1. In Azure (portal.azure.com), go to Microsoft Entra ID -> App registrations and open the app registration for the profile synchronisation.
2. Go to Certificates & secrets and select New client secret. Enter a recognisable name, choose an expiry period (for example, 24 months) and select Add.
3. Copy the secret value immediately: it is shown only once.
4. Update the value where the script reads it:
   • If you use an Automation variable (recommended): update the value of azureClientSecretValue under Shared Resources -> Variables in the Automation account. The script itself does not need to be changed.
   • If the secret is entered directly in the script: replace the value of $azSecret in the CONNECT section of the runbook and publish the runbook again.
5. Delete the expired secret from the app registration and check the synchronisation with a dry run ($dryRun = $true) or during the next scheduled run.

The $authClientSecret (used to send data to Embrace) does not expire on a fixed date; it is provided by Embrace and only needs to be replaced if Embrace requests this.

Troubleshooting

• "$additionalFields must be configured as a hashtable ..."
  You are still using the configuration syntax from a script version older than 2.5. Convert the configuration to the hashtable syntax; see Field mapping.
   
• "ME-ID Group '...' not found (configured in $teamMemberships)"
  The specified Entra ID group does not exist or is spelled differently. The message indicates which configuration option uses the group.  
• "WARNING: First name, Last name and Email cannot be empty. Skipping user ..."
  The user is missing a required field in Entra ID and is skipped. Fill in the field in Entra ID and run the synchronisation again.  
• "AADSTS7000222: The provided client secret keys for app ... are expired"
  The client secret of the Azure app registration has expired. See Maintenance: replacing the client secret.
   
• "The following required PowerShell modules are missing: ..." or "Microsoft.Graph.Authentication version ... 2.0 or higher is required" See the troubleshooting section of part 1: the one-time setup.

Error messages about the Azure environment (modules, runtime, JWT) are described in part 1: the one-time setup.

Attachments

Download the latest version of the profile synchronisation script below: