Skip to main content
Introducing Device Trust
Introducing Device Trust

Length: 01:35

Version: 15.x

Enforce Device Trust

Supported Resources

Device trust fully supports SSH, Database and Kubernetes resources.

Apps may enforce trusted devices using role-based enforcement. See the App Access support section.

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.

Prerequisites​

  • To enroll a macOS device, you need:
  • To enroll a Windows device, you need:
  • To enroll a Linux device, you need:
    • A device with TPM 2.0.
    • A user with permissions to use the /dev/tpmrm0 device (typically done by assigning the tss group to the user).
    • tsh v15.0.0 or newer. Install tsh for Linux.

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.

v13.3.6+

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
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:
      '*': '*'
    ...

Update the role:

$ 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. Only tsh and Teleport Connect are able to fulfill device mode required.

To enable device mode required update your configuration as follows:

Create a 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.yaml
cluster auth preference has been updated

You can also edit this configuration directly:

$ tctl edit cluster_auth_preference

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.

App Access support​

Apps may enforce device trust via role-based enforcement. Any apps that enforce device trust must be accessed using tsh commands such as tsh proxy app or using the certificates issued by tsh app login. Direct access to those apps via the Web UI is not yet available.

For example, to enforce device trust for all env:production apps, save the role below as require-trusted-device-apps.yaml:

kind: role
version: v7
metadata:
  name: require-trusted-device-apps
spec:
  options:
    device_trust_mode: "required"
  allow:
    app_labels:
      env: production

Create the role and assign it to a user:

$ tctl create require-trusted-device-apps.yaml
$ tctl edit users/alice
kind: user
metadata:
  name: alice
  # (...)
spec:
  roles:
  - access
  - editor
+ - require-trusted-device-apps
  # (...)
version: v2

Now the alice user can only access env:production apps using a trusted device. For example, to access an app called myapp, alice runs tsh proxy app myapp -p 8888 and opens http://localhost:8888 in her browser.

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)

Troubleshooting​

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

"Failed to open the TPM device" on Linux​

Linux users need permissions to read and write from the TPM device, /dev/tpmrm0. Without such permissions tsh would need sudo prompts for most operations.

The simplest way to solve this is to check if your distro ships with the tss group and assign it to your OS user. If that is not possible, or you are looking for a different solution, we recommend creating udev rules similar to the ones shipped by the TPM2 Software Stack.

Auto enrollment not working​

Auto-enrollment ceremonies, due to their automated nature, are stricter than regular enrollment. Additional auto-enrollment checks include:

  1. Verifying device profile data, such as data originated from Jamf, against the actual device
  2. Verifying that the device is not enrolled by another user (auto-enroll cannot take devices that are already enrolled)

Check you audit log for clues: look for failed "Device Enroll Token Created" events and see the "message" field in the details (auto-enroll audit log details available since Teleport v15.4.21).

If you suspect (1) is the issue, compare the actual device against its inventory definition (tsh device collect executed in the actual device vs tctl get device/<asset_tag>). Tweaking the device profile, manual enrollment or waiting for the next MDM sync may solve the issue.

If you suspect (2), you can unenroll the device using tctl edit device/<asset_tag> and changing the "enroll_status" field to "not_enrolled".

App access and "access to this app requires a trusted device"​

A Teleport admin configured the particular app you are trying to access to require a trusted device.

There are a few situations that might cause the error:

  1. You are trying to access the app using the Web UI.

  2. You are trying to access the app using an untrusted device.

The Web UI is currently not capable of device authentication. To access apps protected by device trust you need to use one of the tsh commands described by App Access support. For example, for an app called myapp, run tsh proxy app myapp -p 8888, then open http://localhost:8888 in your browser.

If you are already running tsh proxy app, or using the certificates acquired from tsh app login, then it's likely your device isn't registered or enrolled. In this case, follow the advice from the unauthorized device section above.

Next steps​