Fix Cookie Authentication guide flow with complete Cookie Policy Middleware integration examples

aspnetcore/security/authentication/cookie.md

@@ -1,10 +1,11 @@
 ---
 title: Use cookie authentication without ASP.NET Core Identity
+ai-usage: ai-assisted
 author: wadepickett
 description: Learn how to use cookie authentication without ASP.NET Core Identity.
 monikerRange: '>= aspnetcore-3.1'
 ms.author: wpickett
-ms.date: 1/1/2022
+ms.date: 09/12/2025
 uid: security/authentication/cookie
 ---
 # Use cookie authentication without ASP.NET Core Identity
@@ -46,22 +47,15 @@ Configure <xref:Microsoft.AspNetCore.Authentication.Cookies.CookieAuthentication
 ## Cookie Policy Middleware
 
 The 
-[Cookie Policy Middleware (GitHub Source)](https://github.com/dotnet/aspnetcore/blob/main/src/Security/CookiePolicy/src/CookiePolicyMiddleware.cs) <xref:Microsoft.AspNetCore.Builder.CookiePolicyAppBuilderExtensions.UseCookiePolicy%2A> enables cookie policy capabilities. Middleware is processed in the order it's added:
-
-```csharp
-app.UseCookiePolicy(cookiePolicyOptions);
-```
+[Cookie Policy Middleware (GitHub Source)](https://github.com/dotnet/aspnetcore/blob/main/src/Security/CookiePolicy/src/CookiePolicyMiddleware.cs) <xref:Microsoft.AspNetCore.Builder.CookiePolicyAppBuilderExtensions.UseCookiePolicy%2A> enables cookie policy capabilities. Middleware is processed in the order it's added, and Cookie Policy Middleware should be added before cookie authentication middleware.
 
 Use <xref:Microsoft.AspNetCore.Builder.CookiePolicyOptions> provided to the Cookie Policy Middleware to control global characteristics of cookie processing and hook into cookie processing handlers when cookies are appended or deleted.
 
 The default <xref:Microsoft.AspNetCore.Builder.CookiePolicyOptions.MinimumSameSitePolicy> value is `SameSiteMode.Lax` to permit OAuth2 authentication. To strictly enforce a same-site policy of `SameSiteMode.Strict`, set the `MinimumSameSitePolicy`. Although this setting breaks OAuth2 and other cross-origin authentication schemes, it elevates the level of cookie security for other types of apps that don't rely on cross-origin request processing.
 
-```csharp
-var cookiePolicyOptions = new CookiePolicyOptions
-{
-    MinimumSameSitePolicy = SameSiteMode.Strict,
-};
-```
+The following example shows how to configure cookie authentication with Cookie Policy Middleware:
+
+:::code language="csharp" source="cookie/snippets/6.0/Program.cs" id="snippet_policy" highlight="3-5,9":::
 
 The Cookie Policy Middleware setting for `MinimumSameSitePolicy` can affect the setting of `Cookie.SameSite` in `CookieAuthenticationOptions` settings according to the matrix below.
 
@@ -223,22 +217,15 @@ services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
 
 ## Cookie Policy Middleware
 
-[Cookie Policy Middleware](xref:Microsoft.AspNetCore.CookiePolicy.CookiePolicyMiddleware) enables cookie policy capabilities. Adding the middleware to the app processing pipeline is order sensitive&mdash;it only affects downstream components registered in the pipeline.
-
-```csharp
-app.UseCookiePolicy(cookiePolicyOptions);
-```
+[Cookie Policy Middleware](xref:Microsoft.AspNetCore.CookiePolicy.CookiePolicyMiddleware) enables cookie policy capabilities. Adding the middleware to the app processing pipeline is order sensitive&mdash;it only affects downstream components registered in the pipeline, and Cookie Policy Middleware should be added before cookie authentication middleware.
 
 Use <xref:Microsoft.AspNetCore.Builder.CookiePolicyOptions> provided to the Cookie Policy Middleware to control global characteristics of cookie processing and hook into cookie processing handlers when cookies are appended or deleted.
 
 The default <xref:Microsoft.AspNetCore.Builder.CookiePolicyOptions.MinimumSameSitePolicy> value is `SameSiteMode.Lax` to permit OAuth2 authentication. To strictly enforce a same-site policy of `SameSiteMode.Strict`, set the `MinimumSameSitePolicy`. Although this setting breaks OAuth2 and other cross-origin authentication schemes, it elevates the level of cookie security for other types of apps that don't rely on cross-origin request processing.
 
-```csharp
-var cookiePolicyOptions = new CookiePolicyOptions
-{
-    MinimumSameSitePolicy = SameSiteMode.Strict,
-};
-```
+The following example shows how to configure cookie authentication with Cookie Policy Middleware:
+
+:::code language="csharp" source="cookie/snippets/3.x/Startup.cs" id="snippet_policy" highlight="3-5,9":::
 
 The Cookie Policy Middleware setting for `MinimumSameSitePolicy` can affect the setting of `Cookie.SameSite` in `CookieAuthenticationOptions` settings according to the matrix below.
 

aspnetcore/security/authentication/cookie/samples/3.x/CookieSample/Startup.cs

@@ -16,14 +16,15 @@ public void ConfigureServices(IServiceCollection services)
                 options.Conventions.AuthorizePage("/Contact");
             });
 
-            #region snippet1
+            // <snippet1>
             services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
                 .AddCookie();
-            #endregion
+            // </snippet1>
 
             services.AddSingleton<IHttpContextAccessor, HttpContextAccessor>();
         }
 
+        // <snippet_policy>
         public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
         {
             if (env.IsDevelopment())
@@ -40,7 +41,13 @@ public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
             app.UseStaticFiles();
             app.UseRouting();
 
-            #region snippet2
+            var cookiePolicyOptions = new CookiePolicyOptions
+            {
+                MinimumSameSitePolicy = SameSiteMode.Strict,
+            };
+
+            app.UseCookiePolicy(cookiePolicyOptions);
+
             app.UseAuthentication();
             app.UseAuthorization();
 
@@ -49,7 +56,7 @@ public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
                 endpoints.MapControllers();
                 endpoints.MapRazorPages();
             });
-            #endregion
         }
+        // </snippet_policy>
     }
 }

aspnetcore/security/authentication/cookie/samples/6.x/CookieSample/Program.cs

@@ -1,7 +1,7 @@
-#define FIRST // FIRST SECOND CC
+#define FIRST // FIRST SECOND POLICY CC
 #if NEVER
 #elif FIRST
-#region snippet1
+// <snippet1>
 using Microsoft.AspNetCore.Authentication.Cookies;
 
 var builder = WebApplication.CreateBuilder(args);
@@ -32,9 +32,9 @@
 app.MapDefaultControllerRoute();
 
 app.Run();
-#endregion
+// </snippet1>
 #elif SECOND
-#region snippet2
+// <snippet2>
 using Microsoft.AspNetCore.Authentication.Cookies;
 
 var builder = WebApplication.CreateBuilder(args);
@@ -70,9 +70,54 @@
 app.MapDefaultControllerRoute();
 
 app.Run();
-#endregion
+// </snippet2>
+#elif POLICY
+// <snippet_policy>
+using Microsoft.AspNetCore.Authentication.Cookies;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddRazorPages();
+builder.Services.AddControllersWithViews();
+
+builder.Services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
+    .AddCookie(options =>
+    {
+        options.ExpireTimeSpan = TimeSpan.FromMinutes(20);
+        options.SlidingExpiration = true;
+        options.AccessDeniedPath = "/Forbidden/";
+    });
+
+builder.Services.AddHttpContextAccessor();
+
+var app = builder.Build();
+
+if (!app.Environment.IsDevelopment())
+{
+    app.UseExceptionHandler("/Error");
+    app.UseHsts();
+}
+
+app.UseHttpsRedirection();
+app.UseStaticFiles();
+
+var cookiePolicyOptions = new CookiePolicyOptions
+{
+    MinimumSameSitePolicy = SameSiteMode.Strict,
+};
+
+app.UseCookiePolicy(cookiePolicyOptions);
+
+app.UseAuthentication();
+app.UseAuthorization();
+
+app.MapRazorPages();
+app.MapDefaultControllerRoute();
+
+app.Run();
+// </snippet_policy>
 #elif CC
-#region snippet_cc
+// <snippet_cc>
 using Microsoft.AspNetCore.Authentication.Cookies;
 
 var builder = WebApplication.CreateBuilder(args);
@@ -106,5 +151,5 @@
 app.MapDefaultControllerRoute();
 
 app.Run();
-#endregion
+// </snippet_cc>
 #endif

aspnetcore/security/authentication/cookie/snippets/3.x/Startup.cs

@@ -0,0 +1,60 @@
+using Microsoft.AspNetCore.Authentication.Cookies;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.AspNetCore.Http;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+
+namespace CookieSample
+{
+    public class Startup
+    {
+        public void ConfigureServices(IServiceCollection services)
+        {
+            services.AddRazorPages(options =>
+            {
+                options.Conventions.AuthorizePage("/Contact");
+            });
+
+            services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
+                .AddCookie();
+
+            services.AddSingleton<IHttpContextAccessor, HttpContextAccessor>();
+        }
+
+        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
+        {
+            if (env.IsDevelopment())
+            {
+                app.UseDeveloperExceptionPage();
+            }
+            else
+            {
+                app.UseExceptionHandler("/Error");
+                app.UseHsts();
+            }
+
+            app.UseHttpsRedirection();
+            app.UseStaticFiles();
+            app.UseRouting();
+
+            // <snippet_policy>
+            var cookiePolicyOptions = new CookiePolicyOptions
+            {
+                MinimumSameSitePolicy = SameSiteMode.Strict,
+            };
+
+            app.UseCookiePolicy(cookiePolicyOptions);
+            // </snippet_policy>
+
+            app.UseAuthentication();
+            app.UseAuthorization();
+
+            app.UseEndpoints(endpoints =>
+            {
+                endpoints.MapControllers();
+                endpoints.MapRazorPages();
+            });
+        }
+    }
+}

aspnetcore/security/authentication/cookie/snippets/6.0/Program.cs

@@ -0,0 +1,44 @@
+using Microsoft.AspNetCore.Authentication.Cookies;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddRazorPages();
+builder.Services.AddControllersWithViews();
+
+builder.Services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
+    .AddCookie(options =>
+    {
+        options.ExpireTimeSpan = TimeSpan.FromMinutes(20);
+        options.SlidingExpiration = true;
+        options.AccessDeniedPath = "/Forbidden/";
+    });
+
+builder.Services.AddHttpContextAccessor();
+
+var app = builder.Build();
+
+if (!app.Environment.IsDevelopment())
+{
+    app.UseExceptionHandler("/Error");
+    app.UseHsts();
+}
+
+app.UseHttpsRedirection();
+app.UseStaticFiles();
+
+// <snippet_policy>
+var cookiePolicyOptions = new CookiePolicyOptions
+{
+    MinimumSameSitePolicy = SameSiteMode.Strict,
+};
+
+app.UseCookiePolicy(cookiePolicyOptions);
+// </snippet_policy>
+
+app.UseAuthentication();
+app.UseAuthorization();
+
+app.MapRazorPages();
+app.MapDefaultControllerRoute();
+
+app.Run();