Teleport

Desktop Access Directory Sharing

Available for:
OpenSource
Team
Cloud
Enterprise

Directory Sharing is a Teleport feature of that makes it easy to move files between a local machine and a remote desktop—and apply changes to those files—without compromising security.

During a remote desktop session, you can select a folder on your local workstation to share with the remote desktop. Changes to the folder on either the remote desktop or your workstation are reflected on both machines for the duration of the session.

The shared directory makes it convenient to download log files, edit configuration files, or perform any other file manipulations on a remote Windows desktop. You can disable Directory Sharing for specific users via their Teleport roles, and use session recording to audit activity in the shared directory after the session ends.

Prerequisites

A running Teleport cluster. For details on how to set this up, see the Getting Started guide.
The tctl admin tool and tsh client tool version >= 14.0.1.

See Installation for details.

A Teleport Team account. If you don't have an account, sign up to begin your free trial.
The Enterprise tctl admin tool and tsh client tool, version >= 13.3.9.

You can download these tools from the Cloud Downloads page.

A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.
The Enterprise tctl admin tool and tsh client tool version >= 14.0.1.

You can download these tools by visiting your Teleport account workspace.

Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.

To check version information, run the tctl version and tsh version commands. For example:

tctl version
Teleport Enterprise v13.3.9 git:api/14.0.0-gd1e081e go1.21

tsh version
Teleport v13.3.9 go1.21
Proxy version: 13.3.9Proxy: teleport.example.com

The Teleport Desktop Service with at least one remote desktop registered in your cluster. If you have not yet configured Desktop Access, read Getting Started with Desktop Access before beginning this guide.
A browser on your local machine that supports the File System Access API, which Teleport uses for Directory Sharing. We support the latest versions of Chromium-based browsers like Google Chrome, Brave, and Microsoft Edge.

Brave users can enable the File System Access API by navigating to brave://flags/#file-system-access-api and selecting "Enable".

You can see a full compatibility table in the Mozilla Developer Network documentation.
To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands on your administrative workstation using your current credentials. For example:
```
tsh login --proxy=teleport.example.com --user=[email protected]
tctl status
Cluster  teleport.example.com
Version  14.0.1
CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
```
If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

To share a directory, open the Teleport Web UI and begin a desktop session by navigating to the "Desktops" tab on the sidebar, finding a desktop you want to connect to, and clicking "CONNECT".

Once the session starts, click the three-dot menu on the top-right of the screen and click "Share Directory":

Prohibited directories

For security reasons the web browser's filesystem access API prohibits you from sharing certain directories, including the standard locations for commonly used user directories such as "Desktop" and "Documents", as well as critical directories more typically used by the operating system itself.

For a full list of the blocked user directories, see the File System Access Specification.

Subdirectories within these blocked user directories may still be shared.

Long directory names

Based on testing, we have determined that directory sharing leads to unexpected errors if you share directories whose names (including all path segments) have 640 characters or more.

When you first share a directory, your browser will prompt you to allow it to make changes in the directory, and you will need to grant these permissions to enable directory sharing.

After you grant permissions, you will see a new directory in File Explorer on the remote desktop. The directory will have the same name as the directory on your local machine, but with "on teleport" appended to the name.

You can only share a single directory at a time.

Step 2/4. Edit files in your directory

You can easily share files—and file modifications—between your local machine and the remote desktop.

Editing on the remote side

When you create, edit, or delete a file in the shared directory on the remote side, your browser will apply those changes to the directory on your local machine.

If you move a file into the shared directory on the remote side, that file will appear on the local side as well. And if you move a file outside the directory on the remote side, the remote desktop will copy it, keeping it within the shared directory.

You can also copy a file from one subdirectory within the shared directory and paste it into another—the local side will reflect the changes.

Directory Sharing does not support moving files between subdirectories within the shared directory on the remote side.

Editing on the local side

You can create, edit, and delete files in the shared directory on your local machine, as well as move files between subdirectories.

To view your local changes on the remote side, you will need to either refresh or re-open the remote directory, or re-open any individual files you changed locally. When you do this, the remote desktop will request the current state of the directory from the Teleport Web UI.

File size restrictions

Performance for moving large files to and from the shared directory will depend on network conditions, and file editing performance will depend on the program you use to edit files.

While there is no size limit for files within your shared directory, we only recommend manipulating files up to 32 MB to reduce the impact of the shared directory on network bandwidth and system resources.

Step 3/4. Disconnect

To stop sharing a directory, end your remote desktop session. Navigate to the three-dot menu on the upper-right of the desktop session in your browser and click "Disconnect."

The next time you start a session on the remote desktop, the directory will no longer be shared. You will need to share the directory again to access its content.

The Teleport Auth Service grants access to Directory Sharing on a remote desktop based on the roles of the user who initiates the desktop session.

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

Create the role:

tctl create -f role.yaml

Assign the no-sharing role to your Teleport user by running the appropriate commands for your authentication provider:

Retrieve your local user's configuration resource:

tctl get users/$(tsh status -f json | jq -r '.active.username') > out.yaml

Edit out.yaml, adding no-sharing to the list of existing roles:

  roles:
   - access
   - auditor
   - editor
+  - no-sharing

Apply your changes:
```
tctl create -f out.yaml
```
Sign out of the Teleport cluster and sign in again to assume the new role.

Retrieve your github authentication connector:
```
tctl get github/github --with-secrets > github.yaml
```
Note that the --with-secrets flag adds the value of spec.signing_key_pair.private_key to the github.yaml file. Because this key contains a sensitive value, you should remove the github.yaml file immediately after updating the resource.
Edit github.yaml, adding no-sharing to the teams_to_roles section.

The team you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the team must include your user account and should be the smallest team possible within your organization.

Here is an example:
```
  teams_to_roles:
    - organization: octocats
      team: admins
      roles:
        - access
+       - no-sharing
```
Apply your changes:
```
tctl create -f github.yaml
```
Sign out of the Teleport cluster and sign in again to assume the new role.

Retrieve your saml configuration resource:
```
tctl get --with-secrets saml/mysaml > saml.yaml
```
Note that the --with-secrets flag adds the value of spec.signing_key_pair.private_key to the saml.yaml file. Because this key contains a sensitive value, you should remove the saml.yaml file immediately after updating the resource.
Edit saml.yaml, adding no-sharing to the attributes_to_roles section.

The attribute you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.

Here is an example:
```
  attributes_to_roles:
    - name: "groups"
      value: "my-group"
      roles:
        - access
+       - no-sharing
```
Apply your changes:
```
tctl create -f saml.yaml
```
Sign out of the Teleport cluster and sign in again to assume the new role.

Retrieve your oidc configuration resource:
```
tctl get oidc/myoidc --with-secrets > oidc.yaml
```
Note that the --with-secrets flag adds the value of spec.signing_key_pair.private_key to the oidc.yaml file. Because this key contains a sensitive value, you should remove the oidc.yaml file immediately after updating the resource.
Edit oidc.yaml, adding no-sharing to the claims_to_roles section.

The claim you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.

Here is an example:
```
  claims_to_roles:
    - name: "groups"
      value: "my-group"
      roles:
        - access
+       - no-sharing
```
Apply your changes:
```
tctl create -f oidc.yaml
```
Sign out of the Teleport cluster and sign in again to assume the new role.

Sign in to Teleport

Desktop Access Directory Sharing

Prerequisites

Prohibited directories

Long directory names

Step 2/4. Edit files in your directory

Editing on the remote side

Editing on the local side

File size restrictions

Step 3/4. Disconnect

Next steps

Further reading

Desktop Access Directory Sharing

Prerequisites

Step 1/4. Share a directory

Limitations on directories you can share

Prohibited directories

Long directory names

After you share a directory

Step 2/4. Edit files in your directory

Editing on the remote side

Editing on the local side

File size restrictions

Step 3/4. Disconnect

Step 4/4. Disable Directory Sharing

Next steps

Further reading

How Directory Sharing works