aspnetcore/security/samesite.md
SameSite is an IETF draft standard designed to provide some protection against cross-site request forgery (CSRF) attacks. Originally drafted in 2016, the draft standard was updated in 2019. The updated standard is not backward compatible with the previous standard, with the following being the most noticeable differences:
SameSite=Lax by default.SameSite=None must be used to allow cross-site cookie use.SameSite=None must also be marked as Secure.<iframe> may experience issues with sameSite=Lax or sameSite=Strict cookies because <iframe> is treated as cross-site scenarios.SameSite=None is not allowed by the 2016 standard and causes some implementations to treat such cookies as SameSite=Strict. See Supporting older browsers in this document.The SameSite=Lax setting works for most application cookies. Some forms of authentication like OpenID Connect (OIDC) and WS-Federation default to POST based redirects. The POST based redirects trigger the SameSite browser protections, so SameSite is disabled for these components. Most OAuth logins are not affected due to differences in how the request flows.
Each ASP.NET Core component that emits cookies needs to decide if SameSite is appropriate.
:::moniker range=">= aspnetcore-6.0"
The following sample can be downloaded and tested:
| Sample | Document |
|---|---|
| Razor Pages | xref:security/samesite/rp31 |
.NET supports the 2019 draft standard for SameSite. Developers are able to programmatically control the value of the sameSite attribute using the HttpCookie.SameSite property. Setting the SameSite property to Strict, Lax, or None results in those values being written on the network with the cookie. Setting to SameSiteMode.Unspecified indicates no sameSite should be sent with the cookie.
HttpContext.Response.Cookies.Append defaults to Unspecified, meaning no SameSite attribute added to the cookie and the client will use its default behavior (Lax for new browsers, None for old ones). The following code shows how to change the cookie SameSite value to SameSiteMode.Lax:
All ASP.NET Core components that emit cookies override the preceding defaults with settings appropriate for their scenarios. The overridden preceding default values haven't changed.
| Component | cookie | Default |
| ------------- | ------------- |
| xref:Microsoft.AspNetCore.Http.CookieBuilder | xref:Microsoft.AspNetCore.Http.CookieBuilder.SameSite | Unspecified |
| xref:Microsoft.AspNetCore.Http.HttpContext.Session | SessionOptions.Cookie |Lax |
| xref:Microsoft.AspNetCore.Mvc.ViewFeatures.CookieTempDataProvider | CookieTempDataProviderOptions.Cookie | Lax |
| xref:Microsoft.AspNetCore.Antiforgery.IAntiforgery | AntiforgeryOptions.Cookie| Strict |
| Cookie Authentication | CookieAuthenticationOptions.Cookie | Lax |
| xref:Microsoft.Extensions.DependencyInjection.TwitterExtensions.AddTwitter* | TwitterOptions.StateCookie | Lax |
| xref:Microsoft.AspNetCore.Authentication.RemoteAuthenticationHandler`1 | RemoteAuthenticationOptions.CorrelationCookie | None |
| xref:Microsoft.Extensions.DependencyInjection.OpenIdConnectExtensions.AddOpenIdConnect* | OpenIdConnectOptions.NonceCookie| None |
| HttpContext.Response.Cookies.Append | xref:Microsoft.AspNetCore.Http.CookieOptions | Unspecified |
ASP.NET Core 3.1 or later provides the following SameSite support:
SameSiteMode.None to emit SameSite=NoneSameSiteMode.Unspecified to omit the SameSite attribute.Unspecified. Some components that use cookies set values more specific to their scenarios. See the table above for examples.In ASP.NET Core 3.0 or later the SameSite defaults were changed to avoid conflicting with inconsistent client defaults. The following APIs have changed the default from SameSiteMode.Lax to -1 to avoid emitting a SameSite attribute for these cookies:
CookieOptionsSameSite support was first implemented in ASP.NET Core in 2.0 using the 2016 draft standard. The 2016 standard was opt-in. ASP.NET Core opted-in by setting several cookies to Lax by default. After encountering several issues with authentication, most SameSite usage was disabled.
Patches were issued in November 2019 to update from the 2016 standard to the 2019 standard. The 2019 draft of the SameSite specification:
SameSite=Lax by default.SameSite=None in order to enable cross-site delivery should be marked as Secure. None is a new entry to opt out.<a name="sob"></a>
The 2016 SameSite standard mandated that unknown values must be treated as SameSite=Strict values. Apps accessed from older browsers which support the 2016 SameSite standard may break when they get a SameSite property with a value of None. Web apps must implement browser detection if they intend to support older browsers. ASP.NET Core doesn't implement browser detection because User-Agents values are highly volatile and change frequently. An extension point in xref:Microsoft.AspNetCore.CookiePolicy allows plugging in User-Agent specific logic.
In Program.cs, add code that calls xref:Microsoft.AspNetCore.Builder.CookiePolicyAppBuilderExtensions.UseCookiePolicy* before calling xref:Microsoft.AspNetCore.Builder.AuthAppBuilderExtensions.UseAuthentication* or any method that writes cookies:
In Program.cs, add code similar to the following highlighted code:
In the preceding sample, MyUserAgentDetectionLib.DisallowsSameSiteNone is a user supplied library that detects if the user agent doesn't support SameSite None:
The following code shows a sample DisallowsSameSiteNone method:
[!WARNING] The following code is for demonstration only:
- It should not be considered complete.
- It is not maintained or supported.
Apps that interact with remote sites such as through third-party login need to:
Test web apps using a client version that can opt-in to the new SameSite behavior. Chrome, Firefox, and Chromium Edge all have new opt-in feature flags that can be used for testing. After your app applies the SameSite patches, test it with older client versions, especially Safari. For more information, see Supporting older browsers in this document.
Chrome 78+ gives misleading results because it has a temporary mitigation in place. The Chrome 78+ temporary mitigation allows cookies less than two minutes old. Chrome 76 or 77 with the appropriate test flags enabled provides more accurate results. To test the new SameSite behavior toggle chrome://flags/#same-site-by-default-cookies to Enabled. Older versions of Chrome (75 and below) are reported to fail with the new None setting. See Supporting older browsers in this document.
Google does not make older chrome versions available. Follow the instructions at Download Chromium to test older versions of Chrome. Do not download Chrome from links provided by searching for older versions of chrome.
Starting in Canary version 80.0.3975.0, the Lax+POST temporary mitigation can be disabled for testing purposes using the new flag --enable-features=SameSiteDefaultChecksMethodRigorously to allow testing of sites and services in the eventual end state of the feature where the mitigation has been removed. For more information, see The Chromium Projects SameSite Updates
Safari 12 strictly implemented the prior draft and fails when the new None value is in a cookie. None is avoided via the browser detection code Supporting older browsers in this document. Test Safari 12, Safari 13, and WebKit based OS style logins using MSAL, ADAL or whatever library you are using. The problem is dependent on the underlying OS version. OSX Mojave (10.14) and iOS 12 are known to have compatibility problems with the new SameSite behavior. Upgrading the OS to OSX Catalina (10.15) or iOS 13 fixes the problem. Safari does not currently have an opt-in flag for testing the new spec behavior.
Firefox support for the new standard can be tested on version 68+ by opting in on the about:config page with the feature flag network.cookie.sameSite.laxByDefault. There haven't been reports of compatibility issues with older versions of Firefox.
Edge supports the old SameSite standard. Edge version 44 doesn't have any known compatibility problems with the new standard.
SameSite flags are set on the edge://flags/#same-site-by-default-cookies page. No compatibility issues were discovered with Edge Chromium.
Versions of :::no-loc text="Electron"::: include older versions of Chromium. For example, the version of :::no-loc text="Electron"::: used by Teams is Chromium 66, which exhibits the older behavior. You must perform your own compatibility testing with the version of :::no-loc text="Electron"::: your product uses. See Supporting older browsers in the following section.
| Sample | Document |
|---|---|
| Razor Pages | xref:security/samesite/rp31 |
:::moniker-end
:::moniker range=">= aspnetcore-3.0 < aspnetcore-6.0"
The following sample can be downloaded and tested:
| Sample | Document |
|---|---|
| Razor Pages | xref:security/samesite/rp31 |
.NET Core 3.1 or later support the 2019 draft standard for SameSite. Developers are able to programmatically control the value of the sameSite attribute using the HttpCookie.SameSite property. Setting the SameSite property to Strict, Lax, or None results in those values being written on the network with the cookie. Setting it equal to (SameSiteMode)(-1) indicates that no sameSite attribute should be included on the network with the cookie
.NET Core 3.1 or later support the updated SameSite values and adds an extra enum value, SameSiteMode.Unspecified to the SameSiteMode enum.
This new value indicates no sameSite should be sent with the cookie.
HttpContext.Response.Cookies.Append defaults to Unspecified, meaning no SameSite attribute added to the cookie and the client will use its default behavior (Lax for new browsers, None for old ones). The following code shows how to change the cookie SameSite value to SameSiteMode.Lax:
All ASP.NET Core components that emit cookies override the preceding defaults with settings appropriate for their scenarios. The overridden preceding default values haven't changed.
| Component | cookie | Default |
| ------------- | ------------- |
| xref:Microsoft.AspNetCore.Http.CookieBuilder | xref:Microsoft.AspNetCore.Http.CookieBuilder.SameSite | Unspecified |
| xref:Microsoft.AspNetCore.Http.HttpContext.Session | SessionOptions.Cookie |Lax |
| xref:Microsoft.AspNetCore.Mvc.ViewFeatures.CookieTempDataProvider | CookieTempDataProviderOptions.Cookie | Lax |
| xref:Microsoft.AspNetCore.Antiforgery.IAntiforgery | AntiforgeryOptions.Cookie| Strict |
| Cookie Authentication | CookieAuthenticationOptions.Cookie | Lax |
| xref:Microsoft.Extensions.DependencyInjection.TwitterExtensions.AddTwitter* | TwitterOptions.StateCookie | Lax |
| xref:Microsoft.AspNetCore.Authentication.RemoteAuthenticationHandler`1 | RemoteAuthenticationOptions.CorrelationCookie | None |
| xref:Microsoft.Extensions.DependencyInjection.OpenIdConnectExtensions.AddOpenIdConnect* | OpenIdConnectOptions.NonceCookie| None |
| HttpContext.Response.Cookies.Append | xref:Microsoft.AspNetCore.Http.CookieOptions | Unspecified |
ASP.NET Core 3.1 or later provides the following SameSite support:
SameSiteMode.None to emit SameSite=NoneSameSiteMode.Unspecified to omit the SameSite attribute.Unspecified. Some components that use cookies set values more specific to their scenarios. See the table above for examples.In ASP.NET Core 3.0 or later the SameSite defaults were changed to avoid conflicting with inconsistent client defaults. The following APIs have changed the default from SameSiteMode.Lax to -1 to avoid emitting a SameSite attribute for these cookies:
CookieOptionsSameSite support was first implemented in ASP.NET Core in 2.0 using the 2016 draft standard. The 2016 standard was opt-in. ASP.NET Core opted-in by setting several cookies to Lax by default. After encountering several issues with authentication, most SameSite usage was disabled.
Patches were issued in November 2019 to update from the 2016 standard to the 2019 standard. The 2019 draft of the SameSite specification:
SameSite=Lax by default.SameSite=None in order to enable cross-site delivery should be marked as Secure. None is a new entry to opt out.<a name="sob"></a>
The 2016 SameSite standard mandated that unknown values must be treated as SameSite=Strict values. Apps accessed from older browsers which support the 2016 SameSite standard may break when they get a SameSite property with a value of None. Web apps must implement browser detection if they intend to support older browsers. ASP.NET Core doesn't implement browser detection because User-Agents values are highly volatile and change frequently. An extension point in xref:Microsoft.AspNetCore.CookiePolicy allows plugging in User-Agent specific logic.
In Startup.Configure, add code that calls xref:Microsoft.AspNetCore.Builder.CookiePolicyAppBuilderExtensions.UseCookiePolicy* before calling xref:Microsoft.AspNetCore.Builder.AuthAppBuilderExtensions.UseAuthentication* or any method that writes cookies:
In Startup.ConfigureServices, add code similar to the following:
In the preceding sample, MyUserAgentDetectionLib.DisallowsSameSiteNone is a user supplied library that detects if the user agent doesn't support SameSite None:
The following code shows a sample DisallowsSameSiteNone method:
[!WARNING] The following code is for demonstration only:
- It should not be considered complete.
- It is not maintained or supported.
Apps that interact with remote sites such as through third-party login need to:
Test web apps using a client version that can opt-in to the new SameSite behavior. Chrome, Firefox, and Chromium Edge all have new opt-in feature flags that can be used for testing. After your app applies the SameSite patches, test it with older client versions, especially Safari. For more information, see Supporting older browsers in this document.
Chrome 78+ gives misleading results because it has a temporary mitigation in place. The Chrome 78+ temporary mitigation allows cookies less than two minutes old. Chrome 76 or 77 with the appropriate test flags enabled provides more accurate results. To test the new SameSite behavior toggle chrome://flags/#same-site-by-default-cookies to Enabled. Older versions of Chrome (75 and below) are reported to fail with the new None setting. See Supporting older browsers in this document.
Google does not make older chrome versions available. Follow the instructions at Download Chromium to test older versions of Chrome. Do not download Chrome from links provided by searching for older versions of chrome.
Starting in Canary version 80.0.3975.0, the Lax+POST temporary mitigation can be disabled for testing purposes using the new flag --enable-features=SameSiteDefaultChecksMethodRigorously to allow testing of sites and services in the eventual end state of the feature where the mitigation has been removed. For more information, see The Chromium Projects SameSite Updates
Safari 12 strictly implemented the prior draft and fails when the new None value is in a cookie. None is avoided via the browser detection code Supporting older browsers in this document. Test Safari 12, Safari 13, and WebKit based OS style logins using MSAL, ADAL or whatever library you are using. The problem is dependent on the underlying OS version. OSX Mojave (10.14) and iOS 12 are known to have compatibility problems with the new SameSite behavior. Upgrading the OS to OSX Catalina (10.15) or iOS 13 fixes the problem. Safari does not currently have an opt-in flag for testing the new spec behavior.
Firefox support for the new standard can be tested on version 68+ by opting in on the about:config page with the feature flag network.cookie.sameSite.laxByDefault. There haven't been reports of compatibility issues with older versions of Firefox.
Edge supports the old SameSite standard. Edge version 44 doesn't have any known compatibility problems with the new standard.
SameSite flags are set on the edge://flags/#same-site-by-default-cookies page. No compatibility issues were discovered with Edge Chromium.
Versions of :::no-loc text="Electron"::: include older versions of Chromium. For example, the version of :::no-loc text="Electron"::: used by Teams is Chromium 66, which exhibits the older behavior. You must perform your own compatibility testing with the version of :::no-loc text="Electron"::: your product uses. See Supporting older browsers in the following section.
| Sample | Document |
|---|---|
| Razor Pages | xref:security/samesite/rp31 |
:::moniker-end
:::moniker range="< aspnetcore-3.0"
The following samples can be downloaded and tested:
| Sample | Document |
|---|---|
| MVC | xref:security/samesite/mvc21 |
| Razor Pages | xref:security/samesite/rp21 |
The specific behavior change for .NET Framework and .NET Core 2.1 is how the SameSite property interprets the None value. Before the patch a value of None meant "Do not emit the attribute at all", after the patch it means "Emit the attribute with a value of None". After the patch a SameSite value of (SameSiteMode)(-1) causes the attribute not to be emitted.
The default SameSite value for forms authentication and session state cookies was changed from None to Lax.
HttpContext.Response.Cookies.Append defaults to Unspecified, meaning no SameSite attribute added to the cookie and the client will use its default behavior (Lax for new browsers, None for old ones). The following code shows how to change the cookie SameSite value to SameSiteMode.Lax:
All ASP.NET Core components that emit cookies override the preceding defaults with settings appropriate for their scenarios. The overridden preceding default values haven't changed.
| Component | cookie | Default |
| ------------- | ------------- |
| xref:Microsoft.AspNetCore.Http.CookieBuilder | xref:Microsoft.AspNetCore.Http.CookieBuilder.SameSite | Unspecified |
| xref:Microsoft.AspNetCore.Http.HttpContext.Session | SessionOptions.Cookie |Lax |
| xref:Microsoft.AspNetCore.Mvc.ViewFeatures.CookieTempDataProvider | CookieTempDataProviderOptions.Cookie | Lax |
| xref:Microsoft.AspNetCore.Antiforgery.IAntiforgery | AntiforgeryOptions.Cookie| Strict |
| Cookie Authentication | CookieAuthenticationOptions.Cookie | Lax |
| xref:Microsoft.Extensions.DependencyInjection.TwitterExtensions.AddTwitter* | TwitterOptions.StateCookie | Lax |
| xref:Microsoft.AspNetCore.Authentication.RemoteAuthenticationHandler`1 | RemoteAuthenticationOptions.CorrelationCookie | None |
| xref:Microsoft.Extensions.DependencyInjection.OpenIdConnectExtensions.AddOpenIdConnect* | OpenIdConnectOptions.NonceCookie| None |
| HttpContext.Response.Cookies.Append | xref:Microsoft.AspNetCore.Http.CookieOptions | Unspecified |
SameSite support was first implemented in ASP.NET Core in 2.0 using the 2016 draft standard. The 2016 standard was opt-in. ASP.NET Core opted-in by setting several cookies to Lax by default. After encountering several issues with authentication, most SameSite usage was disabled.
Patches were issued in November 2019 to update from the 2016 standard to the 2019 standard. The 2019 draft of the SameSite specification:
SameSite=Lax by default.SameSite=None in order to enable cross-site delivery should be marked as Secure. None is a new entry to opt out.<a name="sob"></a>
The 2016 SameSite standard mandated that unknown values must be treated as SameSite=Strict values. Apps accessed from older browsers which support the 2016 SameSite standard may break when they get a SameSite property with a value of None. Web apps must implement browser detection if they intend to support older browsers. ASP.NET Core doesn't implement browser detection because User-Agents values are highly volatile and change frequently. An extension point in xref:Microsoft.AspNetCore.CookiePolicy allows plugging in User-Agent specific logic.
In Startup.Configure, add code that calls xref:Microsoft.AspNetCore.Builder.CookiePolicyAppBuilderExtensions.UseCookiePolicy* before calling xref:Microsoft.AspNetCore.Builder.AuthAppBuilderExtensions.UseAuthentication* or any method that writes cookies:
In Startup.ConfigureServices, add code similar to the following:
In the preceding sample, MyUserAgentDetectionLib.DisallowsSameSiteNone is a user supplied library that detects if the user agent doesn't support SameSite None:
The following code shows a sample DisallowsSameSiteNone method:
[!WARNING] The following code is for demonstration only:
- It should not be considered complete.
- It is not maintained or supported.
Apps that interact with remote sites such as through third-party login need to:
Test web apps using a client version that can opt-in to the new SameSite behavior. Chrome, Firefox, and Chromium Edge all have new opt-in feature flags that can be used for testing. After your app applies the SameSite patches, test it with older client versions, especially Safari. For more information, see Supporting older browsers in this document.
Chrome 78+ gives misleading results because it has a temporary mitigation in place. The Chrome 78+ temporary mitigation allows cookies less than two minutes old. Chrome 76 or 77 with the appropriate test flags enabled provides more accurate results. To test the new SameSite behavior toggle chrome://flags/#same-site-by-default-cookies to Enabled. Older versions of Chrome (75 and below) are reported to fail with the new None setting. See Supporting older browsers in this document.
Google does not make older chrome versions available. Follow the instructions at Download Chromium to test older versions of Chrome. Do not download Chrome from links provided by searching for older versions of chrome.
Starting in Canary version 80.0.3975.0, the Lax+POST temporary mitigation can be disabled for testing purposes using the new flag --enable-features=SameSiteDefaultChecksMethodRigorously to allow testing of sites and services in the eventual end state of the feature where the mitigation has been removed. For more information, see The Chromium Projects SameSite Updates
Safari 12 strictly implemented the prior draft and fails when the new None value is in a cookie. None is avoided via the browser detection code Supporting older browsers in this document. Test Safari 12, Safari 13, and WebKit based OS style logins using MSAL, ADAL or whatever library you are using. The problem is dependent on the underlying OS version. OSX Mojave (10.14) and iOS 12 are known to have compatibility problems with the new SameSite behavior. Upgrading the OS to OSX Catalina (10.15) or iOS 13 fixes the problem. Safari does not currently have an opt-in flag for testing the new spec behavior.
Firefox support for the new standard can be tested on version 68+ by opting in on the about:config page with the feature flag network.cookie.sameSite.laxByDefault. There haven't been reports of compatibility issues with older versions of Firefox.
Edge supports the old SameSite standard. Edge version 44 doesn't have any known compatibility problems with the new standard.
SameSite flags are set on the edge://flags/#same-site-by-default-cookies page. No compatibility issues were discovered with Edge Chromium.
Versions of :::no-loc text="Electron"::: include older versions of Chromium. For example, the version of :::no-loc text="Electron"::: used by Teams is Chromium 66, which exhibits the older behavior. You must perform your own compatibility testing with the version of :::no-loc text="Electron"::: your product uses. See Supporting older browsers in the following section.
| Sample | Document |
|---|---|
| MVC | xref:security/samesite/mvc21 |
| Razor Pages | xref:security/samesite/rp21 |
:::moniker-end