Skip to main content
How to enable WebAuthn based second-factor authentication in Teleport.
How to enable WebAuthn based second-factor authentication in Teleport.

Length: 06:42

Version: 15.x

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 as well as biometric authenticators like Touch ID and Windows Hello (tsh and Web UI).

Prerequisites​

  • A running Teleport cluster version 15.4.22 or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

  • The tctl admin tool and tsh client tool.

    On Teleport Enterprise, you must use the Enterprise version of tctl, which you can download from your Teleport account workspace. Otherwise, visit Installation for instructions on downloading tctl and tsh for Teleport Community Edition.

  • WebAuthn hardware device, such as YubiKey or SoloKey
  • A Web browser with WebAuthn support
  • To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. tctl is supported on macOS and Linux machines. For example: 
    $ tsh login --proxy=teleport.example.com [email protected]
    $ tctl status
    # Cluster  teleport.example.com
    # Version  15.4.22
    # CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
    If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

Step 1/3. Enable WebAuthn support​

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

Edit the cluster_auth_preference resource:

$ tctl edit cap

Update the cluster_auth_preference definition to include 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:
    # Required, replace with proxy web address (example.com, mytenant.teleport.sh).
    # rp_id is the public domain of the Teleport Proxy Service, *excluding* protocol
    # (https://) and port number.
    rp_id: example.com
    # Optional, attestation_allowed_cas is an optional allow list
    # of certificate authorities.
    attestation_allowed_cas:
    # Entries can be paths to certificate files:
    - "/path/to/allowed_ca.pem"
    # Entries can also be inline certificates:
    - |
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----
    # Optional, attestation_denied_cas is an optional deny list
    # of certificate authorities.
    attestation_denied_cas:
    # Entries can be paths to certificate files:
    - "/path/to/denied_ca.pem"
    # Entries can also be inline certificates:
    - |
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----

Save and exit the file. tctl will update the remote definition:

cluster auth preference has been updated

webauthn fields definitions​

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

tsh mfa picks the strongest known second factor you have for the "Tap any registered security key" step. This may be undesirable at times, so you may fallback to a weaker second factor, like OTP, using tsh mfa add --mfa-mode=otp.

See the possible --mfa-mode values in the Teleport CLI Reference page.

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​

WebAuthn has replaced U2F in Teleport from previous versions. 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"

You can replace this configuration with its WebAuthn equivalent using a cluster_auth_preference similar to the following:

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"

On a self-hosted cluster, you can configure WebAuthn with a Teleport Auth Service configuration similar to the following:

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

Next steps​