Enforce Device Trust
Device trust fully supports SSH, Database and Kubernetes resources using cluster-wide or role-based enforcement.
Apps and Desktops may enforce trusted devices using role-based enforcement. See the App Access support and the Desktop Access support sections for further details.
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
-
A running Teleport cluster. If you want to get started with Teleport, sign up for a free trial.
-
The
tctladmin tool andtshclient tool.Visit Installation for instructions on downloading
tctlandtsh.
- To enroll a macOS device, you need:
- A signed and notarized
tshbinary. Download the macOS tsh installer.
- A signed and notarized
- To enroll a Windows device, you need:
- A device with TPM 2.0.
- A user with administrator privileges. This is only required during enrollment.
tshv13.1.2 or newer. Download the Windows tsh installer.
- 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
tssgroup to the user). tshv15.0.0 or newer. Install tsh for Linux.
- To authenticate a Web UI session you need Teleport Connect
- We expect your Teleport cluster to be on version 13.3.6 and above, which has
the preset
require-trusted-devicerole. The presetrequire-trusted-devicerole does not enforce the use of a trusted device for Apps or Desktops. Refer to their corresponding sections for instructions.
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.
To enforce authenticated device checks for a specific role when a user accesses
databases, Kubernetes clusters, and servers with Teleport, update the role with
the device_trust_mode field assigned to "required". The following example
updates the preset require-trusted-device role:
kind: role
version: v7
metadata:
name: require-trusted-device
spec:
options:
device_trust_mode: "required"
allow:
db_labels:
'*': '*'
db_names:
- '*'
db_users:
- '*'
kubernetes_groups:
- '{{internal.kubernetes_groups}}'
- system:masters
- developers
- viewers
kubernetes_labels:
'*': '*'
logins:
- '{{internal.logins}}'
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.
To enable device mode required update your configuration as follows:
Edit your cluster authentication preference using the following command:
$ tctl edit cluster_auth_preference
Make the following change:
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
Save and close your editor to apply your changes.
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)
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
The Teleport App Service may enforce Device Trust via role-based enforcement.
To access apps protected by Device Trust using the Web UI (Teleport v16 or later), make sure your device is registered and enrolled, install Teleport Connect, and follow the instructions during login.
Alternatively, you may use tsh proxy app or the certificates issued by
tsh app login.
As an 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.
Desktop Access support
The Teleport Desktop Service may enforce Device Trust via role-based enforcement.
To access desktops protected by Device Trust make sure your device is registered and enrolled, install Teleport Connect, and follow the instructions during login.
As an example, to enforce Device Trust for all env:production desktops, save
the role below as require-trusted-device-desktops.yaml:
kind: role
version: v7
metadata:
name: require-trusted-device-desktops
spec:
options:
device_trust_mode: "required"
allow:
windows_desktop_labels:
env: "production"
windows_desktop_logins: ["Administrator", "alice"]
Create the role and assign it to a user:
$ tctl create require-trusted-device-desktops.yaml
$ tctl edit users/alice
kind: user
metadata:
name: alice
# (...)
spec:
roles:
- access
- editor
+ - require-trusted-device-desktops
# (...)
version: v2
Now the alice user can only access env:production desktops using a trusted
device.
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:
- Verifying device profile data, such as data originated from Jamf, against the actual device
- 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.
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"
Follow the instructions in the Web UI troubleshooting section below (Teleport v16 or later).
Alternatively, you may 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.
Desktop access and "access to this app requires a trusted device"
Follow the instructions in the Web UI troubleshooting section below.
Web UI fails to authenticate trusted device
The Web UI attempts to authenticate your device using Teleport Connect during login. If you are not asked to authenticate your device immediately after login, follow the steps below:
- Make sure your device is registered and enrolled
- Install Teleport Connect. Use the DEB or RPM packages on Linux (the tarball doesn't register the custom URL handler).
- Make sure Teleport Connect can access the same resource you are trying to access on the Web
- Ask your cluster administrator if device trust is enabled (cluster mode "optional" or higher)
If all of the above steps are done, try logging out from the Web UI and logging in again.
Checking Device Trust authorization status in the web UI
When successfully authorized to use Device Trust in the web UI, the user will see a green shield icon next to the logged-in username at the top right of the screen. Additionally, clicking on the username to show the user menu will indicate that the session is authorized with Device Trust.
If the user is not authorized to use Device Trust in the web UI, but either the cluster-wide configuration or their assigned role(s) require the use of a trusted device, the user will see a yellow warning shield next to the logged-in username at the top right of the screen. Additionally, clicking on the username to show the user menu will indicate that the session is not authorized with Device Trust, so the user's access is restricted.
| Theme | Session authorized with Device Trust | Session not authorized with Device Trust |
|---|---|---|
| Light |  |  |
| Dark |  |  |