How to Set Up Two-Factor Authentication in Umami Analytics

Updated: September 2026

If you're running Umami Analytics for your websites, securing the analytics dashboard is just as important as securing the applications you build. Your Umami instance can contain website traffic data, user accounts, team access, and administrative controls, so a compromised password can give an attacker more access than you might expect.

Umami supports two-factor authentication (2FA) using time-based one-time passwords (TOTP). Once enabled, users need both their password and a temporary six-digit code from an authenticator app when signing in.

For developers and teams running self-hosted Umami, 2FA provides an important additional layer of protection against stolen, reused, or leaked passwords.

This guide explains how 2FA works in Umami, how to configure the encryption key required by the server, how individual users can enroll, and how administrators can enforce 2FA across an installation.

Why Enable Two-Factor Authentication in Umami?

A password is only one authentication factor. If an attacker obtains it through phishing, credential stuffing, a password leak, or malware, they may be able to access your Umami account.

With 2FA enabled, logging in requires:

1. Your Umami password.
2. A temporary verification code generated by an authenticator app.

The second factor makes a stolen password significantly less useful on its own.

This is particularly valuable for self-hosted Umami installations, where administrators are responsible for configuring and protecting the application and its environment.

Umami uses TOTP, an established standard supported by popular authenticator applications including:

• Google Authenticator
• Authy
• 1Password
• Other compatible TOTP authenticator apps

The codes are generated locally by the authenticator app and periodically change, so there is no need to receive an SMS message every time you log in.

Umami 2FA Requirements

Two-factor authentication has been available in Umami since version 3.3.0.

Before users can enable 2FA, the Umami server needs a TWO_FACTOR_ENCRYPTION_KEY environment variable.

Umami encrypts stored 2FA secrets at rest using AES-256-GCM. The encryption key must therefore be configured for your installation before 2FA can be enabled.

Generate the encryption key

You can generate a suitable 256-bit key with OpenSSL:

openssl rand -hex 32

This produces a 64-character hexadecimal string.

Add the generated value to your Umami environment configuration:

TWO_FACTOR_ENCRYPTION_KEY="your generated key"

Replace your generated key with the value generated by OpenSSL.

For example:

TWO_FACTOR_ENCRYPTION_KEY="a64-character-hexadecimal-key-generated-by-openssl"

Keep the key secure

The encryption key is security-sensitive configuration data. Treat it like other secrets used by your Umami installation.

The key should be:

• Unique to your Umami installation.
• Kept secret.
• Stored securely alongside your other application secrets.
• Included in your backup and disaster-recovery strategy.

One important detail is that changing or losing this key can make previously stored 2FA secrets unreadable. Users affected by this will need to enroll in 2FA again.

If you're deploying Umami with Docker, Kubernetes, a managed hosting platform, or another deployment system, configure the variable through the appropriate secret or environment-variable mechanism rather than committing it to your source-control repository.

How to Enable 2FA for Your Umami Account

Once TWO_FACTOR_ENCRYPTION_KEY is configured, individual users can enable two-factor authentication from their account settings.

1. Open your profile settings

Log in to your Umami dashboard.

Click the profile button in the side navigation and select Settings.

Then open the Security section.

2. Enable two-factor authentication

In Security settings, find:

Enable two-factor authentication

Turn the option on.

Umami will display a QR code that contains the information your authenticator app needs to configure the account.

3. Add Umami to your authenticator app

Open your preferred authenticator application.

Scan the QR code displayed by Umami.

For example, you can use Google Authenticator, Authy, or 1Password.

Umami also provides a manual entry key. This is useful if scanning the QR code isn't possible or if you prefer to enter the TOTP secret manually.

4. Verify the setup

After adding the account to your authenticator app, the app will generate a six-digit verification code.

Enter the current six-digit code into Umami to confirm that the authenticator has been configured correctly.

Once the code is accepted, 2FA is enabled for your account.

Save Your Umami Backup Codes

After successfully enabling 2FA, Umami generates 10 single-use backup codes.

This is an important step that shouldn't be skipped.

Backup codes provide an alternative way to authenticate if you lose access to your authenticator app. For example, you might need one if you lose your phone, replace your device, or accidentally remove the Umami entry from your authenticator.

Store the codes securely

Umami displays the backup codes only once, so save them somewhere secure before leaving the setup screen.

A password manager is generally a good place to store recovery information.

Remember that each backup code can only be used once. Once a code has been consumed, it cannot be used for another login.

If you lose both your authenticator access and your backup codes, an administrator may need to reset your 2FA configuration.

What Happens When You Log In With 2FA?

After 2FA has been enabled, the normal Umami login process gains an additional step.

First, enter your Umami username or email and password as usual.

After your password is accepted, Umami asks for a six-digit authentication code.

Open your authenticator app and enter the current TOTP code.

If you don't have access to your authenticator app, select:

Use a backup code

You can then enter one of your unused backup codes.

Failed login attempts

Umami limits repeated failed 2FA attempts.

After five failed attempts, additional attempts are locked for 15 minutes.

This helps reduce the risk of someone repeatedly guessing authentication codes.

How to Disable 2FA

If 2FA is no longer required for your account, you can disable it from:

Settings → Security

Turn off the two-factor authentication option.

For security, Umami requires you to confirm the change by entering:

• Your Umami password.
• A valid code from your authenticator app.

If an administrator has required 2FA for your account, you won't be able to disable it yourself. An administrator must first remove the applicable requirement.

How Administrators Can Require 2FA

Allowing users to enable 2FA voluntarily is useful, but organizations may want to make it mandatory.

Umami administrators can require two-factor authentication at three different levels:

This gives administrators flexibility depending on how their Umami installation is organized.

Require 2FA globally

If every account on your Umami instance should use 2FA, go to:

Admin → Security

Enable the global 2FA requirement.

This is a good option for installations where all users should meet the same security standard.

Require 2FA for a specific user

To enforce 2FA for an individual account, go to:

Admin → Users → select the user

From the user's settings, enable the requirement for 2FA.

This can be useful when only certain accounts — such as administrators or users with sensitive access — need mandatory two-factor authentication.

Require 2FA for a team

If your Umami installation uses teams, you can enforce 2FA for everyone belonging to a particular team.

Go to:

Admin → Teams → select the team → Settings

Enable the team's 2FA requirement.

Every member of that team will then be required to enroll in 2FA.

What Happens When 2FA Becomes Required?

An administrator doesn't necessarily need to manually configure the authenticator for every user.

If 2FA is required for a user who hasn't enrolled yet, Umami prompts that user to configure 2FA the next time they log in.

The user must complete the setup before they can continue using the application.

This means administrators can enforce a security policy without having to collect or manage users' authenticator secrets themselves.

If a user's account is affected by a 2FA requirement, the option to disable 2FA is locked until an administrator removes the requirement.

How to Recover a Locked-Out User

What happens if a user loses their phone and their backup codes?

An administrator can reset the user's 2FA configuration.

Navigate to:

Admin → Users → select the user

From there, the administrator can reset the user's 2FA.

The reset clears the existing:

• 2FA secret
• Backup codes

The user can then enroll in 2FA again from scratch.

When should an admin reset 2FA?

A reset may be necessary when a user:

• Loses their authenticator device.
• Replaces a phone without transferring their authenticator accounts.
• Loses all backup codes.
• Can no longer generate valid TOTP codes.

After resetting the account, the user should immediately configure a new authenticator and securely save the newly generated backup codes.

Deployment Considerations for Developers

If you're responsible for deploying Umami, there are a few things worth considering before enabling 2FA for your users.

Configure the encryption key before enforcing 2FA

Make sure TWO_FACTOR_ENCRYPTION_KEY is configured and available to the Umami application before requiring 2FA.

For a self-hosted installation, verify that the environment variable is present in the actual runtime environment, not just in a local development configuration.

Don't commit the key to Git

The encryption key should be treated as a secret.

Avoid putting it directly into:

• Git repositories
• Public Dockerfiles
• Public configuration files
• Client-side JavaScript
• Documentation intended for public distribution

Use your deployment platform's secret-management or environment-variable functionality where appropriate.

Back up the key

Your database and application configuration aren't the only things that matter for disaster recovery.

Because the 2FA secrets stored by Umami depend on TWO_FACTOR_ENCRYPTION_KEY, losing the key can prevent previously stored 2FA secrets from being decrypted.

Keep the key securely backed up and make sure authorized administrators can recover it during a restoration or migration.

Don't casually rotate the key

Changing TWO_FACTOR_ENCRYPTION_KEY isn't equivalent to changing an ordinary application setting.

Previously stored 2FA secrets encrypted with the old key can become unreadable. Affected users will need to re-enroll in 2FA.

For that reason, treat the key as a persistent installation-specific secret rather than something to rotate casually.

A Practical 2FA Rollout Strategy

If you're introducing 2FA to an existing Umami installation with multiple users, it's worth planning the rollout.

A sensible approach is:

1. Configure the encryption key

Generate the key:

openssl rand -hex 32

Add it to your Umami environment:

TWO_FACTOR_ENCRYPTION_KEY="your generated key"

Restart or redeploy Umami as required by your deployment setup.

2. Test enrollment

Before enforcing 2FA for everyone, have an administrator or test account enroll and verify that:

• The QR code works.
• The authenticator generates valid codes.
• Login requires the TOTP code.
• Backup-code login works.

3. Make sure recovery is understood

Administrators should know where to reset a user's 2FA:

Admin → Users → User

Users should also understand that their backup codes are displayed only once and should be stored securely.

4. Enforce 2FA

Once you're confident the configuration works, choose the appropriate enforcement level:

• Global for every user.
• Per user for selected accounts.
• Per team for selected groups.

This avoids discovering a configuration problem only after locking a large group of users into a mandatory authentication flow.

Common Questions About Umami 2FA

Does Umami use SMS for two-factor authentication?

No. Umami's 2FA implementation uses TOTP, with codes generated by a compatible authenticator application.

Which authenticator apps work with Umami?

Umami uses TOTP, so you can use compatible authenticator apps such as Google Authenticator, Authy, and 1Password.

How many backup codes does Umami provide?

Umami generates 10 single-use backup codes when you complete 2FA enrollment.

Can users disable mandatory 2FA?

No. If an administrator requires 2FA for an account through a global, user-level, or team-level requirement, the user cannot disable it themselves.

An administrator must remove the requirement.

What happens if I lose my authenticator?

Use one of your unused backup codes to log in.

If you also lost your backup codes, an administrator can reset your 2FA configuration so you can enroll again.

What if the TWO_FACTOR_ENCRYPTION_KEY is lost?

Previously stored 2FA secrets may become unreadable. Affected users will need to re-enroll in 2FA.

This is why the encryption key should be securely backed up as part of your Umami deployment's disaster-recovery strategy.

Final Thoughts

Two-factor authentication is one of the simplest security improvements you can make to an Umami Analytics installation.

For individual users, enabling 2FA protects the account even if its password is compromised. For administrators, Umami provides flexible enforcement at the global, user, and team levels.

If you're self-hosting Umami, the most important deployment step is configuring and protecting the TWO_FACTOR_ENCRYPTION_KEY before enabling or enforcing 2FA. Once that's done, users can enroll through Settings → Security, connect an authenticator app, verify a six-digit TOTP code, and securely store their 10 backup codes.

For teams running analytics in production, making 2FA part of your normal access-control policy is a small change that can substantially strengthen the security of your Umami dashboard.

Related reading

To protect your Umami installation from the ground up, see our guide to How to Self-Host Umami, and learn how to keep your analytics setup privacy-friendly in GDPR Compliance for Web Analytics.

Get Started with Managed Umami

Ready to try Umami without the DevOps hassle? UmamiEngine provides fully managed Umami analytics with all the depth described above, including secure, privacy-first hosting. No servers, no databases, no maintenance, just privacy-first analytics in minutes. Get started today and take control of your analytics data.