共用方式為

快速入門：在範例精靈應用程式中呼叫Web API

  • 發行項

在本快速入門中，您會使用範例精靈應用程式來取得存取令牌，並使用 Microsoft 驗證連結庫 （MSAL）呼叫受保護的 Web API。

開始之前，請使用此頁面頂端的 租用戶類型選擇器，以選擇租用戶的類型。 Microsoft Entra ID 提供兩種租用戶設定，內部員工 和 外部使用者。 工作環境租戶設定適用於員工、內部應用程式和其他組織資源。 外部租戶是針對客戶面向的應用程式。

您在本快速入門中使用的範例應用程式會取得存取令牌，以呼叫 Microsoft Graph API。

先決條件

  • 擁有有效的訂閱的 Azure 帳戶。 如果您還沒有帳戶，免費建立帳戶。
  • 此 Azure 帳戶必須具有管理應用程式的權限。 下列任何 Microsoft Entra 角色都包含必要的權限:
    • 應用程式管理員
    • 應用程式開發人員
    • 雲端應用程式管理員
  • 員工租戶。 您可以使用預設目錄或 設定新的租使用者。
  • 使用下列設定，在 Microsoft Entra 系統管理中心註冊新的應用程式。 如需詳細資訊，請參閱 註冊應用程式。
    • 名稱：identity-client-daemon-app
    • 支援的帳戶類型：僅限此組織目錄中的帳戶（單一租使用者）

建立客戶端密碼

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

  1. 從 [應用程式註冊] 頁面中，選取您建立的應用程式（例如 Web 應用程式用戶端密碼），以開啟其 概觀 頁面。
  2. 在 [管理] 底下，選取 [憑證 & 密碼>[客戶端密碼]>[新增客戶端密碼]。
  3. 在 [描述] 方塊中，輸入客戶端密碼的描述（例如，Web 應用程式用戶端密碼）。
  4. 在 [到期] 下，選取機密的有效期限（根據您的組織安全性規則），然後選取 [新增]。
  5. 記錄秘密的 值。 您可以在稍後的步驟中使用此值進行設定。 在您離開 憑證和秘密後，秘密值將不再顯示，並且無法藉由任何方式取得。 別忘了記錄下來。

當您建立機密用戶端應用程式的認證時：

  • Microsoft建議您先使用憑證，而不是客戶端密碼，再將應用程式移至生產環境。 如需如何使用憑證的詳細資訊，請參閱 Microsoft身分識別平臺應用程式驗證憑證認證中的指示，。

  • 基於測試目的，您可以建立自我簽署憑證，並將您的應用程式設定為向它進行驗證。 不過，在 生產環境中，您應該購買由知名證書頒發機構簽署的憑證，然後使用 Azure Key Vault 來管理憑證的存取和生命週期。

將 API 許可權授與精靈應用程式

若要讓精靈應用程式存取 Microsoft Graph API 中的數據，您可以授與它所需的許可權。 精靈應用程式需要應用程式類型許可權。 用戶無法與精靈應用程式互動，因此租用戶系統管理員必須同意這些許可權。 使用下列步驟來授與和同意許可權：

針對 .NET 精靈應用程式，您不需要授與並同意任何許可權。 此精靈應用程式會讀取自己的應用程式註冊資訊，因此不需要獲得任何應用程式許可權即可這麼做。

複製或下載範例應用程式

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

  • 若要複製範例，請開啟命令提示字元並流覽至您想要建立專案的位置，然後輸入下列命令：
git clone https://github.com/Azure-Samples/ms-identity-docs-code-dotnet.git
  • 下載 .zip 檔案。 將它解壓縮到名稱長度少於 260 個字元的檔案路徑。

設定專案

若要在用戶端精靈應用程式範例中使用您的應用程式註冊詳細數據，請使用下列步驟：

  1. 開啟主控台視窗，然後流覽至 ms-identity-docs-code-dotnet/console-daemon 目錄：

    cd ms-identity-docs-code-dotnet/console-daemon

  2. 開啟 Program.cs，並以下列代碼段取代檔案內容;

     // Full directory URL, in the form of https://login.microsoftonline.com/<tenant_id>
 Authority = " https://login.microsoftonline.com/Enter_the_tenant_ID_obtained_from_the_Microsoft_Entra_admin_center",
 // 'Enter the client ID obtained from the Microsoft Entra admin center
 ClientId = "Enter the client ID obtained from the Microsoft Entra admin center",
 // Client secret 'Value' (not its ID) from 'Client secrets' in the Microsoft Entra admin center
 ClientSecret = "Enter the client secret value obtained from the Mifcrosoft Entra admin center",
 // Client 'Object ID' of app registration in Microsoft Entra admin center - this value is a GUID
 ClientObjectId = "Enter the client Object ID obtained from the Microsoft Entra admin center"
    • Authority - 權威是一個 URL，指示 MSAL 可從中請求令牌的目錄。 將 從 Microsoft Entra 管理中心獲取的租戶 ID 替換為先前記錄的 目錄（租戶）識別碼 值。
    • ClientId - 應用程式的識別碼，也稱為用戶端。 以先前從已註冊應用程式概觀頁面記錄的 Application (client) ID 值取代引號中的文字。
    • ClientSecret - Microsoft Entra 系統管理中心為應用程式建立的客戶端密碼。 輸入客戶端密碼的 值。
    • ClientObjectId - 用戶端應用程式的物件識別碼。 將您稍早從已註冊應用程式概觀頁面記錄的 Object ID 值替換引號中的文字。

執行及測試應用程式

您已設定範例應用程式。 您可以繼續執行並測試它。

從主控台視窗中，執行下列命令來建置並執行應用程式：

dotnet run

成功執行應用程式之後，它會顯示類似下列代碼段的回應（為了簡潔起見而縮短）：

{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#applications/$entity",
"id": "00001111-aaaa-2222-bbbb-3333cccc4444",
"deletedDateTime": null,
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
"applicationTemplateId": null,
"disabledByMicrosoftStatus": null,
"createdDateTime": "2021-01-17T15:30:55Z",
"displayName": "identity-dotnet-console-app",
"description": null,
"groupMembershipClaims": null,
...
}

運作方式

精靈應用程式會代表自己取得令牌（而非代表使用者）。 用戶無法與精靈應用程式互動，因為它需要自己的身分識別。 這種類型的應用程式會藉由呈現其應用程式標識碼、認證（秘密或憑證）和應用程式識別碼 URI，來要求存取令牌。 精靈應用程式會使用標準 OAuth 2.0 用戶端認證授與流程 來取得存取令牌。

應用程式會從Microsoft身分識別平臺取得存取令牌。 存取令牌的範圍是 Microsoft Graph API。 然後，應用程式會使用存取令牌，從 Microsoft Graph API 要求自己的應用程式註冊詳細數據。 只要存取令牌具有正確的許可權，應用程式就可以從 Microsoft Graph API 要求任何資源。

此範例示範自動作業或 Windows 服務如何使用應用程式身分識別來執行，而不是使用者的身分識別。

相關內容

先決條件

建立客戶端密碼

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

  1. 從 [應用程式註冊] 頁面中，選取您建立的應用程式（例如 Web 應用程式用戶端密碼），以開啟其 概觀 頁面。
  2. 在 [管理] 底下，選取 [憑證 & 密碼>[客戶端密碼]>[新增客戶端密碼]。
  3. 在 [描述] 方塊中，輸入客戶端密碼的描述（例如，Web 應用程式用戶端密碼）。
  4. 在 [到期] 下，選取機密的有效期限（根據您的組織安全性規則），然後選取 [新增]。
  5. 記錄秘密的 值。 您可以在稍後的步驟中使用此值進行設定。 在您離開 憑證和秘密後，秘密值將不再顯示，並且無法藉由任何方式取得。 確保把它記下來。

當您建立機密用戶端應用程式的認證時：

  • Microsoft建議您先使用憑證，而不是客戶端密碼，再將應用程式移至生產環境。 如需如何使用憑證的詳細資訊，請參閱 Microsoft身分識別平臺應用程式驗證憑證認證中的指示，。

  • 基於測試目的，您可以建立自我簽署憑證，並將您的應用程式設定為向它進行驗證。 不過，在 生產環境中，您應該購買由知名證書頒發機構簽署的憑證，然後使用 Azure Key Vault 來管理憑證的存取和生命週期。

將 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. 選取 [重新整理]，然後確認 授與 <你的租用戶名稱> 出現在兩個許可權的 狀態 下。

設定應用程式角色

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 聲明是最簡單的方式來區分應用程式令牌與應用程式 + 使用者令牌。 例如，當令牌是僅限應用程式的令牌時，此聲明的值為 應用程式。

複製或下載範例精靈應用程式和 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

若要在用戶端應用程式範例中使用您的應用程式註冊詳細數據，請使用下列步驟：

  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 的應用程式（用戶端）識別碼。

    • Enter_the_Tenant_Id_Here，然後將其替換為您稍早複製的目錄（租用戶）標識碼。

    • Enter_the_Tenant_Subdomain_Here，並將它取代為 Directory （tenant） 子域。 例如，如果您的租用者主要網域是 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 端的範例 .NET Web API 中，API 必須確認存取令牌具有必要的許可權（應用程式許可權）。 Web API 無法接受沒有必要許可權的存取令牌。

存取數據

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

相關內容