Upgrade to 4.0Changelog
Guides

Require step-up before sensitive actions

Ask a signed-in user to prove their identity again before a sensitive change, then retry the change.

A sensitive change needs a fresh ReAuth proof on top of a sign-in. The proof is the AuthEndpoints.ReAuth cookie, the reauthToken, or both. Neither one signs the user in. A request that sends only that cookie or the X-AuthEndpoints-Reauth header is 401.

Cookie sign-in receives the cookie and reauthToken. A caller signed in with Authorization: Bearer receives reauthToken only. Send that token in X-AuthEndpoints-Reauth. Lifetime, stamp checks, and the schemes are in the ReAuth module.

These actions require ReAuth:

  • POST /auth/manage/2fa, POST /auth/manage/info, and POST /auth/manage/password.
  • Passkey creationOptions, add, rename, and delete.
  • External OAuth unlink.
  • Host endpoints that call .RequireReauth().

The steps assume a signed-in cookie session on the password facade. Both POST /auth/confirmIdentity and POST /auth/confirmIdentity/passkeyOptions require a CSRF token, because management maps them with antiforgery. Get the token from GET /auth/csrfToken and send it in the RequestVerificationToken header. A missing token returns 400 with the body Invalid or missing CSRF token.

Complete step-up

  1. Call the protected action, for example POST /auth/manage/info. A signed-in user without a matching ReAuth proof gets 403. A caller who is not signed in gets 401.
  2. Send GET /auth/manage/authMethods to see which proofs the user has. The response is { "password", "authenticator", "recoveryCodes", "passkeys", "passkeyCount", "emailCode" }.
  3. Collect exactly one proof:
  4. Send the proof to POST /auth/confirmIdentity with the CSRF header.
  5. Check the response:
    • 200 { "reauthToken" }. A cookie sign-in also sets AuthEndpoints.ReAuth. An Authorization: Bearer sign-in does not. Confirm does not sign the user in.
    • 400 "Provide exactly one of Password, TwoFactorCode, TwoFactorRecoveryCode, CredentialJson, or EmailCode.": the body had zero proofs or more than one.
    • 400 with title EmailCodeProofUnavailable: the only proof was emailCode, and that proof is off for this account.
    • 401: the proof was wrong.
  6. Retry the protected action. A browser sends the ReAuth cookie automatically. An API client adds the X-AuthEndpoints-Reauth: <reauthToken> header. A signed-in caller whose security stamp changed after confirm gets 403. After POST /auth/manage/2fa changes the stamp, the 200 response carries a renewed token in the X-AuthEndpoints-Reauth response header. Use that token from then on. The token keeps the original expiry. A password change on POST /auth/manage/info, POST /auth/manage/password, and external unlink do not renew the proof. Complete step-up again after them. Details are in ReAuth.

Use a passkey as the proof

  1. Send POST /auth/confirmIdentity/passkeyOptions with the CSRF header. The options are for the signed-in user.
  2. Call navigator.credentials.get.
  3. Send the credential to POST /auth/confirmIdentity.
const headers = { 'Content-Type': 'application/json', 'RequestVerificationToken': csrfToken };

const options = await fetch('/auth/confirmIdentity/passkeyOptions', {
  method: 'POST', credentials: 'include', headers
}).then(r => r.json());

const credential = await navigator.credentials.get({
  publicKey: PublicKeyCredential.parseRequestOptionsFromJSON(options)
});

await fetch('/auth/confirmIdentity', {
  method: 'POST', credentials: 'include', headers,
  body: JSON.stringify({ credentialJson: JSON.stringify(credential) })
});

A passkey that belongs to a different user returns 401.

Native and mobile clients

Call POST /auth/confirmIdentity with Authorization: Bearer and exactly one proof. Keep reauthToken in memory only, then send it on the sensitive call. Do not store it in durable storage, and do not expect a ReAuth cookie.

const confirm = await fetch('/auth/confirmIdentity', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ password })
});

const { reauthToken } = await confirm.json();

await fetch('/auth/manage/info', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'X-AuthEndpoints-Reauth': reauthToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ oldPassword, newPassword })
});

Changing the password, resetting it, or calling UpdateSecurityStampAsync cancels that in-memory token. Confirm again before the next sensitive call.

Use an emailed code as the proof

emailCode is true 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 leaves it false. Who can use the proof, the code lifetime, and lockout are in the ReAuth module.

  1. Send POST /auth/confirmIdentity/emailCode/send with no body and the CSRF header.
  2. Send { "emailCode" } to POST /auth/confirmIdentity.

A successful confirm returns reauthToken and, for a cookie sign-in, sets AuthEndpoints.ReAuth. It does not create a new sign-in.

Protect your own endpoint

Call .RequireReauth() together with .RequireAuthorization() that signs the user in. AddPasswordAuth registers the ReAuth schemes. A composed host calls AddAccountManagementEndpoints, or AddCookieAuthEndpoints or AddBearerAuthEndpoints, which call it. The policy name stays ReAuthPolicy, and that policy adds no authentication schemes. It does not sign the user in, and it does not replace HttpContext.User.

app.MapPost("/billing/update", handler)
    .RequireAuthorization()
    .RequireReauth();

.RequireAuthorization() without schemes uses the host's default sign-in. With AddIdentityApiEndpoints, that is the application cookie or the Identity bearer token. Pass the JWT scheme as well when that endpoint should accept a JWT. A signed-in caller without a matching proof gets 403. A route that calls .RequireReauth() without a sign-in authorization fails.