Skip to content
Rack Gateway

MFA Overview

Multi-factor authentication (MFA) adds a second factor to your Rack Gateway account. The web UI supports TOTP and WebAuthn, plus backup codes for recovery.

Supported Methods

Section titled “Supported Methods”

Backup Codes

One-time recovery codes generated during enrollment.

Backup codes →

MFA Enrollment

Section titled “MFA Enrollment”

First-Time Setup

Section titled “First-Time Setup”

If MFA is required by your organization, you will be redirected to Account Security after login.

Add MFA Later

Section titled “Add MFA Later”
  1. Open the web UI
  2. Go to Account Security
  3. Click Enable MFA (or, once you have a method, Add Method under Registered MFA Methods)
  4. Choose Authenticator app or Passkey or security key

With both an authenticator app and a security key, Preferred sign-in method picks the one you’re asked for first, on the web and in the CLI.

Disable MFA

Section titled “Disable MFA”

Disable MFA on Account Security removes every method (type DISABLE to confirm). Each removal needs MFA. If your gateway requires MFA for all users, you must enroll again before you can use anything else.

Step-Up Authentication

Section titled “Step-Up Authentication”

Some sensitive actions require MFA verification even with an active session. Examples include:

  • Revealing a secret env value in the web UI
  • Changing env vars, deploying, restarting or scaling an app
  • Trusting a device, regenerating backup codes, or editing an MFA method
  • Adding another MFA method (your first one needs no verification)

Verifying a factor opens a step-up window, 10 minutes by default and configurable by admins. Only a verified factor opens one: signing in on a trusted device, or without an MFA prompt, doesn’t.

A few actions ask for MFA every time, even inside the window: creating, editing or deleting API tokens, approving deploy requests, adding, changing or deleting users, removing an MFA method, and most security settings. See MFA Requirements for the full list.

Trusted Devices

Section titled “Trusted Devices”

You can trust a device during verification or from Account Security → Trusted Devices. A trusted device skips the MFA prompt at sign-in until its TTL expires (default 30 days). It doesn’t skip step-up: the first sensitive action after signing in still asks for a factor.

Backup Codes

Section titled “Backup Codes”

Backup codes are generated during enrollment and can be regenerated later. Codes are only shown at generation time, so store them securely.

CLI MFA

Section titled “CLI MFA”

The CLI supports MFA verification:

Terminal window
rack-gateway deploy -a myapp --mfa-code 123456
rack-gateway deploy -a myapp --mfa-method webauthn

If you use WebAuthn with the CLI, mark the method as CLI Compatible in Account Security.

Administrator Controls

Section titled “Administrator Controls”

Admins configure global MFA settings in Settings:

  • Require MFA for all users
  • Step-up window (minutes)
  • Trusted device TTL (days)

A change applies from the next request; the gateway doesn’t need a restart.