Skip to content

Commit d1d7a39

Browse files
guardrexguardrex
committed
Clarifications on the antiforgery secure policy
1 parent 5ff72a6 commit d1d7a39

1 file changed

Lines changed: 93 additions & 14 deletions

File tree

‎aspnetcore/security/anti-request-forgery.md‎

Lines changed: 93 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
---
22
title: Prevent Cross-Site Request Forgery (XSRF/CSRF) attacks in ASP.NET Core
3+
ai-usage: ai-assisted
34
author: tdykstra
4-
description: Discover how to prevent attacks against web apps where a malicious website can influence the interaction between a client browser and the app.
5-
ms.author: tdykstra
65
content_well_notification: AI-contribution
6+
description: Discover how to prevent attacks against web apps where a malicious website can influence the interaction between a client browser and the app.
77
monikerRange: '>= aspnetcore-3.1'
8+
ms.author: tdykstra
89
ms.custom: mvc
910
ms.date: 11/16/2023
1011
uid: security/anti-request-forgery
11-
ai-usage: ai-assisted
1212
---
1313
# Prevent Cross-Site Request Forgery (XSRF/CSRF) attacks in ASP.NET Core
1414

@@ -161,14 +161,13 @@ Calling <xref:Microsoft.Extensions.DependencyInjection.MvcServiceCollectionExten
161161

162162
Multiple tabs logged in as different users, or one logged in as anonymous, are not supported.
163163

164-
165164
## Configure antiforgery with `AntiforgeryOptions`
166165

167-
Customize <xref:Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions> in `Program.cs`:
166+
Customize <xref:Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions> in the app's `Program` file:
168167

169168
:::code language="csharp" source="anti-request-forgery/samples/6.x/AntiRequestForgerySample/Snippets/Program.cs" id="snippet_AddAntiforgeryOptions":::
170169

171-
Set the antiforgery `Cookie` properties using the properties of the <xref:Microsoft.AspNetCore.Http.CookieBuilder> class, as shown in the following table.
170+
Set the antiforgery cookie properties using the properties of the <xref:Microsoft.AspNetCore.Http.CookieBuilder> class, as shown in the following table.
172171

173172
| Option | Description |
174173
| --- | --- |
@@ -177,6 +176,22 @@ Set the antiforgery `Cookie` properties using the properties of the <xref:Micros
177176
| <xref:Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions.HeaderName%2A> | The name of the header used by the antiforgery system. If `null`, the system considers only form data. |
178177
| <xref:Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions.SuppressXFrameOptionsHeader%2A> | Specifies whether to suppress generation of the `X-Frame-Options` header. By default, the header is generated with a value of "SAMEORIGIN". Defaults to `false`. |
179178

179+
180+
181+
Some browsers don't allow insecure endpoints to set cookies with a 'secure' flag or overwrite cookies whose 'secure' flag is set (for more information, see [Deprecate modification of 'secure' cookies from non-secure origins](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-cookie-alone-01)). Since mixing secure and insecure endpoints is a common scenario in apps, ASP.NET Core relaxes the restriction on the secure policy on some cookies, such as the antiforgery cookie, by setting the cookie's <xref:Microsoft.AspNetCore.Http.CookieBuilder.SecurePolicy%2A> to [`CookieSecurePolicy.None`](xref:Microsoft.AspNetCore.Http.CookieSecurePolicy). Even if a malicious user steals an antiforgery cookie, they also must steal the antiforgery token that's typically sent via a form field (more common) or a separate request header (less common). Cookies related to authentication or authorization use a stronger policy than [`CookieSecurePolicy.None`](xref:Microsoft.AspNetCore.Http.CookieSecurePolicy).
182+
183+
Optionally, you can secure the antiforgery cookie in non-Development environments using Secure Sockets Layer (SSL), over HTTPS only, with the following <xref:Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions.Cookie%2A?displayProperty=nameWithType> property setting in the app's `Program` file:
184+
185+
```csharp
186+
if (!builder.Environment.IsDevelopment())
187+
{
188+
builder.Services.AddAntiforgery(o =>
189+
{
190+
o.Cookie.SecurePolicy = CookieSecurePolicy.Always;
191+
});
192+
}
193+
```
194+
180195
For more information, see <xref:Microsoft.AspNetCore.Builder.CookieAuthenticationOptions>.
181196

182197
## Generate antiforgery tokens with `IAntiforgery`
@@ -481,15 +496,15 @@ With the Synchronizer Token Pattern, only the most recently loaded page contains
481496
* Only the most recently loaded tab contains a valid antiforgery token.
482497
* Requests made from previously loaded tabs fail with an error: `Antiforgery token validation failed. The antiforgery cookie token and request token do not match`
483498

484-
Consider alternative CSRF protection patterns if this poses an issue.
499+
Consider alternative CSRF protection patterns if this poses an issue.
485500

486501
## Configure antiforgery with `AntiforgeryOptions`
487502

488-
Customize <xref:Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions> in `Program.cs`:
503+
Customize <xref:Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions> in the app's `Program` file:
489504

490505
:::code language="csharp" source="anti-request-forgery/samples/6.x/AntiRequestForgerySample/Snippets/Program.cs" id="snippet_AddAntiforgeryOptions":::
491506

492-
Set the antiforgery `Cookie` properties using the properties of the <xref:Microsoft.AspNetCore.Http.CookieBuilder> class, as shown in the following table.
507+
Set the antiforgery cookie properties using the properties of the <xref:Microsoft.AspNetCore.Http.CookieBuilder> class, as shown in the following table.
493508

494509
| Option | Description |
495510
| --- | --- |
@@ -498,6 +513,20 @@ Set the antiforgery `Cookie` properties using the properties of the <xref:Micros
498513
| <xref:Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions.HeaderName%2A> | The name of the header used by the antiforgery system. If `null`, the system considers only form data. |
499514
| <xref:Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions.SuppressXFrameOptionsHeader%2A> | Specifies whether to suppress generation of the `X-Frame-Options` header. By default, the header is generated with a value of "SAMEORIGIN". Defaults to `false`. |
500515

516+
Some browsers don't allow insecure endpoints to set cookies with a 'secure' flag or overwrite cookies whose 'secure' flag is set (for more information, see [Deprecate modification of 'secure' cookies from non-secure origins](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-cookie-alone-01)). Since mixing secure and insecure endpoints is a common scenario in apps, ASP.NET Core relaxes the restriction on the secure policy on some cookies, such as the antiforgery cookie, by setting the cookie's <xref:Microsoft.AspNetCore.Http.CookieBuilder.SecurePolicy%2A> to [`CookieSecurePolicy.None`](xref:Microsoft.AspNetCore.Http.CookieSecurePolicy). Even if a malicious user steals an antiforgery cookie, they also must steal the antiforgery token that's typically sent via a form field (more common) or a separate request header (less common). Cookies related to authentication or authorization use a stronger policy than [`CookieSecurePolicy.None`](xref:Microsoft.AspNetCore.Http.CookieSecurePolicy).
517+
518+
Optionally, you can secure the antiforgery cookie in non-Development environments using Secure Sockets Layer (SSL), over HTTPS only, with the following <xref:Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions.Cookie%2A?displayProperty=nameWithType> property setting in the app's `Program` file:
519+
520+
```csharp
521+
if (!builder.Environment.IsDevelopment())
522+
{
523+
builder.Services.AddAntiforgery(o =>
524+
{
525+
o.Cookie.SecurePolicy = CookieSecurePolicy.Always;
526+
});
527+
}
528+
```
529+
501530
For more information, see <xref:Microsoft.AspNetCore.Builder.CookieAuthenticationOptions>.
502531

503532
## Generate antiforgery tokens with `IAntiforgery`
@@ -742,7 +771,7 @@ ASP.NET Core includes three [filters](xref:mvc/controllers/filters) for working
742771
* [AutoValidateAntiforgeryToken](xref:Microsoft.AspNetCore.Mvc.AutoValidateAntiforgeryTokenAttribute)
743772
* [IgnoreAntiforgeryToken](xref:Microsoft.AspNetCore.Mvc.IgnoreAntiforgeryTokenAttribute)
744773

745-
### Antiforgery with AddControllers
774+
## Antiforgery with `AddControllers`
746775

747776
Calling <xref:Microsoft.Extensions.DependencyInjection.MvcServiceCollectionExtensions.AddControllers%2A> does ***not*** enable antiforgery tokens. <xref:Microsoft.Extensions.DependencyInjection.MvcServiceCollectionExtensions.AddControllersWithViews%2A> must be called to have built-in antiforgery token support.
748777

@@ -753,15 +782,15 @@ With the Synchronizer Token Pattern, only the most recently loaded page contains
753782
* Only the most recently loaded tab contains a valid antiforgery token.
754783
* Requests made from previously loaded tabs fail with an error: `Antiforgery token validation failed. The antiforgery cookie token and request token do not match`
755784

756-
Consider alternative CSRF protection patterns if this poses an issue.
785+
Consider alternative CSRF protection patterns if this poses an issue.
757786

758787
## Configure antiforgery with `AntiforgeryOptions`
759788

760-
Customize <xref:Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions> in `Program.cs`:
789+
Customize <xref:Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions> in the apps' `Program` file:
761790

762791
:::code language="csharp" source="anti-request-forgery/samples/6.x/AntiRequestForgerySample/Snippets/Program.cs" id="snippet_AddAntiforgeryOptions":::
763792

764-
Set the antiforgery `Cookie` properties using the properties of the <xref:Microsoft.AspNetCore.Http.CookieBuilder> class, as shown in the following table.
793+
Set the antiforgery cookie properties using the properties of the <xref:Microsoft.AspNetCore.Http.CookieBuilder> class, as shown in the following table.
765794

766795
| Option | Description |
767796
| --- | --- |
@@ -770,6 +799,20 @@ Set the antiforgery `Cookie` properties using the properties of the <xref:Micros
770799
| <xref:Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions.HeaderName%2A> | The name of the header used by the antiforgery system. If `null`, the system considers only form data. |
771800
| <xref:Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions.SuppressXFrameOptionsHeader%2A> | Specifies whether to suppress generation of the `X-Frame-Options` header. By default, the header is generated with a value of "SAMEORIGIN". Defaults to `false`. |
772801

802+
Some browsers don't allow insecure endpoints to set cookies with a 'secure' flag or overwrite cookies whose 'secure' flag is set (for more information, see [Deprecate modification of 'secure' cookies from non-secure origins](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-cookie-alone-01)). Since mixing secure and insecure endpoints is a common scenario in apps, ASP.NET Core relaxes the restriction on the secure policy on some cookies, such as the antiforgery cookie, by setting the cookie's <xref:Microsoft.AspNetCore.Http.CookieBuilder.SecurePolicy%2A> to [`CookieSecurePolicy.None`](xref:Microsoft.AspNetCore.Http.CookieSecurePolicy). Even if a malicious user steals an antiforgery cookie, they also must steal the antiforgery token that's typically sent via a form field (more common) or a separate request header (less common). Cookies related to authentication or authorization use a stronger policy than [`CookieSecurePolicy.None`](xref:Microsoft.AspNetCore.Http.CookieSecurePolicy).
803+
804+
Optionally, you can secure the antiforgery cookie in non-Development environments using Secure Sockets Layer (SSL), over HTTPS only, with the following <xref:Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions.Cookie%2A?displayProperty=nameWithType> property setting in the app's `Program` file:
805+
806+
```csharp
807+
if (!builder.Environment.IsDevelopment())
808+
{
809+
builder.Services.AddAntiforgery(o =>
810+
{
811+
o.Cookie.SecurePolicy = CookieSecurePolicy.Always;
812+
});
813+
}
814+
```
815+
773816
For more information, see <xref:Microsoft.AspNetCore.Builder.CookieAuthenticationOptions>.
774817

775818
## Generate antiforgery tokens with `IAntiforgery`
@@ -1034,7 +1077,7 @@ services.AddAntiforgery(options =>
10341077
});
10351078
```
10361079

1037-
Set the antiforgery `Cookie` properties using the properties of the <xref:Microsoft.AspNetCore.Http.CookieBuilder> class, as shown in the following table.
1080+
Set the antiforgery cookie properties using the properties of the <xref:Microsoft.AspNetCore.Http.CookieBuilder> class, as shown in the following table.
10381081

10391082
| Option | Description |
10401083
| --- | --- |
@@ -1043,6 +1086,42 @@ Set the antiforgery `Cookie` properties using the properties of the <xref:Micros
10431086
| <xref:Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions.HeaderName%2A> | The name of the header used by the antiforgery system. If `null`, the system considers only form data. |
10441087
| <xref:Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions.SuppressXFrameOptionsHeader%2A> | Specifies whether to suppress generation of the `X-Frame-Options` header. By default, the header is generated with a value of "SAMEORIGIN". Defaults to `false`. |
10451088

1089+
Some browsers don't allow insecure endpoints to set cookies with a 'secure' flag or overwrite cookies whose 'secure' flag is set (for more information, see [Deprecate modification of 'secure' cookies from non-secure origins](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-cookie-alone-01)). Since mixing secure and insecure endpoints is a common scenario in apps, ASP.NET Core relaxes the restriction on the secure policy on some cookies, such as the antiforgery cookie, by setting the cookie's <xref:Microsoft.AspNetCore.Http.CookieBuilder.SecurePolicy%2A> to [`CookieSecurePolicy.None`](xref:Microsoft.AspNetCore.Http.CookieSecurePolicy). Even if a malicious user steals an antiforgery cookie, they also must steal the antiforgery token that's typically sent via a form field (more common) or a separate request header (less common). Cookies related to authentication or authorization use a stronger policy than [`CookieSecurePolicy.None`](xref:Microsoft.AspNetCore.Http.CookieSecurePolicy).
1090+
1091+
Optionally, you can secure the antiforgery cookie in non-Development environments using Secure Sockets Layer (SSL), over HTTPS only, with the following <xref:Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions.Cookie%2A?displayProperty=nameWithType> property setting in the app's `Startup` class:
1092+
1093+
```csharp
1094+
public class Startup
1095+
{
1096+
public Startup(IConfiguration configuration, IHostEnvironment environment)
1097+
{
1098+
Configuration = configuration;
1099+
Environment = environment;
1100+
}
1101+
1102+
public IConfiguration Configuration { get; }
1103+
public IHostEnvironment Environment { get; }
1104+
1105+
public void ConfigureServices(IServiceCollection services)
1106+
{
1107+
// Other services are registered here
1108+
1109+
if (!Environment.IsDevelopment())
1110+
{
1111+
services.AddAntiforgery(o =>
1112+
{
1113+
o.Cookie.SecurePolicy = CookieSecurePolicy.Always;
1114+
});
1115+
}
1116+
}
1117+
1118+
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
1119+
{
1120+
// Request processing pipeline
1121+
}
1122+
}
1123+
```
1124+
10461125
For more information, see <xref:Microsoft.AspNetCore.Builder.CookieAuthenticationOptions>.
10471126

10481127
## Configure antiforgery features with IAntiforgery

0 commit comments

Comments
 (0)