快速入門：透過 Microsoft 身分識別平台保護 ASP.NET Core Web API

發行項
10/03/2024

本快速入門會使用 ASP.NET Core Web API 程式碼範例來示範如何限制授權帳戶的資源存取。此範例會使用與 Microsoft 驗證程式庫 (MSAL) 互動的 ASP.NET Core 身分識別來處理驗證。

必要條件

具有有效訂用帳戶的 Azure 帳戶。如果您還未擁有帳戶，請建立免費帳戶。
.NET 8.0 SDK 的最低需求
Visual Studio 2022 或 Visual Studio Code

註冊應用程式和記錄識別碼

提示

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

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

以不低於 [應用程式開發人員] 的身分登入 [Microsoft Entra 系統管理中心]。
如有多個租用戶的存取權，請使用頂端功能表中的 [設定] 圖示，從 [目錄 + 訂用帳戶] 功能表來切換至您要在其中註冊應用程式的租用戶。
瀏覽至 [身分識別] > [應用程式] > [應用程式註冊]。
選取 [新增註冊]。
輸入應用程式的 [名稱]，例如 NewWebAPI1。
在 [支援的帳戶類型] 區段中，選取 [僅限此組織目錄中的帳戶]。如需不同帳戶類型的資訊，請選取 [協助我選擇] 選項。
選取 [註冊]。
註冊完成時，將會顯示應用程式的 [概觀] 窗格。記錄 [目錄 (租用戶) 識別碼] 和 [應用程式 (用戶端) 識別碼]，以用於您的應用程式原始程式碼。

注意

您可以參考修改應用程式所支援的帳戶，以變更 [支援的帳戶類型]。

公開 API

註冊 API 之後，您可以定義 API 向用戶端應用程式公開的範圍來設定其權限。用戶端應用程式會要求權限以執行作業，方法是將存取權杖連同其要求傳遞至受保護的 Web API。只有當收到的存取權杖包含所需的範圍時，Web API 才會執行要求的作業。

在 [管理] 底下，選取 [公開 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. 請確定 [狀態] 已設為 [已啟用]。
選取 [新增範圍]。如果已正確輸入範圍，其會列在 [公開 API] 窗格中。

複製或下載應用程式範例

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

若要複製範例，請開啟命令提示字元，並瀏覽至您想要建立專案的位置，然後輸入下列命令：
```
git clone https://github.com/Azure-Samples/ms-identity-docs-code-dotnet.git
```
下載 .zip 檔案。將其擷取至名稱長度少於 260 個字元的檔案路徑。

設定 ASP.NET Core 應用程式範例

在您的整合式開發環境 (IDE) 中，開啟包含範例的專案資料夾 "ms-identity-docs-code-dotnet/web-api"。
開啟 appsettings.json 檔案，其中包含下列程式碼片段：
```
{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.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 文字取代為先前從已註冊應用程式 [概觀] 頁面記錄的 [目錄 (用戶端) 識別碼]。

執行應用程式範例

執行下列命令以啟動應用程式：
```
dotnet run
```

輸出會如下列範例所示：

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

記錄 http://localhost:{port} URL 中的連接埠號碼。

若要確認端點受到保護，請更新下列 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

後續步驟

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

操作說明：使用 cURL 呼叫 ASP.NET Core Web API

共用方式為