📚 课程目录第2章身份与安全上下文

2. 身份与安全上下文

在 ASP.NET Core 中，认证的最终产物并不是一个布尔值，而是一个可被程序读取、传递和判断的“安全上下文”。这个上下文由三个核心类型层层嵌套构成：Claim 是最小的事实单元，ClaimsIdentity 是一组 Claim 的集合，ClaimsPrincipal 是一个或多个 Identity 的容器，而 HttpContext.User 则是当前请求中承载 Principal 的入口。理解它们的包含关系，是排查“为什么用户已登录却拿不到角色”“为什么 IsAuthenticated 为 true 但找不到某个声明”这类问题的前提。

一、四层对象的包含关系

一个 Claim 由三部分构成：类型（Type）、值（Value）和签发者（Issuer）。例如 new Claim(ClaimTypes.Name, "alice") 表示“签发者声明 alice 的名字是 alice”。ClaimsIdentity 持有一个 Claim 集合，并通过 AuthenticationType 是否为空来决定 IsAuthenticated 的取值——只要 AuthenticationType 非空，该 Identity 就被视为已认证。ClaimsPrincipal 可以包含多个 ClaimsIdentity，默认情况下 HttpContext.User 就是这样一个 Principal，它通常只包含一个来自认证中间件的 Identity，但在多方案认证场景下可能同时挂载多个。

需要特别注意的是：Principal 上的 IsInRole 和 HasClaim 会遍历其内部所有 Identity，而 Identity.Name 只取第一个满足条件的 Identity。这意味着当同一请求存在多个 Identity 时，角色判断可能来自第二个 Identity，而 Name 却来自第一个，二者来源不一致是常见困惑点。

二、从认证中间件到 HttpContext.User 的填充过程

当请求进入管道时，认证中间件会调用已注册的认证处理器。以 Cookie 认证为例，处理器从加密的 Cookie 中还原出 Claim 列表，构造 ClaimsIdentity，再包装成 ClaimsPrincipal，最后赋值给 HttpContext.User。如果认证失败，HttpContext.User 会被赋值为一个不含已认证 Identity 的空 Principal，此时 User.Identity.IsAuthenticated 为 false，但 User 本身不为 null。这一点在写授权逻辑时非常关键：不要用 User == null 判断是否登录，而应使用 User.Identity?.IsAuthenticated == true。

在 JWT Bearer 场景下，处理器解析令牌的 payload，把每个 JSON 字段映射为 Claim。默认情况下，sub 映射为 ClaimTypes.NameIdentifier，role 映射为 ClaimTypes.Role。如果令牌中的角色声明使用了自定义名称（如 roles 或 groups），则必须在 TokenValidationParameters 中通过 RoleClaimType 显式指定，否则 User.IsInRole("Admin") 会返回 false，即使令牌里确实带有该角色。

三、调试方法：把安全上下文“打印出来”

最直接的调试手段是在一个最小 API 或控制器动作中输出当前用户的所有声明。下面这段代码可以直接放入任意需要观察的端点：

app.MapGet("/whoami", (HttpContext ctx) =>
{
    var user = ctx.User;
    var lines = new List<string>
    {
        $"IsAuthenticated = {user.Identity?.IsAuthenticated}",
        $"AuthenticationType = {user.Identity?.AuthenticationType}",
        $"Name = {user.Identity?.Name}",
        $"IdentityCount = {user.Identities.Count()}"
    };

    foreach (var identity in user.Identities)
    {
        lines.Add($"--- Identity: {identity.AuthenticationType} ---");
        foreach (var claim in identity.Claims)
        {
            lines.Add($"{claim.Type} = {claim.Value} (Issuer: {claim.Issuer})");
        }
    }

    return Results.Text(string.Join("\n", lines));
});

访问该端点后，重点观察四件事：第一，IsAuthenticated 是否为 true；第二，AuthenticationType 是否与预期方案一致（Cookie 通常为 Cookies，JWT 通常为 Bearer）；第三，IdentityCount 是否大于 1，若大于 1 说明存在多方案认证，需要确认角色声明落在哪个 Identity 上；第四，逐条检查 Claim 的 Type 是否与代码中查询的 Type 完全一致。很多“角色失效”问题的根因就是令牌里是 role，而代码查询的是 http://schemas.microsoft.com/ws/2008/06/identity/claims/role，两者字符串不匹配。

在开发环境可以临时启用 Microsoft.AspNetCore.Authentication 的 Debug 日志级别，认证处理器会输出令牌解析、声明映射和验证失败的详细原因，比在代码里逐行断点更高效。

四、常见异常与判断依据

现象	可能原因	验证方式
User.Identity.IsAuthenticated 为 false	Cookie 过期、令牌签名校验失败、认证中间件未注册或顺序错误	查看 /whoami 输出，确认 AuthenticationType 是否为空
IsInRole 返回 false 但令牌含角色	RoleClaimType 未映射，或角色声明类型与查询类型不一致	遍历 User.Claims 找到实际 Type，再与 ClaimTypes.Role 对比
Name 为 null 但其他声明正常	NameClaimType 未指向实际存在的声明类型	检查 TokenValidationParameters.NameClaimType 或 Cookie 的 NameClaimType 设置
IdentityCount 大于 1 且角色判断异常	多方案认证下角色声明落在非首个 Identity	分别遍历每个 Identity 的 Claims，定位角色所在位置

掌握这四个对象的包含关系和填充路径后，调试认证授权问题就有了稳定的切入点：先确认 HttpContext.User 是否被正确赋值，再确认 Identity 的认证类型，最后逐条核对 Claim 的类型与值。把 /whoami 这类诊断端点作为开发期的常备工具，可以显著缩短从“用户说登录了”到“代码里到底看到了什么”之间的排查时间。