Upgrade to 4.0Changelog
Reference

Identity management module

Account lifecycle endpoints — register, confirm, forgot/reset password, manage info and 2FA.

Maps account lifecycle endpoints. Pair with a sign-in module (cookie, bearer, or JWT).

DI

AddPasswordAuth registers Identity, the split password modules, and account management. A compose host that maps MapIdentityManagementApi registers these:

builder.Services.AddAuthEndpointsIdentity<AppUser, AppDbContext>();
builder.Services.AddPasswordEndpoints();
builder.Services.AddAccountManagementEndpoints();

AddAuthEndpointsIdentity sets RequireConfirmedAccount to true and Stores.SchemaVersion to version 3, then runs the configure callback. A second call for the same TUser returns without registering Identity again.

Map

app.MapGroup("/auth").MapIdentityManagementApi<AppUser>();
// Second group that should expose its own confirm-email route:
// app.MapGroup("/bearer").MapIdentityManagementApi<AppUser>("bearer-confirmEmail");

MapIdentityManagementApi is MapPasswordEndpoints with PasswordLoginMode.None, MapConfirmEmailEndpoints, and MapAccountManagementEndpoints. Passkey reauthentication options stay on that composite. The smaller maps:

identity.MapPasswordEndpoints<AppUser>(PasswordLoginMode.None);
identity.MapConfirmEmailEndpoints<AppUser>();
identity.MapAccountManagementEndpoints<AppUser>();

MapAccountManagementEndpoints maps POST /manage/password. That route returns 404 when password sign-in is not mapped. It maps POST /confirmIdentity/passkeyOptions when passkey services are registered. AddPasskeyEndpoints registers them. AddPasswordAuth registers them when Passkeys.ServerDomain is set. MapIdentityManagementApi always maps that route. Confirm-email is mapped once per endpoint name. The default name is AuthEndpointsEndpointNames.ConfirmEmail<AppUser>(). A later map with that name leaves the first route in place. A missing AddPasswordEndpoints or AddAccountManagementEndpoints throws InvalidOperationException when the map runs. The message names the Add* to call. MapConfirmEmailEndpoints throws when AddAccountAbuseRateLimiting was not called.

Routes

Relative to the group prefix. The password facade uses /auth:

MethodPathNotes
POST/registerCreates user; duplicate email returns 200 OK (no enumeration). Rate-limited.
GET/confirmEmailQuery userId, code, optional changedEmail
POST/resendConfirmationEmailAuth + CSRF + rate limit. Signed-in user only; body email is ignored.
POST/forgotPasswordRate-limited
POST/resetPasswordRate-limited
GET/manage/authMethodsReAuth methods (see ReAuth)
POST/confirmIdentityStep-up proof. Auth + CSRF + rate limit.
POST/confirmIdentity/emailCode/sendEmail-code step-up send. Mapped when AddEmailCodeSendEndpoints or AddEmailCodeEndpoints was called. AddEmailCodeSignInEndpoints alone leaves it unmapped. Auth + CSRF + ConfirmIdentity.EmailCode.
POST/confirmIdentity/passkeyOptionsPasskey options for step-up. Auth + CSRF + rate limit.
GET/manage/2fa2FA status
POST/manage/2faEnable/disable 2FA — CSRF + ReAuth
GET/manage/infoCurrent user info
POST/manage/infoUpdate info — CSRF + ReAuth
POST/manage/passwordSet a password when the account has none — CSRF + ReAuth + AccountAbuse

confirmEmail

Query string on GET /confirmEmail:

QueryRequiredNotes
userIdyesIdentity user id
codeyesConfirmation (or change-email) token from the emailed link
changedEmailnoWhen set, confirms a change to that email and updates the user name

When ConfirmEmailRedirectUri is set (PasswordAuthOptions.EmailConfirmation on the password facade, AuthEndpointsOptions.EmailConfirmation on a composed host), success and failure return 302 to that URI with status and flow instead of the thank-you body or 401. The account mutation still runs first. Leave the option unset for callers that expect 200 or 401. See Configuration options.

resendConfirmationEmail

Requires a signed-in user (RequireAuthorization + CSRF). The request body email (ResendConfirmationEmailRequest) is ignored; the handler resends to the signed-in user's email.

With RequireConfirmedAccount set to true (the default), an unconfirmed user cannot sign in, so that user cannot call this endpoint. Resend helps only when RequireConfirmedAccount is false, or after a signed-in user changes their email. There is no anonymous resend endpoint.

Set a password

POST /manage/password sets a password on an account that has none. The body is { "newPassword" }. The route requires a signed-in user, a CSRF token, and a ReAuth proof, and it uses the AccountAbuse rate limit.

MapPasswordAuth, MapAccountManagementEndpoints, and MapIdentityManagementApi map the route. When password sign-in is not mapped (POST /login or JWT POST /create), the route returns 404, including for an anonymous caller. A password sign-up or recovery map does not count. An anonymous caller gets 401 when password sign-in is mapped.

A 400 validation problem UserAlreadyHasPassword means the account already has a password. Change that password with POST /manage/info and oldPassword. An empty newPassword is 400 PasswordRequired. Password-rule failures use the Identity codes.

On success the response is empty 200. The handler calls AddPasswordAsync, which rotates the security stamp, and sends IAccountSecurityEmailSender<TUser>.SendPasswordSetAsync. The default sender is LoggingAccountSecurityEmailSender<TUser>, which logs and does not send mail. AddAccountManagementEndpoints and AddJwtEndpoints register it when no sender is registered. Register an implementation to deliver the notice. The password is not included. When the application cookie authenticated the request, the handler refreshes that sign-in so the acting browser session stays. Other sessions that check the stamp end. The ReAuth proof was issued for the previous stamp, so the next sensitive action needs a new proof.

Authorization

Management authorize attribute accepts registered schemes among: application cookie, Identity bearer, and JWT bearer.

Sensitive manage mutations require antiforgery and ReAuth.

Gotchas

  • Map each confirm-email endpoint name once. A second map with the same name leaves the first route in place. See Composition rules.
  • Production hosts that send confirmation or reset mail register a real IEmailSender<TUser>. Register IAccountSecurityEmailSender<TUser> to deliver the password-set notice. Startup logs a warning when LoggingAccountSecurityEmailSender<TUser> is still the registration.
  • Register alone does not sign the user in. Pair it with a sign-in module, or with email-code sign-in.