/flags/purview/connect-ippssession-connectionuri
Connect-IPPSSession -ConnectionUri: connect to GCC High, DoD or 21Vianet
- tool
- Microsoft Purview (Security & Compliance PowerShell)
- command
- Connect-IPPSSession
- flag
- -ConnectionUri (with -AzureADAuthorizationEndpointUri)
- default
- https://ps.compliance.protection.outlook.com/powershell-liveid/ (Microsoft 365 and GCC)
Connect-IPPSSession -ConnectionUri URL tells the ExchangeOnlineManagement module which Security & Compliance PowerShell endpoint (the PowerShell side of Microsoft Purview) to connect to. In commercial Microsoft 365 and GCC tenants you never need it, because the default is right. In the sovereign clouds (GCC High, DoD, and Office 365 operated by 21Vianet) you must pass the cloud's endpoint, together with -AzureADAuthorizationEndpointUri for the matching Microsoft Entra sign-in endpoint; otherwise the connection goes to the commercial service and fails.
# Microsoft 365 GCC High
Connect-IPPSSession -UserPrincipalName chris@govt.us `
-ConnectionUri https://ps.compliance.protection.office365.us/powershell-liveid/ `
-AzureADAuthorizationEndpointUri https://login.microsoftonline.us/organizationsValues by cloud
From Microsoft's Connect-IPPSSession reference and the "Connect to Security & Compliance PowerShell" article:
| Environment | -ConnectionUri | -AzureADAuthorizationEndpointUri |
|---|---|---|
| Microsoft 365 / GCC | do not use (default https://ps.compliance.protection.outlook.com/powershell-liveid/) | do not use (default https://login.microsoftonline.com/organizations) |
| GCC High | https://ps.compliance.protection.office365.us/powershell-liveid/ | https://login.microsoftonline.us/organizations |
| DoD | https://l5.ps.compliance.protection.office365.us/powershell-liveid/ | https://login.microsoftonline.us/organizations |
| Office 365 operated by 21Vianet | https://ps.compliance.protection.partner.outlook.cn/powershell-liveid | https://login.chinacloudapi.cn/organizations |
The reference adds that the /organizations endpoint accepts only work or school accounts, and that with -UserPrincipalName you don't need -AzureADAuthorizationEndpointUri for MFA or federated users in environments that normally require it.
The parameters in the module
Both are plain strings, and -ConnectionUri is also the first positional parameter.
Pitfalls
- Only one of the two. Passing
-ConnectionUriwithout the matching sign-in endpoint (or the reverse) sends you to the wrong cloud for one half of the connection. - Trailing slash. Copy the values exactly as documented; the 21Vianet URI has no trailing slash, the others do.
- Search cmdlets. Some eDiscovery cmdlets need
-EnableSearchOnlySessionin addition (module 3.9.0 and later); see EnableSearchOnlySession required. - Cmdlets not found. If Purview cmdlets such as
Get-RetentionCompliancePolicyare "not recognized", the session did not connect; see Get-RetentionCompliancePolicy is not recognized. - Scripts. Add
-ShowBanner:$falsefor quiet logs (-ShowBanner:$false); the general connection steps are on Connect-IPPSSession.
FAQ
Do I need -ConnectionUri in a normal Microsoft 365 or GCC tenant?
No. Microsoft says not to use it there: the required value is also the default. Only GCC High, DoD and Office 365 operated by 21Vianet need it.
Is there an -ExchangeEnvironmentName for Security & Compliance PowerShell?
Connect-ExchangeOnline uses -ExchangeEnvironmentName (O365USGovGCCHigh, O365USGovDoD, O365China). Connect-IPPSSession has no such parameter in module 3.10.1, as the check on this page shows; use the two URI parameters with the values listed here.
Why does my GCC High connection keep prompting for the commercial sign-in page?
-AzureADAuthorizationEndpointUri is missing. Without it the sign-in goes to login.microsoftonline.com; GCC High and DoD accounts sign in at https://login.microsoftonline.us/organizations.