How Teleport Works

How Teleport Works

Teleport provides secure access to SSH or Windows servers, Windows desktops, Kubernetes clusters, databases, and web applications. Teleport is trivial to set up as a Linux daemon or in a Kubernetes pod.

The basics

Teleport is a certificate authority and identity-aware, multi-protocol access proxy which implements protocols such as SSH, RDP, HTTPS, Kubernetes API, and a variety of SQL and NoSQL databases. It is completely transparent to client-side tools and designed to work with everything in today's DevOps ecosystem.

Inside the downloaded tarball, you will find three binaries: the teleport daemon, the tsh client, and the tctl administration tool. They are dependency-free, written in a compiled language. Teleport is open source and the source code is available on Github.

Teleport architecture

The key concept of Teleport's architecture is the cluster. A Teleport cluster consists of the Teleport Auth Service, Teleport Proxy Service, Teleport agents, and resources that you want to connect to such as Linux or Windows servers, databases, Kubernetes clusters, Windows desktops, and internal web apps.

To create a minimal Teleport cluster, you must launch three services:

  • Teleport Auth Service. The certificate authority of the cluster. It issues certificates to clients and maintains the audit log.
  • Teleport Proxy Service. The proxy allows access to cluster resources from the outside. Typically it is the only service available from the public network.
  • Teleport agents. A Teleport agent runs in the same network as a target resource and speaks its native protocol, such as the SSH, Kubernetes API, HTTPS, PostgreSQL, and MySQL wire protocols. Think of a "smart sidecar" that routes user requests to its target resource.

The diagram below is interactive. Try clicking on individual components:

Public Network

Edge Network

Private Network

proxy.example.com

How Teleport Works

To learn more about how Teleport works, click on different areas of the diagram.

  • User Connections
  • Audit Information

The teleport binary provides all three services. They can be enabled or disabled via configuration or command line flags. To create a single-node cluster, launch a single instance of the teleport daemon with all services enabled.


Clients must authenticate with Teleport and receive a client certificate, which automatically works for all resources in a cluster. After authentication, the ssh, kubectl, psql, mysql and other remote access commands will be configured with the user's identity. Teleport offers a built-in database for user management, but for production use, we recommend integrating it with enterprise SSO based on Okta, GitHub, Google Workspace, Active Directory, and other identity providers.

How a Teleport cluster works

The concept of a cluster is the foundation of the Teleport security model.

  • Users and servers must all join the same cluster before access can be granted.
  • To join a cluster, both users and servers must authenticate and receive certificates.
  • The Teleport Auth Service is the CA of the cluster, which issues certificates for both users and servers with all supported protocols.

This model prevents honeypot attacks and eliminates the issue of trust on first use. This also allows users to enumerate all servers and other resources that are currently online.

Teleport clusters can be configured to trust each other. This allows users from one organization to access designated servers inside of another organization's cloud or on-premise environment.

User experience

Teleport Desktop Access enables users to access Windows hosts via RDP in their web browser, and does not require a separate RDP client.

Users of ssh, kubectl, and other command-line clients can authenticate first by executing the tsh login command. This configures the users' CLI environments with short-lived certificates for access.

After that, users will be able to access their SSH servers, Windows servers and desktops, Kubernetes clusters, web applications, or databases. Teleport is backward compliant with existing client tools, so users can continue to use client tools including ssh, psql, mysql, kubectl, and others as usual:

# First, 'tsh' commands authenticates users and configures other
# CLI tools with a client's certificate:

$ tsh login --proxy=proxy.example.com

# SSH access as usual:

$ ssh [email protected]

# Kubernetes access as usual:

$ kubectl get pods

# Database access as usual:

$ psql

How authentication works

The Teleport Proxy Service serves the login screen on https://proxy.example.com:443, where users are asked for their username, password, and a second factor. If a third-party identity provider such as GitHub is used, the Proxy Service forwards the user to GitHub using OAuth2.

The Proxy Service sends the user's identity to the Teleport Auth Service. In turn, the Auth Service issues certificates for SSH, Kubernetes, and other resources in a cluster, and sends them back to the client via the Proxy Service.

The tsh client receives the certificates from the Proxy Service, stores them in the user's ~/.tsh directory, and loads them into the ssh-agent if one is running.

To learn more, check out our guide to certificate-based SSH authentication.

Audit log

The Teleport Auth Service maintains an audit log of all activity inside the Teleport cluster. The audit log consists of two components:

  • The audit log: Well-documented JSON records of security events. Examples of such events include login attempts, file transfers, code execution, filesystem changes, and network activity.
  • The recorded sessions: Recordings of interactive sessions established via SSH, RDP and kubectl commands. The recorded sessions can be replayed for audit purposes.

The Teleport Auth Service stores both types of audit data on a local file system by default, but can be configured to use S3, DynamoDB, and other suitable data stores.

The recorded sessions are stored as flat ASCII files and can be easily analyzed by third-party software. For example, a user can replay a session by dumping a session file to stdout using the cat command.

Teleport: How It Works

To learn more, check out Audit Logging.

Access for edge networks

Teleport allows users to access resources running on devices that are located anywhere in the world, for example, devices on third-party networks, servers behind NAT, or devices connected via a cellular connection. Examples of this include self-driving vehicles, network equipment, retail locations, and medical devices.

To make this work, each remote device must be configured to point at the public address of a Teleport Proxy Service, e.g., proxy.example.com. This allows each device to establish and maintain a permanent reverse tunnel to the cluster to which it belongs. This tunnel is used to proxy user connections into devices. The tunnel is automatically re-established if network connectivity is intermittent.

Reverse tunnels enable Teleport users to:

  • Manage IoT devices via SSH.
  • Access Kubernetes clusters located on the edge or on IoT platforms.
  • Access web applications running on 3rd party private networks.
  • Access MySQL and PostgreSQL databases running in remote environments.

To learn more, check out Edge Access

Easy to get started

Teleport is easy to deploy and use. We believe that simplicity and good user experience are key to first-class security.

Teleport consists of just two binaries.
  1. The tsh client allows users to login to retrieve short-lived certificates.
  2. The teleport agent can be installed on any server, database, application and Kubernetes cluster with a single command.
Download Teleport
Terminal
# on a client$ tsh login--proxy=example.com
# on a server$ apt install teleport
# in a Kubernetes cluster$ helm install

Try Teleport today

In the cloud, self-hosted, or open source
Get StartedView developer docs