Mimecast Synchronization Engine - Configuring Open Auth (OAuth)

This article describes configuring your environment for Open Authentication (OAuth) modern authentication method with the Mimecast Synchronization Engine (MSE) software.

PREREQUISITES

• Azure Application with Exchange.ManageAsApp API permission and Exchange Administrator Group.
• Powershell 5.1 or above.
• V3 Exchange Online Management Powershell Module.

STEPS TO COMPLETE

• STEP 1 - Creating a Self-Signed Certificate
• STEP 2 - Importing the Certificate
• STEP 3 - Granting Network Service Read Access
• STEP 4 - Creating OAuth App for MSE
• STEP 5 - Creating a Service Principal in Exchange Online

STEP 1 - Creating a Self-Signed Certificate

Configure a self-signed certificate to allow Powershell to authenticate with M365. MSE uses the Connect-ExchangeOnline commandlet with a certificate thumbprint to extract the information required. 

• Not all the parameters specified in the example below are available on Windows Server 2012 R2. The -NotAfter and -Keyspec parameters will not be available. This is regardless of the Powershell version. It is, however, possible to create the self-signed certificate on another machine if such settings are required.
• Replace <O365 Tenant Domain> with your Microsoft 365 .onmicrosoft.com domain the MSE will connect to. e.g., contoso.onmicrosoft.com.

Run the following commands to create a self-signed certificate:

$mycert = New-SelfSignedCertificate -DnsName "<O365 Tenant Domain>" -CertStoreLocation "cert:\CurrentUser\My" -NotAfter (Get-Date).AddYears(1) -KeySpec KeyExchange

$mycert | Export-PfxCertificate -FilePath mycert.pfx -Password (Get-Credential).password

$mycert | Export-Certificate -FilePath mycert.cer

This will create a certificate valid for one year. 

STEP 2 - Importing the Certificate

To import the Certificate, follow these steps:

1. Open the mmc.exe utility and add the Local Computer Certificates plugin.

2.  Import the generated .pfx Certificate.

3. Click Next.
4. Select the certificate you generated.
5. Enter the password and select Mark this key as exportable.
6. Select Place all certificates in the following store. 
7. Set the Certificate Store to Personal.
8. Click Next. 
9. Click Finish.
10. Take note of the Certificate Thumbprint and Organization in a Notepad file. You will need these later.

STEP 3 - Grant Network Service Read Access

Following STEP 2, give the Network Service (the service the Mimecast Synchronization Engine service runs under). Read permissions to the Certificate by following these steps.

1. Open mmc.exe, right-click on the imported certificate, and select Manage Private Keys.

2. Assign Network Service read access to the certificate.

STEP 4 - Creating OAuth App for Mimecast Synchronization Engine

A Microsoft 365/Azure Admin must log in to Azure to build an App Registration, allowing the MSE to authenticate using OAuth. Please see the following Microsoft Article for more information: https://learn.microsoft.com/en-us/exchange/client-developer/exchange-web-services/how-to-authenticate-an-ews-application-by-using-oauth#register-your-application

Creating the OAuth App for MSE comprises the following parts:

• PART A - Registering the Application
• PART B - Adding the Certificate
• PART C - Setting the App Permissions
• PART D - Azure Application & Exchange Administrator Group

PART A - Register the Application

Log in to Azure (https://portal.azure.com) and navigate to:

1. Azure AD | App Registrations.
2. New Registration.

3. Give the application a name.
4. Leave the Accounts in this organizational directory only setting as enabled.
5. Select Public client (mobile & desktop) under Redirect URI and set the value to: https://login.microsoftonline.com/common/oauth2/nativeclient.
6. Click the Register button.

PART B - Adding Certificate to Azure App

Add the corresponding Certificate to the Azure application in Microsoft 365 in accordance with the instructions in the Microsoft Knowledge Base article here.

Adding the certificate to the Azure application will allow MSE to authenticate to Microsoft 365 using Modern Authentication.

You must have the Exchange Online PowerShell module installed if using Open Auth with Microsoft 365 as the directory type, as this is needed for all Oauth tasks using a Distribution List (DL).

PART C - Set the Permissions

The next screen will bring up the main menu for the app you created. On the left side, navigate to

1. API Permissions.
2. Select Add A Permission.

On the right-hand side, make the following selection...

3. Select APIs my organization uses.
4. Search for Microsoft 365.
5. Select Microsoft 365 Exchange Online from the search results list.

For the Microsoft 365 Exchange Online API, select:

6. Application Permissions
7. Check full_access_as_app.
8. Click Add Permissions.

9. The Configured permissions screen should look like this:

10. Click Grant admin consent > YES.
11. Once Admin consent has been granted, the status column will show a green checkbox.

Set the Permissions

PART D - Azure Application & Exchange Administrator Group (Exchange.ManageAsApp API permission)

These steps assume that an Azure AD Application is already configured; however, tasks require a different set of API permissions to those needed to connect to Exchange. This API Permission and Role must be added to the Azure Application for MSE Tasks to function correctly. To allow MSE to connect to the remote PowerShell, the Azure App must have the Exchange.ManageAsApp API permission.

To add the Exchange.ManageAsApp API permission:

1. Click the Azure Active Directory menu item.
2. Click on the App Registrations menu item.
3. Select API Permissions.
4. Under All APIs, select M365 Exchange Online.
5. Add the necessary Exchange.ManageAsApp application permission.

Site Binding does not validate all the permissions the tasks require; it simply validates that the Powershell cmdlet Connect-ExchangeOnline successfully connects to the Microsoft 365 tenant.

 

6. Tasks call the get-mailboxpermission cmdlet on the target mailbox(es), and all the following requirements are to satisfy Microsoft security. The Get-MailboxPermission cmdlet requires the Azure App to have one of the following RoleTypes:

PS C:\Users\admin> Get-ManagementRole -Cmdlet Get-MailboxPermission

Name                 RoleType
----                 --------
View-Only Recipients ViewOnlyRecipients
Mail Recipients      MailRecipients
  

 

The App Registration must have a member of the “Organization Management” role group assigned, and Azure AD supports the “Exchange Administrator” group by default.

To add Organization Management Permission: 

https://portal.azure.com/#view/Microsoft_AAD_IAM/AllRolesBlade

1. Click on all Services.
2. Click on all Roles.
3. Select Exchange Administrators from the list.
4. Select the Add Assignments button.
5. Search for the MSE app (in this instance, named “MSE_xxxxx”).
6. Select the appropriate option from the drop-down based on your usage scenario, then Add the assignment.

Platform	Permissions If MDS Task Only		Permissions for MDS & All Other Tasks
Azure	Global Reader Security Reader Exchange.Manage.AsApp		Exchange Admin Exchange.ManageAsApp
Exchange Online	MailRecipient		EWS_Full_Access_As_App Mail Recipient

Without the Exchange Administrator's permission or if lesser permission is granted, the tasks will fail to connect to the remote mailbox, and you may observe error logs similar to the following MSE Error Message.

Certificates & Secrets

Next, the application must generate a secret key (App Password).

1. Select Certificates & Secrets on the left-hand navigational menu.
2. Select New Client Secret.

3. On the right-hand panel, enter a description for the key.
4. Set the Expires field (this can be set for up to 2 years in the future).
5. Click the Add button.

The Key will show up under Client Secrets.

6. Copy the Value over to Notepad or another text editor.

Be sure to copy the Value and not the Secret ID. The Secret ID will cause authentication to fail if added to the MSE. The Value must be copied before leaving this window. The admin will not have access to it afterward.

7. Now, select Overview from the left-hand panel of your app.
8. Copy the Application (client) ID to your Notepad file.
9. Copy the Directory (tenant) ID to your Notepad file.

STEP 5 - Creating a Service Principal in Exchange Online

If an error is identified such as the following: "The role assigned to application <Azure App ID> isn't supported in this scenario." when attempting to connect to M365, a Service Principal needs to be created to link the MSE OAuth application and Exchange Online together. The process uses the EWS.AccessAsApp permission to perform Exchange Service Tasks like Folder and Calendar Replication. It replaces the ApplicationImpersonation permission previously used by the MSE service mailbox in Exchange Online.

1. Create the Service Principal in Exchange Online by Connecting to Exchange Online as the certificate or as a Global Admin.

Connect-ExchangeOnline -CertificateThumbPrint "012THISISADEMOTHUMBPRINT" -AppID "36ee4c6c-0812-40a2-b820-b22ebd02bce3" -Organization "contosoelectronics.onmicrosoft.com" 

2. Enter the App ID and Object ID for the MSE OAuth application from the Enterprise Apps section:

3. To create the Service Principal in PowerShell. Run the following CMD.

New-ServicePrincipal -AppId <APP/CLIENT ID FROM AZURE> -ObjectId <OBJECT ID FROM AZURE> -DisplayName MSE

4. Successful Principal Creation:

DisplayName ObjectId AppId ----------- -------- ----- MSE <OBJECT ID FROM AZURE> <APP/CLIENT ID FROM AZURE>

1. Create the Role Assignment for the Application using this PowerShell script. The Exchange Permission needed is Application EWS.AccessAsApp.

New-ManagementRoleAssignment -Name <Name for MSE Role> -Role "Application EWS.AccessAsApp" -App <APP/CLIENT ID FROM AZURE>

6. Successful Management Role Creation Output

PS C:\Users\Administrator> New-ManagementRoleAssignment -Name MSE_RBAC -Role "Application EWS.AccessAsApp" -App <APP/CLIENT ID FROM AZURE> Name Role RoleAssigneeName RoleAssigneeType AssignmentMethod EffectiveUserNam e ---- ---- ---------------- ---------------- ---------------- ---------------- MSE_RBAC Application EW... 67ef1c07-b05b-... ServicePrincipal Direct

7. Test the Service Principal.

Test-ServicePrincipalAuthorization -Resource <Email Address from M365 Tenant> -Identity <APP/CLIENT ID FROM AZURE> | Format-Table

Which should return the following:

PS C:\Users\Administrator> Test-ServicePrincipalAuthorization -Resource <SMTP ADDRESS OF TEST MAILBOX> -Identity <APP/CLIENT ID FROM AZURE> | Format-Table RoleName GrantedPermissions AllowedResourceScope ScopeType InScope -------- ------------------ -------------------- --------- ------- Application EWS.AccessAsApp EWS.AccessAsApp Organization Organization True

Note:

If InScope = True, the app is set up correctly in M365.

8. Attempt to bind the MSE again. 

 >>Navigate to SITE BINDING >>

Navigate to Site Binding to complete the binding process as normal, completing the additional Certificate Thumbprint and Organization fields with the same information gathered from the above steps.