Teleport

Hardware Key Support (Preview)

Enterprise
Cloud

Introduction

Preview

Hardware key Support is currently in Preview mode.

By default, tsh, Teleport Connect, and other Teleport clients store a user's login session directly on their filesystem. If a user's filesystem is compromised, any of their active Teleport login sessions would also be compromised.

Per-session MFA provides a way to require an MFA presence check with a user's login session, but this check is only used for starting sessions with Teleport services (SSH, Kube, DB, etc.). This means that non-session actions, like administrative commands run with tctl, can still be run with an exfiltrated login session.

To prevent these types of exfiltration attacks altogether, Teleport clients support hardware-based private keys. Unlike disk-based private keys, hardware-based private keys are generated and stored directly on a hardware device and are impossible to export. With this feature, a user's login session is only functional with access to the user's hardware device.

Additionally, this feature can be configured to require touch for every Teleport request, including non-session requests. With touch required, hardware key support provides better security in comparison to our per-session MFA offering.

touch caching

A user's touch is cached on the YubiKey for 15 seconds to prevent excessive touch prompts.

Compatibility Issues

Hardware key support provides the best security available, but it is a new feature with some compatibility trade-offs. We hope to improve compatibility in the future.

Supported (tsh, tctl, and Teleport Connect):

Standard Teleport API requests (tsh ls, tctl create, etc.)
Server Access
Database Access
- Must use tsh proxy db instead of tsh db connect

Not yet supported:

Teleport WebUI (except for user registration / reset password)
Agent forwarding functionality such as tsh ssh -A, Proxy Recording mode, and OpenSSH integration
Kubernetes Access
Desktop Access
Application Access

The unsupported features above will not function for users that have have hardware key support enforced. This is either because the user's hardware key can't be accessed within that feature (WebUI) or because the protocol only supports raw private keys currently (Agent forwarding, Kubernetes Access, Desktop Access).

To navigate these incompatibilities, we recommend enabling hardware key support only when necessary, such as for roles with access to critical infrastructure. These roles can be accessed as needed with Access Requests so that users can avoid these issues for their normal login sessions. We also recommend trying Teleport Connect as an alternative to the WebUI.

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 >= 12.1.1.
```
tctl version
Teleport v12.1.1 go1.19
tsh version
Teleport v12.1.1 go1.19
```
See Installation for details.

A running Teleport cluster. For details on how to set this up, see our Enterprise Getting Started guide.
The Enterprise tctl admin tool and tsh client tool version >= 12.1.1, which you can download by visiting the customer portal.
```
tctl version
Teleport Enterprise v12.1.1 go1.19
tsh version
Teleport v12.1.1 go1.19
```

Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.

A series 5+ YubiKey

PIV support

Hardware key support requires users to use a PIV-compatible hardware key. Currently, this feature is only guaranteed to support YubiKey series 5+.

Teleport clients use PIV slot 9a for the hardware_key option and 9c for the hardware_key_touch option, and will overwrite other keys and certs in these slots as needed. This may interfere with other PIV applications, like yubikey-agent, so we recommend only using one PIV application at a time.

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  12.1.1
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  12.1.1
CA pin   sha256:sha-hash-here

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

Step 1/2. Enforce Hardware Key Support

Hardware key support is not required by default. You can enforce hardware key support for specific roles, as shown here:

kind: role
metadata:
  name: admin
spec:
  options:
    require_session_mfa: hardware_key_touch

You can also enforce hardware key support cluster-wide by updating your Teleport configuration as below:

Step 2/2. Log In

Once hardware key support is enforced, affected users will be required to have their login sessions backed by a Hardware Key for all Teleport requests.

These users will be prompted to connect and touch their YubiKey on log in:

Affected users with existing sessions not backed by a hardware key will be prompted to re-login on their next request:

tsh clusters
Unmet private key policy "hardware_key_touch"
Relogging in with YubiKey generated private key.
Enter password for Teleport user dev:
Tap your YubiKey
Cluster Name Status Cluster Type Labels Selected
----------- ------ ------------ ------ --------
example.com online root                *

Configuring Hardware Key Support with Per-session MFA

For existing users of per-session MFA, upgrading to hardware_key_touch may be disruptive, as it requires touch on all requests as opposed to only session requests. While this upgrade would yield the best security, we can get a very similar level of security by combining hardware key support with per-session MFA.

For users who want this mash-up of functionality, you can use the require_session_mfa: hardware_key option in both roles and cluster auth preference settings. This option will continue to use per-session MFA checks while also requiring hardware-based private keys for all Teleport requests.

This prevents basic data exfiltration attacks for Teleport sesssion and non-session requests. However, it does not prevent hacking attacks with non-session Teleport requests, since gaining access to a user's computer would provide both their certificates on disk and a local connection to their YubiKey, assuming its connected.

Troubleshooting

`ERROR: private key policy not met`

This error is returned by the Auth and Proxy servers when a user does not meet their required private key policy. Both tsh and Teleport Connect will automatically catch these errors and initiate re-login with a valid hardware-based private key. If you are getting this error, make sure that your client is up to date (v11.0.0+).

This error may also appear in the WebUI, since the WebUI does not support hardware-based private keys.

`ERROR: authenticating with management key: auth challenge: smart card error 6982: security status not satisfied`

Smart card auth challenge errors can appear when the wrong Management key or PIN is used. Teleport clients expect a fresh PIV module with the default Management and PIN keys. You can reset these keys, along with any existing PIV keys and certs, with the yubikey manager tool command ykman piv reset.

Have a suggestion or can’t find something?

IMPROVE THE DOCS