Force password change (temporary passwords)

When an admin sets a temporary password for a member, the temp credential must not grant ongoing access — the only thing it should allow is setting a new password. The mustChangePassword flag does that, with two layers:

• Surfaced flag (always on) — the user's mustChangePassword is returned on the login response and on /auth/me, so the UI can route straight to the change-password screen.
• Hard-block guard (opt-in) — when enabled, the API itself rejects everything except the change-password flow until the password is rotated. The API is the real gate; the UI redirect is just convenience (and a direct API call can't bypass it).

1. Enable enforcement

NestAuthModule.forRoot({
  // …
  mustChangePassword: { enforce: true }, // hard-block at the guard (default: surface-only)
});

2. Set the flag when an admin assigns a temp password

Set it only on the admin-sets-another-user's-password path — not on self-service set-password or a member's own change (they pick their own there), and not on invites (the member sets their own).

// In your "admin sets a temporary password" handler:
await user.setPassword(tempPassword);              // NestAuthUser.setPassword()
await this.userService.updateUser(user.id, { mustChangePassword: true });
// (revoking the member's existing sessions is also fine, but no longer required —
//  the guard alone makes the temp credential useless beyond changing the password.)

3. What the guard allows while the flag is set

With enforce: true, a flagged user gets 403 MUST_CHANGE_PASSWORD on every guarded route except the allowlist needed to finish signing in and rotate the password:

• change-password, logout
• the current-user / session endpoints (/auth/me, /auth/user, verify-session)
• refresh-token
• the MFA and email/phone verification routes (so a 2FA user can complete sign-in)

Exempt your own routes that must stay reachable with @SkipMustChangePassword():

import { SkipMustChangePassword, Auth } from '@ackplus/nest-auth';
 
@Auth()
@SkipMustChangePassword()
@Get('terms')
terms() { /* reachable even while a password change is pending */ }

4. It clears itself

A successful change-password (or set-a-new-password via reset-password) clears mustChangePassword automatically — the user resumes normal access.

Client

const { mustChangePassword } = await client.login(dto);   // surfaced on login
// …or read it any time from /auth/me:
const me = await client.getSessionUserData();             // me.mustChangePassword
if (me.mustChangePassword) routeTo('/change-password');
// A 403 with code MUST_CHANGE_PASSWORD on any other call means the same thing.

Multi-account apps

With allowMultipleAccounts: true you sign in through addAccount(), not login(). The snapshot it resolves to carries the same flag, so the prompt works without an extra /auth/me call:

const account = await accounts.addAccount(loginDto);
if (account.mustChangePassword) routeTo('/change-password');

const { addAccount } = useAccountSwitcher();
 
const account = await addAccount(loginDto, { meta: { tenantName } });
if (account.mustChangePassword) router.push('/change-password');

completeMfa(...) / commitAccount(...) report it too, so an MFA-gated sign-in is covered.

It is one-shot, on purpose. mustChangePassword appears only on the snapshot returned by the sign-in call — never on listAccounts() snapshots, and it is not persisted. A cached true would survive the password change and bounce the user back to the change-password screen forever. To re-check later, read /auth/me (client.getSessionUserData()), which is always current. undefined means "not observed here", not "false" — with enforce: true the guard is still the real enforcement, so a missed redirect degrades to a server-side block, never to open access.

Related

• Invite a member.
• Multi-account login & switching — the addAccount sign-in path.
• Hooks reference.
• Error codes.