Teleport

Second Factor: WebAuthn

Teleport supports WebAuthn as a second authentication factor. WebAuthn can be used for logging in to Teleport (tsh login or the login page on the Web UI) and for logging in to individual SSH nodes or Kubernetes clusters (tsh ssh and kubectl).

WebAuthn support includes hardware devices, such as YubiKeys or SoloKeys (tsh and Web UI), as well as biometric authenticators like Touch ID and Windows Hello (Web UI only).

Prerequisites

A running Teleport cluster. For details on how to set this up, see one of our Getting Started guides.
The tctl admin tool and tsh client tool version >= 9.3.7.
```
tctl version
Teleport v9.3.7 go1.17
tsh version
Teleport v9.3.7 go1.17
```
See Installation for details.

A running Teleport cluster. For details on how to set this up, see our Enterprise Getting Started guide.
The tctl admin tool and tsh client tool version >= 9.3.7, which you can download by visiting the customer portal.
```
tctl version
Teleport v9.3.7 go1.17
tsh version
Teleport v9.3.7 go1.17
```

A Teleport Cloud account. If you do not have one, visit the sign up page to begin your free trial.
The tctl admin tool and tsh client tool version >= 9.3.8. To download these tools, visit the Downloads page.
```
tctl version
Teleport v9.3.8 go1.17
tsh version
Teleport v9.3.8 go1.17
```

WebAuthn hardware device, such as YubiKey or SoloKey
A Web browser with WebAuthn support

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=teleport.example.com [email protected]
tctl status
Cluster  teleport.example.com
Version  9.3.7
CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

You can run subsequent tctl commands in this guide on your local machine.

For full privileges, you can also run tctl commands on your Auth Service host.

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=myinstance.teleport.sh [email protected]
tctl status
Cluster  myinstance.teleport.sh
Version  9.3.8
CA pin   sha256:sha-hash-here

You must run subsequent tctl commands in this guide on your local machine.

Step 1/3. Enable WebAuthn support

WebAuthn is disabled by default. To enable WebAuthn support, update your Teleport configuration as below:

Auth Server teleport.yaml file:

# snippet from /etc/teleport.yaml:
auth_service:
  authentication:
    type: local
    # To enable WebAuthn support, set this field to 'on', 'optional' or 'webauthn'
    second_factor: on
    webauthn:
      rp_id: example.com
      attestation_allowed_cas:
      - "/path/to/allowed_ca.pem"
      attestation_denied_cas:
      - "/path/to/denied_ca.pem"

Obtain your existing cluster_auth_preference resource:

tctl get cap > cap.yaml

If you have not defined a cluster_auth_preference, cap.yaml will be blank.

Ensure that cap.yaml includes the following content:

kind: cluster_auth_preference
version: v2
metadata:
  name: cluster-auth-preference
spec:
  type: local
  # To enable WebAuthn support, set this field to 'on', 'optional' or 'webauthn'
  second_factor: on
  webauthn:
    rp_id: example.com
    attestation_allowed_cas:
    - "/path/to/allowed_ca.pem"
    attestation_denied_cas:
    - "/path/to/denied_ca.pem"

Update the configuration:

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

You will need to include the following configuration fields.

rp_id is the public domain of the Teleport Proxy Service, excluding protocol (https://) and port number.

attestation_allowed_cas is an optional allow list of certificate authorities (as local file paths or inline PEM certificate strings) for device verification.

This field allows you to restrict which device models and vendors you trust. Devices outside of the list will be rejected during registration. By default all devices are allowed. If you must use attestation, consider using attestation_denied_cas to forbid troublesome devices instead.

attestation_denied_cas is an optional deny list of certificate authorities (as local file paths or inline PEM certificate strings) for device verification.

This field allows you to forbid specific device models and vendors, while allowing all others (provided they clear attestation_allowed_cas as well). Devices within this list will be rejected during registration. By default no devices are forbidden.

Step 2/3. Register WebAuthn devices as a user

A user can register multiple WebAuthn devices using tsh:

tsh mfa add
Choose device type [TOTP, WEBAUTHN]: webauthn
Enter device name: desktop yubikey
Tap any *registered* security key or enter a code from a *registered* OTP device:
Tap your *new* security key
MFA device "desktop yubikey" added.

Windows support

WebAuthn devices are currently not supported in tsh on Windows.

Step 3/3. Log in using WebAuthn

Once a WebAuthn device is registered, the user will be prompted for it on login:

tsh login --proxy=example.com
Enter password for Teleport user codingllama:
Tap any security key or enter a code from a OTP device:
> Profile URL:        https://example.com
Logged in as:       codingllama
Cluster:            example.com
Roles:              access, editor
Logins:             codingllama
Kubernetes:         enabled
Valid until:        2021-10-04 23:32:29 -0700 PDT [valid for 12h0m0s]
Extensions:         permit-agent-forwarding, permit-port-forwarding, permit-pty

Note

WebAuthn for logging in to Teleport is only required for local users. SSO users should configure multi-factor authentication in their SSO provider.

Next steps

Setup per-session MFA checks

Have a suggestion or can’t find something?

IMPROVE THE DOCS