ASP.NET Core security
This file covers security in the HTTP pipeline: authentication, authorization, browser sessions, tokens, the Data Protection key ring, CSRF, CORS, security headers, and open redirects.
- For hosting, request validation, error responses, and the rest of ASP.NET Core, see aspnet-core.md.
- For secrets, deserialization, cryptography, and servicing cadence, see security.md.
Opinions
Authentication: passkeys first
Sign users in with ASP.NET Core Identity's built-in passkey (WebAuthn and FIDO2) support, not passwords or a third-party FIDO library. Since .NET 10, Identity and the Blazor Web App template include passkey management and sign-in. Passkeys resist phishing, leave no server-side secret to leak, and add no dependency. Plan account recovery before you make passkeys the only way in, because it's "primarily a concern for apps that allow passkeys as the only authentication mechanism". Have users register more than one passkey, prompt for another when UserPasskeyInfo.IsBackedUp is false, and add recovery codes generated at account creation or an email-based recovery flow. Build those codes yourself: Identity's built-in recovery codes redeem only inside the two-factor flow, after a first-factor sign-in, so they can't recover a passkey-only account. (Microsoft Learn: What's new in ASP.NET Core 10, Microsoft Learn: Passkeys in ASP.NET Core, dotnet/aspnetcore: SignInManager.cs)
Return 401 or 403 from API endpoints, never a sign-in redirect. Since ASP.NET Core 10, the cookie handler returns the status code instead of redirecting when an endpoint has IDisableCookieRedirectMetadata. Microsoft Learn's What's new page still gives its pre-release name, IApiEndpointMetadata. Four kinds of endpoint get it automatically: [ApiController] actions, minimal APIs that read or write JSON, SignalR hubs, and endpoints whose declared return type is a status-code TypedResults type, such as Ok<T> or NotFound<T>. The declared type decides it: a handler declared to return IResult doesn't get it, even when it returns TypedResults.Ok(). The non-generic NotFound and InternalServerError are exceptions too: they add only their response-type metadata. Call .DisableCookieRedirect() on any other API endpoint, such as one that returns a string, IResult, Results.Text, TypedResults.Text, or only TypedResults.NotFound(). The change covers only the cookie handler: in a custom handler, return 401 from the challenge action and 403 from the forbid action for API endpoints. (Microsoft Learn: What's new in ASP.NET Core 10, aspnet/Announcements#525: Cookie login redirects are disabled for known API endpoints, Microsoft Learn: Overview of ASP.NET Core Authentication, Microsoft Learn: API endpoint authentication behavior, dotnet/aspnetcore: NotFound.cs, dotnet/aspnetcore: InternalServerError.cs, dotnet/aspnetcore: CookieRedirectEndpointConventionBuilderExtensions.cs)
Don't trust the amr claim after a passkey sign-in. .NET 10 sets it to pwd instead of pop, the proof-of-possession value that OpenID Connect EAP ACR Values 1.0 defines. Bowden reports that this "is not implemented correctly in ASP.NET Core (.NET 10)", and it's filed as dotnet/aspnetcore#64881, which is still open, on the ".NET 12 Planning" milestone. Authorization that reads amr for a step-up or multi-factor decision misjudges a passkey. Do one of these instead:
- Take the credential type from your own sign-in path.
- Reissue the claim. You can't change the existing claims collection, so sign the user out and back in with
SignInWithClaimsAsync().
Drop this note when a shipped release fixes the issue.
(Bowden: Set the amr claim when using passkeys authentication in ASP.NET Core)
Review by 2027-11-30.
Authorization by default
Set a fallback policy that requires an authenticated user, and let endpoints opt out. A new endpoint is then private until someone marks it public, the same default as Request validation. "Having authorization required by default is more secure than relying on new controllers and Razor Pages to include the [Authorize] attribute". (Microsoft Learn: Create an ASP.NET Core web app with user data protected by authorization)
builder.Services.AddAuthorizationBuilder()
.SetFallbackPolicy(new AuthorizationPolicyBuilder()
.RequireAuthenticatedUser()
.Build())
.AddPolicy("Admin", policy => policy.RequireRole("admin"));
app.MapDelete("/orders/{id}", (int id) => TypedResults.NoContent())
.RequireAuthorization("Admin");
Mark public endpoints with [AllowAnonymous], or call .AllowAnonymous() on a minimal API endpoint or group. Give an endpoint that needs more than a signed-in user, such as a role or a claim, its own named policy. Register the policy with AddPolicy, and apply it with [Authorize("<policy>")] or .RequireAuthorization("<policy>"). (Microsoft Learn: Policy-based authorization in ASP.NET Core)
Browser clients: cookies, with a BFF holding the tokens
Authenticate a browser app with a cookie. A SPA or Blazor WebAssembly client calls its APIs through a backend for frontend (BFF) that keeps the tokens on the server. Microsoft Learn recommends cookies for browser apps "because, by default, the browser automatically handles them without exposing them to JavaScript", and reserves tokens for clients that can't use cookies. (Microsoft Learn: Use Identity to secure a Web API backend for SPAs)
The reason is XSS. A token in localStorage is readable by any script an attacker injects. (Jovanović: JWT Authentication in ASP.NET Core) By contrast, "HttpOnly cookies cannot be read by JavaScript, so even a successful XSS attack cannot exfiltrate the user's access or refresh token". (Abuhakmeh: The Cookie Apocalypse Already Happened) Bowden states the client-side rule: "No authentication security logic should be implemented in a client application running in the browser". (Bowden: Implement BFF using Auth0, Angular and ASP.NET Core)
Set it up in three parts:
- The session cookie: Use a
__Host-prefixed cookie markedHttpOnlyandSecure. AddSameSite=Strictwhere the flow allows it, because such cookies "are not sent on cross-site requests". This adds to the CSRF defence below, and doesn't replace it. (Abuhakmeh: The Cookie Apocalypse Already Happened) - One origin: Put a reverse proxy in front, so the front end and the API share an origin.
- A separate downstream token: The BFF gets its own token for the downstream API, instead of forwarding the browser's. In Bowden's design, "The downstream API does not accept the user delegated access tokens from the UI application". That token identifies the BFF, not the user: "The app-to-app security has nothing to do with the delegated client from the web application". The downstream API can't tell one user from another, so authorise the user in the BFF before it makes the call. (Bowden: BFF secured ASP.NET Core application using downstream API and an OAuth client credentials JWT)
Blazor's documented BFF sample differs in two ways, so change both if you start from it. It proxies API calls "with the access_token stored in the authentication cookie", which keeps the tokens in the browser's cookie instead of on the server. It also forwards the user's access token to the API, where the BFF should send its own. (Microsoft Learn: Secure an ASP.NET Core Blazor Web App with OpenID Connect (OIDC))
Keep session state on the server, and make the cookie a key to it. Browsers cap a cookie at about 4 KB. Abuhakmeh's fix: "stop storing session data in the cookie entirely... The cookie becomes a thin key that points to the server state rather than containing that state itself". (Abuhakmeh: ASP.NET Core Cookie Size Limits in Production)
Tokens for APIs
Get tokens from an identity provider, validate the issuer, audience, lifetime, and signing key, and keep permissions out of the token. Hand identity to "a battle-tested identity provider" instead of issuing your own JWTs, which would make your service responsible for key management and revocation. (Jovanović: Integrate Keycloak with ASP.NET Core Using OAuth 2.0)
- Resolve permissions on the server with
IClaimsTransformation, and keep tokens small. A revoked permission in a token "keeps working until the token expires", so a request that should get a 403 still succeeds. (Jovanović: Building Secure APIs with Role-Based Access Control in ASP.NET Core, Mukesh: Permission-Based Authorization in ASP.NET Core) - Expire an access token within 15 to 30 minutes, because you can't revoke a JWT after you issue it. Jovanović says "Access tokens should be short-lived (15-30 minutes)". Mukesh's "15 to 60 minutes is reasonable" is too long, because a leaked token works for its whole lifetime. (Jovanović: JWT Authentication in ASP.NET Core, Mukesh: JWT Authentication in ASP.NET Core)
- Rotate refresh tokens on every use: issue a new one, and revoke the old one. (Jovanović: JWT Authentication in ASP.NET Core)
- If you issue your own tokens anyway, store only a hash of each refresh token, and give every sign-in its own token family. An identity provider owns that storage, so this bullet and the next apply only to an app that signs its own JWTs. "Treat a reused refresh token as stolen, and cap each login with an absolute expiry": when a token that was already used comes back, delete the whole family. (Jovanović: How to Revoke a JWT Before It Expires)
- If you issue your own tokens, check a
token_versionclaim against the user row on every request only when one access-token lifetime is too long to wait. A password change doesn't revoke a JWT, because the bearer handler "never reads your database". Deleting the refresh tokens ends the session when the access token expires. The per-request check ends it at once, but only if you increment the column: "On a password change, a sign-out from every device, or refresh token reuse". The check has a cost. On an endpoint with no other database work, Jovanović measured about 0.65 ms more for one user with a PostgreSQL lookup, and throughput that "drops almost eight times" with 64 users. A Redis cache in front "kept about half the throughput". Authentication then also fails when the database does. (Jovanović: How to Revoke a JWT Before It Expires)
Bind each token to its client, and authenticate the client with a key instead of a secret. Anyone who holds a bearer token can use it. Use the three OAuth extensions below. Each one works only if your identity provider supports it, so check which of them it implements before you design around them:
- DPoP: OAuth DPoP binds the token to a key that the client proves it holds. "The access tokens should only be used for what the access tokens are intended for. OAuth DPoP helps force this." (Bowden: Securing APIs using ASP.NET Core and OAuth 2.0 DPoP)
- Pushed authorization requests (PAR): Set
PushedAuthorizationBehavior.Require, available since .NET 9. PAR works by "moving authorization parameters from redirect URLs in the browser to direct machine to machine http calls on the back end". (Bowden: Implement ASP.NET Core OpenID Connect OAuth PAR client with Keycloak using .NET Aspire, Microsoft Learn: What's new in ASP.NET Core 9) - Client assertions: Authenticate a confidential client with a private-key JWT assertion. It replaces the shared secret, the one long-lived credential the client would otherwise keep in configuration. (Bowden: Use client assertions in ASP.NET Core using OpenID Connect, OAuth DPoP and OAuth PAR)
The Data Protection key ring outlives the container
If you run more than one instance, or a container that restarts, persist the key ring to shared storage and protect it at rest. Configure both explicitly. Cookie authentication and antiforgery both depend on the ring. When instances don't share it, a request that reaches another node fails, because "the app can't decrypt the authentication cookie from the node where the user signed in", and "The antiforgery check fails". (Microsoft Learn: Host ASP.NET Core in a web farm) In a container, keep the keys in a Docker volume that outlives the container, or in an external store such as Azure Blob Storage. (Microsoft Learn: Configure ASP.NET Core Data Protection)
// Azure.Extensions.AspNetCore.DataProtection.Blobs and .Keys; both extension
// methods live in the Microsoft.AspNetCore.DataProtection namespace.
builder.Services.AddDataProtection()
.PersistKeysToAzureBlobStorage(blobUri, credential)
.ProtectKeysWithAzureKeyVault(keyIdentifier, credential);
Make both calls. When you name a location, "the data protection system deregisters the default key encryption at rest mechanism, so keys are no longer encrypted at rest". Don't use Redis unless you've turned on its persistence. It "doesn't persist data by default when restarting", so a restart gives the app new keys and invalidates everything the old ones protected. (Microsoft Learn: Key storage providers in ASP.NET Core)
Encryption at rest "doesn't prevent cyberattackers from creating new keys", so lock down the store's permissions as carefully as you encrypt it. (Microsoft Learn: Configure ASP.NET Core Data Protection)
Give each app its own key store, and call SetApplicationName with a fixed name. On a shared store, the application discriminator keeps each app's payloads apart, but it isn't a security boundary: "a compromise of one is functionally equivalent to a compromise of both". It defaults to the content root path, and in a container "the app always has the same path and, therefore, the same application discriminator", so the payloads aren't even kept apart. (Microsoft Learn: Configure ASP.NET Core Data Protection) To share sign-in cookies between apps for single sign-on, point them at the same key storage location and give each the same SetApplicationName value. Apps on different subdomains also need a common Cookie.Domain, so the shared cookie can't take the __Host- prefix that the session cookie above uses: a __Host- cookie "must not have a Domain attribute specified". Learn also notes that these steps "don't work with ITicketStore (CookieAuthenticationOptions.SessionStore)", so a sign-in that keeps its ticket in a server-side store can't share its cookie this way. (Microsoft Learn: Share authentication cookies among ASP.NET apps, MDN: Set-Cookie header)
CSRF defence in depth
Leave the automatic CSRF middleware on, and keep UseAntiforgery() in an app that renders forms with antiforgery tokens. In .NET 11, WebApplication.CreateBuilder adds a middleware that reads the Sec-Fetch-Site and Origin headers, which the browser sets and page script can't forge. On an endpoint whose metadata requires antiforgery validation, it records a verdict on the request, and "Components that process submitted form data enforce that verdict, rejecting cross-origin form posts that aren't explicitly trusted." The two protections "coexist and can both be active on the same endpoint". Razor Pages, MVC, and Blazor SSR apps that use tokens "gain a header-based check that runs before token validation, without changing the token flow", and when both run, "The token result is authoritative". A valid token turns a rejected verdict into an accepted one, and a missing or invalid token rejects a request the header check accepted. So in an app that calls UseAntiforgery(), the header check isn't an independent layer: the app behaves as it did before .NET 11. (Microsoft Learn: Prevent Cross-Site Request Forgery (XSRF/CSRF) attacks in ASP.NET Core, Lock: Understanding the Fetch Metadata headers)
Know what the middleware doesn't cover:
- Only unsafe methods are checked.
GET,HEAD,OPTIONS, andTRACEpass, so never change state on aGET. - Only an endpoint that reads a form enforces the verdict: an MVC action protected by antiforgery, a minimal API that binds a form parameter, or a Blazor SSR form. An endpoint that binds its body from JSON "isn't rejected automatically on a cross-origin request".
- A handler that reads the form itself isn't covered. A minimal API that takes
HttpContextand readsRequest.Form, or callsReadFormAsync, has no antiforgery metadata, so the middleware records no verdict. Tested on .NET 11.0.0: a cross-site post to such an endpoint returns 200. Bind the form with a[FromForm]orIFormFileparameter instead, and the same post returns 400. - A request with no browser signal passes. One with neither
Sec-Fetch-SitenorOriginis "almost certainly a non-browser client". The middleware is a CSRF defence, and it doesn't authenticate an API's callers. - A cross-origin form post needs a CORS policy that names its origin and calls
.AllowCredentials(). "AllowAnyOrigin is intentionally not honored as a CSRF trust signal", and "A policy that lists specific origins with WithOrigins but omits .AllowCredentials() isn't honored for CSRF trust either."
(Microsoft Learn: Prevent Cross-Site Request Forgery (XSRF/CSRF) attacks in ASP.NET Core)
Opt an endpoint out only when a browser can't reach it, or when it doesn't rely on credentials that the browser attaches by itself. Never turn the middleware off for the whole app. Call .DisableAntiforgery() on a minimal API, or put [IgnoreAntiforgeryToken] on an MVC action or controller. That fits an endpoint that "isn't browser-reachable or is secured by a non-cookie mechanism, such as a bearer token or API key". Cookies aren't the only credentials a browser attaches: "Basic and Digest authentication are also vulnerable", so keep the check on an endpoint that uses either. The DisableCsrfProtection configuration key removes the middleware everywhere, and Microsoft Learn says to "prefer per-endpoint opt-outs". (Microsoft Learn: Prevent Cross-Site Request Forgery (XSRF/CSRF) attacks in ASP.NET Core)
On .NET 11, a minimal API that binds a form or a form file doesn't need UseAntiforgery(). On .NET 8 to 10, "Minimal API endpoints that bind a parameter from the form via IFormFile or IFormFileCollection require anti-forgery validation", and the endpoint throws on every request until you register the token middleware. Now "The automatic CSRF middleware also satisfies the antiforgery requirement for endpoints that require validation, even when an app doesn't call app.UseAntiforgery()". Two cases still need builder.Services.AddAntiforgery() and app.UseAntiforgery(): a host that isn't built with WebApplication, where the middleware isn't added, and an app that sets DisableCsrfProtection. Without either middleware, the request throws. (Microsoft Learn: Minimal APIs antiforgery checks, Microsoft Learn: Prevent Cross-Site Request Forgery (XSRF/CSRF) attacks in ASP.NET Core)
If your identity provider runs on .NET 11, check its cross-origin endpoints. A SPA exchanges its authorization code by posting to the provider's token endpoint from its own origin, and the provider's check rejects that request: "It's cross-origin. It's a POST. It will be rejected." (Abuhakmeh: Understanding .NET 11 Automatic CSRF Protection) The request gets through when the provider opts the endpoint out, or trusts the SPA's origin with the kind of CORS policy described above. A same-origin BFF, as Browser clients recommends, makes the token request from the server, so the browser never sends it.
A second case is still open. With response_mode=form_post, the provider posts back to your app's /signin-oidc from its own domain, and it's not yet known whether the check lets that through. (Abuhakmeh: Understanding .NET 11 Automatic CSRF Protection) When it's known, state the answer, and drop this note. Review by 2027-02-28.
CORS
Name every CORS policy, and never combine a wildcard origin with credentials. Microsoft Learn calls two combinations insecure: "Specifying AllowAnyOrigin and AllowCredentials", and "Bypassing the built-in checks by using SetIsOriginAllowed(_ => true) together with AllowCredentials". (Microsoft Learn: Enable Cross-Origin Requests (CORS) in ASP.NET Core)
Apply a named policy to each endpoint or group with [EnableCors("<policy>")] or .RequireCors("<policy>"), instead of one permissive default. Otherwise, a policy you widen for one endpoint widens what the whole app accepts. A policy that calls .AllowCredentials() also decides which cross-origin requests the CSRF middleware trusts: the ones from its allowed origins. For details, see CSRF defence in depth.
Security headers and output encoding
Send a baseline of security headers with NetEscapades.AspNetCore.SecurityHeaders, and give the Content Security Policy (CSP) a nonce instead of unsafe-inline. Bowden's baseline is:
X-Frame-Options: DENYX-Content-Type-Options: nosniffReferrer-Policy: strict-origin-when-cross-origin- The three
Cross-Origin-*policies Permissions-Policy- HSTS outside development
For an interactive Blazor circuit, prefer the nonce, and fall back to hashes.
(Bowden: Implement a secure Blazor Web application using OpenID Connect and security headers, Bowden: Revisiting using a Content Security Policy (CSP) nonce in Blazor, NetEscapades.AspNetCore.SecurityHeaders: README)
app.UseSecurityHeaders(new HeaderPolicyCollection()
.AddDefaultSecurityHeaders()
.AddCrossOriginOpenerPolicy(policy => policy.SameOrigin())
.AddPermissionsPolicy(policy =>
{
policy.AddDefaultSecureDirectives();
// The secure defaults turn off publickey-credentials-get, which a passkey sign-in needs.
policy.AddPublickeyCredentialsGet().Self();
policy.AddPublickeyCredentialsCreate().Self();
})
.AddContentSecurityPolicy(csp =>
{
csp.AddDefaultSrc().Self();
csp.AddScriptSrc().Self().WithNonce();
csp.AddObjectSrc().None();
csp.AddFormAction().Self();
csp.AddFrameAncestors().None();
}));
Your AddContentSecurityPolicy call replaces the policy that AddDefaultSecurityHeaders() sets, because the collection keeps one policy per header. So restate its form-action 'self': default-src doesn't cover where a form submits. AddDefaultSecurityHeaders() doesn't send Permissions-Policy, so add it. The secure defaults turn off publickey-credentials-get, so allow it, and allow publickey-credentials-create beside it. In a WebAssembly render mode, add .WasmUnsafeEval() to script-src, or the browser won't run the .NET runtime. Blazor's ImportMap renders an inline script, so give it the request's nonce. (NetEscapades.AspNetCore.SecurityHeaders: README, NetEscapades.AspNetCore.SecurityHeaders: HeaderPolicyCollectionExtensions.cs, NetEscapades.AspNetCore.SecurityHeaders: CspDirectiveBuilderExtensions.cs, Microsoft Learn: Enforce a Content Security Policy for ASP.NET Core Blazor, Bowden: Revisiting using a Content Security Policy (CSP) nonce in Blazor)
<ImportMap AdditionalAttributes="@(new Dictionary<string, object> { ["nonce"] = HttpContext?.GetNonce() ?? "" })" />
Razor encodes output "sourced from variables, unless you work to prevent this behavior". Never pass untrusted input to HtmlString, because that "exposes an XSS vulnerability". (Microsoft Learn: Prevent Cross-Site Scripting (XSS) in ASP.NET Core)
Blazor Web Apps send frame-ancestors 'self' without extra code. Before .NET 11, a CSP without unsafe-inline styles breaks the Virtualize component. .NET 11 fixes it: the component no longer renders inline style attributes on its spacer and placeholder elements. (Microsoft Learn: Enforce a Content Security Policy for ASP.NET Core Blazor, Microsoft Learn: What's new in ASP.NET Core in .NET 11)
If client-side script writes to the DOM, enable Trusted Types, which moves the check into the browser: "APIs like innerHTML must be passed a TrustedHTML object". (Lock: Preventing client-side cross-site-scripting vulnerabilities with Trusted Types)
Open redirects
Before you redirect to a URL from the request, check that it's local. Since .NET 10, RedirectHttpResult.IsLocalUrl works outside MVC. LocalRedirect "throws an exception if a non-local URL is specified". (Microsoft Learn: What's new in ASP.NET Core 10, Microsoft Learn: Prevent open redirect attacks in ASP.NET Core)