使用 DelegatingHandler 在 Web API 中实现 API 密钥验证
在构建 Web API 服务时，确保请求来源的合法性是安全设计的重要环节。一种常见做法是通过 API Key 进行客户端身份识别。客户端可通过两种方式传递密钥：查询字符串（query string）或 HTTP 请求头（header）。
API Key 传递方式示例
1. 通过查询参数传递：
http://localhost:57967/api/values?key=abc1232. 通过自定义请求头传递：
var client = new HttpClient();
client.BaseAddress = new Uri("http://localhost:57967/");
client.DefaultRequestHeaders.Add("X-ApiKey", "abc123");
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
var response = await client.GetAsync("api/values");创建自定义消息处理程序
ASP.NET Web API 提供了 DelegatingHandler 类，可用于在请求进入控制器之前拦截并验证请求。以下是一个基于 API Key 的验证处理器实现：
public class ApiKeyValidationHandler : DelegatingHandler
{
private const string ApiKeyHeaderName = "X-ApiKey";
private readonly string _validApiKey;
public ApiKeyValidationHandler(string apiKey, HttpConfiguration configuration)
{
_validApiKey = apiKey;
InnerHandler = new HttpControllerDispatcher(configuration);
}
protected override async Task<HttpResponseMessage> SendAsync(
HttpRequestMessage request,
CancellationToken cancellationToken)
{
if (!IsValidApiKey(request))
{
return request.CreateResponse(HttpStatusCode.Forbidden,
new { error = "Invalid or missing API key." });
}
return await base.SendAsync(request, cancellationToken);
}
private bool IsValidApiKey(HttpRequestMessage request)
{
// 优先从请求头中读取
if (request.Headers.TryGetValues(ApiKeyHeaderName, out var headerValues))
{
return string.Equals(headerValues.FirstOrDefault(), _validApiKey, StringComparison.Ordinal);
}
// 其次尝试从查询字符串中获取
var queryParameters = System.Web.HttpUtility.ParseQueryString(request.RequestUri.Query);
var queryKey = queryParameters["key"];
return string.Equals(queryKey, _validApiKey, StringComparison.Ordinal);
}
}上述代码首先尝试从 X-ApiKey 请求头中提取密钥；若未找到，则回退至查询参数 key。只要任一方式提供正确的密钥即可通过验证。
将处理程序注册到特定路由
为了仅对特定接口启用 API Key 验证，可以在路由配置中指定该处理程序：
config.Routes.MapHttpRoute(
name: "SecureApi",
routeTemplate: "api/secure/{controller}/{id}",
defaults: new { id = RouteParameter.Optional },
constraints: null,
handler: new ApiKeyValidationHandler("abc123", GlobalConfiguration.Configuration)
);此配置表示所有匹配 /api/secure/** 模式的请求都将经过 ApiKeyValidationHandler 的检查，而其他普通路由则不受影响，保持开放或由其他机制保护。
可选增强功能
为进一步提升安全性与可扩展性，可考虑以下改进：
- 结合数据库或缓存动态校验多个有效密钥
- 记录非法访问尝试以用于审计
- 支持过期时间、权限范围等更复杂的密钥元数据
- 集成日志框架输出调试信息
