Update device trust docs

docs/config.json

@@ -345,23 +345,35 @@
           "slug": "/access-controls/device-trust/",
           "forScopes": [
             "enterprise",
-            "cloud"
+            "cloud",
+            "team"
           ],
           "entries": [
             {
-              "title": "Set Up Device Trust",
+              "title": "Getting Started",
               "slug": "/access-controls/device-trust/guide/",
               "forScopes": [
                 "enterprise",
-                "cloud"
+                "cloud",
+                "team"
               ]
             },
             {
-              "title": "Set Up Auto-Enrollment",
-              "slug": "/access-controls/device-trust/auto-enrollment/",
+              "title": "Manage Trusted Devices",
+              "slug": "/access-controls/device-trust/device-management/",
               "forScopes": [
                 "enterprise",
-                "cloud"
+                "cloud",
+                "team"
+              ]
+            },
+            {
+              "title": "Enforce Device Trust",
+              "slug": "/access-controls/device-trust/enforcing-device-trust/",
+              "forScopes": [
+                "enterprise",
+                "cloud",
+                "team"
               ]
             },
             {
@@ -1551,6 +1563,11 @@
     }
   ],
   "variables": {
+    "clusterDefaults": {
+      "clusterName": "teleport.example.com",
+      "username": "myuser",
+      "nodeIP": "ip-172-31-35-170"
+    },
     "ansible": {
       "min_version": "2.9.6"
     },
@@ -2659,6 +2676,11 @@
       "destination": "/access-controls/device-trust/guide/",
       "permanent": true
     },
+    {
+      "source": "/access-controls/device-trust/auto-enrollment/",
+      "destination": "/access-controls/device-trust/device-management/",
+      "permanent": true
+    },
     {
       "source": "/management/guides/teleport-operator/",
       "destination": "/management/dynamic-resources/teleport-operator/",

docs/pages/access-controls/device-trust.mdx

@@ -1,31 +1,97 @@
 ---
 title: Device Trust (Preview)
-description: Use and enforce trusted devices with Teleport
+description: Teleport Device Trust Concepts
 layout: tocless-doc
+videoBanner: gBQyj_X1LVw
 ---
 
 <Admonition type="warning">
-Device Trust is currently in Preview mode.
+  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.
 </Admonition>
 
+## Concepts
+
 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 on macOS and Windows devices and supports the
-following Teleport features:
+Device Trust requires two of the following steps to have been configured:
+
+- Trusted device registered and enrolled with Teleport.
+- Device enforcement mode configured via either a role or a cluster-wide config.
+
+Categorically, we define these two requirements as Trusted Device management
+and Device Trust enforcement.
+
+## Trusted Device management
+
+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.
+
+Inventory management can be manually operated using `tctl` or automatically synced
+with a Mobile Device Management (MDM) solution such as Jamf Pro.
+
+**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 registers its public key counterpart with the Teleport Auth
+Server. Enrollment has to run on 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 exchanges an enrollment token, created by a
+device admin, for the opportunity to enroll the corresponding device.
+
+### How trust is established with the device
+
+Device Trust leverages dedicated secure hardware in devices to store device credentials
+and perform device challenges. The specific implementation varies between types of devices.
+
+On macOS devices, Device Trust uses the Secure Enclave in order to store a
+device private key. That key is used to solve device challenges issued by the
+Teleport Auth Service, proving the identity of the trusted device.
+
+On Windows devices, a Trusted Platform Module (TPM) is used to perform an
+attestation as to the state of the device. This attestation is signed by a
+private key that is also protected by the TPM.
+
+The signed attestation ensures that the Teleport Auth Service knows both the state
+of the device and that the request has come from the device.
+
+That said, a device is as "trustworthy" as the enrollment process. If enrollment operator
+enrolls a malicious device to Teleport, establishing trust with Secure Enclave or TPM is
+already defeated at this point. The more trusted the enrollment environment and operator,
+the better the ongoing guarantees that the device itself is trustworthy.
+
+## Device Trust enforcement
+
+Enforcing Device Trust means configuring Teleport with device trust mode, i.e. applying
+`device_trust_mode: required` rule, which tells Teleport Auth Service to only allow access
+with a trusted and an authenticated device, in addition to establishing the user's identity and enforcing
+the necessary roles.
 
-- SSH access enforcement
-- Database access enforcement
-- Kubernetes access enforcement
+Teleport supports two methods for device enforcement: Role-based
+enforcement and Cluster-wide enforcement.
 
-Support for other operating systems and access features is planned for upcoming
-Teleport versions.
+- **Role-based enforcement** can be used to enforce Device Trust at role level, using RBAC.
+- **Cluster-wide enforcement** can be used to enforce Device Trust at cluster level.
 
 ## Guides
 
-- [Set Up Device Trust](./device-trust/guide.mdx)
-- [Set Up Auto-Enrollment](./device-trust/auto-enrollment.mdx)
+- [Getting Started with Device Trust](./device-trust/guide.mdx)
+- [Device Management](./device-trust/device-management.mdx)
+- [Enforcing Device Trust](./device-trust/enforcing-device-trust.mdx)
 - [Jamf Pro Integration](./device-trust/jamf-integration.mdx)