Teleport
Getting Started with Device Trust
- Version 17.x
- Version 16.x
- Version 15.x
- Version 14.x
- Older Versions
Introducing Device Trust
Length: 01:35
Device Trust supports all platforms and clients, including tsh
, Teleport
Connect and the Web UI (requires Teleport Connect to be installed).
The following resources are protected by device trust:
- Role-based enforcement only: Apps and Desktops
- Cluster and role-based enforcement: SSH nodes, databases, and Kubernetes clusters
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 andtsh
client tool.Visit Installation for instructions on downloading
tctl
andtsh
.
- To enroll a macOS device, you need:
- A signed and notarized
tsh
binary. Download the macOS tsh installer.
- A signed and notarized
- 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
- 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:~#
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.
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=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.
"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"
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:
- Make sure your device is registered and enrolled
- Install Teleport Connect. Use the DEB or RPM packages on Linux (the tarball doesn't register the custom URL handler).
- Make sure Teleport Connect can access the same resource you are trying to access on the Web
- Ask your cluster administrator if device trust is enabled (cluster mode "optional" or higher)
If all of the above steps are done, try logging out from the Web UI and logging in again.
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.