# Prerequisites and setup

## Prerequisites

Please make sure you meet the following requirements before starting the installation of Cloud Sync:

- **An active subscription in the Azure tenant**: You can use an existing [subscription in Azure](https://portal.azure.com/#view/Microsoft_Azure_Billing/SubscriptionsBladeV2) or create a [new subscription](https://learn.microsoft.com/en-us/azure/cost-management-billing/manage/create-subscription). You need to have the Owner or Contributor role to edit this subscription.

- **Global Administrator (or similar) role in the Azure tenant**: Required to grant the automation account [read access to Exchange Online](https://learn.microsoft.com/en-us/powershell/exchange/connect-exo-powershell-managed-identity?view=exchange-ps).

- **Administrator permissions in Zivver**: Required to create an [API key](https://app.zivver.com/organization/api-keys) to connect to Zivver. If your organization uses [Role-Based Access Control](https://docs.zivver.com/en/admin/webapp/references/set-admin-roles.html), this needs to be a full administrator account.

- **Claimed all domains that receive email**: See [How to claim a domain in Zivver](https://docs.zivver.com/en/admin/webapp/references/how-to-claim-a-domain.html) for instructions on claiming your domains.

- **_Optional_: Create a source filter group**: Create a (security) group in Azure if you want to synchronize only part of the mailboxes in the tenant. See the [Cloud Sync FAQ](https://docs.zivver.com/en/admin/cloudsync/faq.html) to check which types of groups are supported.

Warning

Before proceeding with the implementation of Zivver Cloud Sync, please [check your IdP](https://docs.zivver.com/en/admin/cloudsync/check-zivveraccountkey-entra-id.html) to ensure that `user.objectid` is used as the value for `ZivverAccountKey`. Correct configuration of `ZivverAccountKey` is required for Cloud Sync to work properly.

## How to set up Cloud Sync

Setup Instructions Zivver Cloud Sync - YouTube

Tap to unmute

[Setup Instructions Zivver Cloud Sync](https://www.youtube.com/watch?v=Gnn_ZTEpVgc) [Zivver](https://www.youtube.com/channel/UCkUmayjA6YaDrwKtuQknleA)

Zivver209 subscribers

Please [watch the video directly on YouTube](https://youtu.be/Gnn_ZTEpVgc) if the video isn’t loading on this page.

## Setup

This manual describes the steps to set up Cloud Sync in Azure.

Warning

**Review results before performing synchronization**

Check synchronization results carefully before performing the synchronization. Please [inform us](https://support.zivver.com/s/contactsupport?language=en_US) if you experience any issues.

01. Click this button to deploy the automation account to Azure:
     
02. Login to your Azure administrator account. Fill in the fields of the form:

- _Subscription, Resource Group and Region_:

This is the location where the Azure Automation account for Cloud Sync will be placed in your Azure tenant.
    - _Zivver Api Key_:

Paste the API key that you generated in the Zivver [administrator portal](https://app.zivver.com/organization/api-keys). The API key gives Cloud Sync access to your Zivver tenant.
    - _Daily Start Time UTC_:

Add the time that Cloud Sync should start on a daily basis in UTC. Choose a time that is outside of office hours for your organization.
    - _Target Filter_:

Specific mailboxes or domains entered will not be changed in Zivver. Use this filter if your Zivver admin account does not exist in the Exchange Online tenant. Separate values by comma (e.g. [admin@it-supplier.com](mailto:admin@it-supplier.com), externaldomain.uk).
    - _Source Filter_:

Enter the ObjectID of the group to be included in the sync. You can add multiple ObjectIDs to sync users from multiple groups. Only mailboxes that are members of these groups will be synced to Zivver. If the Group Filter is empty, all mailboxes from the Included Domains will be synchronised. Separate values by comma (e.g. b74fd2c0-3d1a-4b7a-bc88-123456789abc, e5b3d8e2-f3b4-4a8d-9b7d-abcdef123456). Find the Object ID(s) of groups by navigating to Groups in the [Azure Portal](https://portal.azure.com/#view/Microsoft_AAD_IAM/GroupsManagementMenuBlade/~/AllGroups).
    - _Email Report Sender_:

Enter the mail address of the sender of the email report. This should be a mailbox in the tenant (e.g. [sender@domain.com](mailto:sender@domain.com)).
    - _Email Report Recipients_:

Enter the mail address(es) of the recipient(s) of the email report. This can also be mailboxes outside of the tenant. Separate values by comma (e.g. [recipient1@domain.com](mailto:recipient1@domain.com), [recipient2@example.uk](mailto:recipient2@example.uk)).
    - _Organizational Units Domains_:

Enable if you use organizational units that are based on the primary email addresses of mailboxes in Exchange Online. Each domain that corresponds to an organizational unit should be set as the OU-identifier in the [Zivver Admin Portal](https://app.zivver.com/organization/units). Do not use in combination with _Organizational Units Groups_.
    - _Organizational Units Groups_:

Enable if you use organizational units that are based on a specified security group. The UUID of each group that is used for this must be added as the OU-identifier of the corresponding organizational unit in the [Zivver Admin Portal](https://app.zivver.com/organization/units). Do not use in combination with _Organizational Units Domains_.

Click Review + Create and on the next screen click Create.

03. Click in the top right corner on the _Cloud Shell_ to start a PowerShell terminal. You don’t need to set up a storage location.

Warning

**Other Powershell terminals not recommended**

It is not recommended to use other PowerShell terminals than the Cloud Shell. The suggested PowerShell code may fail due to missing modules or authentication functionalities.

04. To authenticate and start setting up the correct permissions, paste the following code in the terminal and hit **Enter**:

```powershell
    # Allow Graph Command Line Tools
    Connect-MgGraph -Scopes AppRoleAssignment.ReadWrite.All,Application.Read.All,RoleManagement.ReadWrite.Directory
    ```

05. Allow _Microsoft Graph Command Line Tools_ by following the steps suggested when you see in the Cloud Shell: `To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code [123456] to authenticate.`

06. After successful authentication, run the below Powershell code to assign read permissions to Exchange Online. Verify that all code executed successfully. **Do not close the Cloud Shell as you will need it for the next step.**

```powershell
    # Get the ID of the Managed Identity
    $ResourceId = (Get-AzADServicePrincipal -DisplayName "ZivverCloudSync").Id

# Assign API permissions Exchange Online
    $AppRoleId = "dc50a0fb-09a3-484d-be87-e023b12c6440"
    $MsOfficeId = (Get-MgServicePrincipal -Filter "DisplayName eq 'Office 365 Exchange Online'").Id

New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $ResourceId -PrincipalId $ResourceId -AppRoleId $AppRoleId -ResourceId $MsOfficeId

# Assign the Global Reader role
    $RoleID = (Get-MgRoleManagementDirectoryRoleDefinition -Filter "DisplayName eq 'Global Reader'").Id

New-MgRoleManagementDirectoryRoleAssignment -PrincipalId $ResourceId -RoleDefinitionId $RoleID -DirectoryScopeId "/"

# Assigned permissions to read from Exchange Online
    ```

Tip

Do you get the error `[Could not load file or assembly 'Microsoft.Graph.Authentication, Version=2.26.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35'. Assembly with same name is already loaded]`? run the following commands in the Cloud Shell to fix this:

```powershell
Get-InstalledModule Microsoft.Graph* | Uninstall-Module -Force
Remove-Module Microsoft.Graph* -Force
Install-Module Microsoft.Graph -AllowClobber -Force
```

07. To send the email report, Cloud Sync requires [permission to send emails](https://learn.microsoft.com/en-us/graph/auth-limit-mailbox-access) for the sending mailbox. Paste the following code in the Cloud Shell:

```powershell
# Connect to Exchange Online
Connect-ExchangeOnline

# Create a mail enabled security group with only the Sender as member
$AutomationAccount = Get-AzResource -ResourceType "Microsoft.Automation/automationAccounts" | Where-Object { $_.Name -eq 'ZivverCloudSync' }

$sender = Get-AzAutomationVariable -AutomationAccountName $AutomationAccount.Name -Name "CLOUD_SYNC__EMAIL_REPORT_SENDER" -ResourceGroupName $AutomationAccount.ResourceGroupName

$mesg = New-DistributionGroup -Name "Zivver Cloud Sync Mail Report" -Members $sender.value -Type "Security"

# Restrict Mail.Send Permission to only this security group
New-ApplicationAccessPolicy -AppId $ResourceId -PolicyScopeGroupId $mesg -AccessRight RestrictAccess -Description "Restrict Mail.Send permission for Zivver Cloud Sync."

# Assign Graph API Mail.Send Permission to the Managed Identity
$AppRoleId = "b633e1c5-b582-4048-a93e-9f11b44c7e96"
$MsOfficeId = (Get-MgServicePrincipal -Filter "DisplayName eq 'Microsoft Graph'").Id

New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $ResourceId -PrincipalId $ResourceId -AppRoleId $AppRoleId -ResourceId $MsOfficeId

# Assigned permissions to send email from a specific mailbox
```

08. In the Azure tenant, search **Automation Accounts** and open the Automation Account called _ZivverCloudSync_.

09. In the Automation Account, search **Runbooks** and open the _ZivverCloudSyncLoader_ runbook.

10. In the runbook, click **Start** and then OK. Cloud Sync will now run a preview without making any changes.

11. Wait a few minutes and validate the accounts to be created, updated and disabled that Cloud Sync proposes in the **Output** tab or in the email report. Any warnings or errors are displayed under **Warnings** and **Errors**. Read the [troubleshooting documentation](https://docs.zivver.com/en/admin/cloudsync/troubleshooting.html) for more information.

12. If you are happy with the proposed changes, you can run the first synchronization. Navigate to the _ZivverCloudSyncLoader_ runbook and click **Start**. Add the following two parameters:

- `perform_sync`: this ensures that the sync is not in preview anymore.
    - `allow_large_sync`: this is needed because this is the first sync. Without this parameter, Cloud Sync will not allow creating, updating, or suspending more than 10% of the accounts.

Optionally, you can add the following parameters to split the synchronization jobs for user mailboxes and shared mailboxes. This approach is useful, for example, when applying specific filters or when you have a large number of mailboxes and may run into Microsoft’s fair use policy of a maximum 3-hour runtime per job.

- `sync_users`: this ensures only user mailboxes are synced.
    - `sync_groups`: this ensures only shared mailboxes are synced.

Click OK and the synchronization will create and update the accounts in Zivver.

13. If you are happy with the proposed changes, you can enable the schedule. In the _ZivverCloudSyncLoader_, click **Link to schedule**.

14. Click **Schedule** and link the runbook to the _ZivverCloudSyncSchedule_.

15. Click **Configure parameters and run settings** and add the `perform_sync` parameter. Click OK.

Cloud Sync will now run automatically on a daily basis. If you have enabled the email reports, an email report will be sent after every run.

16. **Recommended**: If everything was set up successfully, the _Microsoft Graph Command Line Tools_ are not needed anymore. You can remove them by navigating to **Enterprise Applications**. In this section, search the _Microsoft Graph Command Line Tools_ application and verify that the creation date is the day of this Cloud Sync setup (to ensure the application was not created earlier for something else). Open the application and delete it.

Updated on 2026-07-03