設定連接器以匯入實體徽章數據

發行項
04/01/2024

您可以設定數據連接器來匯入實體徽章數據，例如員工的原始實體存取事件，或組織徽章系統所產生的任何實體存取警示。實體存取點的範例包括建築物的專案或伺服器室或數據中心的專案。 Microsoft Purview Insider Risk Management 解決方案可以使用實體惡意代碼數據，協助保護貴組織免於遭受組織內的惡意活動或數據竊取。

設定實體徽章連接器包含下列工作：

在 Microsoft Entra ID 中建立應用程式，以存取接受包含實體徽章數據之 JSON 承載的 API 端點。
使用實體徽章數據連接器所定義的架構來建立 JSON 承載。
在 Microsoft Purview 入口網站或 Microsoft Purview 合規性入口網站中建立實體徽章數據連接器。
執行腳本來將實體徽章數據推送至 API 端點。
選擇性地將腳本排程為自動執行，以匯入目前實體的徽章數據。

提示

如果您不是 E5 客戶，請使用 90 天的 Microsoft Purview 解決方案試用版來探索其他 Purview 功能如何協助貴組織管理數據安全性與合規性需求。立即從 Microsoft Purview 合規性入口網站試用中樞開始。瞭解有關註冊和試用版條款的詳細數據。

設定連接器之前

在步驟 3 中建立實體徽章連接器的用戶必須獲指派數據連接器管理員角色。需要此角色，才能在 Microsoft Purview 入口網站或合規性入口網站的 [ 資料連接器 ] 頁面上新增連接器。此角色預設會新增至多個角色群組。如需這些角色群組的清單，請參閱適用於 Office 365 的 Microsoft Defender 中的角色和 Microsoft Purview 合規性。或者，組織中的系統管理員可以建立自定義角色群組、指派數據連接器管理員角色，然後將適當的使用者新增為成員。如需詳細指示，請參閱：
注意事項

美國政府 GCC High 和 DoD 環境中目前不支援資料連接器管理員角色。因此，在 GCC High 和 DoD 環境中建立 HR 連接器的用戶必須在 Exchange Online 中指派信箱匯入匯出角色。依預設，此角色不會指派給 Exchange Online 內的任何角色群組。您可以在 Exchange Online 中將「信箱匯入匯出」角色新增至「組織管理」角色群組。或者，您可以建立新的角色群組、指派信箱匯入匯出角色，然後將適當的使用者新增為成員。如需詳細資訊，請參閱「在 Exchange Online 中管理角色群組」文章中的建立角色群組或修改角色群組章節。
您必須判斷如何每天從組織的實體徽章系統 (擷取或匯出數據，) 並建立步驟 2 中所述的 JSON 檔案。您在步驟 4 中執行的腳本會將 JSON 檔案中的數據推送至 API 端點。
您在步驟 4 中執行的範例腳本會將實體徽章數據從 JSON 檔案推送至連接器 API，讓測試人員風險管理解決方案可以使用該數據。任何 Microsoft 標準支援計劃或服務都不支援此範例腳本。範例指令碼係依「現狀」提供，不含任何種類的擔保方式。 Microsoft 另外不承擔任何明示或默示的擔保，包括但不限於適售性或適合某特定用途的默示擔保。使用或操作範例指令碼和文件發生的所有風險，皆屬於您的責任。 Microsoft、其作者以及其他與建置、生產或交付程式碼相關的任何人在任何情況下皆完全不需對任何損失負責任，包括但不限於商業利潤損失、業務中斷、業務資訊損失、或其他錢財損失等因使用或無法使用範例指令碼或文件所發生的損失，即使 Microsoft 曾建議這些損失發生的可能性。
此連接器可在 Microsoft 365 美國政府雲端的 GCC 環境中使用。第三方應用程式和服務可能涉及在 Microsoft 365 基礎結構以外的第三方系統上儲存、傳輸和處理貴組織的客戶數據，因此 Microsoft Purview 和數據保護承諾並未涵蓋在內。這不代表將此產品用於連線至協力廠商應用程式的這些協力廠商應用程式符合 FEDRAMP 規範。

步驟 1：在 Microsoft Entra ID 中建立應用程式

第一個步驟是在 Microsoft Entra ID 中建立並註冊新的應用程式。應用程式會對應至您在步驟 3 中建立的實體徽章連接器。建立此應用程式可讓 Microsoft Entra ID 驗證包含實體徽章數據之 JSON 承載的推播要求。在建立此 Microsoft Entra 應用程式期間，請務必儲存下列資訊。這些值將在後續步驟中使用。

Microsoft Entra 應用程式識別碼 (也稱為應用程式識別碼或用戶端標識碼)
Microsoft Entra 應用程式秘密 (也稱為客戶端密碼)
租用戶標識碼 (也稱為 目錄標識 碼)

如需在 Microsoft Entra ID 中建立應用程式的逐步指示，請參閱向 Microsoft 身分識別平台註冊應用程式。

步驟 2：準備具有實體徽章數據的 JSON 檔案

下一個步驟是建立 JSON 檔案，其中包含員工實體存取數據的相關信息。如開始一節之前所述，您必須判斷如何從組織的實體徽章系統產生此 JSON 檔案。

JSON 檔案必須符合連接器所需的架構定義。以下是 JSON 檔案所需架構屬性的描述：

屬性	描述	資料類型
UserId	員工可以在系統中擁有多個數位身分識別。輸入必須已由來源系統解析 Microsoft Entra ID。	UPN 或電子郵件位址
AssetId	實體資產或實體存取點的參考標識符。	英數位元字串
AssetName	實體資產或實體存取點的易記名稱。	英數位元字串
EventTime	存取的時間戳。	UTC 格式的日期和時間
AccessStatus	或的 `Success` 值 `Failed`	String

以下是符合所需架構的 JSON 檔案範例：

[
    {
        "UserId":"sarad@contoso.com",
        "AssetId":"Mid-Sec-7",
        "AssetName":"Main Building 1st Floor Mid Section",
        "EventTime":"2019-07-04T01:57:49",
        "AccessStatus":"Failed"
    },
    {
        "UserId":"pilarp@contoso.com",
        "AssetId":"Mid-Sec-7",
        "AssetName":"Main Building 1st Floor Mid Section",
        "EventTime":"2019-07-04T02:57:49",
        "AccessStatus":"Success"
    }
]

當您在步驟 3 中建立實體徽章連接器時，您也可以從精靈下載下列 JSON 檔案的架構定義。

{
   "title" : "Physical Badging Signals",
   "description" : "Access signals from physical badging systems",
   "DataType" : {
      "description" : "Identify what is the data type for input signal",
      "type" : "string",
   },
   "type" : "object",
   "properties": {
      "UserId" : {
         "description" : "Unique identifier AAD Id resolved by the source system",
         "type" : "string",
      },
      "AssetId": {
         "description" : "Unique ID of the physical asset/access point",
         "type" : "string",
      },
      "AssetName": {
         "description" : "friendly name of the physical asset/access point",
         "type" : "string",
      },
      "EventTime" : {
         "description" : "timestamp of access",
         "type" : "string",
      },
      "AccessStatus" : {
         "description" : "what was the status of access attempt - Success/Failed",
         "type" : "string",
      },
   }
   "required" : ["UserId", "AssetId", "EventTime" "AccessStatus"]
}

步驟 3：建立實體徽章連接器

下一個步驟是在 Microsoft Purview 入口網站或合規性入口網站中建立實體徽章連接器。在步驟 4 中執行腳本之後，將會處理您在步驟 3 中建立的 JSON 檔案，並推送至您在步驟 1 中設定的 API 端點。在此步驟中，請務必複製建立連接器時產生的JobId。當您執行文稿時，將會使用 JobId。

針對您使用的入口網站選取適當的索引標籤。若要深入瞭解 Microsoft Purview 入口網站，請參閱 Microsoft Purview 入口網站。若要深入瞭解合規性入口網站，請參閱 Microsoft Purview 合規性入口網站。

Microsoft Purview 入口網站
合規性入口網站

登入 Microsoft Purview 入口網站。
選取> [設定數據連接器]。
選取 [我的連接器]，然後選取 [ 新增連接器]。
從清單中，選擇 [ 實體徽章]。
在 [ 驗證認證 ] 頁面上，執行下列動作，然後選取 [ 下一步]：
1. 輸入或貼上您在步驟 1 中建立的 Azure 應用程式 Microsoft Entra 應用程式識別碼。
2. 下載範例架構以供您參考，以建立 JSON 檔案。
3. 輸入實體徽章連接器的唯一名稱。
在 [ 檢閱] 頁面上，檢閱您的設定，然後選取 [ 完成 ] 以建立連接器。
狀態頁面隨即顯示，確認連接器已建立。此頁面也包含作業標識碼。您可以從此頁面或從連接器的飛出視窗頁面複製作業識別碼。執行文稿時，您需要此作業識別碼。

狀態頁面也包含腳本的連結。請參閱此腳本，以瞭解如何將 JSON 檔案張貼至 API 端點。
選取 [完成]。

新的連接器會顯示在 [ 連接器] 索 引標籤上的清單中。
選取您剛才建立的實體徽章連接器，以顯示飛出視窗頁面，其中包含連接器的屬性和其他資訊。

步驟 4：執行腳本以張貼包含實體徽章數據的 JSON 檔案

設定實體徽章連接器的下一個步驟是執行腳本，以將您在步驟 2 中建立的 JSON 檔案 (中的實體徽章數據推送至您在步驟 1 中建立的 API 端點) 。我們提供參考的範例腳本，您可以選擇使用它或建立自己的腳本，將 JSON 檔案張貼至 API 端點。

執行腳本之後，包含實體惡意代碼數據的 JSON 檔案會推送至您的 Microsoft 365 組織，內部風險管理解決方案可在其中存取該檔案。建議您每天張貼實體的不良數據。若要這麼做，您可以將每天從實體徽章系統產生 JSON 檔案的程式自動化，然後排程腳本來推送數據。

注意事項

JSON 檔案中可由 API 處理的記錄數目上限為 50,000 筆記錄。

移至此 GitHub 網站以存取範例腳本。
選取 [原始] 按鈕以在文字檢視中顯示文稿
複製範例文本中的所有行，然後將它們儲存至文本檔。
視需要修改組織的範例腳本。
使用檔名後綴 .ps1，將文本檔儲存為 Windows PowerShell 腳本檔案;例如，PhysicalBadging.ps1。
在本機計算機上開啟命令提示字元，然後移至您儲存腳本的目錄。

執行下列命令，將 JSON 檔案中的實體徽章數據推送至 Microsoft 雲端;例如：

.\PhysicalBadging.ps1 -tenantId "<Tenant Id>" -appId "<Azure AD App Id>" -appSecret "<Azure AD App Secret>" -jobId "Job Id" -jsonFilePath "<records file path>"

下表描述要搭配此腳本使用的參數及其必要值。您在先前步驟中取得的資訊會用於這些參數的值。

參數	描述
tenantId	這是您在步驟 1 中取得的 Microsoft 365 組織識別碼。您也可以在 Microsoft Entra 系統管理中心的 [概觀] 刀鋒視窗上取得組織的 tenantId。這是用來識別您的組織。
appId	這是您在步驟 1 中 Microsoft Entra ID 中建立之應用程式的 Microsoft Entra 應用程式識別碼。當腳本嘗試存取您的 Microsoft 365 組織時，Microsoft Entra ID 會使用此項目進行驗證。
appSecret	這是您在步驟 1 Microsoft Entra ID 中建立之應用程式的 Microsoft Entra 應用程式密碼。這也會用於驗證。
jobId	這是您在步驟 3 中建立之實體徽章連接器的作業標識碼。這是用來將推送至 Microsoft 雲端的實體徽章數據與實體徽章連接器產生關聯。
JsonFilePath	這是本機計算機上的檔案路徑， (您用來執行您在步驟 2 中建立之 JSON 檔案之腳本) 的檔案路徑。此檔案必須遵循步驟 3 中所述的範例架構。

以下是針對每個參數使用實際值之實體徽章連接器腳本的語法範例：

.\PhysicalBadging.ps1 -tenantId d5723623-11cf-4e2e-b5a5-01d1506273g9 -appId 29ee526e-f9a7-4e98-a682-67f41bfd643e -appSecret MNubVGbcQDkGCnn -jobId b8be4a7d-e338-43eb-a69e-c513cd458eba -jsonFilePath 'C:\Users\contosoadmin\Desktop\Data\physical_badging_data.json'

如果上傳成功，腳本會顯示 上傳成功 訊息。

如果您有多個 JSON 檔案，則必須為每個檔案執行腳本。

注意事項

您也可以選擇透過執行先前腳本以外的方法，將實體徽章數據推送至 API 端點。例如，以下是使用 Postman 將數據推送至 API 端點的範例。

步驟 5：監視實體徽章連接器

建立實體徽章連接器並推送實體徽章數據之後，您可以在 Microsoft Purview 入口網站或合規性入口網站中檢視連接器和上傳狀態。如果您排程定期自動執行文稿，您也可以在上次執行腳本之後檢視目前的狀態。

Microsoft Purview 入口網站
合規性入口網站

登入 Microsoft Purview 入口網站。
選取> [設定數據連接器]。
選取 [我的連接器]，然後選取您建立以顯示飛出視窗頁面的實體徽章連接器。此頁面包含連接器的屬性和資訊。
在 [ 上次匯入] 底下，選取 [下載記錄] 鏈接以開啟 (或儲存) 連接器的狀態記錄檔。此記錄檔包含每次腳本執行並將數據從 JSON 檔案上傳至 Microsoft 雲端時的相關信息。

RecordsSaved 字段會指出已上傳 JSON 檔案中的記錄數目。例如，如果 JSON 檔案包含四筆記錄，則如果腳本成功上傳 JSON 檔案中的所有記錄，則 RecordsSaved 字段的值為 4。 RecordsSkipped 字段會指出 JSON 檔案中已略過的記錄數目。上傳 JSON 檔案中的記錄之前，將會驗證記錄的 Email 識別碼。將會略過具有無效 Email 標識碼的任何記錄，並在 EmailIdsNotSaved 欄位中顯示對應的 Email 識別碼

如果您尚未在步驟 4 中執行腳本，[ 上次匯入] 底下會顯示下載腳本的連結。您可以下載腳本，然後遵循步驟 4 中的步驟來執行它。

(選擇性) 步驟 6：排程腳本自動執行

若要確定您組織中最新的實體不良數據可供測試人員風險管理解決方案之類的工具使用，建議您將腳本排程為定期自動執行，例如一天一次。如果) 排程不相同，這也需要您將實體徽章數據更新為類似 (的 JSON 檔案，以便包含有關離開組織員工的最新資訊。目標是上傳最新的實體徽章數據，讓實體徽章連接器可以提供給內部風險管理解決方案使用。

您可以使用 Windows 中的工作排程器應用程式，每天自動執行腳本。

在本機計算機上，選取 [Windows 開始 ] 按鈕，然後輸入 工作排程器。
選取 [工作排程器 ] 應用程式加以開啟。
在 [ 動作] 區 段中，選取 [ 建立工作]。
在 [ 一般] 索引標籤上，輸入排程工作的描述性名稱;例如， 實體徽章連接器腳本。您也可以新增選擇性描述。
在 [ 安全性選項] 下，執行下列動作：
1. 判斷是否只在登入計算機時才執行腳本，或在登入時執行腳本。
2. 確定已選取 [ 以最高許可權執行] 複選框。
選取 [ 觸發程式] 索引標籤 ，選取 [ 新增]，然後執行下列動作：
1. 在 [ 設定] 下，選取 [ 每日] 選項，然後選擇第一次執行腳本的日期和時間。文本會每天在相同的指定時間執行。
2. 在 [ 進階設定] 下，確定已選取 [ 已啟用 ] 複選框。
3. 選取 [確定]。
選取 [ 動作] 索引 標籤，選取 [ 新增]，然後執行下列動作：
1. 在 [ 動作] 下拉式清單中，確定已選取 [ 啟動程式 ]。
2. 在 [ 程式/腳本] 方塊中，選取 [ 流覽]，然後移至下列位置並加以選取，讓路徑顯示在方塊中：C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe。
3. 在 [ 新增自變數 (選擇性) ] 方塊中，貼上您在步驟 4 中執行的相同腳本命令。例如， .\PhysicalBadging.ps1-tenantId “d5723623-11cf-4e2e-b5a5-01d1506273g9” -appId “c12823b7-b55a-4989-faba-02de41bb97c3” -appSecret “MNubVGbcQDkGSecurity” -jobId “e081f4f4-3831-48d6-7bb3-fcfab1581458” -jsonFilePath “C：\Users\contosoadmin\Desktop\Data\physical_badging_data.json”
4. 在 [ (選用) 開始] 方塊中，貼上您在步驟 4 中執行之腳本的資料夾位置。例如，C：\Users\contosoadmin\Desktop\Scripts。
5. 選取 [確定 ] 以儲存新動作的設定。
在 [ 建立工作] 視窗中，選取 [ 確定] 以儲存排程的工作。系統可能會提示您輸入使用者帳戶認證。

新的工作會顯示在工作排程器連結庫中。

上次執行文本的時間，以及下一次排程執行時會顯示。您可以按下選取要編輯的工作。

您也可以確認上次文稿在合規性中心對應實體徽章連接器的飛出視窗頁面上執行的時間。