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 or create a new subscription. You need to have an Owner or Contributor role to edit this subscription.

• Global Administrator (or similar) role in the Azure tenant: This is needed to grant the automation account read access to Exchange Online.

• Administrator permissions in Zivver: This is needed to create an API key to connect to Zivver. If your organization uses Role-Based Access Control, this needs to be a full administrator.

Setup

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

1. Click this button to deploy the automation account to Azure:

   

2. 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. The API key gives Cloud Sync access to your Zivver tenant.
   • Included Domains:
     Add all claimed domains in Zivver separated by comma (e.g. domain.com, example.uk). Only mailboxes from domains included here will be synchronized to Zivver.
   • 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, externaldomain.uk).
   • Source Filter:
     Enter the ObjectID of the group to be included in the sync. You can add multiple ObjectID’s to sync users from multiple groups. Only mailboxes that are member of these groups will be synced to Zivver. If the Group Filter is empty, all mailboxes from the Included Domains will by 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.
   • 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).
   • 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, recipient2@example.uk).

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

   

3. Click in the top right corner on the Cloud Shell to start a PowerShell terminal. You don’t need to setup a storage location.
   
   

   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.

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

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

5. 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.

   

6. 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.

   # 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
   

7. To send the email report, Cloud Sync requires permission to send emails for the sending mailbox. Paste the following code in the Cloud Shell:

   # 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
   

8. In the Azure tenant, search Automation Accounts and open the Automation Account called ZivverCloudSync.

   

9. 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 for more information.

12. If you are happy with the proposed changes, you can run the first synchronisation. Navigate to the ZivverCloudSyncLoader runbook and click Start. Add both of 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.
      

    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 left search bar, navigate to Schedules. Click the ZivverCloudSyncSchedule, set Enabled to Yes and click Save.

    

    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.

14. Optional: 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.