From 250b2aa3abad37fe5882a2ef2b8a443fbd76dcb2 Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 8 May 2024 15:22:19 -0300 Subject: [PATCH 1/8] Update device trust support notice --- docs/pages/access-controls/device-trust.mdx | 12 +----------- docs/pages/access-controls/device-trust/guide.mdx | 12 +----------- docs/pages/includes/device-trust/support-notice.mdx | 10 ++++++++++ 3 files changed, 12 insertions(+), 22 deletions(-) create mode 100644 docs/pages/includes/device-trust/support-notice.mdx diff --git a/docs/pages/access-controls/device-trust.mdx b/docs/pages/access-controls/device-trust.mdx index 36f92779b363c..658a7dd487d5b 100644 --- a/docs/pages/access-controls/device-trust.mdx +++ b/docs/pages/access-controls/device-trust.mdx @@ -5,17 +5,7 @@ layout: tocless-doc videoBanner: gBQyj_X1LVw --- - - Device Trust supports the following components: - - - User devices: macOS, Windows and Linux. - - Teleport client: `tsh` and Teleport connect. - - Resources: Apps (role-based enforcement only), SSH nodes, databases, and - Kubernetes clusters - - Support for the Web UI and desktop access are planned for upcoming Teleport - versions. - +(!docs/pages/includes/device-trust/support-notice.mdx!) ## Concepts diff --git a/docs/pages/access-controls/device-trust/guide.mdx b/docs/pages/access-controls/device-trust/guide.mdx index aa0bd817aa234..45efc23226fdc 100644 --- a/docs/pages/access-controls/device-trust/guide.mdx +++ b/docs/pages/access-controls/device-trust/guide.mdx @@ -4,17 +4,7 @@ description: Get started with Teleport Device Trust videoBanner: gBQyj_X1LVw --- - - Device Trust supports the following components: - - - User devices: macOS, Windows and Linux. - - Teleport client: `tsh` and Teleport connect. - - Resources: Apps (role-based enforcement only), SSH nodes, databases, and - Kubernetes clusters - - Support for the Web UI and desktop access are planned for upcoming Teleport - versions. - +(!docs/pages/includes/device-trust/support-notice.mdx!) Device Trust requires two of the following steps to have been configured: diff --git a/docs/pages/includes/device-trust/support-notice.mdx b/docs/pages/includes/device-trust/support-notice.mdx new file mode 100644 index 0000000000000..ee55c48303130 --- /dev/null +++ b/docs/pages/includes/device-trust/support-notice.mdx @@ -0,0 +1,10 @@ + + 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 + From e5df4417e03a4ed0197f3510883161142799429f Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 8 May 2024 15:22:38 -0300 Subject: [PATCH 2/8] Update prerequisites --- docs/pages/includes/device-trust/prereqs.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/pages/includes/device-trust/prereqs.mdx b/docs/pages/includes/device-trust/prereqs.mdx index 599ae72de5e70..98ad852d99873 100644 --- a/docs/pages/includes/device-trust/prereqs.mdx +++ b/docs/pages/includes/device-trust/prereqs.mdx @@ -10,3 +10,5 @@ - 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](../../installation.mdx#linux). +- To authenticate a Web UI session you need [Teleport Connect]( + ../../connect-your-client/teleport-connect.mdx#installation--upgrade) From b1776bf9808f939ea81e7fb7db858dd9d64e2a53 Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 8 May 2024 16:08:54 -0300 Subject: [PATCH 3/8] Update troubleshooting --- .../includes/device-trust/troubleshooting.mdx | 31 +++++++++++++------ 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/docs/pages/includes/device-trust/troubleshooting.mdx b/docs/pages/includes/device-trust/troubleshooting.mdx index ef3323c2a24d5..7b39b644b0d77 100644 --- a/docs/pages/includes/device-trust/troubleshooting.mdx +++ b/docs/pages/includes/device-trust/troubleshooting.mdx @@ -26,17 +26,10 @@ https://github.com/tpm2-software/tpm2-tss/blob/ede63dd1ac1f0a46029d457304edcac21 ### App access and "access to this app requires a trusted device" -A Teleport admin configured the particular app you are trying to access to -require a trusted device. +Follow the instructions in the [Web UI troubleshooting section]( +#web-ui-fails-to-authenticate-trusted-device) below. -There are a few situations that might cause the error: - -1. You are trying to access the app using the Web UI. - -2. You are trying to access the app using an untrusted device. - -The Web UI is currently not capable of device authentication. To access apps -protected by device trust you need to use one of the tsh commands described by +Alternatively, you may use one of the tsh commands described by [App Access support]( ../../access-controls/device-trust/enforcing-device-trust.mdx#app-access-support). For example, for an app called `myapp`, run `tsh proxy app myapp -p 8888`, then @@ -46,3 +39,21 @@ 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]( #unauthorized-device-errors-using-a-trusted-device) above. + +### 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: + +1. Make sure your device is [registered and enrolled]( + ../../access-controls/device-trust/device-management.mdx#register-a-trusted-device) +2. Install [Teleport Connect]( + ../../connect-your-client/teleport-connect.mdx#installation--upgrade) +3. Make sure Teleport Connect can access the same resource you are trying to + access on the Web +4. 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. From c5ef6b1481f984a01180656ee6a99ea788f1be6a Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 8 May 2024 16:16:58 -0300 Subject: [PATCH 4/8] Remove Web UI warning --- .../access-controls/device-trust/enforcing-device-trust.mdx | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/pages/access-controls/device-trust/enforcing-device-trust.mdx b/docs/pages/access-controls/device-trust/enforcing-device-trust.mdx index 4863077df36f1..5c514d6ec7cc5 100644 --- a/docs/pages/access-controls/device-trust/enforcing-device-trust.mdx +++ b/docs/pages/access-controls/device-trust/enforcing-device-trust.mdx @@ -78,11 +78,6 @@ 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. Only `tsh` and Teleport -Connect are able to fulfill device mode `required`. - - To enable device mode `required` update your configuration as follows: From 0c78e1682c5a230a2f87755dcba69e98a26de21c Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 8 May 2024 15:51:08 -0300 Subject: [PATCH 5/8] Update the App Access section --- .../device-trust/enforcing-device-trust.mdx | 20 +++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/pages/access-controls/device-trust/enforcing-device-trust.mdx b/docs/pages/access-controls/device-trust/enforcing-device-trust.mdx index 5c514d6ec7cc5..3f48ed3a9d824 100644 --- a/docs/pages/access-controls/device-trust/enforcing-device-trust.mdx +++ b/docs/pages/access-controls/device-trust/enforcing-device-trust.mdx @@ -150,13 +150,19 @@ leaf clusters. ## App Access support Apps may enforce device trust via [role-based enforcement]( -#role-based-trusted-device-enforcement). Any apps that enforce device trust must -be accessed using tsh commands such as [tsh proxy app]( -../../reference/cli/tsh.mdx#tsh-proxy-app) or using the certificates issued by -`tsh app login`. Direct access to those apps via the Web UI is not yet -available. +#role-based-trusted-device-enforcement). -For example, to enforce device trust for all `env:production` apps, save the +To access apps protected by device trust using the Web UI, make sure your device +is [registered and enrolled]( +./device-management.mdx#register-a-trusted-device), install [Teleport Connect]( +../../connect-your-client/teleport-connect.mdx#installation--upgrade), and +follow the instructions during login. + +Alternatively, you may use [tsh proxy app]( +../../reference/cli/tsh.mdx#tsh-proxy-app) or the certificates issued by +`tsh app login`. + +As an example, to enforce device trust for all `env:production` apps, save the role below as `require-trusted-device-apps.yaml`: ```yaml @@ -194,8 +200,6 @@ version: v2 ``` Now the alice user can only access `env:production` apps using a trusted device. -For example, to access an app called `myapp`, alice runs `tsh proxy app myapp -p -8888` and opens http://localhost:8888 in her browser. ## Locking a device From 44a33e054ea7275f6193ab9f1c69e0299dee480e Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 8 May 2024 16:01:04 -0300 Subject: [PATCH 6/8] Add the Desktop Access section --- .../device-trust/enforcing-device-trust.mdx | 52 +++++++++++++++++++ .../includes/device-trust/troubleshooting.mdx | 5 ++ 2 files changed, 57 insertions(+) diff --git a/docs/pages/access-controls/device-trust/enforcing-device-trust.mdx b/docs/pages/access-controls/device-trust/enforcing-device-trust.mdx index 3f48ed3a9d824..991c6a11c6d89 100644 --- a/docs/pages/access-controls/device-trust/enforcing-device-trust.mdx +++ b/docs/pages/access-controls/device-trust/enforcing-device-trust.mdx @@ -201,6 +201,58 @@ version: v2 Now the alice user can only access `env:production` apps using a trusted device. +## Desktop Access support + +Desktop access may enforce device trust via [role-based enforcement]( +#role-based-trusted-device-enforcement). + +To access desktops protected by device trust make sure your device is +[registered and enrolled](./device-management.mdx#register-a-trusted-device), +install [Teleport Connect]( +../../connect-your-client/teleport-connect.mdx#installation--upgrade), and +follow the instructions during login. + +As an example, to enforce device trust for all `env:production` desktops, save +the role below as `require-trusted-device-desktops.yaml`: + +```yaml +kind: role +version: v7 +metadata: + name: require-trusted-device-desktops +spec: + options: + device_trust_mode: "required" + allow: + windows_desktop_labels: + env: "production" + windows_desktop_logins: ["Administrator", "alice"] +``` + +Create the role and assign it to a user: + +```code +$ tctl create require-trusted-device-desktops.yaml +$ tctl edit users/alice +``` + +```diff +kind: user +metadata: + name: alice + # (...) +spec: + roles: + - access + - editor ++ - require-trusted-device-desktops + # (...) +version: v2 +``` + +Now the alice user can only access `env:production` desktops using a trusted +device. + ## Locking a device Similar to [session and identity locking](../guides/locking.mdx), a device can diff --git a/docs/pages/includes/device-trust/troubleshooting.mdx b/docs/pages/includes/device-trust/troubleshooting.mdx index 7b39b644b0d77..e0ec1eea13300 100644 --- a/docs/pages/includes/device-trust/troubleshooting.mdx +++ b/docs/pages/includes/device-trust/troubleshooting.mdx @@ -40,6 +40,11 @@ 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]( #unauthorized-device-errors-using-a-trusted-device) above. +### Desktop access and "access to this app requires a trusted device" + +Follow the instructions in the [Web UI troubleshooting section]( +#web-ui-fails-to-authenticate-trusted-device) below. + ### Web UI fails to authenticate trusted device The Web UI attempts to authenticate your device using Teleport Connect during From 4cb30e1049246d40d870e15ff3f13ef6e7e4048e Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 8 May 2024 17:39:42 -0300 Subject: [PATCH 7/8] Mention Teleport v16 on App Access content --- .../access-controls/device-trust/enforcing-device-trust.mdx | 4 ++-- docs/pages/includes/device-trust/troubleshooting.mdx | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/pages/access-controls/device-trust/enforcing-device-trust.mdx b/docs/pages/access-controls/device-trust/enforcing-device-trust.mdx index 991c6a11c6d89..1f8fd824bc262 100644 --- a/docs/pages/access-controls/device-trust/enforcing-device-trust.mdx +++ b/docs/pages/access-controls/device-trust/enforcing-device-trust.mdx @@ -152,8 +152,8 @@ leaf clusters. Apps may enforce device trust via [role-based enforcement]( #role-based-trusted-device-enforcement). -To access apps protected by device trust using the Web UI, make sure your device -is [registered and enrolled]( +To access apps protected by device trust using the Web UI (Teleport v16 or +later), make sure your device is [registered and enrolled]( ./device-management.mdx#register-a-trusted-device), install [Teleport Connect]( ../../connect-your-client/teleport-connect.mdx#installation--upgrade), and follow the instructions during login. diff --git a/docs/pages/includes/device-trust/troubleshooting.mdx b/docs/pages/includes/device-trust/troubleshooting.mdx index e0ec1eea13300..0977838ecb6fd 100644 --- a/docs/pages/includes/device-trust/troubleshooting.mdx +++ b/docs/pages/includes/device-trust/troubleshooting.mdx @@ -27,7 +27,7 @@ https://github.com/tpm2-software/tpm2-tss/blob/ede63dd1ac1f0a46029d457304edcac21 ### App access and "access to this app requires a trusted device" Follow the instructions in the [Web UI troubleshooting section]( -#web-ui-fails-to-authenticate-trusted-device) below. +#web-ui-fails-to-authenticate-trusted-device) below (Teleport v16 or later). Alternatively, you may use one of the tsh commands described by [App Access support]( From f2250a99455d01806aa3a1448cf1fce2e8d64903 Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Thu, 9 May 2024 12:15:20 -0300 Subject: [PATCH 8/8] Mention that the services do the enforcement --- .../access-controls/device-trust/enforcing-device-trust.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/pages/access-controls/device-trust/enforcing-device-trust.mdx b/docs/pages/access-controls/device-trust/enforcing-device-trust.mdx index 1f8fd824bc262..987d626e5917e 100644 --- a/docs/pages/access-controls/device-trust/enforcing-device-trust.mdx +++ b/docs/pages/access-controls/device-trust/enforcing-device-trust.mdx @@ -149,7 +149,7 @@ leaf clusters. ## App Access support -Apps may enforce device trust via [role-based enforcement]( +The Teleport App Service may enforce device trust via [role-based enforcement]( #role-based-trusted-device-enforcement). To access apps protected by device trust using the Web UI (Teleport v16 or @@ -203,8 +203,8 @@ Now the alice user can only access `env:production` apps using a trusted device. ## Desktop Access support -Desktop access may enforce device trust via [role-based enforcement]( -#role-based-trusted-device-enforcement). +The Teleport Desktop Service may enforce device trust via [role-based +enforcement]( #role-based-trusted-device-enforcement). To access desktops protected by device trust make sure your device is [registered and enrolled](./device-management.mdx#register-a-trusted-device),