# 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 **Open Source** - A running Teleport cluster. For details on how to set this up, see our [Getting Started](https://goteleport.com/docs/get-started/deploy-community.md) 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: true # TLS certificate for the HTTPS connection. https_keypairs: [] # Get an automatic certificate from letsencrypt.org using ACME. acme: {} ``` **Enterprise** - A running Teleport cluster. For details on how to set this up, see our Enterprise [Getting Started](https://goteleport.com/docs/zero-trust-access/deploy-a-cluster.md) 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: true # TLS certificate for the HTTPS connection. https_keypairs: [] # Get an automatic certificate from letsencrypt.org using ACME. acme: {} ``` * The `tctl` and `tsh` client tools: **Mac** Download the signed macOS .pkg installer for Teleport, which includes `tctl` and `tsh`. In Finder double-click the `pkg` file to begin installation: ``` $ curl -O https://cdn.teleport.dev/teleport-19.0.0-dev.pkg ``` --- DANGER Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security. --- **Windows - Powershell** ``` $ curl.exe -O https://cdn.teleport.dev/teleport-v19.0.0-dev-windows-amd64-bin.zip Unzip the archive and move tsh.exe and tctl.exe to your %PATH% NOTE: Do not place tsh.exe and tctl.exe in the System32 directory, as this can cause issues when using WinSCP. Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\) instead. ``` **Linux** All of the Teleport binaries in Linux installations include tctl and tsh. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see the [installation page](https://goteleport.com/docs/installation.md). ``` $ curl -O https://cdn.teleport.dev/teleport-v19.0.0-dev-linux-amd64-bin.tar.gz $ tar -xzf teleport-v19.0.0-dev-linux-amd64-bin.tar.gz $ cd teleport $ sudo ./install Teleport binaries have been copied to /usr/local/bin ``` Make sure `tctl` and `tsh` are at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at `/v1/webapi/ping` and use a JSON query tool to obtain your cluster version: ``` $ curl https://example.teleport.sh/v1/webapi/ping | jq -r '.server_version' 19.0.0-dev ``` ## 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: **Using the CLI** 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`. **Helm chart** If you are using the `teleport-cluster` Helm chart, set [extraArgs](https://goteleport.com/docs/reference/helm-reference/teleport-cluster.md) to include the extra argument: `--insecure`. Here is an example of the field within a values file: ``` extraArgs: - "--insecure" ``` When using the `--set` flag, use the following syntax: ``` --set "extraArgs={--insecure}" ``` If you are using the `teleport-kube-agent` chart, set the [insecureSkipProxyTLSVerify](https://goteleport.com/docs/reference/helm-reference/teleport-kube-agent.md) flag to `true`. In a values file, this would appear as follows: ``` insecureSkipProxyTLSVerify: true ``` When using the `--set` flag, use the following syntax: ``` --set insecureSkipProxyTLSVerify=true ``` **systemd** 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](https://goteleport.com/docs/connect-your-client/teleport-clients/teleport-connect.md). ## Further reading - [Configuring Teleport TLS Certs](https://goteleport.com/docs/get-started/deploy-community.md) - [Run Teleport as a systemd Daemon](https://goteleport.com/docs/reference/cli/teleport.md#teleport-install-systemd) - [Teleport Proxy Service](https://goteleport.com/docs/reference/architecture/proxy.md) - [Teleport Authentication](https://goteleport.com/docs/reference/architecture/authentication.md)