Fork me on GitHub

Teleport

Device Trust (Preview)

Improve
Introducing Device Trust

Introducing Device Trust

Length: 01:35

Warning

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.

Enrollment

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 and tsh client tool version >= 13.0.3, which you can download by visiting your Teleport account.

    tctl version

    Teleport Enterprise v13.0.3 go1.20

    tsh version

    Teleport v13.0.3 go1.20

Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.

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

Editor Role

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

Removing Devices

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

Web UI

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

cluster 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 server1

ERROR: ssh: rejected: administratively prohibited (unauthorized device)

Trusted Clusters

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 vs. Cluster-wide

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