--- title: Microsoft Exchange Online Access Requirements excerpt: '' deprecated: false hidden: false metadata: title: '' description: '' robots: index next: description: '' --- # 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](https://docs.microsoft.com/en-us/powershell/module/exchange/add-distributiongroupmember?view=exchange-ps) Adds users to a distribution group “Add to DL” skill
[Get-DistributionGroupMember](https://docs.microsoft.com/en-us/powershell/module/exchange/get-distributiongroupmember?view=exchange-ps) Fetches a list of distribution group members 1. Determine if a user already has access 2. Find group members for approval reachout 3. Build user lists for employee comms
[New-DistributionGroup](https://docs.microsoft.com/en-us/powershell/module/exchange/new-distributiongroup?view=exchange-ps) Creates a new distribution group “Create DL” skill
[Get-DistributionGroup](https://docs.microsoft.com/en-us/powershell/module/exchange/get-distributiongroup?view=exchange-ps) Retrieve one or more distribution groups 1. Group ingestion (scrape all mailing lists) 2. Find group owners for approval reachout
[Get-User](https://docs.microsoft.com/en-us/powershell/module/exchange/get-user?view=exchange-ps) Retrieve one or more users 1. User ingestion (scrape all user identities) 2. Owner lookup (used w/ Get-DistributionGroup)
[Get-EXORecipient](https://docs.microsoft.com/en-us/powershell/module/exchange/get-exorecipient?view=exchange-ps) 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](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/new-pssession?view=powershell-7.2)
(Full command:
``` New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri -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](https://docs.microsoft.com/en-us/powershell/module/exchange/connect-exchangeonline?view=exchange-ps) 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](https://docs.microsoft.com/en-us/windows/win32/winrm/portal)) 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](https://docs.microsoft.com/en-us/powershell/exchange/app-only-auth-powershell-v2?view=exchange-ps). In [Step 5](https://learn.microsoft.com/en-us/powershell/exchange/app-only-auth-powershell-v2?view=exchange-ps#step-5-assign-microsoft-entra-roles-to-the-application), 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](https://docs.microsoft.com/en-us/powershell/exchange/app-only-auth-powershell-v2?view=exchange-ps#step-4-attach-the-certificate-to-the-azure-ad-application) * **tenant\_domain** – your named domain (typically includes .onmicrosoft.com) * **certificate file** – **`.pfx`** file generated [in Step 3](https://docs.microsoft.com/en-us/powershell/exchange/app-only-auth-powershell-v2?view=exchange-ps#step-3-generate-a-self-signed-certificate) - please also provide the expiration date * **certificate password** – provided [in Step 3](https://docs.microsoft.com/en-us/powershell/exchange/app-only-auth-powershell-v2?view=exchange-ps#step-3-generate-a-self-signed-certificate) 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 ` ### Once obtained, the following script can be used to verify authentication works as expected: ```powershell Install-Module ExchangeOnlineManagement Get-Module ExchangeOnlineManagement # Version here should be 2.0.5*** # If the above fails: # Import-Module ExchangeOnlineManagement $AppId = "" $TenantDomain = "" $CertificateBase64 = "" $CertificatePassword = "" $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 "" ```