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

• To enroll a macOS device, you need:
  • A signed and notarized tsh binary for enrollment. Download the macOS tsh installer.
  • A Teleport version newer than v12.0.0.
• To enroll a Windows device, you need:
  • A device that includes a TPM with 2.0 support.
  • tsh installed on the device. Download the Windows tsh installer.
  • Credentials for a user with administrator privileges for the device. This is only required during enrollment.
  • A Teleport version newer than v13.1.2.

• 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:~#

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.

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

First, let's fetch the user profile locally so we can update it with the preset require-trusted-device role.

tctl get users/myuser > myuser.yaml

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

Save and update user:

tctl create -f myuser.yaml

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.

Next steps

• Device Management
• Enforcing Device Trust
• Jamf Pro Integration