共用方式為

快速入門：呼叫受 Microsoft 身分識別平台保護的 ASP.NET Web API

  • 發行項

下列快速入門使用範例程式碼，示範如何透過限制只有授權帳戶才能存取其資源來保護 ASP.NET Web API。 此範例支援個人 Microsoft 帳戶和任何 Microsoft Entra 組織中帳戶的授權。

本文也會使用 Windows Presentation Foundation (WPF) 應用程式來示範如何要求存取權杖來存取 Web API。

必要條件

複製或下載範例

範例程式碼可透過兩種方式取得：

  • 從殼層或命令列複製範例：

    git clone https://github.com/AzureADQuickStarts/AppModelv2-NativeClient-DotNet.git

  • 將其下載為 ZIP 檔案。

提示

為了避免 Windows 中路徑長度限制所造成的錯誤，建議您將封存解壓縮或將存放庫複製到磁碟機根目錄附近的目錄中。

註冊 Web API (TodoListService)

提示

根據您從中開始的入口網站，本文中的步驟可能會略有不同。

在 Azure 入口網站的 [應用程式註冊] 註冊您的 Web API。

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

  2. 如果您有多個租用戶的存取權，請使用頂端功能表中的 [設定] 圖示 ，從 [目錄 + 訂用帳戶] 功能表來切換要在其中註冊應用程式的租用戶。

  3. 瀏覽至 [身分識別]> [應用程式]> [應用程式註冊]，然後選取 [新增註冊]。

  4. 輸入應用程式的名稱，例如 AppModelv2-NativeClient-DotNet-TodoListService。 您的應用程式使用者可能會看到此名稱，而且您稍後可以加以變更。

  5. 針對 [支援的帳戶類型]，選取 [任何組織目錄中的帳戶]。

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

  7. 在應用程式 [概觀] 頁面上，尋找 [應用程式 (用戶端) 識別碼] 值，然後將其記下以供稍後使用。 您必須用此識別碼來設定此專案的 Visual Studio 組態檔 (亦即，TodoListService\appsettings.json 檔案中的 ClientId)。

  8. 在 [管理] 底下，選取 [公開 API]>[新增範圍]。 透過選取 [儲存並繼續]，接受建議的應用程式識別碼 URI (api://{clientId})，然後輸入下列資訊：

    1. 針對 [範圍名稱]，輸入 access_as_user。
    2. 針對 [誰可以同意]，確保已選取 [管理員與使用者] 選項。
    3. 在 [管理員同意顯示名稱] 方塊中輸入 Access TodoListService as a user。
    4. 在 [管理員同意描述] 方塊中輸入 Accesses the TodoListService web API as a user。
    5. 在 [使用者同意顯示名稱] 方塊中輸入 Access TodoListService as a user。
    6. 在 [使用者同意描述] 方塊中輸入 Accesses the TodoListService web API as a user。
    7. 針對 [狀態]，保持 [已啟用]。

  9. 選取新增範圍。

設定服務專案

設定服務專案來符合已註冊的 Web API。

  1. 在 Visual Studio 中開啟解決方案，然後開啟 TodoListService 專案根目錄下的 appsettings.json 檔案。

  2. 將 Enter_the_Application_Id_here 的值取代為在 ClientID 和 Audience 參數中的應用程式註冊中所註冊應用程式用戶端識別碼 (應用程式識別碼) 的值。

將新範圍新增至 app.config 檔案

若要將新範圍新增至 TodoListClient app.config 檔案，請執行下列步驟：

  1. 在 TodoListClient 專案根資料夾中，開啟 app.config 檔案。

  2. 貼上您在參數中 TodoListServiceScope 為 TodoListService 專案註冊的應用程式的應用程式識別碼，並取代 {Enter the Application ID of your TodoListService from the app registration portal} 字串。

注意

確定應用程式識別碼使用下列格式：api://{TodoListService-Application-ID}/access_as_user (其中 {TodoListService-Application-ID} 是代表 TodoListService 應用程式識別碼的 GUID)。

註冊 Web 應用程式 (TodoListClient)

在 Azure 入口網站中的應用程式註冊中註冊您的 TodoListClient 應用程式，然後設定 TodoListClient 專案中的程式碼。 如果用戶端和伺服器被視為相同的應用程式，則您可以重複使用在步驟 2 中註冊的應用程式。 如果您想要讓使用者以個人 Microsoft 帳戶登入，請使用同一個應用程式。

註冊應用程式

若要註冊 TodoListClient 應用程式，請遵循下列步驟：

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

  2. 瀏覽至 [身分識別]> [應用程式]> [應用程式註冊]，然後選取 [新增註冊]。

  3. 選取新增註冊。

  4. 當 [註冊應用程式] 頁面開啟時，輸入您應用程式的註冊資訊：

    1. 在 [名稱] 區段中，輸入將對應用程式使用者顯示、且有意義的應用程式名稱 (例如，NativeClient-DotNet-TodoListClient)。
    2. 針對 [支援的帳戶類型]，選取 [任何組織目錄中的帳戶]。
    3. 選取 [暫存器] 以建立應用程式。

    注意

    在 TodoListClient 專案 app.config 檔案中，ida:Tenant 的預設值會設定為 common。 可能的值是：

    • common：您可以使用公司或學校帳戶或個人 Microsoft 帳戶登入 (因為您在先前步驟中選取了 [任何組織目錄中的帳戶])。
    • organizations：您可以使用公司或學校帳戶登入。
    • consumers：您可以使用 Microsoft 個人帳戶登入。

  5. 在應用程式的 [概觀] 頁面上，選取 [驗證]，然後完成下列步驟以新增平台：

    1. 在 [平台設定] 下，選取 [新增平台] 按鈕。
    2. 若是行動應用程式與傳統型應用程式，請選取 [行動應用程式與傳統型應用程式]。
    3. 若是重新導向 URI，請選取 https://login.microsoftonline.com/common/oauth2/nativeclient 核取方塊。
    4. 選取設定。

  6. 選取 [API 權限]，然後完成下列步驟來新增權限：

    1. 選取 [新增權限] 按鈕。
    2. 選取 [我的 API] 索引標籤。
    3. 在 API 清單中，選取 AppModelv2-NativeClient-DotNet-TodoListService API 或您已針對 Web API 輸入的名稱。
    4. 選取 access_as_user 權限核取方塊 (如果尚未選取)。 如有需要請使用搜尋方塊。
    5. 選取 [新增權限] 按鈕。

設定專案

將應用程式識別碼新增至 app.config 檔案，以設定您的 TodoListClient 專案。

  1. 在應用程式註冊入口網站的 [概觀] 頁面上，複製 [應用程式 (用戶端) 識別碼] 的值。

  2. 從 TodoListClient 專案根資料夾中，開啟 app.config 檔案，然將應用程式識別碼值貼到 ida:ClientId 參數中。

執行您的專案

啟動兩個專案。 針對 Visual Studio 使用者；

  1. 以滑鼠右鍵按一下 Visual Studio 解決方案，然後選取 [屬性]

  2. 在 [通用屬性] 中選取 [啟始專案]，然後選取 [多個啟始專案]。

  3. 針對這兩個專案，選擇 [開始] 作為動作

  4. 使用向上箭號將 TodoListService 服務移至清單中的第一個位置，以確保其先啟動。

登入以執行您的 TodoListClient 專案。

  1. 按 F5 以啟動專案。 服務頁面和桌面應用程式會隨即開啟。

  2. 在 TodoListClient 中，選取右上方的 [登入]，然後使用您用來註冊應用程式的同一認證，或以同一目錄中的使用者來登入。

    如果您是第一次登入，系統可能會提示您同意 TodoListService Web API。

    為了協助您存取 TodoListService Web API，並操作 To-Do 清單，登入也會要求 access_as_user 範圍的存取權杖。

預先授權用戶端應用程式

您可以允許其他目錄中的使用者存取 Web API，方法是預先授權用戶端應用程式存取您的 Web API。 若要這麼做，您可以將用戶端應用程式中的應用程式識別碼新增至 Web API 的預先授權應用程式清單。 藉由新增預先授權的用戶端，您可以讓使用者存取您的 Web API，而不需要提供同意。

  1. 在應用程式註冊入口網站中，開啟 TodoListService 應用程式的屬性。
  2. 在 [公開 API] 區段中，選取 [授權的用戶端應用程式] 下的 [新增用戶端應用程式]。
  3. 在 [用戶端識別碼] 方塊中，貼上 TodoListClient 應用程式的應用程式識別碼。
  4. 在 [授權的範圍] 區段中，選取 api://<Application ID>/access_as_user Web API 的範圍。
  5. 選取新增應用程式。

執行專案

  1. 請按 F5 執行您的專案。 您的 TodoListClient 應用程式會隨即開啟。
  2. 選取右上方的 [登入]，然後使用個人 Microsoft 帳戶 (例如 live.com 或 hotmail.com 帳戶) 來登入或使用公司或學校帳戶來登入。

選用：限制特定使用者的登入存取權

根據預設，任何個人帳戶 (例如 outlook.com 或 live.com 帳戶) 或來自組織 (與 Microsoft Entra ID 整合) 的公司或學校帳戶，都可以要求權杖並存取您的 Web API。

若要指定誰可以登入您的應用程式，請變更 appsettings.json 檔案中的TenantId 屬性。

說明與支援 

如果您需要協助、想要回報問題，或想要深入了解您的支援選項，請參閱 開發人員的協助與支援。

下一步

在下列教學課程系列中，您可以建置受保護的 ASP.NET Core Web API，以深入了解：

受保護的 Web API 教學課程 (部分機器翻譯)