Cross-Site Request Forgery

Browsers attach cookies to a request based on where it is going, not on where it came from. A request to your application carries your application's cookies whether the user typed the address, clicked a link on one of your pages, or loaded a page somewhere else entirely that caused the request to be made.

Cross-site request forgery uses exactly that behaviour. A signed-in employee has a page from another site open, that page causes their browser to issue a request to your application, and the browser attaches the session cookie as it always does. Your server receives a well-formed, authenticated request from a real employee. The employee did not intend it and may not know it happened.

Note what is not needed for this. No stolen cookie, no password, no ability to read your application's responses — cross-origin rules already prevent that last one. Being able to cause the request is sufficient. That is why the defence is about proving a request came from your own pages, and not about identity: the identity was never in question.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews(options =>
{
    // Validate on every POST, PUT, PATCH and DELETE.
    // Opting in per action means one forgotten attribute is one open endpoint.
    options.Filters.Add(new AutoValidateAntiforgeryTokenAttribute());
});

builder.Services.AddAntiforgery(options =>
{
    options.HeaderName = "X-CSRF-TOKEN";   // for requests issued by script
    options.Cookie.SameSite = SameSiteMode.Lax;
    options.Cookie.SecurePolicy = CookieSecurePolicy.Always;
});

builder.Services
    .AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
    .AddCookie(options =>
    {
        options.Cookie.HttpOnly = true;                          // script cannot read it
        options.Cookie.SecurePolicy = CookieSecurePolicy.Always; // HTTPS only
        options.Cookie.SameSite = SameSiteMode.Lax;              // not sent on cross-site subrequests
    });

• The anti-forgery mechanism issues two linked values: one in a cookie, and one your page must include in the request as a hidden field or a header. A page on another origin can cause the browser to send the cookie. It cannot read your page to obtain the matching value, which is the whole basis of the defence.
• Registering AutoValidateAntiforgeryTokenAttribute globally makes validated the default for unsafe methods, and an action opts out explicitly with IgnoreAntiforgeryToken. That is the right way round: a forgotten attribute then produces a rejected request rather than an unprotected endpoint.
• A Razor form using the form tag helper gets the hidden token field automatically. A hand-written HTML form does not, so it needs Html.AntiForgeryToken() inside it. This is the usual explanation for a form that starts returning 400 after somebody rewrote the markup.
• HeaderName lets script-driven requests carry the token in a header instead of a form field. Read the token from the antiforgery service when rendering the page, and attach it to your fetch calls.
• The session cookie is marked HttpOnly, Secure and SameSite Lax. HttpOnly keeps page script from reading it, which matters for the cross-site scripting lesson. SameSite is the second layer described below.

Put together, the arrangement for a cookie-based application: SameSite Lax or Strict on the session cookie, HttpOnly and Secure alongside it, anti-forgery validation on by default for every state-changing method, and no state changes on GET. Each layer covers a different failure of the others.

For an API whose clients set an Authorization header themselves, this particular risk largely does not arise, and the attention moves to where that token is stored and to the previous lesson. That is a genuine trade rather than a free win — you have removed one class of problem by taking on responsibility for holding a credential in the client.

One honest caveat about mixed designs, which are common in practice. An application that grew a mobile client often ends up accepting either a cookie or a bearer token on the same endpoints. That endpoint has the cookie's exposure, because a request can choose the cookie. Keep the anti-forgery validation on the cookie path rather than removing it on the grounds that the new client does not need it.

Finally, worth saying plainly: this is one of the few security problems where the framework's default configuration does most of the work. The effort goes into not switching it off, and into noticing the endpoint that was added outside the usual pattern.