C# Academy · 课时

配置 JWT Bearer 身份验证

Q: 「配置 JWT Bearer 身份验证」这节课中我会学到什么？

在管道中接入令牌验证。 你通过在浏览器中直接运行的动手代码来练习 C# Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

在管道中接入令牌验证。

配置 JWT Bearer 身份验证 是 CoddyKit 上的免费 C# Academy 课时。这是第 2 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 C# Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 C# Academy 课程共包含 4 节课。

JWT Bearer 处理程序

ASP.NET Core 使用 Microsoft.AspNetCore.Authentication.JwtBearer 包中的JWT Bearer 认证处理程序来验证传入的 JWT。

它从 Authorization: Bearer ... 标头中读取令牌，验证令牌，然后构建一个 ClaimsPrincipal。

dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer

AddAuthentication

注册从 AddAuthentication 开始。您需要设置默认方案，这样框架就知道在未指定方案时应使用哪个处理程序。

JwtBearerDefaults.AuthenticationScheme 是字符串 "Bearer"。

builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer();

AddJwtBearer 选项

AddJwtBearer 重载接受一个选项委托，您可以在其中配置令牌的验证方式。

最重要的属性是 TokenValidationParameters。

builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            // configured below
        };
    });

验证颁发者和受众

设置 ValidateIssuer 和 ValidateAudience，以确保令牌来自您信任的颁发机构，并且确实是发给您的 API 的。

ValidIssuer 和 ValidAudience 必须与令牌中的 iss 和 aud 声明匹配。

var tvp = new TokenValidationParameters
{
    ValidateIssuer = true,
    ValidIssuer = builder.Configuration["Jwt:Issuer"],
    ValidateAudience = true,
    ValidAudience = builder.Configuration["Jwt:Audience"]
};

验证签名密钥

这是最关键的安全检查：使用 IssuerSigningKey 设置 ValidateIssuerSigningKey。这可以确认签名是使用您的密钥生成的。

对于对称签名（HS256），您需要根据密钥字节构建一个 SymmetricSecurityKey。

var key = new SymmetricSecurityKey(
    Encoding.UTF8.GetBytes(builder.Configuration["Jwt:Key"]!));

tvp.ValidateIssuerSigningKey = true;
tvp.IssuerSigningKey = key;

验证有效期

ValidateLifetime = true 会通过检查 exp 和 nbf 声明来拒绝已过期的令牌。

ClockSkew 用于容忍服务器之间的时钟差异。默认值为 5 分钟；对于有效期较短的令牌，应将其设置得更严格。

tvp.ValidateLifetime = true;
tvp.ClockSkew = TimeSpan.FromSeconds(30);

综合配置

完整的生产级配置会在同一个位置组合所有验证参数。

builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidIssuer = builder.Configuration["Jwt:Issuer"],
            ValidateAudience = true,
            ValidAudience = builder.Configuration["Jwt:Audience"],
            ValidateIssuerSigningKey = true,
            IssuerSigningKey = new SymmetricSecurityKey(
                Encoding.UTF8.GetBytes(builder.Configuration["Jwt:Key"]!)),
            ValidateLifetime = true,
            ClockSkew = TimeSpan.FromSeconds(30)
        };
    });

中间件顺序

仅有配置还不够。您必须将认证和授权中间件添加到管道中，而且顺序很重要。

UseAuthentication 必须位于 UseAuthorization 之前。

var app = builder.Build();

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

app.MapControllers();
app.Run();

保护端点

配置完成后，可以在端点上使用 [Authorize]（控制器）或 .RequireAuthorization()（最小 API）来要求有效令牌。

app.MapGet("/me", (ClaimsPrincipal user) =>
        new { id = user.FindFirstValue(ClaimTypes.NameIdentifier) })
   .RequireAuthorization();

使用可信颁发机构

如果令牌来自外部身份提供方（例如 Microsoft Entra ID、Auth0），请设置 Authority，而不是使用静态密钥。

之后，处理程序会自动从提供方的发现文档下载签名密钥。

.AddJwtBearer(options =>
{
    options.Authority = "https://login.myidp.com/";
    options.Audience = "my-api";
    // Keys are fetched from the OpenID configuration endpoint
});

读取验证失败信息

JWT Bearer 会引发您可以挂接的事件，以便进行日志记录或返回自定义响应，例如 OnAuthenticationFailed 和 OnChallenge。

options.Events = new JwtBearerEvents
{
    OnAuthenticationFailed = ctx =>
    {
        logger.LogWarning(ctx.Exception, "JWT validation failed");
        return Task.CompletedTask;
    }
};

快速检查

检查您对管道配置的掌握情况。

回顾

您已经配置了 JWT Bearer 认证：

AddAuthentication(...).AddJwtBearer(...) 会注册处理程序。
TokenValidationParameters 控制颁发者、受众、签名密钥和有效期检查。
UseAuthentication() 必须位于 UseAuthorization() 之前。
对于外部身份提供方，请使用 Authority。

接下来：了解如何签发您自己的令牌。

常见问题解答

「配置 JWT Bearer 身份验证」课时是免费的吗？

是的 — 「配置 JWT Bearer 身份验证」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 C# Academy 课程的其余内容，请升级到 CoddyKit PRO。 C# Academy 课程共包含 4 节课。

「配置 JWT Bearer 身份验证」这节课中我会学到什么？

在管道中接入令牌验证。你通过在浏览器中直接运行的动手代码来练习 C# Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 C# Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 C# Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 2 节课，共 4 节。

「配置 JWT Bearer 身份验证」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 C# Academy 课中编写并运行代码吗？

能。每节 C# Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 C# Academy