Granting access to synchronise Azure AD shared mailboxes

Updated 2 years ago by admin

IMPORTANT: Due to a recent Microsoft Azure update, some customers may not be able to assign the role in step 4 below via the Azure portal. Please see the Command Line steps at the end of the article for an alternative method using Azure CLI or PowerShell.

By default, shared mailboxes synchronised from Azure Active Directory (AAD) are identified as standard users (objectClass=user) which means they are subject to billing. To exclude shared mailboxes from billing, the synchronisation service requires additional permissions to read from the Exchange API.

This article applies to new Azure Active Directory connections. If you already have an existing Azure Active Directory connection, please assign the Office 365 Exchange Online API permission before continuing.
The permission must be granted by the administrator of the Azure Active Directory tenant

To grant the permission:

  1. Sign in to Azure Active Directory
  1. Select Roles and Administrators or use the search feature to quickly find the section.
  1. Search for the Security Reader role
This will grant the Unified Security Service Active Directory sync access to read extended information about Azure AD objects
  1. Click Add Assignments
  1. Search for USS AzureAD and then Add
If the USS AzureAD entry is missing from the search results, ensure that you have created an Azure Active Directory connection within the USS dashboard.

This has now granted the necessary permissions.

If there are existing shared mailboxes then a full synchronisation is required to detect them or alternatively, updating a property of the shared mailbox will force it to update

Role assignment using the Azure CLI

If the Azure portal does not allow you to assign the role to the USS AzureAD application, then the following steps can be performed using the Azure CLI tool.

For further information on Azure CLI, please see the Microsoft documentation (external link).
  1. Start the Azure CLI, for example using a docker container if using that option:

docker run -it mcr.microsoft.com/azure-cli

  1. Log in as a user with permission to assign roles - follow the prompts to open a browser and authenticate the CLI.

az login

  1. Find the Object ID of "USS AzureAD" (this can also be found in Azure > Enterprise Applications > USS AzureAD section)
az ad sp list --all --query "[].{objectId:objectId}" --filter "displayName eq 'USS AzureAD'"
  1. Assign the "Security Reader" role to "USS AzureAD" (where $objectId is the Object ID from step 3)
az rest --method post --url https://graph.microsoft.com/beta/roleManagement/directory/roleAssignments --body "{\"principalId\":\"$objectId\",\"roleDefinitionId\":\"5d6b6bb7-de71-4623-b4af-96380a352509\",\"directoryScopeId\":\"/\"}"

Role Assignment Using PowerShell

  1. Please download and install the AzureAD PowerShell module.
  2. Log in to your tenant as a Global Administrator using the command: Connect-AzureAD
  3. Get the service principal ObjectID using the command: Get-AzureADServicePrincipal
  4. View the Object ID’s of the Azure AD Directory Roles (this outputs the available directory roles): Get-AzureADDirectoryRole | sort DisplayName
  5. Set a directory role to a Service Principal: Add-AzureADDirectoryRoleMember -ObjectId (objectID of the directory role from step 4) -RefObjectId (objectID of the SP from step 3)
  6. Check the current directory roles assigned for the Service Principal: Get-AzureADServicePrincipalMembership -ObjectId(objectID of the SP from step 3)
It may take up to 15 minutes for changes to propagate.

How did we do?