Automated user sync options in Emailgistics

This document describes the steps needed to automate the Emailgistics user sync process, which updates Emailgistics to reflect added and removed shared mailbox users. Instead of having to download a script and run it manually each time, following these steps will let you set up an automated process to do the sync at a schedule and frequency of your choosing.

: To enable unattended, non-interactive execution of the user sync script, authentication will be done by means of a certificate that you control. The script will use the certificate to connect to the app registration you create in the next step and the app’s configuration will determine the permissions the script has.

You may use any active certificate that you have. For example, the SSL certificate for your website can be used. You will need the cert in two formats: .cer or .crt (without the certificate’s private key) and .pfx (which contains the private key).

The .pfx file will be protected with a password, which you will need to know.

If you don’t have a certificate, you can obtain one from a certificate authority or generate a self-signed certificate yourself.

As mentioned above, the sync script will use your certificate to connect to an app registration in Azure. The app will determine what permissions the script has. In this section, we will create and configure that app.

As you go through the steps in this section you will be collecting three pieces of information that will be used later:

Primary domain
Application (client) ID
Certificate thumbprint

Have a Notepad document or other place ready to store this information.

Log in to the Microsoft Azure portal as an administrator: (Application.ReadWrite.All permission required).
Search for “Microsoft Entra ID” in the top search bar and select it.: (Microsoft Entra ID was previously known as Azure Active Directory.)
In the Overview section, copy the Primary domain value and paste it into your Notepad document.
Navigate to the App registrations section in the left side menu and click “New registration” to create a new app registration.
Select the new app from the list of applications. Find the “Application (client) ID” in the Overview section of the application and copy and paste it into your Notepad document.
Navigate to the Certificates & secrets section for the new app and click “Upload certificate”.
Locate the certificate .cer or .crt file from the previous section and upload it.
Copy and paste the certificate Thumbprint value into your Notepad document.
Navigate to the API permissions section and add the following permissions: a. Microsoft Graph > User.Read (this one may already be shown)
b. Office 365 Exchange Online > Exchange.ManageAsApp
Grant Admin consent for all permissions.
Next, we’ll assign the Exchange Administrator role to the app. In the search bar at the top, search for “roles and admin” and select “Microsoft Entra ID roles and administrators” from the dropdown.
In the search bar on this page, enter “exchange admin” and then select the “Exchange Administrator” option that appears by clicking on the name of the role (not the checkbox). You will be directed to the “Exchange Administrator | Assignments” page.
Click “Add assignments” and search for your app. Click the checkbox for your app and then click “Add”. Your app is now completely configured to be used by the user sync script.

With the certificate in hand and the app registration created, you’re now ready to This section describes how to set up the user sync script to run automatically on a Windows 10 system.

Install the certificate

On the computer that will run the script, open the Manage Computer Certificates control panel.
Right-click the Personal store and choose All Tasks > Import.

Install the certificate

Click Next.
Click Browse.
Choose the Personal Information Exchange file type.
Select the .pfx file containing your certificate and click Open.
Click Next.
Enter the password for the .pfx file and click Next.
Ensure the Personal certificate store is selected and click Next.
Click Finish.

Download, configure, and test a multi-use user sync script

Log in to Emailgistics Admin with a Billing or System Admin account.
Click Users in the menu on the left.
At the bottom of the user list, click Sync Users and select “Multi-use sync scripts”.
Enter a name for the script and choose an expiry date. Shorter expiry values are more secure. It’s a good idea to create a reminder to download a new sync script in advance of the expiry date.
Click the checkmark to create and download the script.
Expand the downloaded .zip file and move the resulting syncUsers folder to your desired location on the system that will be running the script.
In the folder, find and open the customerData.json file and open it in a text editor.
Copy the following and paste it into the document, at the start of the line immediately after the opening brace ( { ).
Test the script by running it in PowerShell:: a. Open Windows PowerShell.
b. cd to the syncUsers folder from Step 6 above.
c. Type .\syncUsers.ps1 and press Enter.

You should see that the script is running in non interactive mode and that it completes successfully without asking you to log in.

If any errors are displayed, correct the issues reported and try again. Contact [email protected] if you have any questions.
Test the script by running it in PowerShell:: a. Open Windows PowerShell.
b. cd to the syncUsers folder from Step 6 above.
c. Type .\syncUsers.ps1 and press Enter.

You should see that the script is running in non interactive mode and that it completes successfully without asking you to log in.

If any errors are displayed, correct the issues reported and try again. Contact [email protected] if you have any questions.