ASP.NET Core Minimal API 认证入门到进阶：小白也能看懂的完整实战

原创

步步为营DotNet

发布于 2026-07-09 17:30:05

一、痛点引入：为什么一到 Minimal API 认证就懵？

刚学 Minimal API 时，接口都很简单：

 app.MapGet("/hello", () => "hello");

你会觉得：

路由很简单
写接口很快
没有 Controller 很清爽

但是一到认证，就开始糊涂：

为什么要 AddAuthentication()？
为什么还要 AddAuthorization()？
为什么还要 UseAuthentication()？
.RequireAuthorization() 是干嘛的？
登录成功后，用户信息放哪？
在 Minimal API 里怎么拿当前登录用户？
为什么有时返回 401，有时返回 403？
Cookie 和 JWT 在 Minimal API 中到底差别在哪里？

所以这篇文章我会严格按这个顺序来讲：

先搭一个最简单的“需要认证”的接口
再讲每一行配置在做什么
再讲 Minimal API 里怎么拿当前用户
再讲 Cookie 认证
再讲 JWT 认证
最后再讲角色、策略、路由组这些进阶用法

也就是说：

先让你看懂最小闭环，再逐步升级。

二、先建立最重要的概念：在 Minimal API 里，认证到底由哪几部分组成？

你先不要急着看 Cookie 和 JWT。先记住：Minimal API 的认证能不能跑起来，至少依赖 4 个东西。

2.1 第一个：注册认证服务

 builder.Services.AddAuthentication(...);

它的意思是：

我要启用 ASP.NET Core 的认证系统。

2.2 第二个：注册授权服务

 builder.Services.AddAuthorization();

它的意思是：

我要启用授权系统，这样接口才能要求“必须登录后才能访问”。

2.3 第三个：启用认证中间件

 app.UseAuthentication();

它的意思是：

每次请求进来时，框架尝试识别当前用户是谁。

2.4 第四个：启用授权中间件

 app.UseAuthorization();

它的意思是：

如果某个接口要求必须认证，那就在执行接口前检查用户是否已登录。

2.5 第五个：接口声明需要认证

 .RequireAuthorization()

它的意思是：

这个接口不能匿名访问，必须先通过认证。

2.6 你先把这句话背下来

在 Minimal API 中：

 AddAuthentication：注册认证系统
 AddAuthorization：注册授权系统
 UseAuthentication：请求来了先识别用户
 UseAuthorization：再判断用户能不能访问
 RequireAuthorization：声明这个接口必须登录

你后面学 Cookie、JWT，本质上都离不开这 5 个点。

三、第一步：什么都不讲，先写一个“最简单的认证案例”

这一步我们的目标只有一个：

让你亲眼看到：一个接口可以被保护起来。

为了简单，我们先不用 Cookie，也不用 JWT。我们先做一个“假认证”：

如果请求头里有 X-User
我们就把它当成登录用户
如果没有，就当成未登录

这样可以让你先理解 Minimal API 认证框架本身怎么工作的

3.1 完整可运行代码

新建一个 Program.cs，直接复制下面代码：

 using System.Security.Claims;
 using System.Text.Encodings.Web;
 using Microsoft.AspNetCore.Authentication;
 using Microsoft.Extensions.Options;
 
 var builder = WebApplication.CreateBuilder(args);
 
 // 1. 注册认证：使用我们自定义的 Simple 方案
 builder.Services
     .AddAuthentication("Simple")
     .AddScheme<AuthenticationSchemeOptions, SimpleAuthHandler>("Simple", options => { });
 
 // 2. 注册授权
 builder.Services.AddAuthorization();
 
 var app = builder.Build();
 
 // 3. 启用认证和授权中间件
 app.UseAuthentication();
 app.UseAuthorization();
 
 // 公开接口，不需要登录
 app.MapGet("/", () => "这是公开接口，任何人都能访问");
 
 // 受保护接口，需要登录
 app.MapGet("/me", (ClaimsPrincipal user) =>
 {
     return Results.Ok(new
     {
         Message = "你已登录",
         Name = user.Identity?.Name,
         IsAuthenticated = user.Identity?.IsAuthenticated
     });
 }).RequireAuthorization();
 
 app.Run();
 
 
 // 自定义认证处理器
 public class SimpleAuthHandler : AuthenticationHandler<AuthenticationSchemeOptions>
 {
     public SimpleAuthHandler(
         IOptionsMonitor<AuthenticationSchemeOptions> options,
         ILoggerFactory logger,
         UrlEncoder encoder)
         : base(options, logger, encoder)
     {
     }
 
     protected override Task<AuthenticateResult> HandleAuthenticateAsync()
     {
         // 从请求头中读取 X-User
         var userName = Request.Headers["X-User"].ToString();
 
         // 如果没有这个请求头，就表示没有认证信息
         if (string.IsNullOrWhiteSpace(userName))
         {
             return Task.FromResult(AuthenticateResult.NoResult());
         }
 
         // 构造用户声明（Claims）
         var claims = new[]
         {
             new Claim(ClaimTypes.Name, userName)
         };
 
         // 构造身份对象
         var identity = new ClaimsIdentity(claims, Scheme.Name);
 
         // 构造当前用户
         var principal = new ClaimsPrincipal(identity);
 
         // 构造认证票据
         var ticket = new AuthenticationTicket(principal, Scheme.Name);
 
         // 返回认证成功
         return Task.FromResult(AuthenticateResult.Success(ticket));
     }
 }

3.2 这个例子怎么测试？

访问公开接口

请求：

 GET /

响应：

 这是公开接口，任何人都能访问

不带请求头访问受保护接口

请求：

 GET /me

响应：

 401 Unauthorized

带请求头访问受保护接口

请求：

 GET /me
 X-User: alice

响应：

 {
   "message": "你已登录",
   "name": "alice",
   "isAuthenticated": true
 }

四、第一段代码详细拆解：每一行到底在干什么？

这一段非常重要。你如果把这一节看懂了，后面 Cookie 和 JWT 会轻松很多。

4.1 `AddAuthentication("Simple")`

 builder.Services.AddAuthentication("Simple")

意思是：

注册认证系统，并告诉框架默认使用名为 Simple 的认证方案。

你可以把“认证方案”理解为：

框架识别用户的一套规则

比如：

Cookie 方案：从 Cookie 里识别用户
JWT 方案：从 Bearer Token 里识别用户
我们这里的 Simple 方案：从请求头 X-User 里识别用户

4.2 `.AddScheme<AuthenticationSchemeOptions, SimpleAuthHandler>()`

 .AddScheme<AuthenticationSchemeOptions, SimpleAuthHandler>("Simple", options => { });

这句的意思是：

注册一个名为 Simple 的认证方案，它的具体处理逻辑由 SimpleAuthHandler 来完成。

你可以理解成：

AddAuthentication("Simple")：告诉框架默认用哪个方案
AddScheme(..., "Simple", ...)：把这个方案真正定义出来

4.3 `AddAuthorization()`

 builder.Services.AddAuthorization();

这句的作用是：

开启授权系统，否则 .RequireAuthorization() 不会按预期工作。

很多小白的误区是：

以为“认证”和“授权”是一个东西

其实不是。

认证：识别你是谁
授权：判断你能不能访问

所以你想让接口“必须登录”，不仅要有认证，还要有授权。

4.4 `app.UseAuthentication()`

 app.UseAuthentication();

作用：

在每个请求执行时，先调用认证系统，尝试识别当前用户。

也就是说，请求到了以后，框架会去执行你的 SimpleAuthHandler。

4.5 `app.UseAuthorization()`

 app.UseAuthorization();

作用：

如果某个接口标记了必须认证，那就在执行接口之前检查当前用户是否通过了认证。

4.6 `.RequireAuthorization()`

 app.MapGet("/me", ...).RequireAuthorization();

作用：

这个接口不能匿名访问，必须登录后才能访问。

注意，这一句不是“执行认证”，而是“声明要求”。

真正的认证动作，是 UseAuthentication() 在请求管道里做的。

五、你必须真正看懂的重点：Minimal API 是怎么把用户传进来的？

你看到这段代码：

 app.MapGet("/me", (ClaimsPrincipal user) =>
 {
     return user.Identity?.Name;
 }).RequireAuthorization();

可能会问：

为什么这里我直接写一个 ClaimsPrincipal user，框架就知道把当前用户传进来？

这是 Minimal API 的一个重要特性：

参数绑定

框架会自动识别你的委托参数类型，如果它发现参数是 ClaimsPrincipal，就会把当前请求的：

 HttpContext.User

注入进来。

所以：

 (ClaimsPrincipal user)

本质上就是：

 (HttpContext context) => context.User

的简化写法。

5.1 你也可以直接拿 `HttpContext`

比如：

 app.MapGet("/me2", (HttpContext context) =>
 {
     var user = context.User;
 
     return Results.Ok(new
     {
         Name = user.Identity?.Name,
         IsAuthenticated = user.Identity?.IsAuthenticated
     });
 }).RequireAuthorization();

这两种写法都可以。

对于小白来说，我建议一开始优先用：

 (ClaimsPrincipal user)

更直观。

六、第二步：学习最简单的真实认证方式 —— Cookie 认证

现在我们已经知道 Minimal API 的认证骨架了。接下来开始学习真实项目里最常见的第一种认证方式：

Cookie Authentication

它特别适合：

后台管理系统
企业内部系统
浏览器访问的系统

因为浏览器会自动带 Cookie。

6.1 先理解这次升级了什么

刚刚我们的 Simple 方案只是“演示框架怎么工作”。

现在换成 Cookie 后，变化是：

登录成功后，服务器会给浏览器写一个认证 Cookie
浏览器下次请求时自动带上
框架自动从 Cookie 中恢复用户身份
你就不用手动传 X-User 了

6.2 最简单的 Cookie 认证完整代码

 using System.Security.Claims;
 using Microsoft.AspNetCore.Authentication.Cookies;
 
 var builder = WebApplication.CreateBuilder(args);
 
 // 1. 注册 Cookie 认证
 builder.Services
     .AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
     .AddCookie(options =>
     {
         // 设置 Cookie 名称
         options.Cookie.Name = "demo.auth";
 
         // 对 API 项目来说，未登录时不要跳转页面，直接返回 401
         options.Events.OnRedirectToLogin = context =>
         {
             context.Response.StatusCode = StatusCodes.Status401Unauthorized;
             return Task.CompletedTask;
         };
 
         // 没权限时返回 403
         options.Events.OnRedirectToAccessDenied = context =>
         {
             context.Response.StatusCode = StatusCodes.Status403Forbidden;
             return Task.CompletedTask;
         };
     });
 
 // 2. 注册授权
 builder.Services.AddAuthorization();
 
 var app = builder.Build();
 
 // 3. 启用认证和授权中间件
 app.UseAuthentication();
 app.UseAuthorization();
 
 // 公开接口
 app.MapGet("/", () => "公开接口");
 
 // 登录接口
 app.MapPost("/login", async (HttpContext context) =>
 {
     // 这里为了演示，假设登录成功
     var claims = new List<Claim>
     {
         new Claim(ClaimTypes.Name, "alice"),
         new Claim(ClaimTypes.NameIdentifier, "1001")
     };
 
     var identity = new ClaimsIdentity(
         claims,
         CookieAuthenticationDefaults.AuthenticationScheme);
 
     var principal = new ClaimsPrincipal(identity);
 
     // 写入认证 Cookie
     await context.SignInAsync(
         CookieAuthenticationDefaults.AuthenticationScheme,
         principal);
 
     return Results.Ok("登录成功");
 });
 
 // 当前用户接口
 app.MapGet("/me", (ClaimsPrincipal user) =>
 {
     return Results.Ok(new
     {
         Name = user.Identity?.Name,
         UserId = user.FindFirst(ClaimTypes.NameIdentifier)?.Value,
         IsAuthenticated = user.Identity?.IsAuthenticated
     });
 }).RequireAuthorization();
 
 // 退出登录
 app.MapPost("/logout", async (HttpContext context) =>
 {
     await context.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);
     return Results.Ok("退出成功");
 }).RequireAuthorization();
 
 app.Run();

6.3 这个 Cookie 版本怎么测试？

第一步：先访问 `/me`

因为还没登录，所以返回：

 401 Unauthorized

第二步：调用 `/login`

 POST /login

服务器会返回成功，并在响应头里写入认证 Cookie。

第三步：再访问 `/me`

如果浏览器自动带上 Cookie，就能拿到：

 {
   "name": "alice",
   "userId": "1001",
   "isAuthenticated": true
 }

第四步：调用 `/logout`

 POST /logout

退出后再访问 /me，又会变成 401。

七、Cookie 认证代码逐步拆解

7.1 `AddCookie(...)` 是注册 Cookie 认证方案

 builder.Services
     .AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
     .AddCookie(...)

它的意思是：

默认认证方式是 Cookie，并使用 ASP.NET Core 内置的 Cookie 处理器。

7.2 `SignInAsync(...)` 是登录的关键

 await context.SignInAsync(
     CookieAuthenticationDefaults.AuthenticationScheme,
     principal);

这句非常关键。

它不是简单写一个字符串 Cookie，而是：

把你的 ClaimsPrincipal 作为当前登录用户
由 Cookie 认证方案把它序列化成认证票据
写入浏览器 Cookie

后续请求时，框架再把这个 Cookie 解出来，还原成用户对象。

7.3 `SignOutAsync(...)` 是退出登录的关键

 await context.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);

作用：

删除或失效当前认证 Cookie。

7.4 Minimal API 中读取当前用户 Claim

比如读取用户 ID：

 var userId = user.FindFirst(ClaimTypes.NameIdentifier)?.Value;

比如读取用户名：

 var userName = user.Identity?.Name;

八、第三步：从 Cookie 进阶到 JWT 认证

如果你的项目不是浏览器后台，而是：

前后端分离
Vue / React 调 API
App / 小程序调 API

那么更常用的是：

JWT Bearer 认证

8.1 先说这一步和 Cookie 的最大区别

Cookie 模式

登录成功后，服务器写 Cookie，浏览器自动带上。

JWT 模式

登录成功后，服务器返回一个 Token，客户端自己保存，以后每次手动放到请求头里。

也就是说：

Cookie：浏览器自动带凭证
JWT：客户端主动带凭证

8.2 安装 JWT 包

 dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer

8.3 最简单可运行的 JWT 认证代码

 using System.IdentityModel.Tokens.Jwt;
 using System.Security.Claims;
 using System.Text;
 using Microsoft.AspNetCore.Authentication.JwtBearer;
 using Microsoft.IdentityModel.Tokens;
 
 var builder = WebApplication.CreateBuilder(args);
 
 var issuer = "demo-api";
 var audience = "demo-client";
 var secretKey = "this_is_a_demo_secret_key_1234567890";
 
 // 1. 注册 JWT 认证
 builder.Services
     .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
     .AddJwtBearer(options =>
     {
         options.TokenValidationParameters = new TokenValidationParameters
         {
             ValidateIssuer = true,
             ValidIssuer = issuer,
 
             ValidateAudience = true,
             ValidAudience = audience,
 
             ValidateIssuerSigningKey = true,
             IssuerSigningKey = new SymmetricSecurityKey(
                 Encoding.UTF8.GetBytes(secretKey)),
 
             ValidateLifetime = true,
             ClockSkew = TimeSpan.Zero
         };
     });
 
 // 2. 注册授权
 builder.Services.AddAuthorization();
 
 var app = builder.Build();
 
 // 3. 启用认证和授权
 app.UseAuthentication();
 app.UseAuthorization();
 
 // 公开接口
 app.MapGet("/", () => "公开接口");
 
 // 登录接口：生成 JWT
 app.MapPost("/login", () =>
 {
     var claims = new List<Claim>
     {
         new Claim(ClaimTypes.Name, "alice"),
         new Claim(ClaimTypes.NameIdentifier, "1001")
     };
 
     var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(secretKey));
     var credentials = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);
 
     var token = new JwtSecurityToken(
         issuer: issuer,
         audience: audience,
         claims: claims,
         expires: DateTime.UtcNow.AddMinutes(30),
         signingCredentials: credentials);
 
     var jwt = new JwtSecurityTokenHandler().WriteToken(token);
 
     return Results.Ok(new
     {
         access_token = jwt
     });
 });
 
 // 受保护接口
 app.MapGet("/me", (ClaimsPrincipal user) =>
 {
     return Results.Ok(new
     {
         Name = user.Identity?.Name,
         UserId = user.FindFirst(ClaimTypes.NameIdentifier)?.Value,
         IsAuthenticated = user.Identity?.IsAuthenticated
     });
 }).RequireAuthorization();
 
 app.Run();

8.4 JWT 版本怎么测试？

第一步：调用登录接口

 POST /login

 {
   "access_token": "eyJhbGciOi..."
 }

第二步：访问 `/me` 时带上 Token

请求头：

 Authorization: Bearer eyJhbGciOi...

 {
   "name": "alice",
   "userId": "1001",
   "isAuthenticated": true
 }

如果不带 Token，就返回 401。

九、你现在要真正理解：Cookie 写法和 JWT 写法，Minimal API 中到底差在哪？

这是很多小白很容易混的地方。

9.1 相同点

两者在 Minimal API 中的框架用法其实很像：

都需要：

 builder.Services.AddAuthentication(...)
 builder.Services.AddAuthorization()
 
 app.UseAuthentication()
 app.UseAuthorization()
 
 app.MapGet(...).RequireAuthorization()

也都可以这样拿用户：

 (ClaimsPrincipal user)

9.2 不同点

Cookie 登录时

你要调用：

 await context.SignInAsync(...)

让服务器把认证状态写到 Cookie。

JWT 登录时

你要自己生成 Token：

 new JwtSecurityToken(...)

再把它返回给客户端。

9.3 一句话理解

 Cookie：服务器发 Cookie，浏览器自动带
 JWT：服务器发 Token，客户端手动带

十、第四步：在 Minimal API 中做“角色控制”

现在我们已经会了基本认证。接下来进入比“是否登录”更进一步的一步：

不是所有登录用户都能访问某个接口

比如：

只有管理员能访问 /admin
普通用户不能访问

这就是角色控制。

10.1 登录时加入角色 Claim

不管 Cookie 还是 JWT，思路都一样。你只需要给用户身份加上角色 Claim：

 new Claim(ClaimTypes.Role, "admin")

例如 JWT 登录里：

 var claims = new List<Claim>
 {
     new Claim(ClaimTypes.Name, "alice"),
     new Claim(ClaimTypes.NameIdentifier, "1001"),
     new Claim(ClaimTypes.Role, "admin")
 };

10.2 在 Minimal API 中限制角色访问

 app.MapGet("/admin", (ClaimsPrincipal user) =>
 {
     return Results.Ok(new
     {
         Message = "欢迎管理员",
         Name = user.Identity?.Name
     });
 }).RequireAuthorization(policy => policy.RequireRole("admin"));

如果当前用户没有 admin 角色，就会返回：

 403 Forbidden

注意：

未登录：401
已登录但没权限：403

十一、第五步：在 Minimal API 中做 Policy 策略授权

当项目变大以后，你不能每个接口都写一遍：

 .RequireAuthorization(policy => policy.RequireRole("admin"))

这会很乱。

更好的方式是定义 Policy。

11.1 注册策略

 builder.Services.AddAuthorization(options =>
 {
     options.AddPolicy("AdminOnly", policy =>
     {
         policy.RequireRole("admin");
     });
 });

11.2 使用策略

 app.MapGet("/admin2", () => "只有管理员能访问")
    .RequireAuthorization("AdminOnly");

这样代码更清晰。

十二、第六步：在 Minimal API 中给一组接口统一加认证

这是 Minimal API 非常有代表性的用法：

用 MapGroup() 对一组接口统一做认证控制

12.1 最简单示例

 var userGroup = app.MapGroup("/user")
     .RequireAuthorization();
 
 userGroup.MapGet("/me", (ClaimsPrincipal user) =>
 {
     return Results.Ok(new
     {
         Name = user.Identity?.Name
     });
 });
 
 userGroup.MapGet("/settings", () => "用户设置");

这样：

/user/me
/user/settings

都会要求登录。

12.2 管理员组

 var adminGroup = app.MapGroup("/admin")
     .RequireAuthorization("AdminOnly");
 
 adminGroup.MapGet("/dashboard", () => "管理员仪表盘");
 adminGroup.MapGet("/users", () => "用户列表");

这比每个接口单独写要整洁很多。

十三、常见坑：小白最容易踩的地方

这一节我专门按“最容易错”的点来讲。

13.1 忘了 `UseAuthentication()`

你就算写了：

 builder.Services.AddAuthentication(...)

如果没有：

 app.UseAuthentication();

用户身份也不会自动识别出来。

13.2 `UseAuthentication()` 和 `UseAuthorization()` 顺序写反

必须这样：

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

不能反。

因为必须先识别用户，再判断权限。

13.3 以为加了认证服务，接口就自动必须登录

不是的。

你还要显式声明：

 .RequireAuthorization()

否则接口默认还是可以匿名访问。

13.4 把 401 和 403 搞混

记住：

401

没登录，或者凭证无效

403

已经登录，但没有权限

13.5 Cookie API 默认会跳转页面

如果你用 Cookie 认证，但不改默认行为，未登录时可能返回 302 跳转，而不是 401。

所以 API 场景一般都要加：

 options.Events.OnRedirectToLogin = context =>
 {
     context.Response.StatusCode = 401;
     return Task.CompletedTask;
 };

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

.net

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

.net