ASP.NET Core'da SameSite tanımlama bilgileriyle çalışma

Gönderen Rick Anderson

SameSite, siteler arası istek sahteciliği (CSRF) saldırılarına karşı koruma sağlamak için tasarlanmış bir IETF taslak standardıdır. İlk olarak 2016'da taslak olarak hazırlanan taslak standardı 2019'da güncelleştirildi. Güncelleştirilmiş standart, önceki standartla geriye dönük olarak uyumlu değildir ve en belirgin farklar şunlardır:

• SameSite üst bilgisi olmayan tanımlama bilgileri varsayılan olarak olarak değerlendirilir SameSite=Lax .
• SameSite=None siteler cookie arası kullanıma izin vermek için kullanılmalıdır.
• Onaylayan SameSite=None tanımlama bilgileri de olarak Secureişaretlenmelidir.
• Kullanan <iframe> uygulamalar, siteler arası senaryolar olarak ele alındığından sameSite=Lax veya sameSite=Strict tanımlama bilgileriyle ilgili sorunlarla <iframe> karşılaşabilir.
• Değere SameSite=None 2016 standardı tarafından izin verilmez ve bazı uygulamaların bu tür tanımlama bilgilerini olarak SameSite=Strictişlemesine neden olur. Bu belgedeki Eski tarayıcıları destekleme konusuna bakın.

Bu SameSite=Lax ayar çoğu uygulama tanımlama bilgisinde çalışır. OpenID Connect (OIDC) ve WS-Federation gibi bazı kimlik doğrulama biçimleri post tabanlı yeniden yönlendirmeler olarak varsayılan olarak kullanılır. POST tabanlı yeniden yönlendirmeler SameSite tarayıcı korumalarını tetikler, bu nedenle SameSite bu bileşenler için devre dışı bırakılır. OAuth oturum açma bilgilerinin çoğu, isteğin akışındaki farklılıklardan etkilenmez.

Tanımlama bilgilerini yayan her ASP.NET Core bileşeninin SameSite'nin uygun olup olmadığını belirlemesi gerekir.

SameSite ve Identity

ASP.NET Core, veya Identity tümleştirme gibi gelişmiş senaryolar dışında SameSite tanımlama bilgilerindenIFrames.OpenIdConnect

kullanırken Identityhiçbir cookie sağlayıcı eklemeyin veya çağrısı services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)yapmayın, Identity bu işlemle ilgilenir.

SameSite test örnek kodu

Aşağıdaki örnek indirilebilir ve test edilebilir:

Sample	Document
Razor Sayfaları	ASP.NET Core 3.1 Razor Sayfaları SameSite cookie örneği

aynıSite özniteliği için .NET desteği

.NET, SameSite için 2019 taslak standardını destekler. Geliştiriciler özelliğini kullanarak HttpCookie.SameSite aynıSite özniteliğinin değerini program aracılığıyla denetleyebiliyor. özelliğinin SameSiteStrict, Laxveya None olarak ayarlanması, bu değerlerin ağ üzerinde ile yazılmasıyla cookiesonuçlanıyor. ayarı SameSiteMode.Unspecified ile aynıSitenin gönderilmemesi cookiegerektiğini belirtir.

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

SameSite ile API kullanımı

HttpContext.Response.Cookies.Append varsayılan Unspecifiedolarak kullanılır; yani öğesine sameSite özniteliği eklenmez cookie ve istemci varsayılan davranışını kullanır (Yeni tarayıcılar için Lax, eskiler için Yok). Aşağıdaki kod, SameSite değerinin cookie olarak nasıl değiştireceğini SameSiteMode.Laxgösterir:

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

Tanımlama bilgilerini yayan tüm ASP.NET Core bileşenleri, önceki varsayılanları senaryolarına uygun ayarlarla geçersiz kılar. Önceki varsayılan değerler değiştirilmedi.

Component	cookie	Default
CookieBuilder	SameSite	Unspecified
Session	SessionOptions.Cookie	Lax
CookieTempDataProvider	CookieTempDataProviderOptions.Cookie	Lax
IAntiforgery	AntiforgeryOptions.Cookie	Strict
Cookie Kimlik doğrulama	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 veya üzeri aşağıdaki SameSite desteğini sağlar:

• Yayma davranışını SameSiteMode.None yeniden tanımlar SameSite=None
• SameSite özniteliğini atlamak için yeni bir değer SameSiteMode.Unspecified ekler.
• Tüm tanımlama bilgileri API'leri varsayılan olarak kullanılır Unspecified. Tanımlama bilgileri kullanan bazı bileşenler, senaryolarına daha özel değerler ayarlar. Örnekler için yukarıdaki tabloya bakın.

ASP.NET Core 3.0 veya sonraki sürümlerinde SameSite varsayılanları, tutarsız istemci varsayılanlarıyla çakışmamak için değiştirildi. Aşağıdaki API'ler, bu tanımlama bilgileri için SameSiteMode.Lax SameSite özniteliğini yaymamak için varsayılan -1 değeri olarak değiştirmiştir:

• CookieOptions HttpContext.Response.Cookies.Append ile kullanılır
• CookieBuilder için fabrika olarak kullanılır CookieOptions
• CookiePolicyOptions.MinimumSameSitePolicy

Geçmiş ve değişiklikler

SameSite desteği ilk olarak 2016 taslak standardı kullanılarak 2.0'da ASP.NET Core'da uygulandı. 2016 standardı kabul edildi. ASP.NET Core varsayılan olarak birkaç tanımlama bilgisi Lax ayarlayarak kabul etti. Kimlik doğrulamasıyla ilgili çeşitli sorunlarla karşılaşıldıktan sonra SameSite kullanımının çoğu devre dışı bırakıldı.

Yamalar Kasım 2019'da 2016 standardından 2019 standardına güncelleştirilmek üzere yayınlanmıştır. SameSite belirtiminin 2019 taslağı:

• 2016 taslağı ile geriye dönük olarak uyumlu değildir. Daha fazla bilgi için bu belgede eski tarayıcıları destekleme konusuna bakın.
• Tanımlama bilgilerinin varsayılan olarak olarak işleniyor olduğunu SameSite=Lax belirtir.
• Siteler arası teslimi SameSite=Noneetkinleştirmek için açıkça onaylayan Secure tanımlama bilgilerini belirtir. None , geri çevirmek için yeni bir giriştir.
• ASP.NET Core 2.1, 2.2 ve 3.0 için verilen düzeltme ekleri tarafından desteklenir. ASP.NET Core 3.1 veya üzeri ek SameSite desteğine sahiptir.
• Şub 2020'de Chrome tarafından varsayılan olarak etkinleştirilmesi zamanlanmıştır. Tarayıcılar 2019'da bu standarda geçmeye başladı.

2016 SameSite taslak standardından 2019 taslak standardına yapılan değişiklikten etkilenen API'ler

• Http.SameSiteMode
• CookieOptions.SameSite
• CookieBuilder.SameSite
• CookiePolicyOptions.MinimumSameSitePolicy
• Microsoft.Net.Http.Headers.SameSiteMode
• Microsoft.Net.Http.Headers.SetCookieHeaderValue.SameSite

Eski tarayıcıları destekleme

2016 SameSite standardı, bilinmeyen değerlerin değer olarak SameSite=Strict ele alınması gerektiğini zorunlu kılındı. 2016 SameSite standardını destekleyen eski tarayıcılardan erişilen uygulamalar, değerine Nonesahip bir SameSite özelliği aldıklarında bozulabilir. Web uygulamaları, eski tarayıcıları desteklemeyi amaçlıyorsa tarayıcı algılaması uygulamalıdır. ASP.NET Core, Kullanıcı Aracıları değerleri son derece değişken olduğundan ve sık sık değiştiği için tarayıcı algılaması uygulamaz. içindeki Microsoft.AspNetCore.CookiePolicy bir uzantı noktası, User-Agent'a özgü mantığın takılmasına izin verir.

içinde Program.csçağrısı yapmadan önce UseCookiePolicy çağıran UseAuthentication kodu veya tanımlama bilgileri yazan herhangi bir yöntemi ekleyin:

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();

içinde Program.cs, aşağıdaki vurgulanan koda benzer bir kod ekleyin:

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();

Yukarıdaki örnekte, MyUserAgentDetectionLib.DisallowsSameSiteNone kullanıcı aracısının SameSite 'yi desteklemediğini algılayan, kullanıcı tarafından sağlanan bir kitaplıktır None:

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

Aşağıdaki kodda örnek DisallowsSameSiteNone bir yöntem gösterilmektedir:

Warning

Aşağıdaki kod yalnızca tanıtım amaçlıdır:

• Tamamlanmış olarak kabul edilmemelidir.
• Bakım yapılmaz veya desteklenmez.

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 sorunları için uygulamaları test etme

Üçüncü taraf oturum açma bilgileri gibi uzak sitelerle etkileşim kuran uygulamaların şunlara ihtiyacı vardır:

• Etkileşimi birden çok tarayıcıda test edin.
• Bu belgede açıklanan CookiePolicy tarayıcı algılama ve azaltmayı uygulayın.

Yeni SameSite davranışını kabul eden bir istemci sürümü kullanarak web uygulamalarını test edin. Chrome, Firefox ve Chromium Edge'in tümü test için kullanılabilecek yeni kabul etme özelliği bayraklarına sahiptir. Uygulamanız SameSite düzeltme eklerini uyguladıktan sonra, özellikle Safari olmak üzere eski istemci sürümleriyle test edin. Daha fazla bilgi için bu belgede eski tarayıcıları destekleme konusuna bakın.

Chrome ile test edin

Chrome 78+, geçici bir risk azaltmaya sahip olduğundan yanıltıcı sonuçlar verir. Chrome 78+ geçici azaltma özelliği, iki dakikadan kısa süreli tanımlama bilgilerine izin verir. Uygun test bayraklarının etkinleştirildiği Chrome 76 veya 77, daha doğru sonuçlar sağlar. Yeni SameSite davranışını test etmek için Etkin'echrome://flags/#same-site-by-default-cookies geçin. Chrome'un eski sürümleri (75 ve üzeri) yeni None ayarda başarısız olduğu bildirilir. Bu belgedeki Eski tarayıcıları destekleme konusuna bakın.

Google, eski chrome sürümlerini kullanıma sunmaz. Chrome'un eski sürümlerini test etmek için Chromium'u indirin başlığındaki yönergeleri izleyin. Chrome'un eski sürümlerini arayarak sağlanan bağlantılardan Chrome'ı indirmeyin.

• Chromium 76 Win64
• Chromium 74 Win64

Kanarya sürümünden 80.0.3975.0başlayarak, Lax+POST geçici azaltma, azaltmanın kaldırıldığı özelliğin son son durumunda sitelerin ve hizmetlerin test edilmesine izin vermek için yeni bayrağı --enable-features=SameSiteDefaultChecksMethodRigorously kullanılarak test amacıyla devre dışı bırakılabilir. Daha fazla bilgi için bkz. Chromium Projeleri SameSite Güncelleştirmeleri

Safari ile test et

Safari 12, önceki taslağı kesin olarak uyguladı ve yeni None değer içinde cookieolduğunda başarısız oluyor. None, bu belgede eski tarayıcıları destekleyen tarayıcı algılama kodu aracılığıyla önlenir. MSAL, ADAL veya kullandığınız kitaplığı kullanarak Safari 12, Safari 13 ve WebKit tabanlı işletim sistemi stili oturum açma bilgilerini test edin. Sorun, temel işletim sistemi sürümüne bağlıdır. OSX Mojave (10.14) ve iOS 12'nin yeni SameSite davranışıyla uyumluluk sorunları olduğu bilinmektedir. İşletim sistemini OSX Catalina (10.15) veya iOS 13'e yükseltmek sorunu düzeltir. Safari şu anda yeni belirtim davranışını test etmek için bir kabul etme bayrağına sahip değildir.

Firefox ile test edin

Yeni standart için Firefox desteği, özellik bayrağı about:configile sayfadan kabul edilerek network.cookie.sameSite.laxByDefault sürüm 68+ üzerinde test edilebilir. Firefox'un eski sürümleriyle ilgili uyumluluk sorunları bildirilmemiştir.

Edge tarayıcısıyla test edin

Edge, eski SameSite standardını destekler. Edge sürüm 44'de yeni standartla ilgili bilinen bir uyumluluk sorunu yoktur.

Edge ile Test (Chromium)

Sayfada SameSite bayrakları ayarlanır edge://flags/#same-site-by-default-cookies . Edge Chromium'da uyumluluk sorunu bulunamadı.

Ile test edin Electron

sürümleri Electron Chromium'un eski sürümlerini içerir. Örneğin, Teams tarafından kullanılan sürümü, eski davranışı gösteren Chromium 66 sürümüdür Electron . Ürününüzün kullandığı sürümle Electron kendi uyumluluk testinizi gerçekleştirmeniz gerekir. Aşağıdaki bölümde eski tarayıcıları destekleme bölümüne bakın.

Ek kaynaklar

• Chromium Blogu:Geliştiriciler: New SameSite=None için Hazırlanın; Güvenli Cookie Ayarlar
• SameSite tanımlama bilgileri açıklandı
• Kasım 2019 Yamaları

Sample	Document
Razor Sayfaları	ASP.NET Core 3.1 Razor Sayfaları SameSite cookie örneği