Skip to content

Multi-Factor Authentication (MFA)

Multi-factor authentication adds an extra layer of security to your Poweradmin account. With MFA enabled, you need both your password and a time-based one-time password (TOTP) from an authenticator app - or a code sent to your email - to log in.

Poweradmin supports two MFA methods:

  • Authenticator app - uses a TOTP app such as Google Authenticator, Microsoft Authenticator, or Authy
  • Email verification - sends a 6-digit code to your email address (requires mail configuration)

Note: MFA must be enabled globally by an administrator before users can set it up. See Configuration below.

Enabling MFA for Your Account

  1. Log in to Poweradmin and navigate to Account in the top navigation bar
  2. In the MFA section, select your preferred method (authenticator app or email)
  3. If using an authenticator app:
    • A QR code is displayed on screen
    • Open your authenticator app and scan the QR code
    • Enter the 6-digit verification code shown in your app to confirm setup
  4. If using email verification:
    • A verification code is sent to your registered email address
    • Enter the code to confirm setup
  5. After successful verification, MFA is active on your account
  6. Save your recovery codes in a safe place - you will need these if you lose access to your authenticator app or email

Warning: Recovery codes can only be viewed once during setup. Store them securely before closing the page.

Logging In with MFA

Once MFA is enabled, the login flow has an additional step:

  1. Enter your username and password as usual
  2. After successful password verification, you are prompted for your MFA code
  3. Open your authenticator app and enter the current 6-digit code, or check your email for a verification code
  4. If the code is valid, you are logged in

If your authenticator app code is not accepted, check that your device clock is accurate. TOTP codes are time-sensitive and allow a tolerance of approximately 30 seconds.

MFA Enforcement

Administrators can require specific users to set up MFA. This is controlled through two mechanisms:

  • User permission templates - add the user_enforce_mfa permission to a permission template assigned to users
  • Group permission templates - add the user_enforce_mfa permission to a group's permission template, which enforces MFA for all group members

When MFA is enforced, users who have not yet set up MFA will be redirected to the MFA setup page after their next login. They cannot use Poweradmin until MFA is configured.

Note: MFA enforcement requires both the global mfa.enabled and mfa.enforced settings to be set to true in your configuration. See Configuration below.

Since 4.5.0, enforcement can be waived for users who log in through an external identity provider (LDAP, OIDC, SAML) by setting mfa.skip_for_external_auth to true. Use this when the IdP already enforces MFA - it avoids a second OTP prompt in Poweradmin. Local (password) logins are still enforced, and external users can still enable Poweradmin MFA voluntarily.

Disabling MFA

To disable MFA on your account:

  1. Navigate to Account in the top navigation bar
  2. In the MFA section, click Disable MFA - it takes effect immediately, there is no confirmation step

After disabling, you will only need your password to log in.

Note: If MFA is enforced for your account through a user or group template, you cannot disable it. The Disable MFA button is not shown, and a disable request sent anyway is refused with a message saying MFA is required by your organization's security policy. The enforcement has to be removed first.

Recovery

If you lose access to your authenticator app or email:

  1. On the MFA verification screen, enter one of your recovery codes instead of a TOTP code
  2. Each recovery code can only be used once - it is removed from your list after use
  3. After logging in, go to Account and either:
    • Set up MFA again with a new authenticator app
    • Regenerate new recovery codes if your supply is running low

If you have no remaining recovery codes and cannot access your authenticator, contact your Poweradmin administrator. There is no admin screen for this: the user list shows whether MFA is configured, but nobody can clear another user's MFA from the interface or the API. Recovery means removing the user's row from the user_mfa table directly in the database, after which the account logs in with its password alone and can set MFA up again.

Too many failed attempts

After several wrong codes the verification screen stops accepting attempts for a while, and reports too many failed attempts. If you use email verification, any pending code is discarded and no replacement is sent until the wait is over.

A recovery code is still accepted while the second factor is locked, on 4.5.0 as well as the 4.2.x, 4.3.x and 4.4.x lines, and is the documented way back into the account. A wrong recovery code during the lockout is written to the audit log but does not extend the wait.

Wait for the period to pass and try again with a fresh code. In 4.5.0 and later, administrators can change how many attempts are allowed and how long the wait lasts - see Configuration. On the 4.2.x, 4.3.x and 4.4.x lines the limit is fixed at 5 attempts and a 15-minute wait.

Configuration

MFA is configured in config/settings.php under the security section. The two max_verify_attempts and verify_lockout_duration keys below exist from 4.5.0 onwards; on earlier lines they are ignored and the built-in limit of 5 attempts and 15 minutes applies.

'security' => [
    'mfa' => [
        'enabled' => true,
        'enforced' => true,
        'skip_for_external_auth' => false,
        'app_enabled' => true,
        'email_enabled' => true,
        'recovery_codes' => 8,
        'recovery_code_length' => 10,
        'max_verify_attempts' => 5,
        'verify_lockout_duration' => 15,
    ],
],
  • enabled - enable MFA functionality globally. Default: false
  • enforced - enable MFA enforcement (works with user_enforce_mfa permission). Default: false
  • skip_for_external_auth - do not enforce MFA for LDAP, OIDC, or SAML logins; the identity provider is trusted to enforce it. Default: false (added in 4.5.0)
  • app_enabled - allow the authenticator app method. Default: true. Setting it to false hides the option and refuses the setup request. It is ignored if email verification is unusable at the time (turned off, or no mail transport configured), so the last remaining method is never withdrawn
  • email_enabled - allow email verification method (requires mail configuration). Default: true
  • recovery_codes - number of recovery codes to generate per user. Default: 8
  • recovery_code_length - character length of each recovery code. Default: 10
  • max_verify_attempts - wrong codes tolerated before verification is refused. Default: 5 (added in 4.5.0)
  • verify_lockout_duration - minutes to keep refusing attempts once the limit is reached. Default: 15 (added in 4.5.0)

The attempt limit is always active when MFA is enabled and does not depend on the account lockout settings. See Second-factor attempt limit for how it differs from password lockout.

For the full list of security settings, see Security Policies.