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):
|Add-DistributionGroupMember||Adds users to a distribution group||“Add to DL” skill|
|Get-DistributionGroupMember||Fetches a list of distribution group members so we can||1. Determine if a user already has access|
2. Find group members for approval reachout
3. Build user lists for employee comms
|New-DistributionGroup||Creates a new distribution group||“Create DL” skill|
|Get-DistributionGroup||Retrieve one or more distribution groups||1. Group ingestion (scrape all mailing lists)|
2. Find group owners for approval reachout
|Get-User||Retrieve one or more users||1. User ingestion (scrape all user identities)|
2. 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)|
|Creates a powershell session using legacy basic auth mechanism.||Used to authenticate for each of the above commands (except Get-EXORecipient)|
|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)|
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-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.
for EXO V2 Module (modern authentication)
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.
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 –
.pfxfile generated in Step 3 - please also provide the expiration date
- certificate password – provided in Step 3 when signing & exporting the certificate
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>
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>"
Updated about 2 months ago