Testing EWS App Access

Testing EWS application access and EWSAllowedAppIDs

This guide explains how to use Test-EWSAppAccess.ps1 to verify the Exchange Online EWS application ID allow list. The script tests real mailbox access by obtaining an OAuth token and querying the mailbox's Inbox folder metadata. It reports success or failure and returns exit code 0 or 1 respectively.

Important: Perform this procedure in a test tenant first. Removing an application from the allow list can stop production workloads from accessing EWS after the configuration has propagated.

How the allow list works

EwsAllowedAppIDs is a tenant-level allow list of application (client) IDs. When EWSEnabled is True and the list contains one or more IDs, only those applications can access EWS. The list is separate from the older user-agent-based EWSAllowList setting.

Changes to EwsAllowedAppIDs can take up to 24 hours to take effect because Exchange Online servers refresh their in-memory configuration cache periodically. The allow list command writes the complete list, so always read the existing value before adding or removing an ID.

Prerequisites

You need:

• A test Microsoft 365 tenant and a test mailbox. The script does not require any mailbox message to exist; it validates access by retrieving the Inbox folder metadata.
• An app registration in the same tenant as the mailbox.
• EWS application permission granted to the app, with consent, for the mailbox(es) being tested. The app must be configured to authenticate with either a client secret or certificate.
• Exchange Online PowerShell and permission to run Get-OrganizationConfig and Set-OrganizationConfig.
• Windows PowerShell or PowerShell 7. The script has no external dependencies.

Record these values before starting:

$tenantId = "<tenant ID>"
$appId = "<application (client) ID>"
$mailbox = "<test mailbox SMTP address>"   # required for application permissions / impersonation
$secretKey = "<client secret value>"

For delegated authentication, -Mailbox is not required. For application permissions, the mailbox must be supplied because the script uses impersonation to access that mailbox. Treat the client secret as a password. Do not place it in a shared script or commit it to source control.

Test the app while it is allowed

1. Connect to Exchange Online and confirm the current settings:

   Connect-ExchangeOnline
   
   Get-OrganizationConfig | Format-List EWSEnabled
   Get-OrganizationConfig -RetrieveEwsOperationAccessPolicy |
   	 Format-List EwsAllowedAppIDs

2. Confirm that EWS is enabled for the test. For a controlled allow-list test, set EWSEnabled to True:

   Set-OrganizationConfig -EWSEnabled $true

3. Add the test app's App ID to the existing allow list. This example preserves all existing IDs:

   $current = (Get-OrganizationConfig -RetrieveEwsOperationAccessPolicy).EwsAllowedAppIDs
   $updated = @(
   	 $current -split "," |
   		  ForEach-Object { $_.Trim() } |
   		  Where-Object { $_ }
   	 $appId
   ) | Select-Object -Unique
   
   Set-OrganizationConfig -EwsAllowedAppIDs ($updated -join ",")

4. Confirm that the App ID was written to the configuration:

   Get-OrganizationConfig -RetrieveEwsOperationAccessPolicy |
   	 Format-List EwsAllowedAppIDs

5. Wait for the configuration change to propagate. It can take up to 24 hours.

6. Download Test-EWSAppAccess.ps1, then run it using application authentication. The -Mailbox parameter is required for application permissions because the script impersonates that mailbox:

   .\Test-EWSAppAccess.ps1 `
   	 -AppId $appId `
   	 -TenantId $tenantId `
   	 -Mailbox $mailbox `
   	 -SecretKey $secretKey

   A successful test ends with a message similar to:

   Application <AppId> successfully accessed mailbox <mailbox>
   

   Save/note the output and confirm that the process exit code is 0:

   $LASTEXITCODE

Remove the app and test again

1. Remove only the test App ID from the allow list. This example again preserves every other entry:

   $current = (Get-OrganizationConfig -RetrieveEwsOperationAccessPolicy).EwsAllowedAppIDs
   $updated = $current -split "," |
   	 ForEach-Object { $_.Trim() } |
   	 Where-Object { $_ -and $_ -ne $appId }
   
   Set-OrganizationConfig -EwsAllowedAppIDs ($updated -join ",")

2. Confirm that the App ID is no longer present:

   Get-OrganizationConfig -RetrieveEwsOperationAccessPolicy |
   	 Format-List EwsAllowedAppIDs

3. Wait at least 24 hours before running the test again. Running it immediately after changing the setting does not prove that the app is still allowed; some Exchange Online servers may still have the previous configuration cached.

4. Run the same Test-EWSAppAccess.ps1 command again. After the change has propagated, the expected result is a failure similar to:

   Application <AppId> failed to access mailbox <mailbox>
   

   The process should return exit code 1. The preceding error output should show that the EWS request could not retrieve the Inbox or its first item.

5. To restore the test app, add its App ID back to the full allow list, run the verification command, wait for propagation, and repeat the successful access test. Do not leave a production tenant with an unintentionally empty or incomplete list.

Interpreting the result

The test demonstrates the allow-list behavior when all of the following are true:

• The app can obtain an OAuth token.
• The app has EWS application permission and admin consent.
• EWSEnabled is True.
• The app can access the target mailbox and retrieve the Inbox folder metadata.
• The App ID is present for the successful test and absent for the failed test.
• At least 24 hours has elapsed after each allow-list change.

If the first test fails, troubleshoot app registration, permissions, consent, credentials, mailbox permissions, and script dependencies before testing the allow list. If the second test succeeds after the full waiting period, verify that the App ID was actually removed and that the tenant's EWSEnabled and allow-list values are the intended ones.

For the Exchange Online behavior and retirement timeline, see Introducing EWSAllowedAppIDs: Preparing for the Final Phase of EWS Retirement.