Cookie 已知 API 端點的登入重定向功能被停用

預設情況下,對受認證保護 cookie 的已知 API 端點發出的未經認證及未授權請求,現在會產生 401 和 403 回應,而非直接導向登入或被拒絕存取的 URI。

已知的 API 端點 可透過新 IDisableCookieRedirectMetadata 介面識別,且實現新介面的元資料已自動加入以下:

  • [ApiController] 端點。
  • 用最少的 API 端點讀取 JSON 請求主體或撰寫 JSON 回應。
  • 端點使用 TypedResults 回傳類型。
  • SignalR 端點。

伴隨 IAllowCookieRedirectMetadata 介面會選擇將端點重新啟用以進行重定向。 無論中繼資料是以何種順序加入,它都會覆寫 IDisableCookieRedirectMetadata。

401 和 403 回應仍包含 Location 一個標頭,包含登入或被拒絕存取的 URI。 只有狀態碼會改變。

只有 Challenge (401) 和 forbid (403) 路徑會考慮端點元資料。 登出與回傳網址的重定向不受影響。

推出的版本

.NET 10 預覽版 7

先前的行為

過去, cookie 認證處理程序會預設將未認證及未授權的請求導向至登入或拒絕存取的 URI,針對除 XMLHttpRequests (XHRs) 以外的所有請求。

新行為

從 .NET 10 開始,對已知 API 端點提出未經認證且未經授權的請求會產生 401 和 403 回應,而非直接導向登入或被拒絕存取的 URI。 XHRs無論目標終點為何,仍持續產生401和403的回應。

破壞性變更的類型

此變更為行為變更。

變更的原因

這項變更是廣受期待的。 對於 API 端點來說,將未經認證的請求重新導向到登入頁面通常沒有意義,因為 API 端點通常依賴 401 和 403 狀態碼,而非 HTML 重定向來傳達認證失敗。

要恢復整個應用程式的先前行為,請啟用 Microsoft.AspNetCore.Authentication.Cookies.IgnoreRedirectMetadata 開關。 Cookie認證則忽略端點元資料,只有 XHR 會產生 401 和 403 的回應,這與 .NET 10 之前的行為相符。 在專案檔案中設定 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);

若要改為還原個別端點的重新導向,請呼叫 AllowCookieRedirect,或將 AllowCookieRedirectAttribute 套用至動作方法或控制器類別:

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

相反地,呼叫 DisableCookieRedirect 回傳 401 和 403 狀態碼,針對未自動被偵測為 API 端點的端點。

如果你想無論目標端點為何,或請求來源是否為 XHR,都能始終重定向到未認證或未授權的登入與拒絕存取 URI,你可以覆寫 RedirectToLogin 並 RedirectToAccessDenied 如下:

builder.Services.AddAuthentication()
    .AddCookie(options =>
    {
        options.Events.OnRedirectToLogin = context =>
        {
            context.Response.Redirect(context.RedirectUri);
            return Task.CompletedTask;
        };

        options.Events.OnRedirectToAccessDenied = context =>
        {
            context.Response.Redirect(context.RedirectUri);
            return Task.CompletedTask;
        };
    });

如果你想回復到之前只針對 XHR 請求避免重定向的確切行為,可以用這個稍微複雜一點的邏輯來覆蓋事件:

builder.Services.AddAuthentication()
    .AddCookie(options =>
    {
        bool IsXhr(HttpRequest request)
        {
            return string.Equals(request.Query[HeaderNames.XRequestedWith], "XMLHttpRequest", StringComparison.Ordinal) ||
                string.Equals(request.Headers.XRequestedWith, "XMLHttpRequest", StringComparison.Ordinal);
        }

        options.Events.OnRedirectToLogin = context =>
        {
            if (IsXhr(context.Request))
            {
                context.Response.Headers.Location = context.RedirectUri;
                context.Response.StatusCode = 401;
            }
            else
            {
                context.Response.Redirect(context.RedirectUri);
            }

            return Task.CompletedTask;
        };

        options.Events.OnRedirectToAccessDenied = context =>
        {
            if (IsXhr(context.Request))
            {
                context.Response.Headers.Location = context.RedirectUri;
                context.Response.StatusCode = 403;
            }
            else
            {
                context.Response.Redirect(context.RedirectUri);
            }

            return Task.CompletedTask;
        };
    });

受影響的 API

另請參閱