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 Cloud >= 7.3.2
- 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 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. If you use a port number other than 443, include it as well.
https://example.com(uses default port 443)
https://example.com:3080(uses non-default port 3080)
app_id must 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
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.
U2F devices are currently not supported in
tsh on Windows.
Once a U2F device is registered, the user will be prompted for it on login:
tsh login --proxy=example.com
Enter password for Teleport user awly:
Tap any security key <tap U2F token>
> Profile URL: https://example.com
Logged in as: awly
Valid until: 2021-04-01 23:32:29 -0700 PDT [valid for 12h0m0s]
Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty
U2F for logging into Teleport is only required for local users. SSO users should configure multi-factor authentication in their SSO provider.