Connect-IPPSSession: fixing Security & Compliance PowerShell connection errors

Security & Compliance PowerShell is where Purview admins script DLP policies, labels, retention and eDiscovery searches, and every session starts with Connect-IPPSSession from the ExchangeOnlineManagement module. When the connection fails, the error rarely says what to change. In this post I'll match the errors Microsoft documents to their causes, then show how to set up interactive and certificate-based connections that keep working.

Symptoms#

One of these appears while you install the module, connect, or run your first cmdlet:

Files cannot be loaded because running scripts is disabled on this system. Provide a valid certificate with which to sign the files.

The specified module 'ExchangeOnlineManagement' with PowerShellGetFormatVersion '<version>' isn't supported by the current version of PowerShellGet. Get the latest version of the PowerShellGet module to install this module, 'ExchangeOnlineManagement'.

No match was found for the specified search criteria and module name 'ExchangeOnlineManagement'. Try running Get-PSRepository to see all available registered module repositories.

The term 'Connect-IPPSSession' is not recognized as the name of a cmdlet, function, script file, or operable program.

The term 'Update-ModuleManifest' 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.

The request for the Windows Remote Shell with ShellId <ID> failed because the shell was not found on the server.

Please close the current PowerShell session and open a new session using Connect-IPPSSession with the -EnableSearchOnlySession flag. This requires using ExchangeOnlineManagement v3.9.0 or higher.

Two quieter symptoms: an unattended script opens a sign-in prompt, or you connect fine but a specific cmdlet is missing. The second one is a permissions problem, covered in my guide to Purview roles and role groups.

Why it happens#

Since October 2023, Security & Compliance PowerShell accepts only REST API connections; remote PowerShell (RPS) connections are deprecated, and module version 3.9.2 deprecated the UseRPSSession switch. REST connections don't need Basic authentication in WinRM, but they do depend on a healthy PowerShellGet setup and a current module. Most errors map to one cause:

Platform matters too: Connect-IPPSSession isn't available in PowerShell 7 on macOS or Linux, and connect and disconnect commands are likely to fail if the profile path of the signed-in account contains special PowerShell characters such as $.

How to fix it#

1. Fix the module and its prerequisites#

# Elevated session: allow signed remote scripts
Set-ExecutionPolicy RemoteSigned

# Preview versions of these modules can break connections
Get-InstalledModule PackageManagement -AllVersions; Get-InstalledModule PowerShellGet -AllVersions

# "No match was found": re-register the PowerShell Gallery
Register-PSRepository -Default

# Install, or update with the same scope you installed with
Install-Module -Name ExchangeOnlineManagement -Scope CurrentUser
Update-Module -Name ExchangeOnlineManagement -Scope CurrentUser
Get-InstalledModule ExchangeOnlineManagement | Format-List Name, Version, InstalledLocation

For the PowerShellGetFormatVersion error, update PowerShellGet first, then close and reopen the window before you retry. In PowerShell 7, module 3.10.0 and later needs PowerShell 7.6.0 or later, and versions 3.5.0 to 3.9.2 need 7.4.0 or later; Windows PowerShell 5.1 supports every version. Microsoft Learn lists 3.10.1 as the current release.

2. Connect interactively#

Connect-IPPSSession -UserPrincipalName admin@contoso.onmicrosoft.com

# Microsoft 365 GCC High
Connect-IPPSSession -UserPrincipalName admin@contoso.us `
  -ConnectionUri https://ps.compliance.protection.office365.us/powershell-liveid/ `
  -AzureADAuthorizationEndpointUri https://login.microsoftonline.us/organizations

# Web Account Manager (WAM) sign-in problems on Windows
Connect-IPPSSession -UserPrincipalName admin@contoso.onmicrosoft.com -DisableWAM

Commercial and GCC tenants need no ConnectionUri; the default endpoint is correct. Don't use -Credential for accounts with MFA. If sign-in works but the session is refused, check that the account is allowed to use PowerShell: in Exchange Online PowerShell, Get-User admin@contoso.com | Format-List RemotePowerShellEnabled should return True.

3. Open a search-only session for eDiscovery cmdlets#

Close the current session, then reconnect with the switch:

Disconnect-ExchangeOnline -Confirm:$false
Connect-IPPSSession -UserPrincipalName admin@contoso.onmicrosoft.com -EnableSearchOnlySession
Get-ComplianceSearch | Format-Table Name, Status

App-only authentication isn't supported for the eDiscovery cmdlets. Existing automations that still use it should run module 3.10.1 or later with -EnableSearchOnlySession, but Microsoft treats that as best effort and recommends moving to Microsoft Graph APIs where they exist.

4. Set up app-only connections correctly#

• API permission: add the application permission Microsoft Exchange Online Protection › Exchange.ManageAsApp and grant admin consent. The Office 365 Exchange Online permission is for Connect-ExchangeOnline; an app that connects to both needs both.
• Role: assign the app a supported Microsoft Entra role (Compliance Administrator, Security Administrator, Security Reader or Global Reader), or create a service principal with New-ServicePrincipal and add it to a role group with Add-RoleGroupMember.
• Certificate: CNG certificates aren't supported. Create the key with a CSP provider (for example New-SelfSignedCertificate ... -KeySpec KeyExchange) and upload the .cer file to the app registration.
• Parameters: -Organization must be the primary .onmicrosoft.com domain, and -CertificateThumbprint works only on Windows with the certificate in the user store.

Connect-IPPSSession -AppId "<application (client) ID>" `
  -CertificateThumbprint "<thumbprint>" -Organization "contoso.onmicrosoft.com"

If this command still shows a sign-in prompt, Microsoft's documented workaround is to run $Global:IsWindows = $true before Connect-IPPSSession. My Exchange Online PowerShell V3 guide walks through creating the certificate and app registration.

5. Fix the network path#

• For the ShellId error, use a SNAT pool with a single IP address, or force one address for connections to the Security & Compliance endpoint.
• -PSSessionOption works only together with -UseRPSSession, so proxy settings passed that way have no effect on REST connections. Allow the endpoints through the proxy instead; Microsoft also lists TCP port 80 as a requirement.
• Still stuck? Capture logs for support: Connect-IPPSSession -UserPrincipalName admin@contoso.onmicrosoft.com -EnableErrorReporting -LogDirectoryPath C:\Temp\EXOLogs -LogLevel All.

Verify the fix#

• Get-ConnectionInformation returns the Security & Compliance connection.
• A quick cmdlet such as Get-RetentionCompliancePolicy returns results without errors.
• In a search-only session, Get-ComplianceSearch runs without the EnableSearchOnlySession message.
• App-only scripts run without a prompt, and the app's sign-ins appear under service principal sign-ins in the Microsoft Entra sign-in logs.

Prevent it next time#

• Update the module on a schedule and read the release notes first; 3.10.0 raised the PowerShell 7 minimum to 7.6.
• End every script with Disconnect-ExchangeOnline. Closing the window without disconnecting can use up your available sessions until they expire.
• Remove -UseRPSSession and -PSSessionOption from old scripts, and use -CommandName to import only the cmdlets a job needs.
• Give automation apps the narrowest role that works, not Global Administrator.
• For Exchange Online module errors, see the Exchange Online PowerShell errors quick reference.

References#

• Connect to Security & Compliance PowerShell
• App-only authentication in Exchange Online PowerShell and Security & Compliance PowerShell
• About the Exchange Online PowerShell module