分享方式：

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

  • 文章

本指南會使用程式碼範例來示範如何在 Node.js Web 應用程式中新增驗證和授權。 範例應用程式會將使用者登入 Node.js Web 應用程式，然後呼叫 .NET API。 您可以使用外部租用戶詳細資料來啟用驗證和授權。 範例 Web 應用程式會使用適用於 Node 的 Microsoft 驗證程式庫 (MSAL) (英文) 來處理驗證。

在本文中，您會完成下列工作：

  • 在 Microsoft Entra 系統管理中心中註冊及設定 Web API。

  • 更新範例 Node Web 應用程式和 ASP.NET Web API，以使用您的外部租用戶詳細資料。

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

必要條件

註冊 Web API

在此步驟中，您會建立 Web 和 Web API 應用程式註冊，而且會指定 Web API 的範圍。

註冊 Web API 應用程式

  1. 至少以應用程式開發人員的身分登入 Microsoft Entra 系統管理中心。

  2. 如果您有權存取多個租用戶，請使用頂端功能表中的 [設定] 圖示 ，以從 [目錄 + 訂用帳戶] 功能表切換至您的外部租用戶。

  3. 瀏覽至 [身分識別] > [應用程式] > [應用程式註冊]。

  4. 選取 + 新增註冊。

  5. 在出現的 [註冊應用程式] 頁面 中，輸入應用程式的註冊資訊：

    1. 在 [名稱] 區段中，輸入將向應用程式使用者顯示的有意義應用程式名稱，例如 ciam-ToDoList-api。

    2. 在 [支援的帳戶類型] 底下，選取 [僅在此組織目錄中的帳戶]。

  6. 選取 [暫存器] 以建立應用程式。

  7. 註冊完成時，將會顯示應用程式的 [概觀] 窗格。 記錄 [目錄 (租用戶) 識別碼] 和 [應用程式 (用戶端) 識別碼]，以用於您的應用程式原始程式碼。

設定 API 範圍

此 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 的讀取權限，然後選取 [新增範圍] 以儲存您的變更：

    屬性 數值
    範圍名稱 ToDoList.Read
    有權同意者 僅限管理員
    管理員同意顯示名稱 使用 'TodoListApi' 讀取使用者的待辦事項清單
    管理員同意描述 允許應用程式使用 'TodoListApi' 讀取使用者的待辦事項清單。
    州/省 已啟用

  7. 再次選取 [新增範圍]，然後輸入下列值來定義對 API 的讀取和寫入權限範圍。 選取 [新增範圍] 以儲存您的變更：

    屬性 數值
    範圍名稱 ToDoList.ReadWrite
    有權同意者 僅限管理員
    管理員同意顯示名稱 使用 'TodoListApi' 讀取和寫入使用者的待辦事項清單
    管理員同意描述 允許應用程式使用 'TodoListApi' 讀取和寫入使用者的待辦事項清單
    州/省 已啟用

  8. 在 [管理] 底下，選取 [資訊清單] 以開啟 API 資訊清單編輯器。

  9. 將 accessTokenAcceptedVersion 屬性設定為 2。

  10. 選取 [儲存]。

深入了解針對 Web API 發佈權限時的最低權限準則 (部分機器翻譯)。

設定應用程式角色

API 必須為應用程式至少發佈一個應用程式角色 (也稱為應用程式權限)，用戶端應用程式才能以自身身分取得存取權杖。 應用程式權限是 API 應該在想要讓用戶端應用程式能夠以自身身分成功驗證，且不需登入使用者時發佈的權限類型。 若要發佈應用程式權限，請遵循下列步驟：

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

  2. 在 [管理] 下方，選取 [應用程式角色]。

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

    屬性 數值
    Display name ToDoList.Read.All
    允許的成員類型 應用程式
    值 ToDoList.Read.All
    描述 允許應用程式使用 'TodoListApi' 讀取每位使用者的待辦事項清單

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

    屬性 數值
    Display name ToDoList.ReadWrite.All
    允許的成員類型 應用程式
    值 ToDoList.ReadWrite.All
    描述 允許應用程式使用 'ToDoListApi' 讀取和寫入每個使用者的待辦事項清單

設定選擇性宣告

您可以使用 idtyp 選擇性宣告，協助 Web API 判斷權杖為應用程式權杖或應用程式 + 使用者權杖。 雖然您可以將 scp 和 roles 宣告組合用於相同用途，但使用 idtyp 宣告是告知應用程式權杖和應用程式 + 使用者權杖的最簡單方式。 例如，當權杖是僅限應用程式權杖時，此宣告值為 app。

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

  • 針對 [權杖類型]，選取 [存取]。
  • 從選擇性宣告清單中，選取 idtyp。

為 Web 應用程式授與 API 權限

若要為您的用戶端應用程式 (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

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

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

  2. 尋找預留位置：

    • Enter_the_Application_Id_Here 並將其取代為您稍早註冊之應用程式的應用程式 (用戶端) 識別碼。
    • Enter_the_Tenant_Subdomain_Here 並將其取代為目錄 (租用戶) 子網域。 例如，若租用戶主要網域是 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 的 [應用程式 (用戶端) 識別碼]。
    • Enter_the_Tenant_Id_Here，並將其取代為您稍早複製的目錄 (租用戶) 識別碼。
    • Enter_the_Tenant_Subdomain_Here 並將其取代為目錄 (租用戶) 子網域。 例如，若租用戶主要網域是 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 start

  3. 開啟瀏覽器，然後移至 http://localhost:3000.

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

    登入節點 Web 應用程式的螢幕擷取畫面。

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

  6. 如果您選擇註冊選項，在填寫電子郵件、一次性密碼、新密碼和更多帳戶詳細資料之後，您便能完成整個註冊流程。 您會看到類似下列螢幕擷取畫面的頁面。 如果您選擇登入選項，則會看到類似的頁面。

    登入節點 Web 應用程式並呼叫 API 的螢幕擷取畫面。

呼叫 API

  1. 若要呼叫 API，請選取 [檢視待辦事項清單] 連結。 您會看到類似下列螢幕擷取畫面的頁面。

    操作 API 待辦事項清單的螢幕擷取畫面。

  2. 透過建立和移除項目來操作待辦事項清單。

運作方式

每次檢視、新增或移除工作時，都會觸發 API 呼叫。 每次觸發 API 呼叫時，用戶端 Web 應用程式都會取得具有呼叫 API 端點之必要權限 (範圍) 的存取權杖。 例如，若要讀取工作，用戶端 Web 應用程式必須取得具有 ToDoList.Read 權限/範圍的存取權杖。

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

相關內容