LinQ2 OAuth integration with Azure Outlook

LinQ2 OAuth integration with Azure Outlook

Introduction:

This document provides steps for connecting LinQ2 Email to SMA with Microsoft Office 365 email service. The main feature is to change from plain text username/password authentications to OAuth2.

New LinQ2 Email to SMS OAuth mail handler requires the following additional configuration parameters:

Figure 1 LinQ2 Outlook OAuth Configuration

Azure portal at the time of writing is accessible at https://portal.azure.com/  

Figure 2 Microsoft Azure Portal

OAuth Client Id: This is the Application (client) ID of the application that is created in the Microsoft Azure Portal.

OAuth Tenant Id: The Directory (tenant) ID from the application overview screen form the Microsoft Azure Portal.

Both the above values can be obtained from the Overview of the application from Azure Portal à App Registration à <Your App> à Overview:

Figure 3 Client ID & Tenant ID

OAuth Client Secret: The value of the client secret that is added under the “Certificates & Secrets” in application that is configured in the Microsoft Azure Portal. If no values are there then you might need to add a secret. The value is visible only when the secret is added for the first time, so note the value and keep it in a safe place for future references. Is obtained from the Azure Portal à App Registration à <Your App> à Certificates & Secrets:

Figure 4 Client Secret

OAuth Authority: This is the URL to be used while obtaining the OAuth Access Token. Normally there is no need to change the default value.

For Advanced purposes, the value can be update using the following procedure:

The default value is https://login.microsoftonline.com/%s/ , the system replaces %s with the tenant id, most of the cases this value should work. But, if you want to put complete URL including your tenant id or some other fix URL, just ignore %s and enter the full URL (e.g.  https://login.microsoftonline.com/<your_tenant _id>/)

OAuth Scope: This is the scope for the OAuth access tokens. The default value is not required to be changed most of the time. The configuration is available for future use if required. The default scope for Access Toke is https://outlook.office365.com/.default.  

On the exchange side we need to create an “Enterprise Application” and grant this application the access to specific mailbox.

Enter an application name, keep the other things as default or as per your requirements and click Register.

Figure 5 An Overview of Application account types

Now note your Application (client) ID and Directory (tenant) ID to be used inside LinQ2 P Series Email2SMS configuration.

Add description and change the expiry if desired, recommend is 6 months expiry. Click Add

Once the client secret is added don’t’ forget to note down the value for the secret. This value is only displayed once, only at the time the secret is created.

Select APIs my organization uses and search office 365, and select Office 365 Exchange Online

Select Application permissions à IMAP à IMAP.AccessAsApp and click Add permissions

We should grant admin consent to allow the app to access the designated mailboxes. This is done using Grant admin consent for <your_domain_name>

Click Yes to approve the gran of admin consent

The admin consent is granted for the API permission to the application

If not done already then login to the Microsoft 365 admin center and create a new email account to be used by the newly created enterprise application in the previous steps

Prerequisites, blue ones are required commands:

$PSVersionTable.PSVersion

Get-ExecutionPolicy -List

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Install-Module -Name Az -Scope CurrentUser -Repository PSGallery -Force

Install-Module AzureAD

Install-Module -Name ExchangeOnlineManagement 

Add new Service Principle:

Use the following PowerShell script to add a new service principal for the created application:

Connect-AzureAD

Connect-ExchangeOnline

$azapp = Get-AzureADApplication -SearchString '<your_app_name>'

$azsp = Get-AzureADServicePrincipal -SearchString $azapp.DisplayName

$sp = New-ServicePrincipal -AppId $azapp.AppId -ServiceId $azsp.ObjectId -DisplayName "EXO Service Principal for $($azapp.DisplayName)"

Sample Output

Link Microsoft Exchange Mailbox to the service principal:

Use the following PowerShell script to link a mailbox to the above created service principal:

$mbx = '<your_mailbox_address>'

$mbx | %{ Add-MailboxPermission -Identity $_ -User $sp.id -AccessRights FullAccess } | fl *

Get-MailboxPermission $mbx | ft -a

Sample Output 

Update the configurations for your email handler service in the in the P Series backend configuration Don’t forget to update the Mail ID in the P Series Email backend to point to the email address that you just linked with the Azure Application. The new LinQ2 P Series service is to be used for accessing the Exchange Online using OAuth2.

After following all the configurations required for your Email to SMS like the user and group access lists, restart the application server (e.g. Wildfly etc.). Now a plain text email sent to the configured email address using the email address that is configured in the Email to SMS backend, shall generate and SMS to the number in the Subject line of the email.