Fork me on GitHub

Second Factor - U2F


U2F ( Hardware Tokens)

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 kubectl).


Enable U2F support

By default U2F is disabled. To enable U2F support, edit the Teleport configuration file /etc/teleport.yaml like so:

# snippet from /etc/teleport.yaml to show an example configuration of U2F:
    type: local
    # to enable U2F support, set this field to 'u2f', 'on' or 'optional'
    second_factor: u2f
       - "/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.


    • (uses default port 443)
    • (uses non-default port 3080)

The 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 app_id is, your facets should include,, and

  • 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 changes.

Register U2F devices as a user

A user can register multiple U2F devices using tsh:

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.

Windows support

U2F devices are currently not supported in tsh on Windows.

Login using U2F

Once a U2F device is registered, the user will be prompted for it on login:

tsh login

Enter password for Teleport user awly:

Tap any security key <tap U2F token>

> Profile URL:

Logged in as: awly


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


U2F for logging into Teleport is only required for local users. SSO users should configure multi-factor authentication in their SSO provider.

Next steps

Have a suggestion or can’t find something?