Email Prerequisites for a Microsoft 365 OAuth 2.0 Connection¶

Introduction¶

These are the prerequisites for using the Email connector with a Microsoft 365 OAuth 2.0 connection using Resource Owner Password Credential (ROPC) authentication:

• Create an App Registration

• Add Required Permissions to the App Registration

• Connect the App Registration to Exchange Online

• Verify the App Registration

• Obtain Access Tokens for ROPC Authentication

All prerequisite tasks will require you to log in to the Azure portal with an Azure account with the Exchange Administrator admin permissions enabled. Exchange Administrator is required to download the EXO2 PowerShell module needed in Connect the App Registration to Exchange Online. This account's username and password will also be used in Obtain Access Tokens for ROPC Authentication.

Some tasks will also require Windows PowerShell and curl, Postman, or a similar tool for sending POST requests.

Create an App Registration¶

Follow these steps to create an app registration with the Microsoft identity platform:

1. In the Azure portal, search for and click Microsoft Entra ID (previously known as Azure Active Directory or Azure AD):

   

2. In the left sidebar under Manage, click App registrations.

3. Click New registration:

   

4. Enter a Name for your app. This display name will be visible to users:

   

5. Click Register to complete the app registration. You are then directed to the app's Overview page:

   

   Important

   Retain the app registration's Application (client) ID and Directory (tenant) ID to use as client_id and tenant_id in Verify the App Registration and Obtain Access Tokens for ROPC Authentication.

6. Click Add a certificate or secret.

7. In the Client secrets tab, click New client secret to open the Add a client secret pane. In this pane, enter a description and select an expiration date for the client secret, then set, click Add:

   

8. The client secret is now visible in the Client secrets tab. Retain the client secret's Value to use as client_secret in Obtain Access Tokens for ROPC Authentication.

   

Add Required Permissions to the App Registration¶

To use the Email connector with a Microsoft 365 OAuth 2.0 connection, your app registration must have these permissions:

• Office 365 Exchange Online Application Permissions
• Microsoft Graph Application Permissions
• Microsoft Graph Delegated Permissions

In the Azure portal, navigate to your app registration and click API permissions in the left sidebar:

Office 365 Exchange Online Application Permissions¶

To add Office 365 Exchange Online application permissions, follow these steps:

1. On the API permissions page, click Add a permission.

2. In the Request API permissions pane, click the APIs my organization uses tab, search for and click Office 365 Exchange Online:

   

3. Click Application permissions.

4. For POP access, enable the POP.AccessAsApp permission. For IMAP access, enable the IMAP.AccessAsApp permission.

5. Click Add permissions. The updated app registration's Configured permissions page is shown.

Microsoft Graph Application Permissions¶

To add Microsoft Graph application permissions, follow these steps:

1. On the API permissions page, click Add a permission.

2. In the Request API permissions pane, click the APIs my organization uses tab, search for and click Microsoft Graph:

   

3. Click Application permissions.

4. Enable the Mail.Send and User.Read.All permissions.

5. Click Add permissions. The updated app registration's Configured permissions page is shown.

Microsoft Graph Delegated Permissions¶

To add Microsoft Graph delegated permissions, follow these steps:

1. On the API permissions page, click Add a permission.

2. In the Request API permissions pane, click the APIs my organization uses tab, search for and click Microsoft Graph:

   

3. Click Delegated permissions.

4. Enable the offline_access, IMAP.AccessAsUser.All, and SMTP.Send permissions. User.Read should remain enabled.

5. Click Add permissions. The updated app registration's Configured permissions page is shown. Your app registration now has the required permissions.

Connect the App Registration to Exchange Online¶

To connect the app registration to Exchange Online, follow these steps:

1. Download and install the EXO2 PowerShell module by going to the Classic Exchange admin center. Click Hybrid and then Configure Exchange PowerShell module.

   Important

   If you cannot download and install the EXO2 PowerShell module, you cannot complete the Exchange connection.

2. Launch Windows PowerShell and run:

   Install-Module -Name ExchangeOnlineManagement -allowprerelease
   Install-Module Microsoft.Graph -allowprerelease
   Install-Module -Name AzureAD
   Install-module AzureADPreview -Verbose
   import-module AzureADPreview
   import-module ExchangeOnlineManagement
   

3. Run Connect-AzureAD and enter your login information.

4. Run Connect-ExchangeOnline and enter your login information.

5. Obtain the registered app's service principal information and store it in a variable by running:

   $MyApp = Get-AzureADServicePrincipal -SearchString <Registered application name>
   $MyApp | fl
   

6. Use the stored service principal information to complete the connection:

   New-ServicePrincipal -AppId $MyApp.AppId -ServiceId $MyApp.ObjectId -DisplayName "Service Principal for IMAP APP"
   Add-MailboxPermission -Identity <Administrator email address> -User $MyApp.ObjectId -AccessRights FullAccess
   

Verify the App Registration¶

To verify the app registration, follow these steps:

1. Submit a POST request to https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/devicecode where <client_id> and <tenant_id> are replaced with the Application (client) ID and Directory (tenant) ID you saved while creating your app registration:

   curl --location --request POST 'https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/devicecode' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'client_id=<client_id>' \
   --data-urlencode 'scope=https://outlook.office.com/SMTP.Send https://outlook.office.com/IMAP.AccessAsUser.All'
   

   If successful, the response will contain an authorization code.

2. Navigate to https://login.microsoftonline.com/common/oauth2/deviceauth in your browser and submit the authorization code. The app registration is now verified and you can freely obtain access tokens.

Obtain Access Tokens for ROPC Authentication¶

After completing the previous steps, tokens can be generated for ROPC authentication using a POST request:

curl --location --request POST 'https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<client_id>' \
--data-urlencode 'scope=https://outlook.office.com/IMAP.AccessAsUser.All' \
--data-urlencode 'client_secret=<client_secret>' \
--data-urlencode 'username=<account_username>' \
--data-urlencode 'password=<account_password>' \
--data-urlencode 'grant_type=password'

• <client_id> and <tenant_id> are replaced with the Application (client) ID and Directory (tenant) ID you saved while creating your app registration.
• <client_secret> is replaced with the client secret you saved while creating your app registration.
• <account_username> and <account_password> are replaced with your Azure login credentials for ROPC authentication.

If successful, the response will contain an access_token for ROPC authentication.