Fork me on GitHub


Enforce Device Trust

  • Available for:
  • Enterprise
  • Cloud
  • Team
Introducing Device Trust

Introducing Device Trust

Length: 01:35

Preview Note: Supported Resources

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 by the 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.

  • The Enterprise tctl admin tool and tsh client 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.21

    tsh version

    Teleport v14.0.1 go1.21

Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.
  • To enroll a macOS device, you need:
  • To enroll a Windows device, you need:
    • A device that includes a TPM with 2.0 support.
    • tsh installed 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 trusted device enforcement

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


Teleport version 13.3.6 and above has the preset require-trusted-device role. 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
  name: require-trusted-device
    # require authenticated device check for this role
+   device_trust_mode: "required" # add this line
    logins: ['admin']
    kubernetes_groups: ['edit']
      '*': '*'

tctl create -f device-enforcement.yaml

Cluster-wide trusted device enforcement

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

Web UI

The Web UI is not capable of trusted device access during the device trust preview. Only tsh and Teleport Connect are able to fulfill device mode required.

To enable device mode required update your configuration as follows:

Choose one of the options

Create a cap.yaml file or get the existing configuration using tctl get cluster_auth_preference:

kind: cluster_auth_preference
version: v2
  name: cluster-auth-preference
  type: local
  second_factor: "on"
+   mode: "required" # add this line

Update the configuration:

tctl create -f cap.yaml
cluster 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:

    type: local
    second_factor: "on"
+     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-170
ERROR: ssh: rejected: administratively prohibited (unauthorized device)
Trusted Clusters

It is possible to use trusted clusters to limit the impact of device mode 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 leaf clusters.

Locking a device

Similar to session and identity locking, a device can be locked using tctl lock.

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 ls
Asset 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=12h
Created 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-170
ERROR: ssh: rejected: administratively prohibited (lock targeting Device:"9cdfc0ad-64b7-4d9c-this-is-an-example" is in force)


"binary missing signature or entitlements" on tsh device enroll

A signed and notarized tsh binary is necessary to enroll and use a a trusted device. Download the macOS tsh installer to fix the problem.

"unauthorized device" errors using a trusted device

A trusted device needs to be registered and enrolled before it is recognized by Teleport as such. Follow the registration and enrollment steps and make sure to tsh logout and tsh login after enrollment is done.

Next steps