Unifying API for configuring cookie settings

[natemcmaster]

2.0.0 will introduce changes that help unify API for configuring cookie settings in various ASP.NET Core components.

The current API will be marked [Obsolete] and removed in a future version. Although these obsolete API will continue to function as they do in 1.x, we recommend moving to the new API soon. (See below).

For more discussion on this issue, use aspnet/HttpAbstractions#853.

Associated PRs:
aspnet/HttpAbstractions#882
aspnet/Security#1284
aspnet/Security#1285
aspnet/Session#173
aspnet/Mvc#6472
aspnet/Antiforgery#148

Recommended changes

Update your code from the obsolete API to the new API.

Antiforgery

public void ConfigureServices(ServiceCollection services)
{
    services.AddAntiforgery(options =>
    {
        // obsolete
        options.CookieName = "AntiforgeryCookie";
        options.CookieDomain = "contoso.com";
        options.CookiePath = "/";
        options.RequireSsl = true;
        // new API
        options.Cookie.Name = "AntiforgeryCookie";
        options.Cookie.Domain = "contoso.com";
        options.Cookie.Path = "/";
        options.Cookie.SecurePolicy = CookieSecurePolicy.Always;
    });
}

Session

public void ConfigureServices(ServiceCollection services)
{
    services.AddSession(options =>
    {
        // obsolete
        options.CookieName = "SessionCookie";
        options.CookieDomain = "contoso.com";
        options.CookiePath = "/";
        options.CookieHttpOnly = true;
        options.CookieSecure = CookieSecurePolicy.Always;
        // new API
        options.Cookie.Name = "SessionCookie";
        options.Cookie.Domain = "contoso.com";
        options.Cookie.Path = "/";
        options.Cookie.HttpOnly = true;
        options.Cookie.SecurePolicy = CookieSecurePolicy.Always;
    });
}

Cookie authentication

public void ConfigureServices(ServiceCollection services)
{
    // same is applies anywhere CookieAuthenticationOptions is used,
    // such as `services.AddCookieAuthentication(Action<CookieAuthenticationOptions> configureOptions)`
    app.AddAuthentication()
        .AddCookie(options =>
        {
            // obsolete
            options.CookieName = "AuthCookie";
            options.CookieDomain = "contoso.com";
            options.CookiePath = "/";
            options.CookieHttpOnly = true;
            options.CookieSameSite = SameSiteMode.Lax;
            options.CookieSecure = CookieSecurePolicy.Always;

            // new API
            options.Cookie.Name = "AuthCookie";
            options.Cookie.Domain = "contoso.com";
            options.Cookie.Path = "/";
            options.Cookie.HttpOnly = true;
            options.Cookie.SameSite = SameSiteMode.Lax;
            options.Cookie.SecurePolicy = CookieSecurePolicy.Always;
        });
}

MVC

public void ConfigureServices(ServiceCollection services)
{
    app.AddMvc()
        .AddCookieTempDataProvider(options =>
        {
            // obsolete
            options.CookieName = "TempDataCookie";
            options.Domain = "contoso.com";
            options.Path = "/";

            // new API
            options.Cookie.Name = "TempDataCookie";
            options.Cookie.Domain = "contoso.com";
            options.Cookie.Path = "/";
        });
}