# Introduction to Teleport Clients This guide covers the basics of authenticating to Teleport and accessing resources. It's written for end-users of resources protected by Teleport, and includes links to more detailed documentation at the end. ## Choosing a client Teleport provides three tools for accessing protected infrastructure. `tsh` is a command-line client, Teleport Connect is a graphical native client, and the Teleport Web UI is a browser-based console available at the URL of your Teleport cluster. You should get familiar with all three tools, since each provides access to a different set of resources and offers a different user experience. This section includes a summary of the capabilities available in each client tool. Accessing infrastructure: | Resource | Teleport Connect | Web UI | tsh | | ------------------------------------ | ---------------- | ------ | --- | | Browser-based web applications | ⚠️1 | ✅ | ❌ | | TCP apps and HTTP APIs | ✅ | ❌ | ✅ | | Databases with GUI client tools | ✅ | ❌ | ✅ | | Databases with command-line clients | ✅ | ⚠️2 | ✅ | | Remote desktops | ✅ | ✅ | ❌ | | Kubernetes clusters | ✅ | ⚠️3 | ✅ | | Linux servers (Teleport SSH Service) | ✅ | ✅ | ✅ | | MCP servers | ✅ | ⚠️2 | ✅ | 1 Browser-based web applications in Teleport Connect open in the default web browser. 2 For resources that require a command-line tool to access, the Teleport Web UI shows you instructions for using a terminal to access the resource. You can establish sessions with certain databases in the Web UI. See [Starting a database session](https://goteleport.com/docs/connect-your-client/teleport-clients/web-ui.md#starting-a-database-session) for supported databases. 3 You can `exec` into a Kubernetes pod using a browser-based terminal in the Teleport Web UI. Full `kubectl` access is not supported. Other client operations: | Task | Teleport Connect | Web UI | tsh | | ------------------------- | ---------------- | ------ | --- | | Manage Access Requests | ✅ | ✅ | ✅ | | Start VNet | ✅ | ❌ | ✅ | | Access session recordings | ❌ | ✅ | ✅ | ### tsh `tsh` lets you authenticate to Teleport and list and connect to resources. After [downloading](https://goteleport.com/download/) and installing `tsh`, sign in to your Teleport cluster: **Local user** Authenticate to Teleport as a local user with `tsh login` by assigning user to your Teleport username and teleport.example.com to the domain name of your Teleport cluster: ``` $ tsh login --proxy=teleport.example.com --user=user Enter password for Teleport user alice: Tap any security key > Profile URL: https://teleport.example.com:443 Logged in as: alice Cluster: example.com Roles: access, requester Logins: ubuntu, ec2-user Kubernetes: enabled Valid until: 2022-11-01 22:37:05 -0500 CDT [valid for 12h0m0s] Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty, private-key-policy ``` **Single sign-on user** Authenticate to Teleport as a single sign-on (SSO) user by running `tsh login` and assigning your-idp-connector to the name of your authentication connector, if implemented by your administrators: ``` $ tsh login --proxy=teleport.example.com --auth=your-idp-connector If browser window does not open automatically, open it by clicking on the link: http://127.0.0.1:49927/1d80e257-ec61-4ed2-9403-784f8d35b2fe > Profile URL: https://teleport.example.com:443 Logged in as: user@example.com Cluster: example.com Roles: access, requester Logins: ubuntu, ec2-user Kubernetes: enabled Valid until: 2022-11-01 22:37:05 -0500 CDT [valid for 12h0m0s] Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty, private-key-policy ``` Depending on how Teleport was configured for your network, you may not need the additional flag `--auth`. Your administrator should provide the details required for your particular use case. ### Teleport Connect The Teleport Connect app provides all the same access to resources as `tsh` in a friendly graphical user interface. After [downloading](https://goteleport.com/download/) and installing Teleport Connect, you can log in and initiate sessions for server and database access within a single window. 1. Click **CONNECT** to connect to the Teleport cluster: ![A new instance of Teleport Connect](/docs/assets/images/teleport-connect-init-365252c5f08cfb68d2e02908474fd4c8.png) 2. Provide the address of your Teleport Cluster (e.g. `https://example.teleport.sh`) and click **NEXT**. 3. Teleport Connect will ask you for your username, password, and MFA. If Teleport is integrated with an external Identity Provider (**IdP**), you might be prompted to authenticate with that service in a browser window. 4. Browse and connect to all the resources your user is permitted to access: ![An example of Teleport Connect, populated with instances](/docs/assets/images/connect-ui-overview@2x-594d9741d26c623d38ba15aec4a75757.png) ### Web UI Teleport provides a web interface for users to interact with Teleport, e.g., by accessing resources or creating Access Requests. This is usually found at the same URL used to connect to Teleport with (e.g. `https://example.teleport.sh`), but you should confirm the Web UI URL with the team that manages your Teleport deployment. The Web UI provides similar access to resources as Teleport Connect, and additional access to Request and Activity logs for users with the right permissions. ## Connecting to resources This section provides an overview of some ways you can use Teleport client tools to connect to resources in your infrastructure. ### Server access (`ssh`) **tsh** `tsh ls` lists the servers you have access to through Teleport: ``` $ tsh ls Node Name Address Labels ------------------- --------------- ---------------------------- server1.example.com 192.0.2.24:3022 access=servers,hostname=server1 server2.example.com 192.0.2.32:3022 access=servers,hostname=server2 ``` To connect to a server: ``` $ tsh ssh ubuntu@server1.example.com ubuntu@server1:~$ ``` **Teleport Connect** Under the **Servers** tab, click **CONNECT** next to the server you want to access. Select or type in a username available to your Teleport user. In a new tab, Teleport Connect will initiate the connection and provide a terminal environment. **Web UI** From the **Servers** menu, the Teleport Web UI will list all servers your user has permission to access. The **CONNECT** button will open a new tab with a terminal emulator to provide access to that server. ### Kubernetes access (`kubectl`) **tsh** To see the Kubernetes clusters that you can access via Teleport, run the following command: ``` $ tsh kube ls Kube Cluster Name Labels Selected ----------------- --------------------------- -------- mycluster env=dev ``` To log in to the cluster, run the following command, changing `mycluster` to the name of a Kubernetes cluster as it was listed in `tsh kube ls`: ``` $ tsh kube login mycluster Logged into kubernetes cluster "mycluster". Try 'kubectl version' to test the connection. ``` When you log in to your Teleport cluster via `tsh kube login`, `tsh` updates your kubeconfig to point to your chosen Kubernetes cluster. You can then run `kubectl` commands against your cluster. **Teleport Connect** After logging in to a cluster in Teleport Connect, click the **Kubes** tab to see a list of Kubernetes clusters you can access. ![Clusters you can access](/docs/assets/images/connect-kube-list-4aaf4a778c173697a86dc807e9044fe9.png) Next to your chosen cluster, click **Connect**. Teleport Connect will open a terminal in a new tab and authenticate to the cluster. You can then run `kubectl` commands to interact with the cluster. ![Connect to a cluster](/docs/assets/images/connect-kube-access-bbba0ab4bd2d37a9d2b7f8505eb22c60.png) **Web UI** In the Teleport Web UI, click the **Kubernetes** tab. You will see a list of Kubernetes clusters your Teleport user is authorized to connect to. ![Available Kubernetes clusters](/docs/assets/images/kubernetes-clusters-5667223f588d2ea46b81ecccce373290.png) Find your chosen cluster and click **Connect**. You will see a modal window that lists the commands you can execute in your terminal to connect to the cluster via Teleport. ![Connect to a Kubernetes cluster](/docs/assets/images/kubernetes-login-475447c4ca40bc3157d1c9f173f33f97.png) ### Transferring files **tsh scp** `tsh scp` will let you transfer files to servers behind Teleport: ``` $ tsh scp some-file.ext server.example.com: some-file.ext 7% |███████ | (25/342 MB, 2.9 MB/s) [9s:1m48s] ``` **Teleport Connect** Teleport Connect allows you to transfer files to a remote server and runs on macOS, Linux and Windows. You can use the arrows in the top-left corner of an active SSH session to upload and download files: ![Download with connect](/docs/assets/images/download_files_connect-85642efd0e1a004d161b468286daf961.png) You can upload files from systems using drag and drop: ![Drag and drop in Connect](/docs/assets/images/upload_files_connect_drag_drop-f7a20aa728775492f0fbee1853c6e884.png) **Web UI** You can use the arrows in the top-left corner of the Web UI to download files: ![Arrows in Web UI](/docs/assets/images/download_files_webui-c6cebf6c1b04ba7c478c5bb3c77489b7.png) Or you can upload using drag and drop: ![Upload in Web UI](/docs/assets/images/upload_files_webui-829a7f6a37f3d0f805130a38a4186fb8.png) ### Database access **tsh** `tsh db ls` will list the databases available to your user: ``` $ tsh db ls Name Description Allowed Users Labels Connect ----------------------------------------------- ----------- --------------- ------- ------------------------- myelastic [alice elastic] env=dev mysql-server1 (user: alice, db: teleport_example) [alice elastic] env=dev tsh db connect mysql-server1 ``` To connect to a database server through `tsh`, you'll need a local client for that database. For example, to connect to a MySQL or MariaDB database, you'll need the [MySQL CLI](https://dev.mysql.com/doc/refman/8.0/en/mysql.html) client: ``` $ tsh db connect --db-user=alice --db-name=teleport_example mysql-server1 ``` In this example, `teleport_example` is a pre-existing database on the MySQL server: ``` SHOW DATABASES; +--------------------+ | Database | +--------------------+ | information_schema | | mysql | | performance_schema | | teleport_example | +--------------------+ 4 rows in set (0.09 sec) ``` For other connection types, or to connect a graphic database client, you can create a local tunnel to point your software to: ``` $ tsh proxy db myelastic --db-user=alice --tunnel Started authenticated tunnel for the Elasticsearch database "myelastic" in cluster "example.com" on 192.0.2.58:52669. Use one of the following commands to connect to the database: * interactive SQL connection: $ elasticsearch-sql-cli http://localhost:52669/ * run single request with curl: $ curl http://localhost:52669/ Database certificate renewed: valid until 2022-11-02T06:11:50Z [valid for 9h55m0s] ``` **Teleport Connect** In the **Databases** tab, select the database you want to access and click **CONNECT**. Select or type in a username available to your Teleport user. Teleport Connect will open a tunneled connection to the database. You can copy the port number and connect with a GUI app at `localhost`, or click **RUN** to initiate a CLI connection inside Teleport Connect: ![Teleport Connect database connection](/docs/assets/images/teleport-connect-mysql-325e2585839e73e9e1050cb15d525eac.png) **Web UI** The Teleport Web UI will show all databases a user has access to and only offers browser-based sessions for a select number of databases. For databases that can't be accessed from the browser, the Web UI will show the `tsh` commands that are needed to connect from a developer workstation. For more details on accessing databases directly from the browser, refer to [Starting a database session](https://goteleport.com/docs/connect-your-client/teleport-clients/web-ui.md#starting-a-database-session) in the Teleport Web UI. ### Desktop access Desktop access is available through the Teleport Web UI. 1. In your browser, navigate to your Teleport cluster (for example, `https://example.teleport.sh`). 2. From the menu on the right, select **Desktops**. 3. Next to the desktop you want to access, click **CONNECT**. Select or type in a username available to your Teleport user. 4. Teleport will open a new browser tab or window and begin the RDP session. Note that you may need to wait a moment for Teleport to log you in as the specified user. ## Next steps This guide covers the basic installation and access of Teleport for end users, but the rest of the Connect your Client section provides more detailed information. - `tsh` is the CLI tool for accessing resources through Teleport. With it, you can authenticate to Teleport, list available services, and connect to them either directly or through proxy tunnels. Learn more about it from [Using the tsh Command Line Tool](https://goteleport.com/docs/connect-your-client/teleport-clients/tsh.md). - Teleport Connect is a graphical utility for connecting to resources through Teleport. You use it to connect to servers, databases, and Kubernetes clusters. See [Using Teleport Connect](https://goteleport.com/docs/connect-your-client/teleport-clients/teleport-connect.md). - [Access Teleport-protected databases with GUI clients](https://goteleport.com/docs/connect-your-client/third-party/gui-clients.md): Details how to connect many popular database GUI clients through Teleport.