共用方式為

在範例 Node.js 精靈應用程式中呼叫 API

  • 發行項

本指南使用範例 Node.js 精靈應用程式，來示範精靈應用程式如何取得存取權杖以調用 Web API。

精靈應用程式可代表本身 (而不是代表使用者) 取得權杖。 使用者無法與精靈應用程式互動，因為其需要自己的身分識別。 這類應用程式會使用其應用程式識別，並向外部識別碼出示其應用程式識別碼、認證 (密碼或憑證) 和應用程式識別碼 URI，以要求存取權杖。

精靈應用程式會使用標準 OAuth 2.0 用戶端認證授與。 為了簡化取得權杖的程序，本文中使用的範例會使用適用於 Node 的 Microsoft 驗證程式庫 (MSAL Node)。

必要條件

註冊精靈應用程式及 Web API

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

註冊 Web API 應用程式

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

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

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

  4. 選取 + 新增註冊。

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

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

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

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

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

設定應用程式角色

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。

註冊精靈應用程式

若要讓您的應用程式能夠使用 Microsoft Entra 來登入使用者，必須讓 Microsoft Entra 外部 ID 知道您建立的應用程式。 應用程式註冊會在應用程式與 Microsoft Entra 之間建立信任關係。 註冊應用程式時，外部 ID 會產生稱為「應用程式 (用戶端) 識別碼」的唯一識別碼，這個值可在建立驗證要求時用來識別您的應用程式。

下列步驟顯示如何在 Microsoft Entra 系統管理中心內註冊您的應用程式：

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

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

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

  4. 選取 + 新增註冊。

  5. 在出現的 [註冊應用程式] 頁面中；

    1. 輸入要向應用程式使用者顯示的有意義應用程式「名稱」，例如 ciam-client-app。
    2. 在 [支援的帳戶類型] 底下，選取 [僅在此組織目錄中的帳戶]。

  6. 選取註冊。

  7. 應用程式的 [概觀] 窗格會在成功註冊時顯示。 記錄要在應用程式原始程式碼中使用的「應用程式 (用戶端) 識別碼」。

建立用戶端密碼

為已註冊的應用程式建立用戶端密碼。 在要求權杖時，應用程式會使用用戶端密碼來證明其身分識別。

  1. 從 [應用程式註冊] 頁面中，選取您建立的應用程式 (例如 ciam-client-app)，以開啟其 [概觀] 頁面。
  2. 在 [管理] 下，選取 [憑證和密碼]。
  3. 選取 [新用戶端密碼]。
  4. 在 [描述] 方塊中，輸入用戶端密碼的描述 (例如「ciam 應用程式用戶端密碼」)。
  5. 在 [到期] 下方，選取祕密有效的持續時間 (根據組織的安全性規則)，然後選取 [新增]。
  6. 記錄祕密的 [值]。 您將會在稍後的步驟中使用此值進行設定。 在您離開 [憑證和祕密] 之後，祕密值將不會再次顯示，而且無法透過任何方式擷取。 請確定將其妥善記錄。

將 API 權限授與精靈應用程式

  1. 從 [應用程式註冊] 頁面中，選取您建立的應用程式 (例如 ciam-client-app)。

  2. 在 [管理] 之下選取 [API 權限]。

  3. 在 [已設定的權限] 底下，選取 [新增權限]。

  4. 選取 [我的組織使用的 API] 索引標籤。

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

  6. 選取 [應用程式權限] 選項。 我們選取此選項是因為應用程式會以自身身分 (而不是使用者) 登入。

  7. 從權限清單中，選取 [TodoList.Read.All]、[ToDoList.ReadWrite.All] (如有必要，請使用搜尋方塊)。

  8. 選取 [新增權限] 按鈕。

  9. 此時，您已正確獲指派權限。 不過，因為精靈應用程式不允許使用者與其互動，所以使用者本身無法同意這些權限。 若要解決此問題，身為管理員的您必須代表租用戶中的所有使用者同意這些權限：

    1. 選取 [代表 <您的租用戶名稱> 授與管理員同意]，然後選取 [是]。
    2. 選取 [重新整理]，然後驗證 [已授與<您的租用戶名稱>] 是否顯示在這兩個權限的 [狀態] 下方。

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

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

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

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

  • 或者，下載 ZIP 檔案範例，將其解壓縮到名稱長度少於 260 個字元的檔案路徑。

安裝專案相依性

  1. 開啟主控台視窗，並變更至包含 Node.js 應用程式範例的目錄。

    cd 2-Authorization\3-call-api-node-daemon\App

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

    npm install && npm update

設定範例精靈應用程式和 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。 如果您沒有租用戶名稱，請了解如何讀取租用戶詳細資料。

執行並測試範例精靈應用程式和 API

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

    cd 2-Authorization\3-call-api-node-daemon\API\ToDoListAPI
dotnet run

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

    2-Authorization\3-call-api-node-daemon\App
node . --op getToDos

  • 若精靈應用程式和 Web API 成功執行，您應該會在主控台視窗中看到類似下列 JSON 陣列的內容

    {
    "id": 1,
    "owner": "3e8....-db63-43a2-a767-5d7db...",
    "description": "Pick up grocery"
},
{
    "id": 2,
    "owner": "c3cc....-c4ec-4531-a197-cb919ed.....",
    "description": "Finish invoice report"
},
{
    "id": 3,
    "owner": "a35e....-3b8a-4632-8c4f-ffb840d.....",
    "description": "Water plants"
}

運作方式

Node.js 應用程式會使用 OAuth 2.0 用戶端認證授與來取得自己的存取權杖，而不是為使用者取得。 應用程式要求的存取權杖包含以角色表示的權限。 用戶端認證流程會使用這組權限來取代應用程式權杖的使用者範圍。 您稍早在 Web API 中公開這些應用程式權限，然後將這些權限授與精靈應用程式。

在 API 端，Web API 必須確認存取權杖具有必要的權限 (應用程式權限)。 Web API 無法接受沒有必要權限的存取權杖。

存取資料

Web API 端點應該準備好接受來自使用者和應用程式的呼叫。 因此，其應該有一種方法可據以回應每個要求。 例如，透過委派的權限/範圍從使用者發出的呼叫會收到使用者的資料待辦事項清單。 另一方面，透過應用程式權限/角色從應用程式發出的呼叫可能會收到整個待辦事項清單。 但在本文中，我們只會進行應用程式呼叫，因此不需要設定委派的權限/範圍。

相關內容