This article contains instructions for how to connect to Exchange Online PowerShell using the Exchange Online PowerShell module with or without multi-factor authentication (MFA).
The Exchange Online PowerShell module uses modern authentication for connecting to all Exchange-related PowerShell environments in Microsoft 365: Exchange Online PowerShell, Security & Compliance PowerShell, and standalone Exchange Online Protection (EOP) PowerShell. For more information about the Exchange Online PowerShell module, see About the Exchange Online PowerShell 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.
Step 1: Load the Exchange Online PowerShell module
Note
If the module is already installed, you can typically skip this step and run Connect-ExchangeOnline without manually loading the module first.
After you've installed the module, open a PowerShell window and load the module by running the following command:
Import-Module ExchangeOnlineManagement
Step 2: Connect and authenticate
Note
Connect commands will likely fail if the profile path of the account that you used to connect contains special PowerShell characters (for example, $). The workaround is to connect using a different account that doesn't have special characters in the profile path.
The command that you need to run uses the following syntax:
When you use the ExchangeEnvironmentName parameter, you don't need use the ConnectionUri or AzureADAuthorizationEndPointUrl parameters. Common values for the ExchangeEnvironmentName parameter are described in the following table:
Environment
Value
Microsoft 365 or Microsoft 365 GCC
n/a*
Microsoft 365 GCC High
O365USGovGCCHigh
Microsoft 365 DoD
O365USGovDoD
Office 365 Germany
O365GermanyCloud
Office 365 operated by 21Vianet
O365China
* The required value O365Default is also the default value, so you don't need to use the ExchangeEnvironmentName parameter in Microsoft 365 or Microsoft 365 GCC environments.
The DelegatedOrganization parameter specifies the customer organization that you want to manage as an authorized Microsoft Partner. For more information, see the connection examples later in this article.
Depending on the nature of your organization, you might be able to omit the UserPrincipalName parameter in the connection command. Instead, you enter the username and password or select stored credentials 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 should be able to 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.
Use the SkipLoadingFormatData switch to avoid errors when connecting to Exchange Online PowerShell from within a Windows service.
Using the module in PowerShell 7 requires version 2.0.4 or later.
The connection examples in the following sections use modern authentication, and are incapable of using Basic authentication.
Connect to Exchange Online PowerShell with an interactive login prompt
The following examples work in Windows PowerShell 5.1 and PowerShell 7 for accounts with or without MFA:
This example connects to Exchange Online PowerShell in a Microsoft 365 or Microsoft 365 GCC organization:
In the sign-in window that opens, enter your password, and then click Sign in.
Note
In PowerShell 7, browser-based single sign-on (SSO) is used by default, so the sign-in prompt opens in your default web browser instead of a standalone dialog.
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.
PowerShell 7 exclusive connection methods
In PowerShell 7 for accounts without MFA, this example prompts for credentials within the PowerShell window:
In PowerShell 7 for accounts with or without MFA, this example uses another computer to authenticate and complete the connection. Typically, you use this method on computers that don't have web browsers (users are unable to enter their credentials in PowerShell 7):
Run the following command on the computer where you want to connect:
On any other device with a web browser and internet access, open https://microsoft.com/devicelogin and enter the <XXXXXXXXX> code value from the previous step.
Enter your credentials on the resulting pages.
In the confirmation prompt, click Continue. The next message should indicate success, and you can close the browser or tab.
The command from step 1 continues to connect you to Exchange Online PowerShell.
Connect to Exchange Online PowerShell without a login prompt (unattended scripts)
Be sure to disconnect the session when you're finished. If you close the PowerShell window without disconnecting the session, you could use up all the sessions available to you, and you need to wait for the sessions to expire. To disconnect the session, run the following command:
Disconnect-ExchangeOnline
To silently disconnect without a confirmation prompt, run the following command:
Disconnect-ExchangeOnline -Confirm:$false
Note
The disconnect command will likely fail if the profile path of the account that you used to connect contains special PowerShell characters (for example, $). The workaround is to connect using a different account that doesn't have special characters in the profile path.
How do you know you've connected successfully?
If you don't receive any errors, you've connected successfully. A quick test is to run an Exchange Online PowerShell cmdlet, for example, Get-AcceptedDomain, and see the results.
If you receive errors, check the following requirements:
A common problem is an incorrect password. Run the connection steps again and pay close attention to the username and password that you use.
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.
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.
REST-based connections to Exchange Online PowerShell require the PowerShellGet module, and by dependency, the PackageManagement module, so you'll receive errors if you try to connect without having them installed. For example, you might see the following error:
The term 'Update-ModuleManifest' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.
After you connect, you might received an error that looks like this:
Could not load file or assembly 'System.IdentityModel.Tokens.Jwt,Version=<Version>, Culture=neutral, PublicKeyToken=<TokenValue>'. Could not find or load a specific file.
This error happens when the Exchange Online PowerShell module conflicts with another module that's imported into the runspace. Try connecting in a new Windows PowerShell window before importing other modules.
Appendix: Comparison of old and new connection methods
This section attempts to compare older connection methods that have been replaced by the Exchange Online PowerShell module. The Basic authentication and OAuth token procedures are included for historical reference only and are no longer supported.
Connect without multi-factor authentication
Exchange Online PowerShell module with interactive credential prompt: