Enforce Device Trust
- Version 15.x
- Version 14.x
- Version 13.x
- Version 12.x
- Older Versions
- Available for:
Introducing Device Trust
The device trust preview only supports SSH, Database and Kubernetes resources. Support for other resources is planned for upcoming Teleport versions.
Resources protected by the device mode "required" will enforce the use of a trusted device, in addition to establishing the user's identity and enforcing the necessary roles. Furthermore, users using a trusted device leave audit trails that include the device's information.
Device Trust enforcement can be configured with the following three modes of operation, represented
device_trust_mode authentication setting:
off- disables device trust. Device authentication is not performed and device-aware audit logs are absent.
optional- enables device authentication and device-aware audit, but does not require a trusted device to access resources.
required- enables device authentication and device-aware audit. Additionally, it requires a trusted device for all SSH, Database and Kubernetes connections.
A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.
tctladmin tool and
tshclient tool version >= 14.0.1. You can download these tools by visiting your Teleport account. You can verify the tools you have installed by running the following commands:tctl version
Teleport Enterprise v14.0.1 go1.21tsh version
Teleport v14.0.1 go1.21
- To enroll a macOS device, you need:
- A signed and notarized
tshbinary for enrollment. Download the macOS tsh installer.
- A Teleport version newer than v12.0.0.
- A signed and notarized
- To enroll a Windows device, you need:
- A device that includes a TPM with 2.0 support.
tshinstalled on the device. Download the Windows tsh installer.
- Credentials for a user with administrator privileges for the device. This is only required during enrollment.
- A Teleport version newer than v13.1.2.
Role-based configuration enforces trusted device access at the role level. It
can be configured with the
spec.options.device_trust_mode option and
applies to the resources in its
allow rules. It
works similarly to
Teleport version 13.3.6 and above has the preset
Make sure you update the "allow" rules in the role according to your requirements.
To enforce authenticated device checks for a specific role, update the role with the following:
kind: role version: v7 metadata: name: require-trusted-device spec: options: # require authenticated device check for this role + device_trust_mode: "required" # add this line allow: logins: ['admin'] kubernetes_groups: ['edit'] node_labels: '*': '*' ...
tctl create -f device-enforcement.yaml
Cluster-wide configuration enforces trusted device access at the cluster level.
Enterprise clusters run in
optional mode by default. Changing the mode to
required will enforce a trusted device for all SSH, Database and Kubernetes
The Web UI is not capable of trusted device access during the device trust
tsh and Teleport Connect are able to fulfill device mode
To enable device mode
required update your configuration as follows:
Choose one of the options
- Teleport Enterprise Cloud
cap.yaml file or get the existing configuration using
tctl get cluster_auth_preference:
kind: cluster_auth_preference version: v2 metadata: name: cluster-auth-preference spec: type: local second_factor: "on" webauthn: rp_id: teleport.example.com device_trust: + mode: "required" # add this line
Update the configuration:
tctl create -f cap.yamlcluster auth preference has been updated
You can also edit this configuration directly:
tctl edit cluster_auth_preference
Edit the Auth Server's
teleport.yaml file and restart all Auth Services:
auth_service: authentication: type: local second_factor: "on" webauthn: rp_id: teleport.example.com device_trust: + mode: "required" # add this line
Once the config is updated, SSH, Database and Kubernetes access without a trusted device will be forbidden. For example, SSH access without a trusted device fails with the following error:
tsh ssh ip-172-31-35-170ERROR: ssh: rejected: administratively prohibited (unauthorized device)
It is possible to use trusted
clusters to limit the impact of
required. A leaf cluster in mode
required will enforce access to
all of its resources, without imposing the same restrictions to the root
cluster. Likewise, a root cluster will not enforce device trust on resources in
Similar to session and identity locking, a device can
be locked using
Locking blocks certificate issuance and ongoing or future accesses originating from a locked device. Locking a device only works if device trust is enabled and if the device is enrolled to Teleport.
Find a device ID to lock:
tctl devices lsAsset Tag OS Enroll Status Device ID------------ ----- ------------- ------------------------------------C00AA0AAAA0A macOS enrolled 9cdfc0ad-64b7-4d9c-this-is-an-example
Lock a device:
tctl lock --device=9cdfc0ad-64b7-4d9c-this-is-an-example --ttl=12hCreated a lock with name "5444970a-39a0-4814-968d-e58b4a8fa686".
Now, if a user on that device tries to access an SSH server for example, Teleport will deny access:
tsh ssh ip-172-31-35-170ERROR: ssh: rejected: administratively prohibited (lock targeting Device:"9cdfc0ad-64b7-4d9c-this-is-an-example" is in force)
A signed and notarized
tsh binary is necessary to enroll and use a a trusted
device. Download the macOS tsh installer to fix
A trusted device needs to be registered and enrolled before it is recognized by
Teleport as such. Follow the registration and
and make sure to
tsh logout and
tsh login after enrollment is done.