Add breaking change for ASP.NET Core 3.0

docs/core/compatibility/2.2-3.0.md

@@ -1,7 +1,7 @@
 ---
 title: Breaking changes, version 2.2 to 3.0 - .NET Core
 description: Lists the breaking changes from version 2.2 to version 3.0 of .NET Core, ASP.NET Core, and EF Core.
-ms.date: "10/16/2019"
+ms.date: "11/20/2019"
 ---
 # Breaking changes for migration from Version 2.2 to 3.0
 
@@ -81,6 +81,10 @@ If you're migrating from version 2.2 to version 3.0 of .NET Core, ASP.NET Core,
 
 ***
 
+[!INCLUDE[HTTP: Some cookie SameSite default values changed](~/includes/core-changes/aspnetcore/3.0/http-cookie-samesite-defaults-change.md)]
+
+***
+
 [!INCLUDE[HTTP: Synchronous IO disabled by default](~/includes/core-changes/aspnetcore/3.0/http-synchronous-io-disabled.md)]
 
 ***

docs/core/compatibility/aspnetcore.md

@@ -1,7 +1,7 @@
 ---
 title: ASP.NET Core breaking changes - .NET Core
 description: Lists the breaking changes in ASP.NET Core.
-ms.date: "10/17/2019"
+ms.date: "11/20/2019"
 author: "scottaddie"
 ms.author: "scaddie"
 ---
@@ -83,6 +83,10 @@ The following is a list of ASP.NET Core breaking changes by ASP.NET Core version
 
 ***
 
+[!INCLUDE[HTTP: Some cookie SameSite default values changed](~/includes/core-changes/aspnetcore/3.0/http-cookie-samesite-defaults-change.md)]
+
+***
+
 [!INCLUDE[HTTP: Synchronous IO disabled by default](~/includes/core-changes/aspnetcore/3.0/http-synchronous-io-disabled.md)]
 
 ***

includes/core-changes/aspnetcore/3.0/http-cookie-samesite-defaults-change.md

@@ -0,0 +1,41 @@
+### HTTP: Some cookie SameSite defaults changed to None
+
+`SameSite` is an option for cookies that can help mitigate some Cross-Site Request Forgery (CSRF) attacks. When this option was initially introduced, inconsistent defaults were used across various ASP.NET Core APIs. The inconsistency has led to confusing results. As of ASP.NET Core 3.0, these defaults are better aligned. You must opt in to this feature on a per-component basis.
+
+#### Version introduced
+
+3.0
+
+#### Old behavior
+
+Similar ASP.NET Core APIs used different default <xref:Microsoft.AspNetCore.Http.SameSiteMode> values. An example of the inconsistency is seen in `HttpResponse.Cookies.Append(String, String)` and `HttpResponse.Cookies.Append(String, String, CookieOptions)`, which defaulted to `SameSiteMode.None` and `SameSiteMode.Lax`, respectively.
+
+#### New behavior
+
+All the affected APIs default to `SameSiteMode.None`.
+
+#### Reason for change
+
+The default value was changed to make `SameSite` an opt-in feature.
+
+#### Recommended action
+
+Each component that emits cookies needs to decide if `SameSite` is appropriate for its scenarios. Review your usage of the affected APIs and reconfigure `SameSite` as needed.
+
+#### Category
+
+ASP.NET Core
+
+#### Affected APIs
+
+- <xref:Microsoft.AspNetCore.Http.IResponseCookies.Append(System.String,System.String,Microsoft.AspNetCore.Http.CookieOptions)?displayProperty=nameWithType>
+- <xref:Microsoft.AspNetCore.Builder.CookiePolicyOptions.MinimumSameSitePolicy%2A?displayProperty=nameWithType>
+
+<!--
+
+#### Affected APIs
+
+- `M:Microsoft.AspNetCore.Http.IResponseCookies.Append(System.String,System.String,Microsoft.AspNetCore.Http.CookieOptions)`
+- `Overload:Microsoft.AspNetCore.Builder.CookiePolicyOptions.MinimumSameSitePolicy`
+
+-->