Simplifying FedRAMP Compliance with Teleport
Jun 27
Virtual
Register Today
Support
LOG IN
Teleport logoTry For Free
Contact SalesTry for Free
Support
LOG IN
Fork me on GitHub

Teleport

Running Teleport with Self-Signed Certificates

Version preview

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 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 >= 17.0.0-dev. Read Installation for how to install these.

    See Installation for details.

  • A running Teleport cluster. For details on how to set this up, see our Enterprise Getting Started guide.

  • 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 >= 17.0.0-dev, which you can download by visiting your Teleport account.

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.

If you are using the teleport-cluster Helm chart, set extraArgs to include the extra argument: --insecure:

extraArgs:
- "--insecure"

--set "extraArgs={--insecure}"

If you are using the teleport-kube-agent chart, set the insecureSkipProxyTLSVerify flag to true:

insecureSkipProxyTLSVerify: true

--set insecureSkipProxyTLSVerify=true

Locate the systemd unit file for Teleport (called teleport.service) by running the following command:

$ systemctl status teleport

You will see output similar to the following, including the file path (/lib/systemd/system/teleport.service) that contains the unit file for the systemd configuration being applied:

● teleport.service - Teleport Service    Loaded: loaded (/lib/systemd/system/teleport.service; disabled; vendor preset: enabled)    Active: inactive (dead)

Edit the Teleport unit file to include --insecure in the ExecStart line, for example:

ExecStart=/usr/local/bin/teleport start --pid-file=/run/teleport.pid --insecure

After saving the unit file, you will need to reload the daemon for your changes to take effect:

$ sudo systemctl daemon-reload
$ sudo systemctl restart teleport.service

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