Fork me on GitHub

Teleport

Introduction to Teleport Clients

Improve

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.

Client tools

tsh

tsh lets you authenticate to Teleport and list and connect to resources. After downloading and installing tsh, sign in to your Teleport cluster:

tsh login --proxy=
--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

Logins: root, 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

tsh login --proxy=
--user=
--auth=

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

Logins: root, 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 flags --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 graphic user interface. After downloading 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

  2. Provide the address of your Teleport Cluster (e.g. https://teleport.example.com ) 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), it may instead prompt you to authenticate in a browser window with that service.

  4. Once authenticated, you can browse and connect to all the resources your user is permitted to access:

    An example of Teleport Connect, populated with instances

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://teleport.example.com ), 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 to Request and Activity logs for users with the right permissions.

Protocols

Server Access (ssh)

tsh ls lists the servers you have access to through Server Access (SSH):

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:

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.

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.

Transferring files (scp)

tsh scp will let you transfer files to servers behind Teleport:

tsh scp somefile.ext xeon.tp.alexf.xyz:

somefile.ext 7% |███████ | (25/342 MB, 2.9 MB/s) [9s:1m48s]

Kubernetes Access (kubectl)

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.

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

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

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

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

Database Access

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 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.come" 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]

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

The Teleport Web UI cannot provide direct connections to databases, but it will list those that are accessible to your user under Databases and provide tsh commands to connect from your local terminal environment.

Desktop Access

Desktop Access is available through the Teleport Web UI. In your browser, navigate to your Teleport cluster (e.g. https://teleport.example.com ).

  1. From the menu on the right, select Desktops.
  2. Next to the desktop you want to access, click CONNECT. Select or type in a username available to your Teleport user.
  3. 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.

  • Teleport Connect is a graphic utility for connecting to resources through Teleport. You can initiate Server Access, connect to databases, and start Desktop Accesss sessions. See Using Teleport Connect.

  • Database Access GUI Clients details how to connect many popular database GUI clients through Teleport.