Upgrade to 4.0Changelog
Reference

Cookie sign-in module

Identity cookie login, logout, and CSRF token endpoints for browser/web clients.

Cookie sign-in for first-party web and browser clients. Pair with Identity management.

The password facade maps cookie login with MapPasswordSignInEndpoints(AuthEndpointsSession.Cookie) under Path (default /auth). This page describes MapCookieAuthEndpoints. The password check on the password facade is in Password login.

MapCookieAuthEndpoints maps LoginCookie to POST {prefix}/login. The scheme is always IdentityConstants.ApplicationScheme.

DI

builder.Services.AddAntiforgery();
builder.Services.AddCookieAuthEndpoints(); // ReAuth schemes + rate limits

With a cookie session, AddPasswordAuth calls AddPasswordSignInEndpoints and AddCookieSessionEndpoints. It does not call AddCookieAuthEndpoints.

Map

app.MapGroup("/auth").MapCookieAuthEndpoints<AppUser>();

The examples on this page use the prefix /auth, as on the password facade.

MapCookieAuthEndpoints maps cookie POST /login and then MapCookieSessionEndpoints. Session-only logout and CSRF, with no password login on this prefix:

builder.Services.AddCookieSessionEndpoints();
app.MapGroup("/auth").MapCookieSessionEndpoints<AppUser>();

AddCookieAuthEndpoints registers AddPasswordEndpoints, AddCookieSessionEndpoints, and AddAccountManagementEndpoints. A missing AddPasswordEndpoints or AddCookieSessionEndpoints throws InvalidOperationException when the matching map runs. The message names the Add* to call.

Routes

Relative to the group prefix:

MethodPathNotes
POST/loginLoginCookie; application cookie; lockout on failure; rate-limited
POST/logoutAuth + CSRF
GET/csrfTokenAntiforgery token for unsafe methods

Login query string

LoginCookie reads only useSessionCookies. useCookies is ignored.

QueryResult
omittedsession application cookie
useSessionCookies=truesession application cookie
useSessionCookies=falsepersistent application cookie
useCookies=trueignored

Persistent cookie: POST /auth/login?useSessionCookies=false.

Two-factor and remembered browsers

A persistent login (?useSessionCookies=false) with a valid twoFactorCode also sets the Identity two-factor remember-client cookie (rememberClient is true when the login is persistent). Later password logins from that browser skip the 2FA challenge. A session login does not set the cookie. A twoFactorRecoveryCode login never sets it. POST /auth/manage/2fa with { "forgetMachine": true } clears it, and POST /auth/logout clears it.

Passkey register/login uses a different flag table. See Passkeys.

Login body

Identity LoginRequest:

  • email
  • password
  • twoFactorCode (optional)
  • twoFactorRecoveryCode (optional)

CSRF

POST /login does not use antiforgery. The route accepts JSON only, so a cross-site form cannot post the credentials: the browser sends a CORS preflight first. The response sets the application cookie, so that limit is what stops a cross-site login. POST /logout and cookie-authenticated unsafe methods (POST / PUT / PATCH / DELETE on CSRF-protected routes) still require antiforgery.

Client notes

  1. Send cookies: credentials: "include" (or Axios withCredentials: true).
  2. POST /login does not require CSRF.
  3. Before logout and other CSRF-protected unsafe methods, call GET /auth/csrfToken (or your prefix) and send header RequestVerificationToken with the token value.

Gotchas

  • Pipeline must include authentication, authorization, rate limiting, and antiforgery.
  • Do not map cookie and bearer login on the same path without separate groups — pick one sign-in stack per prefix.
  • CORS must allow credentials if the web client origin differs from the API.
  • Do not confuse LoginCookie with bearer Login (MapBearerAuthEndpoints).