Today, Exchange Online is managed through PowerShell by creating a remote PowerShell session to Exchange Online (this existing process is described here: Connect to Exchange Online PowerShell).

This process does not use a dedicated local PowerShell module and has never supported Multi-Factor Authentication (MFA) which is very important for privileged Administrator accounts.

To address MFA, Microsoft has recently released a PowerShell module which is used to authenticate with MFA, and then establishes a remove PowerShell session. Instructions on using this new module are described here: Connect to Exchange Online PowerShell using multi-factor authentication.

The remainder of this article has tips and answers common questions about this new module.

Installing the EXO MFA PowerShell Module

The primary supported method to get and install this new module from the Exchange Admin Center (EAC) in Exchange Online. The Hybrid Configuration Wizard in the EAC has an option to download and install the module. See Connect to Exchange Online PowerShell using multi-factor authentication for specific instructions on installing from the EAC. This installation uses the ClickOnce installation method to install and auto-update.

Tip – some people are getting this module from this previous preview link: http://aka.ms/exopspreview.  I would not recommend this since there is no guarantee it contains the latest bits.

Another option is to install it using a PowerShell Gallery Load-Exchange MFA Module written by Jos Verlinde. This is not a Microsoft module, so inspect and install as you would any untrusted source. It also installs via ClickOnce and check’s for any updates. The benefit of this module is that it installs the EXO module if it is not installs it, and loads it the local PowerShell session (including PowerShell ISE – see Q&A section below for more information).

Tip – you must run in a PowerShell session with elevated Administrator rights to install the new Exchange Online Module.

From a client computer with Windows Management Foundation (WMF) 5.0 or greater, run the following PowerShell (Windows 10 has WMF 5 installed):

Install-Script -Name Load-ExchangeMFA.  This installs a PowerShell script called Load-ExchangeMFA.ps1 (the installation directory is C:\Program Files\WindowsPowerShell\Scripts by default). This script exposes the following functions to use and install the new EXO PowerShell Module:

• Load-ExchangeMFA.ps1 – imports the MFA module, loads it into the current PowerShell session, and invokes a MFA connection to Exchange Online (including the interactive logon for MFA)
• Install-ClickOnce  – installs the MFA module
• Get-ClickOnce – checks the location of the installed module
• Test-ClickOnce – test the installation of the MFA module
• Uninstall-ClickOnce – uninstall the MFA module

To use the module, load it with the following script :  Load-ExchangeMFA.ps1.  This PowerShell module allows you to connect to Exchange Online service with the following cmdlet:  Connect-EXOPSSession -UserPrincipalName <your UPN>

Tip – I have an issue on a couple of client machines where the authentication failed with the following error:

New-ExoPSSession : Create Powershell Session is failed using OAuth
At C:\Users\curti\AppData\Local\Apps\2.0\AN5BH7D1.Q5V\Z9RHER5V.08Z\micr..tion_c3bce3770c238a49_0010.0000_90fa60bba125a33a\CreateExoPSSession.ps1:179
char:22
+ … PSSession = New-ExoPSSession -UserPrincipalName $UserPrincipalName -C …
+                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [New-ExoPSSession], Exception
    + FullyQualifiedErrorId : System.Exception,Microsoft.Exchange.Management.ExoPowershellSnapin.NewExoPSSession

The issue is the  Load-ExchangeMFA.ps1 script seems to set the PowerShell Session options to expect an IE Proxy, which isn’t required or available on some clients.  You can work around this by setting the $ProxySetting to null at the end of this script as follows:

$ProxySetting = $null
Connect-EXOPSSession -PSSessionOption $ProxySetting

Enabling the new Exchange Online MFA PowerShell Module

Once installed, there are 2 primary pre-requisites that must be met:

1. The administrative account you are connecting with must be enabled for MFA.
2. The administrative account you are connecting with are enabled to use Exchange Online PowerShell

Is administrative account MFA enabled?

The user principal being used to connect and authenticate needs to be enabled for MFA. This setting can be viewed and changed in the user properties in the Office 365 Admin Portal, or using the Office 365 MSOnline PowerShell module Get-MsolUser cmdlet (now called the Azure AD PowerShell module) as follows:

$userAuth = Get-MsolUser -UserPrincipalName NewUserAdminTest@Ucclearly.com | Select StrongAuthenticationRequirements
$userAuth.StrongAuthenticationRequirements.State

Is the administrative account you are connecting with enabled to use Exchange Online PowerShell?

Office 365 user accounts, including Administrator ones, are enabled for Exchange Online PowerShell by default. See Enable or disable access to Exchange Online PowerShell for more information.

Tip – Enabling your Exchange Online Tenant for MFA

I have seen references to the requirement that the Exchange Online tenant must be enabled for MFA.  There is a setting in the Exchange Online tenant to enables oAuth authentication. In practice, I have I have been able to authenticate with MFA despite this setting being set to $false so I do not believe it is a requirement.  If it becomes a requirement, you can see whether it is enabled with this Exchange Online PowerShell cmdlet

Get-OrganizationConfig | select OAuth2ClientProfileEnabled

And it can be enabled on EXO tenant with the following EXO PowerShell cmdlet:

Set-OrganizationConfig –OAuth2ClientProfileEnabled $true

Common Questions and Answers

Q. What if I try to Authenticate with MFA on an Account that is not Enabled for MFA? (i.e. programmatically without a user authenticating with the web form)

A. No easily supported document method today. I assume this will come soon. If you are technical and clever enough to use oAuth tokens and creating remote PowerShell sessions, it likely can be done.

Q. Will this Module Replace the Current Exchange Online Module?

A. There are no current plans to remove the ability to connect to Exchange Online as it is done today (as described here: https://technet.microsoft.com/en-us/library/jj984289%28v=exchg.160%29.aspx).

Q. What if I try to Authenticate with MFA on an Account that is not Enabled for MFA?

A. The authentication will fail with the following error:

New-ExoPSSession : Create Powershell Session is failed using OAuth
At C:\Users\<local user name>\AppData\Local\Apps\2.0\AN5BH7D1.Q5V\Z9RHER5V.08Z\micr..tion_c3bce3770c238a49_0010.0000_90fa60bba125a33a\CreateExoPSSession.ps1:179
char:22
+ … PSSession = New-ExoPSSession -UserPrincipalName $UserPrincipalName -C …
+                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [New-ExoPSSession], Exception
    + FullyQualifiedErrorId : System.Exception,Microsoft.Exchange.Management.ExoPowershellSnapin.NewExoPSSession

Q. What type of PowerShell module is this, and where is it installed?

A. This module is not implemented like many of the other PowerShell modules. It is a PowerShell script that uses several application dll’s. The main dll is named Microsoft.Exchange.Management.ExoPowershellModule and is implemented in the Microsoft.Exchange.Management.ExoPowershellModule.dll which is installed in the users local application folder.  In Windows 10 this will equates to “C:\Users\<user name>\AppData\Local\Apps”, and you will find the Exchange Online PowerShell Module .dll and associated manifest in a hidden directory something like this:

> C:\Users\<user name>\AppData\Local\Apps\2.0\AN5BH7D1.Q5V\Z9RHER5V.08Z\micr..tion_c3bce3770c238a49_0010.0000_90fa60bba125a33a

Tip – a quick way to get the installation directory on any client machine is to find it with the Get-Module cmdlet and launch it in Windows Explorer using this PowerShell cmdlet:

1. > explorer.exe $(Get-Item $(Get-Module Microsoft.Exchange.Management.ExoPowershellModule).Path).Directory.FullName

The dll module implements and exports one cmdlet: New-ExoPSSession.

The main PS script in this directory is called CreateExoSession.ps1 and is the wrapper around loading the DLL’s and creating the implicit remote PowerShell sessions. The PowerShell function Connect-EXOPSSession is the key wrapper function for creating the remote PowerShell session with MFA – it loads the EXO module and establishes the remote PowerShell session using the New-ExoPSSession cmdlet.

These details could be useful when using this module from PowerShell ISE (see the next question).

Q.  Can I use this module from PowerShell ISE?

A. Yes.  Currently (March 2017) it is a bit cumbersome.  There are two ways as described below.

1. Copy the Exchange Online MFA modules to a Locate Folder and Invoke it from the Command Line in PowerShell ISE

My understanding is that the location of EXO MFA Module can change when it’s auto-updated, so use the following PowerShell to launch Windows explorer to the currently installed directory:

Explorer.exe $(Get-Item $(Get-Module Microsoft.Exchange.Management.ExoPowershellModule).Path).Directory.FullName

Copy these files to a local folder, call the main associated PowerShell script, and the main cmdlet to connect to EXO as follows:

1. cd <to locally installed folder>
2. ..\CreateExoPSSession.ps1
3. Connect-EXPPSSession –UserPrincipalName user@example.com

This can be simplified by wrapping these steps into a PowerShell function that is loaded automatically in a PowerShell profile.

2. Use the PowerShell Gallery Load-Exchange MFA Module written by Jos Verlinde

This is an unknown author (to me), so inspect before you install.  This is a very useful module which exposes a couple of cmdlets/scripts, the most useful being the Load-ExchangeMFA.ps1 script. Once you have the module installed, just call Load-ExchangeMFA.ps1 from PowerShell ISE. It ensures the latest Exchange Online MFA PowerShell module is installed and calls Connect-EXPOPSSession to initiate an MFA Exchange Online session.

Tip – if you are getting an error while authenticating, and everything else is installed and configured correctly, try settings the IEProxySettings to null at the end of the Load-ExchangeMFA.ps1 script.

$ProxySetting = $null
Connect-EXOPSSession -PSSessionOption $ProxySetting

Key Resources

Connect to Exchange Online PowerShell using multi-factor authentication – TechNet article on using MFA with this module

Enable or disable access to Exchange Online PowerShell – TechNet article describing how to enable Exchange Online PowerShell for a user (administrator)

PowerShell Gallery Load-Exchange MFA Module – A module by Jos Verlinde to install and load the new Exchange Online PowerShell module in a PowerShell session

Azure Active Directory Authentication Library (ADAL) GitHub Project – the Github project for the Microsoft.ADAL.PowerShell module wrapper around the Azure Active Directory Authentication Library (ADAL)