Exchange Online PowerShell 和安全性 & 合規性 PowerShell 中自動腳本的僅限應用程式驗證
Microsoft 365 中的稽核和報告案例通常涉及 Exchange Online PowerShell 和安全性與合規性 PowerShell 中的自動指令碼。 在過去,自動登入需要您將使用者名稱和密碼儲存在本機檔案中,或是儲存在執行時間存取的密碼保存庫中。 但如我們所知,在本機儲存用戶認證並不是很好的安全性作法。
如本文所述,憑證型驗證 (CBA) 或僅限應用程式驗證,可使用 Microsoft Entra 應用程式和自我簽署憑證來支援自動腳本和自動化案例。
注意事項
您知道可以在 Azure 中使用受控識別連線到 Exchange Online PowerShell 嗎? 請參閱 使用 Azure 受控識別連線到 Exchange Online PowerShell。
本文所述的功能和程式需要下列版本的 Exchange Online PowerShell 模組:
- Exchange Online PowerShell (Connect-ExchangeOnline):版本 2.0.3 或更新版本。
- 安全性 & 合規性 PowerShell (Connect-IPPSSession) :3.0.0 版或更新版本。
如需如何安裝或更新模組的指示,請參閱 安裝和維護 Exchange Online PowerShell 模組。 如需如何在 Azure 自動化中使用模組的指示,請參閱 管理 Azure 自動化中的模組。
Exchange Online PowerShell V3 模組中的 REST API 連線需要 PowerShellGet 和 PackageManagement 模組。 如需詳細資訊,請參閱 Windows 中 REST 型連線的 PowerShellGet。
如果本文中的程式不適用於您,請執行下列命令來確認您沒有安裝 PackageManagement 或 PowerShellGet 模組的 Beta 版本:
Get-InstalledModule PackageManagement -AllVersions; Get-InstalledModule PowerShellGet -AllVersions
。在 Exchange Online PowerShell 中,無法將此文章中的程序與下列 Microsoft 365 群組 Cmdlet 一起使用:
您可以使用 Microsoft Graph 來取代這些 Cmdlet 中的大部分功能。 如需詳細資訊,請 參閱在 Microsoft Graph 中使用群組。
在安全性 & 合規性 PowerShell 中,您無法使用本文中的程式搭配下列Microsoft 365 群組 Cmdlet:
Exchange Online 支援委派的案例。 使用委派聯機的建議方法是使用 GDAP 和應用程式同意。 如需詳細資訊,請 參閱搭配 GDAP 和應用程式同意使用 Exchange Online PowerShell v3 模組。 當未與客戶建立 CSP 關聯性時,您也可以使用多租使用者應用程式。 使用多租使用者應用程式的必要步驟會在本文的一般指示中說明。
如果您在使用 Windows PowerShell SDK 進行連線時收到下列錯誤,請在 Connect-ExchangeOnline Cmdlet 上使用 SkipLoadingFormatData 參數:
The term 'Update-ModuleManifest' is not recognized as a name of a cmdlet, function, script file, or executable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.
它的運作方式為何?
Exchange Online PowerShell 模組會使用 Active Directory 驗證連結庫,使用應用程式識別碼、租使用者標識碼 (組織) 和憑證指紋來擷取僅限應用程式的令牌。 在 Microsoft Entra ID 內布建的應用程式物件具有指派的目錄角色,該角色會在存取令牌中傳回。 使用權杖中可用的目錄角色資訊,設定工作階段的角色型存取控制 (RBAC)。
線上範例
下列範例示範如何使用 Exchange Online PowerShell 模組搭配僅限應用程式驗證:
重要事項
在下列連線命令中,使用組織的主要 .onmicrosoft.com
網域作為 Organization 參數的值。
下列連線命令有許多相同的選項,如 聯機到 Exchange Online PowerShell 和 連線到安全性 & 合規性 PowerShell 中所述。 例如:
Microsoft 365 GCC High 或 Microsoft 365 DoD 環境需要下列其他參數和值:
-
GCC High 中的 Connect-ExchangeOnline:
-ExchangeEnvironmentName O365USGovGCCHigh
。 -
GCC High 中的 Connect-IPPSSession:
-ConnectionUri https://ps.compliance.protection.office365.us/powershell-liveid/ -AzureADAuthorizationEndpointUri https://login.microsoftonline.us/common
。 -
DoD 中的 Connect-ExchangeOnline:
-ExchangeEnvironmentName O365USGovDoD
。 -
DoD 中的 Connect-IPPSSession:
-ConnectionUri https://l5.ps.compliance.protection.office365.us/powershell-liveid/ -AzureADAuthorizationEndpointUri https://login.microsoftonline.us/common
。
-
GCC High 中的 Connect-ExchangeOnline:
如果 Connect-IPPSSession 命令顯示登入提示字元,請在 Connect-IPPSSession 命令之前執行命令:
$Global:IsWindows = $true
使用憑證指紋進行連線:
注意事項
只有在 Windows Microsoft才支援 CertificateThumbprint 參數。
憑證必須安裝在您執行命令的計算機上。 該憑證應安裝在使用者憑證存放區中。
Exchange Online PowerShell:
Connect-ExchangeOnline -CertificateThumbPrint "012THISISADEMOTHUMBPRINT" -AppID "36ee4c6c-0812-40a2-b820-b22ebd02bce3" -Organization "contosoelectronics.onmicrosoft.com"
安全性與合規性 PowerShell:
Connect-IPPSSession -CertificateThumbPrint "012THISISADEMOTHUMBPRINT" -AppID "36ee4c6c-0812-40a2-b820-b22ebd02bce3" -Organization "contosoelectronics.onmicrosoft.com"
使用憑證物件進行連線:
憑證不需要安裝在您執行命令的計算機上。 您可以從遠端儲存憑證物件。 執行腳本時會擷取憑證。
Exchange Online PowerShell:
Connect-ExchangeOnline -Certificate <%X509Certificate2 Object%> -AppID "36ee4c6c-0812-40a2-b820-b22ebd02bce3" -Organization "contosoelectronics.onmicrosoft.com"
安全性與合規性 PowerShell:
Connect-IPPSSession -Certificate <%X509Certificate2 Object%> -AppID "36ee4c6c-0812-40a2-b820-b22ebd02bce3" -Organization "contosoelectronics.onmicrosoft.com"
使用本機憑證進行連線:
注意事項
使用 ConvertTo-SecureString 命令在本機儲存憑證的密碼,會使自動化案例的安全連線方法目的失敗。 使用 Get-Credential 命令來提示您安全地輸入憑證密碼,並不適用於自動化案例。 換句話說,實際上沒有自動化 且 安全的方式可以使用本機憑證進行連線。
Exchange Online PowerShell:
Connect-ExchangeOnline -CertificateFilePath "C:\Users\navin\Desktop\automation-cert.pfx" -CertificatePassword (Get-Credential).password -AppID "36ee4c6c-0812-40a2-b820-b22ebd02bce3" -Organization "contosoelectronics.onmicrosoft.com"
安全性與合規性 PowerShell:
Connect-IPPSSession -CertificateFilePath "C:\Users\navin\Desktop\automation-cert.pfx" -CertificatePassword (Get-Credential).password -AppID "36ee4c6c-0812-40a2-b820-b22ebd02bce3" -Organization "contosoelectronics.onmicrosoft.com"
設定僅限應用程式的驗證
使用應用程式標的進行驗證需要初始登入。 應用程式和服務主體可互換使用,但是應用程式就像是課程標的,而服務主體就像是課程的實例。 如需詳細資訊,請參閱 Microsoft Entra ID 中的應用程式和服務主體物件。
如需在 Microsoft Entra ID 中建立應用程式的詳細視覺流程,請參閱 https://aka.ms/azuread-app。
-
根據默 認,應用程式 物件具有 Graph>User.Read Microsoft委派 API 許可權。 若要讓應用程式物件存取 Exchange 中的資源,它 需要應用程式 API 許可權 Office 365 Exchange Online>Exchange.ManageAsApp。
-
針對 Microsoft Entra ID 中的僅限應用程式驗證,您通常會使用憑證來要求存取權。 擁有憑證及其私鑰的任何人都可以使用具有授與應用程式許可權的應用程式。
建立並設定自我簽署 X.509 憑證,此憑證可用來針對 Microsoft Entra ID 驗證您的應用程式,同時要求僅限應用程式的存取令牌。
此程式類似於產生用戶帳戶的密碼。 也可以自行簽署憑證。 如需在 PowerShell 中產生憑證的指示,請參閱本文稍後的 本節 。
注意事項
密碼編譯:新一代 (CNG) 憑證不支援使用 Exchange 進行僅限應用程式的驗證。 CNG 憑證預設會在新式 Windows 版本中建立。 您必須使用 CSP 金鑰提供者的憑證。 本節 涵蓋建立 CSP 憑證的兩個支援方法。
-
應用程式必須指派適當的 RBAC 角色。 因為應用程式是以 Microsoft Entra ID 佈建,所以您可以使用任何支援的內建角色。
步驟 1:在 Microsoft Entra ID 中註冊應用程式
注意事項
如果您遇到問題,請檢查 必要權限,以確保您的帳戶可以建立身分識別。
在開啟 Microsoft Entra 系統管理中心。https://portal.azure.com/
在頁面頂端的 [搜尋] 方塊中,開始輸入應用程式註冊,然後從 [服務] 區段的結果中選取 [應用程式註冊]。
或者,若要直接移至 [應用程式註冊] 頁面,請使用 https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade。
在 [應用程式登錄] 頁面上選取 [新增登錄]。
在出現的 [註冊應用程式] 頁面中,設定下列設定:
名稱:輸入描述性的文字。 例如,ExO PowerShell CBA。
支持的帳戶類型:確認 此組織目錄中的帳戶僅 (僅限 <YourOrganizationName> - 已選取單一租使用者) 。
注意事項
若要讓 應用程式成為 Exchange Online 委派案例的多租使用者,請選取 任何組織目錄中的 [帳戶] 值 ([任何Microsoft的 Entra 目錄 - 多租使用者) 。
重新導向 URI (選擇性) :此設定為選擇性設定。 如果您需要使用它,請設定下列設定:
- 平台:選取 [Web]。
- URI:輸入傳送存取令牌的 URI。
注意事項
您無法建立 原生應用程式的認證,因為您無法將原生應用程式用於自動化應用程式。
當您在 [ 應用程式註冊 ] 頁面上完成時,請選取 [ 註冊]。
系統會帶您前往您剛註冊之應用程式的 [ 概觀 ] 頁面。 讓此頁面保持開啟。 您會在下一個步驟用到它。
步驟2:指派 API 權限給應用程式
選擇本節中的下列 其中一 種方法,將 API 許可權指派給應用程式:
- 從入口網站選取並指派 API 許可權。
- 修改應用程式指令清單以指派 API 許可權。 (Microsoft 365 GCC High 和 DoD 組織應該使用此方法)
從入口網站選取並指派 API 許可權
在 [應用程式 概觀] 頁面上,從 [管理] 區段中選取 [API權 限]。
在 [應用程式 API 許可權] 頁面上,選取 [ 新增許可權]。
在開啟的 [要求 API 許可權] 飛出視窗中,選取 [我的組織使用的 API] 索引卷標,在 [搜尋] 方塊中開始輸入 Office 365 Exchange Online,然後從結果中選取它。
在出現 的 [您的應用程式需要何種類型的許可權?] 飛出視窗上,選取 [ 應用程式許可權]。
在出現的許可權清單中,展開 [Exchange],選取 [Exchange.ManageAsApp],然後選取 [ 新增許可權]。
回到應用程式 API 許可權 頁面,確認已列出 Office 365 Exchange Online>Exchange.ManageAsApp ,並包含下列值:
類型: 應用程式。
需要管理員同意: 是。
狀態:目前不正確的值 未授與 <組織>。
選取 [授與組織>管理員同意<],讀取開啟的確認對話框,然後選取 [是],以變更此值。
[ 狀態] 值現在是 [授與給 <組織]>。
針對預設 Microsoft Graph>User.Read 項目,選取 [...]>撤銷系統管理員同意,然後在開啟的確認對話框中選取 [ 是 ],將 [狀態 ] 傳回預設空白值。
關閉目前的 [API 權限] 頁面 (不是瀏覽器索引標籤),以回到 [應用程式註冊] 頁面。 您會在後續步驟中使用 [應用程式註冊 ] 頁面。
修改應用程式指令清單以指派 API 許可權
注意事項
本節中的程式會將應用程式的現有默認許可權附加 (委派的User.Read權限,Microsoft Graph) Office 365 Exchange Online 中所需的應用程式 Exchange.ManageAsApp 許可權。
在 [應用程式概觀] 頁面上,從 [管理] 區段中選取 [指令清單]。
在 [應用程式指令 清單 ] 頁面上,尋找
requiredResourceAccess
(或大約第 42 行) 的專案,並讓專案看起來像下列代碼段:"requiredResourceAccess": [ { "resourceAppId": "00000002-0000-0ff1-ce00-000000000000", "resourceAccess": [ { "id": "dc50a0fb-09a3-484d-be87-e023b12c6440", "type": "Role" } ] }, { "resourceAppId": "00000003-0000-0000-c000-000000000000", "resourceAccess": [ { "id": "e1fe6dd8-ba31-4d61-89e7-88639da4683d", "type": "Scope" } ] } ],
注意事項
Microsoft 365 GCC High 或 DoD 環境只能存取安全性 & 合規性 PowerShell。 針對專案使用下列值
requiredResourceAccess
:"requiredResourceAccess": [ { "resourceAppId": "00000007-0000-0ff1-ce00-000000000000", "resourceAccess": [ { "id": "455e5cd2-84e8-4751-8344-5672145dfa17", "type": "Role" } ] }, { "resourceAppId": "00000003-0000-0000-c000-000000000000", "resourceAccess": [ { "id": "e1fe6dd8-ba31-4d61-89e7-88639da4683d", "type": "Scope" } ] } ],
當您在 [指令 清單 ] 頁面上完成時,請選取 [ 儲存]。
仍在 [ 指令清單] 頁面上,從 [管理] 區段中選取 [API權 限]。
在 [API 許可權] 頁面上,確認 已列出 Office 365 Exchange Online>Exchange.ManageAsApp ,並包含下列值:
類型: 應用程式。
需要管理員同意: 是。
狀態:Office 365 Exchange Online>Exchange.ManageAsApp 項目的組織>未授<與目前的不正確值。
選取 [授與組織>管理員同意<],讀取開啟的確認對話框,然後選取 [是],以變更 [狀態] 值。
[ 狀態] 值現在是 [授與給 <組織]>。
針對預設 Microsoft Graph>User.Read 項目,選取 [...]>撤銷系統管理員同意,然後在開啟的確認對話框中選取 [ 是 ],將 [狀態 ] 傳回預設空白值。
關閉目前的 [API 權限] 頁面 (不是瀏覽器索引標籤),以回到 [應用程式註冊] 頁面。 您會在後續步驟中使用 [應用程式註冊 ] 頁面。
步驟 3:產生自行簽署憑證
使用下列其中一種方法建立自行簽署的 x.509 憑證:
(建議) 在提升權限 (以系統管理員身分執行) 的 Windows PowerShell 工作階段中使用 New-SelfSignedCertificate、Export-Certificate 和 Export-PfxCertificate Cmdlet 來要求自我簽署的憑證,並將它匯出為
.cer
和.pfx
(預設為 SHA1)。 例如:# Create certificate $mycert = New-SelfSignedCertificate -DnsName "contoso.org" -CertStoreLocation "cert:\CurrentUser\My" -NotAfter (Get-Date).AddYears(1) -KeySpec KeyExchange # Export certificate to .pfx file $mycert | Export-PfxCertificate -FilePath mycert.pfx -Password (Get-Credential).password # Export certificate to .cer file $mycert | Export-Certificate -FilePath mycert.cer
使用 Create-SelfSignedCertificate 指令碼來產生 SHA1 憑證。
.\Create-SelfSignedCertificate.ps1 -CommonName "MyCompanyName" -StartDate 2021-01-06 -EndDate 2022-01-06
步驟 4:將憑證附加至 Microsoft Entra 應用程式
向應用程式註冊憑證之後,您可以使用私密金鑰 (.pfx
檔案) 或指紋來進行驗證。
在步驟 2 結尾的 [應用程式註冊] 頁面上的 [擁有的應用程式] 索引標籤上,選取您的應用程式。
如果您需要回到 [應用程式註冊 ] 頁面,請使用 https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps,確認已選取 [ 擁有的應用程式 ] 索引卷標,然後選取您的應用程式。
在開啟的應用程式頁面上,從 [管理] 區段中選取 [憑證 & 秘密]。
在 [ 憑證 & 秘密 ] 頁面上,選取 [ 上傳憑證]。
在開啟的對話方塊中,瀏覽至您在步驟 3 中建立的自我簽署憑證 (
.cer
檔案)。完成時,選取 [新增]。
憑證現在會顯示在 [憑證] 區段中。
關閉目前的 [憑證及祕密] 頁面,然後關閉 [應用程式註冊] 頁面,以回到 https://portal.azure.com/ 的主頁面。 您會在下一個步驟用到它。
步驟 4b:僅限 Exchange Online 委派案例:授與多租使用者應用程式的管理員同意
如果您在步驟 1 中為 Exchange Online 委派案例建立應用程式多租使用者,您必須將 Exchange.ManageAsApp 許可權的管理員同意授與,讓應用程式可以在每個租用戶組織中於 Exchange Online 中執行 Cmdlet。 若要這樣做,請為每個客戶租用戶產生系統管理員同意 URL。 在任何人使用多租使用者應用程式連線到租用戶組織中的 Exchange Online 之前,客戶租使用者中的系統管理員應該開啟下列 URL:
https://login.microsoftonline.com/<tenant-id>/adminconsent?client_id=<client-id>&scope=https://outlook.office365.com/.default
-
<tenant-id>
是客戶的租用戶標識碼。 -
<client-id>
是多租使用者應用程式的標識碼。 - 默認範圍是用來授與應用程式許可權。
如需URL語法的詳細資訊,請參閱 向目錄管理員要求許可權。
步驟 5:將 Microsoft Entra 角色指派給應用程式
您有兩種選擇:
- 將 Microsoft Entra 角色指派給應用程式
- 使用服務主體將自定義角色群組指派給應用程式:只有當您在 REST API 模式中連線到 Exchange Online PowerShell 或安全性 & 合規性 PowerShell 時,才支援此方法。 安全性 & 合規性 PowerShell 支援 v3.2.0 或更新版本中的 REST API 模式。
注意事項
您也可以結合這兩種方法來指派許可權。 例如,您可以針對「Exchange 收件者系統管理員」角色使用 Microsoft Entra 角色,也可以指派您的自定義 RBAC 角色來擴充許可權。
針對 Exchange Online 委派案例中的多租使用者應用程式,您必須在每個客戶租使用者中指派許可權。
將 Microsoft Entra 角色指派給應用程式
下表說明支援的 Microsoft Entra 角色:
角色 | Exchange Online PowerShell |
安全性與合規性 PowerShell |
---|---|---|
合規性系統管理員 | ✔ | ✔ |
Exchange 系統管理員¹ | ✔ | |
Exchange 收件者系統管理員 | ✔ | |
全域管理員¹ ² | ✔ | ✔ |
全域讀取者 | ✔ | ✔ |
技術服務人員系統管理員 | ✔ | |
安全性系統管理員¹ | ✔ | ✔ |
安全性讀取者 | ✔ | ✔ |
¹ 全域管理員和 Exchange 系統管理員角色提供 Exchange Online PowerShell 中任何工作的必要許可權。 例如:
- 收件者管理。
- 安全性和保護功能。 例如,反垃圾郵件、反惡意程式碼、防網路釣魚,以及相關聯的報告。
安全性系統管理員角色沒有這些相同 Exchange 相關工作的必要權限。
² Microsoft建議您使用許可權最少的角色。 使用較低許可權的帳戶有助於改善組織的安全性。 全域管理員是高度特殊許可權的角色,當您無法使用現有角色時,應該僅限於緊急案例。
如需在 Microsoft Entra ID 中指派角色的一般指示,請參閱將 Microsoft Entra 角色指派給使用者。
注意事項
下列步驟對 Exchange Online PowerShell 和安全性與合規性 PowerShell 稍有不同。 這兩個環境的步驟都會顯示出來。 若要設定兩個環境的角色,請重複本節中的步驟。
在 Microsoft 的 Entra 系統管理中心https://portal.azure.com/,開始在頁面頂端的 [搜尋] 方塊中輸入角色和系統管理員,然後從 [服務] 區段的結果中選取 [Microsoft Entra 角色和系統管理員]。
或者,若要直接移至 [Microsoft Entra 角色和系統管理員] 頁面,請使用 https://portal.azure.com/#view/Microsoft_AAD_IAM/AllRolesBlade。
在開啟的 [角色和系統管理員] 頁面上,尋找並選取其中一個支援的角色,方法是按一下結果中的角色名稱 (而非核取方塊)。
Exchange Online PowerShell:例如,尋找並選取 Exchange 系統管理員 角色。
安全性 & 合規性 PowerShell:例如,尋找並選取 合規性系統管理員 角色。
在開啟 的 [指派] 頁面上,選取 [ 新增指派]。
Exchange Online PowerShell:
安全性與合規性 PowerShell:
在 [新增指派] 飛出視窗中,尋找並選取您在步驟 1 中建立的應用程式。
當您在 [ 新增指派 ] 飛出視窗中完成時,請選取 [ 新增]。
回到 [ 指派] 頁面,確認角色已指派給應用程式。
Exchange Online PowerShell:
安全性與合規性 PowerShell:
使用服務主體將自定義角色群組指派給應用程式
注意事項
您必須先連線到 Exchange Online PowerShell 或安全性 & 合規性 PowerShell, 才能 完成建立新服務主體的步驟。 建立新的服務主體而不連線到PowerShell將無法運作 (需要您的 Azure 應用程式識別碼和物件識別碼,才能建立新的服務主體) 。
只有當您在 REST API 模式中連線到 Exchange Online PowerShell 或安全性 & 合規性 PowerShell 時,才支援此方法。 安全性 & 合規性 PowerShell 支援 v3.2.0 或更新版本中的 REST API 模式。
如需建立自定義角色群組的相關信息,請參閱 在 Exchange Online 中建立角色群組和在Microsoft Defender 入口網站中建立電子郵件 & 共同作業角色群組。 您指派給應用程式的自訂角色群組可以包含內建和自定義角色的任何組合。
若要使用服務主體將自訂角色群組指派給應用程式,請執行下列步驟:
在 Microsoft Graph PowerShell 中,執行下列命令,將您在 步驟 1 中註冊的 Microsoft Entra 應用程式詳細數據儲存在變數中:
Connect-MgGraph -Scopes AppRoleAssignment.ReadWrite.All,Application.Read.All $<VariableName1> = Get-MgServicePrincipal -Filter "DisplayName eq '<AppName>'"
例如:
Connect-MgGraph -Scopes AppRoleAssignment.ReadWrite.All,Application.Read.All $AzureADApp = Get-MgServicePrincipal -Filter "DisplayName eq 'ExO PowerShell CBA'"
如需詳細的語法和參數資訊,請參閱 Get-MgServicePrincipal。
在相同的 PowerShell 視窗中,連線到 Exchange Online PowerShell 或 安全性 & 合規性 PowerShell ,然後執行下列命令來執行:
- 建立 Microsoft Entra 應用程式的服務主體物件。
- 將服務主體的詳細數據儲存在變數中,以便在下一個步驟中使用。
New-ServicePrincipal -AppId $<VariableName1>.AppId -ObjectId $<VariableName1>.Id -DisplayName "<Descriptive Name>" $<VariableName2> = Get-ServicePrincipal -Identity "<Descriptive Name>"
例如:
New-ServicePrincipal -AppId $AzureADApp.AppId -ObjectId $AzureADApp.Id -DisplayName "SP for Azure AD App ExO PowerShell CBA" $SP = Get-ServicePrincipal -Identity "SP for Azure AD App ExO PowerShell CBA"
如需詳細的語法和參數資訊,請參閱 New-ServicePrincipal。
在 Exchange Online PowerShell 或安全性 & 合規性 PowerShell 中,執行下列命令,將服務主體新增為自定義角色群組的成員:
Add-RoleGroupMember -Identity "<CustomRoleGroupName>" -Member <$<VariableName2>.Identity | $<VariableName2>.ObjectId | $<VariableName2>.Id>
例如:
Add-RoleGroupMember -Identity "Contoso View-Only Recipients" -Member $SP.Identity
如需詳細的語法及參數資訊,請參閱 Add-RoleGroupMember。