Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update public docs for device trust web #41334

Merged
merged 8 commits into from
May 9, 2024
Merged

Update public docs for device trust web #41334

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
250b2aa
Update device trust support notice
codingllama May 8, 2024
e5df441
Update prerequisites
codingllama May 8, 2024
b1776bf
Update troubleshooting
codingllama May 8, 2024
c5ef6b1
Remove Web UI warning
codingllama May 8, 2024
0c78e16
Update the App Access section
codingllama May 8, 2024
44a33e0
Add the Desktop Access section
codingllama May 8, 2024
4cb30e1
Mention Teleport v16 on App Access content
codingllama May 8, 2024
f2250a9
Mention that the services do the enforcement
codingllama May 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 1 addition & 11 deletions docs/pages/access-controls/device-trust.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,17 +5,7 @@ layout: tocless-doc
videoBanner: gBQyj_X1LVw
---

<Admonition type="notice">
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.
</Admonition>
(!docs/pages/includes/device-trust/support-notice.mdx!)

## Concepts

Expand Down
79 changes: 65 additions & 14 deletions docs/pages/access-controls/device-trust/enforcing-device-trust.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,11 +78,6 @@
`required` will enforce a trusted device for all SSH, Database and Kubernetes
accesses.

<Admonition type="warning" title="Web UI">
The Web UI is not capable of trusted device access. Only `tsh` and Teleport
Connect are able to fulfill device mode `required`.
</Admonition>

To enable device mode `required` update your configuration as follows:

<Tabs dropDownCaption="Teleport Deployment">
Expand Down Expand Up @@ -154,14 +149,20 @@

## 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.
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
later), make sure your device is [registered and enrolled](
./device-management.mdx#register-a-trusted-device), install [Teleport Connect](
codingllama marked this conversation as resolved.
Show resolved Hide resolved
../../connect-your-client/teleport-connect.mdx#installation--upgrade), and
follow the instructions during login.

For example, to enforce device trust for all `env:production` apps, save the
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
Expand Down Expand Up @@ -199,8 +200,58 @@
```

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.

## Desktop Access support

Check failure on line 204 in docs/pages/access-controls/device-trust/enforcing-device-trust.mdx

View workflow job for this annotation

GitHub Actions / Lint docs prose style 

[vale] reported by reviewdog 🐶
[messaging.protocol-products] Avoid the impression that Teleport consists of multiple products for secure access, e.g., "Database Access" or "Server Access". Instead, talk about enrolling resources in your Teleport cluster, protecting resources with Teleport, or the ability for Teleport to proxy various protocols.

Raw Output:
{"message": "[messaging.protocol-products] Avoid the impression that Teleport consists of multiple products for secure access, e.g., \"Database Access\" or \"Server Access\". Instead, talk about enrolling resources in your Teleport cluster, protecting resources with Teleport, or the ability for Teleport to proxy various protocols.", "location": {"path": "docs/pages/access-controls/device-trust/enforcing-device-trust.mdx", "range": {"start": {"line": 204, "column": 4}}}, "severity": "ERROR"}
codingllama marked this conversation as resolved.
Show resolved Hide resolved

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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are we capitalizing "device trust"? I would use consistent capitalization so readers know whether to treat this is as a Teleport-specific feature—if it's a general computing term that's not unique to Teleport, it would make sense to use lowercase everywhere.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll take a look and see what we are doing. Do you have a preference for capitalized or not in this particular case?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry for the delay. It's a mixed bag for sure, we use both capitalized and not in various places. If you have a suggestion, @ptgott, I'd be happy to write a follow-up "normalizing" it.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The AWS Verified Access docs say "device trust", although Okta capitalizes "Device Trust". I think this is a general enough computing term that "device trust" makes sense, though to be honest I can see "Device Trust" making sense as well. I'll ask Marketing and write a Vale rule for it so we can decouple the standardization work from this PR!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds great, thanks!

[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

Expand Down
12 changes: 1 addition & 11 deletions docs/pages/access-controls/device-trust/guide.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,17 +4,7 @@ description: Get started with Teleport Device Trust
videoBanner: gBQyj_X1LVw
---

<Admonition type="notice">
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.
</Admonition>
(!docs/pages/includes/device-trust/support-notice.mdx!)

Device Trust requires two of the following steps to have been configured:

Expand Down
2 changes: 2 additions & 0 deletions docs/pages/includes/device-trust/prereqs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
10 changes: 10 additions & 0 deletions docs/pages/includes/device-trust/support-notice.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
<Admonition type="notice">
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
</Admonition>
36 changes: 26 additions & 10 deletions docs/pages/includes/device-trust/troubleshooting.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 (Teleport v16 or later).

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
Expand All @@ -46,3 +39,26 @@ 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.

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