核心概念：JWT Bearer认证与资源服务器
在现代微服务架构中，api安全通常通过oauth 2.0和openid connect协议实现，其中json web token (jwt) 作为访问令牌的标准格式。资源服务器（resource server）是托管受保护资源的api服务，其主要职责是验证传入请求中的访问令牌，并根据令牌的有效性和权限信息决定是否授予访问。
对于从Java Spring Boot等其他平台迁移到C# .NET的开发者而言，如何以简洁高效的方式实现REST API的安全保护，尤其是作为纯资源服务器的角色，常常是一个挑战。许多教程倾向于将用户管理与API安全紧密结合，但这并非总是纯资源服务器所需的场景。本教程将展示如何在C# .NET中，通过最小化配置，实现一个专注于令牌验证的资源服务器。
配置步骤
在C# .NET（本示例基于.NET 6.0）中实现JWT Bearer认证的资源服务器，主要涉及以下三个步骤：
1. 添加认证服务
在应用程序的Program.cs文件中，需要配置认证服务，指定使用JWT Bearer认证方案。这包括设置默认的认证和挑战方案，并配置JWT Bearer选项，如受众（Audience）和OpenID Connect元数据地址。
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;
var builder = WebApplication.CreateBuilder(args);
// 添加认证服务
builder.Services.AddAuthentication(options =>
{
// 设置默认的认证方案为JwtBearer
options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
// 设置默认的挑战方案为JwtBearer
options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
}).AddJwtBearer(options =>
{
// 配置JWT Bearer选项
// Audience (受众) 是验证令牌时检查的声明之一，通常是客户端ID或资源服务器的标识符。
// 它确保令牌是为预期接收者颁发的。
options.Audience = "";
// MetadataAddress (元数据地址) 指向外部授权服务器的OpenID Connect配置发现文档。
// .NET认证中间件将从该地址自动获取公钥（JWKS URI）、颁发者（Issuer）等信息，
// 用于验证JWT令牌的签名和有效性。
options.MetadataAddress = "https://api.asgardeo.io/t//oauth2/token/.well-known/openid-configuration";
// 如果需要更精细的控制，例如自定义令牌验证参数，可以在这里进一步配置TokenValidationParameters。
// options.TokenValidationParameters = new TokenValidationParameters
// {
// ValidateIssuer = true,
// ValidIssuer = "https://api.asgardeo.io/t//oauth2/token",
// ValidateAudience = true,
// ValidAudience = "",
// ValidateLifetime = true,
// ClockSkew = TimeSpan.Zero // 允许的时间偏移量，建议设置为零或较小值
// };
});
// 其他服务注册，例如添加控制器
builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
var app = builder.Build();
// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}
app.UseHttpsRedirection(); 请将
2. 配置认证与授权中间件
在请求处理管道中，必须按照正确的顺序添加认证和授权中间件。UseAuthentication()负责验证请求的凭据（即JWT令牌），而UseAuthorization()则根据验证结果和端点上定义的授权策略来决定是否允许访问。
// ... (之前的代码) app.UseHttpsRedirection(); // 启用认证中间件，它会尝试解析并验证传入请求中的JWT令牌。 app.UseAuthentication(); // 启用授权中间件，它会根据已认证用户的身份和策略来决定访问权限。 app.UseAuthorization(); // 映射控制器路由，确保在认证和授权之后执行。 app.MapControllers(); app.Run();
重要提示： UseAuthentication()、UseAuthorization()和MapControllers()的顺序至关重要。认证必须在授权之前发生，而路由映射则应在两者之后，以确保所有请求都能经过认证和授权检查。
3. 保护API端点
最后，通过在控制器或特定的API方法上应用[Authorize]属性，即可轻松保护您的API端点。当请求到达带有此属性的端点时，如果没有有效的JWT令牌或令牌验证失败，ASP.NET Core将返回401 Unauthorized响应。
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
namespace YourAppName.Controllers
{
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
private static readonly string[] Summaries = new[]
{
"Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};
private readonly ILogger _logger;
public WeatherForecastController(ILogger logger)
{
_logger = logger;
}
[HttpGet(Name = "GetWeatherForecast")]
public IEnumerable Get()
{
return Enumerable.Range(1, 5).Select(index => new WeatherForecast
{
Date = DateTime.Now.AddDays(index),
TemperatureC = Random.Shared.Next(-20, 55),
Summary = Summaries[Random.Shared.Next(Summaries.Length)]
})
.ToArray();
}
// 添加一个受保护的私有端点
[HttpGet]
[Route("Private")] // 定义该私有端点的路由
[Authorize] // 应用Authorize属性，表示此端点需要认证
public IActionResult Private()
{
// 只有经过认证的用户才能访问此端点
return Ok(new
{
Message = "Hello from a private endpoint. You are authorized!"
});
}
}
} 现在，当客户端向/WeatherForecast/Private端点发送请求时，必须在Authorization请求头中包含一个有效的Bearer JWT令牌，否则请求将被拒绝。
注意事项
- 外部授权服务器配置： 确保您的外部授权服务器（如AWS Cognito、Asgardeo、Auth0等）已正确配置，并且其OpenID Connect发现文档（/.well-known/openid-configuration）可公开访问。
- 客户端类型： 本教程提供的解决方案适用于那些不涉及客户端密钥（Client Secret）的应用场景，例如单页应用（SPA）或移动应用。对于需要客户端密钥的保密客户端（Confidential Client），AddJwtBearer的配置可能需要额外的参数，例如通过Authority直接指定颁发者，或者通过HttpClient配置来处理密钥交换。
- 令牌验证参数： MetadataAddress会自动获取大部分必要的验证参数。然而，如果您的需求特殊，可以通过TokenValidationParameters属性进行更细粒度的控制，例如强制验证颁发者（Issuer）、自定义时钟偏移（Clock Skew）等。
- 错误处理： 对于认证失败的情况，ASP.NET Core默认会返回401 Unauthorized。您可以根据需要实现自定义的错误处理逻辑，例如通过options.Events来捕获认证失败事件。
- 策略授权： [Authorize]属性除了可以简单地要求认证外，还可以结合策略（Policies）进行更复杂的授权控制，例如要求用户拥有特定的角色或声明。
总结
通过上述简洁的配置，您可以在C# .NET应用程序中快速构建一个纯资源服务器，实现基于JWT Bearer令牌的REST API安全。这种方法与Spring Boot中spring-boot-starter-oauth2-resource-server的理念高度一致，允许开发者专注于业务逻辑，而将令牌验证的复杂性交由框架和外部授权服务器处理。这极大地简化了API安全实现的流程，提高了开发效率和系统的可维护性。
