Connect to Exchange Online PowerShell MFA
This article – Connect to Exchange Online PowerShell MFA – describes steps on how to connect to Exchange Online PowerShell using the Exchange Online PowerShell v2 module (abbreviated EXO V2 module) with or without MFA.
This article assumes you have already installed the Exchange Online PowerShell V2 module. Details on how to install the EXO V2 module can be found here.
The Exchange Online PowerShell V2 module makes use of modern authentication and works with multi-factor authentication (MFA) for connecting to all Microsoft Exchange-related PowerShell environments in Microsoft 365 / Office 365:
- Exchange Online PowerShell.
- Standalone Exchange Online Protection (EOP) PowerShell.
- Security & Compliance PowerShell.
Check to see if the Exchange Online PowerShell V2 module (EXO V2 module) is installed
To check if EXO V2 module is installed on your system do the following:
- Open PowerShell window as an Administrator
- Type “Get-InstalledModule -Name ExchangeOnlineManagement | Select Name,Version,PublishedDate,InstalledDate,InstalledLocation” and press Enter
- The output would look like the image shown below.
Note.
- The Get-InstalledModule cmdlet gets PowerShell modules that are installed on a computer using PowerShellGet.
- To see all modules installed on the system, use the Get-Module -ListAvailable command.
Introduction – Connect to Exchange Online PowerShell V2 with MFA or without mfa.
To use the older, less secure remote PowerShell connection instructions that will eventually be deprecated, see Basic auth – Connect to Exchange Online PowerShell.
To use the older Exchange Online Remote PowerShell Module to connect to Exchange Online PowerShell using MFA, see V1 module – Connect to Exchange Online PowerShell using MFA. Note that this older version of the module will eventually be retired.
Useful to know before you begin?
The requirements for installing and using the EXO V2 module are described in Install and maintain the EXO V2 module.
After you connect, the cmdlets and parameters that you have or don’t have access to is controlled by role-based access control (RBAC). For more information, see Permissions in Exchange Online.
To find the permissions that are required to run specific Exchange Online cmdlets, see Find the permissions required to run any Exchange cmdlet.
If your organization is on-premises Exchange, and you have Exchange Enterprise CAL with Services licenses for Exchange Online Protection (EOP), your EOP PowerShell connection instructions are the same as Exchange Online PowerShell as described in this article.
Connect to Exchange Online PowerShell using modern authentication with or without MFA
These connection instructions use modern authentication and work with or without multi-factor authentication (MFA).
1. Load the EXO V2 module
In a PowerShell window, load the EXO V2 module by running the following command:
PowerShell
Import-Module ExchangeOnlineManagement
Notes:
- If you’ve already installed the EXO V2 module, the previous command will work as written.
- You might be able to skip this step and run Connect-ExchangeOnline without loading the module first.
2. Connect to Exchange Online PowerShell v2 MFA Script
The command that you need to run uses the following syntax:
PowerShell
Connect-ExchangeOnline -UserPrincipalName [-ShowBanner:$false] [-ExchangeEnvironmentName ] [-DelegatedOrganization ] [-PSSessionOption $ProxyOptions]
- <UPN> is your account in user principal name format (for example,
[email protected]
). - When you use the ExchangeEnvironmentName parameter, you don’t need to use the ConnectionUri or AzureADAuthorizationEndPointUrl parameters. For more information, see the parameter descriptions in Connect-ExchangeOnline.
- The DelegatedOrganization parameter specifies the customer organization that you want to manage as an authorized Microsoft Partner. For more information, see Partners.
- If you’re behind a proxy server, run this command first:
$ProxyOptions = New-PSSessionOption -ProxyAccessType <Value>
, where <Value> isIEConfig
,WinHttpConfig
, orAutoDetect
. Then, use the PSSessionOption parameter with the value$ProxyOptions
. For more information, see New-PSSessionOption. - You can often omit the UserPrincipalName parameter in the next step to enter both the username and password after you run the Connect-ExchangeOnline command. If it doesn’t work, then you need to use the UserPrincipalName parameter.
- If you aren’t using MFA, you can often use the Credential parameter instead of the UserPrincipalName parameter. First, run the command
$Credential = Get-Credential
, enter your username and password, and then use the variable name for the Credential parameter (-Credential $Credential
). If it doesn’t work, then you need to use the UserPrincipalName parameter.
This example connects to Exchange Online PowerShell V2 MFA in a Microsoft 365 or Microsoft 365 GCC organization:
PowerShell
Connect-ExchangeOnline -UserPrincipalName [email protected]
This example connects to Exchange Online PowerShell in an Office 365 Germany organization:
PowerShell
Connect-ExchangeOnline -UserPrincipalName [email protected] -ExchangeEnvironmentName O365GermanyCloud
This example connects to Exchange Online PowerShell in a Microsoft GCC High organization:
PowerShell
Connect-ExchangeOnline -UserPrincipalName [email protected] -ExchangeEnvironmentName O365USGovGCCHigh
This example connects to Exchange Online PowerShell in a Microsoft 365 DoD organization:
PowerShell
Connect-ExchangeOnline -UserPrincipalName [email protected] -ExchangeEnvironmentName O365USGovDoD
This example connects to Exchange Online PowerShell to manage another tenant:
PowerShell
Connect-ExchangeOnline -UserPrincipalName [email protected] -DelegatedOrganization adatum.onmicrosoft.com
In the sign-in window that opens, enter your password, and then click Sign in.
MFA only: A verification code is generated and delivered based on the response option that’s configured for your account (for example, a text message or the Microsoft Authenticator app on your device).In the verification window that opens, enter the verification code, and then click Verify.
For detailed syntax and parameter information, see Connect-ExchangeOnline.
Exchange Online PowerShell commands
If you don’t receive any errors after putting in your username and password plus your verification code, then you will have connected successfully.
Exchange Online PowerShell Commands (cmdlets) are imported into your local PowerShell session and tracked by a progress bar at the top of your PowerShell window.
To list a majority of the Exchange Online PowerShell commands – on your screen, run the following command in your PowerShell window:
get-command *mail*
Disconnect-ExchangeOnline
Note
Be sure to disconnect the remote PowerShell session when you’re finished. If you close the PowerShell window without disconnecting the session, you could use up all the remote PowerShell sessions available to you, and you’ll need to wait for the sessions to expire. To disconnect the remote PowerShell session, run the following command.
PowerShell
Disconnect-ExchangeOnline
PowerShell 7 log in experiences
This section describes the log in experiences that are available in version 2.0.4 or later of the EXO V2 module in PowerShell 7.
For more information about the operating systems that are supported by the EXO V2 module in PowerShell 7, see Supported operating systems for the EXO V2 module.
For detailed syntax and parameter information, see Connect-ExchangeOnline.
Interactive scripting using browser-based single sign-on
Browser-based single sign-on (SSO) is the default log in method in PowerShell 7. The Connect-ExchangeOnline command opens the Azure AD login page in the default browser. After you enter your credentials, older Exchange Online cmdlets and EXO V2 module cmdlets are available in the resulting PowerShell session.
If you use the UserPrincipalName parameter in the command, the UPN value is used on the login page in the browser.
PowerShell
Connect-ExchangeOnline -UserPrincipalName [email protected]
Device-based log in
Use device-based log in when no browser is available (and therefore, you can’t see the login page):
PowerShell
Connect-ExchangeOnline -Device
The command returns a URL and unique code that’s tied to the session. You need to open the URL in a browser on any computer, and then enter the unique code. After you complete the login in the web browser, the session in the Powershell 7 window is authenticated via the regular Azure AD authentication flow, and the Exchange Online cmdlets are imported after few seconds.
Inline credentials
You can enter your credentials directly in the PowerShell window without the need to go to the browser for SSO.
Note
This method does not work with accounts that use multi-factor authentication.
This method is an improvement on the Credential parameter, because you don’t need to store the credentials locally in a script, and you can enter the credentials directly in an interactive PowerShell session.
PowerShell
Connect-ExchangeOnline -InlineCredential
Checking to see if this worked?
The Exchange Online cmdlets are imported into your local PowerShell session and tracked by a progress bar at the top of your PowerShell window. If you don’t receive any errors, you connected successfully. A quick test is to run an Exchange Online PowerShell cmdlet, for example, Get-Mailbox, and see the results.
If you receive errors, check the following requirements:
- A common problem is an incorrect password. Run the three steps again and pay close attention to the username and password that you use.
- To help prevent denial-of-service (DoS) attacks, you’re limited to five open remote PowerShell connections to Exchange Online.
- TCP port 80 traffic needs to be open between your local computer and Microsoft 365. It’s probably open, but it’s something to consider if your organization has a restrictive internet access policy.
- The account that you use to connect to must be enabled for remote PowerShell. For more information, see Enable or disable access to Exchange Online PowerShell.
- If your organization uses federated authentication, and your identity provider (IDP) and/or security token service (STS) isn’t publicly available, you can’t use a federated account to connect to Exchange Online PowerShell. Instead, create and use a non-federated account in Microsoft 365 to connect to Exchange Online PowerShell.
Recommended Info
You will get some helpful information if you receive an error when you try to create an inbox rule in Outlook on the web (formerly known as Outlook Web App (OWA)) or by using the Exchange Management Shell.
There are multiple recipients matching the identity error – Exchange