From 1aafaa9700c85cb992df1de73d1c6f387ebc9b7a Mon Sep 17 00:00:00 2001 From: Zac Bergquist Date: Wed, 16 Feb 2022 11:31:20 -0700 Subject: [PATCH] Update desktop access docs for 9.0 - Remove admonition about being in preview - Add audit events listing - Break reference.mdx up into separate pages --- docs/pages/desktop-access/getting-started.mdx | 18 +- docs/pages/desktop-access/introduction.mdx | 43 ++--- docs/pages/desktop-access/rbac.mdx | 137 +++++++++++++++ docs/pages/desktop-access/reference.mdx | 122 ------------- docs/pages/desktop-access/reference/audit.mdx | 161 ++++++++++++++++++ docs/pages/desktop-access/reference/cli.mdx | 24 +++ .../reference/configuration.mdx | 36 ++++ docs/pages/desktop-access/troubleshooting.mdx | 8 - 8 files changed, 382 insertions(+), 167 deletions(-) create mode 100644 docs/pages/desktop-access/rbac.mdx delete mode 100644 docs/pages/desktop-access/reference.mdx create mode 100644 docs/pages/desktop-access/reference/audit.mdx create mode 100644 docs/pages/desktop-access/reference/cli.mdx create mode 100644 docs/pages/desktop-access/reference/configuration.mdx diff --git a/docs/pages/desktop-access/getting-started.mdx b/docs/pages/desktop-access/getting-started.mdx index 47f9b256d3dec..b66fc8d2dc89e 100644 --- a/docs/pages/desktop-access/getting-started.mdx +++ b/docs/pages/desktop-access/getting-started.mdx @@ -4,12 +4,6 @@ description: Connect Teleport to Active Directory and log into a Windows Desktop videoBanner: YvMqgcq0MTQ --- - - Desktop Access is currently in Preview. Do not use this feature for any - critical infrastructure and keep a backup option for accessing your desktop - hosts. - - # Getting Started In this guide we will connect an Active Directory domain to Teleport using @@ -356,7 +350,8 @@ the filepath to the `der_ca_file` configuration variable. In order to enable Desktop Access in Teleport, add the following section in `teleport.yaml` on your Linux server. For a detailed description of these -configuration fields, see the [reference](./reference.mdx) page. +configuration fields, see the +[configuration reference](./reference/configuration.mdx) page.
```yaml @@ -428,8 +423,13 @@ spec: windows_desktop_logins: ["Administrator"] ``` -See the [RBAC section](./reference.mdx#rbac) in the Reference documentation -for more information about setting up Windows Desktop Access permissions. + +Ensure that each Teleport user is only assigned Windows logins that they should +be allowed to access. + + +See the [RBAC page](./rbac.mdx) for more information about setting up +Windows Desktop Access permissions. See the [Access Controls Getting Started](../access-controls/getting-started.mdx#step-13-add-local-users-with-preset-roles) guide for instructions on how to create or update a user with a given role. diff --git a/docs/pages/desktop-access/introduction.mdx b/docs/pages/desktop-access/introduction.mdx index dcb1ce51c1568..5db07c6e893b2 100644 --- a/docs/pages/desktop-access/introduction.mdx +++ b/docs/pages/desktop-access/introduction.mdx @@ -4,22 +4,6 @@ description: Teleport Desktop Access introduction and resources. videoBanner: n2h0GisWdss --- - - Desktop Access is currently in Preview. Do not use this feature for any critical - infrastructure and keep a backup option for accessing your desktop hosts. - - Desktop Access Preview: - - - is not compatible with HSM integration. - - does not support clipboard sharing. - - does not support session recording. - - does not support per-session MFA. - - may have worse performance than a native RDP client. - - # Desktop Access Teleport manages graphical desktop access to remote hosts. With Teleport @@ -34,7 +18,7 @@ Desktop Access, you get: type="note" title="Supported platforms" > - Only Windows hosts accessible over RDP are supported currently. Specifically: + Only Windows hosts accessible over RDP are supported. Specifically: - Windows Server 2012 R2 / Windows 10 or newer - Hosts connected to an Active Directory domain @@ -50,17 +34,20 @@ Desktop Access, you get: ## Resources -{/* - -To learn more about configuring role-based access control for Desktop Access, -check out [RBAC](./rbac.mdx) section. - -TODO: Complete the RBAC section - -*/} - -See [Reference](./reference.mdx) for an overview of -Desktop Access related configuration and CLI commands. + + + Configure Windows Desktop Service + + + Role-based Access Control for Teleport Desktop Access + + + CLI Reference + + + Audit Events + + ## Troubleshooting diff --git a/docs/pages/desktop-access/rbac.mdx b/docs/pages/desktop-access/rbac.mdx new file mode 100644 index 0000000000000..21b256b88b49d --- /dev/null +++ b/docs/pages/desktop-access/rbac.mdx @@ -0,0 +1,137 @@ +--- +title: Desktop Access Access Controls +description: Role-based access control (RBAC) for Teleport Desktop Access +--- + +# Desktop Access Role-Based Access Control + +Teleport's RBAC allows administrators to set up granular access policies for +Windows desktops connected to Teleport. + +Teleport's "role" resource provides the following instruments for controlling +desktop access: + +```yaml +kind: role +version: v4 +metadata: + name: developer +spec: + options: + # Specify whether or not to record the user's desktop sessions. + # Desktop session recording is enabled if one or more of the user's + # roles has enabled recording. Defaults to true if unspecified. + # Desktop sessions will never be recorded if auth_service.session_recording + # is set to 'off' in teleport.yaml or if the cluster's session_recording_config + # resource has set 'mode: off'. + record_sessions: + desktop: true + + # Specify whether clipboard sharing should be allowed with the + # remote desktop (requires a supported browser). Defaults to true + # if unspecified. If one or more of the user's roles has disabled + # the clipboard, then it will be disabled. + desktop_clipboard: true + allow: + # Label selectors for desktops this role has access to. + windows_desktop_labels: + environment: ["dev", "stage"] + + # Windows user accounts this role can connect as. + windows_desktop_logins: ["Administrator", "{{internal.windows_logins}}"] +``` + + +Teleport's RBAC system is not a replacement for proper Active Directory +administration. Teleport-issued Windows certificates are valid for a small +amount of time, but they do apply to the entire domain. Proper care should be +taken to ensure that each Teleport user's roles reflect only the necesary +Windows logins, and that these Windows users are properly secured. + + +## Labeling + +Both `allow` and `deny` rules support `windows_desktop_labels` selectors. These +selectors are matched against the labels set on the desktop. It is possible to +use wildcards (`"*"`) to match all desktop labels. + +Windows desktops acquire labels in two ways: + +1. The `host_labels` rules defined in the Windows Desktop Service configuration +2. Automatic `teleport.dev/` labels applied by Teleport (for desktops discovered + via LDAP only) + +For example, the following `host_labels` configuration would apply the +`environment: dev` label to a Windows desktop named `test.dev.example.com`, +and the `environment: prod` label to `desktop.prod.example.com`: + +```yaml + host_labels: + - match: '^.*\.dev\.example\.com$' + labels: + environment: dev + - match: '^.*\.prod\.example\.com$' + labels: + environment: prod +``` + +For desktops discovered via LDAP, Teleport applies the following labels automatically: + +| Label | LDAP Attribute | Example | +| ----- | -------------- | ------- | +| `teleport.dev/computer_name` | `name` | `WIN-I5G06B8RT33` +| `teleport.dev/dns_host_name` | [`dNSHostName`](https://docs.microsoft.com/en-us/windows/win32/adschema/a-dnshostname) | `WIN-I5G06B8RT33.example.com` +| `teleport.dev/os` | [`operatingSystem`](https://docs.microsoft.com/en-us/windows/win32/adschema/a-operatingsystem) | `Windows Server 2012` +| `teleport.dev/os_version`| [`osVersion`](https://docs.microsoft.com/en-us/windows/win32/adschema/a-operatingsystemversion) | `4.0` +| `teleport.dev/windows_domain`| Sourced from config | `example.com` +| `teleport.dev/is_domain_controller` | `primaryGroupID` | `true` + +## Logins + +The `windows_desktop_logins` role setting lists the Windows user accounts that +the role permits access to. Like with SSH access, the +`{{internal.windows_logins}}` variable can be used for local users, which maps +to any logins that are supplied when the user is created with +`tctl users add alice --windows-logins=Administrator,DBUser`. + +New clusters automatically populate the preset `access` role with the following: + +```yaml +allow: + windows_desktop_logins: ["{{internal.windows_logins}}"] +``` + +## Clipboard Access + +In order to a user to copy and paste between a remote desktop and their local +workstation, shared clipboard must be enabled for the user. The +`desktop_clipboard` role option defaults to enabled if unspecified. To disable +clipboard sharing for a Teleport user, ensure that they are assigned at least +one role that explicitly disables clipboard sharing: + +```yaml +desktop_clipboard: false +``` + +## Session Recording + +In order for a Teleport user's desktop sessions to be recorded, the following must +both be true: + +- Session recording is enabled (i.e. not set to `off`) on the cluster. This + setting resides in `teleport.yaml` under `auth_service.session_recording`, but + can also be configured dynamically via the cluster's + `session_recording_config` resource. +- The user's roles enable desktop session recording. + +By default, desktop session recording is considered enabled in Teleport roles +unless it is explicitly disabled: + +```yaml +record_sessions: + desktop: false +``` + +In order to disable desktop session recording for a user, _all_ of the user's +roles must disable it. In other words, the presence of a single role which +enables recording is enough to ensure sessions are recorded. \ No newline at end of file diff --git a/docs/pages/desktop-access/reference.mdx b/docs/pages/desktop-access/reference.mdx deleted file mode 100644 index e1a2dbd302a1f..0000000000000 --- a/docs/pages/desktop-access/reference.mdx +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: Desktop Access reference -description: Teleport Desktop Access configuration and CLI reference. ---- - - - Desktop Access is currently in Preview. Do not use this feature for any critical - infrastructure and keep a backup option for accessing your desktop hosts. - - -# Configuration and CLI reference - -## teleport.yaml - -`teleport.yaml` fields related to Desktop Access: - -{/* NOTE to devs: If you update this reference yaml, you likely want to mirror the changes in docs/pages/setup/reference/config.mdx */} - -```yaml -# Main service responsible for Desktop Access. -# -# You can have multiple Desktop Access services in your cluster (but not in the -# same teleport.yaml), connected to the same or different Active Directory -# domains. -(!docs/pages/includes/desktop-access/desktop-config.yaml!) -``` - -This `host_labels` configuration would apply the `environment: dev` label to a -Windows desktop named `test.dev.example.com`, and the `environment: prod` label -to a desktop named `desktop.prod.example.com`. - -## Deployment - -The Windows Desktop Service can be deployed in two modes. - -In *direct* mode, Windows Desktop Services registers directly with the Teleport -Auth Server, and listens for desktop connections from the Teleport Proxy. To -enable direct mode, set `windows_desktop_service.listen_addr` in -`teleport.yaml`, and ensure that `teleport.auth_servers` points directly at the -auth server. Direct mode requires network connectivity from the Teleport Proxy -to Windows Desktop Service, and from Windows Desktop Service to the auth server. - -In *IoT mode*, Windows Desktop Service only needs to be able to make an outbound -connection to a Teleport Proxy. The Windows Desktop Service establishes a -reverse tunnel to the proxy, and both registration with the auth server and -desktop sessions are performed over this tunnel. To enable this mode, ensure -that `windows_desktop_service.listen_addr` is *unset*, and point -`teleport.auth_servers` at a Teleport Proxy. - -## RBAC - -Teleport's Role-based access control (RBAC) allows administrators to set up -granular access policies for Windows desktops connected to Teleport. - -Teleport's "role" resource provides the following instruments for controlling -desktop access: - -```yaml -kind: role -version: v5 -metadata: - name: developer -spec: - options: - # Specify whether or not to record the user's desktop sessions. - # Desktop session recording is enabled if one or more of the user's - # roles has enabled recording. Defaults to true if unspecified. - # Desktop sessions will never be recorded if auth_service.session_recording - # is set to 'off' in teleport.yaml or if the cluster's session_recording_config - # resource has set 'mode: off'. - record_sessions: - desktop: true - - # Specify whether clipboard sharing should be allowed with the - # remote desktop (requires a supported browser). Defaults to true - # if unspecified. If one or more of the user's roles has disabled - # the clipboard, then it will be disabled. - desktop_clipboard: true - allow: - # Label selectors for desktops this role has access to. - # See above for how labels are applied to desktops. - windows_desktop_labels: - environment: ["dev", "stage"] - - # Windows user accounts this role can connect as. - windows_desktop_logins: ["Administrator", "{{internal.windows_logins}}"] -``` - -It is possible to use wildcards (`"*"`) to match all desktop labels. - -Like with SSH access, the `windows_desktop_logins` field supports the special -`{{internal.windows_logins}}` variable for local users which will map to any -logins that are supplied when the user is created with -`tctl users add alice --windows-logins=Administrator,DBUser`. - -For new clusters, the `access` role will have -`windows_desktop_logins: ["{{internal.windows_logins}}"]` set by default. - -## CLI - -CLI commands related to Desktop Access. - -Generate a join token for Desktop Access service: - -```sh -$ tctl nodes add --roles=WindowsDesktop -``` - -List registered Desktop Access services: - -```sh -$ tctl get windows_desktop_service -``` - -List registered Windows hosts in the domain: - -```sh -$ tctl get windows_desktop -``` diff --git a/docs/pages/desktop-access/reference/audit.mdx b/docs/pages/desktop-access/reference/audit.mdx new file mode 100644 index 0000000000000..e8ae7ec2b155f --- /dev/null +++ b/docs/pages/desktop-access/reference/audit.mdx @@ -0,0 +1,161 @@ +--- +title: Desktop Access Audit Events Reference +description: Audit events reference for Teleport Desktop Access. +--- + +# Desktop Access Audit Events Reference + +## windows.desktop.session.start (TDP00I/W) + +Emitted when a client successfully connects to a desktop, or when a connection +attempt fails due to access denied. + +Successful connection event: + +```json +{ + "addr.remote": "192.168.1.206:3389", + "cluster_name": "root", + "code": "TDP00I", + "desktop_addr": "192.168.1.206:3389", + "desktop_labels": { + "teleport.dev/computer_name": "WIN-I44F9TN11M3", + "teleport.dev/dns_host_name": "WIN-I44F9TN11M3.teleport.example.com", + "teleport.dev/is_domain_controller": "true", + "teleport.dev/origin": "dynamic", + "teleport.dev/os": "Windows Server 2012 R2 Standard Evaluation", + "teleport.dev/os_version": "6.3 (9600)", + "teleport.dev/windows_domain": "teleport.example.com" + }, + "ei": 0, + "event": "windows.desktop.session.start", + "login": "administrator", + "proto": "tdp", + "sid": "4a0ed655-1e0b-412b-b14a-348e840e7fa2", + "success": true, + "time": "2022-02-16T16:43:30.459Z", + "uid": "1605346b-d90b-4df7-8148-67a3e2d85673", + "user": "alice", + "windows_desktop_service": "316a3ffa-23e6-4d85-92a1-5e44754f8189", + "windows_domain": "teleport.example.com", + "windows_user": "administrator" +} +``` + +Access denied event: + +```json +{ + "addr.remote": "192.168.1.206:3389", + "cluster_name": "root", + "code": "TDP00W", + "desktop_addr": "192.168.1.206:3389", + "desktop_labels": { + "teleport.dev/computer_name": "WIN-I44F9TN11M3", + "teleport.dev/dns_host_name": "WIN-I44F9TN11M3.teleport.example.com", + "teleport.dev/is_domain_controller": "true", + "teleport.dev/origin": "dynamic", + "teleport.dev/os": "Windows Server 2012 R2 Standard Evaluation", + "teleport.dev/os_version": "6.3 (9600)", + "teleport.dev/windows_domain": "teleport.example.com" + }, + "ei": 0, + "error": "access to desktop denied", // Connection error + "event": "windows.desktop.session.start", + "message": "access to desktop denied", // Detailed error message. + "login": "administrator", + "proto": "tdp", + "sid": "4a0ed655-1e0b-412b-b14a-348e840e7fa2", + "success": false, // Indicates unsuccessful connection + "time": "2022-02-16T16:43:30.459Z", + "uid": "1605346b-d90b-4df7-8148-67a3e2d85673", + "user": "alice", + "windows_desktop_service": "316a3ffa-23e6-4d85-92a1-5e44754f8189", + "windows_domain": "teleport.example.com", + "windows_user": "administrator" +} +``` + +## windows.desktop.session.end (TDP01I) + +Emitted when a client disconnects from the desktop. + +```json +{ + "cluster_name": "root", + "code": "TDP01I", + "desktop_addr": "192.168.1.206:3389", + "desktop_labels": { + "teleport.dev/computer_name": "WIN-I44F9TN11M3", + "teleport.dev/dns_host_name": "WIN-I44F9TN11M3.teleport.example.com", + "teleport.dev/is_domain_controller": "true", + "teleport.dev/origin": "dynamic", + "teleport.dev/os": "Windows Server 2012 R2 Standard Evaluation", + "teleport.dev/os_version": "6.3 (9600)", + "teleport.dev/windows_domain": "teleport.example.com" + }, + "desktop_name": "WIN-I44F9TN11M3-teleport-example-com", + "ei": 0, + "event": "windows.desktop.session.end", + "login": "administrator", + "participants": [ + "alice" + ], + "recorded": true, + "session_start": "2022-02-16T16:43:30.459Z", + "session_stop": "2022-02-16T16:46:50.894Z", + "sid": "4a0ed655-1e0b-412b-b14a-348e840e7fa2", + "time": "2022-02-16T16:46:50.895Z", + "uid": "c7956a81-597f-4452-90d7-800506f7a05b", + "user": "alice", + "windows_desktop_service": "316a3ffa-23e6-4d85-92a1-5e44754f8189", + "windows_domain": "teleport.example.com", + "windows_user": "administrator" +} +``` + +## desktop.clipboard.send (TDP02I) + +Emitted when clipboard data is sent from a user's workstation to Teleport. In +order to avoid capturing sensitive data, the event only records the number of +bytes that were sent. + +```json +{ + "addr.remote": "192.168.1.206:3389", + "cluster_name": "root", + "code": "TDP02I", + "desktop_addr": "192.168.1.206:3389", + "ei": 0, + "event": "desktop.clipboard.send", + "length": 4, // number of bytes sent + "proto": "tdp", + "sid": "4a0ed655-1e0b-412b-b14a-348e840e7fa2", + "time": "2022-02-16T16:43:40.010217Z", + "uid": "e45d9890-38a9-4580-8572-35fa0192b123", + "user": "alice" +} +``` + +## desktop.clipboard.receive (TDP03I) + +Emitted when Teleport receives clipboard data from a remote desktop. In order to +avoid capturing sensitive data, the event only records the number of bytes that +were recieved. + +```json +{ + "addr.remote": "192.168.1.206:3389", + "cluster_name": "root", + "code": "TDP03I", + "desktop_addr": "192.168.1.206:3389", + "ei": 0, + "event": "desktop.clipboard.receive", + "length": 4, // number of bytes received + "proto": "tdp", + "sid": "4a0ed655-1e0b-412b-b14a-348e840e7fa2", + "time": "2022-02-16T16:43:40.010217Z", + "uid": "e45d9890-38a9-4580-8572-35fa0192b123", + "user": "alice" +} +``` diff --git a/docs/pages/desktop-access/reference/cli.mdx b/docs/pages/desktop-access/reference/cli.mdx new file mode 100644 index 0000000000000..a0c46de18d583 --- /dev/null +++ b/docs/pages/desktop-access/reference/cli.mdx @@ -0,0 +1,24 @@ +--- +title: Desktop Access CLI Reference +description: CLI reference for Teleport Desktop Access. +--- + +# Desktop Access CLI Reference + +Generate a join token for a Windows Desktop Service: + +```sh +$ tctl nodes add --roles=WindowsDesktop +``` + +List registered Windows Desktop Services: + +```sh +$ tctl get windows_desktop_service +``` + +List registered Windows desktops: + +```sh +$ tctl get windows_desktop +``` \ No newline at end of file diff --git a/docs/pages/desktop-access/reference/configuration.mdx b/docs/pages/desktop-access/reference/configuration.mdx new file mode 100644 index 0000000000000..976d65e89d748 --- /dev/null +++ b/docs/pages/desktop-access/reference/configuration.mdx @@ -0,0 +1,36 @@ +--- +title: Desktop Access Configuration Reference +description: Configuration reference for Teleport Desktop Access. +--- + +# Windows Desktop Service configuration + +`teleport.yaml` fields related to Desktop Access: + +```yaml +# Main service responsible for Desktop Access. +# +# You can have multiple Desktop Access services in your cluster (but not in the +# same teleport.yaml), connected to the same or different Active Directory +# domains. +(!docs/pages/includes/desktop-access/desktop-config.yaml!) +``` + +## Deployment + +The Windows Desktop Service can be deployed in two modes. + +In *direct* mode, Windows Desktop Services registers directly with the Teleport +Auth Server, and listens for desktop connections from the Teleport Proxy. To +enable direct mode, set `windows_desktop_service.listen_addr` in +`teleport.yaml`, and ensure that `teleport.auth_servers` points directly at the +auth server. Direct mode requires network connectivity from the Teleport Proxy +to Windows Desktop Service, and from Windows Desktop Service to the auth server. + +In *IoT mode*, Windows Desktop Service only needs to be able to make an outbound +connection to a Teleport Proxy. The Windows Desktop Service establishes a +reverse tunnel to the proxy, and both registration with the auth server and +desktop sessions are performed over this tunnel. To enable this mode, ensure +that `windows_desktop_service.listen_addr` is *unset*, and point +`teleport.auth_servers` at a Teleport Proxy. + diff --git a/docs/pages/desktop-access/troubleshooting.mdx b/docs/pages/desktop-access/troubleshooting.mdx index bd0018b75f7db..ef5831cf36e27 100644 --- a/docs/pages/desktop-access/troubleshooting.mdx +++ b/docs/pages/desktop-access/troubleshooting.mdx @@ -3,14 +3,6 @@ title: Troubleshooting Desktop Access description: Common issues and resolutions for Teleport's Desktop Access --- - - Desktop Access is currently in Preview. Do not use this feature for any critical - infrastructure and keep a backup option for accessing your desktop hosts. - - Common issues and resolution steps. ## Auto-login does not work