MFA Verification

The rack-gateway CLI supports multi-factor authentication (MFA) for enhanced security. This page covers how MFA works in the CLI and how to handle step-up authentication prompts.

When MFA is Required

MFA is needed:

1. During login - in the browser, when MFA applies to you (see MFA During Login)
2. For sensitive commands - a step-up, which then covers your other commands for the step-up window
3. For the most sensitive commands - every time, whatever the step-up window

Which commands need MFA is fixed by the gateway, per permission (see MFA Requirements). Administrators set how long the step-up window lasts and whether every user must use MFA.

MFA Methods

The CLI supports multiple MFA methods:

TOTP

Time-based One-Time Passwords (Google Authenticator, Authy, 1Password, etc.)

Multi-factor authentication required (TOTP).
Enter MFA code (TOTP or backup code):

Enter the 6-digit code from your authenticator app. The same prompt takes a YubiKey OTP (touch a YubiKey enrolled as a YubiKey OTP method) or a backup code.

WebAuthn

Security Keys (YubiKey 5, Touch ID, Windows Hello)

Multi-factor authentication required (WebAuthn).
Touch your security key to approve api on staging (2 of 4)... (press Ctrl+C to abort)

The CLI prompts you to touch your hardware security key, and says what the touch is for. User verification is required, so you also enter the key’s PIN (or use the biometric sensor). A key with no PIN set can’t be used until you set one. A command that approves several requests asks for the PIN once, then a touch per approval.

Each time a touch is needed, the CLI also shows a desktop notification (macOS, or Linux with notify-send), so you don’t miss one while the terminal is out of sight. On macOS, allow notifications for Script Editor if they don’t appear. To turn them off, set "touch_notifications": false in ~/.config/rack-gateway/config.json.

Only security keys marked CLI Compatible in the web UI can be used from the CLI.

Note

The prebuilt Linux release has no security key support. WebAuthn needs a CLI built with libfido2; see Installation.

Backup Codes

One-time recovery codes

Enter MFA code (TOTP or backup code): 3F9A1C0B7E42

Use a backup code if you’ve lost access to your primary MFA device. Enter it at the TOTP prompt (or with --mfa-code); case, spaces and hyphens don’t matter.

Caution

Each backup code can only be used once. Generate new codes from the web UI after using them.

MFA During Login

Login MFA happens in the browser, after Google sign-in and before the browser returns to the CLI. If you have no MFA method yet, the browser has you enroll one. See CLI Authentication.

Choosing a Method

For a command, the CLI uses one method, the first of:

1. --mfa-method totp or --mfa-method webauthn
2. Your preferred method, set under Account Security in the web UI
3. mfa_preference in ~/.config/rack-gateway/config.json (for all racks, or in one rack’s entry)
4. A CLI-compatible security key, then TOTP, then a backup code

The CLI doesn’t fall back to another method if that one fails: run the command again with --mfa-method.

Step-Up Authentication

Certain sensitive operations require “step-up” MFA verification, even if you’re already logged in. When this happens:

$ rack-gateway env set LOG_LEVEL=debug -a myapp
Multi-factor authentication required (TOTP).
Enter MFA code (TOTP or backup code):

The CLI asks before sending the command, unless your step-up window is still open.

Commands That Need Step-Up

• deploy, build, releases promote and releases rollback
• env set, env unset and env edit, and env get / env --unmask when they show secret values
• run, exec, ps stop and restart
• scale, apps create and other app changes, and rack update

Step-Up Window

A verified MFA proof opens a step-up window (10 minutes by default; administrators can change it) in which other step-up commands don’t ask again.

The window doesn’t cover changes to protected env vars: env set and env unset with --allow-protected ask for MFA every time, and the gateway verifies it on the request that makes the change. See Protected env vars.

Nor does it cover the commands whose permissions always need MFA (apps delete, builds import, api-token create, api-token update, api-token delete and deploy-approval approve): they ask for MFA every time, and the gateway refuses the request unless it carries a proof it verifies on that request.

One Key Touch Per Command

The CLI asks for MFA once per command and sends that proof with every request the command makes. The first request that needs MFA verifies it and starts the step-up window, which covers the rest of the command. Each proof verifies only once, so a command whose later requests run after the step-up window has expired (for example a deploy whose build takes longer than the window) fails at that point and has to be re-run.

Each WebAuthn challenge is single-use and expires 5 minutes after it’s issued, so complete the key prompt promptly.

Pre-emptive MFA Verification

You can preflight your MFA status or supply a code for non-interactive runs.

Check MFA

# Verify with the method a command would use
rack-gateway test-auth mfa

# Or test one method
rack-gateway test-auth totp
rack-gateway test-auth webauthn

Using —mfa-code

# Provide a TOTP code, YubiKey OTP or backup code up front
rack-gateway deploy -a myapp --mfa-code 123456

Using —mfa-method

# Force a specific method
rack-gateway deploy -a myapp --mfa-method totp
rack-gateway deploy -a myapp --mfa-method webauthn

Testing MFA Status

$ rack-gateway test-auth mfa
Testing authentication to https://gateway.example.com...
✓ Authentication successful
  User is enrolled in MFA: true
  MFA required: true
  Enrolled methods:
    - Authenticator app (totp)
    - YubiKey 5C (webauthn)

Testing preferred MFA method...
  Server preferred method: webauthn

Attempting webauthn authentication...
✓ MFA verification successful with webauthn

Connection Security

The CLI verifies the gateway’s TLS certificate against your system’s trusted roots for every request, including streamed commands (logs, exec, run). It refuses to send your session over plain http:// unless the gateway is on this machine (localhost, 127.0.0.1 or [::1]), and it ignores HTTP_PROXY, HTTPS_PROXY and ALL_PROXY for gateway connections.

Scripting and CI/CD

For automated workflows, you have several options:

API Tokens (Recommended)

API tokens don’t use MFA, so they’re the way to run commands from CI/CD:

export RACK_GATEWAY_API_TOKEN="rgw_..."
export RACK_GATEWAY_URL="https://gateway.example.com"
rack-gateway deploy -a myapp

A token can only do what its permissions allow, and only while its owner’s role allows it too. Managing API tokens and approving deploys can’t be done with a token.

TOTP Code via Flag

If you must use a session with MFA, you can pass the TOTP code:

# Generate TOTP code programmatically (requires totp-cli or similar)
TOTP_CODE=$(totp-cli generate my-totp-secret)
rack-gateway deploy -a myapp --mfa-code "$TOTP_CODE"

Security Warning

Embedding TOTP secrets in CI/CD reduces security. Prefer API tokens instead.

Troubleshooting

“WebAuthn not available”

WebAuthn requires:

• A CLI built with security key support (not the prebuilt Linux release, which prints “WebAuthn support not compiled in this build”); see Installation
• A connected security key, marked CLI Compatible in the web UI

Without it, use --mfa-method totp.

“Invalid TOTP code”

TOTP codes are time-sensitive. Check that:

• Your device clock is synchronized
• You’re using the correct authenticator entry
• The code hasn’t expired (codes change every 30 seconds)

“MFA not enrolled” or “no CLI-compatible MFA methods found”

You need at least one MFA method the CLI can use. Enroll one in the web UI, or mark a security key CLI Compatible:

1. Open the web UI: rack-gateway web
2. Go to Account Security
3. Enroll TOTP or WebAuthn

No interactive terminal

Without a terminal, the CLI reads the MFA code from standard input. In cron jobs and CI, use either:

• API tokens (recommended)
• The --mfa-code flag with a TOTP code

“Backup code rejected”

Backup codes are one-time use. If rejected:

• The code may have already been used
• You may have generated new codes since, which replaces the old set
• You may have mistyped it (each code is 12 characters, 0-9 and A-F)

Generate new backup codes from the web UI.

Security Best Practices

1. Use WebAuthn when possible - Hardware keys are more secure than TOTP
2. Keep backup codes secure - Store them in a password manager, not on your computer
3. Use API tokens for CI/CD - Don’t embed TOTP secrets in automation
4. Regenerate backup codes - After using any, generate a fresh set
5. Review MFA sessions - Check active sessions periodically in the web UI

Next Steps

• MFA Setup Guide - Enroll MFA methods
• API Tokens - Create tokens for CI/CD
• Security Best Practices - Security recommendations