Upgrade to 4.0Changelog
Reference

ReAuth module

Require step-up reauthentication before sensitive account and passkey changes: ReAuth routes, proof lifetime, client flow, and host endpoints.

ReAuth (step-up) confirms the user's identity before sensitive mutations. It is included when you map Identity management (with antiforgery in the management map).

Schemes and header

PieceValue
Cookie schemeAuthEndpoints.ReAuth (default 5 minutes, AuthEndpointsReAuthOptions.Lifetime)
Bearer schemeAuthEndpoints.ReAuth.Bearer
HeaderX-AuthEndpoints-Reauth with reauthToken
PolicyReAuthPolicy (no authentication schemes)

Routes

Mapped with management. POST /confirmIdentity and POST /confirmIdentity/passkeyOptions use AuthEndpoints.ConfirmIdentity. POST /confirmIdentity/emailCode/send is mapped by MapAccountManagementEndpoints and MapReAuthEndpoints when AddEmailCodeSendEndpoints or AddEmailCodeEndpoints was called. AddEmailCodeSignInEndpoints alone leaves it unmapped. It uses AuthEndpoints.ConfirmIdentity.EmailCode. AddPasswordAuth adds no email-code module. MapAccountManagementEndpoints adds antiforgery to these POST routes, so send RequestVerificationToken on each. MapReAuthEndpoints adds it only when called with requireAntiforgery: true. Its default is false.

MethodPathNotes
GET/manage/authMethodsAvailable step-up methods, including emailCode
POST/confirmIdentityExactly one proof; CSRF when mapped via management
POST/confirmIdentity/emailCode/sendOnly with email-code send. No body. Sends a step-up code
POST/confirmIdentity/passkeyOptionsWebAuthn options for passkey step-up; CSRF when mapped via management

ConfirmIdentity proof

Provide exactly one of:

  • password
  • twoFactorCode
  • twoFactorRecoveryCode
  • credentialJson (passkey assertion)
  • emailCode (after POST /confirmIdentity/emailCode/send, when emailCode is true)

On success the body is { "reauthToken" }. Cookie sign-ins also set AuthEndpoints.ReAuth. A caller authenticated with Authorization: Bearer and a scheme in AuthEndpointsAntiforgeryOptions.BearerSchemes (default: Identity bearer and JWT) gets the token only, the same rule that skips the CSRF check. Cookie and token share the same lifetime and both include the user's security stamp.

emailCode is offered only when the email-code send module is registered (AddEmailCodeSendEndpoints or AddEmailCodeEndpoints), EmailCode.ReAuth.Enabled is true (the default), the account email is confirmed, and the user has no password, no authenticator, and no passkey. AddEmailCodeSignInEndpoints alone does not offer it. An external login does not hide the proof.

That send route has no body. It requires the signed-in user and a CSRF token when management mapped it. The rate limit is AuthEndpoints.ConfirmIdentity.EmailCode (3 requests per minute per user). The 200 body is { "expiresInSeconds", "resendAfterSeconds" }. The code lasts EmailCode.ReAuth.CodeLifetime (default 5 minutes, 1 through 10). It is single use. A security-stamp change invalidates it. The message purpose is ReAuth (2) and LinkUrl is null. Cooldown and the per-address send cap are separate from sign-in codes. A wrong code counts toward lockout when CountFailuresTowardLockout is true. Five wrong attempts is the default cap.

The step-up credential is an extra proof on top of a sign-in. It is never a sign-in by itself, and it never replaces HttpContext.User. ReAuthPolicy adds no authentication schemes. The requirement looks at the user the route already authenticated, then authenticates the ReAuth cookie and X-AuthEndpoints-Reauth. It succeeds only when that proof has Reauth=true, the same user id, and, when the store supports security stamps, the user's current security stamp. A missing stamp claim is rejected. A password change, reset, or UpdateSecurityStampAsync cancels outstanding cookies and tokens. A request with only the cookie or the header is rejected (401 or 403). A signed-in user with no proof, an expired proof, a proof issued to someone else, or a stale stamp gets 403.

POST /manage/2fa is the only route that renews the proof when it changes the security stamp. The renewed proof keeps the original expiry. A ReAuth cookie is reissued. A proof sent in X-AuthEndpoints-Reauth comes back renewed in the X-AuthEndpoints-Reauth response header of the 200. Send the renewed token on the next request. The old token gets 403. A cross-origin browser client can read that header only when the CORS policy exposes it (WithExposedHeaders("X-AuthEndpoints-Reauth")). Other routes that change the stamp do not renew the proof, so the user completes step-up again after them: a password change on POST /manage/info, POST /manage/password, and external unlink (DELETE /logins/{loginProvider}/{providerKey}).

Pair .RequireReauth() with .RequireAuthorization() that signs the user in. Account management, passkey mutations, and external unlink use the registered application-cookie, Identity bearer, and JWT bearer schemes. .RequireReauth() alone does not authenticate those schemes. A route that omits the sign-in authorization fails.

Lifetime

Default is 5 minutes, non-persistent, no sliding expiration. Set AuthEndpointsReAuthOptions.Lifetime (a TimeSpan) with Configure<AuthEndpointsReAuthOptions>. The password facade and a composed host read the same options. One value drives confirm ExpiresUtc, cookie ExpireTimeSpan, and reauthToken expiry.

Valid range: 1 minute through 60 minutes. Startup rejects zero, negative, over 60 minutes, and InfiniteTimeSpan.

builder.Services.AddPasswordAuth<AppUser, AppDbContext>();
builder.Services.Configure<AuthEndpointsReAuthOptions>(o =>
{
    o.Lifetime = TimeSpan.FromMinutes(2);
});

Protecting host endpoints

builder.Services.AddCookieAuthEndpoints(); // or AddBearerAuthEndpoints. Both register the ReAuth schemes.

app.MapPost("/billing/update", handler)
    .RequireAuthorization() // list the sign-in schemes this route accepts
    .RequireReauth();

.RequireAuthorization() without schemes uses the host default sign-in. Pass the Identity bearer and JWT schemes when those tokens should count, the same way management routes do. A signed-in caller without a matching proof gets 403.

Typical client flow

The steps use the password facade prefix /auth.

  1. GET /auth/manage/authMethods
  2. Collect proof: password, 2FA, a passkey via POST /auth/confirmIdentity/passkeyOptions, or emailCode via POST /auth/confirmIdentity/emailCode/send. The send route exists only when the host adds email-code send (AddEmailCodeSendEndpoints or AddEmailCodeEndpoints). AddEmailCodeSignInEndpoints alone leaves it unmapped.
  3. POST /auth/confirmIdentity with CSRF
  4. Retry the sensitive action with ReAuth cookie and/or X-AuthEndpoints-Reauth

Where ReAuth is required

  • Manage 2FA, info, and set-password mutations
  • Passkey add, rename, delete, and creation options
  • External OAuth unlink
  • Any host endpoint with .RequireReauth()