TLS routing is available starting from Teleport
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.
TLS routing will not work in environments where layer 7 load balancers or reverse proxies are used. See further information in the When to use TLS routing section below.
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
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: v1to your config file and removing
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
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.
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.
Let's take a look at how each protocol Teleport supports implements TLS routing.
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.
To support standard OpenSSH client, Teleport provides a
tsh proxy ssh command
which can be used as a
tsh proxy ssh establishes a TLS tunnel to Teleport
teleport-proxy-ssh ALPN protocol, which
ssh then connects over.
See the OpenSSH client guide for details on how it's configured.
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.
kubectl uses HTTPS API and TLS handshake to talk to the API
As such, it is not possible to request a custom ALPN protocol using
Instead, Teleport leverages SNI and sets a
ServerName prefixed with
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
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-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
protocols for ALPN.
- See migration guide to learn how to upgrade an existing cluster to use TLS routing.
- Read through TLS routing design document RFD.