連線到安全性與合規性 PowerShell

  • 發行項

本文包含如何使用 Exchange Online PowerShell 模組連線到安全性 & 合規性 PowerShell 的指示，其中包含或不使用多重要素驗證 (MFA) 。

Exchange Online PowerShell 模組會使用新式驗證來連線到 Microsoft 365 中所有與 Exchange 相關的 PowerShell 環境：Exchange Online PowerShell、安全性 & 合規性 PowerShell，以及獨立 Exchange Online Protection (EOP) PowerShell。 如需 Exchange Online PowerShell 模組的詳細資訊，請參閱關於 Exchange Online PowerShell 模組。

若要連線到安全性 & 合規性 PowerShell 以進行自動化，請參閱自動 腳本的僅限應用程式驗證。

開始之前有哪些須知？

步驟 1：載入 Exchange Online PowerShell 模組

注意事項

如果已安裝模組，您通常可以略過此步驟並執行 Connect-IPPSSession ，而不需要先手動載入模組。

安裝模組之後，請開啟 PowerShell 視窗，然後執行下列命令來載入模組：

Import-Module ExchangeOnlineManagement

步驟 2：連線和驗證

注意事項

如果您用來連線之帳戶的配置檔路徑包含特殊 PowerShell 字元 (例如，) ， $ 則連線命令可能會失敗。 因應措施是使用配置檔路徑中沒有特殊字元的不同帳戶進行連線。

您需要執行的命令會使用下列語法:

Connect-IPPSSession -UserPrincipalName <UPN> [-ConnectionUri <URL>] [-AzureADAuthorizationEndpointUri <URL>] [-DelegatedOrganization <String>] [-PSSessionOption $ProxyOptions]

如需詳細的語法和參數資訊，請參閱 Connect-IPPSSession。

  • <UPN> 是使用者主體名稱格式的帳戶， (例如， navin@contoso.onmicrosoft.com) 。

  • 所需的 ConnectionUri 和 AzureADAuthorizationEndpointUri 值取決於 Microsoft 365 組織的本質。 下列清單描述一般值：

    • Microsoft 365 或 Microsoft 365 GCC：
      • ConnectionUri：無。 必要的值 https://ps.compliance.protection.outlook.com/powershell-liveid/ 也是預設值，因此您不需要在 Microsoft 365 或 Microsoft 365 GCC 環境中使用 ConnectionUri 參數。
      • AzureADAuthorizationEndpointUri：無。 必要的值 https://login.microsoftonline.com/common 也是預設值，因此您不需要在 Microsoft 365 或 Microsoft 365 GCC 環境中使用 AzureADAuthorizationEndpointUri 參數。
    • Microsoft 365 GCC High：
      • ConnectionUri： https://ps.compliance.protection.office365.us/powershell-liveid/
      • AzureADAuthorizationEndpointUri： https://login.microsoftonline.us/common
    • Microsoft 365 DoD：
      • ConnectionUri： https://l5.ps.compliance.protection.office365.us/powershell-liveid/
      • AzureADAuthorizationEndpointUri： https://login.microsoftonline.us/common
    • Office 365 由 21Vianet 運作：
      • ConnectionUri： https://ps.compliance.protection.partner.outlook.cn/powershell-liveid
      • AzureADAuthorizationEndpointUri： https://login.chinacloudapi.cn/common

  • 如果您位於 Proxy 伺服器後方，您可以在連線命令中使用 PSSessionOption 參數。 首先，執行下列命令： $ProxyOptions = New-PSSessionOption -ProxyAccessType <Value>，其中 <Value> 為 IEConfig、 WinHttpConfig或 AutoDetect。 然後，使用 PSSessionOption 參數的值$ProxyOptions。 如需詳細資訊，請參閱 New-PSSessionOption。

  • 根據組織的性質，您可以在下一個步驟略過 UserPrincipalName 參數。 相反地，執行 Connect-IPPSSession 命令之後，請輸入使用者名稱和密碼，或選取儲存的認證。 如果無法執行，則需要使用 UserPrincipalName 參數。

  • 如果您未使用 MFA，您應該可以使用 Credential 參數，而非 UserPrincipalName 參數。 首先，執行命令 $Credential = Get-Credential，輸入您的使用者名稱和密碼，然後使用 Credential 參數的變數名稱 (-Credential $Credential)。 如果無法執行，則需要使用 UserPrincipalName 參數。

使用互動式登入提示連線到安全性 & 合規性 PowerShell

  1. 下列範例適用於具有或不含 MFA 的帳戶 Windows PowerShell 5.1 和 PowerShell 7：

    • 此範例會連線至 Microsoft 365 或 Microsoft 365 GCC 組織中的安全性與合規性 PowerShell：

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

    • 此範例會連線到 Microsoft GCC High 組織中安全性與合規性 PowerShell：

      Connect-IPPSSession -UserPrincipalName chris@govt.us -ConnectionUri https://ps.compliance.protection.office365.us/powershell-liveid/ -AzureADAuthorizationEndpointUri https://login.microsoftonline.us/common

    • 此範例會連線到 Microsoft 365 DoD 組織中安全性與合規性 PowerShell：

      Connect-IPPSSession -UserPrincipalName michelle@govt.mil -ConnectionUri https://l5.ps.compliance.protection.office365.us/powershell-liveid/ -AzureADAuthorizationEndpointUri https://login.microsoftonline.us/common

    • 此範例會連線到由 21Vianet 組織所運作之 Office 365 中的安全性與合規性 PowerShell：

      Connect-IPPSSession -UserPrincipalName li@fabrikam.cn -ConnectionUri https://ps.compliance.protection.partner.outlook.cn/powershell-liveid -AzureADAuthorizationEndpointUri https://login.chinacloudapi.cn/common

  2. 在開啟的登入視窗中，輸入您的密碼，然後按一下 [登入]。

    在 [登入您的帳戶] 視窗中輸入您的密碼。

    注意事項

    在 PowerShell 7 中，預設會使用瀏覽器型單一登錄 (SSO) ，因此登入提示會在您的預設網頁瀏覽器中開啟，而不是在獨立對話框中開啟。

  3. 僅限 MFA：系統會產生驗證碼並根據針對您的帳戶設定的回應選項 (例如，您的裝置上的簡訊或 Microsoft Authenticator 應用程式) 傳送。

    在開啟的驗證視窗中，輸入驗證碼，然後按一下 [驗證]。

    在 [登入您的帳戶] 視窗中輸入您的驗證碼。

聯機到安全性 & 合規性 PowerShell，而不需要登入提示 (自動腳本)

如需完整指示，請參閱 Exchange Online PowerShell 和安全性 & 合規性 PowerShell 中自動腳本的僅限應用程式驗證。

線上到客戶組織中的安全性 & 合規性 PowerShell

本節中的程式需要 3.0.0 版或更新版本的模組。

在安全性 & 合規性 PowerShell 中，您必須搭配 DelegatedOrganization 參數使用 AzureADAuthorizationEndpointUri。

如需合作夥伴和客戶組織的詳細資訊，請參閱下列主題：

此範例會在下列案例中連線到客戶組織：

  • 使用 CSP 帳戶連線到客戶組織。

  • 使用 GDAP 連線到客戶組織。

  • 以來賓使用者身分連線到客戶組織。

    Connect-IPPSSession -UserPrincipalName navin@contoso.onmicrosoft.com -DelegatedOrganization adatum.onmicrosoft.com -AzureADAuthorizationEndpointUri https://login.microsoftonline.com/adatum.onmicrosoft.com

步驟 3：當您完成時中斷連線

完成時，請務必中斷會話的連線。 如果您關閉 PowerShell 視窗而不中斷工作階段的連線，您可以用掉所有可供您使用的工作階段，而且您必須等候工作階段到期。 若要中斷會話的連線，請執行下列命令：

Disconnect-ExchangeOnline

若要在沒有確認提示的情況下以無訊息方式中斷連線，請執行下列命令：

Disconnect-ExchangeOnline -Confirm:$false

注意事項

如果您用來連線之帳戶的配置檔路徑包含特殊 PowerShell 字元，例如 (，) ，則 $ 中斷連線命令可能會失敗。 因應措施是使用配置檔路徑中沒有特殊字元的不同帳戶進行連線。

如何知道您已成功連線？

安全性與合規性 PowerShell Cmdlet 會匯入到本機 Windows PowerShell 工作階段中，並透過進度列進行追蹤。 如果您未收到任何錯誤，表示您已成功連線。 快速測試方式就是執行安全性與合規性 PowerShell Cmdlet，例如 Get-RetentionCompliancePolicy，並查看結果。

如果出現錯誤，請檢查下列需求：

  • 密碼錯誤是常見的問題。 再次執行這三個步驟，並特別留意您使用的使用者名稱和密碼。

  • 您用來連線的帳戶必須啟用PowerShell。 如需詳細資訊，請參閱啟用或停用 Exchange Online 的封存權。

  • 必須在本機電腦與 Microsoft 365 之間開啟 TCP 連接埠 80 流量。 該連接埠可能已開啟，但必須考量您的組織是否有限制性網際網路存取原則。

  • 以 REST 為基礎的安全性 & 合規性 PowerShell 連線需要 PowerShellGet 模組，而依相依性，也需要 PackageManagement 模組，因此如果您嘗試連線但未安裝它們，就會收到錯誤。 例如，您可能會看到下列錯誤：

    'Update-ModuleManifest' 一詞無法辨識為 Cmdlet、函式、腳本檔案或可操作程序的名稱。 請檢查名稱的拼寫，或者如果包含路徑，請確認路徑是否正確，然後再試一次。

    如需 PowerShellGet 和 PackageManagement 模組需求的詳細資訊，請參閱 適用於 Windows 中 REST 連線的 PowerShellGet。

  • 如果您的用戶端 IP 位址在連線要求其間變更，則您可能會無法連線。 如果您的組織使用的來源網路位址轉譯 (SNAT) 集區包含多個 IP 位址，則可能會發生次情況。 連線錯誤看起來會像這樣：

    要求具有ShellId <標識> 碼的Windows遠端殼層失敗，因為在伺服器上找不到殼層。 可能的原因如下：指定的 ShellId 不正確，或者伺服器上已不存在 Shell。 提供正確的 ShellId 或建立新的 Shell，然後重試操作。

    若要修正此問題，請使用 SNAT 集區 (其中包含單一 IP 位址)，或讓安全性與合規性 PowerShell 端點的連線強制使用特定的 IP 位址。