ASP.NET Core 2.1 Razor Pages SameSite cookie 示例

  • 项目

此示例以 .NET Framework 为目标

ASP.NET Core 2.1 中内置了对 SameSite 属性的支持，但它是按照原始标准编写的。 修补后的行为改变了 SameSite.None 的含义，以发出值为 None 的 sameSite 属性，而不是根本不发出该值。 如果不想发出该值，可以将 cookie 上的 SameSite 属性设置为 -1。

除了 IFrames 或 OpenIdConnect 集成等高级方案外，ASP.NET Core Identity 基本上不受 SameSite cookie 影响。

使用 Identity 时，不要添加任何 cookie 提供程序或调用 services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)，Identity 会执行这些操作。

编写 SameSite 属性

以下代码示例介绍如何在 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 the SameSite property to (SameSiteMode)(-1).
    SameSite = SameSiteMode.None
};

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

Cookie 身份验证、会话状态和各种其他组件通过 Cookie 选项设置其 sameSite 选项，例如

services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
    .AddCookie(options =>
    {
        options.Cookie.SameSite = SameSiteMode.None;
        options.Cookie.SecurePolicy = CookieSecurePolicy.Always;
        options.Cookie.IsEssential = true;
    });

services.AddSession(options =>
{
    options.Cookie.SameSite = SameSiteMode.None;
    options.Cookie.SecurePolicy = CookieSecurePolicy.Always;
    options.Cookie.IsEssential = true;
});

在上述代码中，cookie 身份验证和会话状态都将其 sameSite 属性设置为 None，发出值为 None 的属性，并将 Secure 属性设置为 true。

运行示例

如果运行的是示例项目，请在初始页面上加载浏览器调试器并使用该调试器查看站点的 cookie 集合。 若要在 Edge 和 Chrome 中执行此操作，请按 F12，然后选择 Application 选项卡并单击 Storage 部分中 Cookies 选项下的站点 URL。

Browser Debugger Cookie List

从上图中可以看出，单击“创建 SameSite Cookie”按钮时，由示例创建的 cookie 的 SameSite 属性值为 Lax，该值与示例代码中设置的值相匹配。

截获 cookie

若要截获 cookie，以便根据用户浏览器代理的支持来调整 none 值，你必须使用 CookiePolicy 中间件。 它必须放在 http 请求管道中任何写入 cookie 的组件之前，并在 ConfigureServices() 中进行配置。

若要将其插入管道，请在 Startup.cs 的 Configure(IApplicationBuilder, IHostingEnvironment) 方法中使用 app.UseCookiePolicy()。 例如：

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

    app.UseHttpsRedirection();
    app.UseStaticFiles();
    app.UseCookiePolicy();
    app.UseAuthentication();
    app.UseSession();

    app.UseMvc(routes =>
    {
        routes.MapRoute(
            name: "default",
            template: "{controller=Home}/{action=Index}/{id?}");
    });
}

然后在 ConfigureServices(IServiceCollection services) 中配置 cookie 策略，以便在追加或删除 cookie 时调用帮助程序类，如下所示：

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

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

帮助程序函数 CheckSameSite(HttpContext, CookieOptions)：

  • 在将 cookie 追加到请求或从请求中删除时调用。
  • 检查 SameSite 属性是否设置为 None。
  • 如果 SameSite 设置为 None 并且已知当前用户代理不支持 none 属性值。 使用 SameSiteSupport 类完成检查：
    • 通过将属性设置为 (SameSiteMode)(-1) 将 SameSite 设置为不发出值

面向 .NET Framework

ASP.NET Core 和 System.Web (ASP.NET 4.x) 具有独立的 SameSite 实现。 如果使用的是 ASP.NET Core，则不需要适用于 .NET Framework 的 SameSite KB 修补程序，System.Web SameSite 最低框架版本要求 (.NET Framework 4.7.2) 也不适用于 ASP.NET Core。

.NET 上的 ASP.NET Core 需要更新 NuGet 包依赖项才能获得适当的修补程序。

要获取 .NET Framework 的 ASP.NET Core 更改，请确保直接引用已修补的包和版本（2.1.14 或 2.1 以上的版本）。

<PackageReference Include="Microsoft.Net.Http.Headers" Version="2.1.14" />
<PackageReference Include="Microsoft.AspNetCore.CookiePolicy" Version="2.1.14" />

更多信息

Chrome 更新ASP.NET Core SameSite 文档ASP.NET Core 2.1 SameSite 更改公告