sudo with MFA

sudo with MFA lets you run sudo commands in Websh terminal sessions without permanent sudo privilege. When you enter a sudo command, MFA verification is required before the command executes.

This page covers interactive terminal sessions. For sudo in an automated pipeline running under a token, see Command patterns and sudo—a token is authorized differently and sudo policies do not apply to a service token.

Requirements

  • Alpamon 1.3.2 or later installed on the target server
  • sudo with MFA enabled in Server access policies under Policies (this automatically installs the required PAM module on servers)

Enable sudo with MFA

  1. Go to Policies > Server access in the sidebar (see Server access policies)
  2. Enable Use sudo with MFA
  3. The PAM module is automatically installed on the servers running Alpamon 1.3.2+ that are connected at that moment

Note: A server that is offline at that moment does not receive the install, and there is no automatic retry once it reconnects. Install alpamon-pam on that host yourself—see The user has no sudoers rule.

Note: The Policies menu is visible only to Superuser members, and enabling sudo with MFA requires superuser privileges. Staff users can use sudo with MFA after it is enabled but cannot change this setting.

Note: The Use sudo with MFA toggle is available only on Alpacon Cloud (Auth0-based) workspaces—self-hosted, token-authenticated workspaces don’t show this setting.

Note: sudo with MFA works independently from the Allow direct root access setting. Even when direct root access is disabled, users can still run sudo commands through sudo with MFA.

Disabling sudo with MFA

Turning Use sudo with MFA off in Server access policies takes effect immediately and changes behavior across the whole workspace:

  • Alpacon stops authorizing sudo. Every sudo request that reaches Alpacon is refused, on every server, whether or not the PAM module is installed there. The denial carries the code WORKSPACE_SUDO_WITH_MFA_DISABLED—see “Alpacon denied this sudo command”. A system account that already had its own sudoers permission before Alpacon managed the host keeps it.
  • Your servers are left alone. Nothing is uninstalled and no command is sent to any server. The alpamon-pam package stays installed, and keeps its configuration and the sudoers rule it manages, but it has no effect while the setting is off.
  • Requests already awaiting approval are not rejected. They stay in the approval queue, but approving one no longer lets the sudo command run, and the authorization behind it expires on its own deadline.
  • “Disable sudo outside Websh” is turned off. Because that setting depends on sudo with MFA, it is switched off automatically.

Disabling is a policy change only—it stops Alpacon from authorizing sudo and changes nothing on your servers. That makes it fully reversible: turn the setting back on and sudo with MFA works again, with no repair needed on the servers themselves.

Re-enabling Use sudo with MFA authorizes sudo again immediately. It also installs alpamon-pam on every server that is connected at that moment, so any server still missing the package picks it up.

How it works

When you run a sudo command in the terminal:

  1. Enter a sudo command (for example, sudo systemctl restart nginx).
  2. An MFA verification required overlay appears in the terminal. Click Click to verify to open the verification window.
  3. After you complete MFA, the command executes.
  4. Subsequent sudo commands don’t require MFA again until the sudo with MFA timeout expires. This duration is set by workspace administrators in Server access policies.

If verification fails or the MFA session expires, the terminal asks you to re-run the command to authenticate again.

Sudo policies and grants

How a sudo command is authorized depends on your workspace’s Privileged access settings under Policies (superuser only; Alpacon Cloud/Auth0 workspaces):

  • Sudo policies — administrators can pre-authorize specific commands for certain users or servers. A policy bound to a work session can allow MFA bypass, so a non-interactive caller (for example, an AI agent running exec) can run those exact commands without an interactive MFA prompt.
  • Approval — a sudo request can be authorized by an administrator’s approval.

Every authorization—by direct permission, policy, or approval—is recorded. Review it in Sudo history.

Compatibility with sudo-rs

Ubuntu 25.10 and later (including 26.04) ship sudo-rs as the default sudo. sudo with MFA works on these hosts and requires the alpamon-pam package version 1.1.2 or later—Alpacon detects sudo-rs and authorizes sudo commands through PAM.

With classic sudo (1.9+), Alpacon also registers a separate sudo approval plugin in /etc/sudo.conf. sudo-rs has no plugin interface, so that plugin is not used and does not appear in /etc/sudo.conf on sudo-rs hosts. This is expected and not a misconfiguration.

Note: When a sudo command is denied on a sudo-rs host with no terminal attached (for example, through alpacon exec), sudo-rs cannot display the denial reason and reports A terminal is required to authenticate instead. See PAM and sudo issues to find the actual cause.

Last updated: