使用 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);
}