# Browser MFA

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](https://developers.yubico.com/WebAuthn/WebAuthn_Browser_Support/).

  **Mac**

  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.

  ---

  **Windows - Powershell**

  ```
  $ curl.exe -O https://cdn.teleport.dev/teleport-v19.0.0-dev-windows-amd64-bin.zip
  Unzip the archive and move tsh.exe to your %PATH%
  NOTE: Do not place tsh.exe in the System32 directory, as this can cause issues when using WinSCP.
  Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
  ```

  **Linux**

  All of the Teleport binaries in Linux installations include `tsh`. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/ver/19.x/installation/single-machine.md).

  ```
  $ curl -O https://cdn.teleport.dev/teleport-v19.0.0-dev-linux-amd64-bin.tar.gz
  $ tar -xzf teleport-v19.0.0-dev-linux-amd64-bin.tar.gz
  $ cd teleport
  $ sudo ./install
  Teleport binaries have been copied to /usr/local/bin
  ```

## 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.