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):

Command

Description

Uses

Add-DistributionGroupMember

Adds users to a distribution group

“Add to DL” skill

Get-DistributionGroupMember

Fetches a list of distribution group members

Determine if a user already has access
Find group members for approval reachout
Build user lists for employee comms

New-DistributionGroup

Creates a new distribution group

“Create DL” skill

Get-DistributionGroup

Retrieve one or more distribution groups

Group ingestion (scrape all mailing lists)
Find group owners for approval reachout

Get-User

Retrieve one or more users

User ingestion (scrape all user identities)
Owner lookup (used w/ Get-DistributionGroup)

Get-EXORecipient

Retrieve one or more users. This is a more performant version of Get-User which is only available for customers using the Exchange Online v2 auth mechanism.

User ingestion (scrape all user identities)

New-PSSession
(Full command:

New-PSSession
-ConfigurationName Microsoft.Exchange
-ConnectionUri <https://outlook.office365.com/powershell-liveid/>
-Credential $Credential
-Authentication Basic
-AllowRedirection

)

Creates a powershell session using legacy basic auth mechanism.

Used to authenticate for each of the above commands (except Get-EXORecipient)

New-ExoPSSession
(Full command:

New-ExoPSSession  
-AppId $AppId  
-Organization $TenantDomain  
-Certificate $Certificate

)

Creates a powershell session using new exchange online v2 certificate auth mechanism. This command, which runs in 3-5 seconds, is extracted from the Connect-ExchangeOnline command, which runs in about 15 seconds.

Used to authenticate for each of the above commands (except New-PSSession)

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.

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:

1 Install-Module ExchangeOnlineManagement
2 
3 Get-Module ExchangeOnlineManagement # Version here should be 2.0.5***
4 
5 # If the above fails:
6 
7 # Import-Module ExchangeOnlineManagement
8 
9 $AppId = "<application id>"
10 
11 $TenantDomain = "<customer tenant domain>"
12 $CertificateBase64 = "<base64 encoded cert>"
13 
14 $CertificatePassword = "<customer password>"
15 
16 $CertBytes = [System.Convert]::FromBase64String($CertificateBase64)
17 
18 $Certificate = [System.Security.Cryptography.X509Certificates.X509Certificate2]::New($CertBytes, $CertificatePassword)
19 
20 $Session = Connect-ExchangeOnline -AppId $AppId -Organization $TenantDomain -Certificate $Certificate
21 
22 Disconnect-ExchangeOnline
23 
24 # Optional -- before disconnecting, you can try a few commands like s
25 
26 $SessionId = Import-PSSession $Session -CommandName Get-User -AllowClobber
27 Get-User "<customer username or email>"