Fork me on GitHub
Teleport

Second Factor - U2F

Improve

U2F (Hardware Tokens)

Tip

Consider updating your cluster to use WebAuthn as the second factor protocol. WebAuthn is a modern U2F replacement that allows for a wider range of devices to be used as second factor authenticators.

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

  • A running Teleport cluster. For details on how to set this up, see one of our Getting Started guides.

  • The tctl admin tool and tsh client tool version >= 9.2.4.

    tctl version

    Teleport v9.2.4 go1.17

    tsh version

    Teleport v9.2.4 go1.17

    See Installation for details.

  • A running Teleport cluster. For details on how to set this up, see our Enterprise Getting Started guide.

  • The tctl admin tool and tsh client tool version >= 9.2.4, which you can download by visiting the customer portal.

    tctl version

    Teleport v9.2.4 go1.17

    tsh version

    Teleport v9.2.4 go1.17

  • A Teleport Cloud account. If you do not have one, visit the sign up page to begin your free trial.

  • The tctl admin tool and tsh client tool version >= 9.2.4. To download these tools, visit the Downloads page.

    tctl version

    Teleport v9.2.4 go1.17

    tsh version

    Teleport v9.2.4 go1.17

  • U2F hardware device, such as Yubikey or Solokey
  • Web browser that supports U2F

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=teleport.example.com [email protected]
tctl status

Cluster teleport.example.com

Version 9.2.4

CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

You can run subsequent tctl commands in this guide on your local machine.

For full privileges, you can also run tctl commands on your Auth Service host.

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=myinstance.teleport.sh [email protected]
tctl status

Cluster myinstance.teleport.sh

Version 9.2.4

CA pin sha256:sha-hash-here

You must run subsequent tctl commands in this guide on your local machine.

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
       facets:
       - "https://example.com"      # app_id should always also be listed as a facet
       - "https://example.com:443"
       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.

    Examples:

    • https://example.com (uses default port 443)
    • https://example.com:3080 (uses non-default port 3080)
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, your facets should include https://example.com (same as the app_id) and https://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

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

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