Second Factor - U2F
Teleport supports FIDO U2F
hardware keys as a second authentication factor. U2F 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
- Installed Teleport or Teleport Pro >= 6.2.7
- U2F hardware device, such as Yubikey or Solokey
- Web browser that supports U2F
By default U2F is disabled. To enable U2F support, edit the Teleport
/etc/teleport.yaml like so:
# snippet from /etc/teleport.yaml to show an example configuration of U2F: auth_service: authentication: type: local # to enable U2F support, set this field to 'u2f', 'on' or 'optional' second_factor: u2f u2f: app_id: https://example.com:443 facets: - https://example.com:443 - https://example.com - example.com:443 - example.com device_attestation_cas: - "/path/to/u2f_attestation_ca.pem"
The fields in the above snippet are:
app_id- public address of the Teleport proxy, including the
https://prefix and port number.
app_idmust never change in the lifetime of the cluster, because it's recorded in the registration data on the U2F device. If the App ID changes, all existing U2F key registrations will become invalid and all users who use U2F as the second factor will need to re-register. When using multiple proxy servers, make sure they are reachable at the same public address (usually behind a load balancer).
facets- list of allowed addresses of the Teleport proxy, checked during authentication attempts. This list is used to prevent malicious websites and proxies from requesting U2F challenges on behalf of the legitimate proxy.
For compatibility with multiple browsers, it's recommended to write down the proxy address in several formats. For example, if your
device_attestation_cas- optional list of certificate authorities (as local file paths or in-line PEM certificate string) for U2F device attestation verification. This field allows you to restrict which U2F device vendors you trust. Devices from other vendors will be rejected during registration. By default, any vendor is allowed.
Once the configuration file was edited, restart
teleport to pick up the
A user can register multiple U2F devices using
tsh mfa add # Output Choose device type [TOTP, U2F]: u2f Enter device name: desktop yubikey Tap any *registered* security key Tap your *new* security key MFA device "desktop yubikey" added.
Once a U2F device is registered, the user will be prompted for it on login:
tsh login --proxy=example.com # Output Enter password for Teleport user awly: Tap any security key <tap U2F token> > Profile URL: https://example.com Logged in as: awly Cluster: example.com Roles: admin* Logins: awly Kubernetes: enabled Valid until: 2021-04-01 23:32:29 -0700 PDT [valid for 12h0m0s] Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty