Fork me on GitHub
Teleport

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

Prerequisites

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:
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.
Warning
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 https://example.com:443, your facets should include https://example.com:443, https://example.com and example.com:443.

  • 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

# 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.
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 --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
Note
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?
IMPROVE THE DOCS