Accessing Microsoft Exchange Online Mailboxes Using OAuth

Important

This feature is only available with the CE 7.4 Cumulative Update package 4 released on the 15th of December 2022

This document describes how to configure:

• Microsoft Azure AD

• Office 365 Exchange Online and

• CE

in order to let CE to connect to Exchange Online mailboxes using OAuth.

Configuring Microsoft Azure AD

Azure AD tenant administrator should perform the following steps in order to register CE as a trusted enterprise application. An application which has the required email access permissions inside the tenant.

1. Select the “App registrations” option in the left side menu and create a new application representing CE e.g. with name “CE Email”.

   

2. Write down the following application properties as they will be required by the Exchange Online administrator:

   • Application (Client) ID

   • Directory (tenant) ID

1. Select the link under the application property “Managed application in local directory” (the “CE Email” link in our case)

2. Write down the Object ID application property as it will be required by the Exchange Online administrator:

1. Go back to the previous page in the browser; to the main page of the application

2. Select “Certificates & secrets” option in the left side menu and create a secret for the application by clicking the “New client secret” link

   

3. Copy and paste secret “Value” as they will be required by CE administrator. We will refer it as Client Secret.

4. Select the “API permissions” option in the left side menu and add the IMAP.AccessAsApp, POP.AccessAsApp permissions to the application by performing the steps:

   1. Click the “Add a permission” link

   2. Select the “APIs my organization uses” category

   3. Search for “Office 365 Exchange Online”

   4. Click that and select “Application permissions”

   5. Check the permissions

      • IMAP > IMAP.AccessAsApp

      • POP > POP.AccessAsApp

   6. Click “Add permissions” button

5. The final set of API permissions should look like this

1. Grant this set of API permissions to the application by clicking the button “Grant admin consent for [tenant name]” appearing above the list permissions.

2. Make sure all the permission set is granted to the application now (aka. green icon appears next each permission)

Configuring Office 365 Exchange Online

Office 365 Exchange Online tenant administrator should perform the following steps in order to let CE as a trusted enterprise application to access the intended mailboxes.

1. Start PowerShell

2. Make sure $PSVersionTable.PSVersion says you are running PowerShell 7.x

3. Run Install-Module -Name ExchangeOnlineManagement -AllowPrereleas

4. Run Import-Module ExchangeOnlineManagement

5. Run Connect-ExchangeOnline -Organization [Directory (tenant) ID]

6. Run New-ServicePrincipal -AppId [Application (Client) ID] -ServiceId [Object ID] -Organization [Directory (tenant) ID]

7. Run Add-MailboxPermission -Identity [mailbox address] -User [Object ID] -AccessRights FullAccess where “mailbox address” is the email address associated with the mailbox you want to let CE to access. Having multiple such mailboxes requires this command to be executed for each mailbox one by one.

Configuring CE

CE deployment administrator should perform the following steps on the Portal:

1. Select the Email Infrastructure > Email Gateways menu and select the Exchange Online gateway OAuth will be used with. If no Exchange Online gateway is configured yet than create a new email gateway with the proper values to access Exchange Online (inbound: outlook.office365.com, 993, IMAP; outbound: smtp.office365.com, 587). Make sure IMAP is specified as the protocol to download incoming emails. This is a requirement as CE does not support OAuth for POP3.

CE tenant administrator should perform the following steps on the Portal:

1. Select the Email Infrastructure > OAuth Settings menu and create a new OAuth settings by specifying:

   • Application (Client) ID as client id

   • Client Secret as client secret

   • https://outlook.office365.com/.default as client Scopes

   • https://login.microsoftonline.com/[Directory (tenant) ID]/oauth2/v2.0/token as token endpoint URL

     

2. Select the Email Infrastructure > Email Connections menu and select the email connection associated with the Exchange Online email gateway we looked at above and the tenant you want to enable OAuth for. If no such email connection exists yet than create a new email connection. Click its OAuth Setting tab of the email connection and assign the OAuth settings to the email connection we just created previously. Check the “Use OAuth to receive emails” checkbox. Do not check the “Use OAuth to send emails” checkbox as Exchange Online does not support OAuth (client credential grant flow) for SMTP yet.

   

3. Select the Server Updates menu and initiate a batch update. After the batch update is successfully performed all the incoming emails from all the Exchange Online mailboxes associated with the given email connection will be retrieved/downloaded using OAuth as the authentication protocol. Outgoing emails via Exchange Online still will be sent using basic authentication; using the user name and password specified on the mailbox level.

How to test outbound email sending with SMTP

1. Start Powershell on the CE core Host
2. run $cred = Get-Credential. Provide the username and password for the mailbox.
3. Run Send-MailMessage -To "TO_MAIL_ADDRESS" -from "FROM_MAIL_ADDRESS" -Subject "Test" -Body "Test message" -BodyAsHtml -SmtpServer smtp.office365.com -UseSsl -Credential $cred -Port 587
4. The Send-MailMessage command should complete without errors
5. Check that the email has arrived at the mailbox gives as the destination