From 1283425b60ec5f60d509ba4c791183d452923ff7 Mon Sep 17 00:00:00 2001 From: Przemko Robakowski Date: Tue, 25 Aug 2026 15:37:38 +0000 Subject: [PATCH] Linux desktop access documentation (#490) Export-Source-Commit: 64bc963663f614d8c1ff7fe5c4105774c23b76fe --- docs/cspell.json | 2 + .../desktop-access/desktop-access.mdx | 31 +- .../desktop-access/introduction.mdx | 15 +- .../desktop-access/linux-desktop.mdx | 285 ++++++++++++++++++ .../enroll-resources/desktop-access/rbac.mdx | 68 ++++- .../reference/configuration.mdx | 13 +- .../linux-desktop-config.yaml | 20 ++ docs/pages/includes/role-spec.mdx | 6 +- .../pages/reference/access-controls/roles.mdx | 6 +- 9 files changed, 423 insertions(+), 23 deletions(-) create mode 100644 docs/pages/enroll-resources/desktop-access/linux-desktop.mdx create mode 100644 docs/pages/includes/config-reference/linux-desktop-config.yaml diff --git a/docs/cspell.json b/docs/cspell.json index 86db9df7e83..462cdf97ea2 100644 --- a/docs/cspell.json +++ b/docs/cspell.json @@ -1188,8 +1188,10 @@ "xgmx", "xlarge", "xlink", + "xorg", "xoxb", "xpack", + "xsessions", "ykman", "yourcompany", "yourdatabase", diff --git a/docs/pages/enroll-resources/desktop-access/desktop-access.mdx b/docs/pages/enroll-resources/desktop-access/desktop-access.mdx index edb9d0f21b8..119955b6733 100644 --- a/docs/pages/enroll-resources/desktop-access/desktop-access.mdx +++ b/docs/pages/enroll-resources/desktop-access/desktop-access.mdx @@ -1,6 +1,6 @@ --- -title: Windows Desktops -description: Protect Windows Resources with Teleport's passwordless access and other features. +title: Desktop Access +description: Protect Windows and Linux desktop resources with Teleport's passwordless access and other features. sidebar_position: 7 template: doc-page page_type: landing @@ -19,11 +19,12 @@ import slidersHorizontalSvg from "@site/src/components/Icon/svg/sliders-horizont import keyholeSvg from "@site/src/components/Icon/svg/keyhole.svg"; import activeDirectorySvg from "@site/src/components/Icon/svg/active-directory.svg"; import windowsSvg from "@site/src/components/Icon/svg/windows2.svg"; +import linuxSvg from "@site/src/components/Icon/svg/linux.svg"; import windowsDesktopsSvg from "@site/src/components/Icon/teleport-svg/windows-desktops.svg"; import folderNotchOpenSvg from "@site/src/components/Icon/svg/folder-notch-open.svg"; -Provide secure, passwordless access to Microsoft Windows desktops and servers, backed by short-lived certificates, role-based access controls, clipboard and directory sharing, session recordings, and detailed audit logs. +Provide secure, passwordless access to Windows and Linux desktops, backed by short-lived certificates, role-based access controls, clipboard and directory sharing, session recordings, and detailed audit logs. {/*vale messaging.protocol-products = NO*/} {/*vale messaging.protocol-products = YES*/} diff --git a/docs/pages/enroll-resources/desktop-access/introduction.mdx b/docs/pages/enroll-resources/desktop-access/introduction.mdx index b1b8f3ab233..99fd6a1d36e 100644 --- a/docs/pages/enroll-resources/desktop-access/introduction.mdx +++ b/docs/pages/enroll-resources/desktop-access/introduction.mdx @@ -1,7 +1,7 @@ --- -title: Manage Access to Windows Resources +title: Manage Access to Desktop Resources sidebar_label: Introduction -description: Demonstrates how you can manage access to Windows desktops with Teleport. +description: Demonstrates how you can manage access to Windows and Linux desktops with Teleport. videoBanner: n2h0GisWdss tags: - conceptual @@ -11,14 +11,14 @@ page_type: conceptual --- You can configure Teleport to provide secure, passwordless access to Microsoft -Windows desktops and servers. For Windows, Teleport provides the following key +Windows and Linux desktops and servers. Teleport provides the following key features: -- Passwordless access to Windows hosts backed by secure cryptographic +- Passwordless access to desktop hosts backed by secure cryptographic authentication and short-lived certificates. - Configurable role-based access controls (RBAC) for groups of hosts and users. - Configurable clipboard and directory sharing for copying and pasting to and - from remote Windows hosts. + from remote desktop hosts. - Session recording for all desktop activity. - Audit logs that track user activity. @@ -71,11 +71,12 @@ ability to create users on-demand. The lack of automatic LDAP-based discovery and the requirement to install software on each host makes this approach less attractive for large environments. -For more information about configuring basic access using Teleport Windows -Desktop Service, see the following topics: +For more information about configuring basic access using Teleport Desktop +Services, see the following topics: - [Configure access for local Windows users](./getting-started.mdx) - [Configure access for Active Directory](./active-directory.mdx) +- [Configure access for Linux desktops](./linux-desktop.mdx) ## Further reading diff --git a/docs/pages/enroll-resources/desktop-access/linux-desktop.mdx b/docs/pages/enroll-resources/desktop-access/linux-desktop.mdx new file mode 100644 index 00000000000..d5ff5c508b3 --- /dev/null +++ b/docs/pages/enroll-resources/desktop-access/linux-desktop.mdx @@ -0,0 +1,285 @@ +--- +title: Configure Access for Linux Desktops +sidebar_label: Linux Desktop Access +description: Use Teleport to configure secure, audited access to Linux desktops running X11 desktop environments. +tags: + - how-to + - zero-trust + - infrastructure-identity +--- + +This guide demonstrates how to configure Teleport to provide secure, audited access +to Linux desktops running X11 desktop environments. + +## How it works + +The Teleport Linux Desktop Service runs directly on the Linux host you want to access. +When a user connects, the service starts a virtual X11 display using +[Xvfb](https://www.x.org/releases/X11R7.6/doc/man/man1/Xvfb.1.xhtml) (X virtual +framebuffer) and launches the user's chosen desktop environment inside it. + +The Linux Desktop Service establishes a reverse tunnel to the Teleport Proxy Service, +so only a single outbound connection from the host is required—no inbound firewall +rules are needed. + +Available desktop sessions are discovered from `.desktop` files in +`/usr/share/xsessions`. You can restrict which sessions are offered using the +`xsessions.included` and `xsessions.excluded` filters in the service configuration. + +## Prerequisites + +To complete the steps in this guide, verify your environment meets the following requirements: + +(!docs/pages/includes/edition-prereqs-tabs.mdx!) + +- A Linux host running an X11-compatible desktop environment with session definitions + in `/usr/share/xsessions`. + +- **Xvfb** installed on the Linux host. Xvfb provides the virtual framebuffer that + Teleport uses to render the desktop. Install it with your distribution's package + manager: + + + + + ```code + $ sudo apt-get install xvfb + ``` + + + + + ```code + $ sudo dnf install xorg-x11-server-Xvfb + ``` + + + + + Verify that `Xvfb` is available in `PATH`: + + ```code + $ sudo -i which Xvfb + ``` + +- (!docs/pages/includes/tctl.mdx!) + +## Step 1/3. Configure the Linux Desktop Service + +The Linux Desktop Service runs on the Linux host that users will connect to. + +To configure the Linux Desktop Service: + +1. Sign in to the Teleport cluster from your administrative workstation. + +1. Generate an invitation token for the Linux Desktop Service: + + ```code + $ tctl tokens add --type=linux_desktop --format=text > /tmp/token + ``` + + Copy `/tmp/token` to the target Linux host + +1. Verify that Teleport is installed on the Linux host: + + ```code + $ teleport version + ``` + + If Teleport isn't installed, follow the appropriate [Installation + instructions](../../installation/single-machine/linux.mdx) for your environment. + +1. Configure `/etc/teleport.yaml` on the Linux host: + + ```yaml + version: v3 + teleport: + nodename: + proxy_server: :443 + auth_token: "/tmp/token" + linux_desktop_service: + enabled: true + + auth_service: + enabled: false + proxy_service: + enabled: false + ssh_service: + enabled: false + ``` + + Set `proxy_server` to the address of your Teleport cluster. + +1. (Optional) Add labels to the Linux Desktop Service. Labels are used to control + which users can connect to this host. + + ```diff + version: v3 + teleport: + nodename: + proxy_server: :443 + auth_token: "/tmp/token" + linux_desktop_service: + enabled: true + + labels: + + datacenter: us-east + + env: production + ``` + +1. (Optional) Filter the desktop sessions available to users. Teleport discovers + available session types from `.desktop` files in `/usr/share/xsessions`. You + can restrict which sessions are offered using regular expressions matched against + the session name (the filename without the `.desktop` extension): + + ```diff + linux_desktop_service: + enabled: true + + xsessions: + + # Only expose GNOME, KDE, and XFCE sessions. + + included: "^(gnome|kde|xfce4)$" + + # Exclude classic or fallback variants. + + excluded: ".*-classic$" + ``` + + The `included` pattern is applied first. If set, only sessions whose name + matches the pattern are offered. The `excluded` pattern is applied next and + removes sessions whose name matches it. + +1. (!docs/pages/includes/start-teleport.mdx service="the Teleport Linux Desktop Service"!) + + + Here are some troubleshooting tips: + + - Check the service status: + + ```code + $ systemctl status teleport + ``` + + - Review logs for connection errors: + + ```code + $ sudo journalctl -u teleport + ``` + + - Verify that `Xvfb` is available in `PATH`: + + ```code + $ sudo -i which Xvfb + ``` + + If the command returns no output, Xvfb is not installed. See the Prerequisites + section above for installation instructions. + + - Confirm that at least one `.desktop` file exists in `/usr/share/xsessions`: + + ```code + $ ls /usr/share/xsessions/ + ``` + + - Ensure the token hasn't expired (tokens are valid for 60 minutes by default). + + + +## Step 2/3. Configure a role for Linux desktop access + +To access a Linux desktop, a Teleport user must have a role that grants the +appropriate permissions. + +To configure a role for Linux desktop access: + +1. Sign in to the Teleport cluster from your administrative workstation. + +1. Create a `linux-desktop-admins.yaml` file to define a new role: + + ```yaml + kind: role + version: v6 + metadata: + name: linux-desktop-admins + spec: + allow: + linux_desktop_labels: + "*": "*" + linux_desktop_logins: ["alice"] + ``` + + In this file: + + - Set `linux_desktop_labels` to specify which Linux desktops users assigned + to this role can access. Use `"*": "*"` to allow access to all desktops, or + specify labels to restrict access to desktops with matching labels. + - Set `linux_desktop_logins` to the Linux user accounts that members of this + role can connect as. The specified user must already exist on the Linux host. + +1. Apply the new role to your cluster: + + ```code + $ tctl create -f linux-desktop-admins.yaml + ``` + + (!docs/pages/includes/create-role-using-web.mdx!) + +1. (\!docs/pages/includes/add-role-to-user.mdx role="linux-desktop-admins" \!) + +## Step 3/3. Connect + +Now that the Linux Desktop Service is running and a role has been configured, you +can connect to the Linux desktop from the Teleport Web UI or Teleport Connect. + +To connect to a Linux desktop: + +1. Sign in to the Teleport cluster using an account assigned the + `linux-desktop-admins` role. + +1. Select **Resources**. + +1. Click **Type**, then select **Desktops**. + +1. Click **Connect** for the Linux desktop you want to access, then select the + Linux user account to use for the connection. + + Teleport opens a remote desktop connection and starts recording the desktop + session. When you are finished, click the **More items** menu, then click + **Disconnect**. + + To view the recording, select **Audit** in the Teleport Web UI, then click + **Session Recordings**. + + + Here are some troubleshooting tips: + + - Ensure your Teleport user is assigned the `linux-desktop-admins` role (or an + equivalent role with Linux desktop permissions). + + - Verify that the Linux user account you selected exists on the host. + + - Confirm that Xvfb is installed and in `PATH` on the Linux host. + + - Check that at least one session type is available after applying your + `xsessions` filters: review `/usr/share/xsessions/` and compare against + the `included`/`excluded` patterns in your configuration. + + - If the connection fails, review the Linux Desktop Service logs on the host: + + ```code + $ sudo journalctl -u teleport + ``` + + + +## Next steps +{/* vale messaging.protocol-products = NO */} +- To learn more about controlling who can access which desktops, see + [Role-Based Access Control for Desktops](./rbac.mdx). +- To configure session recording options, see + [Session Recording and Playback](reference/sessions.mdx). +- For a full list of `linux_desktop_service` configuration options, see the + [Desktop Access Configuration Reference](reference/configuration.mdx). +{/* vale messaging.protocol-products = YES */} \ No newline at end of file diff --git a/docs/pages/enroll-resources/desktop-access/rbac.mdx b/docs/pages/enroll-resources/desktop-access/rbac.mdx index bbf3e4d616f..01237e8fc50 100644 --- a/docs/pages/enroll-resources/desktop-access/rbac.mdx +++ b/docs/pages/enroll-resources/desktop-access/rbac.mdx @@ -13,7 +13,7 @@ This page describes the capabilities that Teleport provides for managing role-based access controls for protected remote desktops. Teleport's RBAC allows administrators to set up granular access policies for -Windows desktops connected to Teleport. +Windows and Linux desktops connected to Teleport. Teleport's `role` resource provides the following options for controlling desktop access: @@ -48,16 +48,23 @@ spec: # Specify whether local users should be created automatically at connection # time. By default, this feature is disabled, and the user must already exist. - # Note: this is applicable to local users only and is not supported in Active - # Directory environments. + # Note: this is applicable to local Windows users only and is not supported in + # Active Directory environments. create_desktop_user: true allow: - # Label selectors for desktops this role has access to. + # Label selectors for Windows 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}}"] + + # Label selectors for Linux desktops this role has access to. + linux_desktop_labels: + environment: ["dev", "stage"] + + # Linux user accounts this role can connect as. + linux_desktop_logins: ["alice", "{{internal.linux_desktop_logins}}"] ``` @@ -211,8 +218,43 @@ windows_desktop_service: In this example, all hosts in the Engineering OU would have `team: engineering` while the hosts in the Sales OU would have `team: sales`. +## Linux Desktop Labeling + +Both `allow` and `deny` rules support `linux_desktop_labels` selectors. These +selectors are matched against the labels set on the Linux desktop resource. +Wildcards (`"*"`) can be used to match all label values. + +Linux desktops acquire labels from the `labels` field in the +`linux_desktop_service` section of the Teleport configuration file on the host: + +```yaml +linux_desktop_service: + enabled: true + labels: + environment: dev + datacenter: us-east +``` + +These labels are then used in role `allow` and `deny` rules: + +```yaml +allow: + # Allow access to all Linux desktops in the dev environment. + linux_desktop_labels: + environment: dev +``` + +```yaml +deny: + # Deny access to production Linux desktops. + linux_desktop_labels: + environment: prod +``` + ## Logins +### Windows logins + The `windows_desktop_logins` role setting lists the Windows user accounts that the role permits access to. For local users, the `{{internal.windows_logins}}` variable can be used as a placeholder for the user's `windows_logins` trait. The @@ -226,6 +268,24 @@ allow: windows_desktop_logins: ["{{internal.windows_logins}}"] ``` +### Linux logins + +The `linux_desktop_logins` role setting lists the Linux user accounts that the +role permits access to. The specified accounts must already exist on the Linux +host. The `{{internal.linux_desktop_logins}}` variable can be used as a placeholder for +the user's `linux_desktop_logins` trait. The `linux_desktop_logins` trait can be specified when +the user is created: + +```code +$ tctl users add alice --linux-desktop-logins=alice,admin +``` + +Or updated for an existing user: + +```code +$ tctl users update alice --set-linux-desktop-logins=alice,admin +``` + ## Clipboard Access In order for a user to copy and paste between a remote desktop and their local diff --git a/docs/pages/enroll-resources/desktop-access/reference/configuration.mdx b/docs/pages/enroll-resources/desktop-access/reference/configuration.mdx index 044ef93c5c5..9aa513e3d09 100644 --- a/docs/pages/enroll-resources/desktop-access/reference/configuration.mdx +++ b/docs/pages/enroll-resources/desktop-access/reference/configuration.mdx @@ -12,8 +12,19 @@ page_type: reference This page lists the Teleport configuration fields that you can use to configure the Teleport Desktop Service. +`teleport.yaml` fields for the Linux Desktop Service: + ```yaml -# Main service responsible for desktop access. +# Service responsible for Linux desktop access. +# The Linux Desktop Service runs directly on the Linux host being accessed +# and requires Xvfb to be installed on that host. +(!docs/pages/includes/config-reference/linux-desktop-config.yaml!) +``` + +`teleport.yaml` fields for the Windows Desktop Service: + +```yaml +# Main service responsible for Windows desktop access. # # You can have multiple Desktop Service instances in your cluster (but not in the # same teleport.yaml), connected to the same or different Active Directory diff --git a/docs/pages/includes/config-reference/linux-desktop-config.yaml b/docs/pages/includes/config-reference/linux-desktop-config.yaml new file mode 100644 index 00000000000..7a17ad78a4f --- /dev/null +++ b/docs/pages/includes/config-reference/linux-desktop-config.yaml @@ -0,0 +1,20 @@ +linux_desktop_service: + enabled: true + + # (optional) Labels to attach to this Linux Desktop Service instance. + labels: + "env": "staging" + + # (optional) Filters for available X sessions. + # X session types are discovered from .desktop files in /usr/share/xsessions. + # The filter patterns are Go regular expressions matched against the filename + # of each .desktop file, without the .desktop extension. + # For example, a file named "gnome.desktop" is matched as "gnome". + xsessions: + # (optional) Only expose X sessions whose name matches this pattern. + # If unset, all sessions are included (subject to excluded below). + included: "^(gnome|kde|xfce4)$" + + # (optional) Exclude X sessions whose name matches this pattern. + # Applied after included. If unset, no sessions are excluded. + excluded: ".*-classic$" diff --git a/docs/pages/includes/role-spec.mdx b/docs/pages/includes/role-spec.mdx index aac6a76fef6..734d79c6ad3 100644 --- a/docs/pages/includes/role-spec.mdx +++ b/docs/pages/includes/role-spec.mdx @@ -145,9 +145,12 @@ spec: # both strings and template variables are supported in this field logins: [root, '{{internal.logins}}'] - # Windows logins a user is allowed to use for desktop sessions. + # Windows logins a user is allowed to use for Windows desktop sessions. windows_desktop_logins: [Administrator, '{{internal.logins}}'] + # Linux desktop logins a user is allowed to use for Linux desktop sessions. + linux_desktop_logins: [root, '{{internal.linux_desktop_logins}}'] + # node_labels: a user with this role will be allowed to connect to # SSH nodes with labels matching below. node_labels: @@ -342,6 +345,7 @@ spec: db_labels_expression: 'labels["env"] == "staging"' db_service_labels_expression: 'labels["env"] == "staging"' windows_desktop_labels_expression: 'labels["env"] == "staging"' + linux_desktop_labels_expression: 'labels["env"] == "staging"' group_labels_expression: 'labels["env"] == "staging"' workload_identity_labels_expression: 'labels["env"] == "staging"' beam_labels_expression: 'labels["env"] == "staging"' diff --git a/docs/pages/reference/access-controls/roles.mdx b/docs/pages/reference/access-controls/roles.mdx index a4cacddd96e..a367400cd83 100644 --- a/docs/pages/reference/access-controls/roles.mdx +++ b/docs/pages/reference/access-controls/roles.mdx @@ -275,6 +275,7 @@ conditions: - `db_labels_expression` - `db_service_labels_expression` - `windows_desktop_labels_expression` +- `linux_desktop_labels_expression` - `group_labels_expression` - `workload_identity_labels_expression` - `beam_labels_expression` @@ -878,7 +879,8 @@ Labels for resources enrolled with Teleport: |`db_service_labels`|[Database Service](../../enroll-resources/database-access/database-access.mdx) instances| |`kubernetes_labels`|[Kubernetes clusters](../../enroll-resources/kubernetes-access/controls.mdx)| |`node_labels`|[SSH Servers](../../enroll-resources/server-access/server-access.mdx)| -|`windows_desktop_labels`|[Windows desktops](../../enroll-resources/server-access/server-access.mdx)| +|`windows_desktop_labels`|[Windows desktops](../../enroll-resources/desktop-access/desktop-access.mdx)| +|`linux_desktop_labels`|[Linux desktops](../../enroll-resources/desktop-access/linux-desktop.mdx)| |`workload_identity_labels`|[Workload Identities](../machine-workload-identity/workload-identity/workload-identity-resource.mdx)| |`beam_labels`|Beams| @@ -896,6 +898,7 @@ Principals a user can assume on infrastructure resources: - `kubernetes_users` - `logins` - `windows_desktop_logins` +- `linux_desktop_logins` Teleport principals that a user can impersonate: - `impersonate.roles` @@ -931,6 +934,7 @@ sign-on provider. |`{{internal.kubernetes_users}}`|List of allowed Kubernetes users for the user.| |`{{internal.logins}}` | Substituted with a value stored in Teleport's local user database and logins from a root cluster.

For local users, Teleport will substitute this with the "allowed logins" parameter used in the `tctl users add [user] ` command.

If the role is within a leaf cluster in a [trusted cluster](../../zero-trust-access/management/trustedclusters.mdx), Teleport will substitute the logins from the root cluster whether the user is a local user or from an SSO provider.

As an example, if the user has the `ubuntu` login in the root cluster, then `ubuntu` will be substituted in the leaf cluster with this variable. | |`{{internal.windows_logins}}`|List of allowed Windows logins for the user.| +|`{{internal.linux_desktop_logins}}`|List of allowed Linux desktop logins for the user.| |`{{external.xyz}}` | Substituted with a value from an external [SSO provider](https://en.wikipedia.org/wiki/Single_sign-on). If using SAML, this will be expanded with "xyz" assertion value. For OIDC, the variable is expanded to the value of the "xyz" claim. See the next section for more information on referring to the `external` variable in Teleport roles. | #### Referring to internal traits in Teleport roles