Understanding Anti-Forgery in ASP.NET Core

In today’s web applications, security is a top priority. One of the common attacks that web developers need to guard against is Cross-Site Request Forgery (CSRF). ASP.NET Core provides built-in support to protect against such attacks using Anti-Forgery tokens.

Let’s explore what CSRF is, look at the default settings in ASP.NET Core, and how to implement Anti-Forgery in MVC, Razor Pages, and Minimal APIs. We will also cover handling Anti-Forgery tokens when using XHR or fetch requests originating from JavaScript and considerations for load-balanced scenarios.

What is Cross-Site Request Forgery (CSRF)?

Cross-Site Request Forgery (CSRF) is an attack where a malicious website tricks a user’s browser into performing an unwanted action on a different site where the user is authenticated. This can lead to unauthorized actions such as changing account details, making purchases, or even deleting data.

Diagram explaining Cross-Site Request Forgery (CSRF)

Example of a CSRF Attack

Here’s an example of how a CSRF attack works:

  1. A user logs into their banking website (example.com) and receives an authentication cookie.
  2. Without logging out, the user visits a malicious website.
  3. The malicious site submits a hidden form to example.com/transfer, using the user’s authentication cookie.
  4. The bank processes the transfer without the user’s knowledge or consent.

To ensure that forms can only be submitted from pages that the legitimate website generated, you can use an anti-forgery token.

Note: Cross-Origin Resource Sharing (CORS) is a security feature that restricts web pages from making HTTP requests to a domain different from the one that served the web page. While CORS prevents a malicious site from reading responses from your application, it doesn’t stop CSRF attacks. Even with strict CORS policies, a malicious site can still trick a user into submitting a form to your application. Both CORS and CSRF protections are essential: CORS controls access to resources based on origin, while CSRF ensures that requests are made with the user’s intent.

ASP.NET Core and CSRF - Anti-Forgery

ASP.NET Core has built-in support for Anti-Forgery tokens to help prevent CSRF attacks. By default, ASP.NET Core includes Anti-Forgery tokens in forms and validates them on the server side. The framework automatically generates and validates these tokens for Razor Pages and MVC applications.

When ASP.NET Core generates an Anti-Forgery token, part of the token is stored in a cookie (.AspNetCore.Antiforgery by default), and the other part is included in the form or request header. The server then compares these two pieces to verify the request’s authenticity.

The generated cookie containing the anti-forgery token uses the SameSiteMode.Strict and is HttpOnly, which means it cannot be accessed by JavaScript code running in the browser, making it impossible for malicious code to steal the cookie value.

Note that the ASP.NET Core Anti-Forgery token is also bound to the current user. The validation will fail when the user data embedded in the Anti-Forgery token doesn’t match the authenticated user.

An example of why that matters is a common Duende IdentityServer support issue when a user has two open browser tabs to the same client app. Each tab challenges the user to sign in with IdentityServer. Each tab successfully renders the login with a unique anti-forgery token for the anonymous user. Remember, the user in both tabs is unknown because they haven’t logged in yet. The user then successfully signs in on the first tab, validating the first anti-forgery token, success! The second tab, however, will no longer pass Anti-Forgery validation, as the existing token on the page no longer matches the authenticated user.

Options for AddAntiforgery

In your application’s setup code, typically found in Program.cs, you can configure the anti-forgery options. The AddAntiforgery method has an overload that accepts a lambda, in which you can override the default options:

  • Cookie.Name - Sets the cookie’s name used to store the Anti-Forgery token. Default: .AspNetCore.Antiforgery
  • FormFieldName - Sets the form field’s name for storing the Anti-Forgery token. Default: __RequestVerificationToken
  • HeaderName - Sets the header’s name used to store the Anti-Forgery token. Default: null
  • SuppressXFrameOptionsHeader - Determines whether the X-Frame-Options header is suppressed. Default: false

Here’s an example that configures the cookie name, form field name, and header name:

builder.Services.AddAntiforgery(options =>
{
    options.Cookie.Name = "MyAntiforgeryCookie";
    options.FormFieldName = "MyAntiforgeryField";
    options.HeaderName = "X-CSRF-TOKEN";
});

The default options are generally suitable for most applications, so a simple call to AddAntiforgery() without additional configuration is often sufficient.

Adding Anti-Forgery to MVC and Razor Pages

When working with Anti-Forgery tokens, you need to ensure that a token is rendered in the view to be sent with the request and that the server can validate the token.

In an MVC or Razor Pages application, Anti-Forgery tokens are automatically included in forms generated by the FormTagHelper. In other words, adding a <form> when this tag helper is registered will automatically render a hidden field with Anti-Forgery information.

Some folks prefer not to use FormTagHelper, or are using older versions of ASP.NET that may not have access to these tag helpers. To make sure the anti-forgery token hidden field is added to every form, you can add it manually using the @Html.AntiForgeryToken() method:

<form method="post" action="/Home/Submit">
    @Html.AntiForgeryToken()
    <!-- form fields -->
</form>

On the server-side, Razor Pages automatically validates anti-forgery tokens. This is thanks to a convention in the framework that automatically registers the AutoValidateAntiforgeryTokenAttribute filter. If you want this filter to be registered automatically in ASP.NET MVC Core, you can add it to the filters collection on startup:

builder.Services.AddControllersWithViews(options =>
{
    options.Filters.Add(new AutoValidateAntiforgeryTokenAttribute());
});

On any ASP.NET MVC controller, action method, or Razor Pages model, you can override the default behavior of validating (or ignoring) Anti-Forgery tokens. Add the [RequireAntiForgeryToken] attribute to require validation, or [IgnoreAntiForgeryToken] to skip validation.

Here’s how to add [RequireAntiForgeryToken] to an action method:

public class CustomerController : Controller
{
    [RequireAntiforgeryToken]
    [HttpPost]
    public IActionResult Save(Customer customer)
    {
        return View();
    }
}

In Razor Pages, the attribute can be added to the PageModel:

[IgnoreAntiforgeryToken]
public class Counter : PageModel
{
    // ...
}

Note that you can not apply Anti-Forgery attributes to individual handlers in Razor Pages.

Adding Anti-Forgery to Minimal APIs

In ASP.NET Core Minimal APIs, you need to manually configure and validate Anti-Forgery tokens. There are a few steps involved:

  • Register the necessary services
  • Make sure Anti-Forgery tokens are generated on every response, and submitted in every request
  • Validate the Anti-Forgery token

Registering the Anti-Forgery services can be done in Program.cs:

var builder = WebApplication.CreateBuilder(args);

// ...

builder.Services.AddAntiforgery();

// ...

Once registered, the IAntiforgery service is available through the service provider and can be used to get or store tokens.

If you’re using HTML forms to send requests to ASP.NET Core Minimal APIs, you can add a hidden form field named __RequestVerificationToken, and set its value using the output of the Antiforgery.GetTokens(HttpContext).RequestToken method.

In any API, you can now validate the Anti-Forgery token by injecting the IAntiforgery and validating it against the current HttpContext:

app.MapPost("/save-data", async (HttpContext context, IAntiforgery antiforgery) =>
{
    await antiforgery.ValidateRequestAsync(context);
    
    // ...

    return Results.Ok();
});

What to do when making requests from JavaScript?

When using JavaScript to call existing ASP.NET Core endpoints with Anti-Forgery, your calling code must also include a token to complete the request successfully. For example using Angular, React, or Vue, you need to make sure you’re sending the Anti-Forgery token either as a request parameter on POST, or as a request header.

You’ll typically want to retrieve the Anti-Forgery token from a hidden form field or from a cookie, and include it in the request headers.

Using the Anti-Forgery token from a hidden form field

When using MVC or Razor Pages, you can use @Html.AntiForgeryToken() to generate the hidden form field:

<form id="hiddenForm" method="post">
    @Html.AntiForgeryToken()
</form>

With ASP.NET Core Minimal APIs, you can generate a form that adds a hidden field named __RequestVerificationToken, and populate it using Antiforgery.GetTokens(HttpContext).RequestToken.

In JavaScript, you can then use the value of this hidden field and append it to the request headers (using the default header key RequestVerificationToken):

const token = document.querySelector('input[name="__RequestVerificationToken"]').value;

const formData = new FormData(...);
const data = {};
formData.forEach((value, key) => {
    data[key] = value;
});

fetch('/save-data', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'RequestVerificationToken': token
    },
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => {
    // Handle success
    console.log('Success:', data);
})
.catch((error) => {
    // Handle error
    console.error('Error:', error);
});

As an alternative to using a hidden form field to render the Anti-Forgery token in the browser, you can also make it available in a cookie and then use that later when sending requests to the server.

Here’s a snippet that generates a new Anti-Forgery token for a request, and stores it in a cookie named XSRF-TOKEN:

var app = builder.Build();

app.Use(async (context, next) =>
{
    var antiforgery = context.RequestServices.GetRequiredService<IAntiforgery>();
    var tokens = antiforgery.GetAndStoreTokens(context);
    context.Response.Cookies.Append("XSRF-TOKEN", tokens.RequestToken!,
        new CookieOptions { HttpOnly = false, SameSite = SameSiteMode.Strict });
    await next();
});

// ...

Note that this code sets the cookie’s HttpOnly property to false, to make sure the JavaScript code running in the browser can read the value stored.

In JavaScript, you can then use the value of this cookie, and append it to the request headers (using the default header key RequestVerificationToken):

const token = document.cookie.match('(^|;)\\s*XSRF-TOKEN\\s*=\\s*([^;]+)')?.pop() || '';

fetch('/save-data', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'RequestVerificationToken': token
    },
    body: // ...
})
.then(response => response.json())
.then(data => {
    // Handle success
    console.log('Success:', data);
})
.catch((error) => {
    // Handle error
    console.error('Error:', error);
});

Anti-Forgery tokens and Duende Backend-for-Frontend (BFF)

When you deploy Duende Backend-for-Frontend (BFF), anti-forgery is enabled by default. Anti-forgery in BFF is implemented differently from ASP.NET Core: it only requires the presence of a X-CSRF: 1 header (customizable in settings). Any React, Angular, Vue, Blazor or other front-end can easily add such header!

Combined with BFF’s cookie requirements, having this header triggers a CORS preflight request in the browser for cross-origin calls. This isolates the caller to the same origin as the backend, providing robust CSRF protection. For more information, see protection against CSRF attacks in the BFF documentation.

Load-balanced scenarios and DataProtection

In a load-balanced scenario, you must ensure that the Anti-Forgery tokens are consistent across all application instances. This requires configuring DataProtection to use a shared key storage mechanism, such as a database, Azure Blob Storage, or Azure Key Vault.

Example configuration for DataProtection in Program.cs:

builder.Services.AddDataProtection()
    .PersistKeysToFileSystem(new DirectoryInfo(@"\\server\share\keys"))
    .SetApplicationName("MyApp");

Note that the application name configured here will also be used in the Anti-Forgery cookie.

Summary

Anti-Forgery tokens are a crucial part of securing your ASP.NET Core applications against CSRF attacks. By understanding the defaults and knowing how to configure and implement Anti-Forgery tokens in MVC, Razor Pages, and Minimal APIs, you can ensure that your applications are protected.

Additionally, handling Anti-Forgery tokens in AJAX requests is essential for maintaining security in dynamic web applications. In load-balanced scenarios, configuring DataProtection to use a shared key storage mechanism is necessary to ensure consistency.

Thoughts? Questions? Let us know in the comments!