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:
- connect to your on-premises Exchange servers via remote PowerShell session
- create a remote PowerShell connection to your Exchange Online organization
- troubleshoot PowerShell errors that you may encounter during the process.
Connecting to on-premises Exchange server
- Check the requirements for on-premises Exchange Server.
- Run Windows PowerShell.
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
Provide the target server administrator credentials:
$LiveCred = Get-Credential
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.
Start the connection:
Import-PSSession $Session
Remove-PSSession $Session
Also, if you are logged in directly to an on-premises Exchange server and for some reason cannot run Exchange Management Shell, you can start 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
- Check the requirements for Exchange Online (Microsoft 365),
- Run Windows PowerShell.
- 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
- Connect to Exchange Online (Microsoft 365) using the Connect-ExchangeOnline cmdlet. You will be asked to sign in with your Microsoft 365 administrator credentials:
Connect-ExchangeOnline
- 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 V3 module installed (Learn more about deprecation of the V2 module). 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 V3 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.
If at this point (i.e. while attempting to download the NuGet provider) you receive the “Unable to download from URI” error, you might need to edit your registry to continue. The remedy is to enable strong cryptography for .NET Framework. This Microsoft’s site provides instructions on how to fix this issue.
See also:
- Connect to Exchange Online using remote PowerShell on the Microsoft website
Related products: | CodeTwo Exchange Migration, CodeTwo Office 365 Migration |
Categories: | How-To |
Last modified: | October 20, 2023 |
Created: | December 31, 2013 |
ID: | 350 |