Meet us at KubeCon + CloudNativeCon: Paris, France - March 19
Book Demo
Teleport logoTry For Free
Fork me on GitHub

Teleport

Manage Trusted Devices

  • Available for:
  • Enterprise
  • Cloud
  • Team

Prerequisites

  • A Teleport Team account. If you do not have one, visit the signup page to begin your free trial.

  • The Enterprise tctl admin tool and tsh client tool version >= 14.3.6.

    You can download these tools from the Cloud Downloads page.

    tctl version

    Teleport Enterprise v14.3.6 go1.21


    tsh version

    Teleport v14.3.6 go1.21

  • A running Teleport Enterprise cluster. For details on how to set this up, see our Enterprise Getting Started guide.

  • The Enterprise tctl admin tool and tsh client tool version >= 15.0.2, which you can download by visiting your Teleport account.

    tctl version

    Teleport Enterprise v15.0.2 go1.21


    tsh version

    Teleport v15.0.2 go1.21

  • A Teleport Enterprise Cloud account. If you do not have one, visit the signup page to begin your free trial.

  • The Enterprise tctl admin tool and tsh client tool version >= 14.3.6. To download these tools, visit the Downloads page.

    tctl version

    Teleport Enterprise v14.3.6 go1.21


    tsh version

    Teleport v14.3.6 go1.21

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

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.

Self enrollment: v13.3.5+

Users with the preset editor or device-admin role (since v13.3.6) can register and enroll their device in a single step with the following command:

tsh device enroll --current-device
Sync with Jamf Pro

Teleport supports device synchronization with Jamf Pro. Once configured, devices are automatically updated in Teleport's device inventory.

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

The serial number is visible under Apple menu -> "About This Mac" -> "Serial number".

Windows and Linux devices can have multiple serial numbers depending on the configuration made by the manufacturer.

Teleport will pick the first available value from the following:

  • System asset tag
  • System serial number
  • Baseboard serial number

To find the value chosen by Teleport, run the following command:

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
Device Role

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

For clusters created using Teleport v12 or newer, the preset editor role has the necessary permissions to manage devices. For clusters created before v12, you may want to create a dedicated device-admin role.

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:

Choose one of the options

Modify the dynamic config resource using tctl edit cluster_auth_preference:

kind: cluster_auth_preference
version: v2
metadata:
  name: cluster-auth-preference
spec:
  # ...
  device_trust:
    mode: "required"
+   auto_enroll: true

Edit the Auth Server's teleport.yaml file:

auth_service:
  authentication:
    # ...
    device_trust:
+     auto_enroll: true

After saving the changes, restart the Teleport service.

Once enabled, user's with their device registered in Teleport and with the required permission (preset editor or device-enroll role) 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

Dedicated device admin role

We recommend creating a dedicated device-admin role for device inventory management.

v13.3.6+

Teleport version 13.3.6 and above has the preset device-admin role, which is a substitute for the role described below.

Following is an example of a role that grants permissions for the device resource is necessary to manage the inventory. Save the yaml below as device-admin.yaml and create it in your cluster:

version: v7
kind: role
metadata:
  name: device-admin
spec:
  allow:
    rules:
    - resources: ["device"]
      verbs:
      - create
      - read
      - list
      - update
      - delete
      - create_enroll_token
      - enroll
tctl create -f device-admin.yaml
role 'device-admin' has been created

Note that in addition to the usual CRUD verbs (create, read, list, update and delete), we have also included create_enroll_token and enroll. The create_enroll_token verb is necessary to execute the tctl devices enroll command; enroll is necessary to execute tsh device enroll.

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, there are two ways of configuring ekcert_allowed_cas:

  • Statically using the Teleport configuration file. This is the simplest option, but is not possible for Teleport Cloud clusters and not recommended for clusters in a highly available configuration.
  • Dynamically using cluster_auth_preference resource. This works with all clusters and is the most flexible.

Choose one of the options

Modify the dynamic config resource using tctl edit cluster_auth_preference:

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

Edit the Auth Server's teleport.yaml file and restart:

auth_service:
  authentication:
    ...
    device_trust:
+      ekcert_allowed_cas:
+      # The CA can be configured inline within the configuration file:
+      - |
+        -----BEGIN CERTIFICATE-----
+        --snip--
+        -----END CERTIFICATE-----
+      # Or, it can be configured in the configuration file using a path:
+      - /path/to/my/ekcert-ca.pem

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.

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