Skip to main content
Version: 19.x (unreleased)

Browser MFA

Report an IssueView as Markdown

Browser MFA enables users of tsh, tctl, and Teleport Connect to complete MFA checks in the browser using a WebAuthn device. This is particularly useful when a user's only registered MFA device is browser-based (e.g. a passkey or Touch ID), which would otherwise prevent them from authenticating via the CLI entirely.

Example usage:

Login to a cluster
tsh login --proxy example.teleport.sh --user alice --mfa-mode=browser

SSH in to a node
tsh ssh --mfa-mode=browser alice@node

Add a new MFA device
tsh mfa add --mfa-mode=browser

Edit a Teleport resource
tctl edit --mfa-mode=browser cluster_auth_preference

How it works​

In the Browser MFA flow, a user runs a command requiring MFA but only has a browser-based WebAuthn device (such as a passkey or Touch ID) registered. The CLI tool requests an MFA challenge from Teleport, then opens the user's browser to /web/mfa/browser/[request_id] where they are prompted to complete the challenge. The browser performs the WebAuthn verification, and the response is encrypted with a secret key generated by the CLI tool. The encrypted response is then forwarded to a local callback server run by the CLI tool, which decrypts it and uses it to complete the original command.

Prerequisites​

  • A Teleport Cloud cloud or a self-hosted cluster with WebAuthn configured.
Enable WebAuthn

To enable WebAuthn support, create a cap.yaml file or get the existing configuration using tctl get cluster_auth_preference:

kind: cluster_auth_preference
version: v2
metadata:
  name: cluster-auth-preference
spec:
  type: local
  second_factors: ["webauthn"]
  webauthn:
    rp_id: example.teleport.sh

Update the configuration:

tctl create -f cap.yaml
cluster auth preference has been updated

  • A machine with the tsh binary installed and a Web browser with WebAuthn support.

    Download the signed macOS .pkg installer for Teleport, which includes tsh. In Finder double-click the pkg file to begin installation:

    curl -O https://cdn.teleport.dev/teleport-19.0.0-dev.pkg
    danger

    Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

Step 1/2. Configuration​

A Teleport cluster with WebAuthn configured is automatically capable of Browser MFA without any additional configuration.

Alternative: disable Browser MFA

If you want to forbid Browser MFA in your cluster, add allow_cli_auth_via_browser: false to your configuration.

Create a cap.yaml file or get the existing configuration using tctl get cluster_auth_preference:

kind: cluster_auth_preference
version: v2
metadata:
  name: cluster-auth-preference
spec:
  type: local
  second_factors: ["webauthn"]
  webauthn:
    rp_id: example.teleport.sh
  allow_cli_auth_via_browser: false # disable Browser MFA

Update the configuration:

tctl create -f cap.yaml
cluster auth preference has been updated

Step 2/2. Authenticate via the browser​

Run a command that requires MFA, for example, logging in to a cluster using tsh.

tsh login --proxy example.teleport.sh --user alice --mfa-mode=browser
Enter password for Teleport user alice:
If browser window does not open automatically, open it by clicking on the link:
http://127.0.0.1:51697/d658314e-68f0-4ad4-be79-0181e6e0dae5

A Web browser window should automatically open, if not, click or copy+paste the URL printed by tsh. You will be prompted to complete the MFA verification process in the browser. Once successfully verified, the originating command will be authenticated and allowed to proceed.

The --mfa-mode flag is optional. If omitted, it defaults to auto, which tries each authentication mode in order until one succeeds:

  1. WebAuthn (with TOTP if available)
  2. SSO
  3. Browser MFA
  4. TOTP

Browser MFA is not attempted automatically on Windows because Windows natively supports platform WebAuthn authenticators (such as Windows Hello) in CLI applications. To use Browser MFA on Windows, pass --mfa-mode=browser explicitly.