Overview

This article details the best practices for configuring Exchange Web Services (EWS) OAuth support with GFI Archiver. Microsoft 365 has discontinued the Basic Authentication support for EWS and introduced OAuth 2.0 for authentication and authorization.

EWS OAuth authentication support for Microsoft 365 was introduced in GFI Archiver v15.1. The steps in this article assume that you are running GFI Archiver v15.1 or later. Please consider upgrading your GFI Archiver installation if you use an earlier version.

If you have already configured EWS OAuth and Archiver is not archiving the emails from the Journal Mailbox (it was working until recently), please review the article: Archiver not consuming emails from the journal mailbox on Exchange Online to troubleshoot further.

 

Performing the configuration as described in this article should mitigate the following errors:

• Failed during: Testing connection
Details: Could not perform test of connection. Details: The request failed with HTTP status 401: Unauthorized.
• "MailServerWizard","ERROR:MSCreate_ERR: Requested finishing of steps (with error). Stopping on step: TestConnection. With error: Could not perform test of connection. Details: Type 'Microsoft.Identity.Client.MsalUiRequiredException' in Assembly 'Microsoft.Identity.Client, Version=4.18.0.0, Culture=neutral, PublicKeyToken=0a729f4ee981c7ae' is not marked as serializable."

The most common reasons for the above errors are when the password format is incorrect, allowPublicClient is not true, and delegated permission EWS.AccessAsUser.All has not been granted admin consent.

Important Note: Please ensure that MFA is disabled on the Journal Mailbox. GFI Archiver does not support connection to an MFA-enabled Journal Mailbox. Please ensure that the Journal Mailbox is also excluded from the conditional policies. If you are using a third party MFA service, you will need to change the Journal Mailbox from your federated domain to your onmicrosoft.com domain e.g journal@<yourdomain>.onmicrosoft.com

 

If on Archiver version 15.8, please also consider the steps in the article: Registering Archiver in Azure Portal

Solution

• Step 1: Register GFI Archiver as an OAuth client app
• Step 2: Configure API permissions
• Step 3: Set the OAuth client to public
• Step 4: Configure TLS on Archiver Server
• Step 5: Configure the Journaling Mailbox in Archiver

 

Step 1: Register GFI Archiver as an OAuth client app

To use OAuth, an application must have an application ID issued by Azure Active Directory. This tutorial assumes that the application is a console application, so you need to register your application as a public client with Azure Active Directory.

1. Open a browser, navigate to the Azure Active Directory admin center, and log in using an admin account.
2. Select Azure Active Directory in the left-hand navigation, then select App registrations under Manage.
3. Select New registration.
4. On the Register an application page, set the values as follows
   • Set Name to a friendly name for your app, such as GFI Archiver.
   • Set Supported account types to the choice that makes sense for your use case.
   • For Redirect URI (optional), change the dropdown to Public client/native (mobile & desktop) and set the value to https://login.microsoftonline.com/common/oauth2/nativeclient.
5. Choose Register. On the next page, copy the value of the Application (client) ID and save it; you will need it later in step 5 while configuring EWS passwords.

<supportagent> The above bullet #4 used to specify urn:ietf:wg:oauth:2.0:oob, but from 3699921, the customer showed the URI could be just nativeclient. Upon further testing, neither URI matters, because we allow "Allow public client flows", and Archiver could not work with either. This is because the public client is for "Specifies whether the application is a public client. Appropriate for apps using token grant flows that don't use a redirect URI."</supportagent>

Step 2: Configure API permissions

1. Go to Azure Active Directory > App registrations and select the app registration we created in the previous step.
2. Under Manage, select API Permissions.
3. Select Add a permission, and from the Request API permissions page, select Microsoft Graph.
   
4. Select Delegated permissions, then EWS.AccessAsUser.All under EWS, and click on Add permissions.
5. Back on the API permissions tab, click the Grant admin consent from [Organization/Tenant] option at the top of the list. The green checkmark appears if successful.

<supportagent> A GFI partner reported "is not marked as serializable" error when the journaling user does not have permissions in Azure Active Directory admin center > Azure Active Directory > Manage > Enterprise applications > {ApplicationName} > Manage > Users and groups. This could not be reproduced, hence leaving as agent only for now.  Note that Enterprise applications is a different MS365 section than App registrations. </supportagent>

Step 3: Set the OAuth client to public

1. Locate the Azure App manifest for your registered application from step 1.
2. Ensure that the value of allowPublicClient is set to true in the manifest. If it is set to anything else, please change it to true.

 

Step 4: Configure TLS on Archiver Server

On the Archiver server, run the following PowerShell commands to mitigate any potential TLS issues.

New-ItemProperty -path 'HKLM:\SOFTWARE\Microsoft\.NetFramework\v4.0.30319' -name 'SchUseStrongCrypto' -value '1' -PropertyType 'DWord' -Force | Out-Null

New-ItemProperty -path 'HKLM:\SOFTWARE\WOW6432Node\Microsoft\.NetFramework\v4.0.30319' -name 'SchUseStrongCrypto' -value '1' -PropertyType 'DWord' -Force | Out-Null

New-ItemProperty -path 'HKLM:\SOFTWARE\Microsoft\.NetFramework\v4.0.30319' -name 'SystemDefaultTlsVersions' -value '1' -PropertyType 'DWord' -Force | Out-Null

New-ItemProperty -path 'HKLM:\SOFTWARE\WOW6432Node\Microsoft\.NetFramework\v4.0.30319' -name 'SystemDefaultTlsVersions' -value '1' -PropertyType 'DWord' -Force | Out-Null

Step 5: Configure the Journaling Mailbox in Archiver

Follow the steps listed in Configuring a Journaling Mailbox while keeping the following note about passwords in mind. In addition, these are the precise steps to configure the Journal Mailbox:

• Connect using - EWS
• Login - Enter the full O365 journal mailbox address e.g. username@domain.com
• Password - Enter the password of the journal mailbox in the format: [password]_@oAuthCoxn_[ClientID]  (underscore included), where 
  • [password] is the correct journal mailbox password
  • [ClientID] is the OAuth ClientID obtained when registering GFI Archiver as an OAuth client app in Microsoft 365
  • Please make sure to enter the password and ClientID without the brackets "[ ]"
• Folder - Use the language of your mailbox (e.g. Inbox for English or Posteingang for German) or just enter [INBOX]
• Exchange Server Host - Use Manual Host to Exchange/Office 365 CAS option with the URL: 
  • https://outlook.office365.com/EWS/Exchange.asmx