Getting Started with Device Trust

Device Trust requires two of the following steps to have been configured:

• Device enforcement mode configured via either a role or a cluster-wide config.
• Trusted device registered and enrolled with Teleport.

In this guide, you will update an existing user profile to assign the preset require-trusted-device role and then enroll a trusted device into Teleport to access a resource (a test linux server) protected with Teleport.

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)

• User with editor role.

  tsh status
  > Profile URL:      teleport.example.com:443Logged in as:       myuserCluster:            teleport.example.comRoles:              access, auditor, editorLogins:             root, ubuntu, ec2-userKubernetes:         disabledValid until:        2023-08-22 03:30:24 -0400 EDT [valid for 11h52m0s]Extensions:         login-ip, permit-agent-forwarding, permit-port-forwarding, permit-pty, private-key-policy

• Access to a linux server (any Linux server you can access via tsh ssh will do).

  tsh ls
  Node Name        Address        Labels---------------- -------------- --------------------------------------ip-172-31-35-170 ⟵ Tunnel
  test connection to ip-172-31-35-170
  tsh ssh root@ip-172-31-35-170
  root@ip-172-31-35-170:~#

tctl edit role/access

kind: role
metadata:
  labels:
    teleport.internal/resource-type: preset
  name: access
spec:
  allow:
    logins:
    - '{{internal.logins}}'
    ...
  options:
    # require authenticated device check for this role
+   device_trust_mode: "required" # add this line
    ...
  deny:
    ...

Once the above prerequisites are met, begin with the following step.

Step 1/2. Update user profile to enforce Device Trust

To enforce Device Trust, a user must be assigned with a role with Device Trust mode "required".

For this guide, we will use the preset require-trusted-device role to update current user profile.

Open the user resource in your editor so we can update it with the preset require-trusted-device role.

tctl edit users/myuser

Edit the profile:

kind: user
metadata:
  id: 1692716146877042322
  name: myuser
spec:
  created_by:
    time: "2023-08-14T13:42:22.291972449Z"
  expires: "0001-01-01T00:00:00Z"
  roles:
  - access
  - auditor
  - editor
+ - require-trusted-device # add this line
  status:
    is_locked: false
  ...

Update the user by saving and closing the file in your editor.

Now that the user profile is updated to enforce Device Trust, try to access the test server again.

tsh logout; tsh login --proxy=teleport.example.com --user=myuser
tsh ssh root@ip-172-31-35-170
ERROR: access denied to root connecting to ip-172-31-35-170:0

As you can verify from the above step, access to ip-172-31-35-170 ssh server, which was previously accessible, is now forbidden.

Step 2/2. Enroll device

To access ip-172-31-35-170 server again, you will have to enroll your device.

Enrolling your device is easy, and can be done using tsh client:

tsh device enroll --current-device
Device "C00AA0AAAA0A"/macOS registered and enrolled

Relogin to fetch updated certificate with device extension:

tsh logout; tsh login --proxy=teleport.example.com --user=myuser

tsh status
> Profile URL:        teleport.example.com:443  Logged in as:       myuser  Cluster:            teleport.example.com:443  Roles:              access, auditor, editor  Logins:             root  Kubernetes:         enabled  Valid until:        2023-08-22 04:06:53 -0400 EDT [valid for 12h0m0s]  Extensions:         login-ip, ... teleport-device-asset-tag, teleport-device-credential-id, teleport-device-id

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

Now, let's try to access server (ip-172-31-35-170) again:

tsh ssh root@ip-172-31-35-170
root@ip-172-31-35-170:~#

Congratulations! You have successfully configured a Trusted Device and accessed a resource protected with Device Trust enforcement.

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 Management
• Enforcing Device Trust
• Jamf Pro Integration
• The role we illustrated in this guide uses the internal.logins trait, which Teleport replaces with values from the Teleport local user database. For full details on how traits work in Teleport roles, see the Teleport Access Controls Reference.