

Introducing Device Trust
Length: 01:35
Device Trust is currently in Preview mode.
Device Trust requires Teleport Enterprise v12+.
Device Trust allows Teleport admins to enforce the use of trusted devices. Resources protected by the device mode "required" will enforce the use of a trusted device, in addition to establishing the user's identity and enforcing the necessary roles. Furthermore, users using a trusted device leave audit trails that include the device's information.
The device trust preview works only with macOS devices and supports the following Teleport features:
- SSH access enforcement
- Database access enforcement
- Kubernetes access enforcement
Support for other operating systems and access features is planned for upcoming Teleport versions.
Concepts
Device Trust uses the Secure Enclave in macOS devices to store a device private key. That key is used to solve device challenges issued by the Teleport Auth Server, proving the identity of the trusted device.
Device management is divided into two separate phases: inventory management and device enrollment.
Inventory management is performed by a device admin. In this step, devices are registered or removed from Teleport. For example, this happens when the IT department of your company acquires new devices, or retires devices from use.
Device enrollment is performed either by a device admin or by the end-user, at your discretion. This is the step that creates the Secure Enclave private key in the device and register its public key counterpart with the Teleport Auth Server. Enrollment has to run in the actual device that you want to enroll. For example, this happens when a user gets a new device for the first time, or when IT prepares a new device for a user. Enrollment only needs to happen once per user/device combination.
Device enrollment is key in correctly identifying a device throughout its lifetime. The more trusted the enrollment operator, the better the ongoing guarantees that the device itself is trustworthy.
The tie between the device inventory and enrollment is a device enrollment token. A device enrollment token needs to be created by a device admin and sent to the person performing the enrollment ceremony. The token ties the actual device being enrolled to the expected device in the inventory, adding an extra layer of protection.
Prerequisites
-
A running Teleport Enterprise cluster, including the Auth Service and Proxy Service. For details on how to set this up, see our Enterprise Getting Started guide.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 13.0.3, which you can download by visiting your Teleport account.tctl versionTeleport Enterprise v13.0.3 go1.20
tsh versionTeleport v13.0.3 go1.20
Please use the latest version of Teleport Enterprise documentation.
- A signed and notarized
tsh
binary for enrollment. Download the macOS tsh installer. - A macOS device to register and enroll.
Step 1/2. 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.
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: v6
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.yamlrole 'device-admin' has been created
For clusters created using Teleport v12 or newer, the builtin role editor
has
the necessary permissions to manage devices. For production setups a separate
role is still recommended.
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
. Both are
demonstrated in the following section.
Make sure your user has the device-admin
role:
tctl edit users/alice
kind: user
metadata:
name: alice
# unrelated fields omitted.
spec:
roles:
- access
+ - device-admin # add this line
version: v2
Relogin to fetch updated certificates:
tsh logout; tsh login --proxy=example.com --user=alice
Having the necessary permissions, let's add a device to the inventory. Replace
the $SERIAL
below with your macOS device serial number (visible under Apple ->
"About This Mac" -> "Serial number", or use the command below).
SERIAL="$(ioreg -c IOPlatformExpertDevice -d 2 | grep -i IOPlatformSerialNumber | awk -F'"' '{print $4}')"tctl devices add --os=macos --asset-tag="$SERIAL"Device C00AA0AAAA0A/macOS added to the inventory
View registered devices:
tctl devices lsAsset Tag OS Enroll Status Device ID
------------ ----- ------------- ------------------------------------
C00AA0AAAA0A macOS not enrolled 9cdfc0ad-64b7-4d9c-this-is-an-example
A registered device is a device that Teleport knows about. Once a registered device is enrolled, it becomes 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>
.
Step 2/2. Enroll a trusted device
A registered device becomes a trusted device after it goes through the enrollment ceremony. Enrollment exchanges an enrollment token, created by a device admin, for the opportunity to enroll the corresponding device.
macOS enrollments are tied to the current user in the device. If the same device is handed to a new user, they will need to perform enrollment again.
To create an enrollment token run the following command, 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
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-exampleDevice "C00AA0AAAA0A"/macOS enrolled
tsh logout; tsh login --proxy=example.com --user=alice # fetch new certificates
The device above is now a trusted device.
Optional: Cluster-wide trusted device enforcement
Cluster-wide configuration enforces trusted device access at the cluster level.
It can be configured with the following three modes of operation, represented
by the device_trust.mode
authentication setting:
off
- disables device trust. Device authentication is not performed and device-aware audit logs are absent.optional
- enables device authentication and device-aware audit, but does not require a trusted device to access resources.required
- enables device authentication and device-aware audit. Additionally, it requires a trusted device for all SSH, Database and Kubernetes connections.
Enterprise clusters run in optional
mode by default. Changing the mode to
required
will enforce a trusted device for all SSH, Database and Kubernetes
accesses.
The Web UI is not capable of trusted device access during the device trust
preview. Only tsh
and Teleport Connect are able to fulfill device mode
required
.
To enable device mode required
update your configuration as follows:
Choose one of the options
Create a cap.yaml
file or get the existing configuration using
tctl get cluster_auth_preference
:
kind: cluster_auth_preference
version: v2
metadata:
name: cluster-auth-preference
spec:
type: local
second_factor: "on"
webauthn:
rp_id: example.com
device_trust:
+ mode: "required" # add this line
Update the configuration:
tctl create -f cap.yamlcluster auth preference has been updated
You can also edit this configuration directly:
tctl edit cluster_auth_preference
Edit the Auth Server's teleport.yaml
file and restart all Auth Services:
auth_service:
authentication:
type: local
second_factor: "on"
webauthn:
rp_id: example.com
device_trust:
+ mode: "required" # add this line
SSH, Database and Kubernetes access without a trusted device is now forbidden. For example, SSH access without a trusted device fails with the following error:
tsh ssh server1ERROR: ssh: rejected: administratively prohibited (unauthorized device)
It is possible to use trusted
clusters to limit the impact of
device mode required
. A leaf cluster in mode required
will enforce access to
all of its resources, without imposing the same restrictions to the root
cluster. Likewise, a root cluster will not enforce device trust on resources in
leaf clusters.
Optional: Role-based trusted device enforcement
Role-based configuration enforces trusted device access at the role level. It
can be configured with the spec.options.device_trust_mode
(required
,
optional
, off
) option and applies to the resources in its allow
rules. It
works similar to require_session_mfa
.
To enforce authenticated device checks for a specific role, update the role with the following:
kind: role
version: v6
metadata:
name: example-role
spec:
options:
# require authenticated device check for this role
+ device_trust_mode: "required" # add this line
allow:
logins: ['admin']
kubernetes_groups: ['edit']
node_labels:
'*': '*'
...
Per-role configuration let's you progressively block unauthorized device access, and is useful for getting started with Teleport Device Trust.
Once all the devices used are enrolled in Teleport, cluster-wide configuration will ensure every resources can only ever be accessed with a trusted device.
Optional: Locking a device
Similar to session and identity locking, a device can be locked
using tctl lock
.
Locking blocks certificate issuance and ongoing or future accesses originating from a locked device. Locking a device only works if device trust is enabled and if the device is enrolled to Teleport.
Find a device ID to lock:
tctl devices lsAsset Tag OS Enroll Status Device ID
------------ ----- ------------- ------------------------------------
C00AA0AAAA0A macOS enrolled 9cdfc0ad-64b7-4d9c-this-is-an-example
Lock a device:
tctl lock --device 9cdfc0ad-64b7-4d9c-this-is-an-example --ttl=12hCreated a lock with name "5444970a-39a0-4814-968d-e58b4a8fa686".
Now, if a user on that device tries to access an SSH server for example, Teleport will deny access:
tsh ssh server1ERROR: ssh: rejected: administratively prohibited (lock targeting Device:"9cdfc0ad-64b7-4d9c-this-is-an-example" is in force)
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 signed and notarized tsh
binary is necessary to use a trusted device. Make
sure to download and use the
macOS tsh installer.
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.