Manage Trusted Devices

This guide provides instructions for performing Device Trust management operations, such as registering a trusted device, creating a device enrollment token, and removing a trusted device.

Prerequisites

• A running Teleport cluster. If you want to get started with Teleport, sign up for a free trial.

• The tctl admin tool and tsh client tool.

  Visit Installation for instructions on downloading tctl and tsh.

• To enroll a macOS device, you need:
  • A signed and notarized tsh binary. Download the macOS tsh installer.
• To enroll a Windows device, you need:
  • A device with TPM 2.0.
  • A user with administrator privileges. This is only required during enrollment.
  • tsh v13.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 tss group to the user).
  • tsh v15.0.0 or newer. Install tsh for Linux.
• To authenticate a Web UI session you need Teleport Connect
• Correct end-user IP propagation to your Teleport deployment: X-Forwarded-For header (L7 load balancer) or PROXY protocol (L4 load balancer)

• For clusters created after v13.3.6, Teleport supports the preset device-admin role to manage devices.

Register a trusted device

The tctl tool is used to manage the device inventory. A device admin is responsible for managing devices, adding new devices to the inventory and removing devices that are no longer in use.

tsh device enroll --current-device

Before you can enroll the device, you need to register it. To register a device, you first need to determine its serial number.

Retrieve device serial number with tsh (must be run on the device you want to register):

tsh device asset-tag
C00AA0AAAA0A

tsh device asset-tag
C00AA0AAAA0A

Replace C00AA0AAAA0A with the serial number of the device you wish to enroll and run the tctl devices add command:

tctl devices add --os='macos' --asset-tag='C00AA0AAAA0A'
Device C00AA0AAAA0A/macos added to the inventory

Use tctl to check that the device has been registered:

tctl devices ls
Asset Tag    OS    Enroll Status Device ID------------ ----- ------------- ------------------------------------C00AA0AAAA0A macOS not enrolled  9cdfc0ad-64b7-4d9c-this-is-an-example

Create a device enrollment token

A registered device becomes a trusted device after it goes through the enrollment ceremony. To enroll the device, a device enrollment token is necessary. The token is created by a device admin and sent to the person performing the enrollment off-band (for example, via a corporate chat).

To create an enrollment token run the command below, where --asset-tag is the serial number of the device we want to enroll:

tctl devices enroll --asset-tag="C00AA0AAAA0A"
Run the command below on device "C00AA0AAAA0A" to enroll it:tsh device enroll --token=AAAAAAAAAAAAAAAAAAAAAAAA-this-is-an-example

Enroll a trusted device

To perform the enrollment ceremony, using the device specified above, type the command printed by tctl devices enroll:

tsh device enroll --token=AAAAAAAAAAAAAAAAAAAAAAAA-this-is-an-example
Device "C00AA0AAAA0A"/macOS enrolled
tsh logout
tsh login --proxy=teleport.example.com --user=myuser # fetch new certificates
Enter password for Teleport user myuser:Tap any security keyDetected security key tap> Profile URL:        teleport.example.com:443  Logged in as:       myuser  Cluster:            teleport.example.com  Roles:              access, editor  Logins:             myuser  Kubernetes:         enabled  Valid until:        2023-06-23 02:47:05 -0300 -03 [valid for 12h0m0s]  Extensions:         teleport-device-asset-tag, teleport-device-credential-id, teleport-device-id

The presence of the teleport-device-* extensions shows that the device was successfully enrolled and authenticated. The device above is now a trusted device.

Auto-Enrollment

Distributing enrollment tokens to many users can be challenging. To address that, Teleport supports auto-enrollment. When enabled, auto-enrollment automatically enrolls the user's device in their next Teleport (tsh) login.

For auto-enrollment to work, the following conditions must be met:

• A device must be registered. Registration may be manual or performed using an integration, like the Jamf Pro integration.
• Auto-enrollment must be enabled in the cluster setting.
• User must have either preset editor or device-enroll (available v13.3.6+) role assigned to them.

Enable auto-enrollment in your cluster settings. To do so, modify the dynamic config resource 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:
  # ...
  device_trust:
    mode: "required"
+   auto_enroll: true

Save and close your editor to apply your changes.

Once enabled, users with their device registered in Teleport will have their device enrolled to Teleport in their next login.

tsh logout
All users logged out.
tsh login --proxy=teleport.example.com --user=myuser
Enter password for Teleport user myuser:Tap any security keyDetected security key tap> Profile URL:        teleport.example.com:443  Logged in as:       myuser  Cluster:            teleport.example.com  Roles:              access, editor  Logins:             myuser  Kubernetes:         enabled  Valid until:        2023-06-23 02:47:05 -0300 -03 [valid for 12h0m0s]  Extensions:         teleport-device-asset-tag, teleport-device-credential-id, teleport-device-id

The presence of the teleport-device-* extensions shows that the device was successfully enrolled and authenticated.

Remove a trusted device

A device that is no longer in use may be removed using tctl devices rm --device-id=<ID> or tctl devices rm --asset-tag=<SERIAL>

First, find a device to delete:

tctl devices ls
Asset Tag    OS    Enroll Status Device ID------------ ----- ------------- ------------------------------------C00AA0AAAA0A macOS enrolled      c9cbb327-68a8-497e-b820-6a4b2bf58269

Now use asset-tag or device id to delete a device:

Delete using asset tag:
tctl devices rm --asset-tag=C00AA0AAAA0A
Device "C00AA0AAAA0A" removed
Delete using device id:
tctl devices rm --device-id=c9cbb327-68a8-497e-b820-6a4b2bf58269
Device "c9cbb327-68a8-497e-b820-6a4b2bf58269" removed

Configuring a TPM EKCert CA allow-list

This advice only applies to Device Trust on platforms that use TPMs, such as Windows and Linux.

Some TPMs include a certificate—known as an EKCert—signed by the manufacturer's certificate authority (CA). This certificate allows a third party (such a Teleport cluster) to know that the TPM it is communicating with is legitimate. This significantly reduces the burden on the administrator to ensure that the device has not been tampered with prior to enrollment.

By default, the Teleport cluster does not verify the EKCert. This is because not all TPMs include an EKCert, and it is not possible to verify an EKCert without knowledge of the manufacturer's CA. This verification is enabled by the inclusion of the Teleport configuration field called ekcert_allowed_cas.

Once configured, only devices that include a TPM with an EKCert signed by a CA specified in the field will be able to enroll. Previously-enrolled devices will not be affected.

To configure ekcert_allowed_cas, you must first obtain the CA certificate in PEM format from the manufacturer of the TPM included in your devices. This step varies from manufacturer to manufacturer.

After you obtain the CA certificate in PEM format, modify the dynamic config resource 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:
  ...
  device_trust:
    mode: "required" # add this line
+    ekcert_allowed_cas:
+      # The CA is configured inline within the resource:
+      - |
+        -----BEGIN CERTIFICATE-----
+        --snip--
+        -----END CERTIFICATE-----

Save and close your editor to apply your changes.

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 v16.4.6).

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:

1. Make sure your device is registered and enrolled
2. Install Teleport Connect. Use the DEB or RPM packages on Linux (the tarball doesn't register the custom URL handler).
3. Make sure Teleport Connect can access the same resource you are trying to access on the Web
4. Ask your cluster administrator if Device Trust is enabled (cluster mode "optional" or higher)

After the steps above are done try logging out from the Web UI and logging in again. If the error persists, check your audit log for failed "device authenticated" or "device web" events and look for failure details within the events.

"device web authentication IP mismatch" errors

"IP mismatch" errors in audit logs indicate that the IP checks performed by the device web authentication ceremony failed. In this case it's likely that end-user IPs are not propagated correctly to your Teleport deployment.

• L7 load balancer: make sure it propagates the X-Forwarded-For header
• L4 load balancer: enable PROXY protocol

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

Next steps

• Device Trust Enforcement
• Jamf Pro Integration