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

適用於：白色勾選標記符號的綠色圓圈 工作租用戶 外部租用戶（深入瞭解）

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

先決條件

• 具有有效訂閱的 Azure 帳戶。 免費建立帳戶。
• Visual Studio 2022。 免費下載 Visual Studio。

註冊 Web API 應用程式

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

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

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

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

4. 選取 新增註冊。

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

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

7. 選取 [[註冊]。

   

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

   

注意

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

公開 API

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

ASP.NET

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. 選取 新增範圍。

ASP.NET CORE

1. 在 [管理] 下，選取 [[公開 API] > [新增範圍]。 選取 [儲存並繼續]，以接受建議 應用程式識別碼 URI(api://{clientId})。 {clientId} 是從 [概觀] 頁面 記錄的值。 然後輸入下列資訊：

   1. 針對 範圍名稱，輸入 Forecast.Read。
   2. 針對 誰可以同意，請確定已選取 [系統管理員和使用者] 選項。
   3. 在 [系統管理員同意顯示名稱 方塊中，輸入 Read forecast data。
   4. 在 [系統管理員同意描述] 方塊中，輸入 Allows the application to read weather forecast data。
   5. 在 [使用者同意顯示名稱 方塊中，輸入 Read forecast data。
   6. 在 [使用者同意描述] 方塊中，輸入 Allows the application to read weather forecast data。
   7. 確定 [狀態 ] 已設定為 [啟用 ]。

2. 選取 [新增範圍]。 如果範圍已正確輸入，則會列在「公開 API」窗格中。

   

複製或下載範例應用程式

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

ASP.NET

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

• 下載為 ZIP 檔案。

提示

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

ASP.NET CORE

git clone https://github.com/Azure-Samples/ms-identity-docs-code-dotnet.git

• 下載 .zip 檔案。 將它解壓縮到名稱長度少於 260 個字元的檔案路徑。

設定範例應用程式

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

ASP.NET

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

2. 在 ClientID 和 Audience 屬性中，用您在 應用程式註冊 入口網站中註冊的應用程式的用戶端識別碼（應用程式識別元）值來取代 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 參數中。

ASP.NET CORE

1. 在您的 IDE 中，開啟專案資料夾，ms-identity-docs-code-dotnet/web-api，其中包含範例。

2. 開啟 appsettings.json 檔案，其中包含下列代碼段：

   {
     "AzureAd": {
       "Instance": "https://login.microsoftonline.com/", //For external tenants, use instance in the form of "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/"
       "TenantId": "Enter the tenant ID obtained from the Microsoft Entra admin center",
       "ClientId": "Enter the client ID obtained from the Microsoft Entra admin center",
       "Scopes": "Forecast.Read"
     },
     "Logging": {
       "LogLevel": {
         "Default": "Information",
         "Microsoft.AspNetCore": "Warning"
       }
     },
     "AllowedHosts": "*"
   }
   

   尋找以下 key：

   • ClientId - 應用程式的識別碼，也稱為用戶端。 將引號中的 value 文字替換成之前從已註冊應用程式的 概觀 頁面記錄的 應用程式（用戶端）標識碼。
   • TenantId - 註冊應用程式之租戶的識別碼。 請將引號中的 value 文字替換成先前從已註冊應用程式的 概觀 頁面中記錄的 租用戶目錄 ID 值。

執行範例應用程式

ASP.NET

啟動這兩個專案。 針對 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.com 或 hotmail.com 帳戶或公司或學校帳戶。

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

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

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

ASP.NET CORE

1. 執行下列命令以啟動應用程式：

   dotnet run
   

2. 如下列範例所示的輸出隨即出現：

   ...
   info: Microsoft.Hosting.Lifetime[14]
         Now listening on: http://localhost:{port}
   ...
   

   在 http://localhost:{port} URL 中記錄埠號碼。

3. 若要確認端點受到保護，請更新下列 cURL 命令中的基底 URL，以符合您在上一個步驟中收到的端點，然後執行 命令：

   curl -X GET https://localhost:5001/weatherforecast -ki
   

   預期的回應為 401 未經授權，其輸出類似：

   user@host:~$ curl -X GET https://localhost:5001/weatherforecast -ki
   HTTP/2 401
   date: Fri, 23 Sep 2023 23:34:24 GMT
   server: Kestrel
   www-authenticate: Bearer
   content-length: 0
   

後續步驟

ASP.NET

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

受保護的 Web API 教學課程

ASP.NET CORE

請繼續進行下一篇文章，瞭解如何使用 cURL 呼叫受保護的 Web API。

使用指南：使用 cURL 呼叫 ASP.NET Core Web API