快速入門:呼叫受Microsoft身分識別平台保護的Web API
適用於:白色勾選標記符號的綠色圓圈 工作租用戶
外部租用戶(深入瞭解)
在本快速入門中,您會使用範例 Web 應用程式來示範如何使用 Microsoft 身分識別平台來保護 ASP.NET Web API。 此範例會使用 Microsoft 驗證連結庫 (MSAL) 來處理驗證。
先決條件
- 具有有效訂閱的 Azure 帳戶。 免費建立帳戶。
- Visual Studio 2022。 免費下載 Visual Studio。
註冊 Web API 應用程式
若要完成註冊,請提供應用程式名稱,並指定支援的帳戶類型。 註冊之後,應用程式 概觀 頁面會顯示應用程式原始碼中所需的標識碼。
以至少 應用程式開發人員身分登入 Microsoft Entra 系統管理中心。
如果您有多個租使用者的存取權,請使用頂端功能表中的 [設定] 圖示
,切換至您想要從 [目錄 + 訂用帳戶] 功能表註冊應用程式的租使用者。
瀏覽至 身分識別>應用程式>應用程式註冊。
選取 新增註冊。
輸入應用程式的 名稱,例如 NewWebAPI1。
針對 支援的帳戶類型,請選取 僅限此組織目錄中的帳戶。 如需不同帳戶類型的資訊,請選取 [[協助我選擇] 選項。
選取 [[註冊]。
在註冊完成時,會顯示應用程式的 概觀 窗格。 記錄 目錄(租使用者)標識碼 和 應用程式(用戶端)標識碼,以用於您的應用程式原始程式碼。
注意
支援的帳戶類型 可以藉由參閱 修改應用程式所支援的帳戶來變更。
公開 API
註冊 API 之後,您可以定義 API 公開給用戶端應用程式的範圍來設定其許可權。 用戶端應用程式會藉由將存取令牌及其要求傳遞至受保護的 Web API,來要求執行作業的許可權。 只有當收到的存取令牌包含所需的範圍時,Web API 才會執行要求的作業。
在 [管理] 下,選取 [[公開 API>[新增範圍]。 選取 [儲存後繼續],然後輸入下列資訊,以接受建議的應用程式識別碼 URI (
api://{clientId}
) :- 針對 範圍名稱,輸入
access_as_user
。 - 針對 誰可以同意,請確定已選取 [系統管理員和使用者] 選項。
- 在 [系統管理員同意顯示名稱 方塊中,輸入
Access TodoListService as a user
。 - 在 [系統管理員同意描述] 方塊中,輸入
Accesses the TodoListService web API as a user
。 - 在 [使用者同意顯示名稱 方塊中,輸入
Access TodoListService as a user
。 - 在 [使用者同意描述] 方塊中,輸入
Accesses the TodoListService web API as a user
。 - 針對 狀態,請保持 啟用。
- 針對 範圍名稱,輸入
選取 新增範圍。
複製或下載範例應用程式
若要取得範例應用程式,您可以從 GitHub 複製它,或將它下載為 .zip 檔案。
git clone https://github.com/AzureADQuickStarts/AppModelv2-NativeClient-DotNet.git
提示
若要避免 Windows 中路徑長度限制所造成的錯誤,建議您將封存盤或複製存放庫擷取到磁碟驅動器根附近的目錄。
設定範例應用程式
設定程式代碼範例以符合已註冊的 Web API。
在 Visual Studio 中開啟方案,然後在 TodoListService 專案的根目錄下開啟 appsettings.json 檔案。
在
ClientID
和Audience
屬性中,用您在 應用程式註冊 入口網站中註冊的應用程式的用戶端識別碼(應用程式識別元)值來取代Enter_the_Application_Id_here
的值。
將新範圍新增至 app.config 檔案
若要將新的範圍新增至 TodoListClient app.config 檔案,請遵循下列步驟:
在 TodoListClient 專案根資料夾中,開啟 app.config 檔案。
在
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 應用程式,請遵循下列步驟:
以至少 雲端應用程式管理員身分登入 Microsoft Entra 系統管理中心。
瀏覽至 [身分識別>應用程式>應用程式註冊],然後選取 [[新增註冊]。
選取 新增註冊。
當 [註冊應用程式] 頁面 開啟時,請輸入應用程式的註冊資訊:
- 在 [名稱] 區段中,輸入要向用戶顯示有意義的應用程式名稱(例如,NativeClient-DotNet-TodoListClient)。
- 針對 支援的帳戶類型,請選取任何組織目錄中的 帳戶。
- 選取 註冊 來建立應用程式。
注意
在 TodoListClient 項目 app.config 檔案中,
ida:Tenant
的預設值會設定為common
。 可能的值為:-
common
:您可以使用公司或學校帳戶或個人Microsoft帳戶登入(因為您在上一個步驟中選取了任何組織目錄中 帳戶)。 -
organizations
:您可以使用公司或學校帳戶登入。 -
consumers
:您只能使用Microsoft個人帳戶登入。
在應用程式 [概觀] 頁面上,選取 [驗證],然後完成下列步驟以新增平臺:
- 在 [平臺組態]下,選取 [[新增平臺] 按鈕。
- 針對 行動裝置和傳統型應用程式,選取 [行動裝置和傳統型應用程式]。
- 針對 [重新導向 URI],選取 [
https://login.microsoftonline.com/common/oauth2/nativeclient
] 複選框。 - 選取 [設定]。
選取 API 許可權,然後完成下列步驟以新增權限:
- 選取「新增許可權」 按鈕。
- 選取 [我的 API] 索引標籤。
- 在 API 清單中,選取 [AppModelv2-NativeClient-DotNet-TodoListService API 或您為 Web API 輸入的名稱。
- 請選取 [access_as_user 許可權] 複選框(如果尚未選取)。 如有必要,請使用 [搜尋] 方塊。
- 請選取 [新增許可權] 按鈕。
設定您的專案
將應用程式識別碼新增至 app.config 檔案,以設定 TodoListClient 專案。
在 應用程式註冊 入口網站的 [ 概觀] 頁面上,複製 [應用程式(客戶)識別碼]的值。
從 TodoListClient 專案根資料夾,開啟 app.config 檔案,然後將 [應用程式識別符] 值貼到
ida:ClientId
參數中。
執行範例應用程式
啟動這兩個專案。 針對 Visual Studio 使用者;
以滑鼠右鍵點擊 Visual Studio 解決方案,然後選取 [屬性]
在 [通用屬性] 選取 [啟動專案],然後 [多個啟動專案]。
針對這兩個專案,請選擇 開始 作為動作。
使用向上箭號,確保 TodoListService 服務會先啟動,方法是將它移至清單中的第一個位置。
登入以執行 TodoListClient 專案。
按 F5 以啟動專案。 服務頁面和桌面應用程式同步開啟。
在 TodoListClient 的右上方,選取 [登入],然後使用您用來註冊應用程式的相同認證登入,或以相同目錄中的使用者身分登入。
如果您第一次登入,系統可能會提示您同意 TodoListService Web API。
為了協助您存取 TodoListService 網站 API 並操作 To-Do 清單,登入時也會要求 access_as_user 範圍的存取權杖。
預先授權客戶端應用程式
您可以預先授權用戶端應用程式存取 Web API,以允許來自其他目錄的使用者存取您的 Web API。 若要這樣做,請從用戶端應用程式將應用程式標識元新增至 Web API 預先授權的應用程式清單。 藉由新增預先授權的用戶端,您可以讓使用者存取您的 Web API,而不需要提供同意。
- 在 應用程式註冊 入口網站中,開啟 TodoListService 應用程式的屬性。
- 在 [公開 API] 區段中的 [授權應用程式] 下,選取 [新增用戶端應用程式]。
- 在 [用戶端標識符] 方塊中,貼上 TodoListClient 應用程式的應用程式識別符。
- 在 [授權範圍] 區段中,選取
api://<Application ID>/access_as_user
Web API 的範圍。 - 選擇 新增應用程式。
執行您的專案
- 按 F5 以執行您的專案。 您的 TodoListClient 應用程式隨即開啟。
- 在右上方,選取 [登入],然後使用個人Microsoft帳戶登入,例如 live.com 或 hotmail.com 帳戶或公司或學校帳戶。
選擇性:限制特定使用者的登入存取
根據預設,任何個人帳戶,例如 outlook.com 或 live.com 帳戶,或是與 Microsoft Entra ID 整合的組織的工作或學校帳戶,都可以要求令牌並存取您的 Web API。
若要指定誰可以登入您的應用程式,請變更 appsettings.json 檔案中的 TenantId
屬性。
後續步驟
在下列教學課程系列中建置受保護的 ASP.NET Core Web API,以深入瞭解: