Knowledge Base

How to connect to an Exchange server via PowerShell

Problem:

You want to set up a remote session to an Exchange server via PowerShell.

Solution:

This article will help you:

Connecting to on-premises Exchange server

  1. Check the requirements for on-premises Exchange Server.
  2. Run ps Windows PowerShell.
  3. Check your Execution policy settings:

    Get-ExecutionPolicy

    If the execution policy is set to Restricted, change it to RemoteSigned or Unrestricted (this might need to be executed from PowerShell in the Run as administrator mode):

    Set-ExecutionPolicy RemoteSigned
  4. Provide the target server administrator credentials:

    $LiveCred = Get-Credential
  5. Configure the connection to your Exchange Server 2010, 2013, 2016, and 2019:

    $Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://<target-server-address>/powershell/ -Credential $LiveCred

    Be advised the method shown above is not universal. Depending on your target environment configuration, you may be required to specify the authentication method as an argument (-Authentication Kerberos), connect via http instead of https, etc., as shown in the example below:

    $Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri http://<target-server-address>/powershell/ -Credential $LiveCred -Authentication Kerberos

    What is more, some options cannot be passed as New-PSSession arguments and must be specified as New-PSSessionOption, and only then passed together as a variable. See the Troubleshooting section below to see an example of using advanced option for a session.

    Info

    If you cannot use a hostname or FQDN as a target for PowerShell connection and must use an IP address instead, see this article first.

  6. Start the connection:

    Import-PSSession $Session
  7. To disconnect, type:

    Remove-PSSession $Session

Also, if you are logged in directly to an on-premises Exchange server and for some reason cannot run ems Exchange Management Shell, you can start ps Windows PowerShell and load the Exchange snap-in from there by executing the cmdlet below:

Add-PSSnapin Microsoft.Exchange.Management.PowerShell.SnapIn

Connecting to Exchange Online

  1. Check the requirements for Exchange Online (Microsoft 365),
  2. Run ps Windows PowerShell.
  3. Check your Execution policy settings:
Get-ExecutionPolicy
  • By default, the execution policy is set to Restricted. To successfully connect to Exchange Online with PowerShell, it is recommended to set the policy to RemoteSigned:
Set-ExecutionPolicy RemoteSigned
  1. Provide your Microsoft 365 administrator credentials:
$LiveCred = Get-Credential
  1. Connect to Exchange Online using the Connect-ExchangeOnline cmdlet:
  • If you're connecting to Exchange Online (Microsoft 365):
Connect-ExchangeOnline -Credential $LiveCred

Info

If you’re connecting to Exchange Online with an account that has MFA enabled, use the plain Connect-ExchangeOnline cmdlet and enter your credentials in a pop-up window, as the -Credential parameter isn’t supported with MFA enabled.

  • If your organization runs Microsoft 365 Germany, execute this command instead:
Connect-ExchangeOnline -Credential $LiveCred -ExchangeEnvironmentName “O365GermanyCloud”
  1. To disconnect, type:
Disconnect-ExchangeOnline

Troubleshooting

Incorrect credentials

When connecting to an on-premises Exchange server, you might see the following error:

Connecting to remote server <ServerName> failed with the following error message : The user name or password is incorrect. 

This error message is self-explanatory – you need to make sure that the entered credentials are correct. A similar problem occurs when connecting to Exchange Online. This time the error message is not that informative:

Connecting to remote server ps.outlook.com failed with the following error message : [ClientAccessServer=XXXXX,BackEndServer=YYYYY,RequestId=ZZZZZ, TimeStamp=MM/DD/YYYY H:MM:SS PM] Access Denied

In such a case you should also double-check if there aren't any spelling mistakes in the provided credentials.

Problems with certificates

If you encounter errors specified below (or similar), you will not be able to establish a remote connection using the method described earlier in this article.

Connecting to remote server <ServerName> failed with the following error message : The server certificate on the destination computer <ServerName> has the following errors:
The SSL certificate is signed by and unknown certificate authority.
The SSL certificate contains a common name (CN) that does not match the hostname.

However, you can use the New-PSSessionOption cmdlet to ignore the validation of certificate-related operations:

$SessionOpt = New-PSSessionOption -SkipCACheck:$true -SkipCNCheck:$true -SkipRevocationCheck:$true
$Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://<target-server-address>/powershell/ -Credential $LiveCred -SessionOption $SessionOpt

The above-mentioned errors will not appear, and you should be able to create a new session.

Connect-ExchangeOnline is not recognized

Modern method of connecting to Exchange Online with PowerShell requires Exchange Online PowerShell V2 module installed. If you do not have it installed, you will receive the following error:

Connect-ExchangeOnline : The term 'Connect-ExchangeOnline' 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. 

To fix it, you need to install and import the PowerShellGet and Exchange Online PowerShell V2 modules. You can do so with the following cmdlets:

Install-Module -Name ExchangeOnlineManagement;
Import-Module -Name ExchangeOnlineManagement

If you don’t have the prerequisite package provider installed, PowerShell should prompt you to install one, before installing the new Exchange Online Management module.

See also: