GFI Archiver AI: Migrating from EWS to Microsoft Graph

Purpose: Move Exchange Online journal archiving to Microsoft Graph without moving historical archive data. Requires upgrade to GFI Archiver 15.14 and above.

This guide applies to any GFI Archiver AI version 15.14 release where the mail server wizard includes Microsoft 365 / Microsoft Graph. During the migration:

• Existing GFI Archiver messages remain in the current archive.

• Exchange Online journaling rules and the journal mailbox remain in place.

• Only the method used to retrieve new journal messages changes.

• An existing EWS source is not converted by editing it; add a new Graph source instead.

📌 Caution: EWS and Graph can run at the same time. Do not leave both sources active for the same journal mailbox, as messages may be archived twice.

Before You Start

---

Prerequisites

• GFI Archiver installer for a release with Microsoft Graph support.

• GFI Archiver administrator access.

• Microsoft Entra ID permissions to register an application and grant admin consent (Global Administrator or Application Administrator is usually required).

• Exchange Online administrator access if you plan to restrict the application to selected mailboxes with Exchange RBAC for Applications.

• A scheduled maintenance window and a confirmed backup of the GFI Archiver configuration and databases.

• .NET Framework 4.8 on the GFI Archiver server required for new installations. Existing installations already have this pre-existing requirement (the installer will indicate if a restart is required).

• Outbound HTTPS access from the GFI Archiver server to Microsoft Graph and Microsoft Entra ID.

• GFI Archiver server running Windows Server 2016 or later (Windows Server 2019, 2022, and 2025 are also supported). PowerShell 5.1 or later is required to run the application registration script; this is pre-installed on all supported Windows Server versions. 

Record Current EWS Source Configuration

Before upgrading, record the following details:

1. Source name and the server/node where it runs.

2. Journal mailbox address.

3. Journal mailbox folder (usually Inbox).

4. Source status.

5. Folder Structure Retrieval settings (if utilized).

📝 Note for distributed installations: Upgrade every node that can run GFI Archiver or the polling service before activating the Graph source.

Glossary

• EWS — The retiring Exchange interface Archiver used to read Microsoft 365 mail.

• Microsoft Graph — Its modern, supported replacement.

• Microsoft Entra ID — Microsoft's identity portal (formerly Azure AD); where you register the app.

• Tenant ID / Client ID — From the app: the Directory (tenant) ID and Application (client) ID.

• Client Secret — The app's password; shown once, so copy it securely.

• Journal mailbox — The Microsoft 365 mailbox that receives a copy of all mail for Archiver to store.

1. Upgrade GFI Archiver

1. Schedule a maintenance window and verify current backups.

2. Run the new installer as Administrator over the existing installation (do not uninstall the previous version).

3. Wait for database updates and service restarts to complete.

4. Verify by checking Configuration > Mail Servers > Add. Ensure Microsoft 365 / Microsoft Graph appears under the Connect using dropdown.

2. Register a Microsoft Graph Application

The simplest supported option is using the application registration script provided within GFI Archiver.

New Application Setup

1. Navigate to Configuration > Mail Servers > Add.

2. Select Microsoft 365 / Microsoft Graph.

3. Click Download application registration script to download New-GfiArchiverGraphApp.ps1.

4. Run the script in Windows PowerShell as a user with required permissions:

New-GfiArchiverGraphApp.ps1 -TenantId "<tenant-id>"   

The script installs required Microsoft Graph PowerShell modules if missing. Follow the device code sign-in prompt and grant admin consent.

Manual Registration in the Entra Portal

• 2a — Register: Go to Entra ID > App registrations > New registration. Name it and click Register. On the Overview page, copy the Directory (tenant) ID and Application (client) ID.

• 2b — Secret: Navigate to Certificates & secrets > New client secret > Add. Copy the Value immediately.

• 2c — Permissions: Go to API permissions > Add a permission > Microsoft Graph > Application permissions. Add the permissions outlined below, click Grant admin consent, and confirm each row shows Granted.

Required Microsoft Graph Application Permissions

📝 Note: Use Application permissions, not Delegated permissions. Admin consent must be granted after permissions are added. Save the generated client secret immediately in a secure password store (do not share via email or support tickets).

Existing Application Setup

If using an existing registered application:

1. Configure the Graph source using those credentials and run Test Connection.

2. Select Use existing Azure AD/OAuth credentials if credentials are already saved in GFI Archiver.

If the test reports missing permissions, download and run Update-GfiArchiverAzureAdAppForGraph.ps1:

.\Update-GfiArchiverAzureAdAppForGraph.ps1 `
-AppId "<application-client-id>" `
-TenantId "<tenant-id>" `
 -CreateNewClientSecret

📝 Note: Use -CreateNewClientSecret only when generating a new secret is necessary. Existing EWS permissions are preserved during update to allow rollback during testing.

Restrict Access to Selected Mailboxes (Optional)

To scope permissions rather than granting organization-wide access:

• Use Exchange Online RBAC for Applications to limit access to target journal mailboxes.

• Remove organization-wide Mail.ReadWrite separately and validate using Test-ServicePrincipalAuthorization.

3. Add the Graph Source

1. Navigate to Configuration > Mail Servers and select Add.

2. Under Connect using, choose Microsoft 365 / Microsoft Graph.

3. Select credential type:

   • Manual: Enter Tenant ID, Client ID, and Client Secret.

   • Use existing Azure AD/OAuth credentials: Select if credentials were set up previously.

4. Enter the exact Journal mailbox SMTP address and Mailbox folder (Inbox) used by the EWS source.

Webhook Configuration

For initial migration, leave Public webhook URL and Local listen URL blank. GFI Archiver defaults to Delta polling (no inbound internet access required). Enable webhooks only if an external HTTPS endpoint and reverse proxy are already established.

1. Click Test Connection or Next. Resolve any authentication/permission issues before saving.

2. Save the source and set its status to Active.

4. Switch Archiving from EWS to Graph

1. Confirm the new Graph source is listed as Active.
2. Under Configuration > Mail Servers, select the legacy EWS source for the corresponding mailbox.
3. Click Deactivate. Keep the configuration saved for observation (do not delete immediately).
4. Repeat this pairing process for any additional journal mailboxes.

5. Verify the Result

1. Send a test message that triggers the Exchange Online journal rule.
2. Verify delivery in the target journal mailbox.
3. Confirm GFI Archiver ingests the item with correct timestamps, senders, and attachments.
4. Verify no duplicates are created and that the old EWS source remains inactive.
   
   

Folder Structure Retrieval Validation

If Folder Structure Retrieval is used, navigate to Configuration > Folder Structure Retrieval > Settings, select Graph, and click Test Connection.

Folder Structure Retrieval Wizard configured with manual Graph credentials.

Folder Structure Retrieval Wizard using existing Azure AD/OAuth settings.

Checking Graph Health State

Graph state and snapshot health logs are stored locally on each node:

• State directory:%ProgramData%\GFI\Archiver\GraphPolling\state  

• Health summary: %ProgramData%\GFI\Archiver\GraphPolling\state\health\snapshot.json  

Review snapshot.json to verify status, lastJournalRunUtcByDataSource, and delta checkpoints.

Rollback Procedure

If Graph ingestion fails:

1. Deactivate the Graph source.

2. Activate the legacy EWS source.

3. Confirm archiving resumes via EWS while investigating Graph logs. Keep the Graph configuration intact during troubleshooting.

Troubleshooting & Common Issues