Multi-Factor Authentication

Nest Auth supports four MFA factors out of the box. You can offer one, several, or all four.

The factors

Configuration

import { NestAuthMFAMethodEnum } from '@ackplus/nest-auth-contracts';
 
NestAuthModule.forRoot({
  // …
  mfa: {
    enabled: true,
    required: false,                                 // make MFA mandatory
    methods: [
      NestAuthMFAMethodEnum.TOTP,
      NestAuthMFAMethodEnum.EMAIL,
    ],
    defaultMethod: NestAuthMFAMethodEnum.TOTP,
    allowUserToggle: true,                           // users can turn MFA on/off
    allowMethodSelection: true,                      // users can pick a method
    trustedDeviceDuration: '14d',                    // how long a "trust this device" lasts
    totp: { issuer: 'My App', period: 30 },
    email: { template: 'mfa-code' },
    sms: { provider: 'twilio', template: 'Your code is {code}' },
  },
});

The MFA challenge flow

1. User submits username + password to /auth/login.
2. Server validates the credentials. If MFA is enabled for the user, the response carries isRequiresMfa: true plus a one-shot challenge token (in the access-token slot — but it can't access protected endpoints).
3. Client calls POST /auth/mfa/challenge with the chosen method to send the code (or skips this step for TOTP).
4. User enters the code. Client calls POST /auth/mfa/verify with { otp, method, trustDevice? }.
5. Server returns the final access + refresh tokens. If trustDevice: true, also a trustToken.

The JS client wraps all of this:

const result = await client.login({ credentials: { email, password } });
 
if (result.isRequiresMfa) {
  await client.send2fa('email');
  const code = await promptUserForCode();
  await client.verify2fa({ otp: code, method: 'email', trustDevice: true });
}

Recovery codes

When a user enables MFA, POST /auth/mfa/generate-recovery-code returns a code once. The library never returns it again. You must show it to the user immediately and tell them to save it somewhere safe.

If they lose their TOTP device, they call POST /auth/mfa/reset-totp with the recovery code — this disables every MFA secret on the account, letting them log in with just their password and re-enroll.

The MFA recovery codes recipe covers the UX in detail.

Trusted devices

When the user verifies MFA with trustDevice: true, the server returns a trustToken. The client persists it (default header name nest_auth_device_trust, configurable via mfa.trustDeviceStorageName). On subsequent logins, the client sends the token in the configured header — if it's valid and not expired, the MFA challenge is skipped for that session.

The duration is set by mfa.trustedDeviceDuration (any ms string). Each trusted device row lives in nest_auth_trusted_devices with userAgent and ipAddress for audit.

TOTP enrollment

Users enroll TOTP independently of the login flow:

// 1. Get the secret + QR code data URL
const setup = await client.setupTotp();
// Render setup.qrCode (data URL) and setup.secret in the UI.
 
// 2. User scans the QR with their authenticator app, enters the code.
await client.verifyTotpSetup({ otp: code, secret: setup.secret });

The server verifies the code matches the secret, then marks the device verified. From then on, the user can log in with TOTP codes.

A user can enroll multiple TOTP devices (listTotpDevices, removeTotpDevice) — useful for users who want a phone and a hardware token like a YubiKey.

MFA scope across tenants

In multi-tenant deployments (tenant.enabled = true), MFA enrolment is user-global, not per-tenant. The nest_auth_mfa_secrets and nest_auth_trusted_devices tables key off userId only — there's no tenantId column.

Practical consequences in SHARED mode (one user → many tenants):

• A user enrols TOTP once. The same TOTP code works to sign into every tenant they belong to.
• A trusted-device token earned in tenant A also lets the user skip MFA in tenant B on the same device.
• toggleMfa / resetMfa operate on the user's global MFA state — flipping MFA off in one tenant flips it off everywhere.

This is intentional: in SHARED mode the user really is a single identity, so a single MFA configuration matches the model. The trade-off: if an attacker compromises the user's authenticator, they can sign into every tenant the user belongs to with the same code.

If your security policy requires per-tenant MFA challenges (e.g. tenant Acme stores high-sensitivity data and wants a fresh TOTP prompt on every tenant switch even if MFA is satisfied for the current session), enforce it via loginHooks.onLogin or guards.beforeAuth — the library doesn't ship per-tenant MFA out of the box.

In ISOLATED mode the question is moot: a "user" is per-tenant by definition, so each tenant has its own MFA state automatically.

@SkipMfa()

Some endpoints inside the auth flow itself need to bypass MFA enforcement (e.g. the verify endpoint can't require MFA — that's circular). Annotate them with @SkipMfa():

@SkipMfa()
@Post('mfa/verify')
verify(@Body() dto: IVerify2faRequest) { … }

Related

• Recovery codes recipe.
• Custom trusted-device header recipe.
• Sending Emails — wiring TwoFactorCodeSentEvent to your email provider.
• Sending SMS — same for SMS.