mirror of
https://github.com/gravitational/teleport.git
synced 2026-10-12 02:15:01 +00:00
141 lines
4.0 KiB
Plaintext
141 lines
4.0 KiB
Plaintext
---
|
|
title: Browser MFA
|
|
description: Complete MFA checks in the browser when using tsh, tctl, or Teleport Connect
|
|
tags:
|
|
- how-to
|
|
- zero-trust
|
|
- privileged-access
|
|
---
|
|
|
|
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:
|
|
```code
|
|
# 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 or a self-hosted cluster with WebAuthn configured.
|
|
|
|
<details>
|
|
<summary>Enable WebAuthn</summary>
|
|
|
|
To enable WebAuthn support, create a `cap.yaml` file or get the existing
|
|
configuration using `tctl get cluster_auth_preference`:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```code
|
|
$ tctl create -f cap.yaml
|
|
# cluster auth preference has been updated
|
|
```
|
|
|
|
</details>
|
|
|
|
- A machine with the `tsh` binary installed and a Web browser with [WebAuthn support](
|
|
https://developers.yubico.com/WebAuthn/WebAuthn_Browser_Support/).
|
|
|
|
(!docs/pages/includes/install-tsh.mdx!)
|
|
|
|
## Step 1/2. Configuration
|
|
|
|
A Teleport cluster with WebAuthn configured is automatically capable of Browser
|
|
MFA without any additional configuration.
|
|
|
|
<details>
|
|
<summary>Alternative: disable Browser MFA</summary>
|
|
|
|
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`:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```code
|
|
$ tctl create -f cap.yaml
|
|
# cluster auth preference has been updated
|
|
```
|
|
|
|
</details>
|
|
|
|
## Step 2/2. Authenticate via the browser
|
|
|
|
Run a command that requires MFA, for example, logging in to a cluster using `tsh`.
|
|
|
|
```code
|
|
$ 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)
|
|
1. SSO
|
|
1. Browser MFA
|
|
1. 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.
|