As customers prepare for the final phase of Exchange Web Services (EWS) retirement in Exchange Online, many are asking the same practical question: how can I prove that EWSAllowedAppIDs is working before I depend on it? This field guide walks through a controlled positive-and-negative test, explains what the result means, and highlights an important naming trap that we are already seeing in customer conversations.
A note from the field
The most common confusion is not about the PowerShell syntax. It is about two similarly named controls that operate at different layers. EWSAllowedAppIDs is the new application-ID control for EWS. The older EWSAllowList and EWSBlockList settings are user-agent controls associated with EwsApplicationAccessPolicy, and they can affect both EWS and REST traffic.
Understand the two controls before testing
EWSAllowedAppIDs is a tenant-level list of application (client) IDs. When EWS is enabled and the list contains one or more Application IDs, only the listed applications are permitted to access EWS. This is the control to validate when you are testing an application's EWS access during the retirement transition.
EWSAllowList and EWSBlockList are older, user-agent-based controls. Despite their names, the underlying access policy is not limited to EWS; it will also affect REST requests. Customers that already use these settings may still need them for REST access control after EWS retirement.
The controls are evaluated independently. In practical terms, an EWS request must pass the application-ID control and then any applicable user-agent control. A successful App-ID test therefore does not prove that a separate user-agent policy is configured correctly.
What the test proves
A valid before-and-after test demonstrates the EWSAllowedAppIDs behavior only when all of the following are true:
- The application can obtain an OAuth token.
- The application has EWS application permission and tenant-wide admin consent.
- EWSEnabled is set to True for the test.
- The test mailbox contains at least one item in the Inbox.
- The App ID is present for the positive test and absent for the negative test.
- At least 24 hours has elapsed after each allow-list change.
Before you start
Perform this procedure in a test tenant if you can. Removing an application from the list can stop a production workload from accessing EWS after the configuration change has propagated.
Prepare the following:
- A test mailbox with at least one Inbox item.
- An app registration in the same tenant as the mailbox.
- EWS application permission with tenant-wide admin consent.
- A client secret or certificate for application authentication. Treat a client secret as a password and do not place it in a shared script or source-control repository.
- Exchange Online PowerShell access and permission to run Get-OrganizationConfig and Set-OrganizationConfig.
- Download the Test-EWSAppAccess.ps1 script. This is a test script that you can use unless you want to test with a real app. Script documentation can be found at Testing EWS App Access.
Record the tenant ID, application (client) ID, test mailbox SMTP address, and the selected authentication material before starting.
Test 1: Confirm access while the app is allowed
- Connect to Exchange Online PowerShell.
Connect-ExchangeOnline- Inspect the current EWS state and capture the complete existing App-ID list.
Get-OrganizationConfig | Format-List EWSEnabled
Get-OrganizationConfig -RetrieveEwsOperationAccessPolicy | Format-List EwsAllowedAppIDs- For a controlled test, set EWSEnabled to $null (all EWS allowed, AppID Allow List ignored).
Set-OrganizationConfig -EWSEnabled $null- Add the test App ID without overwriting any existing entries. The EwsAllowedAppIDs command writes the complete list, so preserve the current value.
$current = (Get-OrganizationConfig -RetrieveEwsOperationAccessPolicy).EwsAllowedAppIDs
$updated = @($current -split "," | ForEach-Object { $_.Trim() } | Where-Object { $_ }; $appId) | Select-Object -Unique
Set-OrganizationConfig -EwsAllowedAppIDs ($updated -join ",")- Verify that the App ID was written.
Get-OrganizationConfig -RetrieveEwsOperationAccessPolicy | Format-List EwsAllowedAppIDs- Wait for the change to propagate. Because of the Exchange Online configuration caching, this can take up to 24 hours.
- Set EWSEnabled to True
Set-OrganizationConfig -EWSEnabled $true- Wait for under 1 hour (but can be up to 4 hours), for the change to become effective.
- Download Test-EWSAppAccess.ps1 and run Test-EWSAppAccess.ps1 with application authentication. The Mailbox parameter is required when using application permissions.
.\Test-EWSAppAccess.ps1 -AppId $appId -TenantId $tenantId -Mailbox $mailbox -SecretKey $secretKey- A successful test should report that the application accessed the mailbox.
Application <appid> successfully accessed mailbox <mailbox></mailbox></appid>- Confirm that $LASTEXITCODE is 0 and save the output with your change record.
Test 2: Remove the app and confirm access is blocked
- Remove only the test App ID, preserving every other entry.
$current = (Get-OrganizationConfig -RetrieveEwsOperationAccessPolicy).EwsAllowedAppIDs
$updated = $current -split "," | ForEach-Object { $_.Trim() } | Where-Object { $_ -and $_ -ne $appId }
Set-OrganizationConfig -EwsAllowedAppIDs ($updated -join ",")- Confirm that the App ID is no longer present.
Get-OrganizationConfig -RetrieveEwsOperationAccessPolicy | Format-List EwsAllowedAppIDs- Wait at least 24 hours before retesting. An immediate success can simply mean that an Exchange Online server still has the previous configuration cached.
- Run the same Test-EWSAppAccess.ps1 command again.
- After propagation, the expected result is a failure.
Application <appid> failed to access mailbox <mailbox></mailbox></appid>Confirm that the process returns exit code 1. If the first test failed too, troubleshoot authentication, permissions, consent, mailbox access, and script dependencies before concluding that the allow list caused the failure.
- Restore the test App ID to the full list, verify the configuration, wait for propagation, and repeat the successful-access test.
Do not leave a production tenant with an unintentionally empty or incomplete App ID allow list.
The fastest way to re-enable EWS after App ID blocking
Let’s say you are testing this process in a tenant and after setting both EWSEnabled = True and populating EWSAllowedAppIDs you do not see results that you expected and need the quickest way to undo your changes and re-enable the use of EWS in your tenant.
- Changes to EWSAllowedAppIDs take ~24 hours to fully apply to your tenant.
- Changes to EWSEnabled take about 1 hour.
- EWSAllowedAppIDs (Allow List) is ignored if EWSEnabled is set to Null.
Therefore, the quickest way to re-enable EWS in an unrestricted way is to set EWSEnabled back to Null. One hour later, EWS will be unrestricted:
Set-OrganizationConfig -EWSEnabled $nullEWSEditor is another option
EWSEditor is also available for administrators and developers who prefer an interactive EWS API explorer. It can be useful for making a real EWS call against a test mailbox while using the same application identity you are validating.
You still need a correctly configured OAuth application, EWS permissions and consent, a controlled test mailbox, a recorded baseline, and enough time for EWSAllowedAppIDs changes to propagate.
Common pitfalls to avoid
- Running the negative test immediately after removing the App ID.
- Replacing the entire list instead of preserving existing App IDs.
- Testing with an empty Inbox when the test script reads the first Inbox item.
- Treating an OAuth, permission, consent, or credential failure as proof that EWSAllowedAppIDs blocked the request.
- Confusing the user-agent-based EWSAllowList or EWSBlockList with the new App-ID-based EWSAllowedAppIDs control.
- Adding an App ID for a workload that uses REST but does not call EWS.
Customer guidance in one paragraph
If an application calls EWS and requires temporary access during the retirement transition, validate its application ID with EWSAllowedAppIDs in a test tenant. If a tenant already uses EwsApplicationAccessPolicy, assess its EWSAllowList or EWSBlockList separately because those user-agent settings can also affect REST. The similar names do not make the controls interchangeable.
This distinction matters because we are already seeing customers assume that any setting beginning with “EWS” is part of the EWS retirement exception process. It is not. Making that mistake can create unnecessary configuration changes or interrupt REST workloads that were never using EWS.
The simple rule: use EWSAllowedAppIDs for the new EWS application-ID gate; use EWSAllowList or EWSBlockList only for the older user-agent policy. Test each layer independently.
And lastly: Set up your EWSAllowedAppIDs parameter while EWSEnabled is still Null, then wait 24h before changing EWSEnabled to True.
Sources and further reading
- Testing EWS App Access, PowerShell-EWS-Scripts Wiki: https://github.com/David-Barrett-MS/PowerShell-EWS-Scripts/wiki/Testing-EWS-App-Access
- EWSEditor project: https://github.com/dseph/EwsEditor
David Barrett
(All-round good guy and Exchange development expert)
