The latest iteration of the Exchange Online Management module is V3. This module improved upon the already enhanced features in the previous V2 module.
Among other things, one of the most crucial enhancements of the V3 module is that it is no longer dependent on WinRM for authentication. Especially since basic authentication is now deprecated, this update is a much-welcome feature.
It also means that EXO V3 should now be compatible with running on PowerShell 7 on non-Windows machines like Linux and macOS.
In this post, we’ll learn how to install the Exchange Online PowerShell v3 module and use it to connect to Exchange Online.
Installing the Exchange Online PowerShell v3 Module
But before we go any further, let’s install the module. The module is available in the PowerShell Gallery, which you can install using the Install-Module cmdlet. Follow these steps.
- Open an elevated PowerShell window.
- Update the Nuget package provider (if using Windows PowerShell 5.1):
Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force
- Install the latest PowerShellGet module (if using Windows PowerShell 5.1):
Install-Module -Name PowerShellGet -Force
- Now that the NuGet and PowerShellGet are in their latest versions, run the command below to install the ExchangeOnlineManagement PowerShell module:
# OPTION 1: Install for all users Install-Module -Name ExchangeOnlineManagement -Scope AllUsers # OPTION 2: Install for your profile only Install-Module -Name ExchangeOnlineManagement -Scope CurrentUser # List the installed EXOV3 module. Get-Module ExchangeOnlineManagement -ListAvailable
Note. The -Scope parameter does not affect non-Windows platforms.
As you can see, the latest Exchange Online PowerShell V3 module is 3.1.0.
Connect to Exchange Online PowerShell using Administrator Credential
The most common way to connect Exchange Online PowerShell is with your administrator credential.
Without MFA
If your admin account is not MFA-enabled, you can store the username and password into an object and pass it as the Exchange Online PowerShell credential without leaving the PowerShell window.
Note. Learn how to install Azure PowerShell module.
First, get the admin credential and store it in the $credential variable.
$credential = Get-Credential
Next, connect to Exchange Online PowerShell using this command:
Connect-ExchangeOnline -Credential $credential
To confirm the connection status, run the following command:
Get-ConnectionInformation
If the state says connected, you’ve successfully connected to the Exchange Online PowerShell session.
Note. Learn how to add Calendar permissions in Office 365 via PowerShell.
With MFA
On the other hand, if your user account is MFA-enabled, the connection experience is different.
Connect-ExchangeOnline -UserPrincipalName <userprincipalname>
Enter your account password and sign in.
And verify your MFA method.
You’ve successfully connected to Exchange Online PowerShell if there’s no error.
Connect to Exchange Online PowerShell with a Certificate
In unattended scenarios like scripting and automation, the interactive method of entering credentials is not applicable. Especially if the user account is MFA-enabled.
The alternative is an app-only authentication using an Azure AD application and service principal. The Exchange Online PowerShell v3 module lets you authenticate using a digital certificate instead of a password or secret. The certificate can be self-signed, too, so there’s no added cost.
Note. Check our post on how to transfer FSMO roles using PowerShell.
Onboard the Azure AD Application and Service Principal
Registering the Azure AD application and enabling its service principal is a one-time onboarding activity. Once you’ve onboarded the application, you can use the client ID and certificate to authenticate to Exchange Online PowerShell.
To create the Azure AD app and principal, follow these steps:
- Log in to the Microsoft Entra admin center.
- Under the Azure Active Directory, click Applications → App registrations → New registration.
- On the Register application page:
- Enter the name of the application. This can be any name that you think is appropriate. This example uses EXO V3 PowerShell.
- Select the Accounts in this organizational directory only ( only – Single tenant) option.
- In the Redirect URI, select Web and enter http://localhost.
- Click Register.
- Once the app is registered, copy the Application (client) ID. You’ll need it later.
- On the fly-out, click APIs my organization uses and click Office 365 Exchange Online.
- Select Application permissions, and check the Exchange.ManagerAsApp permission and click Add permissions.
- Next, click Grant admin consent for and click Yes.
The API permission status for Exchange.ManageAsApp changes to Granted for.
- Now let’s generate the self-signed certificate. On your PowerShell terminal, run these commands:
# Create certificate $exov3cert = New-SelfSignedCertificate -DnsName 'exov3powershell' -CertStoreLocation "cert:\CurrentUser\My" -NotAfter (Get-Date).AddYears(1) -KeySpec KeyExchange # Export certificate to .pfx file $exov3certpwd = ConvertTo-SecureString 'mycertpassword' -AsPlainText -Force $exov3cert | Export-PfxCertificate -FilePath exov3cert.pfx -Password $exov3certpwd # Export certificate to .cer file $exov3cert | Export-Certificate -FilePath exov3cert.cer
So what did the above commands do?
The first command created a self-signed certificate with the subject exov3powershell in your personal certificate store, valid for 1 year.
The second command exported the certificate to a password-protected PFX file called exov3cert.pfx.
The third command exported the certificate public key to exov3cert.cer. This is the certificate you’ll attach to the Azure AD application later.
- Now that you have the certificate, go back to the Microsoft Entra admin center and click Certificates and secrets → Certificates → Upload certificate.
- Upload the certificate (exov3cert.cer) and click Add.
The certificate is now uploaded.
- The last onboarding task is to enable the service principal of your Azure AD application. Go back to the Azure AD portal and click Roles & admins.
- Click Add assignments.
- Search and select the application name (EXO V3 PowerShell) and click Add.
The app is now assigned the Exchange Administrator role.
Connect Using a Certificate File (*.PFX)
With the Azure AD app registered and the service principal enabled, you can connect to Exchange Online PowerShell using the client ID and certificate. This method works with PowerShell on Windows and non-Windows computers.
The parameters you need with the Connect-ExchangeOnline cmdlet are:
- -AppId — the application ID you registered in Azure AD
- -Organization — your tenant’s primary domain or directory ID.
- -CertificateFilePath — the full path to your PFX certificate.
- -CertificatePassword — the PFX certificate password you specified when exporting the certificate.
Run the following command to connect to Exchange Online PowerShell with a certificate file.
# Store the certificate password in a variable. $certificatePassword = Read-Host -AsSecureString -Prompt 'PFX Password' # Connect to Exchange Online Connect-ExchangeOnline ` -AppId 8d7e4dd3-df34-4416-a51d-7822d1ea1c65 ` -Organization org870b.ga ` -CertificateFilePath .\exov3cert.pfx ` -CertificatePassword $certificatePassword # Check the EXO connection information Get-ConnectionInformation
You may have noticed that you still needed to enter the certificate password somehow, which involves manual interaction. If you plan to use this method in automation, you can incorporate the PowerShell Secret Management module and vault to eliminate manually entering passwords.
Connect Using a Certificate Object (X.509)
PowerShell has at least two ways to create a certificate object in the session from existing certificates. One works with Windows only, and the other works with other platforms. Let’s explore both.
You can get the certificate object from the certificate store on a Windows computer. Remember that when you onboarded the Azure AD application, you generated a certificate (exov3powershell in this example), which exists in the Cert:\CurrentUser\My store.
Get-ChildItem Cert:\CurrentUser\My
Copy the certificate thumbprint.
Now, connect to Exchange Online PowerShell by running this command. Make sure to change the values accordingly.
# Get the certificate from the certificate store. $certificate = Get-Item Cert:\CurrentUser\My\30061C93554D846419428A571F41766A47EFCD32 # Connect to Exchange Online Connect-ExchangeOnline ` -AppId 8d7e4dd3-df34-4416-a51d-7822d1ea1c65 ` -Organization org870b.ga ` -Certificate $certificate ` -ShowBanner:$false # Check the EXO connection information Get-ConnectionInformation
Another method that works with both Windows and non-Windows platforms is by using the Get-PfxCertificate cmdlet.
Note. The -Password parameter is not available on Windows PowerShell 5.1.
# Store the certificate password in a variable. $certificatePassword = Read-Host -AsSecureString -Prompt 'PFX Password' # Import the PFX certificate into the current session $certificate = Get-PfxCertificate -filePath ./exov3cert.pfx -Password $certificatePassword # Connect to Exchange Online Connect-ExchangeOnline ` -AppId 8d7e4dd3-df34-4416-a51d-7822d1ea1c65 ` -Organization org870b.ga ` -Certificate $certificate ` -ShowBanner:$false # Check the EXO connection information Get-ConnectionInformation
The example below is demonstrated using PowerShell 7.3.2 on Ubuntu 22.04.
Tip. You can remove the PFX password using the openssl command.
Connect using a Certificate Thumbprint
Finally, you can use the -CertificateThumbprint <thumbprint> parameter without importing the certificate into the current session. The parameter import the certificate from the certificate store that matches the given thumbprint.
But, this method does not work with non-Windows systems for one apparent reason—the Windows Certificate Store only exists in Windows.
# Connect to Exchange Online Connect-ExchangeOnline ` -AppId 8d7e4dd3-df34-4416-a51d-7822d1ea1c65 ` -Organization org870b.ga ` -CertificateThumbprint '30061C93554D846419428A571F41766A47EFCD32' ` -ShowBanner:$false # Check the EXO connection information Get-ConnectionInformation
That’s it! You can now manage Exchange Online using the cmdlets provided by the Exchange Online PowerShell V3 module.
Disconnect from the Exchange Online PowerShell Session
Once you’re done with using the Exchange Online PowerShell session, you must ensure to disconnect from it. Doing so frees up the connection and releases the counter from the throttling threshold.
Disconnect-ExchangeOnline
Or you can disconnect without the confirmation prompt.
disconnect-ExchangeOnline -Confirm:$false
Conclusion
This article aimed to demonstrate how to connect to Exchange Online PowerShell using the V3 module. We’ve installed the required module, registered the Azure AD app, and enabled the service principal for app-only authentication.
The Exchange Online PowerShell v3 module works on Windows and non-Windows platforms. Your preferred operating system should not restrict you from adopting the module in your Exchange Online management and automation tasks.
