快速入門 - 在 Web 應用程式範例 Node.js 中登入使用者並呼叫 Web API

適用於： 外部租用戶 （深入瞭解）

在本快速入門中，您將瞭解如何登入使用者，並從外部租使用者中的 Node.js Web 應用程式呼叫 Web API。 範例應用程式會呼叫 .NET API。 範例 Web 應用程式會使用 適用於 Node 的 Microsoft 驗證程式庫（MSAL） 來處理驗證。

先決條件

• 完成 快速入門中的步驟和必要條件：在範例 Web 應用程式中登入使用者 一文。 本文說明如何使用範例 Node.js Web 應用程式來登入使用者。
• 外部租戶。 若要建立一個，請從下列方法中選擇：
  • （建議）使用 Microsoft Entra External ID 擴充功能 直接在 Visual Studio Code 中設定外部租使用者。
  • 在 Microsoft Entra 系統管理中心建立新的外部租戶。
• 在 Microsoft Entra 系統管理中心註冊 Web API 的新應用程式， 僅針對此組織目錄中的帳戶進行設定。 如需詳細資訊 ，請參閱註冊應用程式 。 從應用程式 [概 觀 ] 頁面記錄下列值，以供稍後使用：
  • 應用程式 （用戶端） 識別碼
  • 目錄（租戶）識別碼
• Visual Studio Code 或其他程式碼編輯器。
• Node.js。
• .NET 7.0 或更新版本。

設定 API 範圍和角色

藉由註冊 Web API，您必須設定 API 範圍，以定義用戶端應用程式可以要求存取 Web API 的許可權。 此外，您必須設定應用程式角色來指定使用者或應用程式可用的角色，並將必要的 API 許可權授與 Web 應用程式，讓其能夠呼叫 Web API。

設定 API 範圍

API 必須發佈至少一個範圍，也稱為 委派許可權，用戶端應用程式才能成功取得使用者的存取令牌。 若要發佈範圍，請遵循下列步驟：

1. 從 [應用程式註冊] 頁面中，選取您建立的 API 應用程式（ciam-ToDoList-api），以開啟其 概觀 頁面。

2. 在 [管理] 下，選取 [[公開 API]。

3. 在頁面頂端 應用程式識別碼 URI旁，選取 [新增 連結]，以產生此應用程式唯一的 URI。

4. 接受建議的應用程式識別碼 URI，例如api://{clientId}，然後選取[儲存]。 當您的 Web 應用程式要求 Web API 的存取令牌時，它會新增 URI 作為您為 API 定義之每個範圍的前置詞。

5. 在此 API 定義的 範圍下，選取 [加一個範圍]。

6. 輸入下列值來定義 API 的讀取許可權，然後選取 [[新增範圍] 以儲存變更：

   財產	價值
   範圍名稱	待辦清單.閱讀
   誰可以同意	僅限 管理員
   管理員同意顯示名稱	使用 'TodoListApi' 讀取使用者的待辦事項清單
   管理員同意描述	允許應用程式使用 『TodoListApi』讀取使用者的 ToDo 清單。
   國家	已啟用

7. 選取 [再次新增範圍，然後輸入下列值來定義 API 的讀取和寫入存取範圍。 選取 將範圍新增 來保存您的變更。

   財產	價值
   範圍名稱	ToDoList.ReadWrite
   誰可以同意	僅限 管理員
   管理員同意顯示名稱	使用 『ToDoListApi』 讀取和寫入使用者 ToDo 清單
   管理員同意描述	允許應用程式使用 『ToDoListApi』 來讀取和寫入使用者的 ToDo 清單
   國家	已啟用

深入了解在設定 Web API 許可權時的最低許可原則。

設定應用程式角色

API 需要為應用程式發佈至少一個應用程式角色，也稱為 應用程式許可權，用戶端應用程式才能取得存取令牌。 應用程式許可權是 API 想要讓用戶端應用程式以自己身分成功驗證，而不需要登入使用者時，應該發佈的許可權類型。 若要發佈應用程式許可權，請遵循下列步驟：

1. 從 [應用程式註冊] 頁面中，選取您建立的應用程式（例如 ciam-ToDoList-api），以開啟其 概觀 頁面。

2. 在 【管理】下，選取【應用程式角色】。

3. 選取 [[建立應用程式角色]，然後輸入下列值，然後選取 [套用]，以儲存變更：

   財產	價值
   顯示名稱	ToDoList.Read.All
   允許的成員類型	應用程式
   價值	ToDoList.Read.All
   描述	允許應用程式使用 『TodoListApi』 讀取每個使用者的 ToDo 清單
   您要啟用此應用程式角色嗎？	保持勾選狀態

4. 再次選取 [建立應用程式角色]，然後輸入下列第二個應用程式角色的值，然後選取 [套用]，以儲存變更：

   財產	價值
   顯示名稱	ToDoList.ReadWrite.All
   允許的成員類型	應用程式
   價值	ToDoList.ReadWrite.All
   描述	允許應用程式使用 『ToDoListApi』 讀取和寫入每個使用者的 ToDo 清單
   您要啟用此應用程式角色嗎？	保持勾選狀態

設定可選的宣告項

您可以新增 idtyp 選擇性宣告，以協助 Web API 判斷令牌是 應用程式 令牌還是 應用程式 + 使用者 令牌。 雖然您可以將 scp 和 角色結合 宣告來達成相同目的，但使用 idtyp 宣告是最簡單的方式來區分應用程式令牌和應用程式 + 使用者令牌。 例如，當代幣是僅供應用程式使用的代幣時，此宣告的值是 應用程式。

使用 設定選用宣告 一文中的步驟，將 idtyp 宣告新增至存取權杖：

• 針對 [令牌類型]，選取 [Access]。
• 從選擇性宣告清單中，選取 idtyp。

將 API 許可權授與 Web 應用程式

若要授與用戶端應用程式 （ciam-client-app） API 許可權，請遵循下列步驟：

1. 從 [應用程式註冊] 頁面中，選取您建立的應用程式（例如 ciam-client-app），以開啟其 [概觀] 頁面。

2. 在 [管理] 下，選取 [API 許可權]。

3. 在 [設定的許可權]下，選取 [新增許可權]。

4. 選取我組織使用的 API，然後點擊 索引標籤。

5. 在 API 清單中，選取 api，例如 ciam-ToDoList-api。

6. 選取 委派的許可權 選項。

7. 從許可權清單中，選取 [ToDoList.Read、ToDoList.ReadWrite （如有必要，請使用搜尋方塊）。

8. 按一下 新增許可權 按鈕。 此時，您已正確設定許可權。 不過，由於租用戶屬於客戶，因此取用者本身無法同意這些權限。 若要解決此問題，身為系統管理員必須代表租使用者中的所有使用者同意這些許可權：

   1. 選取 [授予 <您的租戶名稱> 的系統管理員同意]，然後選取 [是] 。

   2. 選取 [重新整理]，然後確認 授與 <您的租用戶名稱> 出現在這兩個範圍的 狀態 底下。

9. 從 [設定的許可權] 清單中，依次選取 ToDoList.Read 和 ToDoList.ReadWrite 許可權，然後複製每個許可權的完整 URI 以供日後使用。 完整許可權 URI 看起來與 api://{clientId}/{ToDoList.Read} 或 api://{clientId}/{ToDoList.ReadWrite}類似。

複製或下載範例 Web 應用程式和 Web API

若要取得範例應用程式，您可以從 GitHub 複製它，或將它下載為 .zip 檔案。

• 若要複製範例，請開啟命令提示字元並流覽至您想要建立專案的位置，然後輸入下列命令：

  git clone https://github.com/Azure-Samples/ms-identity-ciam-javascript-tutorial.git
  

• 下載 .zip 檔案。 將它解壓縮到名稱長度少於 260 個字元的檔案路徑。

安裝專案依賴

1. 開啟主控台視窗，然後變更為包含 Node.js/Express 範例應用程式的目錄：

   cd 2-Authorization\4-call-api-express\App
   

2. 執行下列命令以安裝 Web 應用程式相依性：

   npm install && npm update
   

設定範例 Web 應用程式和 API

若要在用戶端應用程式範例中使用您的應用程式註冊：

1. 在您的程式代碼編輯器中，開啟 App\authConfig.js 檔案。

2. 尋找佔位符：

   • Enter_the_Application_Id_Here，將其替換為您先前註冊的用戶端應用程式的應用程式識別碼。 您在先決條件中註冊的應用程式就是用戶端應用程式。
   • Enter_the_Tenant_Subdomain_Here，並將它取代為 Directory （tenant） 子域。 例如，如果您的租戶主要網域是 contoso.onmicrosoft.com，請使用 contoso。 如果您沒有租戶名稱，請瞭解如何 查看租戶詳細數據。
   • Enter_the_Client_Secret_Here，並將其替換為您稍早複製的應用程式秘密值。
   • Enter_the_Web_Api_Application_Id_Here 並將它取代為您稍早複製作為必要條件一部分之 Web API 的應用程式（用戶端）識別碼。

若要在 Web API 範例中使用您的應用程式註冊：

1. 在您的程式代碼編輯器中，開啟 API\ToDoListAPI\appsettings.json 檔案。

2. 尋找佔位符：

   • Enter_the_Application_Id_Here，並將它取代為您複製之 Web API 的應用程式（用戶端）識別碼。 Web API 應用程式是您先前註冊必要條件的一部分。
   • Enter_the_Tenant_Id_Here，然後將其替換為您稍早複製的目錄（租用戶）ID。
   • Enter_the_Tenant_Subdomain_Here，並將它取代為 Directory （tenant） 子域。 例如，如果您的租戶主要網域是 contoso.onmicrosoft.com，請使用 contoso。 如果您沒有租戶名稱，請瞭解如何 查看租戶詳細數據。

執行和測試範例 Web 應用程式和 API

1. 開啟主控台視窗，然後使用下列命令執行 Web API：

   cd 2-Authorization\4-call-api-express\API\ToDoListAPI
   dotnet run
   

2. 使用下列命令執行 Web 應用程式用戶端：

   cd 2-Authorization\4-call-api-express\App
   npm install
   npm start
   

3. 開啟瀏覽器，然後前往 http://localhost:3000.

4. 選取 [登入] 按鈕。 系統會提示您登入。

   

5. 在登入頁面上，輸入 電子郵件地址，選取 [下一步]，輸入 密碼，然後選取 [登入]。 如果您沒有帳戶，請選取 [沒有帳戶？建立一個 連結，以啟動註冊流程。

6. 如果您選擇註冊選項，請在填寫電子郵件、單次密碼、新密碼和更多帳戶詳細數據之後，完成整個註冊流程。 您會看到類似下列螢幕快照的頁面。 如果您選擇登入選項，您會看到類似的頁面。

   

呼叫 API

1. 若要呼叫應用程式介面，請選取 [檢視待辦事項清單] 連結。 您會看到類似下列螢幕快照的頁面。

   

2. 操控 to-do 清單，透過建立和移除項目。

運作方式

每次檢視、新增或移除工作時，都會觸發 API 呼叫。 每次觸發 API 呼叫時，用戶端 Web 應用程式都會取得具有所需許可權（範圍）的存取令牌，以呼叫 API 端點。 例如，若要讀取一個任務，客戶端網頁應用程式必須取得具有 ToDoList.Read 許可權/範疇的存取令牌。

Web API 端點必須檢查用戶端應用程式所提供的存取令牌中的許可權或範圍是否有效。 如果存取令牌有效，端點會回應 HTTP 要求，否則會以 401 Unauthorized HTTP 錯誤回應。

相關內容

• 教程：保護在外部租用戶中註冊的 ASP.NET Core Web API。