Skip to content

Update CSRF/antiforgery docs for deferred validation behavior#37262

Open
DeagleGross wants to merge 5 commits into
dotnet:mainfrom
DeagleGross:deaglegross/update-csrf-docs-defer-behavior
Open

Update CSRF/antiforgery docs for deferred validation behavior#37262
DeagleGross wants to merge 5 commits into
dotnet:mainfrom
DeagleGross:deaglegross/update-csrf-docs-defer-behavior

Conversation

@DeagleGross

@DeagleGross DeagleGross commented Jun 17, 2026

Copy link
Copy Markdown
Member

Follow-up docs for dotnet/aspnetcore#67082 (defer antiforgery/CSRF rejection to form consumers). Keeping this as a draft — will be marked ready for review once #67082 is merged into dotnet/aspnetcore.

Summary

The merged docs for automatic CSRF protection in .NET 11 described the middleware as short-circuiting cross-origin write requests with 400. dotnet/aspnetcore#67082 changes that runtime behavior: the CsrfProtectionMiddleware now records its verdict on the shared IAntiforgeryValidationFeature and lets the request continue, and rejection is deferred to the components that consume the submitted form. This PR reconciles the docs with that model.

Files changed

  • aspnetcore/security/csrf-protection.md

    • Reframed the intro and How it works to drop the short-circuit model — the middleware now produces an allowed/denied verdict recorded on the request.
    • Added a Deferred validation section: the verdict is recorded on IAntiforgeryValidationFeature and enforced only when a form consumer reads it (MVC antiforgery, minimal-API form binding, Blazor SSR, or a direct form read). Notes explicitly that JSON/non-form endpoints proceed even when the verdict is invalid.
    • Switched the Default behavior and Allowing cross-origin clients examples to form-based ([FromForm]) endpoints so the "rejected with 400" narrative is accurate.
    • Added Token validation takes precedence and Blazor server-side rendering sections.
    • Refreshed troubleshooting diagnostics (event name CsrfValidationFailed, "marked request … as invalid"), and a caveat note under Disabling globally.
  • aspnetcore/migration/antiforgery-to-csrf.md

    • Added a Blazor static server-side rendering breaking-change subsection (removing app.UseAntiforgery() shifts protection to the CSRF middleware and stops antiforgery token generation).
    • Reframed the after-upgrade symptoms to cross-origin form posts, refreshed the log message, and added a caveat subsection for pure-antiforgery apps combined with DisableCsrfProtection or non-WebApplication hosts.

Both files have ms.date bumped and retain ai-usage: ai-assisted.


Internal previews

📄 File 🔗 Preview link
aspnetcore/breaking-changes/11/blazor-server-side-rendering-deferred-cross-site-request-forgery-protection.md Blazor server-side rendering defers antiforgery validation to middleware
aspnetcore/breaking-changes/11/overview.md Breaking changes in ASP.NET Core 11
aspnetcore/migration/antiforgery-to-csrf.md Adopt automatic CSRF protection in .NET 11
aspnetcore/security/csrf-protection.md Automatic CSRF protection in ASP.NET Core
aspnetcore/toc.yml aspnetcore/toc

DeagleGross and others added 4 commits June 17, 2026 11:17
Reconcile the automatic CSRF protection docs with the deferred validation model where CsrfProtectionMiddleware records a verdict on IAntiforgeryValidationFeature instead of short-circuiting, and form consumers enforce it. Adds deferred-validation, token-precedence, and Blazor SSR sections, updates examples to form-based scenarios, refreshes diagnostics strings, and documents the migration breaking changes and caveats.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Document the .NET 11 breaking change where Blazor static server-side rendering defers antiforgery validation to middleware and skips token generation when no token middleware ran. Adds the breaking-changes article, indexes it in overview.md and toc.yml, and cross-links it from the CSRF reference and migration articles.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Spell out server-side-rendering in the filename to satisfy the repo filename rules, and update the overview index, toc.yml, and cross-links accordingly.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Spell out the filename fully (no ssr abbreviation, no antiforgery closed compound) to clear the filename suggestion from the docs build, and update the overview index, toc.yml, and cross-links accordingly.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@DeagleGross DeagleGross marked this pull request as ready for review June 18, 2026 18:15
Comment thread aspnetcore/security/csrf-protection.md Outdated
Comment thread aspnetcore/security/csrf-protection.md Outdated
Comment thread aspnetcore/security/csrf-protection.md Outdated
Comment thread aspnetcore/security/csrf-protection.md Outdated

@wadepickett wadepickett left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@DeagleGross, looks great! See the very minor items I suggested inline to consider.

Co-authored-by: Wade Pickett <wpickett@microsoft.com>
@DeagleGross DeagleGross requested a review from danroth27 June 22, 2026 16:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants