GALSync Admin Guide
Keep your Global Address Lists synchronized across Microsoft 365, Google Workspace, and Exchange On-Premises.
Introduction
GALSync (Global Address List Synchronization) is a Cloudiway solution that keeps address books synchronized across different mail platforms. It automatically creates users and groups from one tenant as contacts, mail users, or guest users in another tenant.
This guide is intended for system administrators who need to configure GALSync between cloud platforms. While the Cloudiway interface is user-friendly, GALSync setup requires familiarity with mail systems, directories, and administrative consoles.
Key Benefits
- No Installation Required: Configure GALSync entirely through the web-based platform
- Automatic Synchronization: Schedule sync intervals to keep address books up to date
- Bi-directional Support: Synchronize in both directions between tenants
- Granular Filtering: Select specific domains, groups, or organizational units to sync
- Simulation Mode: Preview changes before applying them
Enterprise Coexistence Solution
GALSync is part of our Enterprise Coexistence offering, which also includes Free/Busy synchronization for calendar availability.
View Enterprise CoexistenceSupported Platforms
GALSync works with any combination of the following platforms:
Synchronization Scenarios
- Microsoft 365 ↔ Microsoft 365 (tenant-to-tenant)
- Microsoft 365 ↔ Google Workspace
- Microsoft 365 ↔ Exchange On-Premises
- Google Workspace ↔ Google Workspace
- Multi-tenant synchronization (3+ tenants)
How GALSync Works
GALSync operates through a two-step synchronization process: Pull and Push.
Pull from Source
GALSync extracts users and groups from the source tenant and stores them in Cloudiway's internal cache. Only users and groups are pulled - existing contacts and guest users are not extracted.
Push to Target
The cached data is pushed to the target tenant, creating objects as Contacts, Mail Users, or Guest Users based on your configuration.
Target Object Types
| Type | Description | Use Case |
|---|---|---|
| Mail Contact | Adds email address to address book only | Long-term coexistence with no migration planned |
| Mail User | Creates mail-enabled user that can be converted to mailbox | Pre-migration preparation (add license later to migrate) |
| Guest User | Creates Azure AD guest user | Allow access to Teams and SharePoint in target tenant |
Prerequisites
Before configuring GALSync, ensure you have the following:
Cloudiway Account
An active Cloudiway account with GALSync subscription.
Admin Access
Microsoft 365: Limited Exchange admin permissions (see below). Google Workspace: Super Admin access.
Service Account (Google)
Domain-wide delegation configured for the Cloudiway service account.
Microsoft 365 Requirements
GALSync does not require Global Administrator access for Microsoft 365. You can create a custom role group with limited permissions:
Access Exchange Admin Center
Go to admin.exchange.microsoft.com and navigate to Roles > Admin roles.
Create New Role Group
Click Add role group and provide a name (e.g., "GalSync") and description.
Configure Role Group
Set the Write scope to Default and assign the following roles:
- Address Lists
- Mail Recipient Creation
- Mail Recipients
Assign Members
Add the service account that will be used for the Cloudiway connector to this role group.
Google Workspace Requirements
- Super Admin access to Google Admin Console. The Google service account needs to be a super admin and requires a valid Google user license.
- Domain-wide delegation enabled for API access
- Required API scopes authorized for Cloudiway
Step 1: Create Connectors
Connectors enable Cloudiway to communicate with your source and target tenants. Each connector is multi-directional and can be used for both pulling and pushing data.
Create a Microsoft 365 Connector
Navigate to Connectors
In the Cloudiway platform, go to Connectors and click Add Connector.
Select Connector Type
Choose Microsoft 365 as the connector type.
Enable GALSync
In the Coexistence Products section, make sure to select GALSync.
Authenticate
Enter your service account credentials and complete the OAuth authentication flow.
Create a Google Workspace Connector
Add Google Connector
Click Add Connector and select Google Workspace.
Choose Service Account Option
Select either Cloudiway's predefined service account (faster) or create your own custom service account (more control).
Configure Domain-Wide Delegation
In Google Admin Console, authorize the required API scopes for the service account:
- https://apps-apis.google.com/a/feeds/user/
- https://apps-apis.google.com/a/feeds/groups/
- https://apps-apis.google.com/a/feeds/policies/
- https://www.google.com/m8/feeds/
- https://apps-apis.google.com/a/feeds/alias/
- https://www.googleapis.com/auth/admin.directory.user
- https://www.googleapis.com/auth/admin.directory.user.readonly
- https://www.googleapis.com/auth/directory.readonly
- https://www.googleapis.com/auth/contacts
Enable GALSync
Ensure GALSync is selected in the Coexistence Products.
Step 2: Configure GALSync
Once connectors are created, configure the GALSync settings for each connector.
Access Configuration
- Navigate to GALSync > Configuration
- Select the connector you want to configure
- Configure the settings for this connector
The configuration wizard guides you through 6 steps:
- Common Data: General connector settings
- Pull Options: Configure what to extract from the source
- Pulling Filters: Filter users and groups to synchronize
- Push Options: Configure how objects are created in the target
- Push Customizations: Advanced push settings
- End: Summary: Review and save configuration
Microsoft 365 Configuration
When configuring a Microsoft 365 connector, the following options are available:
Common Data (Step 1)
Tenant
| Tenant Name | Your Microsoft 365 tenant identifier. |
| Server Region | Select the Azure region (Azure Public, Azure Government, etc.). |
| Domain Names | The domains associated with this tenant. |
Azure Active Directory Application
| Client ID | The Application (client) ID from Azure AD app registration. |
| Client Secret Value | The secret value generated for the Azure AD application. |
Administrator Account
| Administrator Account | The admin account email address for the tenant. |
| Administrator Password | The password for the administrator account. |
Pull Options (Step 2)
Pull Options
| Pull groups | Enable to extract groups from the source tenant in addition to users. |
| Pull disabled users | Enable to include disabled user accounts in the synchronization. |
Pull Members
| Pull specific groups | Enter group names to pull only members of these specific groups. |
| Exclude specific groups | Enter group names to exclude their members from synchronization. |
Pulling Filters (Step 3)
If you don't want to pull the entire directory, you can specify filters to synchronize only the users and groups of your choice.
The filters are based on attributes that match conditions:
- Equals
- DoesNotEqual
- Contains
- DoesNotContain
- StartsWith
- DoesNotStartWith
- EndsWith
- DoesNotEndWith
- MatchRegex
- DoesNotMatchRegex
- DateAfter
- DateBefore
Use pulling filters to create advanced rules for selecting which users to synchronize:
| NAME | Select the attribute to filter on (e.g., department, company, email). |
| RULE | Choose the comparison operator (Equals, Contains, StartsWith, etc.). |
| VALUE | Enter the attribute value to match against. |
| ACTIONS | Remove the filter rule. Use the + button to add additional filter rules. |
Push Options (Step 4)
Push Type
| Create as Mail Contact | Creates contacts with email addresses visible in the Global Address List. |
| Create as Mail User | Creates mail-enabled users that can be converted to full mailboxes later (useful for migrations). |
| Create Guest User | Creates Azure AD guest users for Teams and SharePoint access. |
Push Options
| Push Groups | Enable to publish group email addresses as contacts in the target tenant. |
| Push Empty Fields | When enabled, empty source fields will clear corresponding target fields. |
Deletion Rules
| Propagate deletion | When enabled, objects deleted from source are removed from target on next sync. |
| Propagate deletion and disabled user | Also removes target objects when source users are disabled. |
| Do not delete | Never delete objects from the target tenant. |
Push Customizations (Step 5)
User Customization
| Proxy addresses | Synchronize all email aliases (proxy addresses) to the target. |
| Postal Address | Synchronize physical address information. |
| Phone Numbers | Synchronize phone number fields. |
| Organization Information | Synchronize department, company, and job title information. |
Group Customization
| Proxy Addresses | Synchronize all email aliases for groups. |
Option
| Clear Cache After Push | Clear the internal cache after push completes. Useful for one-time synchronizations. |
Google Workspace Configuration
When configuring a Google Workspace connector, the following options are available:
Pull Options (Step 2)
Pull Options
| Pull groups | Enable to extract groups from Google Workspace in addition to users. |
| Pull disabled users | Enable to include suspended user accounts in the synchronization. |
Pull Members
| Pull specific groups | Enter group names to pull only members of these specific groups. |
| Exclude specific groups | Enter group names to exclude their members from synchronization. |
Pulling Filters (Step 3)
Use pulling filters to create advanced rules for selecting which users to synchronize:
| NAME | Select the attribute to filter on (e.g., department, orgUnitPath, email). |
| RULE | Choose the comparison operator (Equals, Contains, StartsWith, etc.). |
| VALUE | Enter the attribute value to match against. |
| ACTIONS | Remove the filter rule. Use the + button to add additional filter rules. |
Push Customizations (Step 4)
User Customization
| Phone Numbers | Synchronize phone number fields to the target. |
| Postal Address | Synchronize physical address information. |
| Organization Information | Synchronize department, company, and job title information. |
| IMs | Synchronize instant messaging addresses (Hangouts, Skype, etc.). |
Option
| Clear Cache After Push | Clear the internal cache after push completes. Useful for one-time synchronizations. |
Step 3: Push Configuration
Configure how objects are created in the target tenant.
Push Operations
Push takes the cached data from Pull and creates/updates objects in the target:
- Creates new Contacts, Mail Users, or Guest Users
- Updates existing objects with changes
- Optionally deletes objects that no longer exist in source
Display Options
- Show in Address Book: Objects appear in the Global Address List
- Hide from Address Book: Objects are created but hidden from GAL
Step 4: Run Synchronization
Execute the synchronization manually or use simulation mode to preview changes.
Navigate to GALSync > Actions and select a job type from the dropdown. You must also select the Source connector to run the action on.
Available Actions
| Pull | Extracts users and groups from the source tenant and stores them in Cloudiway's internal cache. |
| Clear Cache | Clears the internal cache. Use this to reset the synchronization state and start fresh. |
| Simulate | Previews the changes that would be made without actually applying them. Recommended before running Push. |
| Push | Creates or updates objects (contacts, mail users, guest users) in the target tenant based on cached data. |
| Delete Contacts | Removes all contacts created by GALSync from the target tenant. Use with caution. |
Data Discovery
After running a Pull action, navigate to GALSync > Data Discovery to view and explore the objects that have been extracted from the source tenant.
Select a source connector from the dropdown to view the pulled objects. Each object displays a status icon indicating its synchronization state:
| Created | Object was created in the target tenant. |
| Modified | Object was updated in the target tenant. |
| Pending Creation | Object will be created on next Push. |
| Pending Modification | Object will be updated on next Push. |
| Pending Delete | Object will be deleted on next Push (if propagate deletion is enabled). |
| Deleted | Object was deleted from the target tenant. |
| Not Modified | Object exists and requires no changes. |
| Programmatically Filtered | Object excluded by filter rules in configuration. |
| Manually Filtered | Object manually excluded from synchronization. |
| Manually Unfiltered | Object manually included in synchronization. |
| Unknown | Object status could not be determined. |
| Error | An error occurred while processing this object. |
Data Discovery allows you to:
- View all users and groups pulled from the source tenant
- Search and filter objects by name, email, or other attributes
- Verify that your pull configuration and filters are working correctly
- Inspect object details before pushing to the target tenant
- Identify any issues with the extracted data
Simulation Mode
Before running the actual synchronization, use simulation mode to:
- Preview which objects will be created
- See which objects will be updated
- Identify objects that will be deleted (if propagate deletion is enabled)
- Validate your configuration without making changes
Manual Execution
Run Pull
Select your Source and Target connectors, then click PULL to extract users and groups from the source tenant.
Review Results
Check the pull results to verify the correct objects were extracted.
Run Push
Click PUSH to create/update objects in the target tenant.
Verify in Target
Check the target tenant's address book to confirm objects were created correctly.
Execution Logs
All synchronization operations are logged. To view the execution history and logs, navigate to GALSync > History.
Job List
The Job List displays all executed operations with the following information:
| JOB TYPE | The type of operation (Galsync Pull, Galsync Push, Galsync Delete, etc.). |
| CONNECTOR NAME | The connector used for this operation. |
| STATUS | The job status: SUCCESS, SCHEDULED, RUNNING, or FAILED. |
| START TIME | When the job started. |
| END TIME | When the job completed. |
Use the STOP JOB button to cancel a running job, or CLEAR to remove completed jobs from the list.
Job Information
Click on a job to view detailed statistics about the synchronization results:
| Created | Number of new objects created in the target tenant. |
| Modified | Number of existing objects that were updated. |
| NoChanges | Number of objects that already exist and required no updates. |
| Deleted | Number of objects removed from the target (when propagate deletion is enabled). |
| Filtered | Number of objects excluded by filter rules. |
| Errors | Number of objects that failed to synchronize. |
Results are broken down by object type: CONTACTS, MAIL USER, and GUEST. Use the EXPORT button to download the results.
Job Logs
For detailed operation logs, scroll down to view the Jobs Logs section:
The logs show timestamped entries with:
- TIMESTAMP: When the event occurred
- TYPE: The operation type (GalSync)
- LEVEL: Log level (Info, Warning, Error)
- MESSAGE: Detailed description including job start/end times and duration
Automatic Scheduling
Once your configuration is working correctly, you can schedule automatic synchronization.
Setting Up a Schedule
- Navigate to GALSync > Scheduling
- Create a new scheduled task
- Select the connectors and synchronization direction
- Set the execution interval (daily, hourly, etc.)
- Enable the schedule
Bi-directional Synchronization
For bi-directional sync between two tenants, create two scheduled actions:
- Schedule 1: Pull from Tenant A → Push to Tenant B
- Schedule 2: Pull from Tenant B → Push to Tenant A
Each scheduled action automatically concatenates:
- Pull action from source to Cloudiway cache
- Push action from cache to target tenant
On-Premises Configuration
For Exchange On-Premises environments, GALSync uses a local agent to communicate with your Exchange server.
Architecture
The local agent facilitates communication between your on-premises Exchange and the Cloudiway platform. The agent initiates all outbound connections, eliminating the need for inbound firewall rules.
Installation Steps
Create On-Premises Connector
In Cloudiway, go to Connectors > Add Connector and select GALSync OnPremises. Enter an alias (cannot be changed later) and a descriptive name.
Download Installation Files
Download the CloudiwayLocalAgentInstaller.msi and configuration.json files.
Install the Agent
Run the MSI installer on a server with access to Exchange. Default path: C:\Program Files (x86)\Cloudiway\GalSync LocalAgent
Configure the Agent
Copy configuration.json to the installation directory and update the settings.
Configuration Parameters
| Parameter | Description |
|---|---|
| AliasDns | Must match the connector alias exactly |
| Exchange URI | Your Exchange server domain (in PullUsers.ps1 and PushContacts.ps1) |
| Organizational Unit | Optional. DN format: OU=Contacts,DC=company,DC=com |
| Security Token | Personal access token generated in Cloudiway platform |
Filtering by Organizational Unit
To synchronize only specific OUs, modify the PullUsers.ps1 script:
Single OU
Get-MailUser -OrganizationalUnit "OU=Sales,OU=Users,DC=contoso,DC=com"Multiple OUs
# First OU (creates file)
Get-MailUser -OrganizationalUnit "OU=Sales,DC=contoso,DC=com" | Export-Csv users.csv
# Additional OUs (append to file)
Get-MailUser -OrganizationalUnit "OU=Marketing,DC=contoso,DC=com" | Export-Csv users.csv -AppendTroubleshooting
Common issues and solutions when configuring GALSync:
Pull operation returns no users
Check the following:
- Verify the connector has proper permissions
- Check if domain filters are too restrictive
- Ensure the service account has access to the directory
- Review the execution logs for specific errors
Push operation fails with permission error
The service account needs sufficient permissions to create objects in the target tenant. For Microsoft 365, ensure the account is a member of a role group with Address Lists, Mail Recipient Creation, and Mail Recipients roles (see Prerequisites section). For Google Workspace, verify domain-wide delegation is properly configured.
Objects created but not visible in address book
Check if "Hide from Address Book" option is enabled. Also, address book updates may take up to 24 hours to propagate in large tenants. You can force an address book update using PowerShell.
Duplicate contacts created
This can occur if the matching criteria isn't finding existing objects. GALSync matches by email address. Ensure the target contact's email address exactly matches the source user's email address.
On-premises agent not connecting
Verify the following:
- The AliasDns in configuration.json matches the connector alias exactly
- The security token is valid and not expired
- Outbound HTTPS (443) is allowed to Cloudiway servers
- The Windows service is running
Service account blocked by conditional access
The GALSync service account must authenticate directly without conditional access policies. Create an exclusion in your conditional access policies for the service account, or use a dedicated service account that bypasses these policies.
Our team can assist with configuration and provide guidance for your specific environment.