在 ASP.NET Core 中處理 SameSite Cookie

作者:Rick Anderson

SameSite 是 IETF 草稿標準,旨在提供對跨站請求偽造 (CSRF) 攻擊的一些防禦。 最初於 2016 年起草,草案標準於 2019 年更新。 更新的標準不向下相容於先前的標準,以下是最明顯的差異:

  • 依預設會將沒有 SameSite 標頭的 cookies 視為 SameSite=Lax 。
  • SameSite=None 必須用於允許跨站 Cookie 使用。
  • 判斷提示 SameSite=None 的 cookies 也必須標示為 Secure。
  • 使用 <iframe> 的應用程式可能會遇到 sameSite=Lax 或 sameSite=Strict cookies 的問題,因為 <iframe> 會被視為跨網站。
  • 值 SameSite=None 不被 2016 標準 允許,而導致某些實作將這類 cookies 視為 SameSite=Strict。 請參閱本文件中的支援舊版瀏覽器。

SameSite=Lax 設定適用於大部分的應用程式 cookies。 某些形式的驗證 (例如 OpenID Connect (OIDC) 和 WS-Federation) 預設為 POST 型重新導向。 POST 型重新導向會觸發 SameSite 瀏覽器保護,因此對於這些元件會停用 SameSite。 大部分的 OAuth 登入並不會因為請求流程的差異而受到影響。

每個發出 cookies 的 ASP.NET Core 元件都必須確認 SameSite 是否適當。

SameSite 與 Identity

ASP.NET Core Identity 大多不受 SameSite Cookie 影響,只有在如 IFrames 或 OpenIdConnect 整合等進階情境下例外。

使用 Identity時,請不要新增任何 Cookie 服務提供者或呼叫 services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme),Identity 會處理這件事。

SameSite 測試範例程式碼

下列範例可供下載並測試:

Sample Document
Razor 頁面 ASP.NET Core 3.1 Razor Pages SameSite cookie 範例

.NET 對 sameSite 屬性的支援

.NET 支援 SameSite 的 2019 草稿標準。 開發人員可以使用 HttpCookie.SameSite 屬性,以程式設計方式控制 sameSite 屬性的值。 將屬性設 SameSite 為 Strict、 Lax、 或 None 會讓這些值與 cookie 一起寫入網路。 設定為 SameSiteMode.Unspecified 表示不應隨 cookie 傳送 sameSite。

    var cookieOptions = new CookieOptions
    {
        // Set the secure flag, which Chrome's changes will require for SameSite none.
        // Note this will also require you to be running on HTTPS.
        Secure = true,

        // Set the cookie to HTTP only which is good practice unless you really do need
        // to access it client side in scripts.
        HttpOnly = true,

        // Add the SameSite attribute, this will emit the attribute with a value of none.
        SameSite = SameSiteMode.None

        // The client should follow its default cookie policy.
        // SameSite = SameSiteMode.Unspecified
    };

    // Add the cookie to the response cookie collection
    Response.Cookies.Append("MyCookie", "cookieValue", cookieOptions);
}

將 API 與 SameSite 搭配使用

HttpContext.Response.Cookies.Append 預設為 Unspecified,表示 cookie 不會新增 SameSite 屬性,客戶端會使用預設行為(新瀏覽器為 Lax,舊瀏覽器為 None)。 以下程式碼說明如何將 Cookie SameSite 值更改為 SameSiteMode.Lax:

HttpContext.Response.Cookies.Append(
                     "name", "value",
                     new CookieOptions() { SameSite = SameSiteMode.Lax });

所有發出 cookies 的 ASP.NET Core 元件都會將前述預設值覆寫為適合其案例的設定。 被覆寫的前述預設值並未變更。

Component cookie Default
CookieBuilder SameSite Unspecified
Session SessionOptions.Cookie Lax
CookieTempDataProvider CookieTempDataProviderOptions.Cookie Lax
IAntiforgery AntiforgeryOptions.Cookie Strict
Cookie 認證 CookieAuthenticationOptions.Cookie Lax
AddTwitter TwitterOptions.StateCookie Lax
RemoteAuthenticationHandler<TOptions> RemoteAuthenticationOptions.CorrelationCookie None
AddOpenIdConnect OpenIdConnectOptions.NonceCookie None
HttpContext.Response.Cookies.Append CookieOptions Unspecified

ASP.NET Core 3.1 或更新版本提供下列 SameSite 支援:

  • 重新定義 SameSiteMode.None 發出 SameSite=None 的行為
  • 新增可用來省略 SameSite 屬性的新值 SameSiteMode.Unspecified。
  • 所有 Cookie API 預設為 Unspecified。 某些使用 cookies 的元件會依據其情境設定更明確的值。 如需範例,請參閱上表。

在 ASP.NET Core 3.0 或更新版本中,SameSite 預設值已變更,以避免與不一致的客戶端預設值發生衝突。 下列 API 已將預設值從 SameSiteMode.Lax 變更為 -1 ,以避免針對這些 cookies 發出 SameSite 屬性:

歷史記錄與變更

SameSite 支援最初在 ASP.NET Core 2.0 中使用 2016 草稿標準實作。 2016 標準為選擇性採用。 ASP.NET Core 預設會設定數個 cookie 至 Lax,以啟用加入機制。 在發生若干驗證問題之後,大部分的 SameSite 使用都已停用。

2019 年 11 月發行了修補檔,用以從 2016 標準更新為 2019 標準。 SameSite 規格的 2019 草稿:

  • 與 2016 草稿不回溯相容。 如需詳細資訊,請參閱本文件中的支援舊版瀏覽器。
  • 指定 cookies 預設被視為 SameSite=Lax 。
  • 指定明確宣告 SameSite=None 以啟用跨網站傳遞的 cookies 應標示為 Secure。 None 是新的退出選項。
  • 受到針對 ASP.NET Core 2.1、2.2 和 3.0 發出的修補檔支援。 ASP.NET Core 3.1 或更新版本有額外的 SameSite 支援。
  • 排定於由 Chrome 依預設在 2020 年 2 月啟用。 瀏覽器於 2019 年開始移轉至此標準。

從 2016 SameSite 草稿標準變更為 2019 SameSite 草稿標準後影響到的 API

支援舊版瀏覽器

2016 年 SameSite 標準規定未知的值必須被視為 SameSite=Strict 值。 由支援 2016 SameSite 標準的舊版瀏覽器存取的應用程式在取得值為 None 的 SameSite 屬性時可能會中斷。 如果 Web 應用程式預定要支援舊版瀏覽器,則必須實作瀏覽器偵測。 ASP.NET Core 不會實作瀏覽器偵測,因為 User-Agents 值非常不穩定,經常變更。 Microsoft.AspNetCore.CookiePolicy 中的擴充點允許掛接 User-Agent 特定邏輯。

在 Program.cs中新增程式碼,以在呼叫 UseAuthentication 或任何會寫入 Cookie 的任何方法之前呼叫 UseCookiePolicy:

var builder = WebApplication.CreateBuilder(args);

builder.Services.Configure<CookiePolicyOptions>(options =>
{
    options.MinimumSameSitePolicy = SameSiteMode.Unspecified;
    options.OnAppendCookie = cookieContext =>
        CheckSameSite(cookieContext.Context, cookieContext.CookieOptions);
    options.OnDeleteCookie = cookieContext =>
        CheckSameSite(cookieContext.Context, cookieContext.CookieOptions);
});

void CheckSameSite(HttpContext httpContext, CookieOptions options)
{
    if (options.SameSite == SameSiteMode.None)
    {
        var userAgent = httpContext.Request.Headers["User-Agent"].ToString();
        if (MyUserAgentDetectionLib.DisallowsSameSiteNone(userAgent))
        {
            options.SameSite = SameSiteMode.Unspecified;
        }
    }
}

    builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseCookiePolicy();
app.UseAuthorization();

app.MapRazorPages();

app.Run();

在 Program.cs 中,新增與下列反白顯示的程式碼相似的程式碼:

var builder = WebApplication.CreateBuilder(args);

builder.Services.Configure<CookiePolicyOptions>(options =>
{
    options.MinimumSameSitePolicy = SameSiteMode.Unspecified;
    options.OnAppendCookie = cookieContext =>
        CheckSameSite(cookieContext.Context, cookieContext.CookieOptions);
    options.OnDeleteCookie = cookieContext =>
        CheckSameSite(cookieContext.Context, cookieContext.CookieOptions);
});

void CheckSameSite(HttpContext httpContext, CookieOptions options)
{
    if (options.SameSite == SameSiteMode.None)
    {
        var userAgent = httpContext.Request.Headers["User-Agent"].ToString();
        if (MyUserAgentDetectionLib.DisallowsSameSiteNone(userAgent))
        {
            options.SameSite = SameSiteMode.Unspecified;
        }
    }
}

    builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseCookiePolicy();
app.UseAuthorization();

app.MapRazorPages();

app.Run();

在上述範例中,MyUserAgentDetectionLib.DisallowsSameSiteNone 是使用者提供的程式庫,可偵測使用者代理程式是否不支援 SameSite None:

if (MyUserAgentDetectionLib.DisallowsSameSiteNone(userAgent))
{
    options.SameSite = SameSiteMode.Unspecified;
}

下列程式碼顯示範例 DisallowsSameSiteNone 方法:

Warning

下列程式碼僅供示範之用:

  • 不應將其視為完整。
  • 該程式碼不受維護或支援。
public static bool DisallowsSameSiteNone(string userAgent)
{
    // Check if a null or empty string has been passed in, since this
    // will cause further interrogation of the useragent to fail.
     if (String.IsNullOrWhiteSpace(userAgent))
        return false;
    
    // Cover all iOS based browsers here. This includes:
    // - Safari on iOS 12 for iPhone, iPod Touch, iPad
    // - WkWebview on iOS 12 for iPhone, iPod Touch, iPad
    // - Chrome on iOS 12 for iPhone, iPod Touch, iPad
    // All of which are broken by SameSite=None, because they use the iOS networking
    // stack.
    if (userAgent.Contains("CPU iPhone OS 12") ||
        userAgent.Contains("iPad; CPU OS 12"))
    {
        return true;
    }

    // Cover Mac OS X based browsers that use the Mac OS networking stack. 
    // This includes:
    // - Safari on Mac OS X.
    // This does not include:
    // - Chrome on Mac OS X
    // Because they do not use the Mac OS networking stack.
    if (userAgent.Contains("Macintosh; Intel Mac OS X 10_14") &&
        userAgent.Contains("Version/") && userAgent.Contains("Safari"))
    {
        return true;
    }

    // Cover Chrome 50-69, because some versions are broken by SameSite=None, 
    // and none in this range require it.
    // Note: this covers some pre-Chromium Edge versions, 
    // but pre-Chromium Edge does not require SameSite=None.
    if (userAgent.Contains("Chrome/5") || userAgent.Contains("Chrome/6"))
    {
        return true;
    }

    return false;
}

用於測試 SameSite 問題的應用程式

與遠端站台互動的應用程式 (例如透過第三方登入) 必須:

使用可選擇加入新 SameSite 行為的用戶端版本來測試 Web 應用程式。 Chrome、Firefox 和 Chromium Edge 都有新的需啟用功能標記可用於測試。 在您的應用程式套用 SameSite 修補檔後,請使用較舊的用戶端版本 (尤其是 Safari) 加以測試。 如需詳細資訊,請參閱本文件中的支援舊版瀏覽器。

使用 Chrome 測試

Chrome 78+ 已採取暫時性的緩解措施,因此會提供誤導性的結果。 Chrome 78+ 的暫時緩解措施允許建立時間未滿兩分鐘的 Cookie。 已啟用適當測試旗標的 Chrome 76 或 77 可提供更精確的結果。 若要測試新的 SameSite 行為,請將 chrome://flags/#same-site-by-default-cookies 切換為 啟用。 據回報,舊版的 Chrome (75 和更低版本) 在使用新的 None 設定時會失敗。 請參閱本文件中的支援舊版瀏覽器。

Google 不提供較舊的 Chrome 版本。 請依照下載 Chromium 中的指示,對舊版 Chrome 進行測試。 請不要用搜尋舊版 Chrome 所獲得的連結來下載 Chrome。

從 Canary 版本 80.0.3975.0 開始,可以基於測試目的使用新旗標 --enable-features=SameSiteDefaultChecksMethodRigorously 將 Lax+POST 暫時性緩和措施停用,以便在功能最終移除該緩和措施後的狀態下測試站台和服務。 如需詳細資訊,請參閱 Chromium Projects 的 SameSite 更新

使用 Safari 測試

Safari 12 嚴格執行先前的草案,但當新 None 值出現在 Cookie 中時會導致錯誤。 可透過本文件中的瀏覽器偵測程式碼 支援舊版瀏覽器 來避免 None。 使用 MSAL、ADAL 或您使用的任何程式庫,測試 Safari 12、Safari 13 和 WebKit 型 OS 樣式登入。 此問題取決於基礎 OS 版本。 目前已知 OSX Mojave (10.14) 和 iOS 12 會與新的 SameSite 行為發生相容性問題。 將 OS 升級至 OSX Catalina 10.15 或 iOS 13,可修正這個問題。 目前 Safari 並未提供用於測試新規格行為的啟用旗標。

使用 Firefox 測試

Firefox 對新標準的支援可在 68+ 版上進行測試,方法是在 about:config 分頁上選擇加入,並使用功能旗標 network.cookie.sameSite.laxByDefault。 目前為止並未回報任何舊版 Firefox 的相容性問題。

使用 Edge 瀏覽器進行測試

Edge 支援舊的 SameSite 標準。 Edge 44 版與新標準間沒有任何已知的相容性問題。

使用 Edge (Chromium) 進行測試

SameSite 旗標設定在 edge://flags/#same-site-by-default-cookies 頁面上。 未發現 Edge Chromium 的相容性問題。

用電子測試

Electron 的各個版本包含較舊版本的 Chromium。 例如,Teams 所使用的 Electron 版本是 Chromium 66,呈現出較舊的功能表現。 您必須針對您的產品所使用的 Electron 版本自行執行相容性測試。 請參閱下一節中的支援舊版瀏覽器。

其他資源

Sample Document
Razor 頁面 ASP.NET Core 3.1 Razor Pages SameSite cookie 範例

下列範例可供下載並測試:

Sample Document
Razor 頁面 ASP.NET Core 3.1 Razor Pages SameSite cookie 範例

.NET Core 對 sameSite 屬性的支援

.NET Core 3.1 或更新版本支援SameSite的 2019 草稿標準。 開發人員可以使用 HttpCookie.SameSite 屬性,以程式設計方式控制 sameSite 屬性的值。 將屬性 SameSite 設為嚴格、Lax 或 None 會將這些值隨 Cookie 一起寫入網路。 將其設為 (SameSiteMode)(-1) 表示 Cookie 不應包含任何 SameSite 屬性

var cookieOptions = new CookieOptions
{
    // Set the secure flag, which Chrome's changes will require for SameSite none.
    // Note this will also require you to be running on HTTPS.
    Secure = true,

    // Set the cookie to HTTP only which is good practice unless you really do need
    // to access it client side in scripts.
    HttpOnly = true,

    // Add the SameSite attribute, this will emit the attribute with a value of none.
    // To not emit the attribute at all set
    // SameSite = (SameSiteMode)(-1)
    SameSite = SameSiteMode.None
};

// Add the cookie to the response cookie collection
Response.Cookies.Append("MyCookie", "cookieValue", cookieOptions);

.NET Core 3.1 或更新版本支援更新的 SameSite 值,並將額外的列舉值 SameSiteMode.Unspecified 添加到 SameSiteMode。 這個新值表示不應隨 cookie 傳送 sameSite。

將 API 與 SameSite 搭配使用

HttpContext.Response.Cookies.Append 預設為 Unspecified,表示 cookie 不會新增 SameSite 屬性,客戶端會使用預設行為(新瀏覽器為 Lax,舊瀏覽器為 None)。 以下程式碼說明如何將 Cookie SameSite 值更改為 SameSiteMode.Lax:

HttpContext.Response.Cookies.Append(
                     "name", "value",
                     new CookieOptions() { SameSite = SameSiteMode.Lax });

所有發出 cookies 的 ASP.NET Core 元件都會將前述預設值覆寫為適合其案例的設定。 被覆寫的前述預設值並未變更。

Component cookie Default
CookieBuilder SameSite Unspecified
Session SessionOptions.Cookie Lax
CookieTempDataProvider CookieTempDataProviderOptions.Cookie Lax
IAntiforgery AntiforgeryOptions.Cookie Strict
Cookie 認證 CookieAuthenticationOptions.Cookie Lax
AddTwitter TwitterOptions.StateCookie Lax
RemoteAuthenticationHandler<TOptions> RemoteAuthenticationOptions.CorrelationCookie None
AddOpenIdConnect OpenIdConnectOptions.NonceCookie None
HttpContext.Response.Cookies.Append CookieOptions Unspecified

ASP.NET Core 3.1 或更新版本提供下列 SameSite 支援:

  • 重新定義 SameSiteMode.None 發出 SameSite=None 的行為
  • 新增可用來省略 SameSite 屬性的新值 SameSiteMode.Unspecified。
  • 所有 Cookie API 預設為 Unspecified。 某些使用 cookies 的元件會依據其情境設定更明確的值。 如需範例,請參閱上表。

在 ASP.NET Core 3.0 或更新版本中,SameSite 預設值已變更,以避免與不一致的客戶端預設值發生衝突。 下列 API 已將預設值從 SameSiteMode.Lax 變更為 -1 ,以避免針對這些 cookies 發出 SameSite 屬性:

歷史記錄與變更

SameSite 支援最初在 ASP.NET Core 2.0 中使用 2016 草稿標準實作。 2016 標準為選擇性採用。 ASP.NET Core 預設會設定數個 cookie 至 Lax,以啟用加入機制。 在發生若干驗證問題之後,大部分的 SameSite 使用都已停用。

2019 年 11 月發行了修補檔,用以從 2016 標準更新為 2019 標準。 SameSite 規格的 2019 草稿:

  • 與 2016 草稿不回溯相容。 如需詳細資訊,請參閱本文件中的支援舊版瀏覽器。
  • 指定 cookies 預設被視為 SameSite=Lax 。
  • 指定明確宣告 SameSite=None 以啟用跨網站傳遞的 cookies 應標示為 Secure。 None 是新的退出選項。
  • 受到針對 ASP.NET Core 2.1、2.2 和 3.0 發出的修補檔支援。 ASP.NET Core 3.1 有額外的 SameSite 支援。
  • 排定於由 Chrome 依預設在 2020 年 2 月啟用。 瀏覽器於 2019 年開始移轉至此標準。

從 2016 SameSite 草稿標準變更為 2019 SameSite 草稿標準後影響到的 API

支援舊版瀏覽器

2016 年 SameSite 標準規定未知的值必須被視為 SameSite=Strict 值。 由支援 2016 SameSite 標準的舊版瀏覽器存取的應用程式在取得值為 None 的 SameSite 屬性時可能會中斷。 如果 Web 應用程式預定要支援舊版瀏覽器,則必須實作瀏覽器偵測。 ASP.NET Core 不會實作瀏覽器偵測,因為 User-Agents 值非常不穩定,經常變更。 Microsoft.AspNetCore.CookiePolicy 中的擴充點允許掛接 User-Agent 特定邏輯。

在 Startup.Configure中新增程式碼,以在呼叫 UseAuthentication 或任何會寫入 Cookie 的任何方法之前呼叫 UseCookiePolicy:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseStaticFiles();

    app.UseRouting();

    app.UseCookiePolicy();
    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
    });
}

在 Startup.ConfigureServices 中,新增如下的程式碼:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<CookiePolicyOptions>(options =>
    {
        options.MinimumSameSitePolicy = SameSiteMode.Unspecified;
        options.OnAppendCookie = cookieContext =>
            CheckSameSite(cookieContext.Context, cookieContext.CookieOptions);
        options.OnDeleteCookie = cookieContext =>
            CheckSameSite(cookieContext.Context, cookieContext.CookieOptions);
    });

    services.AddRazorPages();
}

private void CheckSameSite(HttpContext httpContext, CookieOptions options)
{
    if (options.SameSite == SameSiteMode.None)
    {
        var userAgent = httpContext.Request.Headers["User-Agent"].ToString();
        if (MyUserAgentDetectionLib.DisallowsSameSiteNone(userAgent))
        {
            options.SameSite = SameSiteMode.Unspecified;
        }
    }
}

在上述範例中,MyUserAgentDetectionLib.DisallowsSameSiteNone 是使用者提供的程式庫,可偵測使用者代理程式是否不支援 SameSite None:

if (MyUserAgentDetectionLib.DisallowsSameSiteNone(userAgent))
{
    options.SameSite = SameSiteMode.Unspecified;
}

下列程式碼顯示範例 DisallowsSameSiteNone 方法:

Warning

下列程式碼僅供示範之用:

  • 不應將其視為完整。
  • 該程式碼不受維護或支援。
public static bool DisallowsSameSiteNone(string userAgent)
{
    // Check if a null or empty string has been passed in, since this
    // will cause further interrogation of the useragent to fail.
     if (String.IsNullOrWhiteSpace(userAgent))
        return false;
    
    // Cover all iOS based browsers here. This includes:
    // - Safari on iOS 12 for iPhone, iPod Touch, iPad
    // - WkWebview on iOS 12 for iPhone, iPod Touch, iPad
    // - Chrome on iOS 12 for iPhone, iPod Touch, iPad
    // All of which are broken by SameSite=None, because they use the iOS networking
    // stack.
    if (userAgent.Contains("CPU iPhone OS 12") ||
        userAgent.Contains("iPad; CPU OS 12"))
    {
        return true;
    }

    // Cover Mac OS X based browsers that use the Mac OS networking stack. 
    // This includes:
    // - Safari on Mac OS X.
    // This does not include:
    // - Chrome on Mac OS X
    // Because they do not use the Mac OS networking stack.
    if (userAgent.Contains("Macintosh; Intel Mac OS X 10_14") &&
        userAgent.Contains("Version/") && userAgent.Contains("Safari"))
    {
        return true;
    }

    // Cover Chrome 50-69, because some versions are broken by SameSite=None, 
    // and none in this range require it.
    // Note: this covers some pre-Chromium Edge versions, 
    // but pre-Chromium Edge does not require SameSite=None.
    if (userAgent.Contains("Chrome/5") || userAgent.Contains("Chrome/6"))
    {
        return true;
    }

    return false;
}

用於測試 SameSite 問題的應用程式

與遠端站台互動的應用程式 (例如透過第三方登入) 必須:

使用可選擇加入新 SameSite 行為的用戶端版本來測試 Web 應用程式。 Chrome、Firefox 和 Chromium Edge 都有新的需啟用功能標記可用於測試。 在您的應用程式套用 SameSite 修補檔後,請使用較舊的用戶端版本 (尤其是 Safari) 加以測試。 如需詳細資訊,請參閱本文件中的支援舊版瀏覽器。

使用 Chrome 測試

Chrome 78+ 已採取暫時性的緩解措施,因此會提供誤導性的結果。 Chrome 78+ 的暫時緩解措施允許建立時間未滿兩分鐘的 Cookie。 已啟用適當測試旗標的 Chrome 76 或 77 可提供更精確的結果。 若要測試新的 SameSite 行為,請將 chrome://flags/#same-site-by-default-cookies 切換為 啟用。 據回報,舊版的 Chrome (75 和更低版本) 在使用新的 None 設定時會失敗。 請參閱本文件中的支援舊版瀏覽器。

Google 不提供較舊的 Chrome 版本。 請依照下載 Chromium 中的指示,對舊版 Chrome 進行測試。 請不要用搜尋舊版 Chrome 所獲得的連結來下載 Chrome。

從 Canary 版本 80.0.3975.0 開始,可以基於測試目的使用新旗標 --enable-features=SameSiteDefaultChecksMethodRigorously 將 Lax+POST 暫時性緩和措施停用,以便在功能最終移除該緩和措施後的狀態下測試站台和服務。 如需詳細資訊,請參閱 Chromium Projects 的 SameSite 更新

使用 Safari 測試

Safari 12 嚴格執行先前的草案,但當新 None 值出現在 Cookie 中時會導致錯誤。 可透過本文件中的瀏覽器偵測程式碼 支援舊版瀏覽器 來避免 None。 使用 MSAL、ADAL 或您使用的任何程式庫,測試 Safari 12、Safari 13 和 WebKit 型 OS 樣式登入。 此問題取決於基礎 OS 版本。 目前已知 OSX Mojave (10.14) 和 iOS 12 會與新的 SameSite 行為發生相容性問題。 將 OS 升級至 OSX Catalina 10.15 或 iOS 13,可修正這個問題。 目前 Safari 並未提供用於測試新規格行為的啟用旗標。

使用 Firefox 測試

Firefox 對新標準的支援可在 68+ 版上進行測試,方法是在 about:config 分頁上選擇加入,並使用功能旗標 network.cookie.sameSite.laxByDefault。 目前為止並未回報任何舊版 Firefox 的相容性問題。

使用 Edge 瀏覽器進行測試

Edge 支援舊的 SameSite 標準。 Edge 44 版與新標準間沒有任何已知的相容性問題。

使用 Edge (Chromium) 進行測試

SameSite 旗標設定在 edge://flags/#same-site-by-default-cookies 頁面上。 未發現 Edge Chromium 的相容性問題。

用電子測試

Electron 的各個版本包含較舊版本的 Chromium。 例如,Teams 所使用的 Electron 版本是 Chromium 66,呈現出較舊的功能表現。 您必須針對您的產品所使用的 Electron 版本自行執行相容性測試。 請參閱下一節中的支援舊版瀏覽器。

其他資源

Sample Document
Razor 頁面 ASP.NET Core 3.1 Razor Pages SameSite cookie 範例

下列範例可供下載並測試:

Sample Document
MVC ASP.NET Core 2.1 MVC SameSite cookie 範例
Razor 頁面 ASP.NET Core 2.1 Razor Pages SameSite cookie 範例

12 月修補檔行為變更

.NET Framework 和 .NET Core 2.1 的特定行為變更在於 SameSite 屬性解譯 None 值的方式。 在此修補檔之前,值 None 表示「完全不要發出屬性」,在此修補檔之後,則表示「發出值為 None 的屬性」。 在此修補檔之後,SameSite 值若為 (SameSiteMode)(-1),則不會輸出該屬性。

表單驗證和工作階段狀態 cookies 的預設 SameSite 值已從 None 變更為 Lax。

將 API 與 SameSite 搭配使用

HttpContext.Response.Cookies.Append 預設為 Unspecified,表示 cookie 不會新增 SameSite 屬性,客戶端會使用預設行為(新瀏覽器為 Lax,舊瀏覽器為 None)。 以下程式碼說明如何將 Cookie SameSite 值更改為 SameSiteMode.Lax:

HttpContext.Response.Cookies.Append(
                     "name", "value",
                     new CookieOptions() { SameSite = SameSiteMode.Lax });

所有發出 cookies 的 ASP.NET Core 元件都會將前述預設值覆寫為適合其案例的設定。 被覆寫的前述預設值並未變更。

Component cookie Default
CookieBuilder SameSite Unspecified
Session SessionOptions.Cookie Lax
CookieTempDataProvider CookieTempDataProviderOptions.Cookie Lax
IAntiforgery AntiforgeryOptions.Cookie Strict
Cookie 認證 CookieAuthenticationOptions.Cookie Lax
AddTwitter TwitterOptions.StateCookie Lax
RemoteAuthenticationHandler<TOptions> RemoteAuthenticationOptions.CorrelationCookie None
AddOpenIdConnect OpenIdConnectOptions.NonceCookie None
HttpContext.Response.Cookies.Append CookieOptions Unspecified

歷史記錄與變更

SameSite 支援最初在 ASP.NET Core 2.0 中使用 2016 草稿標準實作。 2016 標準為選擇性採用。 ASP.NET Core 預設會設定數個 cookie 至 Lax,以啟用加入機制。 在發生若干驗證問題之後,大部分的 SameSite 使用都已停用。

2019 年 11 月發行了修補檔,用以從 2016 標準更新為 2019 標準。 SameSite 規格的 2019 草稿:

  • 與 2016 草稿不回溯相容。 如需詳細資訊,請參閱本文件中的支援舊版瀏覽器。
  • 指定 cookies 預設被視為 SameSite=Lax 。
  • 指定明確宣告 SameSite=None 以啟用跨網站傳遞的 cookies 應標示為 Secure。 None 是新的退出選項。
  • 受到針對 ASP.NET Core 2.1、2.2 和 3.0 發出的修補檔支援。 ASP.NET Core 3.1 有額外的 SameSite 支援。
  • 排定於由 Chrome 依預設在 2020 年 2 月啟用。 瀏覽器於 2019 年開始移轉至此標準。

從 2016 SameSite 草稿標準變更為 2019 SameSite 草稿標準後影響到的 API

支援舊版瀏覽器

2016 年 SameSite 標準規定未知的值必須被視為 SameSite=Strict 值。 由支援 2016 SameSite 標準的舊版瀏覽器存取的應用程式在取得值為 None 的 SameSite 屬性時可能會中斷。 如果 Web 應用程式預定要支援舊版瀏覽器,則必須實作瀏覽器偵測。 ASP.NET Core 不會實作瀏覽器偵測,因為 User-Agents 值非常不穩定,經常變更。 Microsoft.AspNetCore.CookiePolicy 中的擴充點允許掛接 User-Agent 特定邏輯。

在 Startup.Configure中新增程式碼,以在呼叫 UseAuthentication 或任何會寫入 Cookie 的任何方法之前呼叫 UseCookiePolicy:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseStaticFiles();

    app.UseRouting();

    app.UseCookiePolicy();
    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
    });
}

在 Startup.ConfigureServices 中,新增如下的程式碼:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<CookiePolicyOptions>(options =>
    {
        options.MinimumSameSitePolicy = (SameSiteMode)(-1);
        options.OnAppendCookie = cookieContext =>
            CheckSameSite(cookieContext.Context, cookieContext.CookieOptions);
        options.OnDeleteCookie = cookieContext =>
            CheckSameSite(cookieContext.Context, cookieContext.CookieOptions);
    });

    services.AddRazorPages();
}

private void CheckSameSite(HttpContext httpContext, CookieOptions options)
{
    if (options.SameSite == SameSiteMode.None)
    {
        var userAgent = httpContext.Request.Headers["User-Agent"].ToString();
        if (MyUserAgentDetectionLib.DisallowsSameSiteNone(userAgent))
        {
            options.SameSite = (SameSiteMode)(-1);
        }

    }
}

在上述範例中,MyUserAgentDetectionLib.DisallowsSameSiteNone 是使用者提供的程式庫,可偵測使用者代理程式是否不支援 SameSite None:

if (MyUserAgentDetectionLib.DisallowsSameSiteNone(userAgent))
{
    options.SameSite = SameSiteMode.Unspecified;
}

下列程式碼顯示範例 DisallowsSameSiteNone 方法:

Warning

下列程式碼僅供示範之用:

  • 不應將其視為完整。
  • 該程式碼不受維護或支援。
public static bool DisallowsSameSiteNone(string userAgent)
{
    // Check if a null or empty string has been passed in, since this
    // will cause further interrogation of the useragent to fail.
     if (String.IsNullOrWhiteSpace(userAgent))
        return false;
    
    // Cover all iOS based browsers here. This includes:
    // - Safari on iOS 12 for iPhone, iPod Touch, iPad
    // - WkWebview on iOS 12 for iPhone, iPod Touch, iPad
    // - Chrome on iOS 12 for iPhone, iPod Touch, iPad
    // All of which are broken by SameSite=None, because they use the iOS networking
    // stack.
    if (userAgent.Contains("CPU iPhone OS 12") ||
        userAgent.Contains("iPad; CPU OS 12"))
    {
        return true;
    }

    // Cover Mac OS X based browsers that use the Mac OS networking stack. 
    // This includes:
    // - Safari on Mac OS X.
    // This does not include:
    // - Chrome on Mac OS X
    // Because they do not use the Mac OS networking stack.
    if (userAgent.Contains("Macintosh; Intel Mac OS X 10_14") &&
        userAgent.Contains("Version/") && userAgent.Contains("Safari"))
    {
        return true;
    }

    // Cover Chrome 50-69, because some versions are broken by SameSite=None, 
    // and none in this range require it.
    // Note: this covers some pre-Chromium Edge versions, 
    // but pre-Chromium Edge does not require SameSite=None.
    if (userAgent.Contains("Chrome/5") || userAgent.Contains("Chrome/6"))
    {
        return true;
    }

    return false;
}

用於測試 SameSite 問題的應用程式

與遠端站台互動的應用程式 (例如透過第三方登入) 必須:

使用可選擇加入新 SameSite 行為的用戶端版本來測試 Web 應用程式。 Chrome、Firefox 和 Chromium Edge 都有新的需啟用功能標記可用於測試。 在您的應用程式套用 SameSite 修補檔後,請使用較舊的用戶端版本 (尤其是 Safari) 加以測試。 如需詳細資訊,請參閱本文件中的支援舊版瀏覽器。

使用 Chrome 測試

Chrome 78+ 已採取暫時性的緩解措施,因此會提供誤導性的結果。 Chrome 78+ 的暫時緩解措施允許建立時間未滿兩分鐘的 Cookie。 已啟用適當測試旗標的 Chrome 76 或 77 可提供更精確的結果。 若要測試新的 SameSite 行為,請將 chrome://flags/#same-site-by-default-cookies 切換為 啟用。 據回報,舊版的 Chrome (75 和更低版本) 在使用新的 None 設定時會失敗。 請參閱本文件中的支援舊版瀏覽器。

Google 不提供較舊的 Chrome 版本。 請依照下載 Chromium 中的指示,對舊版 Chrome 進行測試。 請不要用搜尋舊版 Chrome 所獲得的連結來下載 Chrome。

從 Canary 版本 80.0.3975.0 開始,可以基於測試目的使用新旗標 --enable-features=SameSiteDefaultChecksMethodRigorously 將 Lax+POST 暫時性緩和措施停用,以便在功能最終移除該緩和措施後的狀態下測試站台和服務。 如需詳細資訊,請參閱 Chromium Projects 的 SameSite 更新

使用 Safari 測試

Safari 12 嚴格執行先前的草案,但當新 None 值出現在 Cookie 中時會導致錯誤。 可透過本文件中的瀏覽器偵測程式碼 支援舊版瀏覽器 來避免 None。 使用 MSAL、ADAL 或您使用的任何程式庫,測試 Safari 12、Safari 13 和 WebKit 型 OS 樣式登入。 此問題取決於基礎 OS 版本。 目前已知 OSX Mojave (10.14) 和 iOS 12 會與新的 SameSite 行為發生相容性問題。 將 OS 升級至 OSX Catalina 10.15 或 iOS 13,可修正這個問題。 目前 Safari 並未提供用於測試新規格行為的啟用旗標。

使用 Firefox 測試

Firefox 對新標準的支援可在 68+ 版上進行測試,方法是在 about:config 分頁上選擇加入,並使用功能旗標 network.cookie.sameSite.laxByDefault。 目前為止並未回報任何舊版 Firefox 的相容性問題。

使用 Edge 瀏覽器進行測試

Edge 支援舊的 SameSite 標準。 Edge 44 版與新標準間沒有任何已知的相容性問題。

使用 Edge (Chromium) 進行測試

SameSite 旗標設定在 edge://flags/#same-site-by-default-cookies 頁面上。 未發現 Edge Chromium 的相容性問題。

用電子測試

Electron 的各個版本包含較舊版本的 Chromium。 例如,Teams 所使用的 Electron 版本是 Chromium 66,呈現出較舊的功能表現。 您必須針對您的產品所使用的 Electron 版本自行執行相容性測試。 請參閱下一節中的支援舊版瀏覽器。

其他資源

Sample Document
MVC ASP.NET Core 2.1 MVC SameSite cookie 範例
Razor 頁面 ASP.NET Core 2.1 Razor Pages SameSite cookie 範例