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. 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 version >= 15.2.2.

  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 --user=[email protected]
  tctl status
  Cluster  teleport.example.com
  Version  15.2.2
  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:

tctl edit cap

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

cluster auth preference has been updated

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

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.

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

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, reviewer
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

tsh login --proxy=mytenant.teleport.sh
Enter password for Teleport user codingllama:
Tap any security key or enter a code from a OTP device:
> Profile URL:        https://mytenant.teleport.sh
Logged in as:       codingllama
Cluster:            mytenant.teleport.sh
Roles:              access, editor, reviewer
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

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"

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"

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

• Passwordless
• Set up per-session MFA checks
• Require MFA for administrative actions