Skip to main content
Version: 15.x

Running Teleport with Self-Signed Certificates

This guide explains how to evaluate Teleport in a non-production environment without having to configure TLS certificates. We will show you how to run Teleport with self-signed certificates and address problems caused by this configuration.

The Teleport Proxy Service authenticates itself to clients via TLS x509 certificates. If certificates are not configured for the Proxy Service then it uses self-signed certificates, which clients will not trust by default. When visiting the cluster's Web UI, the certificate presented will not be trusted by your browser. In this case, you will likely see a page warning you that the website is not trusted.

Additionally, self-signed certificates can prevent teleport, tsh, and tctl from connecting to the Proxy Service.

DO NOT USE THIS IN PRODUCTION

DO NOT USE SELF-SIGNED CERTIFICATES IN PRODUCTION

Configuring your cluster to trust self-signed certificates makes it easier for attackers to intercept communications between the Proxy Service and clients, since there is no way to verify the authenticity of the certificates. It is therefore important to properly configure certificates when using Teleport in a production environment.

Prerequisites​

  • A running Teleport cluster. For details on how to set this up, see our Getting Started guide (skip TLS certificate setup).

  • A Teleport Proxy Service which does not have certificates or ACME automatic certificates configured. For example, this Teleport Proxy Service configuration would use self-signed certs:

    proxy_service:
      enabled: "yes"
      # TLS certificate for the HTTPS connection.
      https_keypairs: []
      # Get an automatic certificate from letsencrypt.org using ACME.
      acme: {}

  • The tctl and tsh client tools version >= 15.4.22. Read Installation for how to install these.

    See Installation for details.

How to use self-signed certs with Teleport binaries and clients​

teleport​

When running a Teleport service with teleport, if the service you are starting is configured to point to the Teleport Proxy Service endpoint and the Proxy Service is using self-signed certificates, then teleport will need to be run with the --insecure flag to disable verification of the Proxy Service TLS certificate. This is the case when:

  • The Teleport config file proxy_server setting is set to the Proxy Service endpoint:
    • proxy_server: "tele.example.com:443" or
    • proxy_server: "tele.example.com:3080"
  • Teleport is started with the --auth-server flag pointing to the Proxy Service endpoint:
    • teleport [app | db] start --auth-server=tele.example.com:443 or
    • teleport [app | db] start --auth-server=tele.example.com:3080

Instructions for disabling TLS certificate verification depend on how you are running Teleport: via the teleport CLI, using a Helm chart, or via systemd:

When running teleport from the command line, pass the --insecure flag to disable TLS certificate validation. For example:

$ sudo teleport start -c /etc/teleport.yaml --insecure
$ sudo teleport app start -c /etc/teleport.yaml --insecure
$ sudo teleport db start -c /etc/teleport.yaml --insecure

Without the --insecure flag, you will see an error message that looks like x509: “tele.example.com” certificate is not trusted.

tctl​

When running tctl remotely via the Teleport Proxy Service, if the Proxy Service is using self-signed certificates, then tctl will not trust the certificate from the Proxy Service. To disable certificate verification use the --insecure flag when running tctl commands.

tctl will determine how to connect to the Auth Service in a few ways:

  • loading configuration from a local profile after logging in with tsh
  • loading from a config file passed as an argument: tctl -c /etc/teleport.yaml
  • passing the --auth-server flag directly, as in:
    • tctl --auth-server=tele.example.com:443 or
    • tctl --auth-server=tele.example.com:3080

If any of these methods tries to connect via the Teleport Proxy Service, and the Proxy Service is using self-signed certificates, then tctl will not trust the certificate from the Proxy Service and you will get an error message about untrusted or invalid certificates, unless --insecure is also passed to tctl.

For example: tctl status --insecure

tsh​

When running tsh, you must specify the Teleport Proxy Service address for tsh to connect to. If the Teleport Proxy Service is using self-signed certificates, then tsh will not trust the Proxy Service certificate. In order to use tsh in this case, you need to use the --insecure flag.

For example: tsh login --proxy=tele.example.com:443 --user=alice --insecure

Teleport Connect​

Teleport Connect lets you skip TLS certificate verification with the --insecure flag.

Further reading​