Discussion Thread View
Expand all | Collapse all

Changing Mail Provider to Exchange Online (Microsoft 365) using OAuth

  • 1.  Changing Mail Provider to Exchange Online (Microsoft 365) using OAuth

    Posted 02-10-2021 22:35
    Edited by Jeff Hoogkamer 02-15-2021 04:01

    Hi All,

    *EDIT 15-Feb-2021 - added Step 4 about API permissions, updated script to use single quotation marks*

    Just thought I'd post my journey changing the Mail provider in PureConnect over from an Exchange 2013 On-Premise using Basic Authentication over to using Exchange Online (Microsoft 365) using OAuth authentication.

    The PureConnect help documentation for Configuring domain properties for an Exchange provider just had this information about using OAuth:

    To use OAuth to authenticate with Exchange, under Use OAuth, enter the certificate, certificate password, and the application ID that were generated during the application registration in the Microsoft Azure portal to request an access token that is passed during requests to Exchange.

    As this is my first time using Exchange Online and OAuth - the instructions seemed to indicate the Certificate file and Certificate password were generated by the Azure portal. However it turns out I needed to create the Certificate file (in both .pfx and .cer format) with a Certificate password using a Powershell Admin script first. The .cer is used in the Azure portal, the .pfx is used in the CIC Mail provider configuration.

    So before proceeding, these steps assume:

    a. You already have a CIC Service Account setup on your Exchange Online platform, and it can already impersonate the required mailboxes also on Exchange Online
    b. You know your Domain as configured in the Microsoft/Office 365 Admin Center > Domains (i.e. the default)
    c. Choose your own Certificate password (and take note of what you choose for later)

    These were the steps I ended up following after digging around the internet for answers - hopefully this helps you on your journey - however please note this is not a definitive guide and use this information at your own risk. Try this in a development or test environment first without using your production CIC Service Account and mailboxes, or at least make sure you know how your current configuration is setup and you're able to revert back.

    Step 1: Create your Certificate.pfx and Certificate.cer file with Certificate Password

    Running Powershell as an administrator from your computer (doesn't have to be the CIC server), use the following script after updating your Domain, Password and File Name:

    # Run this script as an administrator
    # --- config start
    $dnsName = 'your.domain.com' # This is the tenant domain configured in your Microsoft 365 Admin Center (under Domains, look for the Default)
    $password = 'enterpasswordhere' # You enter a certificate password here and take note of it - don't use dollar sign in the password
    $folderPath = 'C:\temp' # Where do you want the files to get saved to? The folder needs to exist.
    $fileName = 'CIC_OAUTH_CERTIFICATE_your.domain.com' # The name of the certificate - I chose to add the Domain name at the end
    $yearsValid = 10 # Number of years until you need to renew the certificate
    # --- config end
    $certStoreLocation = 'cert:\LocalMachine\My'
    $expirationDate = (Get-Date).AddYears($yearsValid)
    $certificate = New-SelfSignedCertificate -DnsName $dnsName -CertStoreLocation $certStoreLocation -NotAfter $expirationDate -KeyExportPolicy Exportable -KeySpec Signature
    $certificatePath = $certStoreLocation + '\' + $certificate.Thumbprint
    $filePath = $folderPath + '\' + $fileName
    $securePassword = ConvertTo-SecureString -String $password -Force -AsPlainText
    Export-Certificate -Cert $certificatePath -FilePath ($filePath + '.cer')
    Export-PfxCertificate -Cert $certificatePath -FilePath ($filePath + '.pfx') -Password $securePassword

    If you get an error and realize that you haven't installed the Azure AD PowerShell module yet, you can do it with this command in PowerShell

    Install-Module -Name AzureAD

    Step 2:  Creating the Application and register in Azure Portal

    These steps are pretty much cut/paste from the same step from https://laurakokkarinen.com/authenticating-to-office-365-apis-with-a-certificate-step-by-step/ article:

    If you don't yet have an existing app registration, here are the steps for doing that. If you do, you can skip this section and go to the Adding the certificate section.

    1. Go to https://portal.azure.com
    2. Click on Azure Active Directory on the left navigation.
    3. Click on App registrations (the new blade, not the legacy one).
    4. New registration:
      1. Give it a descriptive name e.g. CIC EWS
      2. Select supported account types. e.g. Accounts in any organisational directory
      3. Redirect URI is not required.

    After your app has been created, note down the following information from the Overview tab. You'll need these in your solution.

    • Application (client) ID

    Step 3: Adding the Certificate

    These steps are pretty much cut/paste from the same step from https://laurakokkarinen.com/authenticating-to-office-365-apis-with-a-certificate-step-by-step/ article:

    In your application registration…

    1. Go to Certificates & secrets.
    2. Click Upload certificate.
    3. Select the .cer file we generated with the PowerShell script, and click Add.
    4. If prompted for the Certificate Password, enter it as well.

    Step 4: API permissions

    Also within the Azure Portal:

    In your application registration…

    1. Go to API permissions.
    2. Confirm that the 'full_access_as_app' permission is listed
    3. Select Grant admin consent for org and accept the consent dialog

    Step 5: Configure Exchange Mail provider in PureConnect

    Following the steps from Configuring domain properties for an Exchange provider you should now be able to configure OAuth with the following:

    Application ID:  This is from Step 2 from the Azure portal
    Certificate:  Choose the Certificate File (in .pfx format) that you created earlier from Step 1
    Password:  Use the Certificate Password you defined earlier from Step 1
    Service URL:   This will be the default Office 365 EWS URL - https://outlook.office365.com/EWS/Exchange.asmx

    Click OK and you should be done.

    For me, after this step it all worked and I was able to then resume using email functionality within PureConnect including address book/name lookups, email routing in through Attendant mailboxes, sending emails, and voicemails from my own account appearing.

    Hope that helps someone!



  • 2.  RE: Changing Mail Provider to Exchange Online (Microsoft 365) using OAuth

    Posted 21 days ago
    Hi, Jeff, thanks a lot for posting this Step by Step.
    This helped us alot !
    Regards, Bart Meul

    Bart Meul
    Telenet BVBA