Auth Integration Overview: Exchange Online

Moveworks uses a microservice architecture to structure our backend integrations as a collection of loosely coupled services. One of our core services is our Auth service. This service was built to give the Moveworks Bot a structured and extensible way to interact with various configurations of authentication systems.

The Moveworks Auth Service allows the Moveworks platform to interact with Exchange users & distribution lists while requiring only minimal configuration on the Exchange side (Currently just admin access to the service account).

The table below outlines the core actions supported through the Moveworks Auth Service specific to Exchange (the actions listed below are subject to evolve with product improvements):

Operation Frequency

Most of the commands written above (read and write alike) do not get called more than a few times a day. Their usage is tied to the frequency with which employees make use of the “Access DL” / “Create DL” skills. They also only return a few objects per query and are therefore not particularly heavy in terms of network load.

The exceptions to the above rule are the following READ operations:

Get-User / Get-EXORecipient - These are used for user ingestion, which runs every 4 hours and may be I/O intensive depending on the number of users in the organization.

Get-DistributionGroup - This is used for group ingestion, which runs every 12 hours and may be I/O intensive depending on the number of distribution groups in the organization.

Get-DistributionGroupMember - This does not run on a fixed cadence and may be very rare. When used in the access DL skill it should be a very lightweight operation, but the comms product uses this method to list every direct and indirect member of a given distribution list, which may be I/O intensive depending on the size of the list. For example, a comm sent to the “All employees” mailing list may make this operation very expensive.

Microsoft Exchange Online Access Needs

for EXO V2 Module (modern authentication)

Overview

To manage email distribution lists in a Microsoft Exchange Online environment, Moveworks requires an App Registration with the ability to connect to Exchange Online via remote PowerShell and permissions to manage Distribution Lists. Moveworks uses Windows Remote Management (WinRM) which is the protocol for remote PowerShell. Once the connection is established, all data exchange happens over SSL.

Setting up the App Registration

Follow the steps indicated in the Microsoft guide for App-only authentication.

In Step 5, please assign the Exchange Administrator role which is required for Exchange Online Powershell access.

What to share with Moveworks

As you go through the steps, please gather the following details for configuration:

• app_id - gathered in Step 4.3
• tenant_domain – your named domain (typically includes .onmicrosoft.com)
• certificate file – .pfx file generated in Step 3 - please also provide the expiration date
• certificate password – provided in Step 3 when signing & exporting the certificate
  • Ensure that the password does not have illegal characters like -

Validating the Credentials

An administrator can validate the credentials with the script below. Please note this cannot be run in MacOS, but can work in the following environments:

• Windows or Linux computer
• PowerShell Cloud environment

Here is how to obtain the base-64 encrypted certificate using a bash command:

base64 -i <certificate filepath>

Once obtained, the following script can be used to verify authentication works as expected:

Install-Module ExchangeOnlineManagement

Get-Module ExchangeOnlineManagement # Version here should be 2.0.5***

# If the above fails:

# Import-Module ExchangeOnlineManagement

$AppId = "<application id>"

$TenantDomain = "<customer tenant domain>"
$CertificateBase64 = "<base64 encoded cert>"

$CertificatePassword = "<customer password>"

$CertBytes = [System.Convert]::FromBase64String($CertificateBase64)

$Certificate = [System.Security.Cryptography.X509Certificates.X509Certificate2]::New($CertBytes, $CertificatePassword)

$Session = Connect-ExchangeOnline -AppId $AppId -Organization $TenantDomain -Certificate $Certificate

Disconnect-ExchangeOnline

# Optional -- before disconnecting, you can try a few commands like s

$SessionId = Import-PSSession $Session -CommandName Get-User -AllowClobber
Get-User "<customer username or email>"