TLS Routing

In TLS routing mode Teleport proxy multiplexes all client connections on a single TLS port.

With TLS routing, cluster administrators can simplify network configurations since proxy only listens on one port. All connections are authenticated with mutual TLS and users are able to tunnel protocols that may be blocked on the network such as SSH.

To implement TLS routing, Teleport uses SNI (Server Name Indication) and ALPN (Application-Level Protocol Negotiation) TLS extensions.

When to use TLS routing

Using Teleport's TLS routing mode behind a layer 7 (HTTP/HTTPS) proxy is generally not supported, due to these proxies terminating TLS themselves and then rewriting their requests to the upstream service, stripping the additional SNI/ALPN parts of the request in the process. In order for ALPN to work correctly, the Teleport proxy must terminate TLS itself.

Broadly, this means that Teleport's TLS routing functionality is incompatible with:

• AWS ALBs (Application Load Balancers)
• AWS NLBs (Network Load Balancers), when using a TLS listener and a public ACM (Amazon Certificate Manager) certificate
• Commonly used HTTP reverse proxies including nginx, Apache, Caddy, Traefik, HAProxy and many others
• Cloudflare tunnels in their default configuration

Deploying Teleport in TLS routing mode behind an HTTP proxy will result in a Teleport Web UI experience that seems to work perfectly, but the use of tsh, tctl and attempting to join remote Teleport services to the cluster will fail with errors like ssh: overflow reading version string and EOF. A functioning Teleport Web UI is not always an indication of a correctly configured Teleport cluster.

If in doubt, remove all load balancers/proxies from the equation and connect Teleport clients or agent processes directly to Teleport's web port to isolate the issue.

To use Teleport behind a reverse proxy, you should either:

• use a layer 4 (TCP) proxy which forwards TCP streams directly to Teleport (which will in turn handle TLS termination itself)
• disable Teleport's TLS routing mode by adding version: v1 to your config file and removing proxy_listener_mode: multiplex

You can get an example v1 config file using teleport configure --version=v1 --public-addr=teleport.example.com:443 (change the public address to your own domain)

If disabling TLS routing, you can find the list of default ports to use for connecting different Teleport services at ports without TLS routing

How it works

Starting from version 8.0 Teleport proxy listens for all client connections on its web_listen_addr by default:

proxy_service:
  web_listen_addr: "0.0.0.0:443"

All Teleport clients including SSH, web browser, kubectl, database and reverse tunnel clients establish a TLS tunnel to the proxy's web port and indicate the protocol they're requesting using SNI and ALPN TLS extensions.

Upon accepting a new connection, the proxy inspects the SNI/ALPN value in the TLS handshake and forwards the connection to appropriate backend service.

Local proxy

Clients like psql or mysql implement TLS handshake as a part of their protocol-specific connection negotiation phase (aka STARTTLS).

To support these clients, as well as clients that do support TLS but don't allow setting custom ALPN values, Teleport's tsh client includes ability to start a local TLS routing aware proxy.

Such clients connect to the local proxy instead of Teleport proxy directly. The local proxy establishes a TLS connection to the Teleport proxy with the proper SNI/ALPN values set and tunnels the client's connection over it.

In most cases, clients handle TLS routing transparently when establishing connection. For example, tsh client starts local proxy and sets appropriate SNI/ALPN values automatically. For some clients, like native/GUI database clients instead of tsh db connect, the user needs to start the local proxy so these clients can connect to it.

Diagram

Let's take a look at how each protocol Teleport supports implements TLS routing.

SSH

Teleport client tsh, when connecting to an SSH node, first dials Teleport proxy over TLS and requests teleport-proxy-ssh ALPN protocol.

No local proxy is started in this case as tsh uses this TLS connection as a transport to establish the SSH connection.

OpenSSH

To support standard OpenSSH client, Teleport provides a tsh proxy ssh command which can be used as a ProxyCommand.

Similarly to tsh ssh, tsh proxy ssh establishes a TLS tunnel to Teleport proxy with teleport-proxy-ssh ALPN protocol, which ssh then connects over.

See the OpenSSH client guide for details on how it's configured.

Reverse tunnels

Reverse tunnel workers within the Teleport Node, Application and Database Services, as well as for Trusted Clusters, open a TLS tunnel to the cluster's Proxy Service with the teleport-reversetunnel ALPN protocol. The workers then dial SSH over the tunnel, establishing a secure connection.

Kubernetes

Kubernetes client kubectl uses HTTPS API and TLS handshake to talk to the API server.

As such, it is not possible to request a custom ALPN protocol using kubectl. Instead, Teleport leverages SNI and sets a ServerName prefixed with kube. when generating a kubeconfig file during tsh kube login:

apiVersion: v1
kind: Config
clusters:
- cluster:
    certificate-authority-data: ...
    server: https://proxy.example.com:443
    tls-server-name: kube.proxy.example.com
  name: example

Databases

The tsh db connect command executes an appropriate database client for the database you're connecting to.

In TLS routing mode, tsh starts a local proxy which database client connection is tunneled through. The local proxy uses one of teleport-postgres, teleport-mysql or teleport-mongodb ALPN values depending on the database. The proxy is shut down when the database session ends.

Native and GUI clients

For the native or graphical database clients to work with TLS routing, they must be connecting to the local proxy instead of Teleport proxy directly.

Teleport provides a tsh proxy db command to launch a local database proxy:

tsh proxy db example-db

See GUI clients guide for a usage example.

Web UI, apps and desktops

Application access, desktop access and Teleport web UI are served by the Teleport proxy's web listener and don't require a local proxy or any special ALPN/SNI negotiation. These web connections use standard http1.1 and h2 protocols for ALPN.

Next steps

• See migration guide to learn how to upgrade an existing cluster to use TLS routing.
• Read through TLS routing design document RFD.