
Introduction
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.
A user's touch is cached on the YubiKey for 15 seconds to prevent excessive touch prompts.
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 oftsh db connect
- Must use
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 andtsh
client tool version >= 12.1.1.tctl versionTeleport v12.1.1 go1.19
tsh versionTeleport 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 andtsh
client tool version >= 12.1.1, which you can download by visiting the customer portal.tctl versionTeleport Enterprise v12.1.1 go1.19
tsh versionTeleport v12.1.1 go1.19
Please use the latest version of Teleport Enterprise documentation.
- A series 5+ YubiKey
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 statusCluster 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 statusCluster 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 clustersUnmet 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
.