Role-Based Access Control for Desktops

Teleport's RBAC allows administrators to set up granular access policies for Windows desktops connected to Teleport.

Teleport's role resource provides the following options for controlling desktop access:

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_session:
      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

    # 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.
    create_desktop_user: 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}}"]

For a full Teleport role reference, including information on how Teleport expands the internal and external traits, see the Teleport Access Controls Reference.

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:

• Using the host_labels rules defined in the windows_desktop_service section of your Teleport configuration file.
• Using LDAP (for desktops discovered via LDAP only)

Using host_labels

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:

host_labels:
  - match: '^.*\.dev\.example\.com'
    labels:
      environment: dev
  - match: '^.*\.prod\.example\.com'
    labels:
      environment: prod

The regular expression provided in the match rule above is applied to the desktop's name for desktops that are discovered via LDAP. Hosts that are statically defined (in the hosts or non_ad_hosts sections of your configuration) receive an auto-generated name, so host label matching applies against the desktop's addr in these cases.

Static hosts

A static host definition of 192.168.1.105 would result in the following resource:

kind: windows_desktop
metadata:
  expires: "2023-05-01T15:47:21.564561Z"
  id: 1682955441565783000
  labels:
    teleport.dev/ad: "true"
    teleport.dev/origin: config-file
  name: 3362ad10b55d-static-192-168-1-105
spec:
  addr: 192.68.1.105:3389
  domain: example.com
  host_id: 307e091b-7f6b-42e0-b78d-3362ad10b55d
  non_ad: false
version: v3

In this case, the regular expression is evaluated against 192.68.1.105:3389.

Discovered hosts

For hosts that are discovered via LDAP (or created by API), the regular expression is evaluated against the name.

kind: windows_desktop
metadata:
  expires: "2023-05-01T15:47:36.677008Z"
  id: 1682955456680526000
  labels:
    teleport.dev/computer_name: EC2AMAZ-37TSM4L
    teleport.dev/dns_host_name: EC2AMAZ-37TSM4L.example.com
    teleport.dev/is_domain_controller: "true"
    teleport.dev/origin: dynamic
    teleport.dev/os: Windows Server 2019 Datacenter
    teleport.dev/os_version: 10.0 (17763)
    teleport.dev/ou: OU=Domain Controllers,DC=example,DC=com
    teleport.dev/windows_domain: example.com
  name: EC2AMAZ-37TSM4L-example-com
spec:
  addr: 172.31.9.146:3389
  domain: example.com
  host_id: 307e091b-7f6b-42e0-b78d-3362ad10b55d
  non_ad: false
version: v3

In this case, the regular expression is evaluated against EC2AMAZ-37TSM4L-example-com.

Using LDAP

The Teleport Desktop Service can automatically discover Windows Desktops and register them with the Teleport Cluster by periodically querying an LDAP server. There are several ways that these desktops can be labeled:

Teleport applies the following labels automatically to all desktops discovered via LDAP:

Additionally, users can configure LDAP attributes which will be converted into Teleport labels. For example, consider the following Desktop Service configuration:

discovery:
  label_attributes:
    - location

For a desktop with a location attribute of Oakland, Teleport would apply a label with key ldap/location and value Oakland.

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 windows_logins trait can be specified 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:

allow:
  windows_desktop_logins: ["{{internal.windows_logins}}"]

Automatic User Creation

Teleport's Desktop Service can be configured to automatically create local Windows users upon login.

Configuration

This feature is disabled by default, and can be enabled by setting the create_desktop_user role option on one of the user's roles.

kind: role
version: v7
metadata:
  name: allow-user-provisioning
spec:
  options:
    create_desktop_user: true
  allow:
    windows_desktop_labels: { '*': '*' }
    windows_desktop_logins: jane

When a Teleport user connects to a desktop, Teleport checks each of the user's roles that match the desktop. If at least one role matches the desktop but does not include create_desktop_user: true, automatic user creation will be disabled. Roles that do not match the desktop's labels will not be checked.

In order to create the user, the requested username must be present in one of the role's windows_desktop_logins.

User management

By default, the newly-created user will be placed in two Windows groups:

• Remote Desktop Users: a built-in Windows group allowing remote desktop access
• Teleport Users: a custom group that Teleport places all automatically-created users in

To add the user to additional groups, specify the desktop_groups role option:

kind: role
version: v7
metadata:
  name: allow-user-provisioning
spec:
  options:
    create_desktop_user: true
  allow:
    windows_desktop_labels: { '*': '*' }
    windows_desktop_logins: jane
    desktop_groups:
    - developers
    # to make the newly-created user an administrator
    - Administrators
    # IdP trait templating is also supported
    - '{{external.desktop_groups}}'

Teleport will never delete users that are created via automatic user provisioning. This ensures that the user's profile is preserved for future logins. Teleport will disable the account when the session completes (and automatically re-enable it on future connection attempts). This ensures that user accounts created by Teleport can only be accessed via Teleport.

Clipboard Access

In order for a user to copy and paste between a remote desktop and their local workstation, clipboard sharing 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:

desktop_clipboard: false

Directory Sharing

A Teleport user can share a directory on their local workstation with a remote desktop using Directory Sharing.

A Teleport role enables Directory Sharing by default. If one of a user's Teleport roles disables Directory Sharing, then Directory Sharing will be disabled for that user.

To disable Directory Sharing for a Teleport user, define a role similar to the following in a file called role.yaml:

kind: role
version: v5
metadata:
  name: "no-sharing"
spec:
  options:
    desktop_directory_sharing: 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:

record_session:
  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.