最小 API 中的認證與授權

注意

這不是這篇文章的最新版本。關於目前版本，請參閱本文的 .NET 10 版本。

警告

不再支援此版本的 ASP.NET Core。如需詳細資訊，請參閱 .NET 和 .NET Core 支持原則。關於目前版本，請參閱本文的 .NET 10 版本。

基本 API 支援 ASP.NET Core 中提供的所有驗證和授權選項，並提供一些額外的功能來改善使用驗證的體驗。

驗證和授權的重要概念

驗證是確定使用者身分的程序。授權是用來判斷使用者是否有權存取資源的程序。驗證和授權案例在 ASP.NET Core 中共用類似的實作語意。驗證會由驗證中介軟體所使用的驗證服務 IAuthenticationService 來處理。授權是由授權中介軟體所使用的驗證服務 IAuthorizationService 來處理。

驗證服務會使用已註冊的驗證處理常式來完成驗證相關動作。例如，驗證相關的動作為驗證使用者或登出使用者。驗證配置是用來唯一識別驗證處理常式及其設定選項的名稱。驗證處理常式負責執行驗證策略，在特定的驗證方式下，例如 OAuth 或 OIDC，生成使用者的聲明。設定選項也是策略特有的選項，並為處理常式提供會影響驗證行為的設定，例如重新導向 URI。

有兩種策略可用來判斷對授權層中資源的使用者存取權：

角色型策略會根據使用者獲指派的角色來判斷其存取權，例如 Administrator 或 User。如需角色型授權的詳細資訊，請參閱角色型授權文件。
宣告式策略會根據中央授權單位發出的宣告來判斷使用者的存取權。如需宣告型授權的詳細資訊，請參閱宣告型授權文件。

在 ASP.NET Core 中，這兩個策略都會擷取到授權需求中。授權服務會利用授權處理常式來判斷特定使用者是否符合套用至資源的授權需求。

在基本應用程式中啟用驗證

若要啟用驗證，請呼叫 AddAuthentication 以在應用程式的服務提供者上註冊必要的驗證服務。

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication();
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

一般而言，會使用特定的驗證策略。在下列範例中，應用程式已設定為支援 JWT 持有人型驗證。此範例會使用 Microsoft.AspNetCore.Authentication.JwtBearer NuGet 套件中可用的 API。

var builder = WebApplication.CreateBuilder(args);
// Requires Microsoft.AspNetCore.Authentication.JwtBearer
builder.Services.AddAuthentication().AddJwtBearer();
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

依預設，如果已啟用特定驗證和授權服務，則 WebApplication 會自動註冊驗證和授權中介軟體。在下列範例中，不需要叫用 UseAuthentication 或 UseAuthorization 來註冊中介軟體，因為 WebApplication 會在呼叫 AddAuthentication 或 AddAuthorization 之後自動執行此動作。

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization();
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

在某些情況下，例如控制中介軟體順序，必須明確註冊驗證和授權。在下列範例中，驗證中介軟體會在 CORS 中介軟體執行之後。如需中介軟體和此自動行為的詳細資訊，請參閱基本 API 應用程式中的中介軟體。

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCors();
builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization();

var app = builder.Build();

app.UseCors();
app.UseAuthentication();
app.UseAuthorization();

app.MapGet("/", () => "Hello World!");
app.Run();

設定驗證策略

驗證策略通常支援透過選項載入的各種設定。簡約應用程式支援從設定載入選項，以供下列驗證策略使用：

預期 ASP.NET Core 架構會在 Authentication:Schemes:{SchemeName} 的 configuration 區段下找到這些選項。在下列範例中，兩個不同的配置，Bearer 和 LocalAuthIssuer，會使用其各自的選項來定義。 Authentication:DefaultScheme 選項可用來設定使用的預設驗證策略。

{
  "Authentication": {
    "DefaultScheme":  "LocalAuthIssuer",
    "Schemes": {
      "Bearer": {
        "ValidAudiences": [
          "https://localhost:7259",
          "http://localhost:5259"
        ],
        "ValidIssuer": "dotnet-user-jwts"
      },
      "LocalAuthIssuer": {
        "ValidAudiences": [
          "https://localhost:7259",
          "http://localhost:5259"
        ],
        "ValidIssuer": "local-auth"
      }
    }
  }
}

在 Program.cs 中，會註冊兩個 JWT 持有人型驗證策略，使用：

"Bearer" 配置名稱。
"LocalAuthIssuer" 方案名稱。

"Bearer" 是已啟用 JWT 持有人型應用程式的典型預設配置，但是藉由將 DefaultScheme 屬性設定為上述範例，即可覆寫預設配置。

配置名稱用來唯一識別驗證策略，並在解析設定的驗證選項時做為查閱金鑰，如下列範例所示：

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication()
  .AddJwtBearer()
  .AddJwtBearer("LocalAuthIssuer");
  
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

在基本應用程式中設定授權原則

驗證是用來識別及驗證使用者對 API 的身分識別。授權是用來驗證 API 中資源的存取權，並由 IAuthorizationService 擴充方法所註冊的 AddAuthorization 協助完成。在下列案例中，會新增需要使用者以 /hello 範圍宣告呈現 admin 角色宣告的 greetings_api 資源。

在資源上設定授權需求是需要下列項目的兩個步驟程序：

全域設定原則中的授權需求。
將個別原則套用至資源。

在下列程式碼中，會叫用 AddAuthorizationBuilder，其中：

將授權相關服務新增至 DI 容器。
傳回 AuthorizationBuilder，可用來直接註冊授權原則。

程式碼會建立名為 admin_greetings 的新授權原則，其會封裝兩個授權需求：

透過RequireRole為具有admin角色的使用者提供角色型需求。
透過 RequireClaim 的宣告型需求，使用者必須提供 greetings_api 範圍宣告。

此 admin_greetings 原則會以 /hello 端點的必要原則的形式提供。

using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthorizationBuilder()
  .AddPolicy("admin_greetings", policy =>
        policy
            .RequireRole("admin")
            .RequireClaim("scope", "greetings_api"));

var app = builder.Build();

app.MapGet("/hello", () => "Hello world!")
  .RequireAuthorization("admin_greetings");

app.Run();

使用 `dotnet user-jwts` 進行開發測試

在本文中，會使用以 JWT 持有人為基礎的驗證所設定的應用程式。 JWT 驗證要求用戶端在請求標頭中出示令牌，以驗證其身分識別和權限。一般而言，這些令牌是由中央授權單位所發行，例如身分識別伺服器。

在本機電腦上開發時，dotnet user-jwts 工具可用來建立持有人權杖。

dotnet user-jwts create

注意

在專案上叫用時，工具會自動將符合所產生權杖的驗證選項新增至 appsettings.json。

可以使用各種自訂來設定權杖。例如，若要針對上述程式碼中的授權政策所預期的 admin 角色與 greetings_api 範圍生成權杖：

dotnet user-jwts create --scope "greetings_api" --role "admin"

然後，產生的權杖可以在所選的測試工具中，作為標頭的一部分傳送。例如，使用 curl：

curl -i -H "Authorization: Bearer {token}" https://localhost:{port}/hello

如需 dotnet user-jwts 工具的詳細資訊，請閱讀完整文件。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-11-19