通过

ASP.NET Core 中的 API 终结点身份验证行为

使用 cookie 身份验证时，API 终结点将返回相应的 HTTP 状态代码（例如 401 或 403），以进行身份验证失败，而不是将未经身份验证的请求重定向到登录页。 此行为更适用于编程 API 访问，是在 .NET 10 ASP.NET Core 中引入的。

ASP.NET 核心如何标识 API 终结点

ASP.NET Core 会自动将这个行为应用于它识别为与 API 有关的端点，包括：

  • 使用特性修饰的 [ApiController] 控制器
  • 注册的 API 终结点为最简，并附加在 MapGet、MapPost、MapPut、MapDelete 等。
  • 显式请求 JSON 响应的终结点
  • SignalR 中心和端点

默认行为和自定义

默认情况下，ASP.NET Core 根据终结点类型应用 cookie 身份验证逻辑：

  • 网页：重定向到登录页
  • API 终结点：在不重定向的情况下返回 401 或 403 状态代码

行为配置

虽然默认行为适用于大多数方案，但如果需要，可以对其进行自定义：

builder.Services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
    .AddCookie(options =>
    {
        options.LoginPath = "/Account/Login";
        // The framework automatically handles API endpoints
        // No additional configuration needed
    });

如果需要覆盖特定终结点的自动检测，请使用某个[Authorize]属性与特定身份验证方案或实现自定义身份验证处理程序。

迁移注意事项

在 .NET 10 中引入的这种行为更改旨在不影响现有应用程序的正常运行。

  • Web 应用程序：继续像以前一样使用登录页重定向
  • 混合应用程序：API 终结点获取正确的状态代码，而网页获取重定向。
  • 仅限 API 的应用程序：无需其他配置即可从适当的 HTTP 状态代码中受益

测试 API 终结点

升级到 ASP.NET Core 10 后，验证 API 终结点是否返回适当的状态代码：

[Test]
public async Task UnauthorizedApiRequest_Returns401()
{
    var response = await client.GetAsync("/api/secure-data");
    Assert.Equal(HttpStatusCode.Unauthorized, response.StatusCode);
    Assert.False(response.Headers.Location != null); // No redirect
}