教學課程：使用 Microsoft 身分識別平臺建置及保護 ASP.NET Core Web API

發行項
03/05/2025

適用於：白色勾勾符號的綠色圓圈。 Workforce 租戶綠色圓圈帶白色勾勾符號。外部租戶（了解更多）

本教學課程系列示範如何使用 Microsoft 身分識別平臺來保護 ASP.NET Core Web API，以限制其僅存取授權的使用者和用戶端應用程式。您建置的 Web API 會使用委派的許可權（範圍）和應用程式許可權（應用程式角色）。

在本教學課程中，您將：

建置 ASP.NET Core Web API
設定 Web API 以使用其 Microsoft Entra 應用程式註冊詳細資訊
保護您的 Web API 端點
執行 Web API 以確保其正在接聽 HTTP 要求

先決條件

如果您尚未完成快速入門指南中的步驟：讓使用者登入範例應用程式。在快速入門中，您不需要複製並執行程式碼範例。
.NET 8.0 SDK 或更新版本。
Visual Studio Code 或其他程式碼編輯器。

建立新的 ASP.NET Core Web API 專案

若要建立基本 ASP.NET Core Web API 專案，請遵循下列步驟：

在 Visual Studio Code 或任何其他程式碼編輯器上開啟終端機，並流覽至您要建立項目的目錄。
在 .NET CLI 或任何其他命令行工具上執行下列命令。
```
dotnet new webapi -n MyProtectedApi
cd MyProtectedApi
```
當對話框詢問您是否要信任作者時，請選取 [[是]。
在對話框詢問是否要將必要的資產新增至專案時，選取 [是]。

安裝必要的套件

若要保護 ASP.NET Core Web API，您需要 Microsoft.Identity.Web 套件 - 一組 ASP.NET Core 連結庫，可簡化將驗證和授權支援新增至與Microsoft身分識別平臺整合的 Web 應用程式和 Web API。

若要安裝套件，請使用：

dotnet add package Microsoft.Identity.Web

設定應用程式註冊詳細數據

在應用程式資料夾中開啟 appsettings.json 檔案，並新增您在註冊 Web API 之後所記錄的應用程式註冊詳細數據。

{
    "AzureAd": {
        "Instance": "Enter_the_Authority_URL_Here",
        "TenantId": "Enter_the_Tenant_Id_Here",
        "ClientId": "Enter_the_Application_Id_Here",
    },
    "Logging": {...},
  "AllowedHosts": "*"
}

取代下列佔位符，如下所示：

以您的應用程式（用戶端）識別碼取代 Enter_the_Application_Id_Here。
使用您的目錄（租用戶）ID 替換 Enter_the_Tenant_Id_Here。
將 Enter_the_Authority_URL_Here 取代為您的權威 URL，如下一節所述。

應用程式的授權URL

授權單位 URL 指定了 Microsoft 驗證程式庫（MSAL）用於請求令牌的目錄。它會以不同的方式建置在員工和外部租使用者中，如下所示：

Workforce 租戶
外部租戶

//Instance for workforce tenant
Instance: "https://login.microsoftonline.com/"

//Authority URL for external tenant
Instance: "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/"

"員工租戶不支援自訂網域名稱。"

使用自訂網址（選擇性）

使用自訂網域來完整呈現驗證網址的品牌形象。從用戶的觀點來看，用戶在驗證過程中會保留在您的網域名稱上，而不是被重新導向至 ciamlogin.com 網域名稱。

請遵循下列步驟來使用自訂網域：

使用在外部租戶中為應用程式啟用自訂 URL 網域的步驟，來為您的外部租戶啟用自訂 URL 網域。
開啟 appsettings.json 檔案：
1. 將 Instance 屬性的值更新為 https://Enter_the_Custom_Domain_Here/Enter_the_Tenant_ID_Here。將 Enter_the_Custom_Domain_Here 替換為您自定義的 URL 網域，並將 Enter_the_Tenant_ID_Here 替換為您的租戶 ID。如果您沒有租戶識別碼，請瞭解如何查閱租戶詳細資料。
2. 新增 knownAuthorities 屬性，並使用值 [Enter_the_Custom_Domain_Here]。

在您修改 appsettings.json 檔案後，如果您的自定義 URL 網域是 login.contoso.com，且您的租戶 ID 是 aaaabbbb-0000-cccc-1111-dddd2222eeee，則您的檔案應該類似以下片段：

{
    "AzureAd": {
        "Instance": "https://login.contoso.com/aaaabbbb-0000-cccc-1111-dddd2222eeee",
        "TenantId": "Enter_the_Tenant_Id_Here",
        "ClientId": "Enter_the_Application_Id_Here",
        "KnownAuthorities": ["login.contoso.com"]
    },
    "Logging": {...},
  "AllowedHosts": "*"
}

新增應用程式角色和範圍

所有 API 都必須發布至少一個範圍，也稱為委派許可權，用戶端應用程式才能成功取得使用者的存取令牌。 API 也應該發佈至少一個應用程式角色，也稱為應用程式許可權，讓用戶端應用程式自行取得存取令牌，也就是說，當他們未登入使用者時。

我們會在 appsettings.json 檔案中指定這些許可權。在本教學課程中，您將「Forecast.Read」範圍下的委派和應用程式權限註冊。這表示只有使用包含「Forecast.Read」範圍之存取令牌呼叫 API 的使用者或用戶端應用程式，才獲得存取受保護端點的授權。

{
  "AzureAd": {
    "Instance": "Enter_the_Authority_URL_Here",
    "TenantId": "Enter_the_Tenant_Id_Here",
    "ClientId": "Enter_the_Application_Id_Here",
    "Scopes": {
      "Read": "Forecast.Read",
    },
    "AppPermissions": {
      "Read": ["Forecast.Read"],
    }
  },
  "Logging": {...},
  "AllowedHosts": "*"
}

在 API 中實作驗證和授權

若要設定驗證和授權，請開啟 program.cs 檔案，並取代其內容下列代碼段：

新增驗證配置

在此 API 中，我們會使用 JSON Web 令牌（JWT）持有人配置作為預設驗證機制。使用 AddAuthentication 方法來註冊 JWT 持有人方案。

// Import the required packages

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

// Configure authentication
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(options =>
    {
        builder.Configuration.Bind("AzureAd", options);
        options.TokenValidationParameters.NameClaimType = "name";
    }, options => { builder.Configuration.Bind("AzureAd", options); });

設定授權

授權會決定已驗證的使用者允許執行哪些動作。我們會定義名為 AuthZPolicy 的原則，要求呼叫 API 的用戶端具有用戶端應用程式的 Forecast.Read 角色或已登入使用者的 Forecast.Read 範圍。

builder.Services.AddAuthorization(config =>
{
config.AddPolicy("AuthZPolicy", policy =>
    policy.RequireRole("Forecast.Read"));
});

AddPolicy 方法會建立名為（AuthZPolicy）的原則，檢查使用者令牌宣告中是否存在 Forecast.Read 角色。如果令牌中缺少 roles 宣告，則會拒絕存取需要該原則的端點。

建置 HTTP 要求管線

在本教學課程中，我們會使用不含控制器的最小 API，因為重點在於保護 API。我們會藉由新增下列項目來設定 API 中間件管線：

HTTPS 重新導向：將 HTTP 要求重新導向至 HTTPS 來強制執行安全通訊。
驗證中間件：在處理要求之前驗證傳入令牌。
授權中間件：在驗證之後套用原則，確保只有授權的用戶端可以存取受保護的端點。

var app = builder.Build();

// Configure the HTTP request pipeline

app.UseHttpsRedirection();
app.UseAuthentication();
app.UseAuthorization();

定義氣象預報端點

/weatherforecast 端點會產生隨機的五天天氣預測，受到授權原則的保護。 RequireAuthorization("AuthZPolicy") 可確保只有具有 Forecast.Read 角色的用戶端才能存取它。

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
{
    var forecast =  Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
    
        summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("weatherForecast")
.RequireAuthorization("AuthZPolicy"); // Protect this endpoint with the AuthZPolicy

app.Run();

record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

我們建立的範例 Web API 中的驗證和授權流程的運作方式如下：

用戶端將帶有 JWT 的 GET 請求發送至 /weatherforecast 的 Authorization 標頭。
UseAuthentication 會根據Microsoft Entra識別符驗證令牌
UseAuthorization 檢查令牌聲明中的 Forecast.Read 角色。
如果成功，端點會傳回預測;否則，它會以 401 Unauthorized 回應（無效/沒有令牌）或 403 Forbidden（遺漏角色）。

執行您的 API

執行您的 API，以確保執行時沒有任何錯誤，請使用命令 dotnet run。如果您要即使在測試期間使用 HTTPS 通訊協定，則需要信任。NET 的開發憑證。

在終端機中輸入下列命令以啟動應用程式：
```
dotnet run
```

與下列類似的輸出應該會顯示在終端機中，這可確認應用程式正在 http://localhost:{port} 上執行並接聽要求。

Building...
info: Microsoft.Hosting.Lifetime[0]
    Now listening on: http://localhost:{port}
info: Microsoft.Hosting.Lifetime[0]
    Application started. Press Ctrl+C to shut down.
...

網頁 http://localhost:{host} 會顯示類似下圖的輸出。這是因為 API 是在未驗證的情況下呼叫。若要進行授權的呼叫，請參閱後續步驟，以取得如何存取受保護 Web API 的指引。

顯示網頁啟動時 401 錯誤的螢幕快照。

如需此 API 程式代碼的完整範例，請參閱範例檔案。

後續步驟

第 2 部分：測試受保護的 ASP.NET Core Web API

共用方式為

教學課程：使用 Microsoft 身分識別平臺建置及保護 ASP.NET Core Web API

先決條件

建立新的 ASP.NET Core Web API 專案

安裝必要的套件

設定應用程式註冊詳細數據

應用程式的授權URL

使用自訂網址（選擇性）

使用自訂網址（選擇性）

新增應用程式角色和範圍

在 API 中實作驗證和授權

新增驗證配置

設定授權

建置 HTTP 要求管線

定義氣象預報端點

執行您的 API

後續步驟

意見反應

其他資源

共用方式為

教學課程：使用 Microsoft 身分識別平臺建置及保護 ASP.NET Core Web API

先決條件

建立新的 ASP.NET Core Web API 專案

安裝必要的套件

設定應用程式註冊詳細數據

應用程式的授權URL

使用自訂網址 （選擇性）

新增應用程式角色和範圍

在 API 中實作驗證和授權

新增驗證配置

設定授權

建置 HTTP 要求管線

定義氣象預報端點

執行您的 API

後續步驟

意見反應

其他資源

使用自訂網址（選擇性）