How to Require Multi-Factor Authentication for SSH Gateway

How to require multi-factor authentication for SSH Gateway

Multi-factor authentication (MFA) in SSH Gateway adds a time-based one-time password (TOTP) after the user’s SSH key. SSH Gateway performs MFA if all of a user’s roles that permit access to a host require MFA.

Prerequisites

  • Users: Each user of the roles that permit access to the host must enable MFA on their Profile page first. A user without MFA cannot use a role that requires MFA in SSH Gateway or the Control Panel. See How to Configure Multi-Factor Authentication .

1. Create a role for automation

To connect from automation, such as a CI/CD pipeline, use a role without MFA for the automation user.

  1. Role: Create a role without Require multi-factor authentication enabled. See How to Create Roles and Invite Users .
  2. Access: In SSH Connect, choose the role in Roles with access on each host the automation user needs. To let the automation user reach every host in the account, including new ones, permit POST on /ssh-hosts/*/authorization in the role instead.
  3. User: Invite only the automation user to the role.

The automation user needs its own SSH public key , which a service user cannot add.

2. Require MFA on each role

Enable Require multi-factor authentication (mfa_required in the API) on every role that permits access to the host, but not on the role for automation. This includes Editor and Account owner, which permit POST on /ssh-hosts/*/authorization by default. Roles with access on the host shows these roles, but not those from a parent account or those that permit POST on /ssh-hosts/** or /**.

3. Connect with MFA

An OpenSSH connection to the host then looks like this:

ssh joesample@sampleco-cp1@ssh.webscale.com

Multi-factor authentication is required to reach sampleco-cp1.
(joesample@sampleco-cp1@ssh.webscale.com) MFA code:

For 24 hours after SSH Gateway verifies a user’s TOTP, their connections from the same public IP address to any host skip the TOTP.

Further reading

Have questions not answered here? Contact Support to get more help.

Last modified on October 15, 2026