Connect to Exchange Online Protection 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 Protection PowerShell using the EXO V2 module with or without using MFA.

To use the older, less secure remote PowerShell connection instructions that will eventually be deprecated, see Basic auth - Connect to Exchange Online Protection PowerShell.

What do you need to know before you begin?

  • The procedures in this article are only for Microsoft 365 organizations that don't have Exchange Online mailboxes. For example, you have a standalone EOP subscription that protects your on-premises email environment. If your Microsoft 365 subscription includes Exchange Online mailboxes, you can't connect to EOP PowerShell; instead, you connect to Exchange Online PowerShell.

    If your organization is on-premises Exchange, and you have Exchange Enterprise CAL with Services licenses for EOP, your EOP PowerShell connection instructions are the same as Exchange Online PowerShell. Use the Exchange Online PowerShell connection instructions in Connect to Exchange Online PowerShell instead of the instructions in this article.

  • The requirements for installing and using the EXO V2 module are described in Install and maintain the EXO V2 module. 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 standalone EOP.

Tip

Having problems? Ask for help in the Exchange Online Protection forum.

Connect to Exchange Online Protection PowerShell using MFA and modern authentication

If your account uses multi-factor authentication, use the steps in this section. Otherwise, skip to the Connect to Exchange Online Protection PowerShell using modern authentication section.

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

    Import-Module ExchangeOnlineManagement
    

    Note: If you've already installed the EXO V2 module, the previous command will work as written.

  2. The command that you need to run uses the following syntax:

    Connect-IPPSSession -UserPrincipalName <UPN> [-ConnectionUri <URL>] [-AzureADAuthorizationEndPointUri <URL>] [-PSSessionOption $ProxyOptions]
    
    • <UPN> is your account in user principal name format (for example, navin@contoso.com).
    • The required ConnectionUri and AzureADAuthorizationEndPointUrl values depend on the nature of your Microsoft 365 organization. For more information, see the parameter descriptions in Connect-IPPSSession.
    • 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.

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

    Connect-IPPSSession -UserPrincipalName navin@contoso.com -ConnectionUri https://ps.protection.outlook.com/powershell-liveid/
    

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

    Connect-IPPSSession -UserPrincipalName lukas@fabrikam.com -ConnectionUri https://ps.protection.outlook.de/powershell-liveid/ -AzureADAuthorizationEndPointUri https://login.microsoftonline.de/common
    

For detailed syntax and parameter information, see Connect-IPPSSession.

Note

Be sure to disconnect the remote PowerShell session when you're finished. If you close the Windows 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

Connect to Exchange Online Protection PowerShell using modern authentication

If your account doesn't use multi-factor authentication, use the steps in this section.

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

    Import-Module ExchangeOnlineManagement
    

    Note: If you've already installed the EXO V2 module, the previous command will work as written.

  2. Run the following command:

    Note

    You can skip this step and omit the Credential parameter in the next step to be prompted to enter the username and password after you run the Connect-IPPSSession command. If you omit the Credential parameter and include the UserPrincipalName parameter in the next step, you're only prompted to enter the password after you run the Connect-IPPSSession command.

    $UserCredential = Get-Credential
    

    In the Windows PowerShell Credential Request dialog box that appears, type your work or school account and password, and then click OK.

  3. The last command that you need to run uses the following syntax:

    Connect-IPPSSession [-Credential $UserCredential] -ConnectionUri <URL> [-PSSessionOption $ProxyOptions]
    
    • The required ConnectionUri value depends on the nature of your Microsoft 365 organization. For more information, see the parameter description in Connect-IPPSSession.
    • If you're behind a proxy server, store the output of the New-PSSessionOption cmdlet in a variable (for example, $ProxyOptions = New-PSSessionOption -ProxyAccessType <Value> [-ProxyAuthentication <Value>] [-ProxyCredential <Value>]). Then, use the variable ($ProxyOptions) as the value for the PSSessionOption parameter.

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

    Connect-IPPSSession -Credential $UserCredential -ConnectionUri https://ps.protection.outlook.com/powershell-liveid/
    

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

    Connect-IPPSSession -Credential $UserCredential -ConnectionUri https://ps.protection.outlook.de/powershell-liveid/
    

For detailed syntax and parameter information, see Connect-IPPSSession.

Note

Be sure to disconnect the remote PowerShell session when you're finished. If you close the Windows 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

How do you know this worked?

The Exchange Online Protection Protection cmdlets are imported into your local Windows 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 Protection cmdlet, for example, Get-TransportRule, 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 Protection.

  • 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 Exchange Online Protection PowerShell must be represented as a mail user in EOP (created manually or by directory synchronization). If the account is not visible in the Exchange admin center (EAC) as a mail user at Recipients > Contacts, you'll receive the following error when you try to connect:

    Import-PSSession : Running the Get-Command command in a remote session reported the following error: Processing data for a remote command failed with the following error message: The request for the Windows Remote Shell with ShellId failed because the shell was not found on the server. Possible causes are: the specified ShellId is incorrect or the shell no longer exists on the server. Provide the correct ShellId or create a new shell and retry the operation.

  • You might fail to connect if your client IP address changes during the connection request. This can happen if your organization uses a source network address translation (SNAT) pool that contains multiple IP addresses. The connection error looks like this:

    The request for the Windows Remote Shell with ShellId failed because the shell was not found on the server. Possible causes are: the specified ShellId is incorrect or the shell no longer exists on the server. Provide the correct ShellId or create a new shell and retry the operation.

    To fix the issue, use an SNAT pool that contains a single IP address, or force the use of a specific IP address for connections to the Exchange Online Protection PowerShell endpoint.