Skip to main content

​
Overview

Multi-factor authentication (MFA) adds a second verification step when a user signs in. After MFA is enabled for an account, Mage requires the user’s password or SSO sign in and then a 6-digit code from an authenticator app before issuing a session. Mage supports time-based one-time passwords (TOTP), which work with authenticator apps such as Google Authenticator, Microsoft Authenticator, Authy, and 1Password.
MFA is configured per user account. Each user must enable MFA from their own account settings.

​
Pre-requisites

Before configuring MFA, make sure:
  • User authentication is enabled. See User authentication.
  • Your Mage deployment has run the latest database migrations.
  • The Mage server has the MFA dependencies installed from requirements.txt, including pyotp and qrcode.
  • The user has access to an authenticator app that can scan QR codes.

​
Enable MFA

1

Open MFA settings

Sign in to Mage and go to Settings → Workspace → MFA.
2

Start setup

Click Set up Multi-Factor Authentication.
3

Install or open an authenticator app

Open an authenticator app that supports TOTP codes. Mage supports apps such as:
  • Google Authenticator
  • Microsoft Authenticator
  • Authy
  • 1Password
4

Scan the QR code

Click Next, then scan the QR code with your authenticator app.The QR code adds a new Mage entry to the authenticator app. The app will start showing rotating 6-digit verification codes for that Mage account.
5

Verify the code

Enter the current 6-digit code from the authenticator app and click Next.After the code is accepted, Mage shows a confirmation step.
6

Complete setup

Click Complete Setup to close the setup flow and return to the MFA settings page.The status changes to Active after MFA is enabled for your account.

​
Sign in with MFA

After MFA is enabled, signing in has two steps:
  1. Enter your email or username and password, or complete your configured SSO sign in.
  2. Enter the 6-digit code from your authenticator app on the MFA verification page.
If the MFA verification session expires, return to the sign in page and start again.
After too many invalid MFA codes, Mage temporarily locks MFA verification for that user. Wait 5 minutes, then sign in again and enter a new code from the authenticator app.

​
Disable MFA

To disable MFA for your account:
1

Open MFA settings

Sign in to Mage and go to Settings → Workspace → MFA.
2

Choose disable

Click Disable MFA.
3

Confirm with a current code

Enter the current 6-digit code from your authenticator app and confirm.Mage deactivates the active MFA devices for your account after the code is verified.

​
Troubleshooting