diff --git a/docs/config.json b/docs/config.json index 98360e017d2b3..75607587f7df2 100644 --- a/docs/config.json +++ b/docs/config.json @@ -389,6 +389,10 @@ { "title": "Run Teleport as a Daemon", "slug": "/management/admin/daemon/" + }, + { + "title": "Run Teleport with Self-Signed Certificates", + "slug": "/management/admin/self-signed-certs/" } ] }, @@ -803,10 +807,10 @@ "title": "Access Controls", "slug": "/desktop-access/rbac/" }, - { - "title": "Directory Sharing", - "slug": "/desktop-access/directory-sharing/" - }, + { + "title": "Directory Sharing", + "slug": "/desktop-access/directory-sharing/" + }, { "title": "Reference", "slug": "/desktop-access/reference/", diff --git a/docs/pages/application-access/guides/connecting-apps.mdx b/docs/pages/application-access/guides/connecting-apps.mdx index f0a4146cf5237..29db0f467ffe5 100644 --- a/docs/pages/application-access/guides/connecting-apps.mdx +++ b/docs/pages/application-access/guides/connecting-apps.mdx @@ -65,28 +65,7 @@ In our example: - `teleport.example.com` will host the Access Plane. - `*.teleport.example.com` will host all of the applications e.g. `grafana.teleport.example.com`. -You can either configure Teleport to obtain a TLS certificate via Let's Encrypt or use an existing certificate and private key (e.g. using [certbot](https://certbot.eff.org/)). - - -(!docs/pages/includes/acme.mdx!) - - -If you have obtained certificate/key pairs for your domain they can be provided directly -to the proxy service: - -```yaml -proxy_service: - enabled: "yes" - web_listen_addr: "0.0.0.0:443" - public_addr: "teleport.example.com:443" - https_keypairs: - - key_file: "/etc/letsencrypt/live/teleport.example.com/privkey.pem" - cert_file: "/etc/letsencrypt/live/teleport.example.com/fullchain.pem" - - key_file: "/etc/letsencrypt/live/*.teleport.example.com/privkey.pem" - cert_file: "/etc/letsencrypt/live/*.teleport.example.com/fullchain.pem" -``` - - +(!docs/pages/includes/tls-certificate-setup.mdx!) ### Create a user diff --git a/docs/pages/deploy-a-cluster/open-source.mdx b/docs/pages/deploy-a-cluster/open-source.mdx index 21e2ecb371576..ef62b711686be 100644 --- a/docs/pages/deploy-a-cluster/open-source.mdx +++ b/docs/pages/deploy-a-cluster/open-source.mdx @@ -110,34 +110,7 @@ Take a look at the [Installation Guide](../installation.mdx) for more options. Generate a configuration file for Teleport using the `teleport configure` command. This command requires information about a TLS certificate and private key. -If you are running Teleport on the internet, we recommend using Let's Encrypt to -receive your key and certificate automatically. For private networks or custom -deployments, use your own private key and certificate. - - - - (!docs/pages/includes/acme.mdx!) - - - - - On your Teleport host, place a valid private key and a certificate chain in `/var/lib/teleport/privkey.pem` - and `/var/lib/teleport/fullchain.pem` respectively. - - The leaf certificate must have a subject that corresponds to the domain of your Teleport host, e.g., `*.teleport.example.com`. - - Configure Teleport, changing the values of the `--cluster-name` and `--public-addr` flags to match the domain name of your Teleport host. - - ```code - $ sudo teleport configure -o file \ - --cluster-name=tele.example.com \ - --public-addr=tele.example.com:443 \ - --cert-file=/var/lib/teleport/fullchain.pem \ - --key-file=/var/lib/teleport/privkey.pem - ``` - - - +(!docs/pages/includes/tls-certificate-setup.mdx!) Next, configure Teleport to provide secure access to your web service. Edit your Teleport configuration file (`/etc/teleport.yaml`) to include the following, diff --git a/docs/pages/deploy-a-cluster/teleport-enterprise/getting-started.mdx b/docs/pages/deploy-a-cluster/teleport-enterprise/getting-started.mdx index 6c917048d84da..6798ddc7bf921 100644 --- a/docs/pages/deploy-a-cluster/teleport-enterprise/getting-started.mdx +++ b/docs/pages/deploy-a-cluster/teleport-enterprise/getting-started.mdx @@ -144,30 +144,7 @@ If you are exposing your Teleport host to the internet, we recommend using Let's Encrypt to receive your key and certificate automatically. For private networks or custom deployments, use your own private key and certificate. - - - (!docs/pages/includes/acme.mdx!) - - - - - On your Teleport host, place a valid private key and a certificate chain in `/var/lib/teleport/privkey.pem` - and `/var/lib/teleport/fullchain.pem` respectively. - - The leaf certificate must have a subject that corresponds to the domain of your Teleport host, e.g., `*.teleport.example.com`. - - Configure Teleport, changing the values of the `--cluster-name` and `--public-addr` flags to match the domain name of your Teleport host. - - ```code - $ sudo teleport configure -o file \ - --cluster-name=tele.example.com \ - --public-addr=tele.example.com:443 \ - --cert-file=/var/lib/teleport/fullchain.pem \ - --key-file=/var/lib/teleport/privkey.pem - ``` - - - +(!docs/pages/includes/tls-certificate-setup.mdx!) Next, configure Teleport to provide secure access to your web service. Edit your Teleport configuration file (`/etc/teleport.yaml`) to include the following, diff --git a/docs/pages/includes/tls-certificate-setup.mdx b/docs/pages/includes/tls-certificate-setup.mdx new file mode 100644 index 0000000000000..4617ab5f396e4 --- /dev/null +++ b/docs/pages/includes/tls-certificate-setup.mdx @@ -0,0 +1,59 @@ +If you are running Teleport on the internet, we recommend using Let's Encrypt to +receive your key and certificate automatically. For private networks or custom +deployments, use your own private key and certificate. + + + + Let's Encrypt verifies that you control the domain name of your Teleport cluster + by communicating with the HTTPS server listening on port 443 of your Teleport + Proxy Service. + + You can configure the Teleport Proxy Service to complete the Let's Encrypt + verification process when it starts up. + + On the host where you will start the Teleport Auth Service and Proxy Service, + run the following `teleport configure` command, where `tele.example.com` is the + domain name of your Teleport cluster and `user@example.com` is an email address + used for notifications (you can use any domain): + + ```code + $ DOMAIN=tele.example.com + $ EMAIL=user@example.com + $ teleport configure --acme --acme-email=${EMAIL?} --cluster-name=${DOMAIN?} | \ + sudo tee /etc/teleport.yaml > /dev/null + ``` + + The `--acme`, `--acme-email`, and `--cluster-name` flags will add the following + settings to your Teleport configuration file: + + ```yaml + proxy_service: + enabled: "yes" + web_listen_addr: 0.0.0.0:443 + public_addr: tele.example.com:443 + acme: + enabled: "yes" + email: user@example.com + ``` + + Port 443 on your Teleport Proxy Service host must allow traffic from all sources. + + + + On your Teleport host, place a valid private key and a certificate chain in `/var/lib/teleport/privkey.pem` + and `/var/lib/teleport/fullchain.pem` respectively. + + The leaf certificate must have a subject that corresponds to the domain of your Teleport host, e.g., `*.teleport.example.com`. + + Configure Teleport, changing the values of the `--cluster-name` and `--public-addr` flags to match the domain name of your Teleport host. + + ```code + $ sudo teleport configure -o file \ + --cluster-name=tele.example.com \ + --public-addr=tele.example.com:443 \ + --cert-file=/var/lib/teleport/fullchain.pem \ + --key-file=/var/lib/teleport/privkey.pem + ``` + + + diff --git a/docs/pages/management/admin.mdx b/docs/pages/management/admin.mdx index 583f9b6c0e1b8..718459b9dbb77 100644 --- a/docs/pages/management/admin.mdx +++ b/docs/pages/management/admin.mdx @@ -16,6 +16,8 @@ cluster maintenance tasks. - [Teleport Daemon](./admin/daemon.mdx): Set up Teleport as a daemon on Linux with systemd. - [Upgrade the Teleport Binary](./admin/upgrading-the-teleport-binary.mdx): Upgrade the `teleport` binary without losing connections. +- [Run Teleport with Self-Signed Certificates](./admin/self-signed-certs.mdx): Set up Teleport in a local +environment without configuring TLS certificates. ## Manage users and resources diff --git a/docs/pages/management/admin/self-signed-certs.mdx b/docs/pages/management/admin/self-signed-certs.mdx new file mode 100644 index 0000000000000..d04e447a0180b --- /dev/null +++ b/docs/pages/management/admin/self-signed-certs.mdx @@ -0,0 +1,224 @@ +--- +title: Running Teleport with Self-Signed Certificates +description: How run Teleport using self-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 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 one of our + [Getting Started](/docs/getting-started) guides (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: + + ```yaml + proxy_service: + enabled: "yes" + # TLS certificate for the HTTPS connection. + https_keypairs: [] + # Get an automatic certificate from letsencrypt.org using ACME. + acme: {} + ``` + +- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=). + + ```code + $ tctl version + # Teleport v(=teleport.version=) go(=teleport.golang=) + + $ tsh version + # Teleport v(=teleport.version=) go(=teleport.golang=) + ``` + + See [Installation](/docs/installation.mdx) for details. + + + + +- A running Teleport cluster. For details on how to set this up, see our Enterprise + [Getting Started](/docs/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: + + ```yaml + proxy_service: + enabled: "yes" + # TLS certificate for the HTTPS connection. + https_keypairs: [] + # Get an automatic certificate from letsencrypt.org using ACME. + acme: {} + ``` + +- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=), + which you can download by visiting the + [customer portal](https://dashboard.gravitational.com/web/login). + + ```code + $ tctl version + # Teleport v(=teleport.version=) go(=teleport.golang=) + + $ tsh version + # Teleport v(=teleport.version=) go(=teleport.golang=) + ``` + + + + +## How to use self-signed certs with Teleport binaries + +### `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: + ```sh + $ teleport start -c /etc/teleport.yaml --insecure + $ teleport app start -c /etc/teleport.yaml --insecure + $ 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](../../reference/helm-reference/teleport-cluster.mdx#extraargs) + to include the extra argument: `--insecure`: + + + ```yaml + extraArgs: + - "--insecure" + ``` + + + ```code + $ --set "extraArgs={--insecure}" + ``` + + + + + If you are using the `teleport-kube-agent` chart, set the + [insecureSkipProxyTLSVerify + ](../../reference/helm-reference/teleport-kube-agent.mdx#insecureskipproxytlsverify) + flag to `true`: + + + ```yaml + insecureSkipProxyTLSVerify: true + ``` + + + ```code + $ --set insecureSkipProxyTLSVerify=true + ``` + + + + + + Locate the `systemd` unit file for Teleport (called teleport.service) by running the following command: + ```sh + $ 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: + + ```code + ● teleport.service - Teleport SSH 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: + ```text + 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: + ```sh + $ 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` + +## Further reading + +- [Configuring Teleport TLS Certs](../../deploy-a-cluster/open-source.mdx#configure-teleport) +- [Run Teleport as a systemd Daemon](./daemon.mdx) +- [Teleport Proxy Service](../../architecture/proxy.mdx) +- [Teleport Authentication](../../architecture/authentication.mdx)