
Teleport
Getting Started with Device Trust
- Version 15.x
- Version 14.x
- Version 13.x
- Version 12.x
- Older Versions
- Available for:
- Enterprise
- Cloud
- Team

Introducing Device Trust
Length: 01:35
Device Trust is currently in Preview mode and supports following components:
- User devices: macOS and Windows.
- Teleport client:
tsh
and Teleport connect. - Resources: SSH, Database and Kubernetes.
Support for other operating systems, access from Web UI and application access is planned for upcoming Teleport versions.
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 Teleport Team account. If you do not have one, visit the signup page to begin your free trial.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 13.3.9.You can download these tools from the Cloud Downloads page.
tctl versionTeleport Enterprise v13.3.9 go1.21
tsh versionTeleport v13.3.9 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 andtsh
client tool version >= 14.0.1, which you can download by visiting your Teleport account.tctl versionTeleport Enterprise v14.0.1 go1.21
tsh versionTeleport v14.0.1 go1.21
Please use the latest version of Teleport Enterprise documentation.
- 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.
- A signed and notarized
- 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 lsNode Name Address Labels---------------- -------------- --------------------------------------ip-172-31-35-170 ⟵ Tunneltest connection to ip-172-31-35-170
tsh ssh root@ip-172-31-35-170root@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.
The preset require-trusted-device
role, as referenced in this guide, is only available
from Teleport version 13.3.6 and above. For older Teleport cluster, you will need to update
a role with device_trust_mode: required
.
For simplicity, the example below updates the preset access
role but you can update
any existing access granting role which the user is assigned with to enforce Device Trust.
First, fetch a role so you can update it locally:
tctl edit role/access
Edit the role with device trust mode:
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:
...
Save your edits.
Now that the access
role is configured with device mode "required", users with
this role will be enforced with Device Trust.
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=myusertsh ssh root@ip-172-31-35-170ERROR: 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-deviceDevice "C00AA0AAAA0A"/macOS registered and enrolled
The --current-device
flag tells tsh
to enroll current device. User must have the preset editor
or device-admin
role to be able to self-enroll their device. For users without the editor
or
device-admin
roles, an enrollment token must be generated by a device admin, which can then be
used to enroll the device. Learn more about manual device enrollment in the
device management guide
Relogin to fetch updated certificate with device extension:
tsh logout; tsh login --proxy=teleport.example.com --user=myusertsh 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.