C# .NET JWT外部授权安全配置指南

服务器的REST API安全配置指南 " />

核心概念：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();

请将替换为您的客户端ID，将https://api.asgardeo.io/t//oauth2/token/.well-known/openid-configuration替换为您的外部授权服务器的OpenID Connect发现文档地址。

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安全实现的流程，提高了开发效率和系统的可维护性。