Fork me on GitHub

Teleport

Second Factor: WebAuthn

Improve

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 >= 10.2.6.

    tctl version

    Teleport v10.2.6 go1.18

    tsh version

    Teleport v10.2.6 go1.18

    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 >= 10.2.6, which you can download by visiting the customer portal.

    tctl version

    Teleport v10.2.6 go1.18

    tsh version

    Teleport v10.2.6 go1.18

  • 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 >= 10.1.9. To download these tools, visit the Downloads page.

    tctl version

    Teleport v10.1.9 go1.18

    tsh version

    Teleport v10.1.9 go1.18

  • 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 10.2.6

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 10.1.9

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

Starting on Teleport v10, WebAuthn replaces U2F. See the U2F section.

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.

U2F

Starting with Teleport v10, WebAuthn replaces U2F. If you haven't configured U2F before, no further action is necessary—any U2F devices are automatically supported.

If you have an existing U2F configuration, but haven't explicitly configured WebAuthn yet, Teleport will automatically derive your WebAuthn configuration from your existing U2F configuration.

You may write the WebAuthn configuration yourself, but keep the U2F app_id field. Doing so ensures that any already-registered U2F devices won't need to be re-registered.

For example, consider the U2F configuration below:

# snippet from /etc/teleport.yaml showing a U2F configuration:
auth_service:
  authentication:
    type: local
    second_factor: u2f
    u2f:
      app_id: https://example.com
      facets:
      - "https://example.com"
      - "https://example.com:443"
      device_attestation_cas:
      - "/path/to/u2f_attestation_ca.pem"

The migrated WebAuthn configuration is:

# snippet from /etc/teleport.yaml:
auth_service:
  authentication:
    type: local
    second_factor: on # changed from "u2f"
    u2f:
      # Keep the app_id to avoid re-registering U2F devices.
      app_id: https://example.com
    webauthn:
      # rp_id is the public domain of the Teleport Proxy Service.
      # It's similar to the U2F app_id, but without "https://" or port number.
      rp_id: example.com
      attestation_allowed_cas:
      - "/path/to/u2f_attestation_ca.pem"
kind: cluster_auth_preference
version: v2
metadata:
  name: cluster-auth-preference
spec:
  type: local
  second_factor: "on" # changed from "u2f"
  u2f:
    # Keep the app_id to avoid re-registering U2F devices.
    app_id: https://example.com
  webauthn:
    # rp_id is the public domain of the Teleport Proxy Service.
    # It's similar to the U2F app_id, but without "https://" or port number.
    rp_id: example.com
    attestation_allowed_cas:
    - "/path/to/u2f_attestation_ca.pem"

Next steps