Antiforgery (CSRF) rules
AuthEndpoints adds the EnforceAntiforgeryEndpointFilters endpoint filter through RequireAntiforgery(). The filter validates the request with ASP.NET Core IAntiforgery.
Token
| Item | Value |
|---|---|
| Token routes | Password facade: GET /auth/csrfToken for a cookie session, and for JWT cookie refresh. JWT body refresh maps no token route. |
| Token response | { "csrfToken": "..." } plus the antiforgery cookie |
| Request header | RequestVerificationToken (the ASP.NET Core default) |
| Failure | 400 with the plain-text body Invalid or missing CSRF token. |
MapBearerAuthEndpoints maps no token route.
When the filter skips the check
The filter skips validation only when all of these are true:
- The Identity application cookie does not authenticate the request.
- The request includes a non-empty
Authorization: Bearer <token>header. - A scheme in
AuthEndpointsAntiforgeryOptions.BearerSchemesauthenticates that request. The default list isIdentity.Bearerand the JWT bearer scheme (Bearer).
An anonymous request is always checked. A request with the application cookie is always checked, even with a bearer token or a ReAuth cookie. A cross-site attacker cannot attach an Authorization header without a CORS preflight, so that header is the CSRF signal.
Hosts that read the access token from a cookie in OnMessageReceived still send the CSRF token. The browser attaches that cookie on its own, and a request with no Authorization header is checked. The filter does not call OnMessageReceived and does not remove the header. A refresh cookie or a ReAuth cookie does not by itself force the check when the access token is in the Authorization header and that scheme authenticates.
Add a bearer scheme
A host or package that registers its own access-token scheme adds it to the list. AuthEndpoints.OpenIddict adds its validation scheme this way when it is registered.
builder.Services.Configure<AuthEndpointsAntiforgeryOptions>(options =>
options.BearerSchemes.Add("MyTokenScheme"));
Add only a scheme that reads its credential from the Authorization: Bearer header. The browser sends a cookie on a cross-site request, so a cookie scheme is never safe here. The filter ignores a scheme whose handler is a cookie handler, and the application cookie still forces the check. The header rule stays: a scheme that reads another header, such as an API key in X-Api-Key, does not skip the check on its own. Call BearerSchemes.Clear() to check every caller on every RequireAntiforgery() route.
The same list decides whether POST /confirmIdentity sets the ReAuth cookie. A request that would skip the CSRF check gets only reauthToken.
Keep the check for every caller
RequireAntiforgery(allowBearer: false) requires the token from every caller, including one with a valid bearer token, and ignores BearerSchemes. Use it on a route a token must never call on its own, such as consent approval or account deletion. It works on a route and on a route group. When a group and a route both require antiforgery, both filters run, so the stricter one wins.
app.MapPost("/account/delete", DeleteAccount)
.RequireAuthorization()
.RequireAntiforgery(allowBearer: false);
RequireAntiforgery() is RequireAntiforgery(allowBearer: true).
Routes that require a token
| Module | Routes |
|---|---|
| Identity management | POST /resendConfirmationEmail, POST /confirmIdentity, POST /confirmIdentity/emailCode/send, POST /confirmIdentity/passkeyOptions, POST /manage/2fa, POST /manage/info, POST /manage/password |
| Cookie sign-in | POST /logout |
| Passkeys | Anonymous ceremonies require a token for a cookie session and for JWT cookie refresh: POST /passkeys/requestOptions, POST /passkeys/register/options, POST /passkeys/register, POST /passkeys/login. Signed-in changes always require a token: POST /passkeys/creationOptions, POST /passkeys/, PATCH /passkeys/, DELETE /passkeys/{credentialIdUrl}. MapPasskeyEndpoints, MapPasskeySignInEndpoints, and MapPasskeySignUpEndpoints with no session, and the shared POST /passkeys/register/options map, keep the token on the anonymous ceremonies. |
| JWT | POST /refresh, POST /logout |
| External OAuth | DELETE /logins/{loginProvider}/{providerKey} |
MapIdentityManagementApi maps the confirmIdentity routes, including POST /confirmIdentity/emailCode/send when the email-code send module is registered, with requireAntiforgery: true. MapReAuthEndpoints called on its own defaults to requireAntiforgery: false.
Anonymous passkey routes validate a token for a cookie session and for JWT with cookie refresh transport. Identity bearer and JWT with body refresh transport omit the filter on those routes. MapBearerAuthEndpoints maps no csrfToken route, and JWT body refresh maps none. Signed-in passkey changes always attach the filter. An Authorization: Bearer access token skips the check under the rule above. Cookie callers, including useCookies=true, still send the token.
Routes without a token check
- Identity management:
POST /register,GET /confirmEmail,POST /forgotPassword,POST /resetPassword, and theGETroutes. - Cookie sign-in:
POST /login. The route accepts JSON only, so a cross-site form cannot post the credentials: the browser sends a CORS preflight first. - Identity bearer sign-in:
POST /login,POST /refresh,POST /logout. - Passkeys:
GET /passkeys/. Identity bearer and JWT body refresh also omit the filter on the anonymous ceremonies. Cookie session and JWT cookie refresh keep it. The shared register-options route keeps it.MapPasskeySignInEndpointsandMapPasskeySignUpEndpointswith no session argument keep it. Signed-in passkey changes keep it on every session. - JWT:
POST /create,GET /verify. - External OAuth: the
loginandlinkroutes and their callbacks. The OAuth correlation and state cookies protect the callbacks. - Email code:
POST /emailCode/sendandPOST /emailCode/verify. Neither route is mapped with the antiforgery filter.
Middleware
RequireAntiforgery() attaches only the endpoint filter. It does not add ASP.NET Core antiforgery metadata, so UseAntiforgery() does not reject the request before the filter's bearer check runs. AntiforgeryEnforcementMiddleware is optional. It rejects requests that UseAntiforgery() already marked as invalid.