Device Trust (Preview)

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.

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 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.yaml
role 'device-admin' has been created

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

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-example
Device "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 doesn't 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.

To enable device mode required update your configuration as follows:

auth_service:
  authentication:
    type: local
    second_factor: "on"
    webauthn:
      rp_id: example.com
    device_trust:
+     mode: "required" # add this line

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

tctl create -f cap.yaml
cluster auth preference has been updated

tctl edit cluster_auth_preference

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 server1
ERROR: ssh: rejected: administratively prohibited (unauthorized device)

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

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 ls
Asset 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=12h
Created 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 server1
ERROR: 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.