Fork me on GitHub
Teleport

Second Factor - WebAuthn

Improve

Web Authentication

Teleport supports WebAuthn as a second authentication factor. WebAuthn can be used for logging into Teleport (tsh login or the login page on the Web UI) and for logging into 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

Verify that your Teleport client is connected:

$ tctl status

# Cluster  tele.example.com
# Version  8.0.7
# CA pin   sha256:sha-hash-here

To try this flow in the cloud, login into your cluster using tsh, then use tctl remotely:

$ tsh login --proxy=myinstance.teleport.sh
$ tctl status

If you are upgrading from a Teleport version configured to use U2F, see the Migrating from U2F section below; otherwise start at Enable WebAuthn support.

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"

Create a cap.yaml file or get the existing configuration using tctl get cluster_auth_preference:

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

The fields in the above snippets are:

  • rp_id - public domain of the Teleport proxy, excluding protocol (https://) and port number
  • attestation_allowed_cas - optional allow list of certificate authorities (as local file paths or in-line PEM certificate string) 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 - optional deny list of certificate authorities (as local file paths or in-line PEM certificate string) 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. Login 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 into Teleport is only required for local users. SSO users should configure multi-factor authentication in their SSO provider.

Migrating from U2F

Warning

Do not erase your U2F configuration from /etc/teleport.yaml or cluster_auth_preference, it is used by WebAuthn to ensure U2F-registered devices work properly.

If you have an existing Teleport cluster configured with either second_factor:optional or second_factor:on, then WebAuthn automatically replaces U2F in tsh and Web UI. The existing U2F configuration is used to derive the WebAuthn settings and ensure previously-registered devices keep working.

If your Teleport cluster is configured using second_factor:u2f, you can opt to change it to second_factor:webauthn (allowing only WebAuthn authenticators) or second_factor:on (allowing both WebAuthn and OTP).

We recommend capturing the inferred rp_id in your /etc/teleport.yaml file. You can find the inferred rp_id in the Teleport Auth Server logs:

2021-10-04T18:03:22-07:00 INFO WebAuthn: RPID inferred from U2F configuration: "example.com" types/authentication.go:504

Example configuration, including both U2F and WebAuthn settings:

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
    # valid, pre-existing U2F configuration
    u2f:
      app_id: https://example.com
      facets:
      - https://example.com:443
      - https://example.com
      - example.com:443
      - example.com
      device_attestation_cas:
      - "/path/to/u2f_attestation_ca.pem"
    # optional WebAuthn configuration
    webauthn:
      # inferred from the U2F app_id if not present.
      rp_id: "example.com"
      # copied from U2F device_attestation_cas if not present.
      attestation_allowed_cas:
      - "/path/to/u2f_attestation_ca.pem"
      attestation_denied_cas:
      - "/path/to/denied_ca.pem"

Create a cap.yaml file or get the existing configuration using tctl get cluster_auth_preference:

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
  # valid, pre-existing U2F configuration
  u2f:
    app_id: https://example.com
    facets:
    - https://example.com:443
    - https://example.com
    - example.com:443
    - example.com
    device_attestation_cas:
    - "/path/to/u2f_attestation_ca.pem"
  # optional WebAuthn configuration
  webauthn:
    # inferred from the U2F app_id if not present.
    rp_id: "example.com"
    # copied from U2F device_attestation_cas if not present.
    attestation_allowed_cas:
    - "/path/to/u2f_attestation_ca.pem"
    attestation_denied_cas:
    - "/path/to/denied_ca.pem"

Update the configuration:

tctl create -f cap.yaml

cluster auth preference has been updated

The fields in the above snippet are:

  • rp_id - public domain of the Teleport proxy, excluding protocol (https://) and port number. Inferred from U2F app_id if not present.
  • attestation_allowed_cas - optional allow list of certificate authorities (as local file paths or in-line PEM certificate string) 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. Copied from U2F device_attestation_cas if not present.
  • attestation_denied_cas - optional deny list of certificate authorities (as local file paths or in-line PEM certificate string) 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.

Next steps

Have a suggestion or can’t find something?
IMPROVE THE DOCS