共用方式為


快速入門:呼叫受Microsoft身分識別平台保護的Web API

適用於:白色勾選標記符號的綠色圓圈 。 工作租用戶 灰色X符號的白色圓圈 外部租用戶(深入瞭解

在本快速入門中,您會使用範例 Web 應用程式來示範如何使用 Microsoft 身分識別平台來保護 ASP.NET Web API。 此範例會使用 Microsoft 驗證連結庫 (MSAL) 來處理驗證。

先決條件

註冊 Web API 應用程式

若要完成註冊,請提供應用程式名稱,並指定支援的帳戶類型。 註冊之後,應用程式 概觀 頁面會顯示應用程式原始碼中所需的標識碼。

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

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

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

  4. 選取 新增註冊

  5. 輸入應用程式的 名稱,例如 NewWebAPI1

  6. 針對 支援的帳戶類型,請選取 僅限此組織目錄中的帳戶。 如需不同帳戶類型的資訊,請選取 [[協助我選擇] 選項。

  7. 選取 [[註冊]。

    顯示如何輸入名稱並選取帳戶類型的螢幕快照。

  8. 在註冊完成時,會顯示應用程式的 概觀 窗格。 記錄 目錄(租使用者)標識碼應用程式(用戶端)標識碼,以用於您的應用程式原始程式碼。

    顯示概觀頁面上標識碼值的螢幕快照。

注意

支援的帳戶類型 可以藉由參閱 修改應用程式所支援的帳戶來變更。

公開 API

註冊 API 之後,您可以定義 API 公開給用戶端應用程式的範圍來設定其許可權。 用戶端應用程式會藉由將存取令牌及其要求傳遞至受保護的 Web API,來要求執行作業的許可權。 只有當收到的存取令牌包含所需的範圍時,Web API 才會執行要求的作業。

  1. 在 [管理] 下,選取 [[公開 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. 針對 狀態,請保持 啟用
  2. 選取 新增範圍

複製或下載範例應用程式

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

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

提示

若要避免 Windows 中路徑長度限制所造成的錯誤,建議您將封存盤或複製存放庫擷取到磁碟驅動器根附近的目錄。

設定範例應用程式

設定程式代碼範例以符合已註冊的 Web API。

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

  2. ClientIDAudience 屬性中,用您在 應用程式註冊 入口網站中註冊的應用程式的用戶端識別碼(應用程式識別元)值來取代 Enter_the_Application_Id_here 的值。

將新範圍新增至 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 網站 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.comhotmail.com 帳戶或公司或學校帳戶。

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

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

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

後續步驟

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