Connect to Exchange Online PowerShell

The Exchange Online PowerShell V2 module (abbreviated as the EXO V2 module) uses modern authentication and works with multi-factor authentication (MFA) 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 EXO V2 module, see About the Exchange Online PowerShell V2 module.

This article contains instructions for how to connect to Exchange Online PowerShell using the EXO V2 module with 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.

What do you need 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.

    Note

    The rest of the instructions in the article assume that you've already installed the 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.

Tip

Having problems? Ask in the Exchange Online forum.

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).

For other sign in methods that are available in PowerShell 7, see the PowerShell 7 log in experiences section later in this topic.

  1. In a PowerShell window, load the EXO V2 module by running the following command:

    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. The command that you need to run uses the following syntax:

    Connect-ExchangeOnline -UserPrincipalName <UPN> [-ShowBanner:$false] [-ExchangeEnvironmentName <Value>] [-DelegatedOrganization <String>] [-PSSessionOption $ProxyOptions]
    
    • <UPN> is your account in user principal name format (for example, navin@contoso.com).
    • When you use the ExchangeEnvironmentName parameter, you don't need 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> is IEConfig, WinHttpConfig, or AutoDetect. 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 in a Microsoft 365 or Microsoft 365 GCC organization:

    Connect-ExchangeOnline -UserPrincipalName navin@contoso.com
    

    This example connects to Exchange Online PowerShell in an Office 365 Germany organization:

    Connect-ExchangeOnline -UserPrincipalName lukas@fabrikam.de -ExchangeEnvironmentName O365GermanyCloud
    

    This example connects to Exchange Online PowerShell in a Microsoft GCC High organization:

    Connect-ExchangeOnline -UserPrincipalName laura@blueyonderairlines.us -ExchangeEnvironmentName O365USGovGCCHigh
    

    This example connects to Exchange Online PowerShell in a Microsoft 365 DoD organization:

    Connect-ExchangeOnline -UserPrincipalName julia@adatum.mil -ExchangeEnvironmentName O365USGovDoD
    

    This example connects to Exchange Online PowerShell to manage another tenant:

    Connect-ExchangeOnline -UserPrincipalName navin@contoso.com -DelegatedOrganization adatum.onmicrosoft.com
    
  3. In the sign-in window that opens, enter your password, and then click Sign in.

    Enter your password in the Sign in to your account window

  4. 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.

    Enter your verification code in the Sign in to your account window

For detailed syntax and parameter information, see Connect-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.

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.

Connect-ExchangeOnline -UserPrincipalName navin@contoso.onmicrosoft.com

Device-based log in

Use device-based log in when no browser is available (and therefore, you can't see the login page):

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.

Connect-ExchangeOnline -InlineCredential

How do you know this worked?

The Exchange Online cmdlets are imported into your local PowerShell session and tracked by a progress bar. 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.

  • 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.

  • 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.