How to troubleshoot EWS connection by using EWSEditor

Problem:

You get errors when you use CodeTwo software to connect to (or execute a specific action upon) a mailbox or public folder via the Exchange Web Services (EWS) protocol.

Solution:

To verify if an error is related to CodeTwo software or to your environment, you can use a tool called EWSEditor to connect to the mailbox or public folder that causes errors and check if the error appears.

EWSEditor can be very useful in scenarios when:

• CodeTwo software cannot establish connection to a mailbox or upload/download required data
• CodeTwo software cannot impersonate a mailbox
• CodeTwo software cannot access public folders

To start, browse to the section of your interest:

• Configure EWSEditor to use OAuth 2.0 (required for Exchange Online)
• Connect to your own mailbox
• Connect to other user’s mailbox (impersonation)
• Browse a mailbox
• Browse public folders

Configuring EWSEditor to use OAuth 2.0

With the Modern authentication now being the standard in Microsoft 365 (Office 365), EWSEditor needs to be configured to connect to Exchange Online mailboxes using this method. This requires one-time app registration in your Microsoft 365 tenant’s Entra ID (Azure AD).

To register the app in Entra ID, proceed as follows:

1. Sign in to the Microsoft Entra admin center as an admin with the privileges necessary to manage Entra ID. It’s recommended to use a Global Administrator account.
2. Go to Identity > Overview and use the Copy button to copy your Microsoft 365 tenant’s Tenant ID (Fig. 1.). Note it down somewhere (e.g. in Notepad), as you’ll need it later on.

Fig. 1. Copying the Tenant ID from the Microsoft Entra admin center.

3. Next, go to Applications > App registrations and click New registration (Fig. 2.).

Fig. 2. Starting a new app registration in Entra ID.

4. Register your application (Fig. 3.):
   1. Give it an intuitive & self-explanatory name (e.g. EWSEditor Diagnostics).
   2. Leave the option selected by default under Supported account types.
   3. Set the Redirect URI to Public client/native and paste the following URL:

      https://login.microsoftonline.com/common/oauth2/nativeclient

   4. Click Register to register the app.

Fig. 3. Registering the app in Entra ID.

5. Go to API Permissions in the left-hand menu and click Add a permission. In the pane that opens, go to the APIs my organization uses tab, type Office 365 in the search box and choose Office 365 Exchange Online (Fig. 4.).

Fig. 4. Selecting an API that the app’s going to use.

6. Choose Delegated permissions, expand the EWS permission group and select the checkbox next to EWS.AccessAsUser.All. Finally, click Add permissions to assign the permissions to the app (Fig. 5.).

Fig. 5. Assigning permission to the app.

7. To complete the permission assignment process, click Grant admin consent for <your organization name> and confirm by selecting Yes (Fig. 6.) – the green checkmarks will appear in the Status column.

Fig. 6. Completing the process of assigning permissions to the app.

8. Go to the Overview settings page and copy (e.g. to Notepad) the Application (client) ID value (Fig. 7.) – you’ll need it later on.

Fig. 7. Accessing and copying the Application (client) ID value.

This concludes the configuration of the app in Entra ID. Now, you can proceed to installing and configuring EWSEditor to connect a problematic mailbox or public folders.

Connecting to your own mailbox

1. On the machine where CodeTwo software is installed, go to the EWSEditor page on GitHub and download the bin package.

   Info

   Alternatively, you can download the file to another computer and then copy it to the one where CodeTwo software is installed.

2. Extract the package – EWSEditor is a standalone solution which does not require installation.
3. Open the program and click File > New Exchange Service (Fig. 8.).

Fig. 8. Creating a new EWS connection to a mailbox in EWSEditor.

4. Use the Autodiscover Email option or manually provide the Service URL by using the FQDN of the machine you are connecting to (CAS server), as shown in Fig. 9.

   Info

   The Service URL for EWS should be as follows:
   https://<your machine FQDN>/EWS/Exchange.asmx
   for example: https://exchange.example.com/EWS/Exchange.asmx

   For more detailed information on the Service URL for EWS, please refer to the following article.

   If you want to connect to a Microsoft 365 (Office 365) mailbox, select Service URL and click the 365 Default button to insert the default URL (see Fig. 9.).

Fig. 9. Configuring the EWS connection.

5. Configure the authentication options:

   1. For connections using the Basic authentication (e.g. Outlook 365), select Use the following credentials instead of the default Windows credentials, provide the user name, password, and domain (if required) for the mailbox account you have problems connecting to (Fig. 10.).

      
      Fig. 10. Configuring a direct connection to a mailbox.

   2. For connections using the modern OAuth 2.0 authentication (e.g. Exchange Online), select Use oAuth 2.0 (MSAL) and configure the settings as follows (Fig. 11.):

      • Ensure the Authentication Flow is set to Delegated.
      • In Client App ID, paste the ID of the Entra ID app you created.
      • In Tenant ID, paste the ID of your tenant you copied from the Microsoft Entra admin portal.
      • Ensure that Authority is set to https://login.microsoftonline.com and that the Validate Authority checkbox is enabled.
      • Ensure that Scope is set to https://outlook.office365.com/EWS.AccessAsUser.All.
      • Ensure that Redirect URL is set to https://login.microsoftonline.com/common/oauth2/nativeclient.

      
      Fig. 11. Configuring a connection using OAuth 2.0 (MSAL).

6. When the configuration is complete, click OK to start the connection. If you’ve configured the Modern authentication, provide your admin credentials in the pop-up that opens.
   • If the connection is successful, you will see a confirmation in the program.
   • If the connection is not successful, the software will throw an error. The appearance of any errors means that the mailbox connection problem is not related to CodeTwo software and the problem relates to your environment.

Connecting to other user’s mailbox (impersonation)

To connect to another user’s mailbox using your administrator account, proceed as follows:

1. Complete steps 1-5 from the previous section. In case of using the Basic authentication, provide your administrator’s credentials in step 5a, as shown in Fig. 10.
2. Next, select the Check if using EWS Impersonation checkbox and provide the primary SMTP address of the user mailbox you want to access. Enable the Set X-AnchorMailbox Header option as well – the address of the mailbox you want to access will be inserted automatically (Fig. 12.).

Fig. 12. Configuring an OAuth 2.0 connection to a user’s mailbox using impersonation.

3. When the configuration is complete, click OK to start the connection. If you’ve configured the Modern authentication, provide your admin credentials in the pop-up that opens.
   • If the connection is successful, you will see a confirmation in the program.
   • If the connection is not successful, the software will throw an error. The appearance of any errors means that the mailbox connection problem is not related to CodeTwo software, and the problem relates to your environment.

Browsing a mailbox

Directly after you finish configuring the connection, you get a prompt asking if you want to add the mailbox root to the tree view. Confirm by clicking Yes (Fig. 13.).

Fig. 13. The prompt that allows you to browse the mailbox content in EWSEditor.

After the addition is complete, you can browse the content of your mailbox under Root\Top of Information Store (Fig. 14.). If you are getting any errors while accessing any of the folders within that container, it means that the mailbox is corrupted.

Fig. 14. Browsing the content of a mailbox.

Browsing public folders

To browse public folders of a mailbox account that you added to the EWSEditor’s tree view, right-click the name (email address) of the mailbox at the very top of the tree, and select Add Root Folder. After selecting Identify folder by well known name, choose PublicFoldersRoot from the drop-down list and click OK (Fig. 15.).

Fig. 15. Adding public folders to the mailbox tree view.

If you are getting any errors when accessing public folders, this might mean that public folders are not yet created or their creation is still pending. However, if you are getting trouble accessing some particular public folders, it means that you are missing some of the required permissions.