How Teleport Works

Teleport is an open-source Linux daemon used for secure access to SSH nodes and Kubernetes clusters. Learn basic Teleport concepts and architecture below.

The Basics

Teleport comes as three binaries: the teleport daemon, the tsh client, and the tctl administration tool. They are dependency-free, written in a compiled language, and run on any UNIX-compatible operating system, such as Linux, FreeBSD, or macOS. Teleport is open source under the Apache 2 license and the source code is available on Github.

Teleport is easy to deploy. It is a traditional Linux daemon similar to sshd and usually runs as a systemd service.

Teleport Architecture

The key concept of Teleport architecture is a “cluster”. A cluster is a collection of resources such as servers, remote devices, or a Kubernetes instance. To gain access to any resource in a cluster, a client must authenticate against a user database. Teleport offers a built-in database and integrates with Github, Google Apps, and other identity providers.

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 Node. The node service runs on every node in a cluster. Think of it as sshd on steroids.

The diagram below is interactive, try clicking on individual components:

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.

How Teleport Cluster Works

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

  • Users and servers all must 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 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 users who need SSH access have to authenticate by using tsh, the command-line client. The tsh login command opens a web browser to authenticate users and exits upon successful authentication:

Teleport is fully backward compatible with existing SSH and Kubernetes workflows.

The certificate issued by tsh login automatically expires after 12 hours. This expiration time is configurable.

# the login command will open a web browser:
$ tsh login --proxy=proxy.example.com

# use SSH or Kuberentes as usual:
$ ssh [email protected]
$ kubectl get pods

How Authentication Works

Teleport proxy serves the login screen on https://proxy.example.com:3080 where users are asked for their username, password, and a 2nd factor. If a 3rd party identity such as Github is used, the proxy forwards the user to Github using OAuth2.

The proxy 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.

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

Learn more about certificate-based authentication.

Audit Log

The Teleport Auth server maintains the audit log of everything happening inside the cluster. The audit log consists of two components:

  1. The event log. It consists of well-documented JSON records of security events. Examples of such events include login attempts, file transfers, code execution, filesystem changes, or network activity.
  2. The recorded sessions. All users’ interactive sessions to cluster nodes via the ssh and kubectl commands are recorded for future replay.

The Auth service stores both types of audit 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 3rd party software. For example, one can “replay” a session by dumping a session file to stdout using cat command.

Learn more about the audit log.

Kubernetes Access

Using Teleport allows users to authenticate to SSH hosts and Kubernetes at the same time using the same set of credentials.

When configured, a Teleport proxy sits between a user and a Kubernetes cluster API endpoint. The easiest way to make this work is to deploy the Teleport proxy as a Kubernetes pod. Another approach is to configure the Teleport proxy with a Kubernetes service account and provide a path to kubeconfig in Teleport proxy’s configuration.

Teleport uses Kubernetes Impersonation Headers to proxy users’ connections from the outside to a K8s cluster.

Learn more about Kubernetes Access.

SSH and Kuberentes access on the Edge

Teleport allows users to access devices running anywhere in the world, i.e. on 3rd party networks or via a cellular connection. Examples of this include self-driving vehicles, retail locations, or medical hardware.

To make this work, each remote device must be configured to point at a Teleport Proxy public address, like 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 the network connectivity is intermittent.

Reverse tunnels enable Teleport users to:

  • Manage IoT devices via SSH.
  • Access Kubernetes clusters located on edge or IoT platforms.
  • Access Web applications running on 3rd party private networks.

Learn more about SSH and Kuberentes access on the Edge.

What's Next

This site uses cookies to improve service. By using this site, you agree to our use of cookies. More info.