建立應用程式註冊以搭配 Azure Digital Twins 使用

本文說明如何建立可存取 Azure Digital Twins 的 Microsoft Entra ID「應用程式註冊」。 本文包含 Azure 入口網站和 Azure CLI 的步驟。

使用 Azure Digital Twins 時，通常會透過用戶端應用程式與您的執行個體互動。 這些應用程式需要向 Azure Digital Twins 進行驗證，而應用程式可使用的一些驗證機制會涉及到應用程式註冊。

並非所有驗證案例都需要應用程式註冊。 但如果您使用的驗證策略或程式碼範例需要應用程式註冊，則本文可為您展示如何設定並授權給 Azure Digital Twins API。 內容還涵蓋如何收集使用應用程式註冊驗證時所需的重要值。

提示

您可能偏好在每次需要時設定一個新的應用程式註冊，或是只設定一次，而建立單一應用程式註冊，您便可在所有需要的案例之間共用。

建立註冊

首先，選取下方您慣用介面的索引標籤。

入口網站

在 Azure 入口網站中瀏覽至 Microsoft Entra ID (您可以使用此連結，或使用入口網站搜尋列來尋找)。 從服務功能表中選取 [應用程式註冊]，然後選取 [+ 新增註冊]。

在後續的 [註冊應用程式] 頁面中，填入要求的值：

• 名稱：要與註冊建立關聯的Microsoft Entra 應用程式顯示名稱。
• 支援的帳戶類型：僅選取此組織目錄中的帳戶（僅限預設目錄 - 單一租使用者）。

完成之後，請選取 [註冊] 按鈕。

完成註冊設定後，入口網站會將您重新導向至詳細資料頁面。

CLI

首先，建立資訊清單檔，其中包含應用程式註冊要存取的 Azure Digital Twins API 服務資訊。 接著，您需要將此檔案傳遞至 CLI 命令以建立註冊。

建立資訊清單

在電腦上建立名為「manifest.json」的新 .json 檔案。 將此文字複製到檔案內：

[
	{
		"resourceAppId": "0b07f429-9f4b-4714-9392-cc5e8e80c8b0",
		"resourceAccess": [
			{
				"id": "4589bd03-58cb-4e6c-b17f-b580e39652f8",
				"type": "Scope"
			}
		]
	}
]

靜態值 0b07f429-9f4b-4714-9392-cc5e8e80c8b0 是 Azure Digital Twins 服務端點的資源識別碼，您的應用程式註冊在存取 Azure Digital Twins API 時需要此資訊。

儲存完成的檔案。

Cloud Shell 使用者：上傳資訊清單

如果您使用 Azure Cloud Shell 實作本教學課程內容，則必須將建立的資訊清單檔案上傳至 Cloud Shell，以便在設定應用程式註冊時，在 Cloud Shell 命令中存取該檔案。 如果您是使用本機安裝的 Azure CLI，則可以跳到下一個步驟：執行建立命令。

若要上傳檔案，請移至瀏覽器中的 Cloud Shell 視窗。 選取 [上傳/下載檔案] 圖示，然後選擇 [上傳]。

瀏覽至電腦上的 manifest.json 檔案，然後選取 [開啟]。 如此一來，檔案便會上傳至 Cloud Shell 儲存體的根目錄。

執行建立命令

在本節中，您將執行 CLI 命令，以使用下列設定來建立應用程式註冊：

• 您選擇的名稱
• 僅適用於預設目錄中的帳戶 (單一租用戶)
• http://localhost 的 Web 回覆 URL
• Azure Digital Twins API 的讀取/寫入權限

執行下列命令來建立註冊。 如果您是使用 Cloud Shell，則 manifest.json 檔案的路徑為 @manifest.json。

az ad app create --display-name <app-registration-name> --sign-in-audience AzureADMyOrg --required-resource-accesses "manifest.json"

此命令的輸出是您所建立應用程式註冊的相關資訊。

確認是否成功

您可以在建立命令輸出的 requiredResourceAccess 中尋找下列欄位，以確認已授權 Azure Digital Twins。 確認這些值符合下面所列的內容。

• resourceAccess > id 為 4589bd03-58cb-4e6c-b17f-b580e39652f8
• resourceAppId 為 0b07f429-9f4b-4714-9392-cc5e8e80c8b0

取得重要的值

接下來，請收集一些有關應用程式註冊的重要值，在使用應用程式註冊來驗證用戶端應用程式時會用到這些值。 這些值包括：

• 資源名稱：使用 Azure Digital Twins 時，資源名稱為 http://digitaltwins.azure.net。
• 用戶端識別碼
• 租用戶識別碼
• 用戶端密碼

下列各節會說明如何尋找其餘的值。

收集用戶端識別碼和租用戶識別碼

若要使用應用程式註冊進行驗證，您可能需要提供其應用程式 (用戶端) 識別碼以及目錄 (租用戶) 識別碼。 您需要收集此處的這些值，進行儲存以便在需要時使用。

入口網站

您可以從 Azure 入口網站的應用程式註冊詳細資料頁面，收集用戶端識別碼和租使用者識別碼值：

記下頁面上顯示的應用程式 (用戶端) 識別碼以及目錄 (租用戶) 識別碼。

CLI

您可以在稍早執行的命令的輸出az ad app create中找到應用程式識別碼（或使用 az ad app show 再次顯示資訊）。

在結果中尋找 appId ：

您可以使用 az account tenant list 命令，在殼層中顯示租用戶標識碼。

注意

這個命令群組是實驗性的，目前正在開發中。

收集用戶端密碼

設定應用程式註冊的用戶端密碼，以供其他應用程式用於進行驗證。

入口網站

首先前往 Azure 入口網站中的應用程式註冊頁面。

1. 從註冊功能表選取 [憑證和秘密]，然後選取 [+ 新增用戶端密碼]。

   

2. 針對 [描述] 和 [到期日] 輸入您需要的值，然後選取 [新增]。

   

3. 確認 [憑證和秘密] 頁面上有顯示用戶端密碼，並包含 [到期日] 和 [值] 欄位。

4. 記下其 [秘密識別碼] 和 [值]，以便稍後使用 (您也可以使用複製圖示以複製到剪貼簿)。

   

重要

請務必立即複製值，並將其儲存在安全的地方，因為這些值無法再次擷取。 如果您稍後找不到這些秘密，則必須建立新的秘密。

CLI

若要為應用程式註冊建立用戶端密碼，將會需要在上一個步驟中收集的應用程式註冊用戶端識別碼值。 使用下列 CLI 命令中的值來建立新的秘密：

az ad app credential reset --id <client-ID> --append

您也可以在此命令中新增選用參數，以指定認證描述、結束日期和其他詳細資料。 如需命令及其參數的詳細資訊，請參閱 az ad app credential reset 文件。

此命令的輸出是有關您已建立的用戶端秘密。

請複製 password 的值以在需要用戶端密碼進行驗證時使用。

重要

請務必立即複製值，並將其儲存在安全的地方，因為此值無法再次擷取。 如果您稍後找不到此值，則必須建立新的秘密。

提供 Azure Digital Twins 權限

接下來，請為已建立的應用程式註冊設定存取 Azure Digital Twins 權限。 一共需要兩種類型的權限：

• Azure Digital Twins 執行個體內應用程式註冊的角色指派
• 應用程式讀取和寫入 Azure Digital Twins API 的 API 權限

建立角色指派

在本節中，您將為 Azure Digital Twins 執行個體上的應用程式註冊建立角色指派。 此角色會決定應用程式註冊在執行個體上保留的權限，因此您應該根據需求，選取適當權限層級的角色。 可能的角色之一是 Azure Digital Twins 資料擁有者。 如需角色及其描述的完整清單，請參閱 Azure 內建角色。

入口網站

使用下列步驟來建立註冊的角色指派。

1. 在 Azure 入口網站中，開啟您的 Azure Digital Twins 執行個體頁面。

2. 選取 [存取控制 (IAM)]。

3. 選取 [新增 > 角色指派 ] 以開啟 [新增角色指派] 頁面。

4. 指派適當的角色。 如需詳細步驟，請參閱使用 Azure 入口網站指派 Azure 角色。

   設定	值
   角色	視需要選取
   成員 > 指派存取權給	使用者、群組或服務主體
   成員 > 成員	+ 選取成員，然後搜尋應用程式註冊的名稱

   

   

   選取角色後，加以檢閱 + 指派。

驗證角色指派

您可以在 [存取控制 (IAM)] > [角色指派] 下檢視已設定的角色指派。

應用程式註冊應該會顯示在清單中，並包含您為其指派的角色。

CLI

使用 az dt role-assignment create 命令來指派角色 (必須由 Azure 訂用帳戶中具有足夠權限的使用者執行)。 此命令會要求您傳入要指派的角色名稱、Azure Digital Twins 執行個體的名稱，以及應用程式註冊的名稱或物件識別碼。

az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<name-or-ID-of-app-registration>" --role "<appropriate-role-name>"

此命令的結果會輸出針對此應用程式註冊建立的角色指派相關資訊。

若要進一步確認角色指派，您可以在 [Azure 入口網站] 切換至入口網站指示索引標籤以尋找該角色。

提供 API 權限

在本節中，您會將應用程式基準的讀取/寫入權限授與 Azure Digital Twins API。

如果您是使用 Azure CLI，並在稍早透過資訊清單檔案設定應用程式註冊，則此步驟已經完成。 如果您是使用 Azure 入口網站來建立應用程式註冊，請繼續進行本節的其餘部分來設定 API 權限。

入口網站

在應用程式註冊的入口網站頁面，從功能表選取 [API 權限]。 在下列權限頁面上，選取 [+ 新增權限] 按鈕。

在後續的 [要求 API 權限] 頁面中，切換至 [我的組織使用的 API] 索引標籤，並搜尋「Azure Digital Twins」。 從搜尋結果中選取 [Azure Digital Twins] 以繼續指派 Azure Digital Twins API 的權限。

注意

如果您的訂用帳戶仍有來自先前公開預覽版的現有 Azure Digital Twins 執行個體 (在 2020 年 7 月之前)，您必須改為搜尋並選取 [Azure 智慧空間服務]。 這是相同 API 集合的舊版名稱 (請注意 [應用程式 (用戶端) 識別碼] 與上述螢幕擷取畫面中的識別碼相同)，且此步驟之後的體驗不會改變。

接下來，您需要選取這些 API 可獲得的權限。 展開 [讀取 (1)] 權限，然後勾選顯示 [Read.Write] 的核取方塊，即可授與此應用程式註冊讀取者和寫入者的權限。

完成時，選取 [新增權限]。

驗證 API 權限

在 [API 權限] 頁面上，確認 Azure Digital Twins 現在具有反映 [Read.Write] 權限的項目：

您也可以在應用程式註冊的 manifest.json 內驗證與 Azure Digital Twins 的連線，當您新增 API 權限時，該檔案會根據 Azure Digital Twins 資訊自動更新。

若要這樣做，請從功能表中選取 [資訊清單]，以檢視應用程式註冊的資訊清單程式碼。 捲動至程式碼視窗底部，並在 requiredResourceAccess 下方尋找下列欄位和值：

• "resourceAppId": "0b07f429-9f4b-4714-9392-cc5e8e80c8b0"
• "resourceAccess" > "id": "4589bd03-58cb-4e6c-b17f-b580e39652f8"

這些值如以下螢幕擷取畫面所示：

如果缺少這些值，請重新嘗試新增 API 權限一節中的步驟。

CLI

如果您使用 CLI，則先前的建立註冊步驟中已經設定 API 權限。

您現在可以使用 Azure 入口網站確認該權限 (切換至入口網站指示索引標籤)。

貴組織可能需要的其他步驟

在某些情況下，您的組織可能需要由訂用帳戶擁有者或系統管理員執行更多動作，才能完成應用程式註冊。 這些必要步驟可能會根據您組織的專有設定而有所不同。 選擇下方的索引標籤，以查看您慣用介面適用的資訊。

入口網站

以下是訂用帳戶的擁有者或系統管理員可能需要進行的一些常見活動。 這些活動及其他作業可以在 Azure 入口網站中的 [Microsoft Entra 應用程式註冊] 頁面執行。

• 授與系統管理員同意應用程式註冊。 您的組織可能在 Microsoft Entra ID 中，以全域層級為訂用帳戶中的所有應用程式註冊啟用 [需要管理員同意]。 若是如此，則擁有者/系統管理員必須在應用程式註冊的 [API 權限] 頁面上，為您的公司選取此按鈕，應用程式註冊才會生效：

  

  • 如果成功授與同意，則 Azure Digital Twins 項目的 [狀態] 值應該會顯示為 [已授與 (您的公司)]

  

• 啟用公用用戶端存取權

• 設定供 Web 和桌面存取的特定回覆 URL

• 允許隱含 OAuth2 驗證流程

CLI

以下是訂用帳戶的擁有者或系統管理員可能需要進行的一些常見活動。

• 授與系統管理員同意應用程式註冊。 您的組織可能在 Microsoft Entra ID 中，以全域層級為訂用帳戶中的所有應用程式註冊啟用 [需要管理員同意]。 如果是，則擁有者/系統管理員可能需要授與其他委派或應用程式權限。
• 將 --set publicClient=true 附加至註冊的建立或更新命令以啟用公用用戶端存取權。
• 使用 --reply-urls 參數設定 Web 和桌面存取的特定回覆 URL。 如需此參數搭配 az ad 命令使用的詳細資訊，請參閱 az ad app 文件。
• 允許使用 --oauth2-allow-implicit-flow 參數的隱含 OAuth2 驗證流程。 如需此參數搭配 az ad 命令使用的詳細資訊，請參閱 az ad app 文件。

如需應用程式註冊及其不同設定選項的詳細資訊，請參閱使用 Microsoft 身分識別平台來註冊應用程式。

下一步

在本文中，您設定了可用於透過 Azure Digital Twins API 驗證用戶端應用程式的 Microsoft Entra 應用程式註冊。

接下來，請閱讀驗證機制，包括使用應用程式註冊的驗證機制，以及不使用該註冊的其他機制：

• 撰寫應用程式驗證碼