User Sync Script via Azure Runbook Automation

1. Setting up the Azure Automation Account Runbook

Azure Runbooks are part of the Azure Automation service that allows you to automate frequent, time-consuming, and error-prone cloud management tasks. One of the several types of runbooks is PowerShell which is what we use for our User Synchronization. The script in the Runbook can be directly edited in the Runbook from the Azure Portal or imported from a text editor into the Azure Automation Runbook.

In order to start using the PowerShell Runbook, an Azure Automation Account needs to be created following the guide: Quickstart - Create an Azure Automation account using the portal | Microsoft Learn

2. Enable Managed Identity for the Azure Automation Account

If you already have the Automation Account created, when you go to your Azure Automation resource, follow the next steps to enable Managed Identity:

  • Click on Identity on the left pane.
  • Ensure the System assigned tab is selected
  • Toggle the status from 'off' to 'on'
  • Copy the object (principal) ID to a notepad. This will be used later.
  • Click Save.

3. Grant Permissions to the Managed Identity

When a managed identity is created, it starts off with a clean slate and no permissions. This means that you will need to grant permissions to the resources that it needs to interact with. In our case, we need to grant the managed identity from our Automation account access to read as well as run jobs from the Azure Automation Runbook. More importantly, we need to know how to grant the managed identity permissions to Graph API. Since Azure Automation Runbooks don’t require a secret or certificate to connect to Graph API, this is ideal and the most secure way since we’re letting Azure handle all the authentication process in the cloud. While in the Identity tab:

  • Open the cloud shell terminal
  • Run the following Commands
$ServicePrincipalId = '041faf65-xxxx-xxxx-xxxx-xxxxxxxxxxxx' #fill the Object principal ID that you copied before
$GraphResource = Get-AzureADServicePrincipal -Filter "AppId eq '00000003-0000-0000-c000-000000000000'"
  • Run
$Permission1 = $GraphResource.AppRoles | Where-Object {$_.value -eq 'User.Read.All'}
New-AzureADServiceAppRoleAssignment -ObjectId $ServicePrincipalId -PrincipalId $ServicePrincipalId -Id $Permission1.Id -ResourceId $GraphResource.ObjectId
  • Run
$Permission2 = $GraphResource.AppRoles | Where-Object {$_.value -eq 'Group.Read.All'}
New-AzureADServiceAppRoleAssignment -ObjectId $ServicePrincipalId -PrincipalId $ServicePrincipalId -Id $Permission2.Id -ResourceId $GraphResource.ObjectId
  • Run
$Permission3 = $GraphResource.AppRoles | Where-Object {$_.value -eq 'GroupMember.Read.All'}
New-AzureADServiceAppRoleAssignment -ObjectId $ServicePrincipalId -PrincipalId $ServicePrincipalId -Id $Permission3.Id -ResourceId $GraphResource.ObjectId


After running the commands the permissions granted for the Service Principal can be viewed

  • Azure AD
  • Enterprise Applications
  • Application name should be the name of the created Automation Account
  • Select Permissions on the left hand scroll panel


4. Install the Required Modules for the Runbook

In order for the script to run properly, a couple of required modules are needed to be installed for the Runbook.

The module can be found while in the Automation Account:

  • On the left pane click Modules

  • Click Browse Gallery

  • Search and select the following modules 
    • BrightBookingUserAdminTools - Tags: GoBright BrightBooking active-directory azuread PSModule
    • Microsoft.Graph.Applications
    • Microsoft.Graph.Authentication
    • Microsoft.Graph.Groups
    • Microsoft.Graph.Identity.DirectoryManagement
    • Microsoft.Graph.Users
    • Microsoft.Graph - Do this one last
  • Chose the Runtime Version 7.2
  • Click Import


5. Create the Runbook and Script

In this section the Runbook will be created and the User Sync Script and Schedule configured

  • On the left panel of the Automation Account select Runbooks
  • Create a Runbook
  • Write the name for your Runbook
  • Select Powershell type
  • Select 7.2 version
  • Create

When the created Runbook is selected, press Edit, Edit in Portal.

Add the following script and change the details in the brackets and Publish it when done.

Also you can select the Test Pane and start the test of the script to see if it works properly.

#Get the token using a managed identity and connect to graph using that token
Connect-AzAccount -Identity -ErrorAction Stop | Out-Null
$AccessToken = Get-AzAccessToken -ResourceTypeName MSGraph -ErrorAction Stop | select -ExpandProperty Token | ConvertTo-SecureString -AsPlainText -Force
Connect-Graph -AccessToken $AccessToken -ErrorAction Stop | Out-Null
$includedGroups = @()
$includedGroups += '[your AzureAD groupname here]'
# get the list of userid's in the group
$groups = Get-MgGroup -All | Where-Object { $includedGroups -contains $_.DisplayName }
$users_in_groups_userids = @();
Foreach ($group in $groups) {
   $groupMembers = Get-MgGroupMember -All -GroupID $
   Foreach ($groupMember in $groupMembers) {
       $users_in_groups_userids +=
# get the required details of those users
$users_full_list = Get-MgUser -All -Select Id,DisplayName,Mail,UserPrincipalName,AccountEnabled,MobilePhone,AssignedLicenses
$users = $users_full_list | Where-Object { $users_in_groups_userids-contains $_.Id }
Write-Output "Loaded from AzureAD: $(($users | Measure-Object).Count) users"
# define the mapping of groups to roles
$groupToRoleMapping = @()
$groupToRoleMapping += @{AzureADRoleName = '[your AzureAD groupnamehere]'; RoleName = "[your GoBright Role name here]"; RoleType = "MWV"} # match specific users that belong to a group for Meet-Work-Visit
$users | Push-AzureADUsersToBB -DeactivateExistingUsersInSameIntegrationThatAreNotLoaded -GroupUserRoleMapping $groupToRoleMapping -BrightBookingApiUrl '[API url]' -BrightBookingApiKey '[API key]' -BrightBookingIntegrationName '[name of integration as created in Admin center > Integrations]'



6. Create a Scheduled Task for the Runbook

Within the created Runbook on the left panel select Schedules

  • Add a Schedule
  • Schedule – Link a schedule to your Runbook
  • Add a Schedule
  • Name of the Schedule
  • Description
  • Start date/time of the schedule
  • Add Recurrence
  • Expiration
  • Create

Go back to the Runbook and on the top panel select Link to Schedule and Select the created Schedule.


7. Create a Metric Alert to be notified when the Runbook Job fails

Azure Automation has the ability to check if a Runbook Job/Schedule has failed to run and you can create a custom alert for a group to be notified whenever that happens. You can find how to do that on the following article: Azure Automation Metric Alert


0 out of 0 found this helpful