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.

By default the redirect applies to web pages only, and any path containing /api/ is left alone. Set security.strict_session_gates to true (added in 4.5.0, 4.4.2 and 4.3.6) to also refuse internal API calls with a 403 until setup is done, and to redirect web pages such as /settings/api/logs. API v1 and v2 use API keys, not the session, and are not affected. See Opt-in Hardening.

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.

Passkeys and Security Keys

Poweradmin does not support passkeys or hardware security keys (WebAuthn) for local accounts yet. This is planned as an extra MFA method, tracked in #1679.

You can use them today by signing in through an identity provider that supports passkeys, such as Keycloak, Microsoft Entra ID or Authentik:

  1. Set up OIDC or SAML login in Poweradmin
  2. In the identity provider, enable passkeys or security keys and require them for the Poweradmin client or application
  3. Optionally set mfa.skip_for_external_auth to true, so MFA enforcement does not also make OIDC and SAML users set up Poweradmin MFA (added in 4.5.0)

Poweradmin does not check which method the identity provider used. Passkeys are only required if the identity provider is configured to require them. Local accounts that log in with a password still use Poweradmin's own MFA.

Disabling MFA

To disable MFA on your account:

  1. Navigate to Account in the top navigation bar
  2. In the MFA section, enter a current code next to Disable MFA: a code from your authenticator app, a code sent by email, or one of your recovery codes
  3. Click Disable MFA - it takes effect immediately

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

The code proves you still hold the second factor, so someone using a stolen browser session cannot switch MFA off. Regenerate Recovery Codes asks for a code the same way. With email verification, click the button with the field empty and a code is sent to you; enter it and click again. If the email cannot be sent, the page says so and you can use a recovery code instead. Wrong codes are limited the same way as at sign-in (max_verify_attempts and verify_lockout_duration, see Configuration), but on their own counter, so they never lock you out of logging in.

Asking for a code is new in 4.5.2 and 4.6.0. Earlier versions disable MFA and regenerate recovery codes without one.

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. This is still the only way back for a user who has lost every factor: since 4.5.2 and 4.6.0 the user cannot switch MFA off without a current code either.

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.