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

  • 發行項

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

本文也會使用 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. 以至少雲端應用程式 管理員 istrator 身分登入 Microsoft Entra 系統管理中心。

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

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

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

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

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

  7. 在應用程式 [概觀] 頁面上，尋找 [應用程式] [用戶端] 識別符 值，然後記錄它以供稍後使用。 您將需要它來設定此專案的Visual Studio組態檔（也就是 ClientId在TodoListService\appsettings.json 檔案中）。

  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. 將您為 TodoListService 專案註冊的應用程式識別碼貼到 參數中 TodoListServiceScope ，並 {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. 以至少雲端應用程式 管理員 istrator 身分登入 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. 在 [ 授權的範圍 ] 區段中，選取 Web API 的範圍 api://<Application ID>/access_as_user 。
  5. 選取新增應用程式。

執行您的專案

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

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

根據預設，任何個人帳戶，例如 outlook.com 或 live.com 帳戶，或與 Microsoft Entra ID 整合的組織的工作或學校帳戶，都可以要求令牌並存取您的 Web API。

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

說明與支援 

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

下一步

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

受保護的 Web API 教學課程