View source for Configuring Exchange Online for Grooper Before EWS Retirement

Microsoft is retiring Exchange Web Services (EWS) in Exchange Online, the API that Grooper's Exchange CMIS Connection uses to import email. 

This affects every Grooper version currently in use — the most recent release and older releases alike. If your organization uses Grooper's Exchange CMIS Connection to import email, action is required in your Microsoft 365 tenant to avoid an interruption.

== Key dates ==
{|class="wikitable"
|Date||What happens
|-
|Before Oct 1, 2026||Act immediately. Configuring now, before Microsoft's rollout reaches your tenant, is expected to prevent an interruption — but the closer to October 1 you wait, the higher the risk. Also during September, Microsoft is automatically pre-populating allow lists for tenants that haven't created one, based on observed usage.
|-
|Oct 1, 2026||Microsoft begins blocking EWS by default, tenant by tenant, for any Microsoft 365 tenant that has not opted in. Unconfigured tenants will have Exchange import stop working. EWS can be re-enabled afterward, but with a service interruption.
|-
|Apr 1, 2027||Microsoft permanently and fully shuts down EWS for every tenant. No allow list, exception, or configuration can restore it after this date.
|}

{{attn-box|The steps below only address the October 1, 2026 blocking.
 
EWS is being fully retired on April 1, 2027 with no exceptions of any kind. Your Grooper account representative can advise on the long-term migration path required before that date.}}

==Before you begin==
You will need:
* A Microsoft 365 account with Exchange Online administrator rights (Global Administrator or Exchange Administrator role).
* The Exchange Online PowerShell module ("ExchangeOnlineManagement") installed, or access to a machine where it can be installed.
* To know which authentication method your Grooper Exchange CMIS Connection uses — Exchange OAuth or OAuth Service Login. Your Grooper administrator or Grooper support contact can confirm this if you're unsure.
* Access to the Microsoft 365 admin center to view your tenant's EWS usage report (Step 3).

== Step 1 – Connect to Exchange Online PowerShell==

If the module isn't already installed, install it once:
<pre>Install-Module -Name ExchangeOnlineManagement -Scope CurrentUser</pre>
Then connect to your tenant (a browser window will open for sign-in):
<pre>Connect-ExchangeOnline -UserPrincipalName admin@yourdomain.com</pre>

==Step 2 – Check your current settings ==

Before making changes, check the current value of <code>EWSEnabled</code> and the existing allow list, if any:
<pre>
Get-OrganizationConfig | Format-List EWSEnabled
Get-OrganizationConfig -RetrieveEwsOperationAccessPolicy | Format-List EwsAllowedAppIDs
</pre>
What you should see: 
* If <code>EWSEnabled</code> shows blank or "null", it has never been set. 
* If <code>EwsAllowedAppIDs</code> shows blank, no allow list exists yet.
{{fyi-box|An allow list may already exist even if no one in your organization created one.

During September 2026, Microsoft is automatically pre-populating allow lists for tenants that haven't made their own, based on observed usage in that tenant. 

If a list already exists, do NOT assume it is complete or correct — review it in Step 3, and confirm the Grooper App ID from Step 4 is on it.}}
==Step 3 – Review your EWS usage report==
{{attn-box|An allow list containing only the Grooper App ID could break other things your organization depends on.

Once the allow list is populated and <code>EWSEnabled</code> is True, every application NOT on the list is blocked from EWS — immediately after the change propagates, not just in October. That includes '''any''' application if they still use EWS in your tenant.}}
To see every application that has recently used EWS in your tenant:
* Sign in to the Microsoft 365 admin center (admin.microsoft.com).
* Go to Reports > Usage > Exchange > EWS Usage.
* Note the App ID of every application your organization intends to keep using. Your final allow list must include all of them, not just Grooper's.
The report shows raw App ID values (GUIDs). To identify what an unfamiliar App ID belongs to, look it up in Microsoft Entra ID under Enterprise Applications, or check Microsoft's published reference list of first-party application IDs.
== Step 4 – Identify Grooper's App ID==
Add the App ID that matches the authentication method your Grooper Exchange CMIS Connection uses:
{|class="wikitable"
|Authentication method||App ID to add
|-
|Exchange OAuth||e79cac6f-a984-41c3-bbe4-19b348c3da56  (fixed — same for every Grooper customer)
|-
|OAuth Service Login||The Application (Client) ID of the app registration your organization created in your own Microsoft Entra tenant. This value is different for every customer.
•	Found in the Azure Portal under "App registrations > [your app] > Overview".
•	Found in Grooper in the CMIS Connection’s OAuth Service Login settings stored in the "Client Id" property
|}
==Step 5 – Set the complete allow list==
{{attn-box|<code>Set-OrganizationConfig -EwsAllowedAppIds</code> has no "add" mode.

Whatever value you give it becomes the entire list, discarding whatever was there before. If you run it with only one App ID, every other App ID previously on the list is gone.

The script below exists specifically to avoid that. It reads the current list first, adds the ID to it, and only then writes the full command back in a single call.}}

The safest pattern reads the current list first, merges in the new App ID, and writes the combined result back:
<pre>
$current = (Get-OrganizationConfig -RetrieveEwsOperationAccessPolicy).EwsAllowedAppIDs
$updated = @($current -split "," | ForEach-Object { $_.Trim() } | Where-Object { $_ }; "YOUR-APP-ID-HERE") | Select-Object -Unique
Set-OrganizationConfig -EwsAllowedAppIDs ($updated -join ",")
</pre>

Replace "YOUR-APP-ID-HERE" with the Grooper App ID from Step 4. If Step 3 identified other App IDs that are not yet on the list, run the middle line once for each of them (or add them all before the final line).

<big>Alternative to populate the entire allow list</big>

If you know the full list of App IDs you need to add to the allow list, you can add them as a comma separated list:
{{attn-box|The command below replaces the ENTIRE list every time it runs.

It does not append to an existing list. If you use this command, be sure you have the ENTIRE set of allowed App IDs listed. '''Only use this command if you are populating an empty allow list.'''}}
<pre>
Set-OrganizationConfig -EwsAllowedAppIDs "ID1,ID2,ID3..."
</pre>

== Step 6 – Set EWSEnabled to True ==
Only after the list is complete, turn on <code>EWSEnabled</code>. This activates the allow list and opts your tenant out of Microsoft's automatic blocking:
<pre>
Set-OrganizationConfig -EwsEnabled $true
</pre>
{{fyi-box|Why finish the list first? Not because the list gets locked. You can add App IDs at any time by re-running the Step 5 command. 

The reason is timing. Once <code>EWSEnabled</code> is True and the list is populated, any app missing from it is blocked, and additions to the list can take up to 24 hours to take effect. Completing the list before enabling avoids a temporary, self-inflicted outage for a forgotten app.}}

== Step 7 – Verify ==

Confirm both settings were applied as expected. EWSEnabled should show True, and EwsAllowedAppIDs should show every App ID you intended:
<pre>
Get-OrganizationConfig | Format-List EWSEnabled
Get-OrganizationConfig -RetrieveEwsOperationAccessPolicy | Format-List EwsAllowedAppIDs
</pre>
== Step 8 – Allow time to propagate, then test ==
* Changes to <code>EWSEnabled</code> typically take effect within about '''1 hour'''.
* Changes to <code>EwsAllowedAppIDs</code> can take up to '''24 hours''' to fully propagate, because Exchange Online servers refresh this list from a cache about once a day.
* After waiting, confirm Grooper's Exchange import is working normally. If something that was working stops working immediately after the change, wait the full 24 hours before troubleshooting further. This is almost always the propagation delay, not a configuration error.

== Troubleshooting ==
* Forgot an App ID: re-run the Step 5 merge command with the missing ID — the list can be updated at any time. The blocked app may take up to 24 hours to start working again after the fix. 
** If you need it working sooner: temporarily set EWSEnabled back to Null (Set-OrganizationConfig -EwsEnabled $null). The allow list is ignored while Null, and EWS becomes unrestricted within about an hour. Fix the list, then set EWSEnabled to True again promptly. 
** Do not leave the tenant on Null: a Null tenant is subject to Microsoft's automatic October 1 block, and this workaround stops being clean after that date.
* Wrong ID type: confirm the value entered is the Application (Client) ID — not the Object ID or Service Principal ID — from the Azure Portal app registration.
* List got overwritten: because Set-OrganizationConfig replaces the whole list, re-run the Step 7 verification and confirm every expected App ID is still present. A missing entry means a later command overwrote it.
* Missing consent (OAuth Service Login only): confirm the app registration has the required Exchange/EWS permission and that it has received tenant-wide admin consent.
* Mailbox-level block: EWS can also be disabled on an individual mailbox. Check the specific mailbox Grooper connects to with: Get-CASMailbox -Identity mailbox@yourdomain.com | Format-List EwsEnabled — it must not be False.
* Application Access Policy: a separate policy (New-ApplicationAccessPolicy) can restrict which mailboxes an app may touch, independent of the allow list. Run Test-ApplicationAccessPolicy against the app's ID and the target mailbox to check.
* Frontline licenses: mailboxes on Kiosk, F1, or F3 licenses are subject to a separate license-based EWS restriction that the allow list does not override. If Grooper imports from a mailbox on one of these licenses, a license change may be required.
* Expired credentials: if a client secret or certificate is used for authentication, confirm it has not expired.

==Quick reference – all commands in order==
<pre>
# 1. Connect
Connect-ExchangeOnline -UserPrincipalName admin@yourdomain.com

# 2. Check current state
Get-OrganizationConfig | Format-List EWSEnabled
Get-OrganizationConfig -RetrieveEwsOperationAccessPolicy | Format-List EwsAllowedAppIDs

# 3. Add an App ID without losing existing entries
$current = (Get-OrganizationConfig -RetrieveEwsOperationAccessPolicy).EwsAllowedAppIDs
$updated = @($current -split "," | ForEach-Object { $_.Trim() } | Where-Object { $_ }; "YOUR-APP-ID-HERE") | Select-Object -Unique
Set-OrganizationConfig -EwsAllowedAppIDs ($updated -join ",")

# 4. Enable (only after the list is complete)
Set-OrganizationConfig -EwsEnabled $true

# 5. Verify
Get-OrganizationConfig | Format-List EWSEnabled
Get-OrganizationConfig -RetrieveEwsOperationAccessPolicy | Format-List EwsAllowedAppIDs
</pre>
Remember: EWSEnabled changes take about 1 hour; allow list changes take up to 24 hours.
== Questions ==
Contact your Grooper account representative or Grooper Support with any questions about this change.