ASP.NET Core 中的 API 端點驗證行為

使用 cookie 認證時,API 端點會回傳適當的 HTTP 狀態碼(401 或 403),以應對認證失敗,而非將未認證的請求導向登入頁面。 此行為更適合程式設計 API 存取,是在 .NET 10 的 ASP.NET Core 中引進。

ASP.NET Core 如何識別 API 端點

ASP.NET Core 對其識別為 API 端點的端點新增 IDisableCookieRedirectMetadata,包括:

  • 使用 [ApiController] 屬性標註的控制器。
  • 用最少的 API 端點讀取 JSON 請求主體或撰寫 JSON 回應。
  • 端點使用 TypedResults 回傳類型。
  • SignalR 樞紐與端點。

偵測是基於應用程式建立端點時推斷出的元資料。 它不是根據傳入請求的 Accept 標頭,也不是根據哪個 Map{Verb} 方法註冊了路由。

最小 API 處理器若宣告回傳類型為 void、string 或 IResult 介面,並不會透過其回傳類型提供中繼資料,儘管例如 TypedResults 等具體的 Ok<TValue> 類型會。 例如,app.MapGet("/hello", () => "Hello").RequireAuthorization() 會寫入 text/plain 一個回應且不接受 JSON 請求,因此未經認證的請求仍會被導向登入頁面。

預設行為

依預設,ASP.NET Core cookie 會根據端點類型套用驗證邏輯:

  • 網頁:請以 302 狀態碼重新導向至登入或拒絕存取頁面。
  • API 端點:回傳 401 或 403 狀態碼,而非 302 重新導向。

XMLHttpRequests(XHR)無論目標端點為何,都會收到 401 或 403 回應。 這種行為早於 .NET 10 出現,且未曾改變。

備註

端點中繼資料只會影響質詢路徑(401)和禁止存取路徑(403)。 登出作業的重新導向不受影響。 當登出請求指定重定向 URI 或有效回傳 URL 時,非 XHR 請求會像 .NET 10 之前一樣重新導向。 XHR 的行為沒有改變。

針對特定端點設定行為

執行 DisableCookieRedirect 以針對未自動偵測到的端點回傳 401 和 403 狀態碼:

var api = app.MapGroup("/api").DisableCookieRedirect();

api.MapGet("/status", () => "Ready")
   .RequireAuthorization();

呼叫 AllowCookieRedirect 以保留被偵測為 API 端點的登入重定向:

app.MapGet("/reports/summary", () => new { Total = 1000 })
   .RequireAuthorization()
   .AllowCookieRedirect();

對於控制器,請將 AllowCookieRedirectAttribute 套用至動作方法或控制器類別:

[ApiController]
[Authorize]
[AllowCookieRedirect]
[Route("[controller]")]
public class ReportsController : ControllerBase
{
    [HttpGet("summary")]
    public object GetSummary() => new { Total = 1000 };
}

Important

IAllowCookieRedirectMetadata 無論中繼資料加入的順序如何,都會覆寫 IDisableCookieRedirectMetadata。 在同一端點上於呼叫 AllowCookieRedirect 之後再呼叫 DisableCookieRedirect,並不會恢復狀態碼的行為。

在整個應用程式中選擇不參與此行為

要恢復整個應用程式在 .NET 10 之前的行為,請啟用 Microsoft.AspNetCore.Authentication.Cookies.IgnoreRedirectMetadata Switch。 啟用後, cookie 認證會忽略端點的元資料,只有 XHR 會產生 401 和 403 的回應。

在專案檔案中設定 switch 使其在任何應用程式程式碼執行前就套用:

<ItemGroup>
  <RuntimeHostConfigurationOption
    Include="Microsoft.AspNetCore.Authentication.Cookies.IgnoreRedirectMetadata"
    Value="true" />
</ItemGroup>

開關也可以用程式碼設定。 它會在第一次使用 cookie 驗證時被讀取一次,因此請在建置主機之前呼叫 SetSwitch:

AppContext.SetSwitch(
    "Microsoft.AspNetCore.Authentication.Cookies.IgnoreRedirectMetadata", true);

var builder = WebApplication.CreateBuilder(args);

破壞性變更考量

.NET 10 引入的改變是行為上的改變。 結合cookie驗證與 ASP.NET Core 偵測為 API 端點的應用程式,會回傳 401 和 403 的回應,而之前則是 302 重新導向至登入或存取遭拒頁面。 如需完整的重大變更通知,請參閱 Cookie 已知 API 端點的登入重新導向已停用。

請考慮對每種應用程式的影響:

  • 網頁應用程式:頁面端點持續導向登入頁面。
  • 混合應用:API 端點會回傳狀態碼,而網頁則會被重新導向,因此先前會跟隨重新導向的瀏覽器端程式碼必須改為處理 401 和 403。
  • 僅 API 應用程式:偵測到的 API 端點會回傳正確的 HTTP 狀態碼,無需額外設定。

要維持之前的行為,請在受影響的端點上呼叫 AllowCookieRedirect、將 [AllowCookieRedirect] 套用至受影響的控制器,或啟用整個應用程式的 Microsoft.AspNetCore.Authentication.Cookies.IgnoreRedirectMetadata 交換器。

測試您的 API 端點

在 .NET 10 升級到 ASP.NET Core 後,請確認你的 API 端點是否回傳適當的狀態碼:

[Fact]
public async Task UnauthorizedApiRequest_Returns401()
{
    var response = await client.GetAsync("/api/secure-data");

    Assert.Equal(HttpStatusCode.Unauthorized, response.StatusCode);

    // The handler sets the Location header before setting the status code,
    // so the login URI is still present on the 401 response.
    Assert.NotNull(response.Headers.Location);
}