NestAuthModule

NestAuthModule is the entry point for the entire library. You import it once in your AppModule and pass an IAuthModuleOptions config object.

Synchronous form

import { Module } from '@nestjs/common';
import { NestAuthModule } from '@ackplus/nest-auth';
 
@Module({
  imports: [
    NestAuthModule.forRoot({
      appName: 'My App',
      isGlobal: true,
      // …
    }),
  ],
})
export class AppModule {}

Async form

For when your config depends on something injectable (e.g. a ConfigService):

NestAuthModule.forRootAsync({
  isGlobal: true,
  imports: [ConfigModule],
  inject: [ConfigService],
  useFactory: (config: ConfigService) => ({
    appName: config.get('APP_NAME'),
    session: { jwt: { secret: config.get('JWT_SECRET') } },
    // …
  }),
});

You can also use useClass or useExisting patterns — see IAuthModuleAsyncOptions.

Top-level options

Required

Option	Type	Notes
`appName`	`string`	Used in TOTP issuer, audit events, and error messages

Core

Option	Type	Default	Notes
`isGlobal`	`boolean`	`false`	Marks the module as global so you don't need to re-import it in every feature module
`enableAutoRefresh`	`boolean`	`true`	Server-side support for auto-refresh on 401
`routePrefix`	`string`	`'auth'`	Base path segment for all auth routes (e.g. `'account'` serves `POST /account/login`). Applied in addition to any NestJS global prefix — update your client SDK endpoints to match

Authentication methods

emailAuth?: { enabled: boolean };
phoneAuth?: { enabled: boolean };
passwordless?: { enabled: boolean; allowSignUp?: boolean };
 
google?:   { clientId; clientSecret; redirectUri? };
facebook?: { appId; appSecret; redirectUri? };
apple?:    { clientId; teamId; keyId; privateKey; redirectUri? };
github?:   { clientId; clientSecret; redirectUri? };
 
customAuthProviders?: BaseAuthProvider[];

Registration

registration?: {
  enabled?: boolean;                    // default: true
  requireInvitation?: boolean;          // default: false
  autoLoginAfterSignup?: boolean;       // default: true
  collectProfileFields?: IRegistrationCollectProfileField[];
};

collectProfileFields is metadata for the public /auth/client-config endpoint — your signup form can render itself dynamically based on the server's policy. The same endpoint also returns passwordless flags, OAuth public client/app ids, platformAccess.enabled, and accessTokenType so login/signup UIs can adapt without hardcoding.

Sessions & tokens

See Sessions & Tokens for the conceptual overview. Full options:

session?: {
  storageType?: SessionStorageType;
  redis?: RedisSessionOptions;
  accessTokenValidity?: number | string;       // default: '15m'
  refreshTokenValidity?: number | string;      // default: '7d'
  accessTokenType?: 'header' | 'cookie' | null;
  cookieOptions?: CookieOptions;
  jwt?: { secret: string; validateToken?: (payload, session) => boolean };
  maxSessionsPerUser?: number;                 // default: 10
  slidingExpiration?: boolean;                 // default: false
  allowMultipleAccounts?: boolean;             // default: false — enable the account switcher
  customizeSessionData?: (defaultData, user) => SessionDataPayload;
  customizeTokenPayload?: (defaultPayload, session) => JWTTokenPayload;
  onCreated?:  (session, user)        => void;
  onRefreshed?: (oldSession, newSession) => void;
  onRevoked?:  (session, reason)      => void;
};

allowMultipleAccounts turns on logging into several accounts on one client and switching the active one (Gmail/Slack-style). The backend is already multi-session, so this only opts in the capability — it's surfaced on GET /auth/client-config ({ multipleAccounts: { enabled } }) and, in cookie mode, switches the server to per-account cookies + an active-account selector. See the Multi-account login & switching recipe.

MFA

See MFA.

mfa?: {
  enabled?: boolean;
  required?: boolean;
  methods?: NestAuthMFAMethodEnum[];
  defaultMethod?: NestAuthMFAMethodEnum;
  totp?:  { issuer; period };
  email?: { template };
  sms?:   { provider; template };
  allowUserToggle?: boolean;
  allowMethodSelection?: boolean;
  trustedDeviceDuration?: string | number;     // default: '7d'
  trustDeviceStorageName?: string;             // default: 'nest_auth_device_trust'
};

Multi-tenancy

See Multi-Tenancy.

tenant?: {
  enabled?: boolean;
  mode?: TenantModeEnum;
};
defaultTenantOptions?: IDefaultTenantOptions;
platformAccess?: {
  enabled?: boolean;
  validate?: (request) => boolean | Promise<boolean>;
};

Authorization

roleGuards?: string[];                              // default: ['web']
authorization?: {
  resolveRoles?:       (user) => Promise<string[]>;
  resolvePermissions?: (user, roles) => Promise<string[]>;
};

Password & OTP

password?: {
  passwordResetTokenExpiresIn?: number | string;
  hash?:   (password) => Promise<string>;
  verify?: (password, hash) => Promise<boolean>;
  argon2?: { memoryCost; timeCost; parallelism };
};
 
otp?: {
  secret?: string;
  generate?: (length?, format?) => string | Promise<string>;
  length?: number;                                  // default: 6
  format?: 'numeric' | 'alphanumeric';              // default: 'numeric'
  codeExpiresIn?: number | string;                  // default: '30m'
};

Force password change

mustChangePassword?: {
  enforce?: boolean;                                // default: false (surface-only)
};

The mustChangePassword flag on a user is always surfaced (login response + /auth/me) and cleared on a successful password change. Set enforce: true to additionally hard-block at the guard: a user with the flag set is rejected with 403 MUST_CHANGE_PASSWORD on every guarded route except change-password, logout, the current-user/session endpoints, and the MFA/verification routes (so a 2FA user can still finish signing in and reach the change-password screen). Exempt your own routes with @SkipMustChangePassword().

Hooks

Every config-time hook is on the Hooks Reference page. The high-level groupings:

user?:               IUserHooks;
auth?:               IAuthHooks;
registrationHooks?:  IRegistrationHooks;
loginHooks?:         ILoginHooks;
guards?:             IGuardHooks;
errorHandler?:       (error, context) => any;
resolveConfig?:      (context) => Partial<IAuthModuleOptions> | Promise<…>;
clientConfig?:       { factory?: (defaultConfig, context) => any };

Audit

audit?: {
  enabled?: boolean;
  onEvent?: (event: IAuthAuditEvent) => void | Promise<void>;
};

Admin console

See Admin Console.

adminConsole?: {
  enabled?: boolean;
  path?: string;                                    // dashboard sub-path under routePrefix; default: 'admin'
  basePath?: string;                                // full URL path; default: '/<routePrefix>/<path>' (e.g. '/auth/admin')
  secretKey?: string;                               // gates dashboard AND admin signup
  sessionCookieName?: string;
  sessionDuration?: string | number;
  cookie?: CookieOptions;
  allowAdminManagement?: boolean;
};

Debug

debug?: DebugLogOptions;

See Logging & Debugging.

Setup Checklist — boot-time wiring around the module.
Hooks Reference — every hook with execution-order timeline.
API Reference: Types — auto-generated IAuthModuleOptions definition.

On this page